METATENSOR

	This is part of the metatensor module
	It is only available if you configure PLUMED with ./configure –enable-modules=metatensor . Furthermore, this feature is still being developed so take care when using it and report any problems on the mailing list.

Use arbitrary machine learning models as collective variables.

Note that this action requires the metatensor-torch library. Check the instructions in the Metatensor page to enable this module.

This action enables the use of fully custom machine learning models — based on the metatensor atomistic 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.

Metatensor 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, or at the code in regtest/metatensor/. 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 metatensor 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

SPECIES1=1-26  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES2=27-62  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES3=63-76  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES_TO_TYPES=6,1,8  You cannot view the components that are calculated by each action for this input file. Sorry 
@newline  You cannot view the components that are calculated by each action for this input file. Sorry 

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.

METATENSOR 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 MetatensorAtomisticModel.export in Python.
• CHECK_CONSISTENCY can be used to enable internal consistency checks;
• SELECTED_ATOMS can be used to signal the metatensor 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

CHECK_CONSISTENCY  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES1=1-10  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES2=11-20  You cannot view the components that are calculated by each action for this input file. Sorry 
SPECIES_TO_TYPES=8,13  You cannot view the components that are calculated by each action for this input file. Sorry 
# only run the calculation for the Aluminium (type 13) atoms, but
# include the Oxygen (type 8) as potential neighbors.
SELECTED_ATOMS=11-20  You cannot view the components that are calculated by each action for this input file. Sorry 
@newline  You cannot view the components that are calculated by each action for this input file. Sorry 

Collective variables and metatensor models

PLUMED can use the "features" output of metatensor atomistic models as a collective variables. Alternatively, the code also accepts an output named "plumed::cv", with the same metadata structure as the "features" output.

Glossary of keywords and components

Description of components

By default this Action calculates the following quantities. These quantities can be referenced elsewhere in the input by using this Action's label followed by a dot and the name of the quantity required from the list below.

Quantity	Description
outputs	collective variable created by the metatensor model
.#!value	collective variable created by the metatensor model

The atoms involved can be specified using

SPECIES	the atoms in each PLUMED species. You can use multiple instances of this keyword i.e. SPECIES1, SPECIES2, SPECIES3...
SELECTED_ATOMS	subset of atoms that should be used for the calculation

Compulsory keywords

MODEL

path to the exported metatensor model

Options

NUMERICAL_DERIVATIVES	( default=off ) calculate the derivatives for these quantities numerically
CHECK_CONSISTENCY	( default=off ) Should we enable internal consistency of the model
EXTENSIONS_DIRECTORY	path to the directory containing TorchScript extensions to load
DEVICE	Torch device to use for the calculation
SPECIES_TO_TYPES	mapping from PLUMED SPECIES to metatensor's atomic types