Tools for machine learnt interatomic potentials
janus-core dependencies currently include:
- Python >= 3.9
- ASE >= 3.23
- mace-torch = 0.3.6
- chgnet = 0.3.8 (optional)
- matgl = 1.1.3 (optional)
- sevenn = 0.10.0 (optional)
- alignn = 2024.5.27 (optional)
All required and optional dependencies can be found in pyproject.toml.
Note
Where possible, we expect to update pinned MLIP dependencies to match their latest releases, subject to any required API fixes.
The latest stable release of janus-core, including its dependencies, can be installed from PyPI by running:
python3 -m pip install janus-core
To get all the latest changes, janus-core can also be installed from GitHub:
python3 -m pip install git+https://github.com/stfc/janus-core.git
By default, MACE is the only MLIP installed.
Other MLIPs can be installed as extras. For example, to install CHGNet and M3GNet, run:
python3 -m pip install janus-core[chgnet,m3gnet]or to install all supported MLIPs:
python3 -m pip install janus-core[all]Individual extras are listed in Getting Started, as well as in pyproject.toml under [tool.poetry.extras].
Please see Getting Started, as well as guides for janus-core's Python and command line interfaces, for additional information, or open an issue if something doesn't seem right.
Unless stated otherwise, MLIP calculators and calculations rely heavily on ASE.
Current and planned features include:
- Support for multiple MLIPs
- MACE
- M3GNet
- CHGNet
- ALIGNN (experimental)
- SevenNet (experimental)
- Single point calculations
- Geometry optimisation
- Molecular Dynamics
- NVE
- NVT (Langevin(Eijnden/Ciccotti flavour) and Nosé-Hoover (Melchionna flavour))
- NPT (Nosé-Hoover (Melchiona flavour))
- Nudge Elastic Band
- Phonons
- Phonopy
- Equation of State
- Training ML potentials
- MACE
- Fine tunning MLIPs
- MACE
- Descriptors
- MACE
- Rare events simulations
- PLUMED
All supported MLIP calculations are accessible through subcommands of the janus command line tool, which is installed with the package:
janus singlepoint
janus geomopt
janus md
janus phonons
janus eos
janus train
janus descriptorsFor example, a single point calcuation (using the MACE-MP "small" force-field) can be performed by running:
janus singlepoint --struct tests/data/NaCl.cif --arch mace_mp --model-path smallA description of each subcommand, as well as valid options, can be listed using the --help option. For example,
janus singlepoint --helpprints the following:
Usage: janus singlepoint [OPTIONS]
Perform single point calculations and save to file.
Options:
--struct PATH Path of structure to simulate. [required]
--arch TEXT MLIP architecture to use for calculations. [default:
mace_mp]
--device TEXT Device to run calculations on. [default: cpu]
--model-path TEXT Path to MLIP model. [default: None]
--properties TEXT Properties to calculate. If not specified, 'energy',
'forces' and 'stress' will be returned.
--out PATH Path to save structure with calculated results. Default
is inferred from name of structure file.
--read-kwargs DICT Keyword arguments to pass to ase.io.read. Must be
passed as a dictionary wrapped in quotes, e.g. "{'key'
: value}". [default: "{}"]
--calc-kwargs DICT Keyword arguments to pass to selected calculator. Must
be passed as a dictionary wrapped in quotes, e.g.
"{'key' : value}". For the default architecture
('mace_mp'), "{'model':'small'}" is set unless
overwritten.
--write-kwargs DICT Keyword arguments to pass to ase.io.write when saving
results. Must be passed as a dictionary wrapped in
quotes, e.g. "{'key' : value}". [default: "{}"]
--log PATH Path to save logs to. Default is inferred from the name
of the structure file.
--summary PATH Path to save summary of inputs, start/end time, and
carbon emissions. Default is inferred from the name of
the structure file.
--config TEXT Configuration file.
--help Show this message and exit.Please see the user guide for examples of each subcommand.
Default values for all command line options may be specifed through a Yaml 1.1 formatted configuration file by adding the --config option. If an option is present in both the command line and configuration file, the command line value takes precedence.
For example, with the following configuration file and command:
struct: "NaCl.cif"
properties:
- "energy"
out: "NaCl-results.extxyz"
arch: mace_mp
model-path: medium
calc-kwargs:
dispersion: Truejanus singlepoint --struct KCl.cif --out KCl-results.cif --config config.ymlThis will run a singlepoint energy calculation on KCl.cif using the MACE-MP "medium" force-field, saving the results to KCl-results.cif.
Note
properties must be passed as a Yaml list, as above, not as a string.
Example configurations for all commands can be found in janus-tutorials
Calculations can also be run through the Python interface. For example, running:
from janus_core.calculations.single_point import SinglePoint
single_point = SinglePoint(
struct_path="tests/data/NaCl.cif",
arch="mace_mp",
model_path="tests/models/mace_mp_small.model",
)
results = single_point.run()
print(results)will read the NaCl structure file and attach the MACE-MP (medium) calculator, before calculating and printing the energy, forces, and stress.
Jupyter Notebook tutorials illustrating the use of currently available calculations can be found in the janus-tutorials repository. This currently includes examples for:
We recommend installing poetry for dependency management when developing for janus-core:
- Install poetry
- (Optional) Create a virtual environment
- Install
janus-corewith dependencies:
git clone https://github.com/stfc/janus-core
cd janus-core
python3 -m pip install --upgrade pip
poetry install --with pre-commit,dev,docs # install with useful dev dependencies
pre-commit install # install pre-commit hooks
pytest -v # discover and run all testsContributors to this project were funded by
