# Examples

The `examples/` directory contains runnable scripts that also serve as notebook
sources. Example scripts use module-level constants as notebook-facing
parameters and `argparse` parsers when run as scripts.

## Basics

`examples/01-basics` introduces package structure, neighbor lists, inputs,
spline terms, and fitting workflows.

## Tungsten

`examples/02-tungsten` contains W-14 examples for pair and UF2+3 models. These
are useful for studying elemental systems with a single atomic type and a
three-body correction surface. The constrained-wall uncertainty example loads
the trained UF2+3 checkpoint from the corresponding training demo and fits a
coefficient posterior for a linearized proxy model. It writes reusable
prediction bundles under `uncertainty_models/`; its `example_cache/` usage is only
for optional least-squares assembly caching during posterior fitting. The script
prints follow-on `make_predictions.py` and `calibrate_uncertainty.py` commands.

## Uncertainty

`examples/calibrate_uncertainty.py` computes energy calibration diagnostics from
uncertainty-enabled prediction `.npz` files and can include force diagnostics
when force variance arrays are present. It can also fit and save a post-hoc
energy variance scale back to a bundle. `examples/inspect_uncertainty_bundle.py`
prints validation, posterior, aleatoric, and calibration state for saved
bundles. `examples/alchemical_uncertainty_demo.py` is a minimal fixed-weight
alchemical posterior example that saves and reloads an uncertainty bundle
without requiring an external dataset.

## Water

`examples/03-watermonomer` and `examples/04-waterdimers` cover molecular
systems with hydrogen and oxygen channels. They demonstrate selected active
three-body channels and density-style prediction plots.

## Li-P-S

`examples/05-lips` contains larger Li-P-S workflows, including alchemical
least-squares and torch training scripts. `alchemical_uncertainty.py` loads the
alchemical least-squares checkpoint, fits a fixed-weight uncertainty posterior,
saves a bundle under `uncertainty_models/`, and prints the matching generic
prediction and calibration commands.

## Cache Defaults

Cache-using least-squares and disk-feature training examples use strict cache
reads by default. Cache-enabled examples under
`examples/02-tungsten`, `examples/03-watermonomer`,
`examples/04-waterdimers`, and `examples/05-lips` need a first run with
`--refresh-cache`.

Typical first run:

```sh
python examples/03-watermonomer/uf23_potential_demo.py --refresh-cache
```

Subsequent matching run:

```sh
python examples/03-watermonomer/uf23_potential_demo.py
```

Three-body training examples use disk feature caching by default. Turn that off
when you want a no-disk-cache training run:

```sh
python examples/02-tungsten/uf23_potential_training_demo.py --feature-cache-storage none
python examples/03-watermonomer/uf23_potential_training_demo.py --feature-cache-storage none
python examples/04-waterdimers/uf23_potential_training_demo.py --feature-cache-storage none
```

Pair-only training examples default to `--feature-cache-storage none`, so they
do not need `--refresh-cache` unless you explicitly enable disk feature caching:

```sh
python examples/02-tungsten/pair_potential_training_demo.py
python examples/02-tungsten/pair_potential_training_demo.py --feature-cache-storage disk --refresh-cache
```

Incompatible batch size, dtype, split contents/order, backend/input geometry,
spline settings, and training per-atom-energy cache mode fail immediately
instead of rebuilding. When the cache directory parameter is left unset,
examples derive a settings-addressed folder under `example_cache/` with the
public `ufp.suggest_cache_directory()` helper. Each written cache includes a
`cache_settings.json` file that summarizes the cache-invalidating settings
behind the hashed cache folder name.

## Notebook Generation

`examples/generate_notebooks.py` converts runnable scripts into notebook
counterparts. Keep example scripts runnable first; generated notebooks should
remain a presentation format rather than the source of truth.