Pyramid runs a fast potential between ab initio reference checks

A fast potential carrying the trajectory, a reference checking it

Pyramid describes itself as Python wrapped Ab initio Molecular Dynamics, a name drawn from the PYR-AIMD letters, and it is an updated version of a 2021 project that was developed from Nanoacademic Technology Inc. The scope is a framework rather than a script. It brings first principles engines, machine learned interatomic potentials, solvers and molecular dynamics into one extensible Python framework, and the division of labour is the interesting part. Reference calculations supply energies and forces. Fast potentials propagate the atomic motion. The framework coordinates when to evaluate the reference, when to check the result and when to update. In practice that means a machine learned potential runs the trajectory at the cost of a surrogate, and an expensive ab initio engine is invoked at selected points, which is what makes large scale first principles dynamics possible without paying first principles prices for every step. The project also ships a set of example plugins and a long list of worked examples, from minimal and energetic loops to a periodic Lennard-Jones system, guard rails on an NVT run and a Slurm directory, which is a good sign about how much scaffolding the author expects a real study to need.

The energetic force-error method decides when the reference runs

The framework's intellectual core is a method the documentation calls the energetic force-error method, and it is described in two halves. A local directional response predicts how force errors grow away from a reference configuration. Signed residual work measures the energetic effect of those errors along the trajectory. Together these quantities guide the reference calculations and provide a physical account of the forces used during a run, which is the meaningful difference from a scheme that simply compares numbers. An error metric that ignores direction can be satisfied by a force that is wrong in a way that costs no energy, while a method built on directional response and work along the path is anchored to the physics of the trajectory rather than to a scalar score. For a user, the practical consequence is that the schedule of expensive calls is a policy you can read, reason about and put in a configuration file, rather than a heuristic buried in a script. The 0.8.0 release also adds an experimental fixed-model path, described later here, and the manifest gives the package a version of 0.8.5 with Python 3.12 or later.

Three validation layers that separate a bad config from a blocked machine

The CLI keeps three separate validation scopes, and the separation is the feature. The first is pyramid validate run.toml, which asks whether the configuration is well-formed and never touches the machine's programs or packages. The second adds --check-environment, which asks whether the local runtime prerequisites are present, meaning executables, optional packages and local model files. It is read-only and zero-computation: it starts no backend, runs no command, loads no weights and downloads nothing, and its answer can be blocked or unverified, which explains what it could and could not confirm. The third is --probe-backends, which explicitly evaluates the structure once per backend, and it is the only layer that computes. All three scopes accept --json, which writes one machine-readable report object to stdout. The documentation highlights why that matters for submission scripts on a cluster, because a blocked environment is distinguishable from an invalid configuration by exit status and by the readiness field. A user can therefore test a configuration file on a laptop, check the machine separately, and only then let anything compute.

Installing the wheel and running the offline harmonic demo

The core install is deliberately light. Python 3.12 or later is required, and the core install needs only NumPy and ASE, with no torch, no PySCF and no external programs. From a checkout:

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

The published artefacts are attached to the corresponding GitHub Release, and the documentation shows installing the 0.8.5 wheel into a clean virtual environment:

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

The first run is meant to be quick. The examples/harmonic_adaptive directory is a complete, offline adaptive NVE run using built-in analytic reference and surrogate models to drive a toy H2O molecule, and it exercises anchoring, surrogate acceptance, independent checks, checkpoints, stop and resume, with no external programs and no model downloads, finishing in seconds. The same flow through the command line is:

pyramid init --template harmonic --output my_run
pyramid validate my_run/run.toml
pyramid validate my_run/run.toml --check-environment   # harmonic: ready
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

The init command writes the same pair of files as a starting point for your own configuration, and the documentation is careful to say that the template's policy and verification numbers are demonstration values rather than accuracy recommendations for any real system.

Optional backends are separate extras, and ESPRESSO lives outside Python

The reference and surrogate engines are optional extras that are only imported when selected, which keeps the core install small:

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

The all extra installs both, and builders adds optional structure-building tools, with the manifest listing rdkit at 2024.3 or newer for that role. Quantum ESPRESSO is different again, since it additionally needs a pw.x executable and pseudopotentials installed outside Python, so it cannot be a pure pip install. The manifest also carries a dependency constraint that explains itself in a comment. NumPy is pinned below 2.5, because ASE 3.29.0 sets array shapes through a NumPy API deprecated in NumPy 2.5, and the project prefers to hold the pin until an ASE release drops that usage rather than silencing the warnings. That is a small detail, and it is the kind of detail that saves an afternoon when a new NumPy lands. The Python import is pyraimd2 and the console scripts are pyraimd2 and pyramid, both pointing at pyraimd2:main, with pyramid --version and pyramid --help working offline and downloading nothing.

Fixed-model multiple time stepping and comparing completed runs

Two newer capabilities are worth understanding. The first is the experimental fixed-model multiple time stepping path introduced in 0.8.0, selected with task.mode set to mts. The slow residual between the reference and the fast potential is integrated with symmetric outer r-RESPA kicks around a configurable number of inner velocity-Verlet steps, so the reference is evaluated once per complete outer step. The documentation is explicit about how the modes relate, that it complements adaptive mode rather than replacing it, because adaptive mode decides when to call the reference from a force-error policy while MTS follows a fixed schedule with both models frozen. The step accounting is specific, since timestep_fs is the inner step and steps and resume --steps N count inner steps in multiples of outer_ratio, with the demo running 128 inner steps of 1 fs at ratio 4, which is 32 complete outer steps and 33 committed boundary frames. The structure must carry momenta, and --force-source driving is refused because an outer step has no single driving force. The second is the compare command, pyramid compare REFERENCE_RUN CANDIDATE_RUN, which compares two already completed fixed-cell NVE runs from the same initial state pointwise at identical physical times, reporting per-atom position and velocity RMS over the matched window, per-trajectory Hamiltonian drift when its preconditions hold, and explicit pass or fail only for thresholds you pass yourself. It is fully read-only, constructs no backend, writes nothing, and refuses anything outside that scope with a structured error, which is a better way to judge a change than rerunning both trajectories.

Editorial conclusion

Adopt Pyramid if you are running molecular dynamics where a first principles reference is affordable only occasionally and you want the frequency of those calls decided by a stated policy rather than by hand. Do not adopt it if you only need a cheap surrogate run, because the reference checks are the point of the framework, and do not expect the demo templates to say anything about accuracy on a real system, since the documentation calls their policy and verification numbers demonstration values. Before you start, read the user guide, run the three validation layers in order on your configuration, and confirm the optional backend you need is installed, since PySCF and MACE are separate extras and Quantum ESPRESSO needs a pw.x executable outside Python.

Frequently asked questions

Official sources

1. Issues
2. kpleo/pyraimd on GitHub
3. License: MIT
4. README
5. Releases