Skip to content

Action: METATOMIC

Module metatomic
Description Usage
Use arbitrary machine learning models as collective variables. used in 1 tutorialsused in 0 eggs
output value type
collective variable created by the metatomic model scalar/vector/matrix

Details and examples

Use arbitrary machine learning models as collective variables.

Note

This action requires libmetatomic to be enabled and found. Check the instructions in the module page for more information on how to enable this module.

This action enables the use of fully custom machine learning models — based on the [metatomic] models interface — as collective variables in PLUMED. Such machine learning model are typically written and customized using Python code, and then exported to run within PLUMED as [TorchScript], which is a subset of Python that can be executed by the C++ torch library.

Metatomic offers a way to define such models and pass data from PLUMED (or any other simulation engine) to the model and back. For more information on how to define such model, have a look at the [corresponding tutorials][mta_tutorials], or at the code in regtest/metatomic/. Each of the Python scripts in this directory defines a custom machine learning CV that can be used with PLUMED.

Examples

The following input shows how you can call metatomic and evaluate the model that is described in the file custom_cv.pt from PLUMED.

Click on the labels of the actions for more information on what each action computes
tested on2.11
metatomic_cv: METATOMICUse arbitrary machine learning models as collective variables. More details ...
    MODELpath to the exported metatomic model=custom_cv.pt

    SPECIES1the indices of atoms in each PLUMED species=1-26
    SPECIES2the indices of atoms in each PLUMED species=27-62
    SPECIES3the indices of atoms in each PLUMED species=63-76
    SPECIES_TO_TYPESmapping from PLUMED SPECIES to metatomic's atom types=6,1,8
...

The numbered SPECIES labels are used to indicate the list of atoms that belong to each atomic species in the system. The SPECIES_TO_TYPE keyword then provides information on the atom type for each species. The first number here is the atomic type of the atoms that have been specified using the SPECIES1 flag, the second number is the atomic number of the atoms that have been specified using the SPECIES2 flag and so on.

METATOMIC action also accepts the following options:

  • EXTENSIONS_DIRECTORY should be the path to a directory containing TorchScript extensions (as shared libraries) that are required to load and execute the model. This matches the collect_extensions argument to AtomisticModel.export in Python.
  • CHECK_CONSISTENCY can be used to enable internal consistency checks;
  • SELECTED_ATOMS can be used to signal the metatomic models that it should only run its calculation for the selected subset of atoms. The model still need to know about all the atoms in the system (through the SPECIES keyword); but this can be used to reduce the calculation cost. Note that the indices of the selected atoms should start at 1 in the PLUMED input file, but they will be translated to start at 0 when given to the model (i.e. in Python/TorchScript, the forward method will receive a selected_atoms which starts at 0)

Here is another example with all the possible keywords:

Click on the labels of the actions for more information on what each action computes
tested on2.11
soap: METATOMICUse arbitrary machine learning models as collective variables. More details ...
    MODELpath to the exported metatomic model=path/to/model.pt
    EXTENSIONS_DIRECTORYpath to the directory containing TorchScript extensions to load=path/to/extensions/
    DEVICETorch device to use for the calculations=cuda
    CHECK_CONSISTENCY should we enable internal consistency checks when executing the model

    SPECIES1the indices of atoms in each PLUMED species=1-10
    SPECIES2the indices of atoms in each PLUMED species=11-20
    SPECIES_TO_TYPESmapping from PLUMED SPECIES to metatomic's atom types=8,13

    # only run the calculation for the Aluminium (type 13) atoms,
    # still including all other atoms as potential neighbors.
    SELECTED_ATOMSsubset of atoms that should be used for the calculation=11-20
...

[TorchScript]: https://pytorch.org/docs/stable/jit.html [metatomic]: https://docs.metatensor.org/metatomic/ [mta_tutorials]: https://docs.metatensor.org/metatomic/latest/examples/ [features_output]: https://docs.metatensor.org/metatomic/latest/outputs/features.html

Input

The atoms that serve as the input for this action are specified using one or more of the keywords in the following table.

Keyword Type Description
SPECIES atoms the indices of atoms in each PLUMED species
SELECTED_ATOMS atoms subset of atoms that should be used for the calculation

Output components

This action calculates the values in the following table. These values can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the value required from the list below.

Name Type Description
outputs scalar/vector/matrix collective variable created by the metatomic model

Full list of keywords

The following table describes the keywords and options that can be used with this action

Keyword Type Default Description
SPECIES input none the indices of atoms in each PLUMED species
SELECTED_ATOMS input none subset of atoms that should be used for the calculation
MODEL compulsory none path to the exported metatomic model
NUMERICAL_DERIVATIVESThis keyword do not have examples optional false calculate the derivatives for these quantities numerically
EXTENSIONS_DIRECTORY optional not used path to the directory containing TorchScript extensions to load
DEVICE optional not used Torch device to use for the calculations
CHECK_CONSISTENCY optional false should we enable internal consistency checks when executing the model
SPECIES_TO_TYPES optional not used mapping from PLUMED SPECIES to metatomic's atom types