mlcg

This repository collects a set of tools to apply machine learning techniques to coarse grain atomic systems.

Installation

First we suggest to create a new clean empty virtual environment with python 3.12, then clone the repo and install the following prerequisites:

git clone git@github.com:ClementiGroup/mlcg.git
cd mlcg
pip install -r env_with_hashes.in
pip install --no-deps git+https://github.com/ACEsuit/mace.git@v0.3.13
pip install --no-deps nequip==0.12.1 nequip-allegro==0.7.0

Then install this repository with:

pip install .

This will likely rise an error due to some dependency issue about e3nn that you can safely ignore.

Examples

Please take a look into the examples folder of the repository to see how to use this code to train a model over an existing dataset.

CLI

The models defined in this library can be conveniently trained using the pytorch-lightning CLI utilities.

Documentation

Documentation is available here and here are some references on how to work with it.

Dependencies

pip install sphinx shibuya sphinx-autodoc-typehints

How to build

cd docs
sphinx-build -b html source build

How to update the online documentation

This update should be done after any update of the main branch so that the documentation is synchronized with the main version of the repository.

git checkout gh-pages
git rebase main
cd docs
sphinx-build -b html source ./
git commit -a
git push

Test Coverage

The test coverage of this library is monitored with coverage for each pull request using GitHub actions. To produce a report locally, run:

coverage run -m pytest
coverage report

This will run the full set of unit and continuity tests in mlcg and the larger integration tests under tests/integration, including training and simulation of all models described in examples/input_yamls/README.md.

For quick local development testing, it is also possible to exclude the large test by running:

coverage run -m pytest --light

Troubleshooting

If it is not possible to install an environment with pip install -r env_with_hashes.in, the following commands can do a similar job.

pip install --extra-index-url=https://download.pytorch.org/whl/cu128 torch==2.8.0
pip install torch_geometric
pip install pyg_lib torch_scatter torch_sparse torch_cluster torch_spline_conv -f https://data.pyg.org/whl/torch-2.8.0+cu128.html
pip install lightning tensorboard torchtnt
pip install cuequivariance-torch==0.8.1 cuequivariance-ops-torch-cu12==0.8.1 nvalchemi-toolkit-ops==0.2.0