|
|
|
|
@ -46,25 +46,26 @@ Description
|
|
|
|
|
"""""""""""
|
|
|
|
|
|
|
|
|
|
This fix interfaces LAMMPS to the collective variables `Colvars
|
|
|
|
|
<https://colvars.github.io>`_ library, which allows to accelerate sampling of
|
|
|
|
|
rare events and the computation of free energy surfaces and potentials of
|
|
|
|
|
mean force (PMFs) for any set of collective variables using a variety of
|
|
|
|
|
sampling methods (e.g. umbrella-sampling, metadynamics, ABF...).
|
|
|
|
|
<https://colvars.github.io>`_ library, which allows to accelerate
|
|
|
|
|
sampling of rare events and the computation of freeenergy surfaces and
|
|
|
|
|
potentials of mean force (PMFs) for any set of collective variables
|
|
|
|
|
using a variety of sampling methods (e.g. umbrella-sampling,
|
|
|
|
|
metadynamics, ABF...).
|
|
|
|
|
|
|
|
|
|
This documentation describes only the "fix colvars" command itself in
|
|
|
|
|
a LAMMPS script. The Colvars library is fully documented in the included
|
|
|
|
|
This documentation describes only the "fix colvars" command itself in a
|
|
|
|
|
LAMMPS script. The Colvars library is fully documented in the included
|
|
|
|
|
`PDF manual <PDF/colvars-refman-lammps.pdf>`_ or in 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
|
|
|
|
|
<https://github.com/colvars/colvars>`_. A detailed discussion of its
|
|
|
|
|
implementation is in :ref:`(Fiorin) <Fiorin>`; additional citations for
|
|
|
|
|
specific features are printed at runtime if these features are used.
|
|
|
|
|
|
|
|
|
|
There are example scripts on the `Colvars website <https://colvars.github.io>`_
|
|
|
|
|
as well as in the ``examples/PACKAGES/colvars`` directory in the LAMMPS
|
|
|
|
|
source tree.
|
|
|
|
|
There are example scripts on the `Colvars website
|
|
|
|
|
<https://colvars.github.io>`_ as well as in the
|
|
|
|
|
``examples/PACKAGES/colvars`` directory in the LAMMPS source tree.
|
|
|
|
|
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
@ -75,42 +76,44 @@ units that are specific to each engine. In LAMMPS, the units used by
|
|
|
|
|
Colvars are consistent with those specified by the :doc:`units <units>`
|
|
|
|
|
command.
|
|
|
|
|
|
|
|
|
|
.. versionadded:: Colvars_2023-06-04 The special value "*none*"
|
|
|
|
|
(lowercase) initializes an empty Colvars module, which
|
|
|
|
|
allows loading configuration dynamically using
|
|
|
|
|
.. versionadded:: Colvars_2023-06-04
|
|
|
|
|
|
|
|
|
|
The special value "*none*" (lowercase) initializes an empty Colvars
|
|
|
|
|
module, which allows loading configuration dynamically using
|
|
|
|
|
:doc:`fix_modify <fix_modify>` (see below).
|
|
|
|
|
|
|
|
|
|
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 *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". Supplying
|
|
|
|
|
an empty string suppresses any file output from Colvars to file, except for
|
|
|
|
|
data saved into the LAMMPS :doc:`binary restart <restart>` files.
|
|
|
|
|
The "output" keyword allows to specify the prefix of output files
|
|
|
|
|
generated by Colvars, for example "*output*.colvars.traj" or
|
|
|
|
|
"output.pmf". Supplying an empty string suppresses any file output from
|
|
|
|
|
Colvars to file, except for data saved into the LAMMPS :doc:`binary
|
|
|
|
|
restart <restart>` files.
|
|
|
|
|
|
|
|
|
|
The "input" keyword allows to specify an optional state file that contains
|
|
|
|
|
the restart information needed to continue a previous simulation state.
|
|
|
|
|
However, because "fix colvars" records its state in LAMMPS :doc:`binary
|
|
|
|
|
restart <restart>` files, this is usually not needed when using the
|
|
|
|
|
:doc:`read_restart <read_restart>` command.
|
|
|
|
|
The "input" keyword allows to specify an optional state file that
|
|
|
|
|
contains the restart information needed to continue a previous
|
|
|
|
|
simulation state. However, because "fix colvars" records its state in
|
|
|
|
|
LAMMPS :doc:`binary restart <restart>` files, this is usually not needed
|
|
|
|
|
when using the :doc:`read_restart <read_restart>` command.
|
|
|
|
|
|
|
|
|
|
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. the image flags are used 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 step instead. For information about when and how this
|
|
|
|
|
affects results, please see
|
|
|
|
|
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. the
|
|
|
|
|
image flags are used 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 step
|
|
|
|
|
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 provide the colvars module with the current thermostat target
|
|
|
|
|
temperature.
|
|
|
|
|
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 provide the colvars module with the current
|
|
|
|
|
thermostat target temperature.
|
|
|
|
|
|
|
|
|
|
The *seed* keyword contains the seed for the random number generator
|
|
|
|
|
that will be used in the colvars module.
|
|
|
|
|
@ -119,36 +122,38 @@ that will be used in the colvars module.
|
|
|
|
|
Restarting
|
|
|
|
|
""""""""""
|
|
|
|
|
|
|
|
|
|
This fix writes the current state of the Colvars module into :doc:`binary
|
|
|
|
|
restart files <restart>`. This is in addition to the text-mode
|
|
|
|
|
".colvars.state" state file that is written by the Colvars module itself.
|
|
|
|
|
The information contained in both files is identical, and the binary LAMMPS
|
|
|
|
|
restart file is also used by fix colvars when :doc:`read_restart
|
|
|
|
|
<read_restart>` is called in a LAMMPS script. In that case, there is
|
|
|
|
|
typically no need to specify the *input* keyword.
|
|
|
|
|
This fix writes the current state of the Colvars module into
|
|
|
|
|
:doc:`binary restart files <restart>`. This is in addition to the
|
|
|
|
|
text-mode ".colvars.state" state file that is written by the Colvars
|
|
|
|
|
module itself. The information contained in both files is identical,
|
|
|
|
|
and the binary LAMMPS restart file is also used by fix colvars when
|
|
|
|
|
:doc:`read_restart <read_restart>` is called in a LAMMPS script. In
|
|
|
|
|
that case, there is typically no need to specify the *input* keyword.
|
|
|
|
|
|
|
|
|
|
As long as LAMMPS binary restarts will be used to continue a simulation, it
|
|
|
|
|
is safe to delete the ".colvars.state" files to save space. However, when a
|
|
|
|
|
LAMMPS simulation is restarted using :doc:`read_data <read_data>`, the
|
|
|
|
|
Colvars state file must be available and loaded via the "input" keyword or
|
|
|
|
|
via a "fix_modify Colvars load" command (see below).
|
|
|
|
|
As long as LAMMPS binary restarts will be used to continue a simulation,
|
|
|
|
|
it is safe to delete the ".colvars.state" files to save space. However,
|
|
|
|
|
when a LAMMPS simulation is restarted using :doc:`read_data
|
|
|
|
|
<read_data>`, the Colvars state file must be available and loaded via
|
|
|
|
|
the "input" keyword or via a "fix_modify Colvars load" command (see
|
|
|
|
|
below).
|
|
|
|
|
|
|
|
|
|
When restarting, the fix and the Colvars module should be created and
|
|
|
|
|
configured using either the original configuration file(s).
|
|
|
|
|
configured using the original configuration file(s).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Output
|
|
|
|
|
""""""
|
|
|
|
|
|
|
|
|
|
This fix computes a global scalar which can be accessed by various
|
|
|
|
|
:doc:`output commands <Howto_output>`. The scalar is the energy due to all
|
|
|
|
|
external potentials defined in the Colvars configuration. The scalar value
|
|
|
|
|
calculated by this fix is "extensive".
|
|
|
|
|
:doc:`output commands <Howto_output>`. The scalar is the energy due to
|
|
|
|
|
all external potentials defined in the Colvars configuration. The
|
|
|
|
|
scalar value calculated by this fix is "extensive".
|
|
|
|
|
|
|
|
|
|
Aside from the state information in a ".colvars.state" file, other
|
|
|
|
|
`output files <https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvars_output>`_
|
|
|
|
|
are produced by Colvars depending on the type of simulation.
|
|
|
|
|
For this reason, the "output" keyword is required for fix colvars.
|
|
|
|
|
`output files
|
|
|
|
|
<https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvars_output>`_
|
|
|
|
|
are produced by Colvars depending on the type of simulation. For this
|
|
|
|
|
reason, the "output" keyword is required for fix colvars.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Controlling Colvars via `fix_modify`
|
|
|
|
|
@ -156,18 +161,18 @@ Controlling Colvars via `fix_modify`
|
|
|
|
|
|
|
|
|
|
.. versionadded:: Colvars_2023-06-04
|
|
|
|
|
|
|
|
|
|
The :doc:`fix_modify <fix_modify>` command may be used on "fix colvars" in
|
|
|
|
|
either one of two ways:
|
|
|
|
|
The :doc:`fix_modify <fix_modify>` command may be used on "fix colvars"
|
|
|
|
|
in either one of two ways:
|
|
|
|
|
|
|
|
|
|
(1) Provide updated values for the fix parameters, such as *output*, *input*,
|
|
|
|
|
*unwrap*, *tstat* and *seed*. Additionally, the :doc:`fix_modify
|
|
|
|
|
<fix_modify>` *energy* keyword 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 is :doc:`fix_modify energy no <fix_modify>`).
|
|
|
|
|
For example, in a multi-step LAMMPS script involving multiple thermostats
|
|
|
|
|
(e.g. fix nvt followed by fix npt), Colvars can read a new thermostat's
|
|
|
|
|
target temperature like this:
|
|
|
|
|
(1) Provide updated values for the fix parameters, such as *output*,
|
|
|
|
|
*input*, *unwrap*, *tstat* and *seed*. Additionally, the
|
|
|
|
|
:doc:`fix_modify <fix_modify>` *energy* keyword 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 is :doc:`fix_modify energy no
|
|
|
|
|
<fix_modify>`). For example, in a multi-step LAMMPS script involving
|
|
|
|
|
multiple thermostats (e.g. fix nvt followed by fix npt), Colvars can
|
|
|
|
|
read a new thermostat's target temperature like this:
|
|
|
|
|
|
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
|
|
|
|
|
|
@ -186,10 +191,11 @@ either one of two ways:
|
|
|
|
|
|
|
|
|
|
LAMMPS variables referenced by their string representation
|
|
|
|
|
"${variable}" will be expanded immediately. Note also that this
|
|
|
|
|
variable expansion *will also happen within quotes*, similar to what the
|
|
|
|
|
:doc:`mdi <mdi>` command provides. This feature makes it possible to use
|
|
|
|
|
the values of certain LAMMPS variables in Colvars configuration strings.
|
|
|
|
|
For example, to synchronize the LAMMPS and Colvars dump frequencies:
|
|
|
|
|
variable expansion *will also happen within quotes*, similar to what
|
|
|
|
|
the :doc:`mdi <mdi>` command provides. This feature makes it
|
|
|
|
|
possible to use the values of certain LAMMPS variables in Colvars
|
|
|
|
|
configuration strings. For example, to synchronize the LAMMPS and
|
|
|
|
|
Colvars dump frequencies:
|
|
|
|
|
|
|
|
|
|
.. code-block:: LAMMPS
|
|
|
|
|
|
|
|
|
|
@ -199,27 +205,27 @@ either one of two ways:
|
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
|
|
Although it is possible to use :doc:`fix_modify <fix_modify>` at any time,
|
|
|
|
|
its results will only reflect the state of the Colvars module at the end
|
|
|
|
|
of the most recent "run" or "minimize" command. Any new configuration
|
|
|
|
|
added via "fix_modify Colvars configfile" or "fix_modify Colvars config"
|
|
|
|
|
will only be loaded when the simulation resumes. Configuration files or
|
|
|
|
|
strings will be parsed in the same sequence as they were provided in the
|
|
|
|
|
LAMMPS script.
|
|
|
|
|
Although it is possible to use :doc:`fix_modify <fix_modify>` at any
|
|
|
|
|
time, its results will only reflect the state of the Colvars module
|
|
|
|
|
at the end of the most recent "run" or "minimize" command. Any new
|
|
|
|
|
configuration added via "fix_modify Colvars configfile" or
|
|
|
|
|
"fix_modify Colvars config" will only be loaded when the simulation
|
|
|
|
|
resumes. Configuration files or strings will be parsed in the same
|
|
|
|
|
sequence as they were provided in the LAMMPS script.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Restrictions
|
|
|
|
|
""""""""""""
|
|
|
|
|
|
|
|
|
|
This fix is provided by the COLVARS package and is only available if LAMMPS
|
|
|
|
|
was built with that package (default in most builds). Some of the features
|
|
|
|
|
also require code available from the LEPTON package. See the :doc:`Build
|
|
|
|
|
package <Build_package>` page for more info.
|
|
|
|
|
This fix is provided by the COLVARS package and is only available if
|
|
|
|
|
LAMMPS was built with that package (default in most builds). 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 required amount of information, and
|
|
|
|
|
the Colvars module itself can handle an arbitrary number of collective
|
|
|
|
|
variables, this is not a limitation of functionality.
|
|
|
|
|
interface communicates only the minimum required 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
|
|
|
|
|
|
Axel Kohlmeyer