# Getting Started

## Installation

UFP requires Python 3.10 or newer.

```sh
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:

```sh
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:

```python
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:

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

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