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

Merge branch 'develop' into general-triclinic

Browse Source
This commit is contained in:
Axel Kohlmeyer
2024-03-08 21:32:01 -05:00
parent 835b65b644 bd99c2d661
commit 01d412bdbf
444 changed files with 10212 additions and 3787 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
doc/src/Bibliography.rst
View File

@ -877,6 +877,9 @@ Bibliography
**(PLUMED)**
G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)
**(Pavlov)**
D Pavlov, V Galigerov, D Kolotinskii, V Nikolskiy, V Stegailov, International Journal of High Performance Computing Applications, 38, 34-49 (2024).
**(Paquay)**
Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 <https://arxiv.org/abs/1411.3019/>`_.

2
doc/src/Commands_fix.rst
View File

@ -61,6 +61,7 @@ OPT.
* :doc:`controller <fix_controller>`
* :doc:`damping/cundall <fix_damping_cundall>`
* :doc:`deform (k) <fix_deform>`
* :doc:`deform/pressure <fix_deform_pressure>`
* :doc:`deposit <fix_deposit>`
* :doc:`dpd/energy (k) <fix_dpd_energy>`
* :doc:`drag <fix_drag>`
@ -262,6 +263,7 @@ OPT.
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`
* :doc:`wall/colloid <fix_wall>`
* :doc:`wall/ees <fix_wall_ees>`
* :doc:`wall/flow (k) <fix_wall_flow>`
* :doc:`wall/gran (k) <fix_wall_gran>`
* :doc:`wall/gran/region <fix_wall_gran_region>`
* :doc:`wall/harmonic <fix_wall>`

1
doc/src/Commands_pair.rst
View File

@ -256,6 +256,7 @@ OPT.
* :doc:`rann <pair_rann>`
* :doc:`reaxff (ko) <pair_reaxff>`
* :doc:`rebo (io) <pair_airebo>`
* :doc:`rebomos (o) <pair_rebomos>`
* :doc:`resquared (go) <pair_resquared>`
* :doc:`saip/metal (t) <pair_saip_metal>`
* :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>`

47
doc/src/Developer_updating.rst
View File

@ -18,6 +18,7 @@ Available topics in mostly chronological order are:
- `Setting flags in the constructor`_
- `Rename of pack/unpack_comm() to pack/unpack_forward_comm()`_
- `Use ev_init() to initialize variables derived from eflag and vflag`_
- `Use utils::count_words() functions instead of atom->count_words()`_
- `Use utils::numeric() functions instead of force->numeric()`_
- `Use utils::open_potential() function to open potential files`_
- `Use symbolic Atom and AtomVec constants instead of numerical values`_
@ -130,6 +131,41 @@ Not applying this change will not cause a compilation error, but
can lead to inconsistent behavior and incorrect tallying of
energy or virial.
Use utils::count_words() functions instead of atom->count_words()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 2Jun2020
The "count_words()" functions for parsing text have been moved from the
Atom class to the :doc:`utils namespace <Developer_utils>`. The
"count_words()" function in "utils" uses the Tokenizer class internally
to split a line into words and count them, thus it will not modify the
argument string as the function in the Atoms class did and thus had a
variant using a copy buffer. Unlike the old version, the new version
does not remove comments. For that you can use the
:cpp:func:`utils::trim_comment() function
<LAMMPS_NS::utils::trim_comment>` as shown in the example below.
Old:
.. code-block:: c++
nwords = atom->count_words(line);
int nwords = atom->count_words(buf);
New:
.. code-block:: c++
nwords = utils::count_words(line);
int nwords = utils::count_words(utils::trim_comment(buf));
.. seealso::
:cpp:func:`utils::count_words() <LAMMPS_NS::utils::count_words>`,
:cpp:func:`utils::trim_comments() <LAMMPS_NS::utils::trim_comments>`
Use utils::numeric() functions instead of force->numeric()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -137,11 +173,12 @@ Use utils::numeric() functions instead of force->numeric()
The "numeric()" conversion functions (including "inumeric()",
"bnumeric()", and "tnumeric()") have been moved from the Force class to
the utils namespace. Also they take an additional argument that selects
whether the ``Error::all()`` or ``Error::one()`` function should be
called in case of an error. The former should be used when *all* MPI
processes call the conversion function and the latter *must* be used
when they are called from only one or a subset of the MPI processes.
the :doc:`utils namespace <Developer_utils>`. Also they take an
additional argument that selects whether the ``Error::all()`` or
``Error::one()`` function should be called in case of an error. The
former should be used when *all* MPI processes call the conversion
function and the latter *must* be used when they are called from only
one or a subset of the MPI processes.
Old:

5
doc/src/Howto_granular.rst
View File

@ -45,10 +45,15 @@ atoms, and should be used for granular system instead of the fix style
To model heat conduction, one must add the temperature and heatflow
atom variables with:
* :doc:`fix property/atom <fix_property_atom>`
a temperature integration fix
* :doc:`fix heat/flow <fix_heat_flow>`
and a heat conduction option defined in both
* :doc:`pair_style granular <pair_granular>`
* :doc:`fix wall/gran <fix_wall_gran>`

64
doc/src/Speed_kokkos.rst
View File

