# API Reference

The API reference is generated from package docstrings with Sphinx autodoc and
Napoleon.

## API Stability Labels

UFP documents public imports with stability labels so users can distinguish
ordinary model-building APIs from extension hooks and diagnostic tools.

| Label | Meaning |
| --- | --- |
| Stable user API | Normal user imports intended to remain source-compatible across minor releases. |
| Extension API | Supported hooks for downstream/custom terms and fitting integrations. |
| Expert diagnostics | Importable tools for debugging, profiling, benchmarking, or inspecting internals; they may follow implementation constraints more closely than user APIs. |
| Experimental workflow API | High-level orchestration helpers that are useful in examples and studies but may change faster than model terms and core tensors. |
| Optional integration API | Public wrappers for optional external engines; availability can depend on optional dependencies. |
| Internal/private | Underscore-prefixed modules and implementation helpers unless this page explicitly documents a narrower contract. |

## Public Surface Summary

| Namespace | Status | Notes |
| --- | --- | --- |
| `ufp` | Stable user API | Small lazy-import surface for common model assembly and cache naming. |
| `ufp.cache` | Stable user API | Settings-addressed cache names and identity summaries. |
| `ufp.core` | Stable low-level user API | Tensor input, output, potential, and state primitives. |
| `ufp.neighbors` | Stable user API | Neighbor-list construction and normalized neighbor containers. |
| `ufp.terms` | Stable user API | Built-in term classes and model container. |
| `ufp.terms.contracts` | Extension API | Supported imports for downstream term implementations. |
| `ufp.terms.threebody` runtime helpers | Expert diagnostics | Bucket and evaluator helpers are importable for tests, benchmarks, and debugging. |
| `ufp.splines` | Extension API | Spline representations, stencils, derivatives, and fitting helpers used by terms and fitting code. |
| `ufp.leastsquares` | Stable user and expert fitting API | Solvers, datasets, layouts, cache IO, checkpoints, and diagnostics for direct fitting. |
| `ufp.training` | Stable user API | ASE-native datasets, batches, metrics, and PyTorch training loops. |
| `ufp.coefficients` | Stable user API | Coefficient selectors and interchange helpers. |
| `ufp.projection` | Stable user API | Offline coefficient projection helpers and diagnostics. |
| `ufp.workflows` | Experimental workflow API | Example-oriented orchestration for data, models, fitting, prediction, and runtime choices. |
| `ufp.adapters` | Optional integration API | ASE, metatomic, and torch-sim wrappers. |
| `ufp.analysis` | Stable user diagnostics API | Dataset, prediction, metric, and plotting helpers. |
| `ufp.benchmarks` | Expert benchmark API | Installed benchmark entry points and result containers for speed gates and performance comparisons. |

## Top-Level Package

**Status:** Stable user API.

```{eval-rst}
.. automodule:: ufp
```

## Cache

**Status:** Stable user API.

`ufp.cache` is the public namespace for settings-addressed cache identities.
Top-level `ufp` lazily exports the common cache helpers for convenience.
`ufp.workflows.cache` is retained only as a compatibility alias for older
workflow scripts.

```{eval-rst}
.. automodule:: ufp.cache
   :members:
```

## Core

**Status:** Stable low-level user API.

```{eval-rst}
.. automodule:: ufp.core
```

```{eval-rst}
.. automodule:: ufp.core.input
   :members:
```

```{eval-rst}
.. automodule:: ufp.core.output
   :members:
```

```{eval-rst}
.. automodule:: ufp.core.potential
   :members:
```

## Terms

**Status:** Stable user API for built-in terms and `UFPModel`; extension API
for `ufp.terms.contracts`; expert diagnostics for documented three-body bucket,
feature-cache, and evaluator helpers.

```{eval-rst}
.. automodule:: ufp.terms
```

```{eval-rst}
.. automodule:: ufp.terms.model
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.contracts
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.cutoffs
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.analytic
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.onebody
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.state
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.twobody
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.threebody
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.triplet2d
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.fourbody
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.zbl
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.powerlaw
   :members:
```

```{eval-rst}
.. automodule:: ufp.terms.alchemical
   :members:
```

## Neighbor Lists

**Status:** Stable user API.

```{eval-rst}
.. automodule:: ufp.neighbors
   :members:
```

## Splines

**Status:** Extension API.

`ufp.splines` exports low-level support helpers for expert callers that need to
coordinate coefficient support with fitting, projection, uncertainty, or custom
term code. `uniform_support_parameters`, `spline_support_mask_1d`,
`spline_support_mask_3d`, and `all_supported_uniform_stencil_3d` are public
extension APIs. They are intentionally direct exports rather than facade calls
so hot paths can bind the exact helper they need before entering tensor loops.
`supported_uniform_stencil_3d` remains available for compatibility, but new
performance-sensitive code should filter with `spline_support_mask_3d` and call
`all_supported_uniform_stencil_3d` on already-supported coordinates.

