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:

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

Subsequent matching run:

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:

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:

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.