Merge branch 'fix-tester' into progguide

    OUTPUT requirements.txt

    OUTPUT requirements.txt

    DEPENDS docenv

    DEPENDS docenv

    COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt

    COMMAND ${CMAKE_COMMAND} -E copy ${LAMMPS_DOC_DIR}/utils/requirements.txt requirements.txt

    COMMAND ${DOCENV_BINARY_DIR}/pip install -r requirements.txt --upgrade

    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters

    COMMAND ${DOCENV_BINARY_DIR}/pip install --upgrade ${LAMMPS_DOC_DIR}/utils/converters

    COMMAND ${DOCENV_BINARY_DIR}/pip install --use-feature=2020-resolver -r requirements.txt --upgrade

  )

  )

  # download mathjax distribution and unpack to folder "mathjax"

  # download mathjax distribution and unpack to folder "mathjax"

		$(VIRTUALENV) -p $(PYTHON) $(VENV); \

		$(VIRTUALENV) -p $(PYTHON) $(VENV); \

		. $(VENV)/bin/activate; \

		. $(VENV)/bin/activate; \

		pip install --upgrade pip; \

		pip install --upgrade pip; \

		pip install -r requirements.txt; \

		pip install --use-feature=2020-resolver -r requirements.txt; \

		deactivate;\

		deactivate;\

	)

	)

with many comparisons to reference results based on template input

with many comparisons to reference results based on template input

files, individual command settings, relative error margins, and

files, individual command settings, relative error margins, and

reference data stored in a YAML format file with ``.yaml``

reference data stored in a YAML format file with ``.yaml``

suffix. Currently the programs ``pair_style``, ``bond_style``, and

suffix. Currently the programs ``test_pair_style``, ``test_bond_style``, and

``angle_style`` are implemented.  They will compare forces, energies and

``test_angle_style`` are implemented.  They will compare forces, energies and

(global) stress for all atoms after a ``run 0`` calculation and after a

(global) stress for all atoms after a ``run 0`` calculation and after a

few steps of MD with :doc:`fix nve <fix_nve>`, each in multiple variants

few steps of MD with :doc:`fix nve <fix_nve>`, each in multiple variants

with different settings and also for multiple accelerated styles. If a

with different settings and also for multiple accelerated styles. If a

.. parsed-literal::

.. parsed-literal::

   [tests]$ pair_style mol-pair-lj_cut.yaml

   [tests]$ test_pair_style mol-pair-lj_cut.yaml

   [==========] Running 6 tests from 1 test suite.

   [==========] Running 6 tests from 1 test suite.

   [----------] Global test environment set-up.

   [----------] Global test environment set-up.

   [----------] 6 tests from PairStyle

   [----------] 6 tests from PairStyle

     of mis-compiled code (or an undesired large loss of precision due

     of mis-compiled code (or an undesired large loss of precision due

     to significant reordering of operations and thus less error cancellation).

     to significant reordering of operations and thus less error cancellation).

Unit tests for timestepping related fixes

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A substantial subset of :doc:`fix styles <fix>` are invoked regularly

during MD timestepping and manipulate per-atom properties like

positions, velocities, and forces.  For those fix styles, testing can be

done in a very similar fashion as for force fields and thus there is a

test program `test_fix_timestep` that shares a lot of code, properties,

and command line flags with the force field style testers described in

the previous section.

This tester will set up a small molecular system run with verlet run

style for 4 MD steps, then write a binary restart and continue for

another 4 MD steps. At this point coordinates and velocities are

recorded and compared to reference data. Then the system is cleared,

restarted and running the second 4 MD steps again and the data is

compared to the same reference. That is followed by another restart

after which per atom type masses are replaced with per-atom masses and

the second 4 MD steps are repeated again and compared to the same

reference.  Also global scalar and vector data of the fix is recorded

and compared.  If the fix is a thermostat and thus the internal property

``t_target`` can be extracted, then this is compared to the reference

data.  The tests are repeated with the respa run style.

If the fix has a multi-threaded version in the USER-OMP package, then

the entire set of tests is repeated for that version as well.

For this to work, some additional conditions have to be met by the

YAML format test inputs.

- The fix to be tested (and only this fix), should be listed in the

  ``prerequisites:`` section

- The fix to be tested must be specified in the ``post_commands:``

  section with the fix-ID ``test``.  This section may contain other

  commands and other fixes (e.g. an instance of fix nve for testing

  a thermostat or force manipulation fix)

- For fixes that can tally contributions to the global virial, the

  line ``fix_modify test virial yes`` should be included in the

  ``post_commands:`` section of the test input.

