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.