autocatpath

Reaction-pathway explorer for catalyst surfaces, driven by ML interatomic potentials. Give it an environment (a metal surface), a substrate, and a target; it builds the reaction network, relaxes every intermediate, finds the barriers with climbing-image NEB, and reports energies with honest uncertainty — pooled across random seeds and across ML potentials.

• Reaction networks — curated templates or rule-based autodetection of intermediates (network: auto).
• Pluggable ML potentials — mace, chgnet, fairchem (UMA), grace, or auto (best installed). emt is a dependency-free dev backend.
• Barriers — climbing-image NEB with automatic retry on non-convergence.
• Cross-model comparison — run the same network under several potentials and box-plot where they agree and disagree (intermediates, barriers, and which transition state is the true rate-limiting "highest point").
• Reproducible — every run writes a provenance snapshot; unstable results are flagged low-confidence rather than reported as precise numbers.

NO→NH₃ on Pd (MACE): every intermediate as a level line, transition states as barrier bumps with Ea, competing pathways in colour, ± uncertainty bands — one autocatpath run. → more outputs and their commands in the gallery.

Install

pip install autocatpath

The default emt backend is pure numpy/ASE (no torch, no GPU) and runs the whole pipeline anywhere — great for trying it out and for CI. For real numbers, add exactly one ML backend (their dependencies conflict, so one per environment):

pip install "autocatpath[mace]"      # MACE-MP-0 universal potential (GPU)
pip install "autocatpath[chgnet]"    # CHGNet (CPU-friendly)
pip install "autocatpath[fairchem]"  # Meta FAIRChem / UMA (adsorbates on metals)
pip install "autocatpath[grace]"     # GRACE foundation models

Quickstart

# no config file needed — set the chemistry on the command line:
autocatpath run --substrate NO --target NH3 --element Pd --network auto

# or point at a YAML config (see examples/):
autocatpath run examples/no_to_no3_pd.yaml

# discover the intermediates automatically, on a real ML potential:
autocatpath run examples/auto_ammonia.yaml --backend auto

Run autocatpath --help (or autocatpath run --help) for every flag. Config files and flags mix freely — flags override the file.

Outputs land in runs/<name>/:

File	Contents
graph_thumbs.png	reaction energy-profile with active-site structure thumbnails
graph_network.png	node/DAG view of the network (red = low-confidence)
energy_map.png	substrate × intermediate heatmap; ★ = rate-limiting state
results.json	nodes, edges, barriers, mean ± spread, warnings
methods.md	a deterministic methods paragraph for your write-up
config.snapshot.yaml	provenance snapshot for exact reproduction

Compare several ML potentials

Because the backends can't share an environment, run states / barriers in each one's env, then compare the JSONs:

autocatpath states   my.yaml --backend chgnet   --out s_chgnet.json
autocatpath states   my.yaml --backend fairchem --out s_uma.json
autocatpath compare  --states s_*.json --out intermediates.png     # box plot per state

autocatpath barriers my.yaml --backend chgnet   --out b_chgnet.json
autocatpath compare  --states b_*.json --out barriers.png          # Ea, rate-limiting ringed
autocatpath compare  --states b_*.json --heights s_*.json --out ts_heights.png

State energies are referenced to per-element gas-phase chemical potentials computed in each potential, so composition-changing states are comparable across models. See the gallery and examples/README.md for the full set of commands.

CLI

autocatpath run <cfg>            # all seeds in-process + outputs
autocatpath states <cfg>         # relax states only (no NEB) -> per-model JSON
autocatpath barriers <cfg>       # NEB for every step -> per-model JSON
autocatpath compare --states ... # box plots (states or barriers, auto-detected)
autocatpath multi <cfg>          # several substrates -> union energy map
autocatpath sweep <cfg> --elements Pd,Pt,Cu   # same network across surfaces

Everything is one YAML file — see docs/CONFIG.md for every field, and docs/USAGE.md for extension points.

Development

uv sync --extra dev
uv run ruff check src tests
uv run pytest

Contributing

Issues and PRs welcome — see CONTRIBUTING.md. Maintained by Reto Stamm.

Acknowledgements

autocatpath was requested by Muhammad Umer, whose help shaping what it should do got the project off the ground.

Built with Claude (Anthropic) via Claude Code, with research assistance from Perplexity.

License

GPL-3.0-or-later. Built on ASE (LGPL) and RDKit (BSD).