https://github.com/retospect/catpath
ML-potential reaction-pathway explorer for catalyst surfaces: reaction networks, NEB barriers, cross-model uncertainty, and publication-ready diagrams.
https://github.com/retospect/catpath
ase catalysis computational-chemistry machine-learning-potentials mlip neb reaction-network surface-chemistry transition-state
Last synced: 1 day ago
JSON representation
ML-potential reaction-pathway explorer for catalyst surfaces: reaction networks, NEB barriers, cross-model uncertainty, and publication-ready diagrams.
- Host: GitHub
- URL: https://github.com/retospect/catpath
- Owner: retospect
- License: gpl-3.0
- Created: 2026-07-12T16:29:28.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-07-26T12:36:24.000Z (5 days ago)
- Last Synced: 2026-07-26T14:10:06.019Z (5 days ago)
- Topics: ase, catalysis, computational-chemistry, machine-learning-potentials, mlip, neb, reaction-network, surface-chemistry, transition-state
- Language: Python
- Size: 2.69 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# autocatpath
[](https://github.com/retospect/catpath/actions/workflows/ci.yml)
[](https://pypi.org/project/autocatpath/)
[](https://pypi.org/project/autocatpath/)
[](LICENSE)
**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](docs/GALLERY.md).**
## Install
```bash
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**):
```bash
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
```bash
# 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//`:
| 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:
```bash
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](docs/GALLERY.md) and
[`examples/README.md`](examples/README.md) for the full set of commands.
## CLI
```
autocatpath run # all seeds in-process + outputs
autocatpath states # relax states only (no NEB) -> per-model JSON
autocatpath barriers # NEB for every step -> per-model JSON
autocatpath compare --states ... # box plots (states or barriers, auto-detected)
autocatpath multi # several substrates -> union energy map
autocatpath sweep --elements Pd,Pt,Cu # same network across surfaces
```
Everything is one YAML file — see [`docs/CONFIG.md`](docs/CONFIG.md) for every
field, and [`docs/USAGE.md`](docs/USAGE.md) for extension points.
## Development
```bash
uv sync --extra dev
uv run ruff check src tests
uv run pytest
```
## Contributing
Issues and PRs welcome — see [`CONTRIBUTING.md`](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](https://wiki.fysik.dtu.dk/ase/) (LGPL) and
RDKit (BSD).