{"id":51969409,"url":"https://github.com/retospect/catpath","last_synced_at":"2026-07-29T20:01:13.775Z","repository":{"id":371034805,"uuid":"1298441596","full_name":"retospect/catpath","owner":"retospect","description":"ML-potential reaction-pathway explorer for catalyst surfaces: reaction networks, NEB barriers, cross-model uncertainty, and publication-ready diagrams.","archived":false,"fork":false,"pushed_at":"2026-07-26T12:36:24.000Z","size":2819,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-26T14:10:06.019Z","etag":null,"topics":["ase","catalysis","computational-chemistry","machine-learning-potentials","mlip","neb","reaction-network","surface-chemistry","transition-state"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/retospect.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-12T16:29:28.000Z","updated_at":"2026-07-26T12:36:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/retospect/catpath","commit_stats":null,"previous_names":["retospect/catpath"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/retospect/catpath","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retospect%2Fcatpath","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retospect%2Fcatpath/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retospect%2Fcatpath/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retospect%2Fcatpath/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/retospect","download_url":"https://codeload.github.com/retospect/catpath/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/retospect%2Fcatpath/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36047717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ase","catalysis","computational-chemistry","machine-learning-potentials","mlip","neb","reaction-network","surface-chemistry","transition-state"],"created_at":"2026-07-29T20:01:12.798Z","updated_at":"2026-07-29T20:01:13.756Z","avatar_url":"https://github.com/retospect.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# autocatpath\n\n[![CI](https://github.com/retospect/catpath/actions/workflows/ci.yml/badge.svg)](https://github.com/retospect/catpath/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/autocatpath.svg)](https://pypi.org/project/autocatpath/)\n[![Python](https://img.shields.io/pypi/pyversions/autocatpath.svg)](https://pypi.org/project/autocatpath/)\n[![License: GPL v3](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE)\n\n**Reaction-pathway explorer for catalyst surfaces, driven by ML interatomic\npotentials.** Give it an environment (a metal surface), a substrate, and a\ntarget; it builds the reaction network, relaxes every intermediate, finds the\nbarriers with climbing-image NEB, and reports energies with **honest\nuncertainty** — pooled across random seeds *and* across ML potentials.\n\n- **Reaction networks** — curated templates *or* rule-based **autodetection** of\n  intermediates (`network: auto`).\n- **Pluggable ML potentials** — `mace`, `chgnet`, `fairchem` (UMA), `grace`, or\n  `auto` (best installed). `emt` is a dependency-free dev backend.\n- **Barriers** — climbing-image NEB with automatic retry on non-convergence.\n- **Cross-model comparison** — run the same network under several potentials and\n  box-plot where they agree and disagree (intermediates, barriers, and which\n  transition state is the true rate-limiting \"highest point\").\n- **Reproducible** — every run writes a provenance snapshot; unstable results are\n  flagged low-confidence rather than reported as precise numbers.\n\n![NO→NH3 reaction energy profile on Pd](https://raw.githubusercontent.com/retospect/catpath/main/docs/img/energy_profile.png)\n\n*NO→NH₃ on Pd (MACE): every intermediate as a level line, transition states as\nbarrier bumps with Ea, competing pathways in colour, ± uncertainty bands — one\n`autocatpath run`.* **→ more outputs and their commands in the\n[gallery](docs/GALLERY.md).**\n\n## Install\n\n```bash\npip install autocatpath\n```\n\nThe default **`emt`** backend is pure numpy/ASE (no torch, no GPU) and runs the\nwhole pipeline anywhere — great for trying it out and for CI. For real numbers,\nadd exactly one ML backend (their dependencies conflict, so **one per\nenvironment**):\n\n```bash\npip install \"autocatpath[mace]\"      # MACE-MP-0 universal potential (GPU)\npip install \"autocatpath[chgnet]\"    # CHGNet (CPU-friendly)\npip install \"autocatpath[fairchem]\"  # Meta FAIRChem / UMA (adsorbates on metals)\npip install \"autocatpath[grace]\"     # GRACE foundation models\n```\n\n## Quickstart\n\n```bash\n# no config file needed — set the chemistry on the command line:\nautocatpath run --substrate NO --target NH3 --element Pd --network auto\n\n# or point at a YAML config (see examples/):\nautocatpath run examples/no_to_no3_pd.yaml\n\n# discover the intermediates automatically, on a real ML potential:\nautocatpath run examples/auto_ammonia.yaml --backend auto\n```\n\nRun `autocatpath --help` (or `autocatpath run --help`) for every flag. Config files and\nflags mix freely — flags override the file.\n\nOutputs land in `runs/\u003cname\u003e/`:\n\n| File | Contents |\n|---|---|\n| `graph_thumbs.png` | reaction energy-profile with active-site structure thumbnails |\n| `graph_network.png` | node/DAG view of the network (red = low-confidence) |\n| `energy_map.png` | substrate × intermediate heatmap; ★ = rate-limiting state |\n| `results.json` | nodes, edges, barriers, mean ± spread, warnings |\n| `methods.md` | a deterministic methods paragraph for your write-up |\n| `config.snapshot.yaml` | provenance snapshot for exact reproduction |\n\n## Compare several ML potentials\n\nBecause the backends can't share an environment, run `states` / `barriers` in\neach one's env, then `compare` the JSONs:\n\n```bash\nautocatpath states   my.yaml --backend chgnet   --out s_chgnet.json\nautocatpath states   my.yaml --backend fairchem --out s_uma.json\nautocatpath compare  --states s_*.json --out intermediates.png     # box plot per state\n\nautocatpath barriers my.yaml --backend chgnet   --out b_chgnet.json\nautocatpath compare  --states b_*.json --out barriers.png          # Ea, rate-limiting ringed\nautocatpath compare  --states b_*.json --heights s_*.json --out ts_heights.png\n```\n\n![Cross-model comparison of intermediate formation energies](https://raw.githubusercontent.com/retospect/catpath/main/docs/img/models_intermediates.png)\n\nState energies are referenced to per-element gas-phase chemical potentials\ncomputed *in each potential*, so composition-changing states are comparable\nacross models. See the [gallery](docs/GALLERY.md) and\n[`examples/README.md`](examples/README.md) for the full set of commands.\n\n## CLI\n\n```\nautocatpath run \u003ccfg\u003e            # all seeds in-process + outputs\nautocatpath states \u003ccfg\u003e         # relax states only (no NEB) -\u003e per-model JSON\nautocatpath barriers \u003ccfg\u003e       # NEB for every step -\u003e per-model JSON\nautocatpath compare --states ... # box plots (states or barriers, auto-detected)\nautocatpath multi \u003ccfg\u003e          # several substrates -\u003e union energy map\nautocatpath sweep \u003ccfg\u003e --elements Pd,Pt,Cu   # same network across surfaces\n```\n\nEverything is one YAML file — see [`docs/CONFIG.md`](docs/CONFIG.md) for every\nfield, and [`docs/USAGE.md`](docs/USAGE.md) for extension points.\n\n## Development\n\n```bash\nuv sync --extra dev\nuv run ruff check src tests\nuv run pytest\n```\n\n## Contributing\n\nIssues and PRs welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md). Maintained by\nReto Stamm.\n\n## Acknowledgements\n\nautocatpath was requested by **Muhammad Umer**, whose help shaping what it should do\ngot the project off the ground.\n\nBuilt with **Claude** (Anthropic) via Claude Code, with research assistance from\n**Perplexity**.\n\n## License\n\nGPL-3.0-or-later. Built on [ASE](https://wiki.fysik.dtu.dk/ase/) (LGPL) and\nRDKit (BSD).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretospect%2Fcatpath","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretospect%2Fcatpath","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretospect%2Fcatpath/lists"}