kpleo/pyraimd

What is Pyramid?

Pyramid (Python wrapped Ab initio Molecular Dynamics) is a Python framework that combines first-principles quantum mechanics (like DFT) with fast machine-learned potentials (MLIPs) to run molecular dynamics (MD) simulations. It coordinates when to call the expensive reference calculation (e.g., Quantum ESPRESSO) and when to use the fast surrogate (e.g., MACE), using a force-error method to decide when accuracy is needed.

Core Idea

• Reference engines (e.g., QE, PySCF) provide accurate energies and forces.
• Surrogate potentials (e.g., MACE) are fast but approximate.
• Pyramid's force-error method predicts how force errors grow away from known configurations and measures their energetic impact (signed residual work). This guides when to run reference calculations.

Installation

• Requires Python 3.12+.
• Core install needs only NumPy and ASE (no heavy dependencies).
• Install from source: pip install . or pip install -e '.[dev]'.
• Optional backends: pip install '.[pyscf]' (molecular reference), pip install '.[mace]' (MACE surrogate).
• The Python import is pyraimd2; the CLI is pyramid.

Key Features

• Adaptive MD: decides on-the-fly when to call the reference engine.
• Multiple time stepping (MTS): experimental fixed-schedule method that evaluates the reference once per outer step.
• Validation layers: three levels — config check, environment check, and backend probe — to catch issues before a run.
• Checkpoint/resume: safe stopping (Ctrl-C) and resuming, with event-log replay and identity checks.
• Comparison tool: pyramid compare for offline comparison of two completed runs.
• Plugins: add your own ASE calculators or backend packages via entry points.
• Scratch management: optional unified tmp root for solver scratch files.
• Persistent density retention: read-only inspection of density generations.

Typical Workflow

1. Initialize: pyramid init --template harmonic --output my_run (or other templates).
2. Validate: pyramid validate run.toml (config), --check-environment (prerequisites), --probe-backends (compute).
3. Run: pyramid run run.toml.
4. Inspect/Resume/Export: pyramid inspect, pyramid resume, pyramid export.

Current Scope

• Tasks: single-point, relaxation (FIRE/BFGS), MD (NVE, NVT) with reference-only, surrogate-only, or adaptive modes.
• Dynamics: fixed-cell NVE and NVT (Langevin) with FixAtoms. No variable-cell or other constraints.
• Backends: QE, PySCF, MACE, analytic harmonic, plus generic ASE adapters.
• Energy consistency: forces must be negative gradients of reported energies; cross-kind combinations are checked.
• Examples: offline demos (harmonic, Lennard-Jones, QE+MACE skeletons) and real-material examples (Si, Al slab).

Documentation

• User guide: docs/user_guide.md
• Configuration reference: docs/configuration.md
• Architecture: docs/architecture.md
• API: docs/api.md

Notes

• The README emphasizes that example parameters are for demonstration, not accuracy recommendations.
• Online model updates are only available via Python API, not TOML config.
• The project is at version 0.8.5 (as of the README).