graph-pes is a framework built to accelerate the development of machine-learned potential energy surface (PES) models that act on graph representations of atomic structures.
Links: Google Colab Quickstart - Documentation - PyPI
Statement of need
graph-pes is a toolkit for building, training, and deploying machine-learned potential energy surfaces (PES) models that act on graph representations of atomic structures.
As a researcher who wants to train and use existing MLIPs, you can use the graph-pes-train command to train many different architectures from scratch on your own data, or fine-tune several existing foundation models. Once trained, you can use our drivers to run optimisations, single point energy calculations, and molecular dynamics simulations with your model with a variety of existing tools (LAMMPS, ASE, and torch-sim).
As a researcher wanting to work on MLIP methodology, graph-pes makes implementing new architectures easy, allows you to experiment with various different training strategies, and provides a clean, well-documented API for building things yourself.
Features
- Experiment with new model architectures by inheriting from our
GraphPESModelbase class. - Train your own or existing model architectures (e.g., SchNet, NequIP, PaiNN, MACE, TensorNet, OrB etc.).
- Use and fine-tune foundation models via a unified interface: MACE-MP0, MACE-OFF, MatterSim, GO-MACE, Egret and Orb v2/3.
- Easily configure distributed training, learning rate scheduling, weights and biases logging, and other features using our
graph-pes-traincommand line interface. - Use our data-loading pipeline within your own training loop.
- Run molecular dynamics simulations with any
GraphPESModelusing torch-sim, LAMMPS or ASE
Quickstart
pip install -q graph-pes
wget https://tinyurl.com/graph-pes-minimal-config -O config.yaml
graph-pes-train config.yaml
Alternatively, for a 0-install quickstart experience, please see this Google Colab, which you can also find in our documentation.
Getting help
For usage questions, help with configuration, or troubleshooting, please open a GitHub issue. Questions are welcome; you do not need to have found a bug.
Please include what you are trying to do, your graph-pes and Python versions, your operating system, and a minimal example or configuration where possible. If something fails, include the command and full error message.
Contributing
Contributions are welcome! If you find any issues or have suggestions for new features, please open an issue or submit a pull request on the GitHub repository.
We use uv to manage dependencies and run commands. Install it here, and sync the dependencies using uv sync --all-extras.
Once you have made your changes, you can:
- run tests locally:
uv run pytest tests/ - build the documentation:
uv run sphinx-build docs/source docs/build
Please see our CONTRIBUTING.md file for more details.
Citing graph-pes
We kindly ask that you cite graph-pes in your work if it has been useful to you.
A manuscript is currently in preparation - in the meantime, please cite the Zenodo DOI found in the CITATION.cff file.
1 maintainer
Release files for graph-pes 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| graph_pes-1.0.1.tar.gz | 264.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| graph_pes-1.0.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 561.7 kB
Release files / graph_pes-1.0.1.tar.gz
| Download URL | graph_pes-1.0.1.tar.gz |
|---|---|
| Size | 264.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0df3bdb64f0eb49cdf346122b14a59d65e5ef8aa981dae334ae025513c10d072
|
|
BLAKE2b-256 checksum How to use checksums |
759eb0e9d810ded218e3f352a350669b33f9cc2e022424a13a7cfcf6c1a2e6ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / graph_pes-1.0.1-py3-none-any.whl
| Download URL | graph_pes-1.0.1-py3-none-any.whl |
|---|---|
| Size | 297.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57eda91697bf21a0de23c0bafe56e3db470b2746305b210e70735dd18b4ebca2
|
|
BLAKE2b-256 checksum How to use checksums |
d2eff6489ed342f2f39348785b1032275e6054e992c956ae5c61062d9c9c4ba3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
