Defining custom machine learning CV with metatomic

Metatomic is a library to use arbitrary machine learning models together with arbitrary simulation tools. Here we show how to use the interface between metatomic and plumed to define fully custom collective variables (CV). These CV can be defined using typical machine learning tools, but any Python function based on PyTorch will also work, allowing to define new CV extremely easily.

Through the use of PyTorch, you can focus on defining the CV itself, and automatically get its gradients. You can also execute the code computing your CV on GPUs and other accelerators.

Other tools are able to interact with CV defined as metatomic models, most notably chemiscope. You can therefore visualize how complex CV act on representative structures before even starting a simulation, and improve the Cv interactively.

Free-energy surface of LJ38 cluster

The cluster of 38 atoms interacting through a Lennard-Jones potential is an interesting benchmark system for collective variables, because its global minimum energy structure is a truncated octahedron with O_h symmetry. The potential energy surface also has a multi-funnel landscape, meaning the system can easily get trapped in other local minima.

This tutorial contains a hands-on interactive tutorial (that you can also download and run locally) that defines two different collective variables to drive metadynamics for this system. The first CV is based on the histogram of coordination number, and the second one uses a machine learning representation (the SOAP spherical expansion) as a basis to define Steinhardt oder parameters-like CVs.

Click on the labels of the actions for more information on what each action computes

soap: METATOMICUse arbitrary machine learning models as collective variables. More details ...
    MODELpath to the exported metatomic model=soap-cv.pt
    EXTENSIONS_DIRECTORYpath to the directory containing TorchScript extensions to load=./extensions/
    SPECIES1the indices of atoms in each PLUMED species=1-38
    SPECIES_TO_TYPESmapping from PLUMED SPECIES to metatomic's atom types=18
...

The METATOMIC action with label soap calculates the following quantities:
 Quantity   
 Description  
soap.outputs
collective variable created by the metatomic model
soap.value
collective variable created by the metatomic modelhistogram: METATOMICUse arbitrary machine learning models as collective variables. More details ...
    MODELpath to the exported metatomic model=histo-cv.pt

    SPECIES1the indices of atoms in each PLUMED species=1-38
    SPECIES_TO_TYPESmapping from PLUMED SPECIES to metatomic's atom types=18
...

The METATOMIC action with label histogram calculates the following quantities:
 Quantity   
 Description  
histogram.outputs
collective variable created by the metatomic model
histogram.value
collective variable created by the metatomic modelcv1: SELECT_COMPONENTSCreate a new value to hold a subset of the components that are in a vector or matrix More details ARGthe value from which we are selecting components=histogram COMPONENTSthe components in the input value that you woul like to build a new vector from=1
The SELECT_COMPONENTS action with label cv1 calculates the following quantities:
 Quantity   
 Description  
cv1.value
a vector containing the selected componentscv2: SELECT_COMPONENTSCreate a new value to hold a subset of the components that are in a vector or matrix More details ARGthe value from which we are selecting components=histogram COMPONENTSthe components in the input value that you woul like to build a new vector from=2

The SELECT_COMPONENTS action with label cv2 calculates the following quantities:
 Quantity   
 Description  
cv2.value
a vector containing the selected componentsmtd: METADUsed to performed metadynamics on one or more collective variables. More details ...
    ARGthe labels of the scalars on which the bias will act=cv1,cv2
    HEIGHTthe heights of the Gaussian hills=0.04
    PACEthe frequency for hill addition=30
    SIGMAthe widths of the Gaussian hills=1.0,0.5
    GRID_MINthe lower bounds for the grid=0,0
    GRID_MAXthe upper bounds for the grid=30,20
    GRID_BINthe number of bins for the grid=300,200
    BIASFACTORuse well tempered metadynamics and use this bias factor=40
    FILE a file in which the list of added hills is stored=HILLS
    TEMPthe system temperature - this is only needed if you are doing well-tempered metadynamics=19.3
...
The METAD action with label mtd calculates the following quantities:
 Quantity   
 Description  
mtd.bias
the instantaneous value of the bias potential

Depending on your previous experience, you may want to follow the lessons on metadynamics first.

flowchart TD
A[Basic plumed syntax] ==> B[Metadynamics]
B ==> C([Defining and using custom CVs with metatomic])
subgraph D[Reference documentation]
    E[LAMMPS]
    F[i-PI]
    G[metatomic]
end
D -..-> C


click A "../../../21/001/data/NAVIGATION.html" "Follow this lecture for an introduction to PLUMED and enhanced sampling"
click B "../../../21/004/data/NAVIGATION.html" "Follow this lecture if you have never heard of metadynamics before"
click C "https://atomistic-cookbook.org/examples/metatomic-plumed/metatomic-plumed.html" "An interactive tutorial defining custom CV with metatomic and using them to run metadynamics in both i-PI and LAMMPS"
click E "https://docs.lammps.org/fix_plumed.html" "More information about the interface between LAMMPS and PLUMED"
click F "https://docs.ipi-code.org/input-tags.html#ffplumed" "More information about the interface between i-PI and PLUMED"
click G "https://docs.metatensor.org/metatomic/" "More information about metatomic"

Click here to open manual pages for actions discussed in this tutorial.