Multistate metadynamics
=======================

The core functionality of the :mod:`metafalcon` package is the multistate metadynamics implementation
(J. O. Lindner, M. I. S. Röhr, R. Mitrić, Phys. Rev. A **97** (5), *052502* (2018)). In this method,
the electronic Born-Oppenheimer two-state Hamiltonian :math:`\bm{H_{BO}}` is extended by an
off-diagonal potential :math:`V_{ge}` that is determined by an instance of the metadynamics method
and is therefore dependent on a set of collective variables (CVs).

.. math::
    
    \bm{H_{BO}}=
    \begin{pmatrix}
    E_g    & V_{ge} \\
    V_{ge} & E_e
    \end{pmatrix}
    \rightarrow
    \bm{H_{meta}}=
    \begin{pmatrix}
    E_g' & 0    \\
    0    & E_e'
    \end{pmatrix}

Diagonalization yields the effective energy gap

.. math::
   
    \Delta E_{meta} = E_e' - E_g' = \sqrt{(E_g - E_e)^2 + 4V_{ge}^2}

which is used as a CV for the multistate metadynamics run.

In order to set up the simulation, run the GUI application and check the `Do multistate
metadynamics` option in the metadynamics tab.

.. figure:: gui_multistate.png

The forms below that checkbox refer to the construction of :math:`V_G`, while the `Gaussian height`
in the upper part of the window is used for the Gaussians added to :math:`V_{ge}`. :math:`\epsilon` is
the threshold that is used for the :math:`\Theta`-function to switch between :math:`V_G` and
:math:`V_{ge}`.

The `Collective Variables` tab also refers to the metadynamics in :math:`V_{ge}`. Since the torsion
angle used in the :doc:`previous example <simplemeta>` is an appropriate choice for the multistate
metadynamics, we don't make any changes in this tab.

Run the simulation::

    metaFALCON run

During the simulation, two files `deltaE_meta.dat` and `deltaE_BO.dat` are written that contain the
energy gaps :math:`\Delta E_{meta}` and :math:`\Delta E_{BO}`.

The offdiagonal potential :math:`V_{ge}` is handled just as a normal metadynamics instance, so the
input information about the latter is stored in another section of the `meta-config.json` file. It
is distinguished from the main metadynamics instance with the extension `_multistate`::

    {
      ...
      "metadynamics_multistate": {
        "collective variables": [...],
        "tau_g": ...,
        ...
      },
      ...
    }

This extension is needed later when referring to the multistate instance again, for example when
reconstructing :math:`V_{ge}`::

    metaFALCON reconstruct --extension multistate