README.md

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

1. Install poetry
2. (Optional) Create a virtual environment
3. Install aiida-mlip with dependencies:

git clone https://github.com/stfc/aiida-mlip
cd aiida-mlip
pip install --upgrade pip
poetry install --with pre-commit,dev,docs  # install extra dependencies
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.
• 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/: Scripts for submitting calculations
  • calculations/: Jupyter notebooks with tutorials for running calculations and other files that are used in the tutorial
    • 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.
• 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/: ModelData
    • test_model.py: Test ModelData type
    • test_config.py: Test JanusConfigfile type
• .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