Definition of custom collective variables
=========================================

Apart from the :doc:`../cvs/cvs` already implemented in the :mod:`metafalcon` package, it is
possible to define own variables to be used as metadynamics CVs. For each new CV, it is necessary to
provide a file that contains two functions, :func:`customcv() <metafalcon.cvcustom.customcv>` for 
the calculation of the variable values from the current coordinates and :func:`dcustomcv() 
<metafalcon.cvcustom.dcustomcv>` for the calculation of its gradient. In order to copy a template
`cvcustom.py` for the definition of these two functions into your working directory, run::

    metaFALCON custom

It is important that function names, arguments and returns are not modified. Modifications should
only occur in the designated places in :func:`customcv() <metafalcon.cvcustom.customcv>`::

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

and in :func:`dcustomcv() <metafalcon.cvcustom.dcustomcv>`::
    
    ### modify the following code
    dcustom = np.zeros_like(coords)
    ### end modify

However, you can create help functions or import other modules within the :mod:`cvcustom
<metafalcon.cvcustom>` module without any problems. Additional parameters needed for the
calculation can be provided in `meta-config.json` using the ``"parameters"`` keyword::

    {
      "name": "user-defined variable",
      "type": "custom",
      "filename": "cvcustom",
      "width": 1.0,
      "parameters": {
        "key1": value1,
        "key2": value2,
        ...
      }

The dictionary that contains ``"key1"`` and ``"key2"`` is given to :func:`customcv()
<metafalcon.cvcustom.customcv>` and :func:`dcustomcv() <metafalcon.cvcustom.dcustomcv>` through the
``prm`` argument. The ``"filename"`` keyword is optional and only needed, if files other than
`cvcustom.py` are used, for example because multiple user-defined variables are used in the same
simulation.

In the :mod:`metafalcon` package, lengths and energies are internally handled in atomic units. If
a different unit of the variable should be used in the user input and output (e.g. the Gaussian
width given in the `meta-config.json` file), a conversion factor is needed. Edit the line 

::

    au2unit = 1.0

so that ``au2unit`` by multiplication converts atomic units into the unit of your variable. For
example, if you define a bond length in Angstrom, use::

    au2unit = 0.529

.. seealso::
    Further information on user-defined CVs is found :doc:`here <../cvs/custom>`.