Metadata-Version: 2.4
Name: catpath
Version: 0.1.0
Summary: Reaction-pathway explorer for catalyst surfaces with ML interatomic potentials: reaction networks, NEB barriers, and cross-model uncertainty.
Project-URL: Homepage, https://github.com/retospect/catpath
Project-URL: Repository, https://github.com/retospect/catpath
Project-URL: Issues, https://github.com/retospect/catpath/issues
Author-email: Reto Stamm <reto@retostamm.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ASE,MLIP,NEB,adsorption,catalysis,computational-chemistry,machine-learning-potential,reaction-network,surface-chemistry,transition-state
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: ase>=3.26
Requires-Dist: matplotlib>=3.9
Requires-Dist: networkx>=3.3
Requires-Dist: numpy>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rdkit>=2024.3
Requires-Dist: scipy>=1.13
Provides-Extra: chgnet
Requires-Dist: chgnet; extra == 'chgnet'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.9; extra == 'chgnet'
Requires-Dist: torch; extra == 'chgnet'
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: fairchem
Requires-Dist: fairchem-core; extra == 'fairchem'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.9; extra == 'fairchem'
Requires-Dist: torch; extra == 'fairchem'
Provides-Extra: grace
Requires-Dist: tensorpotential; extra == 'grace'
Provides-Extra: mace
Requires-Dist: mace-torch; extra == 'mace'
Requires-Dist: nvidia-cuda-nvrtc-cu12>=12.9; extra == 'mace'
Requires-Dist: torch; extra == 'mace'
Provides-Extra: orchestration
Requires-Dist: snakemake>=8; extra == 'orchestration'
Description-Content-Type: text/markdown

# catpath

[![CI](https://github.com/retospect/catpath/actions/workflows/ci.yml/badge.svg)](https://github.com/retospect/catpath/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/catpath.svg)](https://pypi.org/project/catpath/)
[![Python](https://img.shields.io/pypi/pyversions/catpath.svg)](https://pypi.org/project/catpath/)
[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-blue.svg)](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.

![Cross-model comparison of intermediate formation energies](https://raw.githubusercontent.com/retospect/catpath/main/docs/img/models_intermediates.png)

*NO→NH₃ on Pd: formation energies of every intermediate under MACE, CHGNet, and
UMA — the models agree on NO activation but diverge on deep hydrogenation.*

## Install

```bash
pip install catpath
```

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 "catpath[mace]"      # MACE-MP-0 universal potential (GPU)
pip install "catpath[chgnet]"    # CHGNet (CPU-friendly)
pip install "catpath[fairchem]"  # Meta FAIRChem / UMA (adsorbates on metals)
pip install "catpath[grace]"     # GRACE foundation models
```

## Quickstart

```bash
# whole pipeline (all seeds) on the dependency-free EMT backend:
catpath run examples/no_to_no3_pd.yaml

# let the intermediates be discovered automatically, on a real ML potential:
catpath run examples/auto_ammonia.yaml --backend auto
```

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:

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

catpath barriers my.yaml --backend chgnet   --out b_chgnet.json
catpath compare  --states b_*.json --out barriers.png          # Ea, rate-limiting ringed
catpath 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 [`examples/README.md`](examples/README.md) for the full set of
commands.

## CLI

```
catpath run <cfg>            # all seeds in-process + outputs
catpath states <cfg>         # relax states only (no NEB) -> per-model JSON
catpath barriers <cfg>       # NEB for every step -> per-model JSON
catpath compare --states ... # box plots (states or barriers, auto-detected)
catpath multi <cfg>          # several substrates -> union energy map
catpath sweep <cfg> --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

catpath 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).
