# 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.