Coordination number
===================

The coordination number of an atom :math:`i` with respect to a set of reference atoms \
:math:`k,l,m,...` is defined as

.. math::
    \mathrm{CN} = \sum_{j=k,l,m,...} \frac{(1-r_{ij}/d)^n}{(1-r_{ij}/d)^m},

with the exponents :math:`m>n`. If only a single bond is taken into account, :math:`\mathrm{CN}` \
takes values close to 1, if :math:`r_{ij}<d` and gets approximately zero, if :math:`r_{ij}>>d`. \
The threshold :math:`d` therefore is a constant that can be diferent for every pair of atoms.

The use of the coordination number is invoked by the following block in the `meta-config.json` \
file::

    "collective variables": [
      {
        "type": "bond",
        "name": "bond length between two atoms",
        "atom": i,
        "reference": [k, l, m, ...],
        "n": 6,
        "m": 12,
        "d": "auto"
      },
      ...
    ]

If ``"d": "auto"``, the distance thresholds are determined for each pair of atoms as the sum of \
their covalent radii. Other possibilities are to provide a single float number ``"d": d_0`` that \
is used for all pairs or a list of floats corresponding to all pairs of atom :math:`i` and \
reference atoms :math:`k,l,m,...` ``"d": [d_ik, d_il, d_im, ...]``.

The choice of parameters can be checked by running the :func:`check_cn_parameters()
<metafalcon.cvs.cvfunctions.check_cn_parameters>` function from the :mod:`metafalcon.cvs.cvfunctions`
module::

    from metafalcon.cvs.cvfunctions import check_cn_parameters

    check_cn_parameters(n=6, m=12, d=1.0)

A file `cv_parameters.png` will be saved that looks like the following and allows for the critical \
evaluation of the parameters.

.. figure:: cn_parameters.png