# Model Terms

UFP terms are small `torch.nn.Module` objects that implement a piece of an
interatomic potential. Terms should be additive, explicit about their supported
atomic types, and conservative about hidden state.

## One-Body Terms

`ElementOneBodyTerm` assigns a reference energy to each covered atomic number:

$$
E_\mathrm{onebody} = \sum_i \epsilon_{Z_i}.
$$

This is useful for fitting formation-like residuals. A one-body term has zero
force because its energy depends only on composition.

## Harmonic Pair Terms

`HarmonicPairTerm` evaluates a uniform harmonic interaction over covered pairs:

$$
E_{ij} = \frac{1}{2} k (r_{ij} - r_0)^2.
$$

`ElementPairHarmonicTerm` generalizes this to element-pair-specific spring
constants and equilibrium distances. Symmetric pair terms canonicalize `(a, b)`
and `(b, a)` into the same category.

## Two-Body Spline Terms

In UFP terminology, **two-body** names the physics family, while a **pair
channel** names one `(Z1, Z2)` coefficient row or category. `SplinePairTerm`
represents one explicit pair channel with a one-dimensional uniform spline over
pair distance. `SplineTwoBodyTerm` is the categorized two-body family term: it
stores coefficients for all pair channels implied by `atomic_types`, optionally
narrowed with `active_pairs`.

Fitting labels follow that distinction. `SplinePairTerm` exposes a single
`pair[(Z1, Z2)]` parameter block with internal kind and assembler `"pair"`.
`SplineTwoBodyTerm` exposes one `twobody[(...)]` parameter block with internal
kind and assembler `"twobody"`. Both use regularization group `"twobody"` so
two-body ridge and shape penalties apply consistently.

`RepulsiveSplineTwoBodyTerm` is a categorized cubic two-body term for optimizer
training when low-distance data are sparse. It generates the low-distance cubic
coefficients from positive curvature coefficients, a positive transition force,
and a trainable transition value, then evaluates the generated row as an
ordinary cubic spline. It does not expose a direct least-squares parameter block
because the constrained wall parameters are nonlinear in the final coefficients.

`TwoBodyCriticalWallPenalty` is a soft Torch-training regularizer for ordinary
cubic spline pair terms. It uses a per-pair critical distance, usually the
shortest observed training distance, and penalizes positive radial slope at that
distance plus negative curvature on the inner interval. Unlike
`RepulsiveSplineTwoBodyTerm`, it does not hard-parameterize the coefficients and
does not provide a direct least-squares constraint solver.

For a pair channel, the energy contribution has the form

$$
E_{ij} = \sum_k c_k B_k(r_{ij}),
$$

and the force uses the derivative of the same spline basis:

$$
\mathbf F_j = -\frac{\partial E_{ij}}{\partial r_{ij}}
              \frac{\mathbf r_j - \mathbf r_i}{r_{ij}}.
$$

The implementation guards division by very small distances with `eps`.

## Charge and Spin Terms

Charge and collinear-spin terms use optional state carried by `UFPInputState`.
ASE inputs can provide atomwise `charges` or `initial_charges`, atomwise
`magmoms` or `initial_magmoms`, and system-level `charge` or `spin_moment`
metadata. Terms declare these requirements through `TermInputRequirements`, so
missing state fails before evaluation or least-squares assembly.

`ChargeSelfEnergyTerm` adds a local charge self energy

$$
E_\mathrm{charge} = \sum_i \chi_{Z_i} q_i
    + \frac{1}{2} \eta_{Z_i} q_i^2,
$$

where `q_i` is a fixed local charge. It exposes linear least-squares blocks for
the electronegativity coefficients `chi` and hardness coefficients `eta`, and
reports the atomwise diagnostic feature `charge_potential = dE / dq_i`.

`LocalChargeCoulombTerm` is a finite-cutoff softened Coulomb prior for fixed
local charges,

$$
E_{ij} = w k_e q_i q_j
        \frac{f_\mathrm{cut}(r_{ij})}{\sqrt{r_{ij}^2 + \delta^2}},
$$

with `k_e = 14.3996454784255 eV Angstrom / e^2`. It is a short-range screened
term only; it does not implement Ewald, PME, P3M, or any other true long-range
periodic electrostatics.

`ChargeScaledSplinePairTerm` fits a short-range spline correction multiplied by
`q_i q_j`:

$$
E_{ij} = w q_i q_j \sum_k C_{Z_i Z_j,k} B_k(r_{ij}).
$$

The coefficient block is linear for fixed charges and uses kind
`charge_twobody`.

`CollinearSpinLandauTerm` adds an onsite scalar-spin Landau energy

$$
E_\mathrm{spin} = \sum_i a_{Z_i} m_i^2 + b_{Z_i} m_i^4,
$$

and reports `spin_effective_field = -dE / dm_i`. `CollinearSpinExchangeTerm`
adds a pairwise scalar exchange spline

$$
E_{ij} = w m_i m_j \sum_k J_{Z_i Z_j,k} B_k(r_{ij}).
$$

These spin terms support fixed collinear scalar moments only. Non-collinear
spins, spin-orbit coupling, charge equilibration, spin relaxation, learned
state prediction, and density-like training targets are outside this first
state-aware term layer.

## Three-Body Spline Terms

`SplineThreeBodyTerm` is source-distinguished. For a source atom $i$ and two
neighbors $j$ and $k$, it evaluates a three-dimensional spline over

$$
x = r_{ij}, \qquad y = r_{ik}, \qquad z = r_{jk}.
$$

The coefficient tensor is indexed by triplet category
`(source, first_neighbor, second_neighbor)` and by the local spline stencil:

$$
E_{ijk} = \sum_{a,b,c} C_{abc}^{Z_i,Z_j,Z_k}
          B_a(x) B_b(y) B_c(z).
$$

The two neighbor categories are symmetric in category construction. For channels
where the two neighbor species are identical, UFP symmetrizes the coefficient
axes so swapping $j$ and $k$ does not change the energy.

Three-body terms require a full neighbor list so the source-centered neighbor
sets are available in both pair directions. Forces are assembled analytically
from the partial derivatives with respect to $x$, $y$, and $z$ using the chain
rule.

## Triplet 2D and Four-Body Terms

`SplineTriplet2DTerm` is a lower-dimensional three-body term over the two
center-neighbor distances $r_{ij}$ and $r_{ik}$. It omits the neighbor-neighbor
distance and is useful when angular or neighbor-neighbor resolution is not
needed.

`SplineFourBody6DTerm` is a Torch-only energy term over the six pair distances
in a source-neighbor triple. Forces can be obtained through autograd by using
model APIs with `derive_forces=True`.

## Repulsion and Alchemical Coefficients

`ZBLRepulsionTerm` provides a short-range repulsive interaction. It is meant to
be composed with learned terms when close-contact behavior needs an explicit
physical prior.

`AlchemicalCoefficients` lets multiple true element channels share a smaller set
of proxy coefficients through mixing weights. This is useful when many element
combinations are present but the desired model should share statistical strength
across related channels.