Pyramid

Python wrapped Ab initio Molecular Dynamics — a name drawn from the PYR-AIMD letters.

Pyramid brings first-principles engines, machine-learned interatomic potentials (MLIPs), solvers and molecular dynamics into one extensible Python framework. Reference calculations supply energies and forces; fast potentials propagate atomic motion; the framework coordinates when to evaluate, check and update them.

Its energetic force-error method connects force accuracy to the motion of the atoms. A local directional response predicts how force errors grow away from a reference configuration. Signed residual work measures their energetic effect along the trajectory. Together, these quantities guide reference calculations and provide a physical account of the forces used during a run.

Install

Python 3.12 or later. The core install needs only NumPy and ASE — no torch, no PySCF, no external programs. From a checkout:

pip install .            # user install
pip install -e '.[dev]'  # development: adds pytest and ruff

Or install a release wheel into a clean virtual environment (the wheel and sdist are attached to the GitHub Release of the same tag; the examples and the example plugins below come from that tag's source tree):

python -m venv ~/.venvs/pyramid && . ~/.venvs/pyramid/bin/activate
pip install pyraimd2-0.7.3-py3-none-any.whl

A first run with the built-in harmonic model — the analytic demo needs no backend installation and finishes in seconds:

pyramid init --template harmonic --output my_run
pyramid validate my_run/run.toml
pyramid run my_run/run.toml
pyramid inspect my_run/runs/harmonic-demo
pyramid resume my_run/runs/harmonic-demo --steps 5
pyramid export my_run/runs/harmonic-demo --force-source driving

Optional backends install separately and are only imported when selected:

pip install '.[pyscf]'   # molecular reference engine
pip install '.[mace]'    # MACE surrogate potentials

all installs both; builders adds optional structure-building tools. Quantum ESPRESSO additionally needs a pw.x executable and pseudopotentials installed outside Python.

The Python import is pyraimd2; the CLI is pyramid (alias pyraimd2). pyramid --version and pyramid --help work offline and download nothing.

Pick your task

Run a first adaptive MD in five minutes

examples/harmonic_adaptive/ is a complete, offline adaptive NVE run: builtin analytic reference and surrogate models drive a toy H2O molecule. It exercises anchoring, surrogate acceptance, independent checks, checkpoints, stop and resume — no external programs, no model downloads, finishes in seconds:

cd examples/harmonic_adaptive
pyramid validate run.toml
pyramid run run.toml
pyramid inspect runs/harmonic-demo
pyramid resume runs/harmonic-demo --steps 10
pyramid export runs/harmonic-demo --force-source reference --output reference.extxyz

pyramid init --template harmonic --output my_run writes the same pair of files as a starting point for your own configuration. The template's policy and verification numbers are demonstration values, not accuracy recommendations for any material. The full field reference is in docs/configuration.md.

A serial relax → NVT → NVE workflow, offline

examples/periodic_lj/ runs a 32-atom fcc Lennard-Jones cell through the three stages with only NumPy + ASE plus the example plugin. The NVT stage is adaptive (fixed model) and the NVE stage continues with the NVT boundary's complete momenta — never rethermalized:

pip install .                       # the core package
pip install examples/backends/pyraimd2_lj   # the example backend plugin
cd examples/periodic_lj
python run_recipe.py --output results/lj-recipe   # relax + NVT + NVE
python run_recipe.py --output results/lj-recipe   # continue/resume, idempotent
pyramid inspect results/lj-recipe/nvt
pyramid export results/lj-recipe/nve --force-source driving

For guarded online model updates under NVT (Python interface), examples/guarded_nvt.py runs offline on analytic potentials, with stop and new-process resume.

Periodic materials (Quantum ESPRESSO + MACE)

examples/qe_mace_skeleton/ shows the configuration shape for a real-material adaptive run: pw.x as the reference engine and a MACE foundation model as the surrogate over a small periodic silicon cell. It is a skeleton, not a verified materials recipe. For complete structure generators and task configurations, see the bulk Si and Al(111) slab examples. They include input requirements, short NVE runs, resume and export commands.

Before pyramid run works you need, on that machine:

• pw.x on PATH (or reference.pw_cmd) and the pseudopotential files the

• pip install '.[mace]' and a MACE model (a local file, or a foundation-model

Without them, pyramid validate run.toml still parses the configuration and reports exactly which pieces are missing. With them, pyramid validate run.toml --probe-backends evaluates the structure once with each backend before committing to a run.

Stop, resume and recover

• Ctrl-C during pyramid run stops at the next complete-step boundary and

• pyramid resume RUN_DIR --steps N always adds N steps to wherever the run

• Resume replays the event log from the last valid checkpoint generation;

• If a crashed process left the event-log writer lock behind,

• Runs whose backends declare file resources (file_parameters) can be

• Solver scratch can live on one unified managed tmp root instead of

• Changing settings means a new run, or a library-level fork that inherits

Plug in your own ASE calculator

Two routes, both without modifying the core package:

1. Python API — the generic adapters wrap separately configured ASE

from pyraimd2.engines import AseEngine
   from pyraimd2.surrogate import AseSurrogate
engine = AseEngine(reference_calculator, force_consistent=True)
   surrogate = AseSurrogate(potential_calculator)

1. Plugin package — register factories under the pyraimd2.backends

Capability declarations (energy kind, force consistency, stress, uncertainty) are checked when a backend is created — before any expensive calculation. See docs/architecture.md for the protocols.

Develop a new method

• docs/architecture.md — the workflow layers and the

• docs/api.md — public entry points of the engines,

• pyraimd2.energetics is a pure numerical layer (directional response,

• pyraimd2.loop.online (GuardedUpdater, UpdatePolicy) is the guarded

Current scope

• Tasks. Single-point evaluation and fixed-model FIRE/BFGS relaxation

• Dynamics. The current release (0.7.2) supports fixed-cell NVE and NVT

• Calibration pacing (opt-in). When [policy.calibration_pacing] is

• Serial recipes. relax → NVT → NVE chains run through

• Backends. QE, molecular closed-shell PySCF, MACE and analytic harmonic

• Energy consistency. Each side's forces must be the negative gradient

• Examples and costs. The Si and Al examples demonstrate software

The energetic MD loop

1. Anchor. Evaluate the reference and fast potential at the same atomic

1. Forecast. Probe the local force response along a configuration-space

1. Propagate or request a reference. Use the corrected fast force while the

1. Measure the work. At a labeled endpoint, compare reference and anchored

1. Update and reanchor. An optional on_label callback can use new labels to

Directional probes supply an empirical forecast. Independent accepted-force checks provide a separate statistical assessment of violations under their sampling protocol. The method guide explains these quantities, their units and the conditions for interpreting them.

Documentation and development

• Configuration and CLI reference
• Architecture and backend integration
• API reference
• Energetic force errors and runtime decisions
• Changelog
• Supplementary Materials: force-error data and code
• examples/ — the demos above, plus direct Python-API scripts:

• Slurm example — a generic submission template

• src/pyraimd2/ — framework implementation; tests/ — numerical, interface

Run the offline core suite (NumPy + ASE only, no optional backends needed):

pytest tests/unit tests/test_smoke.py -q

Backend integration tests marked slow require the corresponding optional software and model files; they are deselected by default and never count as passing when their dependency is missing. Configure production executables, model locations and compute resources in your own run setup.

Citing

If you use Pyramid in your research, please cite the underlying method paper:

• The energetics of force errors in machine-learned molecular dynamics,

License

Pyramid is released under the MIT License.