.. index:: fix amoeba/bitorsion

fix amoeba/bitorsion command
============================

Syntax
""""""

.. code-block:: LAMMPS

   fix ID group-ID ameoba/bitorsion filename

* ID, group-ID are documented in :doc:`fix <fix>` command
* amoeba/bitorsion = style name of this fix command
* filename = force-field file with AMOEBA bitorsion coefficients

Examples
""""""""

.. code-block:: LAMMPS

   fix            bit all amoeba/bitorsion bitorsion.ubiquitin.data
   read_data      proteinX.data fix bit bitorsions BiTorsions
   fix_modify     bit energy yes

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

This command enables 5-body torsion/torsion interactions to be added
to simulations which use the AMOEBA and HIPPO force fields.  It
matches how the Tinker MD code computes its torsion/torsion
interactions for the AMOEBA and HIPPO force fields.  See the
:doc:`Howto amoeba <Howto_amoeba>` doc page for more information about
the implementation of AMOEBA and HIPPO in LAMMPS.

Bitorsion interactions add additional potential energy contributions
to pairs of overlapping phi-psi dihedrals of amino-acids, which are
important to properly represent their conformational behavior.  Each
bitorsion interaction is thus defined for a 5-tuple of atoms
:math:`IJKLM` with bonds between successive atoms in the list,
i.e. two overlapping dihedral interactions for atoms :math:`IJKL` and
:math:`JKLM`.

The examples/amoeba directory has a sample input script and data file
for ubiquitin, which illustrates use of the fix amoeba/bitorsion
command.

As in the example above, this fix should be used before reading a data
file that contains a listing of bitorsion interactions.  The
*filename* specified should contain the bitorsion parameters for the
AMOEBA or HIPPO force field.

The data file read by the :doc:`read_data <read_data>` command must
contain the topology of all the bitorsion interactions, similar to the
topology data for bonds, angles, dihedrals, etc.  Specifically it
should have a line like this in its header section:

.. parsed-literal::

   N bitorsions

where :math:`N` is the number of bitorsion 5-body interactions.  It should
also have a section in the body of the data file like this with :math:`N`
lines:

.. parsed-literal::

   BiTorsions

          1       1       8      10      12      18      20
          2       5      18      20      22      25      27
          [...]
          N       3     314     315     317      318    330

The first column is an index from 1 to :math:`N` to enumerate the
bitorsion 5-atom tuples; it is ignored by LAMMPS.  The second column
is the *type* of the interaction; it is an index into the bitorsion
force field file.  The remaining 5 columns are the atom IDs of the
atoms (in order) for the 5-tuple :math:`IJKLM`, as described above.

Note that the *bitorsions* and *BiTorsions* keywords for the header
and body sections match those specified in the :doc:`read_data
<read_data>` command following the data file name.

The data file should be generated by using the
tools/tinker/tinker2lmp.py conversion script which creates a LAMMPS
data file from Tinker input files, including its PRM file which
contains the parameters necessary for computing bitorsion
interactions.  The script must be invoked with the optional
"-bitorsion" flag to do this; see the example for the ubiquitin system
in the tools/tinker/README file.  The same conversion script also
creates the file of bitorsion coefficient data which is read by this
command.

The potential energy associated with bitorsion interactions can be
output as described below.  It can also be included in the total
potential energy of the system, as output by the :doc:`thermo_style
<thermo_style>` command, if the :doc:`fix_modify energy <fix_modify>`
command is used, as in the example above.  See the note below about
how to include the bitorsion energy when performing an :doc:`energy
minimization <minimize>`.

----------

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

This fix writes the list of bitorsion interactions to :doc:`binary
restart files <restart>`.  See the :doc:`read_restart <read_restart>`
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.

The :doc:`fix_modify <fix_modify>` *energy* option is supported by
this fix to add the potential energy of the bitorsion interactions to
both the global potential energy and peratom potential energies of the
system as part of :doc:`thermodynamic output <thermo_style>` or output
by the :doc:`compute pe/atom <compute_pe_atom>` command.  The default
setting for this fix is :doc:`fix_modify energy yes <fix_modify>`.

The :doc:`fix_modify <fix_modify>` *virial* option is supported by
this fix to add the contribution due to the bitorsion interactions to
both the global pressure and per-atom stress of the system via the
:doc:`compute pressure <compute_pressure>` and :doc:`compute
stress/atom <compute_stress_atom>` commands.  The former can be
accessed by :doc:`thermodynamic output <thermo_style>`.  The default
setting for this fix is :doc:`fix_modify virial yes <fix_modify>`.

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

No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.

The forces due to this fix are imposed during an energy minimization,
invoked by the :doc:`minimize <minimize>` command.

The :doc:`fix_modify <fix_modify>` *respa* option is supported by this
fix. This allows to set at which level of the :doc:`r-RESPA
<run_style>` integrator the fix is adding its forces. Default is the
outermost level.

.. note::

   For energy minimization, if you want the potential energy
   associated with the bitorsion terms forces to be included in the
   total potential energy of the system (the quantity being
   minimized), you MUST not disable the :doc:`fix_modify <fix_modify>`
   *energy* option for this fix.

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

To function as expected this fix command must be issued *before* a
:doc:`read_data <read_data>` command but *after* a :doc:`read_restart
<read_restart>` command.

This fix can only be used if LAMMPS was built with the AMOEBA package.
See the :doc:`Build package <Build_package>` page for more info.

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

:doc:`fix_modify <fix_modify>`, :doc:`read_data <read_data>`

Default
"""""""

none
