aiida-mlip

machine learning interatomic potentials aiida plugin

Features (in development)

• Supports multiple MLIPs
  • MACE
  • M3GNET
  • CHGNET
• Single point calculations
• Geometry optimisation
• Molecular Dynamics:
  • NVE
  • NVT (Langevin(Eijnden/Ciccotti flavour) and Nosé-Hoover (Melchionna flavour))
  • NPT (Nosé-Hoover (Melchiona flavour))
• Training MLIPs
  • MACE
• Fine tuning MLIPs
  • MACE
• MLIP descriptors
  • MACE

The code relies heavily on janus-core, which handles mlip calculations using ASE.

Installation

pip install aiida-mlip
verdi quicksetup  # better to set up a new profile
verdi plugin list aiida.calculations

The last command should show a list of AiiDA pre-installed calculations and the aiida-mlip plugin calculations (mlip.opt, mlip.sp)

Registered entry points for aiida.calculations:
* core.arithmetic.add
* core.templatereplacer
* core.transfer
* mlip.opt
* mlip.sp
* mlip.md
* mlip.train
* mlip.descriptors

Usage

The example folder provides scripts to submit calculations in the calculations folder, and tutorials in jupyter notebook format in the tutorials folder.

A quick demo of how to submit a calculation using the provided example files:

verdi daemon start     # make sure the daemon is running
cd examples/calculations
verdi run submit_singlepoint.py "janus@localhost" --struct "path/to/structure" --architecture mace --model "/path/to/model"    # run singlepoint calculation
verdi run submit_geomopt.py "janus@localhost" --struct "path/to/structure" --model "path/to/model" --steps 5 --opt_cell_fully True # run geometry optimisation
verdi run submit_md.py "janus@localhost" --struct "path/to/structure" --model "path/to/model" --ensemble "nve" --md_dict_str "{'temp':300,'steps':4,'traj-every':3,'stats-every':1}" # run molecular dynamics

verdi process list -a  # check record of calculation

Models can be trained by using the Train calcjob. In that case the needed inputs are a config file containig the path to train, test and validation xyz file and other optional parameters. Running

verdi run submit_train.py

a model will be trained using the provided example config file and xyz files (can be found in the tests folder)

Development

We recommend installing uv for dependency management when developing for aiida-mlip:

1. Install uv
2. Install aiida-mlip with dependencies in a virtual environment:

git clone https://github.com/stfc/aiida-mlip
cd aiida-mlip
uv sync  # Create a virtual environment and install dependencies
source .venv/bin/activate
pre-commit install  # Install pre-commit hooks
pytest -v  # Discover and run all tests

See the developer guide for more information.

Repository contents

• .github/: Github Actions configuration
  • ci.yml: runs tests, checks test coverage and builds documentation at every new commit
  • publish-on-pypi.yml: automatically deploy git tags to PyPI - just generate a PyPI API token for your PyPI account and add it to the pypi_token secret of your github repository
  • docs.yml: builds and deploys the documentation
• aiida_mlip/: The main source code of the plugin package
  • data/: Plugin Data classes
    • model.py ModelData class to save mlip models as AiiDA data types
  • calculations/: Plugin Calcjob classes
    • base.py: Base Calcjob class for other calculations
    • singlepoint.py: Calcjob class to run single point calculations using mlips
    • geomopt.py: Calcjob class to perform geometry optimization using mlips
    • md.py: Calcjob class to perform molecular dynamics using mlips
    • descriptors.py: Calcjob class to calculate MLIP descriptors
  • parsers/: Parsers for the calculations
    • base_parser.py: Base Parser for all calculations.
    • sp_parser.py: Parser for Singlepoint calculation.
    • opt_parser.py: Parser for Geomopt calculation.
    • md_parser.py: Parser for MD calculation.
    • train_parser.py: Parser for Train calculation.
    • descriptors_parser.py: Parser for Descriptors calculation.
  • helpers/: Helpers to run calculations.
  • workflows/: WorkGraphs or WorkChains for common workflows with mlips.
    • ht_workgraph.py: A WorkGraph to run high-throughput optimisations.
• docs/: Code documentation
  • apidoc/: API documentation
  • developer_guide/: Documentation for developers
  • user_guide/: Documentation for users
  • images/: Logos etc used in the documentation
• examples/: Examples for submitting calculations using this plugin
  • tutorials/: Jupyter notebooks with tutorials for running calculations and other files that are used in the tutorial
  • calculations/: Scripts for submitting calculations
    • submit_singlepoint.py: Script for submitting a singlepoint calculation
    • submit_geomopt.py: Script for submitting a geometry optimisation calculation
    • submit_md.py: Script for submitting a molecular dynamics calculation
    • submit_train.py: Script for submitting a train calculation.
    • submit_descriptors.py: Script for submitting a descriptors calculation.
  • workflows/: Scripts for submitting workflows
    • submit_ht_workgraph.py: Script for submitting a high-throughput WorkGraph for singlepoint calculation.
• tests/: Basic regression tests using the pytest framework (submitting a calculation, ...). Install pip install -e .[testing] and run pytest.
  • conftest.py: Configuration of fixtures for pytest
  • calculations/: Calculations
    • test_singlepoint.py: Test SinglePoint calculation
    • test_geomopt.py: Test Geomopt calculation
    • test_md.py: Test MD calculation
    • test_train.py: Test Train calculation
    • test_descriptors.py: Test Descriptors calculation
  • data/: Data
    • test_model.py: Test ModelData type
    • test_config.py: Test JanusConfigfile type
  • workflows/: Workflows
    • test_ht.py: Test high throughput workgraph.
• .gitignore: Telling git which files to ignore
• .pre-commit-config.yaml: Configuration of pre-commit hooks that sanitize coding style and check for syntax errors. Enable via pip install -e .[pre-commit] && pre-commit install
• LICENSE: License for the plugin
• README.md: This file
• tox.ini: File to set up tox
• pyproject.toml: Python package metadata for registration on PyPI and the AiiDA plugin registry (including entry points)

License

BSD 3-Clause License

Funding

Contributors to this project were funded by