User-defined custom CV

It is easily possible to implement own collective variables into calculations done with the metafalcon package. You only need an additional .py file in your working directory that contains the two following functions:

def customcv(symbols, coords, prm):
    """
    Return value of user-defined CV for given symbols, coordinates and prm.

    Parameters
    ----------
    symbols : list of str
        atomic symbols of the molecule
    coords : numpy array
        coordinates of the molecule (shape: (N, 3))
    prm : dict
        parameters given in the CV section of meta-config.py

    Returns
    -------
    custom : number
        CV value

    Warning
    -------
    Do not modify function name, arguments or returns.

    """
    ### modify the following code
    custom = 0.0
    ### end modify
    return custom

def dcustomcv(symbols, coords, prm):
    """
    Return derivative of user_defined CV wrt coordinates for given symbols, coordinates and prm.

    Parameters
    ----------
    symbols : list of strings
        atomic symbols of the molecule
    coords : numpy array
        coordinates of the molecule (shape: (N, 3))
    prm : dict
        parameters given in the CV section of meta-config.py

    Returns
    -------
    dcustom : numpy array
        derivative of CV wrt coordinates (shape: (Nat, 3))

    Warning
    -------
    Do not modify function name, arguments or returns.

    """
    ### modify the following code
    dcustom = np.zeros_like(coords)
    ### end modify
    return dcustom

The first function is for calculating the value of the user-defined CV, the second one returns the gradient. The calculation of these quantities should be inserted into the marked areas in the above code. For the latter, the functions are called from the metadynamics program with the current symbols, coords and a dictionary prm that is provided by the user in the configuration file.

A blank “cvcustom.py” file containing the above functions will be copied to your working directory by running:

metafalcon --custom

The use of a user-defined CV is invoked by the following block in the meta-config.json file:

"collective variables": [
  {
    "type": "custom",
    "name": "user-defined cv",
    "parameters": {
      "key1": value1,
      "key2": value2,
      ...
    },
    "filename": "cvcustom"
  },
  ...
]

The prm dictionary contains all the (key, value) pairs from the "parameters" section, so in this case it would be:

prm = {"key1": value1,
       "key2": value2,
       ...}

If the two functions shown above are provided in a file named other than “cvcustom.py”, its filename (without .py) has to be specified with the "filename" keyword. This is useful when multiple user-defined CVs should be used at the same time.