Getting Started

Installation

UFP requires Python 3.10 or newer.

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Optional extras install integrations, documentation tools, and developer tools:

python -m pip install -e ".[vesin]"
python -m pip install -e ".[metatomic]"
python -m pip install -e ".[torchsim]"
python -m pip install -e ".[docs]"
python -m pip install -e ".[dev]"

Install a specific PyTorch wheel first if you need CPU-only wheels or a particular CUDA build.

A Minimal ASE Model

The top-level package exposes the common pieces needed to build and run a model:

import ase

from ufp import HarmonicPairTerm, UFPASECalculator, UFPModel


atoms = ase.Atoms(
    symbols=["H", "H"],
    positions=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.75]],
    cell=[[8.0, 0.0, 0.0], [0.0, 8.0, 0.0], [0.0, 0.0, 8.0]],
    pbc=False,
)

model = UFPModel(
    pair_terms=[
        HarmonicPairTerm(
            cutoff=1.5,
            spring_constant=2.0,
            equilibrium_distance=1.0,
            atomic_types=[1],
        )
    ],
    atomic_types=[1],
)

atoms.calc = UFPASECalculator(model)
energy = atoms.get_potential_energy()
forces = atoms.get_forces()

UFPASECalculator builds the UFPInput representation, runs the wrapped model, and converts UFPOutput back into ASE calculator results.

Building Documentation

Install the docs extra and run Sphinx:

python -m pip install -e ".[docs]"
tox -e docs

The generated HTML is written to docs/_build/html.