.. index:: fix colvars

fix colvars command
===================

Syntax
""""""

.. code-block:: LAMMPS

   fix ID group-ID colvars configfile keyword values ...

* ID, group-ID are documented in :doc:`fix <fix>` command
* colvars = style name of this fix command
* configfile = the configuration file for the colvars module
* keyword = *input* or *output* or *seed* or *unwrap* or *tstat*

  .. parsed-literal::

       *input* arg = colvars.state file name or prefix or NULL (default: NULL)
       *output* arg = output filename prefix (default: out)
       *seed* arg = seed for random number generator (default: 1966)
       *unwrap* arg = *yes* or *no*
         use unwrapped coordinates in collective variables (default: yes)
       *tstat* arg = fix id of a thermostat or NULL (default: NULL)

Examples
""""""""

.. code-block:: LAMMPS

   fix mtd all colvars peptide.colvars.inp seed 2122 input peptide.colvars.state output peptide
   fix abf all colvars colvars.inp tstat 1

Description
"""""""""""

This fix interfaces LAMMPS to the collective variables (Colvars)
library, which allows to calculate potentials of mean force (PMFs) for
any set of colvars, using sampling methods, including but not limited to
Adaptive Biasing Force (ABF), metadynamics (MtD), Steered Molecular
Dynamics (SMD) and Umbrella Sampling (US) via a flexible harmonic
restraint bias.

This documentation describes only the ``fix colvars`` command itself in
a LAMMPS script.  The Colvars library is documented via the included
`PDF manual <PDF/colvars-refman-lammps.pdf>`_ or at the webpage
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html
<https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html>`_.

The Colvars library is developed at `https://github.com/Colvars/colvars
<https://github.com/Colvars/colvars>`_ A detailed discussion of its
implementation is in :ref:`(Fiorin) <Fiorin>`; additional references are
printed at runtime based on specific features being used.

There are some example scripts for using this package with LAMMPS in the
``examples/PACKAGES/colvars`` directory.

----------

The only required argument to ``fix colvars`` is the filename to the
Colvars configuration file that contains the definition of the variables
and any biasing methods applied to them.  from the MD program in which
the colvars library has been integrated.

The *group-ID* entry is ignored.  ``fix colvars`` will always apply to
the entire system, but specific atoms will be selected based on
selection keywords in the Colvars configuration file or files.  There is
no need to define multiple ``fix colvars`` instances and it is not
allowed.

The *output* keyword allows to specify the prefix of output files
generated by Colvars, for example ``output.colvars.traj`` or
``output.pmf``.

The *input* keyword allows to specify an optional state file that
contains the restart information needed to continue a previous
simulation state.  Note, however, that ``fix colvars`` records its state
in :doc:`binary restart <restart>` files, so when using the
:doc:`read_restart <read_restart>` command, this is usually not needed.

The *seed* keyword contains the seed for the random number generator
used by Colvars.

The *unwrap* keyword controls whether wrapped or unwrapped coordinates
are passed to the Colvars library for calculation of the collective
variables and the resulting forces. The default is *yes*, i.e. to use
the image flags to reconstruct the absolute atom positions.  Setting
this to *no* will use the current local coordinates that are wrapped
back into the simulation cell at each re-neighboring instead.  For
information about when and how this affects results, please see
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping
<https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping>`_.

The *tstat* keyword can be either NULL or the label of a thermostatting
fix that thermostats all atoms in the fix colvars group.  This will be
used to let Colvars know what is the current thermostat target
temperature.

Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This fix writes the current status of the colvars module into
:doc:`binary restart files <restart>`. This is in addition to the text
mode ``.colvars.state`` written by Colvars itself and the information in
both files is identical.

The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
fix to add the energy change from the biasing force added by Colvars to
the global potential energy of the system as part of :doc:`thermodynamic
output <thermo_style>`.  The default setting for this fix is
:doc:`fix_modify energy no <fix_modify>`.

The *fix_modify configfile <config file>* option loads Colvars
configuration from an additional file. This option can only be used,
after the system has been initialized with a :doc:`run <run>` command.

The *fix_modify config <quoted string>* option allows to add settings
from inline strings. Those have to fit on a single line when enclosed in
a pair of double quotes ("), or can span multiple lines when bracketed
by a pair of triple double quotes (""", like Python embedded
documentation).

This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`.  The scalar is the Colvars energy
mentioned above.  The scalar value calculated by this fix is
"extensive".

Restrictions
""""""""""""

``fix colvars`` is provided by the COLVARS package and is only available
if LAMMPS was built with that package.  Some of the features also
require code available from the LEPTON package.  See the :doc:`Build
package <Build_package>` page for more info.

There can only be one Colvars instance defined at a time.  Since the
interface communicates only the minimum amount of information and the
Colvars module itself can handle an arbitrary number of collective
variables, this is not a limitation of functionality.

Related commands
""""""""""""""""

:doc:`fix smd <fix_smd>`, :doc:`fix spring <fix_spring>`,
:doc:`fix plumed <fix_plumed>`

Default
"""""""

The default options are input = NULL, output = out, seed = 1966, unwrap yes,
and tstat = NULL.

----------

.. _Fiorin:

**(Fiorin)** Fiorin, Klein, Henin, Mol. Phys., DOI:10.1080/00268976.2013.813594
