UFP Documentation

UFP is a Torch-first library for building, fitting, and using interatomic potentials from composable energy terms. It keeps ASE and simulation-engine objects at the boundary, then evaluates models on normalized torch tensors.

The documentation is organized around the main decisions a user or developer needs to make:

• Getting Started
  • Installation
  • A Minimal ASE Model
  • Building Documentation
• Core Concepts
  • Energy, Forces, and Differentiation
  • The UFPInput Layout
  • Neighbor Lists
  • Additive Model Terms
  • Uniform Spline Support
• Model Terms
  • One-Body Terms
  • Harmonic Pair Terms
  • Two-Body Spline Terms
  • Charge and Spin Terms
  • Three-Body Spline Terms
  • Triplet 2D and Four-Body Terms
  • Repulsion and Alchemical Coefficients
• Adding Model Terms
  • Start With The Contract
  • Input Requirements
  • Category Layout
  • Parameter Blocks
  • Cache Descriptors
  • Schema Codecs
  • Optimizer Groups
  • Tests To Add
  • Implementation Checklist
• Fitting Workflows
  • Direct Least Squares
  • Regularization
  • Selective Coefficient Fitting
  • Coefficient Interchange
  • Offline Projection
  • Analytic Priors and Residualized Corrections
  • Optimizer-Time Freezing
  • Workflow Stages and Checkpoints
  • Caching
  • Gradient Training
• Predictive Uncertainty
  • Linear Coefficient Posterior
  • Sparse Prediction Rows
  • Alchemical Models
  • Aleatoric Noise
  • Prediction Bundles
  • Variance Scaling
  • Calibration
  • Minimal Alchemical Example
  • Li-P-S Alchemical Example
  • Tungsten Example
• Coefficient Workflows
  • Selection
  • Interchange
  • Projection
  • Freezing
• Workflow Management
  • Stages
  • Checkpoints
  • Residualization
  • Prepared Geometry
  • Caching
  • Regularization Tuning
• Runtime Backends and Integrations
  • Neighbor-List Backends
  • Native Three-Body Kernels
  • ASE
  • Metatomic
  • Torch-Sim
• Examples
  • Basics
  • Tungsten
  • Uncertainty
  • Water
  • Li-P-S
  • Cache Defaults
  • Notebook Generation
• Architecture Ownership
  • Package Boundaries
  • Dependency Direction
  • Public And Internal APIs
  • Hot Paths
  • Least-Squares Setup Split
  • Intentional Duplication
  • Known Technical Debt
• Benchmark Ownership
  • Quick Smoke Checks
  • Area To Benchmark Map
  • Benchmark Commands
  • Acceptance Rules
• API Reference
  • API Stability Labels
  • Public Surface Summary
  • Top-Level Package
  • Cache
  • Core
  • Terms
  • Neighbor Lists
  • Splines
  • Deprecated Compatibility APIs
  • Least Squares
  • Uncertainty
  • Coefficients
  • Projection
  • Training
  • Workflows
  • Adapters
  • Analysis
  • Benchmarks
• Development
  • First Day Setup
  • Validation Commands
  • Type-Check Baseline
  • Generated Artifacts
  • Repository Audits
  • Speed Gates
  • Documentation Style

What UFP Provides

• A shared UFPInput representation for atoms, cells, periodic flags, and neighbor lists.

• Additive UFPModel objects built from one-body, pair, spline, three-body, four-body, repulsion, and alchemical terms.

• Two fitting paths: direct linear least squares for coefficient-linear models and PyTorch training for differentiable models.

• ASE calculator support, metatomic wrappers, torch-sim wrappers, and optional native C++/CUDA acceleration for selected three-body paths.

Units

UFP does not impose a unit registry. Most examples and ASE workflows use angstroms for length and electron volts for energy. Forces then have units of energy per length, typically eV/angstrom. Keep units consistent across input structures, fitted coefficients, and labels.