ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'github/develop' into distributed-grids

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-08-18 15:18:27 -04:00
parent da3e723351 1b979be939
commit ccf6c2d55a
50 changed files with 1107 additions and 933 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/src/Developer_updating.rst
View File

@ -24,6 +24,7 @@ Available topics in mostly chronological order are:
- `Use of "override" instead of "virtual"`_
- `Simplified and more compact neighbor list requests`_
- `Split of fix STORE into fix STORE/GLOBAL and fix STORE/PERATOM`_
- `Use Output::get_dump_by_id() instead of Output::find_dump()`_
----
@ -382,3 +383,43 @@ New:
FixStoreGlobal *fix = dynamic_cast<FixStoreGlobal *>(modify->get_fix_by_id(id_fix));
This change is **required** or else the code will not compile.
Use Output::get_dump_by_id() instead of Output::find_dump()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: TBD
The accessor function to individual dump style instances has been changed
from ``Output::find_dump()`` returning the index of the dump instance in
the list of dumps to ``Output::get_dump_by_id()`` returning a pointer to
the dump directly. Example:
Old:
.. code-block:: C++
int idump = output->find_dump(arg[iarg+1]);
if (idump < 0)
error->all(FLERR,"Dump ID in hyper command does not exist");
memory->grow(dumplist,ndump+1,"hyper:dumplist");
dumplist[ndump++] = idump;
[...]
if (dumpflag)
for (int idump = 0; idump < ndump; idump++)
output->dump[dumplist[idump]]->write();
New:
.. code-block:: C++
auto idump = output->get_dump_by_id(arg[iarg+1]);
if (!idump) error->all(FLERR,"Dump ID {} in hyper command does not exist", arg[iarg+1]);
dumplist.emplace_back(idump);
[...]
if (dumpflag) for (auto idump : dumplist) idump->write();
This change is **required** or else the code will not compile.

113
doc/src/fix_shake.rst
View File

