Core Concepts

Energy, Forces, and Differentiation

UFP models represent an interatomic potential as a total energy

\[ E(\mathbf R, \mathbf Z, \mathbf C), \]

where \(\mathbf R\) are atomic positions, \(\mathbf Z\) are atomic numbers, and \(\mathbf C\) contains cell and periodic-boundary information. Forces follow the standard sign convention

\[ \mathbf F_i = -\frac{\partial E}{\partial \mathbf R_i}. \]

Some terms compute analytic forces directly. If a model returns energy but not forces, UFPotential.compute(..., derive_forces=True) can derive forces with PyTorch autograd, provided the energy path is differentiable with respect to positions.

The UFPInput Layout

UFPInput flattens one or more structures into one tensor bundle:

  • positions has shape (n_atoms, 3).

  • cell has shape (n_systems, 3, 3).

  • pbc has shape (n_systems, 3).

  • atomic_numbers has shape (n_atoms,).

  • system_index maps each atom back to its system.

  • neighbor_list, when present, uses the same concatenated atom indexing.

  • state, when present, is a UFPInputState containing optional atomwise and systemwise charge or spin fields.

This layout keeps model terms independent of ASE, metatomic, and torch-sim objects. Engine adapters are responsible for conversion at the boundary.

UFPInputState currently supports atomic_charges, atomic_spin_moments, system_charges, and system_spin_moments. Missing fields remain None, so legacy geometry-only models do not need to provide state. State-aware terms declare required fields with TermInputRequirements and raise a clear error when a caller omits them.

Neighbor Lists

Pair and higher-body terms operate on a normalized NeighborListData object. Its pairs array stores atom-index pairs, and shifts stores periodic cell shifts. Pair vectors are interpreted as the displacement from the first atom to the second atom, including the periodic image shift.

Backends currently include:

  • ASE, always available through ase.neighborlist;

  • vesin, when the optional dependency is installed;

  • metatomic-provided lists, when running through the metatomic adapter.

When backend="auto", UFP prefers vesin if it can be imported and otherwise falls back to ASE.

Additive Model Terms

UFPModel evaluates each term and sums compatible outputs. A term may provide energy, forces, stress, per-atom energy, and named feature tensors. Energy-like outputs are per system; force-like outputs are per atom in the concatenated atom axis.

The additive structure is important for fitting. Many spline terms are linear in their coefficients, so a fixed geometry can be turned into a design matrix for least-squares fitting.

Uniform Spline Support

Spline terms use uniformly spaced coefficient grids. A one-dimensional spline term evaluates a local stencil around a distance \(r\):

\[ E(r) = \sum_k c_k B_k(r), \]

where only a small number of basis functions \(B_k\) are nonzero for each distance. Quadratic, cubic, and quartic spline families are supported. The same stencil machinery is reused by the forward model and by least-squares assembly, which keeps training and direct fitting consistent.