- For thermostat fixes the target temperature should be ramped from

  an arbitrary value (e.g. 50K) to a pre-defined target temperature

  entered as ``${t_target}``.

- For fixes that have thermostatting support included, but do not

  have it enabled in the input (e.g. fix rigid with default settings),

  the ``post_commands:`` section should contain the line

  ``variable t_target delete`` to disable the target temperature ramp

  check to avoid false positives.

Use custom linker for faster link times when ENABLE_TESTING is active

Use custom linker for faster link times when ENABLE_TESTING is active

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   * :doc:`oxdna2/fene <bond_oxdna>`

   * :doc:`oxdna2/fene <bond_oxdna>`

   * :doc:`oxrna2/fene <bond_oxdna>`

   * :doc:`oxrna2/fene <bond_oxdna>`

   * :doc:`quartic (o) <bond_quartic>`

   * :doc:`quartic (o) <bond_quartic>`

   * :doc:`special <bond_special>`

   * :doc:`table (o) <bond_table>`

   * :doc:`table (o) <bond_table>`

.. _angle:

.. _angle:

.. index:: bond_style special

bond_style special command

=================================

Syntax

""""""

.. code-block:: LAMMPS

   bond_style special

Examples

""""""""

.. code-block:: LAMMPS

   bond_style special

   bond_coeff 0.5 0.5

Description

"""""""""""

The *special* bond style can be used to create conceptual bonds which

effectively impose weightings on the pairwise Lennard Jones and/or

Coulombic interactions between selected pairs of particles in the

system.  The form of the pairwise interaction will be whatever is

computed by the :doc:`pair_style <pair_style>` command defined for the

system; this command defines the weightings for its two terms.

This command can thus be useful to apply weightings that cannot be

handled by the :doc:`special_bonds <special_bonds>` command, such as

on 1-5 or 1-6 interactions.  Or it can be used to add pairwise forces

between one or more pairs of atoms that otherwise would not be include

in the :doc:`pair_style <pair_style>` computation.

The potential for this bond style has the form

.. math::

   E =  w_{LJ} E_{LJ} + w_{Coul} E_{Coul}

The following coefficients must be defined for each bond type via the

:doc:`bond_coeff <bond_coeff>` command as in the example above, or in

the data file or restart files read by the :doc:`read_data <read_data>`

or :doc:`read_restart <read_restart>` commands:

* :math:`w_{LJ}` weight (0.0 to 1.0) on pairwise Lennard-Jones interactions

* :math:`w_{Coul}` weight (0.0 to 1.0) on pairwise Coulombic interactions

----------

Normally this bond style should be used in conjunction with one (or

more) other bond styles which compute forces between atoms directly

bonded to each other in a molecule.  This means the :doc:`bond_style

hybrid <bond_hybrid>` command should be used with bond_style special

as one of its sub-styles.

Note that the same as for any other bond style, pairs of bonded atoms

must be enumerated in the data file read by the :doc:`read_data

<read_data>` command.  Thus if this command is used to weight all 1-5

interactions in the system, all the 1-5 pairs of atoms must be listed

in the "Bonds" section of the data file.

This bond style imposes strict requirements on settings made with the

:doc:`special_bonds <special_bonds>` command.  These requirements

ensure that the new bonds created by this style do not create spurious

1-2, 1-3, or 1-4 interactions within the molecular topology.

Specifically 1-2 interactions must have weights of zero, 1-3

interactions must either have weights of unity or :doc:`special_bonds

angle yes <special_bonds>` must be used, and 1-4 interactions must

have weights of unity or :doc:`special_bonds dihedral yes <special_bonds>` 

must be used.

If this command is used to create bonded interactions between

particles that are further apart than usual (e.g. 1-5 or 1-6

interactions), this style may require an increase in the communication

cutoff via the :doc:`comm_modify cutoff <comm_modify>` command.  If

LAMMPS cannot find a partner atom in a bond, an error will be issued.

Restrictions

""""""""""""

This bond style can only be used if LAMMPS was built with the

USER-MISC package.  See the :doc:`Build package <Build_package>` doc

page for more info.

This bond style requires the use of a :doc:`pair_style <pair_style>` which

computes a pairwise additive interaction and provides the ability to

compute interactions for individual pairs of atoms.  Manybody potentials

are not compatible in general, but also some other pair styles are missing

the required functionality and thus will cause an error.

This command is not compatible with long-range Coulombic interactions. If a 

`kspace_style <kspace_style>` is declared, an error will be issued.

Related commands

""""""""""""""""

:doc:`bond_coeff <bond_coeff>`, :doc:`special_bonds <special_bonds>`

**Default:** none