@ -33,12 +33,14 @@ Syntax
*m* value = one or more mass values
* zero or more keyword/value pairs may be appended
* keyword = *mol*
* keyword = *mol* or *kbond*
.. parsed-literal::
*mol* value = template-ID
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command
*kbond* value = force constant
force constant = force constant used to apply a restraint force when used during minimization
Examples
""""""""
@ -56,7 +58,10 @@ Description
Apply bond and angle constraints to specified bonds and angles in the
simulation by either the SHAKE or RATTLE algorithms. This typically
enables a longer timestep.
enables a longer timestep. The SHAKE or RATTLE algorithms, however, can
*only* be applied during molecular dynamics runs. When this fix is used
during a minimization, the constraints are *approximated* by strong
harmonic restraints.
**SHAKE vs RATTLE:**
@ -90,7 +95,7 @@ The SHAKE algorithm satisfies the first condition, i.e. the sites at
time *n+1* will have the desired separations Dij immediately after the
coordinates are integrated. If we also enforce the second condition,
the velocity components along the bonds will vanish. RATTLE satisfies
both conditions. As implemented in LAMMPS, fix rattle uses fix shake
both conditions. As implemented in LAMMPS, *fix rattle* uses fix shake
for satisfying the coordinate constraints. Therefore the settings and
optional keywords are the same for both fixes, and all the information
below about SHAKE is also relevant for RATTLE.
@ -139,30 +144,47 @@ for.
.. note::
This command works by using the current forces on atoms to
calculate an additional constraint force which when added will leave
the atoms in positions that satisfy the SHAKE constraints (e.g. bond
length) after the next time integration step. If you define fixes
(e.g. :doc:`fix efield <fix_efield>`) that add additional force to the
atoms after fix shake operates, then this fix will not take them into
account and the time integration will typically not satisfy the SHAKE
constraints. The solution for this is to make sure that fix shake is
defined in your input script after any other fixes which add or change
forces (to atoms that fix shake operates on).
This command works by using the current forces on atoms to calculate
an additional constraint force which when added will leave the atoms
in positions that satisfy the SHAKE constraints (e.g. bond length)
after the next time integration step. If you define fixes
(e.g. :doc:`fix efield <fix_efield>`) that add additional force to
the atoms after *fix shake* operates, then this fix will not take them
into account and the time integration will typically not satisfy the
SHAKE constraints. The solution for this is to make sure that fix
shake is defined in your input script after any other fixes which add
or change forces (to atoms that *fix shake* operates on).
----------
The *mol* keyword should be used when other commands, such as :doc:`fix deposit <fix_deposit>` or :doc:`fix pour <fix_pour>`, add molecules
The *mol* keyword should be used when other commands, such as :doc:`fix
deposit <fix_deposit>` or :doc:`fix pour <fix_pour>`, add molecules
on-the-fly during a simulation, and you wish to constrain the new
molecules via SHAKE. You specify a *template-ID* previously defined
using the :doc:`molecule <molecule>` command, which reads a file that
defines the molecule. You must use the same *template-ID* that the
command adding molecules uses. The coordinates, atom types, special
bond restrictions, and SHAKE info can be specified in the molecule
file. See the :doc:`molecule <molecule>` command for details. The only
bond restrictions, and SHAKE info can be specified in the molecule file.
See the :doc:`molecule <molecule>` command for details. The only
settings required to be in this file (by this command) are the SHAKE
info of atoms in the molecule.
The *kbond* keyword sets the restraint force constant when *fix shake*
or fix rattle are used during minimization. In that case the constraint
algorithms are *not* applied and restraint forces are used instead to
maintain the geometries similar to the constraints. How well the
geometries are maintained and how quickly a minimization converges,
depends largely on the force constant *kbond*: larger values will reduce
the deviation from the desired geometry, but can also lead to slower
convergence of the minimization or lead to instabilities depending on
the minimization algorithm requiring to reduce the value of
:doc:`timestep <timestep>`. Even though the restraints will not
preserve the bond lengths and angles as closely as the constraints
during the MD, they are generally close enough so that the constraints
will be fulfilled to the desired accuracy within a few MD steps
following the minimization. The default value for *kbond* depends on the
:doc:`units <units>` setting and is 1.0e6*k_B.
----------
.. include:: accel_styles.rst
@ -177,10 +199,10 @@ LAMMPS closely follows (:ref:`Andersen (1983) <Andersen3>`).
.. note::
The fix rattle command modifies forces and velocities and thus
The *fix rattle* command modifies forces and velocities and thus
should be defined after all other integration fixes in your input
script. If you define other fixes that modify velocities or forces
after fix rattle operates, then fix rattle will not take them into
after *fix rattle* operates, then *fix rattle* will not take them into
account and the overall time integration will typically not satisfy
the RATTLE constraints. You can check whether the constraints work
correctly by setting the value of RATTLE_DEBUG in src/fix_rattle.cpp
@ -194,19 +216,32 @@ Restart, fix_modify, output, run start/stop, minimize info
No information about these fixes is written to :doc:`binary restart
files <restart>`.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
these fixes to add the contribution due to the added forces on atoms
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>`.
Both fix *shake* and fix *rattle* behave differently during a minimization
in comparison to a molecular dynamics run:
- When used during a minimization, the SHAKE or RATTLE constraint
algorithms themselves are **not** applied. Instead the constraints
are replaced by harmonic restraint forces. The energy and virial
contributions due to the restraint forces are tallied into global and
per-atom accumulators. The total restraint energy is also accessible
as a global scalar property of the fix.
- During molecular dynamics runs, however, the fixes do apply the
requested SHAKE or RATTLE constraint algorithms.
The :doc:`fix_modify <fix_modify>` *virial* option is supported by
these fixes to add the contribution due to the added constraint forces
on atoms 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>`. No global or per-atom quantities are stored by these
fixes for access by various :doc:`output commands <Howto_output>` during
an MD run. No parameter of these fixes can be used with the
*start/stop* keywords of the :doc:`run <run>` command.
No global or per-atom quantities are stored by these fixes for access
by various :doc:`output commands <Howto_output>`. No parameter of
these fixes can be used with the *start/stop* keywords of the
:doc:`run <run>` command. These fixes are not invoked during
:doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
@ -224,21 +259,27 @@ which can lead to poor energy conservation. You can test for this in
your system by running a constant NVE simulation with a particular set
of SHAKE parameters and monitoring the energy versus time.
SHAKE or RATTLE should not be used to constrain an angle at 180
degrees (e.g. linear CO2 molecule). This causes numeric difficulties.
You can use :doc:`fix rigid or fix rigid/small <fix_rigid>` instead to
make a linear molecule rigid.
SHAKE or RATTLE should not be used to constrain an angle at 180 degrees
(e.g. a linear CO2 molecule). This causes a divergence when solving the
constraint equations numerically. You can use :doc:`fix rigid or fix
rigid/small <fix_rigid>` instead to make a linear molecule rigid.
When used during minimization choosing a too large value of the *kbond*
can make minimization very inefficient and also cause stability problems
with some minimization algorithms. Sometimes those can be avoided by
reducing the :doc:`timestep <timestep>`.
Related commands
""""""""""""""""
none
`fix rigid <fix_rigid>`, `fix ehex <fix_ehex>`,
`fix nve/manifold/rattle <fix_nve_manifold_rattle>`
Default
"""""""
none
kbond = 1.0e9*k_B
----------

116
doc/src/minimize.rst
View File

@ -32,30 +32,51 @@ Description
Perform an energy minimization of the system, by iteratively adjusting
atom coordinates. Iterations are terminated when one of the stopping
criteria is satisfied. At that point the configuration will hopefully
be in local potential energy minimum. More precisely, the
be in a local potential energy minimum. More precisely, the
configuration should approximate a critical point for the objective
function (see below), which may or may not be a local minimum.
The minimization algorithm used is set by the
:doc:`min_style <min_style>` command. Other options are set by the
:doc:`min_modify <min_modify>` command. Minimize commands can be
interspersed with :doc:`run <run>` commands to alternate between
relaxation and dynamics. The minimizers bound the distance atoms move
in one iteration, so that you can relax systems with highly overlapped
atoms (large energies and forces) by pushing the atoms off of each
other.
The minimization algorithm used is set by the :doc:`min_style
<min_style>` command. Other options are set by the :doc:`min_modify
<min_modify>` command. Minimize commands can be interspersed with
:doc:`run <run>` commands to alternate between relaxation and dynamics.
The minimizers bound the distance atoms may move in one iteration, so
that you can relax systems with highly overlapped atoms (large energies
and forces) by pushing the atoms off of each other.
Alternate means of relaxing a system are to run dynamics with a small
or :doc:`limited timestep <fix_nve_limit>`. Or dynamics can be run
using :doc:`fix viscous <fix_viscous>` to impose a damping force that
slowly drains all kinetic energy from the system. The :doc:`pair_style soft <pair_soft>` potential can be used to un-overlap atoms while
running dynamics.
un-overlap atoms while running dynamics.
.. admonition:: Neighbor list update settings
:class: note
The distance that atoms can move during individual minimization steps
can be quite large, especially at the beginning of a minimization.
Thus `neighbor list settings <neigh_modify>` of *every = 1* and
*delay = 0* are **required**. This may be combined with either
*check = no* (always update the neighbor list) or *check = yes* (only
update the neighbor list if at least one atom has moved more than
half the `neighbor list skin <neighbor>` distance since the last
reneighboring). Using *check = yes* is recommended since it avoids
unneeded reneighboring steps when the system is closer to the minimum
and thus atoms move only small distances. Using *check = no* may
be required for debugging or when coupling LAMMPS with external
codes that require a predictable sequence of neighbor list updates.
If the settings are **not** *every = 1* and *delay = 0*, LAMMPS
will temporarily apply a `neigh_modify every 1 delay 0 check yes
<neigh_modify>` setting during the minimization and restore the
original setting at the end of the minimization. A corresponding
message will be printed to the screen and log file, if this happens.
Alternate means of relaxing a system are to run dynamics with a small or
:doc:`limited timestep <fix_nve_limit>`. Or dynamics can be run using
:doc:`fix viscous <fix_viscous>` to impose a damping force that slowly
drains all kinetic energy from the system. The :doc:`pair_style soft
<pair_soft>` potential can be used to un-overlap atoms while running
dynamics.
Note that you can minimize some atoms in the system while holding the
coordinates of other atoms fixed by applying :doc:`fix setforce
<fix_setforce>` to the other atoms. See a fuller discussion of using
fixes while minimizing below.
coordinates of other atoms fixed by applying :doc:`fix setforce 0.0 0.0
0.0 <fix_setforce>` to the other atoms. See a more detailed discussion
of :ref:`using fixes while minimizing below <fix_minimize>`.
The :doc:`minimization styles <min_style>` *cg*, *sd*, and *hftn*
involves an outer iteration loop which sets the search direction along
@ -74,10 +95,11 @@ they require a :doc:`timestep <timestep>` be defined.
.. note::
The damped dynamic minimizers use whatever timestep you have
defined via the :doc:`timestep <timestep>` command. Often they
will converge more quickly if you use a timestep about 10x larger
than you would normally use for dynamics simulations.
The damped dynamic minimizer algorithms will use the timestep you
have defined via the :doc:`timestep <timestep>` command or its
default value. Often they will converge more quickly if you use a
timestep about 10x larger than you would normally use for regular
molecular dynamics simulations.
----------
@ -210,34 +232,42 @@ The iterations and force evaluation values are what is checked by the
.. note::
There are several force fields in LAMMPS which have
discontinuities or other approximations which may prevent you from
performing an energy minimization to high tolerances. For example,
you should use a :doc:`pair style <pair_style>` that goes to 0.0 at the
cutoff distance when performing minimization (even if you later change
it when running dynamics). If you do not do this, the total energy of
There are several force fields in LAMMPS which have discontinuities
or other approximations which may prevent you from performing an
energy minimization to tight tolerances. For example, you should use
a :doc:`pair style <pair_style>` that goes to 0.0 at the cutoff
distance when performing minimization (even if you later change it
when running dynamics). If you do not do this, the total energy of
the system will have discontinuities when the relative distance
between any pair of atoms changes from cutoff+epsilon to
cutoff-epsilon and the minimizer may behave poorly. Some of the
many-body potentials use splines and other internal cutoffs that
inherently have this problem. The :doc:`long-range Coulombic styles <kspace_style>` (PPPM, Ewald) are approximate to within the
user-specified tolerance, which means their energy and forces may not
agree to a higher precision than the Kspace-specified tolerance. In
all these cases, the minimizer may give up and stop before finding a
minimum to the specified energy or force tolerance.
between any pair of atoms changes from cutoff *plus* epsilon to
cutoff *minus* epsilon and the minimizer may thus behave poorly.
Some of the many-body potentials use splines and other internal
cutoffs that inherently have this problem. The :doc:`long-range
Coulombic styles <kspace_style>` (PPPM, Ewald) are approximate to
within the user-specified tolerance, which means their energy and
forces may not agree to a higher precision than the Kspace-specified
tolerance. This agreement is further reduced when using tabulation
to speed up the computation of the real-space part of the Coulomb
interactions, which is enabled by default. In all these cases, the
minimizer may give up and stop before finding a minimum to the
specified energy or force tolerance.
Note that a cutoff Lennard-Jones potential (and others) can be shifted
so that its energy is 0.0 at the cutoff via the
:doc:`pair_modify <pair_modify>` command. See the doc pages for
individual :doc:`pair styles <pair_style>` for details. Note that
Coulombic potentials always have a cutoff, unless versions with a
long-range component are used (e.g. :doc:`pair_style lj/cut/coul/long <pair_lj_cut_coul>`). The CHARMM potentials go to 0.0 at
the cutoff (e.g. :doc:`pair_style lj/charmm/coul/charmm <pair_charmm>`),
as do the GROMACS potentials (e.g. :doc:`pair_style lj/gromacs <pair_gromacs>`).
so that its energy is 0.0 at the cutoff via the :doc:`pair_modify
<pair_modify>` command. See the doc pages for individual :doc:`pair
styles <pair_style>` for details. Note that most Coulombic potentials
have a cutoff, unless versions with a long-range component are used
(e.g. :doc:`pair_style lj/cut/coul/long <pair_lj_cut_coul>`) or some
other damping/smoothing schemes are used. The CHARMM potentials go to
0.0 at the cutoff (e.g. :doc:`pair_style lj/charmm/coul/charmm
<pair_charmm>`), as do the GROMACS potentials (e.g. :doc:`pair_style
lj/gromacs <pair_gromacs>`).
If a soft potential (:doc:`pair_style soft <pair_soft>`) is used the
Astop value is used for the prefactor (no time dependence).
.. _fix_minimize:
The :doc:`fix box/relax <fix_box_relax>` command can be used to apply an
external pressure to the simulation box and allow it to shrink/expand
during the minimization.