@ -20,11 +20,28 @@ including Sikandar Mashayak (UIUC), Ray Shan (Sandia), and Dan Ibanez
(Sandia). For more information on developing using Kokkos abstractions
see the `Kokkos Wiki <https://github.com/kokkos/kokkos/wiki>`_.
Kokkos currently provides support for 4 modes of execution (per MPI
.. note::
The Kokkos library is under active development and tracking the
availability of accelerator hardware, so is the KOKKOS package in
LAMMPS. This means that only a certain range of versions of the
Kokkos library are compatible with the KOKKOS package of a certain
range of LAMMPS versions. For that reason LAMMPS comes with a
bundled version of the Kokkos library that has been validated on
multiple platforms and may contain selected back-ported bug fixes
from upstream Kokkos versions. While it is possible to build LAMMPS
with an external version of Kokkos, it is untested and may result in
incorrect execution or crashes.
Kokkos currently provides full support for 4 modes of execution (per MPI
task). These are Serial (MPI-only for CPUs and Intel Phi), OpenMP
(threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA
GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
produce an executable compatible with a specific hardware.
(threading for many-core CPUs and Intel Phi), CUDA (for NVIDIA GPUs) and
HIP (for AMD GPUs). Additional modes (e.g. OpenMP target, Intel data
center GPUs) are under development. You choose the mode at build time
to produce an executable compatible with a specific hardware.
The following compatibility notes have been last updated for LAMMPS
version 23 November 2023 and Kokkos version 4.2.
.. admonition:: C++17 support
:class: note
@ -54,22 +71,22 @@ produce an executable compatible with a specific hardware.
:class: note
Kokkos with CUDA currently implicitly assumes that the MPI library is
GPU-aware. This is not always the case, especially when using
GPU-aware. This is not always the case, especially when using
pre-compiled MPI libraries provided by a Linux distribution. This is
not a problem when using only a single GPU with a single MPI
rank. When running with multiple MPI ranks, you may see segmentation
rank. When running with multiple MPI ranks, you may see segmentation
faults without GPU-aware MPI support. These can be avoided by adding
the flags :doc:`-pk kokkos gpu/aware off <Run_options>` to the
LAMMPS command line or by using the command :doc:`package kokkos
gpu/aware off <package>` in the input file.
.. admonition:: AMD GPU support
.. admonition:: Intel Data Center GPU support
:class: note
To build with Kokkos the HIPCC compiler from the AMD ROCm software
version 3.5 or later is required. Supporting this Kokkos mode in
LAMMPS is still work in progress. Please contact the LAMMPS developers
if you run into problems.
Support for Kokkos with Intel Data Center GPU accelerators (formerly
known under the code name "Ponte Vecchio") in LAMMPS is still a work
in progress. Only a subset of the functionality works correctly.
Please contact the LAMMPS developers if you run into problems.
Building LAMMPS with the KOKKOS package
"""""""""""""""""""""""""""""""""""""""
@ -292,6 +309,10 @@ one or more nodes, each with two GPUs:
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
.. code-block:: bash
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff
.. note::
The default binsize for :doc:`atom sorting <atom_modify>` on GPUs
@ -302,9 +323,15 @@ one or more nodes, each with two GPUs:
frequent sorting than default (e.g. sorting every 100 time steps
instead of 1000) may improve performance.
.. code-block:: bash
.. note::
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff
When running on GPUs with many MPI ranks (tens of thousands and
more), the creation of the atom map (required for molecular systems)
on the GPU can slow down significantly or run out of GPU memory and
thus slow down the whole calculation or cause a crash. You can use
the "-pk kokkos atom/map no" :doc:`command-line switch <Run_options>`
of the :doc:`package kokkos atom/map no <package>` command to create
the atom map on the CPU instead.
.. note::
@ -416,15 +443,22 @@ Generally speaking, the following rules of thumb apply:
performance of a KOKKOS style is a bit slower than the OPENMP
package.
* When running large number of atoms per GPU, KOKKOS is typically faster
than the GPU package when compiled for double precision. The benefit
than the GPU package when compiled for double precision. The benefit
of using single or mixed precision with the GPU package depends
significantly on the hardware in use and the simulated system and pair
style.
* When running on Intel hardware, KOKKOS is not as fast as
* When running on Intel Phi hardware, KOKKOS is not as fast as
the INTEL package, which is optimized for x86 hardware (not just
from Intel) and compilation with the Intel compilers. The INTEL
package also can increase the vector length of vector instructions
by switching to single or mixed precision mode.
* The KOKKOS package by default assumes that you are using exactly one
MPI rank per GPU. When trying to use multiple MPI ranks per GPU it is
mandatory to enable `CUDA Multi-Process Service (MPS)
<https://docs.nvidia.com/deploy/mps/index.html>`_ to get good
performance. In this case it is better to not use all available
MPI ranks in order to avoid competing with the MPS daemon for
CPU resources.
See the `Benchmark page <https://www.lammps.org/bench.html>`_ of the
LAMMPS website for performance of the KOKKOS package on different

19
doc/src/compute_adf.rst
View File

@ -204,8 +204,23 @@ angles per atom satisfying the ADF criteria.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
By default, the ADF is not computed for distances longer than the
largest force cutoff, since the neighbor list creation will only contain
pairs up to that distance (plus neighbor list skin). If you use outer
cutoffs larger than that, you must use :doc:`neighbor style 'bin' or
'nsq' <neighbor>`.
If you want an ADF for a larger outer cutoff, you can also use the
:doc:`rerun <rerun>` command to post-process a dump file, use :doc:`pair
style zero <pair_zero>` and set the force cutoff to be larger in the
rerun script. Note that in the rerun context, the force cutoff is
arbitrary and with pair style zero you are not computing any forces, and
since you are not running dynamics you are not changing the model that
generated the trajectory.
The ADF is not computed for neighbors outside the force cutoff,
since processors (in parallel) don't know about atom coordinates for

2
doc/src/compute_ave_sphere_atom.rst
View File

@ -102,6 +102,8 @@ This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This compute requires :doc:`neighbor styles 'bin' or 'nsq' <neighbor>`.
Related commands
""""""""""""""""

2
doc/src/compute_composition_atom.rst
View File

@ -107,6 +107,8 @@ This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This compute requires :doc:`neighbor styles 'bin' or 'nsq' <neighbor>`.
Related commands
""""""""""""""""

2
doc/src/compute_efield_wolf_atom.rst
View File

@ -106,6 +106,8 @@ Restrictions
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package.
This compute requires :doc:`neighbor styles 'bin' or 'nsq' <neighbor>`.
Related commands
""""""""""""""""

8
doc/src/compute_fabric.rst
View File

@ -64,7 +64,7 @@ tangential force tensor. The contact tensor is calculated as
.. math::
C_{ab} = \frac{15}{2} (\phi_{ab} - \mathrm{Tr}(\phi) \delta_{ab})
C_{ab} = \frac{15}{2} (\phi_{ab} - \frac{1}{3} \mathrm{Tr}(\phi) \delta_{ab})
where :math:`a` and :math:`b` are the :math:`x`, :math:`y`, :math:`z`
directions, :math:`\delta_{ab}` is the Kronecker delta function, and
@ -83,7 +83,7 @@ The branch tensor is calculated as
.. math::
B_{ab} = \frac{15}{6 \mathrm{Tr}(D)} (D_{ab} - \mathrm{Tr}(D) \delta_{ab})
B_{ab} = \frac{15}{2\, \mathrm{Tr}(D)} (D_{ab} - \frac{1}{3} \mathrm{Tr}(D) \delta_{ab})
where the tensor :math:`D` is defined as
@ -101,7 +101,7 @@ The normal force fabric tensor is calculated as
.. math::
F^n_{ab} = \frac{15}{6\, \mathrm{Tr}(N)} (N_{ab} - \mathrm{Tr}(N) \delta_{ab})
F^n_{ab} = \frac{15}{2\, \mathrm{Tr}(N)} (N_{ab} - \frac{1}{3} \mathrm{Tr}(N) \delta_{ab})
where the tensor :math:`N` is defined as
@ -119,7 +119,7 @@ as
.. math::
F^t_{ab} = \frac{15}{9\, \mathrm{Tr}(N)} (T_{ab} - \mathrm{Tr}(T) \delta_{ab})
F^t_{ab} = \frac{5}{\mathrm{Tr}(N)} (T_{ab} - \frac{1}{3} \mathrm{Tr}(T) \delta_{ab})
where the tensor :math:`T` is defined as

5
doc/src/compute_property_atom.rst
View File

@ -23,8 +23,9 @@ Syntax
spx, spy, spz, sp, fmx, fmy, fmz,
nbonds,
radius, diameter, omegax, omegay, omegaz,
temperature, heatflow,
angmomx, angmomy, angmomz,
shapex,shapey, shapez,
shapex, shapey, shapez,
quatw, quati, quatj, quatk, tqx, tqy, tqz,
end1x, end1y, end1z, end2x, end2y, end2z,
corner1x, corner1y, corner1z,
@ -56,6 +57,8 @@ Syntax
*nbonds* = number of bonds assigned to an atom
*radius,diameter* = radius,diameter of spherical particle
*omegax,omegay,omegaz* = angular velocity of spherical particle
*temperature* = internal temperature of spherical particle
*heatflow* = internal heat flow of spherical particle
*angmomx,angmomy,angmomz* = angular momentum of aspherical particle
*shapex,shapey,shapez* = 3 diameters of aspherical particle
*quatw,quati,quatj,quatk* = quaternion components for aspherical or body particles

37
doc/src/compute_rdf.rst
View File

@ -176,22 +176,29 @@ also numbers :math:`\ge 0.0`.
Restrictions
""""""""""""
The RDF is not computed for distances longer than the force cutoff,
since processors (in parallel) do not know about atom coordinates for
atoms further away than that distance. If you want an RDF for larger
distances, you can use the :doc:`rerun <rerun>` command to post-process
a dump file and set the cutoff for the potential to be longer in the
By default, the RDF is not computed for distances longer than the
largest force cutoff, since the neighbor list creation will only contain
pairs up to that distance (plus neighbor list skin). This distance can
be increased using the *cutoff* keyword but this keyword is only valid
with :doc:`neighbor styles 'bin' and 'nsq' <neighbor>`.
If you want an RDF for larger distances, you can also use the
:doc:`rerun <rerun>` command to post-process a dump file, use :doc:`pair
style zero <pair_zero>` and set the force cutoff to be longer in the
rerun script. Note that in the rerun context, the force cutoff is
arbitrary, since you are not running dynamics and thus are not changing
your model. The definition of :math:`g(r)` used by LAMMPS is only appropriate
for characterizing atoms that are uniformly distributed throughout the
simulation cell. In such cases, the coordination number is still
correct and meaningful. As an example, if a large simulation cell
contains only one atom of type *itypeN* and one of *jtypeN*, then :math:`g(r)`
will register an arbitrarily large spike at whatever distance they
happen to be at, and zero everywhere else.
The function :math:`\text{coord}(r)` will show a step
change from zero to one at the location of the spike in :math:`g(r)`.
arbitrary and with pair style zero you are not computing any forces, and
you are not running dynamics you are not changing the model that
generated the trajectory.
The definition of :math:`g(r)` used by LAMMPS is only appropriate for
characterizing atoms that are uniformly distributed throughout the
simulation cell. In such cases, the coordination number is still correct
and meaningful. As an example, if a large simulation cell contains only
one atom of type *itypeN* and one of *jtypeN*, then :math:`g(r)` will
register an arbitrarily large spike at whatever distance they happen to
be at, and zero everywhere else. The function :math:`\text{coord}(r)`
will show a step change from zero to one at the location of the spike in
:math:`g(r)`.
.. note::

3
doc/src/dump.rst
View File

@ -104,7 +104,6 @@ Syntax
q, mux, muy, muz, mu,
radius, diameter, omegax, omegay, omegaz,
angmomx, angmomy, angmomz, tqx, tqy, tqz,
heatflow, temperature,
c_ID, c_ID[I], f_ID, f_ID[I], v_name,
i_name, d_name, i2_name[I], d2_name[I]
@ -131,8 +130,6 @@ Syntax
omegax,omegay,omegaz = angular velocity of spherical particle
angmomx,angmomy,angmomz = angular momentum of aspherical particle
tqx,tqy,tqz = torque on finite-size particles
heatflow = rate of heat flow into particle
temperature = temperature of particle
c_ID = per-atom vector calculated by a compute with ID
c_ID[I] = Ith column of per-atom array calculated by a compute with ID, I can include wildcard (see below)
f_ID = per-atom vector calculated by a fix with ID

2
doc/src/fix.rst
View File

@ -226,6 +226,7 @@ accelerated styles exist.
* :doc:`controller <fix_controller>` - apply control loop feedback mechanism
* :doc:`damping/cundall <fix_damping_cundall>` - Cundall non-viscous damping for granular simulations
* :doc:`deform <fix_deform>` - change the simulation box size/shape
* :doc:`deform/pressure <fix_deform_pressure>` - change the simulation box size/shape with additional loading conditions
* :doc:`deposit <fix_deposit>` - add new atoms above a surface
* :doc:`dpd/energy <fix_dpd_energy>` - constant energy dissipative particle dynamics
* :doc:`drag <fix_drag>` - drag atoms towards a defined coordinate
@ -427,6 +428,7 @@ accelerated styles exist.
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>` - time integration for body particles of style :doc:`rounded/polyhedron <Howto_body>`
* :doc:`wall/colloid <fix_wall>` - Lennard-Jones wall interacting with finite-size particles
* :doc:`wall/ees <fix_wall_ees>` - wall for ellipsoidal particles
* :doc:`wall/flow <fix_wall_flow>` - flow boundary conditions
* :doc:`wall/gran <fix_wall_gran>` - frictional wall(s) for granular simulations
* :doc:`wall/gran/region <fix_wall_gran_region>` - :doc:`fix wall/region <fix_wall_region>` equivalent for use with granular particles
* :doc:`wall/harmonic <fix_wall>` - harmonic spring wall

13
doc/src/fix_balance.rst
View File

@ -14,15 +14,15 @@ Syntax
* balance = style name of this fix command
* Nfreq = perform dynamic load balancing every this many steps
* thresh = imbalance threshold that must be exceeded to perform a re-balance
* style = *shift* or *rcb*
* style = *shift* or *rcb* or *report*
.. parsed-literal::
shift args = dimstr Niter stopthresh
*shift* args = dimstr Niter stopthresh
dimstr = sequence of letters containing *x* or *y* or *z*, each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshold is reached
*rcb* args = none
*report* args = none
* zero or more keyword/arg pairs may be appended
* keyword = *weight* or *out*
@ -70,6 +70,13 @@ re-balancing is performed periodically during the simulation. To
perform "static" balancing, before or between runs, see the
:doc:`balance <balance>` command.
.. versionadded:: TBD
The *report* balance style only computes the load imbalance but
does not attempt any re-balancing. This way the load imbalance
information can be used otherwise, for instance for stopping a
run with :doc:`fix halt <fix_halt>`.
Load-balancing is typically most useful if the particles in the
simulation box have a spatially-varying density distribution or
where the computational cost varies significantly between different

10
doc/src/fix_charge_regulation.rst
View File

@ -253,11 +253,11 @@ built with that package. See the :doc:`Build package <Build_package>`
page for more info.
The :doc:`atom_style <atom_style>`, used must contain the charge
property, for example, the style could be *charge* or *full*. Only
usable for 3D simulations. Atoms specified as free ions cannot be part
of rigid bodies or molecules and cannot have bonding interactions. The
scheme is limited to integer charges, any atoms with non-integer charges
will not be considered by the fix.
property and have per atom type masses, for example, the style could be
*charge* or *full*. Only usable for 3D simulations. Atoms specified as
free ions cannot be part of rigid bodies or molecules and cannot have
bonding interactions. The scheme is limited to integer charges, any
atoms with non-integer charges will not be considered by the fix.
All interaction potentials used must be continuous, otherwise the MD
integration and the particle exchange MC moves do not correspond to the

181
doc/src/fix_deform.rst
View File

@ -4,6 +4,9 @@
fix deform command
==================
:doc:`fix deform/pressure <fix_deform_pressure>` command
========================================================
Accelerator Variants: *deform/kk*
Syntax
@ -11,18 +14,18 @@ Syntax
.. code-block:: LAMMPS
fix ID group-ID deform N parameter args ... keyword value ...
fix ID group-ID fix_style N parameter style args ... keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* deform = style name of this fix command
* fix_style = *deform* or *deform/pressure*
* N = perform box deformation every this many timesteps
* one or more parameter/arg pairs may be appended
* one or more parameter/style/args sequences of arguments may be appended
.. parsed-literal::
parameter = *x* or *y* or *z* or *xy* or *xz* or *yz*
*x*, *y*, *z* args = style value(s)
style = *final* or *delta* or *scale* or *vel* or *erate* or *trate* or *volume* or *wiggle* or *variable*
style = *final* or *delta* or *scale* or *vel* or *erate* or *trate* or *volume* or *wiggle* or *variable* or *pressure* or *pressure/mean*
*final* values = lo hi
lo hi = box boundaries at end of run (distance units)
*delta* values = dlo dhi
@ -43,8 +46,15 @@ Syntax
*variable* values = v_name1 v_name2
v_name1 = variable with name1 for box length change as function of time
v_name2 = variable with name2 for change rate as function of time
*pressure* values = target gain (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
*pressure/mean* values = target gain (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
*xy*, *xz*, *yz* args = style value
style = *final* or *delta* or *vel* or *erate* or *trate* or *wiggle*
style = *final* or *delta* or *vel* or *erate* or *trate* or *wiggle* or *variable*
*final* value = tilt
tilt = tilt factor at end of run (distance units)
*delta* value = dtilt
@ -62,9 +72,12 @@ Syntax
*variable* values = v_name1 v_name2
v_name1 = variable with name1 for tilt change as function of time
v_name2 = variable with name2 for change rate as function of time
*pressure* values = target gain (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
* zero or more keyword/value pairs may be appended
* keyword = *remap* or *flip* or *units*
* keyword = *remap* or *flip* or *units* or *couple* or *vol/balance/p* or *max/rate* or *normalize/pressure*
.. parsed-literal::
@ -77,6 +90,15 @@ Syntax
*units* value = *lattice* or *box*
lattice = distances are defined in lattice units
box = distances are defined in simulation box units
*couple* value = *none* or *xyz* or *xy* or *yz* or *xz* (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
couple pressure values of various dimensions
*vol/balance/p* value = *yes* or *no* (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
Modifies the behavior of the *volume* option to try and balance pressures
*max/rate* value = *rate* (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
rate = maximum strain rate for pressure control
*normalize/pressure* value = *yes* or *no* (ONLY available in :doc:`fix deform/pressure <fix_deform_pressure>` command)
Modifies pressure controls such that the deviation in pressure is normalized by the target pressure
Examples
""""""""
@ -88,6 +110,8 @@ Examples
fix 1 all deform 1 xy erate 0.001 remap v
fix 1 all deform 10 y delta -0.5 0.5 xz vel 1.0
See examples for :doc:`fix deform/pressure <fix_deform_pressure>` on its doc page
Description
"""""""""""
@ -95,29 +119,46 @@ Change the volume and/or shape of the simulation box during a dynamics
run. Orthogonal simulation boxes have 3 adjustable parameters
(x,y,z). Triclinic (non-orthogonal) simulation boxes have 6
adjustable parameters (x,y,z,xy,xz,yz). Any or all of them can be
adjusted independently and simultaneously by this command.
adjusted independently and simultaneously.
This fix can be used to perform non-equilibrium MD (NEMD) simulations
of a continuously strained system. See the :doc:`fix nvt/sllod <fix_nvt_sllod>` and :doc:`compute temp/deform <compute_temp_deform>` commands for more details. Note
that simulation of a continuously extended system (extensional flow)
can be modeled using the :ref:`UEF package <PKG-UEF>` and its :doc:`fix commands <fix_nh_uef>`.
The fix deform command allows use of all the arguments listed above,
except those flagged as available ONLY for the :doc:`fix
deform/pressure <fix_deform_pressure>` command, which are
pressure-based controls. The fix deform/pressure command allows use
of all the arguments listed above.
The rest of this doc page explains the options common to both
commands. The :doc:`fix deform/pressure <fix_deform_pressure>` doc
page explains the options available ONLY with the fix deform/pressure
command. Note that a simulation can define only a single deformation
command: fix deform or fix deform/pressure.
Both these fixes can be used to perform non-equilibrium MD (NEMD)
simulations of a continuously strained system. See the :doc:`fix
nvt/sllod <fix_nvt_sllod>` and :doc:`compute temp/deform
<compute_temp_deform>` commands for more details. Note that
simulation of a continuously extended system (extensional flow) can be
modeled using the :ref:`UEF package <PKG-UEF>` and its :doc:`fix
commands <fix_nh_uef>`.
For the *x*, *y*, *z* parameters, the associated dimension cannot be
shrink-wrapped. For the *xy*, *yz*, *xz* parameters, the associated
second dimension cannot be shrink-wrapped. Dimensions not varied by this
command can be periodic or non-periodic. Dimensions corresponding to
unspecified parameters can also be controlled by a :doc:`fix npt <fix_nh>` or :doc:`fix nph <fix_nh>` command.
second dimension cannot be shrink-wrapped. Dimensions not varied by
this command can be periodic or non-periodic. Dimensions
corresponding to unspecified parameters can also be controlled by a
:doc:`fix npt <fix_nh>` or :doc:`fix nph <fix_nh>` command.
The size and shape of the simulation box at the beginning of the
simulation run were either specified by the
:doc:`create_box <create_box>` or :doc:`read_data <read_data>` or
:doc:`read_restart <read_restart>` command used to setup the simulation
initially if it is the first run, or they are the values from the end
of the previous run. The :doc:`create_box <create_box>`, :doc:`read data <read_data>`, and :doc:`read_restart <read_restart>` commands
specify whether the simulation box is orthogonal or non-orthogonal
(triclinic) and explain the meaning of the xy,xz,yz tilt factors. If
fix deform changes the xy,xz,yz tilt factors, then the simulation box
must be triclinic, even if its initial tilt factors are 0.0.
simulation run were either specified by the :doc:`create_box
<create_box>` or :doc:`read_data <read_data>` or :doc:`read_restart
<read_restart>` command used to setup the simulation initially if it
is the first run, or they are the values from the end of the previous
run. The :doc:`create_box <create_box>`, :doc:`read data
<read_data>`, and :doc:`read_restart <read_restart>` commands specify
whether the simulation box is orthogonal or non-orthogonal (triclinic)
and explain the meaning of the xy,xz,yz tilt factors. If fix deform
changes the xy,xz,yz tilt factors, then the simulation box must be
triclinic, even if its initial tilt factors are 0.0.
As described below, the desired simulation box size and shape at the
end of the run are determined by the parameters of the fix deform
@ -258,21 +299,22 @@ of the units keyword below.
The *variable* style changes the specified box length dimension by
evaluating a variable, which presumably is a function of time. The
variable with *name1* must be an :doc:`equal-style variable <variable>`
and should calculate a change in box length in units of distance.
Note that this distance is in box units, not lattice units; see the
discussion of the *units* keyword below. The formula associated with
variable *name1* can reference the current timestep. Note that it
should return the "change" in box length, not the absolute box length.
This means it should evaluate to 0.0 when invoked on the initial
timestep of the run following the definition of fix deform. It should
evaluate to a value > 0.0 to dilate the box at future times, or a
value < 0.0 to compress the box.
variable with *name1* must be an :doc:`equal-style variable
<variable>` and should calculate a change in box length in units of
distance. Note that this distance is in box units, not lattice units;
see the discussion of the *units* keyword below. The formula
associated with variable *name1* can reference the current timestep.
Note that it should return the "change" in box length, not the
absolute box length. This means it should evaluate to 0.0 when
invoked on the initial timestep of the run following the definition of
fix deform. It should evaluate to a value > 0.0 to dilate the box at
future times, or a value < 0.0 to compress the box.
The variable *name2* must also be an :doc:`equal-style variable <variable>` and should calculate the rate of box length
change, in units of distance/time, i.e. the time-derivative of the
*name1* variable. This quantity is used internally by LAMMPS to reset
atom velocities when they cross periodic boundaries. It is computed
The variable *name2* must also be an :doc:`equal-style variable
<variable>` and should calculate the rate of box length change, in
units of distance/time, i.e. the time-derivative of the *name1*
variable. This quantity is used internally by LAMMPS to reset atom
velocities when they cross periodic boundaries. It is computed
internally for the other styles, but you must provide it when using an
arbitrary variable.
@ -414,12 +456,13 @@ can reference the current timestep. Note that it should return the
should evaluate to 0.0 when invoked on the initial timestep of the run
following the definition of fix deform.
The variable *name2* must also be an :doc:`equal-style variable <variable>` and should calculate the rate of tilt change,
in units of distance/time, i.e. the time-derivative of the *name1*
variable. This quantity is used internally by LAMMPS to reset atom
velocities when they cross periodic boundaries. It is computed
internally for the other styles, but you must provide it when using an
arbitrary variable.
The variable *name2* must also be an :doc:`equal-style variable
<variable>` and should calculate the rate of tilt change, in units of
distance/time, i.e. the time-derivative of the *name1* variable. This
quantity is used internally by LAMMPS to reset atom velocities when
they cross periodic boundaries. It is computed internally for the
other styles, but you must provide it when using an arbitrary
variable.
Here is an example of using the *variable* style to perform the same
box deformation as the *wiggle* style formula listed above, where we
@ -510,33 +553,40 @@ box without explicit remapping of their coordinates.
.. note::
For non-equilibrium MD (NEMD) simulations using "remap v" it is
usually desirable that the fluid (or flowing material, e.g. granular
particles) stream with a velocity profile consistent with the
deforming box. As mentioned above, using a thermostat such as :doc:`fix nvt/sllod <fix_nvt_sllod>` or :doc:`fix lavgevin <fix_langevin>`
(with a bias provided by :doc:`compute temp/deform <compute_temp_deform>`), will typically accomplish
that. If you do not use a thermostat, then there is no driving force
pushing the atoms to flow in a manner consistent with the deforming
box. E.g. for a shearing system the box deformation velocity may vary
usually desirable that the fluid (or flowing material,
e.g. granular particles) stream with a velocity profile consistent
with the deforming box. As mentioned above, using a thermostat
such as :doc:`fix nvt/sllod <fix_nvt_sllod>` or :doc:`fix lavgevin
<fix_langevin>` (with a bias provided by :doc:`compute temp/deform
<compute_temp_deform>`), will typically accomplish that. If you do
not use a thermostat, then there is no driving force pushing the
atoms to flow in a manner consistent with the deforming box.
E.g. for a shearing system the box deformation velocity may vary
from 0 at the bottom to 10 at the top of the box. But the stream
velocity profile of the atoms may vary from -5 at the bottom to +5 at
the top. You can monitor these effects using the :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`compute temp/deform <compute_temp_deform>`, and :doc:`compute temp/profile <compute_temp_profile>` commands. One way to induce
atoms to stream consistent with the box deformation is to give them an
velocity profile of the atoms may vary from -5 at the bottom to +5
at the top. You can monitor these effects using the :doc:`fix
ave/chunk <fix_ave_chunk>`, :doc:`compute temp/deform
<compute_temp_deform>`, and :doc:`compute temp/profile
<compute_temp_profile>` commands. One way to induce atoms to
stream consistent with the box deformation is to give them an
initial velocity profile, via the :doc:`velocity ramp <velocity>`
command, that matches the box deformation rate. This also typically
helps the system come to equilibrium more quickly, even if a
thermostat is used.
command, that matches the box deformation rate. This also
typically helps the system come to equilibrium more quickly, even
if a thermostat is used.
.. note::
If a :doc:`fix rigid <fix_rigid>` is defined for rigid bodies, and
*remap* is set to *x*, then the center-of-mass coordinates of rigid
bodies will be remapped to the changing simulation box. This will be
done regardless of whether atoms in the rigid bodies are in the fix
deform group or not. The velocity of the centers of mass are not
remapped even if *remap* is set to *v*, since :doc:`fix nvt/sllod <fix_nvt_sllod>` does not currently do anything special
bodies will be remapped to the changing simulation box. This will
be done regardless of whether atoms in the rigid bodies are in the
fix deform group or not. The velocity of the centers of mass are
not remapped even if *remap* is set to *v*, since :doc:`fix
nvt/sllod <fix_nvt_sllod>` does not currently do anything special
for rigid particles. If you wish to perform a NEMD simulation of
rigid particles, you can either thermostat them independently or
include a background fluid and thermostat the fluid via :doc:`fix nvt/sllod <fix_nvt_sllod>`.
include a background fluid and thermostat the fluid via :doc:`fix
nvt/sllod <fix_nvt_sllod>`.
The *flip* keyword allows the tilt factors for a triclinic box to
exceed half the distance of the parallel box length, as discussed
@ -568,7 +618,8 @@ command if you want to include lattice spacings in a variable formula.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix will restore the initial box settings from :doc:`binary restart files <restart>`, which allows the fix to be properly continue
This fix will restore the initial box settings from :doc:`binary
restart files <restart>`, which allows the fix to be properly continue
deformation, when using the start/stop options of the :doc:`run <run>`
command. None of the :doc:`fix_modify <fix_modify>` options are
relevant to this fix. No global or per-atom quantities are stored by
@ -586,12 +637,14 @@ Restrictions
You cannot apply x, y, or z deformations to a dimension that is
shrink-wrapped via the :doc:`boundary <boundary>` command.
You cannot apply xy, yz, or xz deformations to a second dimension (y in
xy) that is shrink-wrapped via the :doc:`boundary <boundary>` command.
You cannot apply xy, yz, or xz deformations to a second dimension (y
in xy) that is shrink-wrapped via the :doc:`boundary <boundary>`
command.
Related commands
""""""""""""""""
:doc:`fix deform/pressure <fix_deform_pressure>`,
:doc:`change_box <change_box>`
Default

319
doc/src/fix_deform_pressure.rst Normal file
View File

@ -0,0 +1,319 @@
.. index:: fix deform/pressure
fix deform/pressure command
===========================
Syntax
""""""
.. parsed-literal::
fix ID group-ID deform/pressure N parameter style args ... keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* deform/pressure = style name of this fix command
* N = perform box deformation every this many timesteps
* one or more parameter/arg sequences may be appended
.. parsed-literal::
parameter = *x* or *y* or *z* or *xy* or *xz* or *yz* or *box*
*x*, *y*, *z* args = style value(s)
style = *final* or *delta* or *scale* or *vel* or *erate* or *trate* or *volume* or *wiggle* or *variable* or *pressure* or *pressure/mean*
*pressure* values = target gain
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
*pressure/mean* values = target gain
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
NOTE: All other styles are documented by the :doc:`fix deform <fix_deform>` command
*xy*, *xz*, *yz* args = style value
style = *final* or *delta* or *vel* or *erate* or *trate* or *wiggle* or *variable* or *pressure*
*pressure* values = target gain
target = target pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
NOTE: All other styles are documented by the :doc:`fix deform <fix_deform>` command
*box* = style value
style = *volume* or *pressure*
*volume* value = none = isotropically adjust system to preserve volume of system
*pressure* values = target gain
target = target mean pressure (pressure units)
gain = proportional gain constant (1/(time * pressure) or 1/time units)
* zero or more keyword/value pairs may be appended
* keyword = *remap* or *flip* or *units* or *couple* or *vol/balance/p* or *max/rate* or *normalize/pressure*
.. parsed-literal::
*couple* value = *none* or *xyz* or *xy* or *yz* or *xz*
couple pressure values of various dimensions
*vol/balance/p* value = *yes* or *no*
Modifies the behavior of the *volume* option to try and balance pressures
*max/rate* value = *rate*
rate = maximum strain rate for pressure control
*normalize/pressure* value = *yes* or *no*
Modifies pressure controls such that the deviation in pressure is normalized by the target pressure
NOTE: All other keywords are documented by the :doc:`fix deform <fix_deform>` command
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all deform/pressure 1 x pressure 2.0 0.1 normalize/pressure yes max/rate 0.001
fix 1 all deform/pressure 1 x trate 0.1 y volume z volume vol/balance/p yes
fix 1 all deform/pressure 1 x trate 0.1 y pressure/mean 0.0 1.0 z pressure/mean 0.0 1.0
Description
"""""""""""
.. versionadded:: TBD
This fix is an extension of the :doc:`fix deform <fix_deform>`
command, which allows all of its options to be used as well as new
pressure-based controls implemented by this command.
All arguments described on the :doc:`fix deform <fix_deform>` doc page
also apply to this fix unless otherwise noted below. The rest of this
doc page explains the arguments specific to this fix. Note that a
simulation can define only a single deformation command: fix deform or
fix deform/pressure.
----------
For the *x*, *y*, and *z* parameters, this is the meaning of the
styles and values provided by this fix.
The *pressure* style adjusts a dimension's box length to control the
corresponding component of the pressure tensor. This option attempts to
maintain a specified target pressure using a linear controller where the
box length :math:`L` evolves according to the equation
.. parsed-literal::
\frac{d L(t)}{dt} = L(t) k (P_t - P)
where :math:`k` is a proportional gain constant, :math:`P_t` is the target
pressure, and :math:`P` is the current pressure along that dimension. This
approach is similar to the method used to control the pressure by
:doc:`fix press/berendsen <fix_press_berendsen>`. The target pressure
accepts either a constant numeric value or a LAMMPS :ref:`variable <variable>`.
Notably, this variable can be a function of time or other components of
the pressure tensor. By default, :math:`k` has units of 1/(time * pressure)
although this will change if the *normalize/pressure* option is set as
:ref:`discussed below <deform_normalize>`. There is no proven method
to choosing an appropriate value of :math:`k` as it will depend on the
specific details of a simulation. Testing different values is recommended.
By default, there is no limit on the resulting strain rate in any dimension.
A maximum limit can be applied using the :ref:`max/rate <deform_max_rate>`
option. Akin to :doc:`fix nh <fix_nh>`, pressures in different dimensions
can be coupled using the :ref:`couple <deform_couple>` option. This means
the instantaneous pressure along coupled dimensions are averaged and the box
strains identically along the coupled dimensions.
The *pressure/mean* style changes a dimension's box length to maintain
a constant mean pressure defined as the trace of the pressure tensor.
This option has identical arguments to the *pressure* style and a similar
functional equation, except the current and target pressures refer to the
mean trace of the pressure tensor. All options for the *pressure* style
also apply to the *pressure/mean* style except for the
:ref:`couple <deform_couple>` option.
Note that while this style can be identical to coupled *pressure* styles,
it is generally not the same. For instance in 2D, a coupled *pressure*
style in the *x* and *y* dimensions would be equivalent to using the
*pressure/mean* style with identical settings in each dimension. However,
it would not be the same if settings (e.g. gain constants) were used in
the *x* and *y* dimensions or if the *pressure/mean* command was only applied
along one dimension.
----------
For the *xy*, *xz*, and *yz* parameters, this is the meaning of the
styles and values provided by this fix. Note that changing the
tilt factors of a triclinic box does not change its volume.
The *pressure* style adjusts a tilt factor to control the corresponding
off-diagonal component of the pressure tensor. This option attempts to
maintain a specified target value using a linear controller where the
tilt factor T evolves according to the equation
.. parsed-literal::
\frac{d T(t)}{dt} = L(t) k (P - P_t)
where :math:`k` is a proportional gain constant, :math:`P_t` is the
target pressure, :math:`P` is the current pressure, and :math:`L` is
the perpendicular box length. The target pressure accepts either a
constant numeric value or a LAMMPS :ref:`variable
<variable>`. Notably, this variable can be a function of time or other
components of the pressure tensor. By default, :math:`k` has units of
1/(time * pressure) although this will change if the
*normalize/pessure* option is set as :ref:`discussed below
<deform_normalize>`. There is no proven method to choosing an
appropriate value of :math:`k` as it will depend on the specific
details of a simulation and testing different values is
recommended. One can also apply a maximum limit to the magnitude of
the applied strain using the :ref:`max/rate <deform_max_rate>` option.
----------
The *box* parameter provides an additional control over the *x*, *y*,
and *z* box lengths by isotropically dilating or contracting the box
to either maintain a fixed mean pressure or volume. This isotropic
scaling is applied after the box is deformed by the above *x*, *y*,
*z*, *xy*, *xz*, and *yz* styles, acting as a second deformation
step. This parameter will change the overall strain rate in the *x*,
*y*, or *z* dimensions. This parameter can only be used in
combination with the *x*, *y*, or *z* commands: *vel*, *erate*,
*trate*, *pressure*, or *wiggle*. This is the meaning of its styles
and values.
The *volume* style isotropically scales box lengths to maintain a constant
box volume in response to deformation from other parameters. This style
may be useful in scenarios where one wants to apply a constant deviatoric
pressure using *pressure* styles in the *x*, *y*, and *z* dimensions (
deforming the shape of the box), while maintaining a constant volume.
The *pressure* style isotropically scales box lengths in an attempt to
maintain a target mean pressure (the trace of the pressure tensor) of the
system. This is accomplished by isotropically scaling all box lengths
:math:`L` by an additional factor of :math:`k (P_t - P_m)` where :math:`k`
is the proportional gain constant, :math:`P_t` is the target pressure, and
:math:`P_m` is the current mean pressure. This style may be useful in
scenarios where one wants to apply a constant deviatoric strain rate
using various strain-based styles (e.g. *trate*) along the *x*, *y*, and *z*
dimensions (deforming the shape of the box), while maintaining a mean pressure.
----------
The optional keywords provided by this fix are described below.
.. _deform_normalize:
The *normalize/pressure* keyword changes how box dimensions evolve when
using the *pressure* or *pressure/mean* deformation styles. If the
*deform/normalize* value is set to *yes*, then the deviation from the
target pressure is normalized by the absolute value of the target
pressure such that the proportional gain constant scales a percentage
error and has units of 1/time. If the target pressure is ever zero, this
will produce an error unless the *max/rate* keyword is defined,
described below, which will cap the divergence.
.. _deform_max_rate:
The *max/rate* keyword sets an upper threshold, *rate*, that limits the
maximum magnitude of the instantaneous strain rate applied in any dimension.
This keyword only applies to the *pressure* and *pressure/mean* options. If
a pressure-controlled rate is used for both *box* and either *x*, *y*, or
*z*, then this threshold will apply separately to each individual controller
such that the cumulative strain rate on a box dimension may be up to twice
the value of *rate*.
.. _deform_couple:
The *couple* keyword allows two or three of the diagonal components of
the pressure tensor to be "coupled" together for the *pressure* option.
The value specified with the keyword determines which are coupled. For
example, *xz* means the *Pxx* and *Pzz* components of the stress tensor
are coupled. *Xyz* means all 3 diagonal components are coupled. Coupling
means two things: the instantaneous stress will be computed as an average
of the corresponding diagonal components, and the coupled box dimensions
will be changed together in lockstep, meaning coupled dimensions will be
dilated or contracted by the same percentage every timestep. If a *pressure*
style is defined for more than one coupled dimension, the target pressures
and gain constants must be identical. Alternatively, if a *pressure*
style is only defined for one of the coupled dimensions, its settings are
copied to other dimensions with undefined styles. *Couple xyz* can be used
for a 2d simulation; the *z* dimension is simply ignored.
.. _deform_balance:
The *vol/balance/p* keyword modifies the behavior of the *volume* style when
applied to two of the *x*, *y*, and *z* dimensions. Instead of straining
the two dimensions in lockstep, the two dimensions are allowed to
separately dilate or contract in a manner to maintain a constant
volume while simultaneously trying to keep the pressure along each
dimension equal using a method described in :ref:`(Huang2014) <Huang2014>`.
----------
If any pressure controls are used, this fix computes a temperature and
pressure each timestep. To do this, the fix creates its own computes
of style "temp" and "pressure", as if these commands had been issued:
.. code-block:: LAMMPS
compute fix-ID_temp group-ID temp
compute fix-ID_press group-ID pressure fix-ID_temp
See the :doc:`compute temp <compute_temp>` and :doc:`compute pressure
<compute_pressure>` commands for details. Note that the IDs of the
new computes are the fix-ID + underscore + "temp" or fix_ID
+ underscore + "press", and the group for the new computes is the same
as the fix group.
Note that these are NOT the computes used by thermodynamic output (see
the :doc:`thermo_style <thermo_style>` command) with ID =
*thermo_temp* and *thermo_press*. This means you can change the
attributes of this fix's temperature or pressure via the
:doc:`compute_modify <compute_modify>` command or print this
temperature or pressure during thermodynamic output via the
:doc:`thermo_style custom <thermo_style>` command using the
appropriate compute-ID. It also means that changing attributes of
*thermo_temp* or *thermo_press* will have no effect on this fix.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix will restore the initial box settings from :doc:`binary
restart files <restart>`, which allows the fix to be properly continue
deformation, when using the start/stop options of the :doc:`run <run>`
command. No global or per-atom quantities are stored by this fix for
access by various :doc:`output commands <Howto_output>`.
If any pressure controls are used, the :doc:`fix_modify <fix_modify>`
*temp* and *press* options are supported by this fix, unlike in
:doc:`fix deform <fix_deform>`. You can use them to assign a
:doc:`compute <compute>` you have defined to this fix which will be
used in its temperature and pressure calculations. If you do this,
note that the kinetic energy derived from the compute temperature
should be consistent with the virial term computed using all atoms for
the pressure. LAMMPS will warn you if you choose to compute
temperature on a subset of atoms.
This fix can perform deformation over multiple runs, using the *start*
and *stop* keywords of the :doc:`run <run>` command. See the
:doc:`run <run>` command for details of how to do this.
This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
You cannot apply x, y, or z deformations to a dimension that is
shrink-wrapped via the :doc:`boundary <boundary>` command.
You cannot apply xy, yz, or xz deformations to a second dimension (y
in xy) that is shrink-wrapped via the :doc:`boundary <boundary>`
command.
Related commands
""""""""""""""""
:doc:`fix deform <fix_deform>`, :doc:`change_box <change_box>`
Default
"""""""
The option defaults are normalize/pressure = no.
----------
.. _Huang2014:
**(Huang2014)** X. Huang, "Exploring critical-state behavior using DEM",
Doctoral dissertation, Imperial College. (2014). https://doi.org/10.25560/25316

26
doc/src/fix_electrode.rst
View File

@ -45,7 +45,7 @@ Syntax
rng_v = integer used to initialize random number generator
* zero or more keyword/value pairs may be appended
* keyword = *algo* or *symm* or *couple* or *etypes* or *ffield* or *write_mat* or *write_inv* or *read_mat* or *read_inv*
* keyword = *algo* or *symm* or *couple* or *etypes* or *ffield* or *write_mat* or *write_inv* or *read_mat* or *read_inv* or *qtotal* or *eta*
.. parsed-literal::
@ -68,6 +68,10 @@ Syntax
filename = file from which to read elastance matrix
*read_inv* value = filename
filename = file from which to read inverted matrix
*qtotal* value = number or *v_* equal-style variable
add overall potential so that all electrode charges add up to *qtotal*
*eta* value = d_propname
d_propname = a custom double vector defined via fix property/atom
Examples
""""""""
@ -249,6 +253,26 @@ be enabled if any electrode particle has the same type as any
electrolyte particle (which would be unusual in a typical simulation)
and the fix will issue an error in that case.
.. versionadded:: TBD
The keyword *qtotal* causes *fix electrode/conp* and *fix electrode/thermo*
to add an overall potential to all electrodes so that the total charge on
the electrodes is a specified amount (which may be an equal-style variable).
For example, if a user wanted to simulate a solution of excess cations
such that the total electrolyte charge is +2, setting *qtotal -2* would cause
the total electrode charge to be -2, so that the simulation box remains overall
electroneutral. Since *fix electrode/conq* constrains the total charges of
individual electrodes, and since *symm on* constrains the total charge of all
electrodes to be zero, either option is incompatible with the *qtotal* keyword
(even if *qtotal* is set to zero).
.. versionadded:: TBD
The keyword *eta* takes the name of a custom double vector defined via fix
property/atom. The values will be used instead of the standard eta value. The
property/atom fix must be for vector of double values and use the *ghost on*
option.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

5
doc/src/fix_gcmc.rst
View File

@ -440,8 +440,11 @@ This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
This fix style requires an :doc:`atom style <atom_style>` with per atom
type masses.
Do not set "neigh_modify once yes" or else this fix will never be
called. Reneighboring is required.
called. Reneighboring is **required**.
Only usable for 3D simulations.

4
doc/src/fix_nonaffine_displacement.rst
View File

@ -86,8 +86,8 @@ Both of these methods require defining a reference state. With the *fixed* refer
style, the user picks a specific timestep *nstep* at which particle positions are saved.
If peratom data is accessed from this compute prior to this timestep, it will simply be
zeroed. The *update* reference style implies the reference state will be updated every
*nstep* timesteps. The *offset* reference only applies to the *d2min* metric and will
update the reference state *nstep* timesteps before a multiple of *nevery* timesteps.
*nstep* timesteps. The *offset* reference will update the reference state *nstep*
timesteps before a multiple of *nevery* timesteps.
----------

17
doc/src/fix_property_atom.rst
View File

@ -22,6 +22,8 @@ Syntax
*mol* = molecule IDs
*q* = charge
*rmass* = per-atom mass
*temperature* = internal temperature of atom
*heatflow* = internal heat flow of atom
i_name = new integer vector referenced by name
d_name = new floating-point vector referenced by name
i2_name = new integer array referenced by name
@ -59,14 +61,18 @@ these properties for each atom in the system when a data file is read.
This fix augments the set of per-atom properties with new custom
ones. This can be useful in several scenarios.
If the atom style does not define molecule IDs, per-atom charge, or
per-atom mass, they can be added using the *mol*\ , *q* or *rmass*
If the atom style does not define molecule IDs, per-atom charge,
per-atom mass, internal temperature, or internal heat flow, they can
be added using the *mol*\ , *q*, *rmass*, *temperature*, or *heatflow*
keywords. This could be useful to define "molecules" to use as rigid
bodies with the :doc:`fix rigid <fix_rigid>` command, or to carry
around an extra flag with atoms (stored as a molecule ID) that can be
used by various commands like :doc:`compute chunk/atom
<compute_chunk_atom>` to group atoms without having to use the group
command (which is limited to a total of 32 groups including *all*\ ).
For finite-size particles, an internal temperature and heat flow can
be used to model heat conduction as in the
:doc:`GRANULAR package <Howto_granular>`.
Another application is to use the *rmass* flag in order to have
per-atom masses instead of per-type masses. This could be used to
@ -85,9 +91,10 @@ properties that are not needed such as bond lists, which incurs some
overhead when there are no bonds.
In the future, we may add additional existing per-atom properties to
fix property/atom, similar to *mol*\ , *q* or *rmass*\ , which
"turn-on" specific properties defined by some atom styles, so they can
be easily used by atom styles that do not define them.
fix property/atom, similar to *mol*\ , *q*, *rmass*\ , *temperature*\ ,
or *heatflow* which "turn-on" specific properties defined by some atom
styles, so they can be easily used by atom styles that do not define
them.
More generally, the *i_name* and *d_name* options allow one or more
new custom per-atom vectors to be defined. Likewise the *i2_name* and

3
doc/src/fix_sgcmc.rst
View File

@ -155,6 +155,9 @@ This fix is part of the MC package. It is only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
page for more info.
This fix style requires an :doc:`atom style <atom_style>` with per atom
type masses.
At present the fix provides optimized subroutines for EAM type
potentials (see above) that calculate potential energy changes due to
*local* atom type swaps very efficiently. Other potentials are

28
doc/src/fix_ttm.rst
View File

@ -96,11 +96,11 @@ each processor, which is acceptable when the overall grid is reasonably
small. For larger grids you should use fix *ttm/grid* instead.
Fix *ttm/mod* adds options to account for external heat sources (e.g. at
a surface) and for specifying parameters that allow the electronic
heat capacity to depend strongly on electronic temperature. It is
more expensive computationally than fix *ttm* because it treats the
thermal diffusion equation as non-linear. More details on fix *ttm/mod*
are given below.
a surface) and for specifying parameters that allow the electronic heat
capacity to depend strongly on electronic temperature. It is more
expensive computationally than fix *ttm* because it treats the thermal
diffusion equation as non-linear. More details on fix *ttm/mod* are
given below.
Heat transfer between the electronic and atomic subsystems is carried
out via an inhomogeneous Langevin thermostat. Only atoms in the fix
@ -303,15 +303,15 @@ The current fix ttm/mod implementation allows TTM simulations with a
vacuum. The vacuum region is defined as the grid cells with zero
electronic temperature. The numerical scheme does not allow energy
exchange with such cells. Since the material can expand to previously
unoccupied region in some simulations, the vacuum border can be
allowed to move. It is controlled by the *surface_movement* parameter
in the *init_file*. If it is set to 1, then "vacuum" cells can be
changed to "electron-filled" cells with the temperature *T_e_min* if
atoms move into them (currently only implemented for the case of
1-dimensional motion of flat surface normal to the X axis). The
initial borders of vacuum can be set in the *init_file* via *lsurface*
and *rsurface* parameters. In this case, electronic pressure gradient
is calculated as
unoccupied region in some simulations, the vacuum border can be allowed
to move. It is controlled by the *surface_movement* parameter in the
*init_file*. If it is set to 1, then "vacuum" cells can be changed to
"electron-filled" cells with the temperature *T_e_min* if atoms move
into them (currently only implemented for the case of 1-dimensional
motion of a flat surface normal to the X axis). The initial locations of
the interfaces of the electron density to the vacuum can be set in the
*init_file* via *lsurface* and *rsurface* parameters. In this case,
electronic pressure gradient is calculated as
.. math::

175
doc/src/fix_wall_flow.rst Normal file
View File

@ -0,0 +1,175 @@
.. index:: fix wall/flow
.. index:: fix wall/flow/kk
fix wall/flow command
=====================
Accelerator Variants: *wall/flow/kk*
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID wall/flow axis vflow T seed N coords ... keyword value
* ID, group-ID are documented in :doc:`fix <fix>` command
* wall/flow = style name of this fix command
* axis = flow axis (*x*, *y*, or *z*)
* vflow = generated flow velocity in *axis* direction (velocity units)
* T = flow temperature (temperature units)
* seed = random seed for stochasticity (positive integer)
* N = number of walls
* coords = list of N wall positions along the *axis* direction in ascending order (distance units)
* zero or more keyword/value pairs may be appended
* keyword = *units*
.. parsed-literal::
*units* value = *lattice* or *box*
*lattice* = wall positions are defined in lattice units
*box* = the wall positions are defined in simulation box units
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all wall/flow x 0.4 1.5 593894 4 2.0 4.0 6.0 8.0
Description
"""""""""""
.. versionadded:: TBD
This fix implements flow boundary conditions (FBC) introduced in
:ref:`(Pavlov1) <fbc-Pavlov1>` and :ref:`(Pavlov2) <fbc-Pavlov2>`.
The goal is to generate a stationary flow with a shifted Maxwell
velocity distribution:
.. math::
f_a(v_a) \propto \exp{\left(-\frac{m (v_a-v_{\text{flow}})^2}{2 kB T}\right)}
where :math:`v_a` is the component of velocity along the specified
*axis* argument (a = x,y,z), :math:`v_{\text{flow}}` is the flow
velocity specified as the *vflow* argument, *T* is the specified flow
temperature, *m* is the particle mass, and *kB* is the Boltzmann
constant.
This is achieved by defining a series of *N* transparent walls along
the flow *axis* direction. Each wall is at the specified position
listed in the *coords* argument. Note that an additional transparent
wall is defined by the code at the boundary of the (periodic)
simulation domain in the *axis* direction. So there are effectively
N+1 walls.
Each time a particle in the specified group passes through one of the
transparent walls, its velocity is re-assigned. Particles not in the
group do not interact with the wall. This can be used, for example, to
add obstacles composed of atoms, or to simulate a solution of complex
molecules in a one-atom liquid (note that the fix has been tested for
one-atom systems only).
Conceptually, the velocity re-assignment represents creation of a new
particle within the system with simultaneous removal of the particle
which passed through the wall. The velocity components in directions
parallel to the wall are re-assigned according to the standard Maxwell
velocity distribution for the specified temperature *T*. The velocity
component perpendicular to the wall is re-assigned according to the
shifted Maxwell distribution defined above:
.. math::
f_{\text{a generated}}(v_a) \propto v_a f_a(v_a)
It can be shown that for an ideal-gas scenario this procedure makes
the velocity distribution of particles between walls exactly as
desired.
Since in most cases simulated systems are not an ideal gas, multiple
walls can be defined, since a single wall may not be sufficient for
maintaining a stationary flow without "congestion" which can manifest
itself as regions in the flow with increased particle density located
upstream from static obstacles.
For the same reason, the actual temperature and velocity of the
generated flow may differ from what is requested. The degree of
discrepancy is determined by how different from an ideal gas the
simulated system is. Therefore, a calibration procedure may be
required for such a system as described in :ref:`(Pavlov)
<fbc-Pavlov2>`.
Note that the interactions between particles on different sides of a
transparent wall are not disabled or neglected. Likewise particle
positions are not altered by the velocity reassignment. This removes
the need to modify the force field to work correctly in cases when a
particle is close to a wall.
For example, if particle positions were uniformly redistributed across
the surface of a wall, two particles could end up too close to each
other, potentially causing the simulation to explode. However due to
this compromise, some collective phenomena such as regions with
increased/decreased density or collective movements are not fully
removed when particles cross a wall. This unwanted consequence can
also be potentially mitigated by using more multiple walls.
.. note::
When the specified flow has a high velocity, a lost atoms error can
occur (see :doc:`error messages <Errors_messages>`). If this
happens, you should ensure the checks for neighbor list rebuilds,
set via the :doc:`neigh_modify <neigh_modify>` command, are as
conservative as possible (every timestep if needed). Those are the
default settings.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`.
None of the :doc:`fix_modify <fix_modify>` options are relevant to
this fix.
No global or per-atom quantities are stored by this fix for access by
various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
This fix is not invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
Fix *wall_flow* is part of the EXTRA-FIX package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Flow boundary conditions should not be used with rigid bodies such as
those defined by a "fix rigid" command.
This fix can only be used with periodic boundary conditions along the
flow axis. The size of the box in this direction must not change. Also,
the fix is designed to work only in an orthogonal simulation box.
Related commands
""""""""""""""""
:doc:`fix wall/reflect <fix_wall>` command
Default
"""""""
The default for the units keyword is lattice.
----------
.. _fbc-Pavlov1:
**(Pavlov1)** Pavlov, Kolotinskii, Stegailov, "GPU-Based Molecular Dynamics of Turbulent Liquid Flows with OpenMM", Proceedings of PPAM-2022, LNCS (Springer), vol. 13826, pp. 346-358 (2023)
.. _fbc-Pavlov2:
**(Pavlov2)** Pavlov, Galigerov, Kolotinskii, Nikolskiy, Stegailov, "GPU-based Molecular Dynamics of Fluid Flows: Reaching for Turbulence", Int. J. High Perf. Comp. Appl., (2024)

7
doc/src/fix_widom.rst
View File

@ -195,8 +195,11 @@ doc page for more info.
Do not set "neigh_modify once yes" or else this fix will never be
called. Reneighboring is **required**.
Can be run in parallel, but aspects of the GCMC part will not scale well
in parallel. Only usable for 3D simulations.
This fix style requires an :doc:`atom style <atom_style>` with per atom
type masses.
Can be run in parallel, but some aspects of the insertion procedure
will not scale well in parallel. Only usable for 3D simulations.
Related commands

14
doc/src/pair_airebo.rst
View File

@ -156,7 +156,7 @@ pair_coeff command:
The first 2 arguments must be \* \* so as to span all LAMMPS atom types.
The first three C arguments map LAMMPS atom types 1,2,3 to the C
element in the AIREBO file. The final H argument maps LAMMPS atom
type 4 to the H element in the SW file. If a mapping value is
type 4 to the H element in the AIREBO file. If a mapping value is
specified as NULL, the mapping is not performed. This can be used
when a *airebo* potential is used as part of the *hybrid* pair style.
The NULL values are placeholders for atom types that will be used with
@ -222,12 +222,12 @@ enabled if LAMMPS was built with that package. See the :doc:`Build package <Bui
These pair potentials require the :doc:`newton <newton>` setting to be
"on" for pair interactions.
The CH.airebo and CH.airebo-m potential files provided with LAMMPS
(see the potentials directory) are parameterized for metal :doc:`units <units>`.
You can use the AIREBO, AIREBO-M or REBO potential with any LAMMPS units,
but you would need to create your own AIREBO or AIREBO-M potential file
with coefficients listed in the appropriate units, if your simulation
does not use "metal" units.
The CH.airebo and CH.airebo-m potential files provided with LAMMPS (see
the potentials directory) are parameterized for metal :doc:`units
<units>`. You can use the pair styles with *any* LAMMPS units, but you
would need to create your own AIREBO or AIREBO-M potential file with
coefficients listed in the appropriate units, if your simulation does
not use "metal" units.
The pair styles provided here **only** support potential files parameterized
for the elements carbon and hydrogen (designated with "C" and "H" in the

8
doc/src/pair_dsmc.rst
View File

@ -138,8 +138,12 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This style is part of the MC package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This pair style is part of the MC package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This pair style requires an :doc:`atom style <atom_style>` with per
atom type masses.
Related commands
""""""""""""""""

4
doc/src/pair_meam.rst
View File

@ -427,8 +427,8 @@ package. They are only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
The maximum number of elements, that can be read from the MEAM library
file, is determined at compile time. The default is 5. If you need
support for more elements, you have to change the the constant 'maxelt'
file, is determined at compile time. The default is 8. If you need
support for more elements, you have to change the the constant 'MAXELT'
at the beginning of the file ``src/MEAM/meam.h`` and update/recompile
LAMMPS. There is no limit on the number of atoms types.

150
doc/src/pair_rebomos.rst Normal file
View File

@ -0,0 +1,150 @@
.. index:: pair_style rebomos
.. index:: pair_style rebomos/omp
pair_style rebomos command
==========================
Accelerator Variants: *rebomos/omp*
Syntax
""""""
.. code-block:: LAMMPS
pair_style rebomos
* rebomos = name of this pair style
Examples
""""""""
.. code-block:: LAMMPS
pair_style rebomos
pair_coeff * * ../potentials/MoS.rebomos Mo S
Example input scripts available: examples/threebody/
Description
"""""""""""
.. versionadded:: TBD
The *rebomos* pair style computes the interactions between molybdenum
and sulfur atoms :ref:`(Stewart) <Stewart>` utilizing an adaptive
interatomic reactive empirical bond order potential that is similar in
form to the AIREBO potential :ref:`(Stuart) <Stuart2>`. The potential
is based on an earlier parameterizations for :math:`\text{MoS}_2`
developed by :ref:`(Liang) <Liang>`.
The REBOMoS potential consists of two terms:
.. math::
E & = \frac{1}{2} \sum_i \sum_{j \neq i}
\left[ E^{\text{REBO}}_{ij} + E^{\text{LJ}}_{ij} \right] \\
The :math:`E^{\text{REBO}}` term describes the covalently bonded
interactions between Mo and S atoms while the :math:`E^{\text{LJ}}` term
describes longer range dispersion forces between layers. A cubic spline
function is applied to smoothly switch between covalent bonding at short
distances to dispersion interactions at longer distances. This allows
the model to capture bond formation and breaking events which may occur
between adjacent MoS2 layers, edges, defects, and more.
----------
Only a single pair_coeff command is used with the *rebomos* pair style
which specifies an REBOMoS potential file with parameters for Mo and S.
These are mapped to LAMMPS atom types by specifying N additional
arguments after the filename in the pair_coeff command, where N is the
number of LAMMPS atom types:
* filename
* :math:`N` element names = mapping of REBOMoS elements to atom types
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways
to specify the path for the potential file.
As an example, if your LAMMPS simulation has three atom types and you want
the first two to be Mo, and the third to be S, you would use the following
pair_coeff command:
.. code-block:: LAMMPS
pair_coeff * * MoS.rebomos Mo Mo S
The first 2 arguments must be \* \* so as to span all LAMMPS atom types.
The first two Mo arguments map LAMMPS atom types 1 and 2 to the Mo
element in the REBOMoS file. The final S argument maps LAMMPS atom type
3 to the S element in the REBOMoS file. If a mapping value is specified
as NULL, the mapping is not performed. This can be used when a
*rebomos* potential is used as part of the *hybrid* pair style. The
NULL values are placeholders for atom types that will be used with other
potentials.
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair style does not support the :doc:`pair_modify <pair_modify>`
mix, shift, table, and tail options.
This pair style does not write their information to :doc:`binary restart
files <restart>`, since it is stored in potential files. Thus, you need
to re-specify the pair_style and pair_coeff commands in an input script
that reads a restart file.
This pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. It does not support the
*inner*, *middle*, *outer* keywords.
Restrictions
""""""""""""
This pair style is part of the MANYBODY package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
These pair potentials require the :doc:`newton <newton>` setting to be
"on" for pair interactions.
The MoS.rebomos potential file provided with LAMMPS (see the potentials
directory) is parameterized for metal :doc:`units <units>`. You can use
the *rebomos* pair style with any LAMMPS units setting, but you would
need to create your own REBOMoS potential file with coefficients listed
in the appropriate units.
The pair style provided here **only** supports potential files parameterized
for the elements molybdenum and sulfur (designated with "Mo" and "S" in the
*pair_coeff* command. Using potential files for other elements will trigger
an error.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair style rebo <pair_airebo>`
Default
"""""""
none
----------
.. _Stewart:
**(Steward)** Stewart, Spearot, Modelling Simul. Mater. Sci. Eng. 21, 045003, (2013).
.. _Stuart2:
**(Stuart)** Stuart, Tutein, Harrison, J Chem Phys, 112, 6472-6486, (2000).
.. _Liang:
**(Liang)** Liang, Phillpot, Sinnott Phys. Rev. B79 245110, (2009), Erratum: Phys. Rev. B85 199903(E), (2012)

1
doc/src/pair_style.rst
View File

@ -333,6 +333,7 @@ accelerated styles exist.
* :doc:`rann <pair_rann>` -
* :doc:`reaxff <pair_reaxff>` - ReaxFF potential
* :doc:`rebo <pair_airebo>` - second generation REBO potential of Brenner
* :doc:`rebomos <pair_rebomos>` - REBOMoS potential for MoS2
* :doc:`resquared <pair_resquared>` - Everaers RE-Squared ellipsoidal potential
* :doc:`saip/metal <pair_saip_metal>` - interlayer potential for hetero-junctions formed with hexagonal 2D materials and metal surfaces
* :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>` - smoothed dissipative particle dynamics for water at isothermal conditions

34
doc/src/processors.rst
View File

@ -25,6 +25,8 @@ Syntax
*numa* params = none
*custom* params = infile
infile = file containing grid layout
*numa_nodes* arg = Nn
Nn = number of numa domains per node
*map* arg = *cart* or *cart/reorder* or *xyz* or *xzy* or *yxz* or *yzx* or *zxy* or *zyx*
cart = use MPI_Cart() methods to map processors to 3d grid with reorder = 0
cart/reorder = use MPI_Cart() methods to map processors to 3d grid with reorder = 1
@ -159,24 +161,28 @@ surface-to-volume ratio of each processor's subdomain.
The *numa* style operates similar to the *twolevel* keyword except
that it auto-detects which cores are running on which nodes.
Currently, it does this in only 2 levels, but it may be extended in
the future to account for socket topology and other non-uniform memory
access (NUMA) costs. It also uses a different algorithm than the
*twolevel* keyword for doing the two-level factorization of the
simulation box into a 3d processor grid to minimize off-node
communication, and it does its own MPI-based mapping of nodes and
It will also subdivide the cores into numa domains. Currently, the
number of numa domains is not autodetected and must be specified using
the *numa_nodes* keyword; otherwise, the default value is used. The
*numa* style uses a different algorithm than the *twolevel* keyword for
doing the two-level factorization of the simulation box into a 3d
processor grid to minimize off-node communication and communication
across numa domains. It does its own MPI-based mapping of nodes and
cores to the regular 3d grid. Thus it may produce a different layout
of the processors than the *twolevel* options.
The *numa* style will give an error if the number of MPI processes is
not divisible by the number of cores used per node, or any of the Px
or Py of Pz values is greater than 1.
or Py or Pz values is greater than 1.
.. note::
Unlike the *twolevel* style, the *numa* style does not require
any particular ordering of MPI ranks i norder to work correctly. This
any particular ordering of MPI ranks in order to work correctly. This
is because it auto-detects which processes are running on which nodes.
However, it assumes that the lowest ranks are in the first numa
domain, and so forth. MPI rank orderings that do not preserve this
property might result in more intranode communication between CPUs.
The *custom* style uses the file *infile* to define both the 3d
factorization and the mapping of processors to the grid.
@ -207,6 +213,14 @@ any order, but no processor ID should appear more than once.
----------
The *numa_nodes* keyword is used to specifiy the number of numa domains
per node. It is currently only used by the *numa* style for two-level
factorization to reduce the amount of MPI communications between CPUs.
A good setting for this will typically be equal to the number of CPU
sockets per node.
----------
The *map* keyword affects how the P processor IDs (from 0 to P-1) are
mapped to the 3d grid of processors. It is only used by the
*onelevel* and *twolevel* grid settings.
@ -356,5 +370,5 @@ Related commands
Default
"""""""
The option defaults are Px Py Pz = \* \* \*, grid = onelevel, and map =
cart.
The option defaults are Px Py Pz = \* \* \*, grid = onelevel, map =
cart, and numa_nodes = 2.