Phase 7: Fixed-configuration MC energy audit: see PHASE7_FIXED_CONFIGURATION_ENERGY_AUDIT.md. This is an optional diagnostic; the simulation algorithms are unchanged.
rs@md paper reproduction status (2026-10-29): The A2
metropolispath has been replaced by the paper's Figure 3a trial-relaxation/Metropolis workflow. The historical fixed-coordinate MH validation is not a validation of this algorithm. For scope, density, energy-mode audit, and HPC test commands see PAPER_REPRODUCTION_STATUS.md. PEL II and NPT are postponed. Phase 5 energy-source audit: PAPER_SOURCE_CODE_AUDIT_PHASE5.md.
This is the single development repository. The original 100 ns A2 simulation is a read-only scientific reference; do not overwrite its code or Python environment. The current structure separates:
reactive_md/engine/contracts.py: chemistry-neutral reaction and observer contractsreactive_md/engine/nvt.py: Nose-Hoover NVT integration and neighbor-list recoveryreactive_md/md_driver.py: generic MD loop, reaction dispatch, and observer notificationsreactive_md/reactions/: A2 rate, A2 Metropolis and LiPF6 handlers/output adapterstools/audit_a2_trajectory.py: dependency-free 100 ns CSV consistency checker
Legacy run_md_nvt_a2 and run_md_nvt_with_reactions imports remain supported.
The original small/reversible A2 example scripts are restored in scripts/.
See DEVELOPMENT_STATUS.md for verified tests and outstanding JAX-MD validation.
Reactive molecular dynamics framework for topology-changing simulations using JAX-MD.
The package supports:
- Classical OPLS-AA force fields
- Stochastic topology-changing reactions
- Metropolis-based reaction acceptance
- Rate-based reaction kinetics
- Activation-energy-driven reaction kinetics (rs@MD / Heuer-style)
- Optional MACE-JAX / MLIP energy evaluation for the Metropolis reaction acceptance step
The current implementation includes a LiPF6 decomposition example:
LiPF6 <-> LiF + PF5
The LiPF6 reaction is controlled by a single reaction coordinate
sigma = d(P-F) - d(Li-F)
where the selected F atom is the leaving fluorine. Negative sigma values are reactant-like, while positive sigma values are product-like. Forward candidates are ranked by sigma. Reverse candidates are restricted to the recorded leaving F and Li, with finite P-F and Li-F proximity cutoffs; LiF has no explicit Li-F bond. Reverse reactions are off by default in both modes.
Clone the repository:
git clone https://github.com/BAMeScience/reactive_md_project.git
cd reactive_md_projectInstall in editable mode:
pip install -e .or with uv:
uv pip install -e .Run from the repository root in the development environment:
python -m pytest -q tests/
# Or through SLURM:
srun --gres=gpu:1 --time=00:10:00 python -m pytest -q tests/Pytest is configured with pythonpath = ["."] so imports from the
repository-local scripts/ package work with either pytest or
python -m pytest. If test collection refers to tests/test_reaction.py or
tests/test_topology_opls.py, the checkout contains tests not shipped in
this development archive. Back up those old tests before migrating them;
they refer to interfaces absent from the current implementation. A clean
checkout is preferable to extracting the archive over an older source tree.
Install the package together with the test/development tools:
uv pip install -e .
uv pip install pytest ruffAlternatively, install the included development extras:
uv pip install -e ".[dev]"For MACE-assisted reaction acceptance:
uv pip install -e ".[mace]"The currently tested dependency stack is:
jax 0.10.1
jaxlib 0.10.1
flax 0.12.2
haiku 0.0.16
For GPU support, install the appropriate CUDA-enabled JAX version, for example:
uv pip install -U "jax[cuda13]"The package provides the command-line executable:
reactive-mdDisplay all available options:
reactive-md --helpThe code requires:
- A LAMMPS data file
- A LAMMPS settings file
Example:
reactive-md \
--data system.data \
--settings system.in.settingsThe LiPF6 decomposition reaction uses the Fattebert-inspired coordinate:
sigma = d(P-F) - d(Li-F)
Interpretation:
sigma < 0: the leaving F is closer to P than to Li, so the geometry is PF6-like.sigma = 0: the leaving F is equally distant from P and Li.sigma > 0: the leaving F is closer to Li than to P, so the geometry is product-like.
Candidate reactions are ranked by sigma. The reaction probability is derived from sigma using a smooth sigmoid-like factor controlled by:
--sigma-mid
--sigma-width
--sigma-mid is the sigma value where the geometric reaction factor is 0.5. --sigma-width controls how sharply the probability changes around sigma_mid.
Example:
reactive-md \
--data system.data \
--settings system.in.settings \
--reaction-mode rate \
--reaction-rate-ps 0.01 \
--sigma-mid 0.0 \
--sigma-width 0.2Topology changes are proposed using the reaction coordinate σ and accepted according to a hybrid kinetic/thermodynamic Metropolis scheme.
The reaction coordinate σ is first evaluated to determine whether a reaction trial should be attempted. Only if this kinetic condition is satisfied is the expensive trial topology generated, Langevin-relaxed, and evaluated with the selected energy model (classical force field or MACE). The final thermodynamic acceptance is then determined using the Metropolis criterion based on the energy difference ΔE. Trial reactions yielding non-finite energy differences are automatically rejected.
reactive-md \
--data system.data \
--settings system.in.settings \
--reaction-mode metropolis \
--sigma-mid 0.0 \
--sigma-width 0.2In classical mode, the Metropolis energy difference is computed with the classical force field. If MACE support is enabled, the Metropolis energy difference is evaluated with MACE-JAX instead.
Topology changes are accepted according to a prescribed base reaction rate modulated by the sigma-dependent geometric factor:
reactive-md \
--data system.data \
--settings system.in.settings \
--reaction-mode rate \
--reaction-rate-ps 0.01 \
--sigma-mid 0.0 \
--sigma-width 0.2The effective rate is
k_eff = k_base * f(sigma)
and the reaction probability during one reactive interval is
p = f(sigma) * k_base * dt (linear approximation, with k_base * dt <= 1)
where:
k_baseis the prescribed or activation-energy-derived base rate in ps^-1.f(sigma)is the sigma-dependent geometric factor.dtis the reactive check interval.
The exact constant-rate Poisson probability would be 1-exp(-k_eff*dt);
this implementation intentionally uses its first-order approximation. The
rate implementation uses two independent Bernoulli gates (f(sigma) and
k_base*dt), whose joint probability is the expression above. The optional
reverse rate uses f(-sigma) * k_reverse * dt and defaults to zero.
To enable reverse rate attempts, pass --reverse-rate-ps VALUE. A nonzero
reverse rate requires a justified parameter; it is not inferred from the
forward activation barrier. In Metropolis mode, pass --allow-reverse-mc to
allow exploratory reverse proposals. The hybrid sigma-gated Metropolis
algorithm is not an MH-corrected equilibrium sampler.
All accepted LiPF6 events use the shared post-reaction Langevin relaxation
(defaults: --relaxation-dt-ps 0.00025, --relaxation-time-ps 5.0,
--relaxation-tau-ps 0.01). The resulting velocities are passed back to the
NVT driver, and its thermostat is reinitialized. These parameters should be
validated for LiPF6 before production runs.
Instead of specifying a reaction rate directly, provide an activation barrier:
reactive-md \
--data system.data \
--settings system.in.settings \
--reaction-mode rate \
--activation-energy-eV 0.20 \
--sigma-mid 0.0 \
--sigma-width 0.2The base reaction rate is computed using transition-state theory:
k(T) = (kB * T / h) * exp(-Ea / (kB * T))
and then modulated by the sigma-dependent geometric factor.
To evaluate reaction energies with MACE-JAX:
reactive-md \
--data system.data \
--settings system.in.settings \
--reaction-mode metropolis \
--use-mace-mcThe molecular dynamics trajectory still uses the classical force field. MACE is used only for the Metropolis reaction acceptance energy evaluation. The post-proposal Langevin relaxation uses the product-side classical force field; its relaxed velocities are returned to the NVT driver.
Write a LAMMPS-style trajectory:
reactive-md \
--data system.data \
--settings system.in.settings \
--dump-file traj.dumpCompressed output:
reactive-md \
--data system.data \
--settings system.in.settings \
--dump-file traj.dump.gzRecord accepted reactions:
reactive-md \
--data system.data \
--settings system.in.settings \
--event-log-file reactions.csvRecord sigma-ranked reaction candidates:
reactive-md \
--data system.data \
--settings system.in.settings \
--candidate-log-file candidates.csv \
--candidate-log-top-n 20The candidate log contains sigma-ranked candidates. It no longer contains passes_lif, passes_pf, or passes_all, because those belonged to the old hard-distance-gated model.
Useful diagnostic columns include:
step, mode, rank, pf6_index, li_idx, leave_F, d_lif, d_pf, sigma, accepted
Run tests:
pytestRun only the reaction-coordinate tests:
pytest tests/test_reaction_sigma.pyRun with verbose output:
pytest -vreactive_md/
├── config.py
├── forcefield.py
├── reaction.py
├── md_driver.py
├── main.py
├── lammps_io.py
├── extract_params_oplsaa.py
├── reactions/
│ ├── lipf6.py
│ └── templates_pf5.py
tests/
├── test_candidate_selection.py
├── test_config.py
├── test_forcefield.py
├── test_lipf6.py
├── test_main.py
├── test_main_cli.py
├── test_md_driver.py
├── test_metropolis.py
├── test_reaction_coordinate.py
├── test_template_pf5.py
└── test_topology_change.py
| Test | Purpose |
| ----------------------------- | ----------------------------------------------- |
| `test_candidate_selection.py` | Reaction candidate identification and ranking. |
| `test_config.py` | Configuration defaults and validation. |
| `test_forcefield.py` | Force-field construction and evaluation. |
| `test_lipf6.py` | LiPF₆ topology and chemistry utilities. |
| `test_main.py` | Core simulation workflow. |
| `test_main_cli.py` | Command-line interface. |
| `test_md_driver.py` | MD driver and reaction integration. |
| `test_metropolis.py` | Metropolis acceptance criterion. |
| `test_reaction_coordinate.py` | Reaction coordinate (σ) evaluation. |
| `test_template_pf5.py` | PF₅ template generation. |
| `test_topology_change.py` | Topology modification after accepted reactions. |
If you use this software in academic work, please cite:
- JAX-MD
@inproceedings{jaxmd2020,
author = {Schoenholz, Samuel S. and Cubuk, Ekin D.},
booktitle = {Advances in Neural Information Processing Systems},
publisher = {Curran Associates, Inc.},
title = {JAX M.D. A Framework for Differentiable Physics},
url = {https://papers.nips.cc/paper/2020/file/83d3d4b6c9579515e1679aca8cbc8033-Paper.pdf},
volume = {33},
year = {2020}
}
- MACE / MACE-JAX, if used https://github.com/ACEsuit/mace-jax
@inproceedings{Batatia2022mace,
title={{MACE}: Higher Order Equivariant Message Passing Neural Networks for Fast and Accurate Force Fields},
author={Ilyes Batatia and David Peter Kovacs and Gregor N. C. Simm and Christoph Ortner and Gabor Csanyi},
booktitle={Advances in Neural Information Processing Systems},
editor={Alice H. Oh and Alekh Agarwal and Danielle Belgrave and Kyunghyun Cho},
year={2022},
url={https://openreview.net/forum?id=YPpSngE-ZU}
}
@misc{Batatia2022Design,
title = {The Design Space of E(3)-Equivariant Atom-Centered Interatomic Potentials},
author = {Batatia, Ilyes and Batzner, Simon and Kov{\'a}cs, D{\'a}vid P{\'e}ter and Musaelian, Albert and Simm, Gregor N. C. and Drautz, Ralf and Ortner, Christoph and Kozinsky, Boris and Cs{\'a}nyi, G{\'a}bor},
year = {2022},
number = {arXiv:2205.06643},
eprint = {2205.06643},
eprinttype = {arxiv},
doi = {10.48550/arXiv.2205.06643},
archiveprefix = {arXiv}
} - The original rs@MD methodology by Heuer and co-workers, J. Chem. Theory Comput. 2021, 17, 1074-1085
- The ab initio work motivating the LiPF6 reaction coordinate, Journal of The Electrochemical Society, 2024 171 080505
See LICENSE file.
reactive_md.md_driver now owns only the generic Nose–Hoover NVT
integrator, transactional neighbor-list overflow recovery, reaction-handler
protocol, and observer dispatch. It contains no A2 or LiPF6 candidate logic.
reactive_md.reactions.a2_handlers.A2RateHandlerwraps the existing A2 kinetic cycle, including its optional Langevin relaxation.reactive_md.reactions.a2_handlers.A2MetropolisHandlerwraps the fixed-coordinate Metropolis–Hastings cycle.reactive_md.reactions.lipf6_handler.LiPF6Handleradapts the existing LiPF6 callback to the generic interface.reactive_md.observers.EnergyCSVObserverandEventJSONLObserverimplement chemistry-neutral output formats.
A generic simulation can be launched with the following pattern (using an already constructed force field, system state, box, and A2 reaction model):
from reactive_md.md_driver import run_md_nvt
from reactive_md.reactions.a2_handlers import A2MetropolisHandler
from reactive_md.observers import EnergyCSVObserver, EventJSONLObserver
handler = A2MetropolisHandler(reaction=reaction, rng=rng)
with open('energy.csv', 'w') as energy_file, open('events.jsonl', 'w') as event_file:
result = run_md_nvt(
key, cfg=cfg, init_positions=R, masses=masses, shift_fn=shift_fn,
ff=ff, sys=system, box=box, reaction_handler=handler,
observers=(EnergyCSVObserver(energy_file), EventJSONLObserver(event_file)),
)Existing entry points remain available:
reactive_md.md_a2_driver.run_md_nvt_a2preserves A2-specific RDF, population history, LAMMPS dump, and CSV formats.reactive_md.md_driver.run_md_nvt_with_reactionsremains a lazy compatibility alias for the LiPF6 driver.reactive_md.md_driver.run_md_nvt_a2remains a lazy compatibility alias.
Both compatibility drivers now use the same generic run_md_nvt engine.
LiPF6-specific CSVs and trajectory dumps live in reactions/lipf6_output.py;
the optional on_before_reaction hook captures pre-reaction energies and
frames without adding chemistry-specific branches to the MD engine.
The LiPF6 driver also benefits from overflow-checked MD chunks and a refreshed cached force following topology changes. That can change a trajectory compared with the previous implementation, so run numerical regression checks before production.
The current A2 MC implementation is a topology-only sampler. Its attempt frequency is not a physical reaction rate. The target distribution uses the force-field energy (including the per-dimer energy offset); there is no independent chemical-potential or standard-state correction. Coordinate-changing MC proposals require their own reversible proposal-density correction.
This archive includes the restored scripts/ package imported by
the small A2 tests. The original jax-md dependency is still required for
integration tests. Do not deploy this experimental refactor into an ongoing
production job without testing it in a separate environment.
See DEVELOPMENT_STATUS.md for the single-repository plugin refactor, compatibility guarantees, test results, and outstanding validation before production use.
See PHASE6_PAIRED_NVT_PILOT.md for a short, matched-initial-condition MC/rate diagnostic with explicit rate/cutoff inputs, MC attempt energies, and a machine-readable report. It is not a published NPT benchmark.