```{eval-rst}
.. automodule:: ufp.splines
```

```{eval-rst}
.. automodule:: ufp.splines.representation
   :members:
```

```{eval-rst}
.. automodule:: ufp.splines.derivatives
   :members:
```

```{eval-rst}
.. automodule:: ufp.splines.fitting
   :members:
```

## Deprecated Compatibility APIs

| API | Status | Replacement guidance |
| --- | --- | --- |
| `TwoBodySplineShapePenalty` | Deprecated compatibility behavior. It remains importable so older training and least-squares scripts keep running. | Prefer term-family ridge values, `RegularizationSearchConfig`, coefficient selection, explicit priors, validation data checks, or `TwoBodyCriticalWallPenalty` for physical slope/curvature wall regularization during Torch training. |
| `supported_uniform_stencil_3d` | Deprecated helper that combines support filtering and stencil construction. | Filter coordinates outside performance-sensitive loops, then call `ufp.splines.representation.all_supported_uniform_stencil_3d` on already-supported coordinates. |

## Least Squares

**Status:** Stable user and expert fitting API. Public imports cover fitting
datasets, parameter layouts, solvers, regularization, cache IO, checkpoints,
and diagnostic problem containers. Underscore helpers used by assembly and
block-matrix internals are private even when they remain directly importable by
UFP internals.

```{eval-rst}
.. automodule:: ufp.leastsquares
```

```{eval-rst}
.. automodule:: ufp.leastsquares.dataset
   :members:
```

```{eval-rst}
.. automodule:: ufp.leastsquares.linear
   :members:
```

```{eval-rst}
.. automodule:: ufp.leastsquares.regularization
   :members:
```

```{eval-rst}
.. automodule:: ufp.leastsquares.hybrid
   :members:
```

```{eval-rst}
.. automodule:: ufp.leastsquares.alchemical
   :members:
```

## Uncertainty

**Status:** Stable user diagnostics API.

```{eval-rst}
.. automodule:: ufp.uncertainty
   :members:
```

## Coefficients

**Status:** Stable user API.

```{eval-rst}
.. automodule:: ufp.coefficients
```

```{eval-rst}
.. automodule:: ufp.coefficients.interchange
   :members:
```

## Projection

**Status:** Stable user API.

```{eval-rst}
.. automodule:: ufp.projection
```

```{eval-rst}
.. automodule:: ufp.projection.radial
   :members:
```

```{eval-rst}
.. automodule:: ufp.projection.spline
   :members:
```

```{eval-rst}
.. automodule:: ufp.projection.diagnostics
   :members:
```

## Training

**Status:** Stable user API.

```{eval-rst}
.. automodule:: ufp.training
```

```{eval-rst}
.. automodule:: ufp.training.dataset
   :members:
```

```{eval-rst}
.. automodule:: ufp.training.batch
   :members:
```

```{eval-rst}
.. automodule:: ufp.training.engine
   :members:
```

```{eval-rst}
.. automodule:: ufp.training.force_selection
   :members:
```

```{eval-rst}
.. automodule:: ufp.training.freezing
   :members:
```

## Workflows

**Status:** Experimental workflow API.

```{eval-rst}
.. automodule:: ufp.workflows
```

```{eval-rst}
.. automodule:: ufp.workflows.data
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.models
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.onebody
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.predictions
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.cache
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.prior
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.regularization
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.threebody
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.training
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.stages
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.checkpoints
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.residuals
   :members:
```

```{eval-rst}
.. automodule:: ufp.workflows.prepared
   :members:
```

## Adapters

**Status:** Optional integration API.

```{eval-rst}
.. automodule:: ufp.adapters
```

```{eval-rst}
.. automodule:: ufp.adapters.ase
   :members:
```

```{eval-rst}
.. automodule:: ufp.adapters.metatomic
   :members:
```

```{eval-rst}
.. automodule:: ufp.adapters.torchsim
   :members:
```

```{eval-rst}
.. automodule:: ufp.adapters.metatomic_export
   :members:
```

## Analysis

**Status:** Stable user diagnostics API.

```{eval-rst}
.. automodule:: ufp.analysis
```

```{eval-rst}
.. automodule:: ufp.analysis.inputs
   :members:
```

```{eval-rst}
.. automodule:: ufp.analysis.outputs
   :members:
```

```{eval-rst}
.. automodule:: ufp.analysis.plotting
   :members:
```

## Benchmarks

**Status:** Expert benchmark API. These imports are intended for speed gates,
benchmark automation, and performance investigations. Benchmark workloads,
reported fields, and scenario names may evolve as UFP's protected hot paths
change.

```{eval-rst}
.. automodule:: ufp.benchmarks
   :members:
```