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.