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

Merge branch 'develop' into atom-style-var-with-python

Browse Source
This commit is contained in:
Axel Kohlmeyer
2025-06-06 00:20:06 -04:00
parent 1b12f3b47e b3f160c118
commit f69d28fbab
168 changed files with 7506 additions and 2506 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Commands_fix.rst
View File

@ -29,6 +29,7 @@ OPT.
* :doc:`ave/grid <fix_ave_grid>`
* :doc:`ave/histo <fix_ave_histo>`
* :doc:`ave/histo/weight <fix_ave_histo>`
* :doc:`ave/moments <fix_ave_moments>`
* :doc:`ave/time <fix_ave_time>`
* :doc:`aveforce <fix_aveforce>`
* :doc:`balance <fix_balance>`
@ -218,6 +219,7 @@ OPT.
* :doc:`rigid/small (o) <fix_rigid>`
* :doc:`rx (k) <fix_rx>`
* :doc:`saed/vtk <fix_saed_vtk>`
* :doc:`set <fix_set>`
* :doc:`setforce (k) <fix_setforce>`
* :doc:`setforce/spin <fix_setforce>`
* :doc:`sgcmc <fix_sgcmc>`

45
doc/src/Developer_updating.rst
View File

@ -29,6 +29,7 @@ Available topics in mostly chronological order are:
- `Rename of fix STORE/PERATOM to fix STORE/ATOM and change of arguments`_
- `Use Output::get_dump_by_id() instead of Output::find_dump()`_
- `Refactored grid communication using Grid3d/Grid2d classes instead of GridComm`_
- `FLERR as first argument to minimum image functions in Domain class`_
----
@ -610,3 +611,47 @@ KSpace solvers which use distributed FFT grids:
- ``src/KSPACE/pppm.cpp``
This change is **required** or else the code will not compile.
FLERR as first argument to minimum image functions in Domain class
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: TBD
The ``Domain::minimum_image()`` and ``Domain::minimum_image_big()``
functions were changed to take the ``FLERR`` macros as first argument.
This way the error message indicates *where* the function was called
instead of pointing to the implementation of the function. Example:
Old:
.. code-block:: c++
double delx1 = x[i1][0] - x[i2][0];
double dely1 = x[i1][1] - x[i2][1];
double delz1 = x[i1][2] - x[i2][2];
domain->minimum_image(delx1, dely1, delz1);
double r1 = sqrt(delx1 * delx1 + dely1 * dely1 + delz1 * delz1);
double delx2 = x[i3][0] - x[i2][0];
double dely2 = x[i3][1] - x[i2][1];
double delz2 = x[i3][2] - x[i2][2];
domain->minimum_image_big(delx2, dely2, delz2);
double r2 = sqrt(delx2 * delx2 + dely2 * dely2 + delz2 * delz2);
New:
.. code-block:: c++
double delx1 = x[i1][0] - x[i2][0];
double dely1 = x[i1][1] - x[i2][1];
double delz1 = x[i1][2] - x[i2][2];
domain->minimum_image(FLERR, delx1, dely1, delz1);
double r1 = sqrt(delx1 * delx1 + dely1 * dely1 + delz1 * delz1);
double delx2 = x[i3][0] - x[i2][0];
double dely2 = x[i3][1] - x[i2][1];
double delz2 = x[i3][2] - x[i2][2];
domain->minimum_image_big(FLERR, delx2, dely2, delz2);
double r2 = sqrt(delx2 * delx2 + dely2 * dely2 + delz2 * delz2);
This change is **required** or else the code will not compile.

33
doc/src/Speed_compare.rst
View File

@ -75,15 +75,34 @@ section below for examples where this has been done.
**Differences between the GPU and KOKKOS packages:**
* The GPU package accelerates only pair force, neighbor list, and (parts
of) PPPM calculations. The KOKKOS package attempts to run most of the
of) PPPM calculations (and runs the remaining force computations on
the CPU concurrently). The KOKKOS package attempts to run most of the
calculation on the GPU, but can transparently support non-accelerated
code (with a performance penalty due to having data transfers between
host and GPU).
* The list of which styles are accelerated by the GPU or KOKKOS package
differs with some overlap.
* The GPU package requires neighbor lists to be built on the CPU when using
hybrid pair styles, exclusion lists, or a triclinic simulation box.
* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus supports
NVIDIA, AMD, and Intel GPUs well. On NVIDIA hardware, using CUDA is
typically resulting in equal or better performance over OpenCL.
* OpenCL in the GPU package does theoretically also support Intel CPUs or
Intel Xeon Phi, but the native support for those in KOKKOS (or INTEL)
is superior.
* The GPU package benefits from running multiple MPI processes (2-8) per
GPU to parallelize the non-GPU accelerated styles. The KOKKOS package
usually not, especially when all parts of the calculation have KOKKOS
support.
* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus
supports NVIDIA, AMD, and Intel GPUs well. On NVIDIA or AMD hardware,
using native CUDA or HIP compilation, respectively, with either GPU or
KOKKOS results in equal or better performance over OpenCL.
* OpenCL in the GPU package supports NVIDIA, AMD, and Intel GPUs at the
*same time* and with the *same executable*. KOKKOS currently does not
support OpenCL.
* The GPU package supports single precision floating point, mixed
precision floating point, and double precision floating point math on
the GPU. This must be chosen at compile time. KOKKOS currently only
supports double precision floating point math. Using single or mixed
precision (recommended) results in significantly improved performance
on consumer GPUs for some loss in accuracy (which is rather small with
mixed precision). Single and mixed precision support for KOKKOS is in
development (no ETA yet).
* Some pair styles (for example :doc:`snap <pair_snap>`, :doc:`mliap
<pair_mliap>` or :doc:`reaxff <pair_reaxff>` in the KOKKOS package have
seen extensive optimizations and specializations for GPUs and CPUs.

235
doc/src/Speed_measure.rst
View File

@ -1,16 +1,218 @@
Measuring performance
=====================
Before trying to make your simulation run faster, you should
understand how it currently performs and where the bottlenecks are.
Factors that influence performance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The best way to do this is run the your system (actual number of
atoms) for a modest number of timesteps (say 100 steps) on several
different processor counts, including a single processor if possible.
Do this for an equilibrium version of your system, so that the
100-step timings are representative of a much longer run. There is
typically no need to run for 1000s of timesteps to get accurate
timings; you can simply extrapolate from short runs.
Before trying to make your simulation run faster, you should understand
how it currently performs and where the bottlenecks are. We generally
distinguish between serial performance (how fast can a single process do
the calculations?) and parallel efficiency (how much faster does a
calculation get by using more processes?). There are many factors
affecting either and below are some lists discussing some commonly
known but also some less known factors.
Factors affecting serial performance (in no specific order):
* CPU hardware: clock rate, cache sizes, CPU architecture (instructions
per clock, vectorization support, fused multiply-add support and more)
* RAM speed and number of channels that the CPU can use to access RAM
* Cooling: CPUs can change the CPU clock based on thermal load, thus the
degree of cooling can affect the speed of a CPU. Sometimes even the
temperature of neighboring compute nodes in a cluster can make a
difference.
* Compiler optimization: most of LAMMPS is written to be easy to modify
and thus compiler optimization can speed up calculations. However, too
aggressive compiler optimization can produce incorrect results or
crashes (during compilation or at runtime).
* Source code improvements: styles in the OPT, OPENMP, and INTEL package
can be faster than their base implementation due to improved data
access patterns, cache efficiency, or vectorization. Compiler optimization
is required to take full advantage of these.
* Number and kind of fixes, computes, or variables used during a simulation,
especially if they result in collective communication operations
* Pair style cutoffs and system density: calculations get slower the more
neighbors are in the neighbor list and thus for which interactions need
to be computed. Force fields with pair styles that compute interactions
between triples or quadruples of atoms or that use embedding energies or
charge equilibration will need to walk the neighbor lists multiple times.
* Neighbor list settings: tradeoff between neighbor list skin (larger
skin = more neighbors, more distances to compute before applying the
cutoff) and frequency of neighbor list builds (larger skin = fewer
neighbor list builds).
* Proximity of per-atom data in physical memory that for atoms that are
close in space improves cache efficiency (thus LAMMPS will by default
sort atoms in local storage accordingly)
* Using r-RESPA multi-timestepping or a SHAKE or RATTLE fix to constrain
bonds with higher-frequency vibrations may allow a larger (outer) timestep
and thus fewer force evaluations (usually the most time consuming step in
MD) for the same simulated time (with some tradeoff in accuracy).
Factors affecting parallel efficiency (in no specific order):
* Bandwidth and latency of communication between processes. This can vary a
lot between processes on the same CPU or physical node and processes
on different physical nodes and there vary between different
communication technologies (like Ethernet or InfiniBand or other
high-speed interconnects)
* Frequency and complexity of communication patterns required
* Number of "work units" (usually correlated with the number of atoms
and choice of force field) per MPI-process required for one time step
(if this number becomes too small, the cost of communication becomes
dominant).
* Choice of parallelization method (MPI-only, OpenMP-only, MPI+OpenMP,
MPI+GPU, MPI+GPU+OpenMP)
* Algorithmic complexity of the chosen force field (pair-wise vs. many-body
potential, Ewald vs. PPPM vs. (compensated or smoothed) cutoff-Coulomb)
* Communication cutoff: a larger cutoff results in more ghost atoms and
thus more data that needs to be communicated
* Frequency of neighbor list builds: during a neighbor list build the
domain decomposition is updated and the list of ghost atoms rebuilt
which requires multiple global communication steps
* FFT-grid settings and number of MPI processes for kspace style PPPM:
PPPM uses parallel 3d FFTs which will drop much faster in parallel
efficiency with respect to the number of MPI processes than other
parts of the force computation. Thus using MPI+OpenMP parallelization
or :doc:`run style verlet/split <run_style>` can improve parallel
efficiency by limiting the number of MPI processes used for the FFTs.
* Load (im-)balance: LAMMPS' domain decomposition assumes that atoms are
evenly distributed across the entire simulation box. If there are
areas of vacuum, this may lead to different amounts of work for
different MPI processes. Using the :doc:`processors command
<processors>` to change the spatial decomposition, or MPI+OpenMP
parallelization instead of only-MPI to have larger sub-domains, or the
(fix) balance command (without or with switching to communication style
tiled) to change the sub-domain volumes are all methods that
can help to avoid load imbalances.
Examples comparing serial performance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Before looking at your own input deck(s), you should get some reference
data from a known input so that you know what kind of performance you
should expect from your input. For the following we therefore use the
``in.rhodo.scaled`` input file and ``data.rhodo`` data file from the
``bench`` folder. This is a system of 32000 atoms using the CHARMM force
field and long-range electrostatics running for 100 MD steps. The
performance data is printed at the end of a run and only measures the
performance during propagation and excludes the setup phase.
Running with a single MPI process on an AMD Ryzen Threadripper PRO
9985WX CPU (64 cores, 128 threads, base clock: 3.2GHz, max. clock
5.4GHz, L1/L2/L3 cache 5MB/64MB/256MB, 8 DDR5-6400 memory channels) one
gets the following performance report:
.. code-block::
Performance: 1.232 ns/day, 19.476 hours/ns, 7.131 timesteps/s, 228.197 katom-step/s
99.2% CPU use with 1 MPI tasks x 1 OpenMP threads
The %CPU value should be at 100% or very close. Lower values would
be an indication that there are *other* processes also using the same
CPU core and thus invalidating the performance data. The katom-step/s
value is best suited for comparisons, since it is fairly independent
from the system size. The `in.rhodo.scaled` input can be easily made
larger through replication in the three dimensions by settings variables
"x", "y", "z" to values other than 1 from the command line with the
"-var" flag. Example:
- 32000 atoms: 228.8 katom-step/s
- 64000 atoms: 231.6 katom-step/s
- 128000 atoms: 231.1 katom-step/s
- 256000 atoms: 226.4 katom-step/s
- 864000 atoms: 229.6 katom-step/s
Comparing to an AMD Ryzen 7 7840HS CPU (8 cores, 16 threads, base clock
3.8GHz, max. clock 5.1GHz, L1/L2/L3 cache 512kB/8MB/16MB, 2 DDR5-5600
memory channels), we get similar single core performance (~220
katom-step/s vs. ~230 katom-step/s) due to the similar clock and
architecture:
- 32000 atoms: 219.8 katom-step/s
- 64000 atoms: 222.5 katom-step/s
- 128000 atoms: 216.8 katom-step/s
- 256000 atoms: 221.0 katom-step/s
- 864000 atoms: 221.1 katom-step/s
Switching to an older Intel Xeon E5-2650 v4 CPU (12 cores, 12 threads,
base clock 2.2GHz, max. clock 2.9GHz, L1/L2/L3 cache (64kB/256kB/30MB, 4
DDR4-2400 memory channels) leads to a lower performance of approximately
109 katom-step/s due to differences in architecture and clock. In all
cases, when looking at multiple runs, the katom-step/s property
fluctuates by approximately 1% around the average.
From here on we are looking at the performance for the 256000 atom system only
and change several settings incrementally:
#. No compiler optimization GCC (-Og -g): 183.8 katom-step/s
#. Moderate optimization with debug info GCC (-O2 -g): 231.1 katom-step/s
#. Full compiler optimization GCC (-DNDEBUG -O3): 236.0 katom-step/s
#. Aggressive compiler optimization GCC (-O3 -ffast-math -march=native): 239.9 katom-step/s
#. Source code optimization in OPENMP package (1 thread): 266.7 katom-step/s
#. Use *fix nvt* instead of *fix npt* (compute virial only every 50 steps): 272.9 katom-step/s
#. Increase pair style cutoff by 2 :math:`\AA`: 181.2 katom-step/s
#. Use tight PPPM convergence (1.0e-6 instead of 1.0e-4): 161.9 katom-step/s
#. Use Ewald summation instead of PPPM (at 1.0e-4 convergence): 19.9 katom-step/s
The numbers show that gains from aggressive compiler optimizations are
rather small in LAMMPS, the data access optimizations in the OPENMP (and
OPT) packages are more prominent. On the other side, using more
accurate force field settings causes, not unexpectedly, a significant
slowdown (to about half the speed). Finally, using regular Ewald
summation causes a massive slowdown due to the bad algorithmic scaling
with system size.
Examples comparing parallel performance
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The parallel performance usually goes on top of the serial performance.
Using twice as many processors should increase the performance metric
by up to a factor of two. With the number of processors *N* and the
serial performance :math:`p_1` and the performance for *N* processors
:math:`p_N` we can define a *parallel efficiency* in percent as follows:
.. math::
P_{eff} = \frac{p_N}{p_1 \cdot N} \cdot 100\%
For the AMD Ryzen Threadripper PRO 9985WX CPU and the serial
simulation settings of point 6. from above, we get the following
parallel efficiency data for the 256000 atom system:
- 1 MPI task: 273.6 katom-step/s, :math:`P_{eff} = 100\%`
- 2 MPI tasks: 530.6 katom-step/s, :math:`P_{eff} = 97\%`
- 4 MPI tasks: 1.021 Matom-step/s, :math:`P_{eff} = 93\%`
- 8 MPI tasks: 1.837 Matom-step/s, :math:`P_{eff} = 84\%`
- 16 MPI tasks: 3.574 Matom-step/s, :math:`P_{eff} = 82\%`
- 32 MPI tasks: 6.479 Matom-step/s, :math:`P_{eff} = 74\%`
- 64 MPI tasks: 9.032 Matom-step/s, :math:`P_{eff} = 52\%`
- 128 MPI tasks: 12.03 Matom-step/s, :math:`P_{eff} = 34\%`
The 128 MPI tasks run uses CPU cores from hyper-threading.
For a small system with only 32000 atoms the parallel efficiency
drops off earlier when the number of work units is too small relative
to the communication overhead:
- 1 MPI task: 270.8 katom-step/s, :math:`P_{eff} = 100\%`
- 2 MPI tasks: 529.3 katom-step/s, :math:`P_{eff} = 98\%`
- 4 MPI tasks: 989.8 katom-step/s, :math:`P_{eff} = 91\%`
- 8 MPI tasks: 1.832 Matom-step/s, :math:`P_{eff} = 85\%`
- 16 MPI tasks: 3.463 Matom-step/s, :math:`P_{eff} = 80\%`
- 32 MPI tasks: 5.970 Matom-step/s, :math:`P_{eff} = 69\%`
- 64 MPI tasks: 7.477 Matom-step/s, :math:`P_{eff} = 42\%`
- 128 MPI tasks: 8.069 Matom-step/s, :math:`P_{eff} = 23\%`
Measuring performance of your input deck
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The best way to do this is run the your system (actual number of atoms)
for a modest number of timesteps (say 100 steps) on several different
processor counts, including a single processor if possible. Do this for
an equilibrium version of your system, so that the 100-step timings are
representative of a much longer run. There is typically no need to run
for 1000s of timesteps to get accurate timings; you can simply
extrapolate from short runs.
For the set of runs, look at the timing data printed to the screen and
log file at the end of each LAMMPS run. The
@ -28,12 +230,15 @@ breakdown and relative percentages. For example, trying different
options for speeding up the long-range solvers will have little impact
if they only consume 10% of the run time. If the pairwise time is
dominating, you may want to look at GPU or OMP versions of the pair
style, as discussed below. Comparing how the percentages change as
you increase the processor count gives you a sense of how different
operations within the timestep are scaling. Note that if you are
running with a Kspace solver, there is additional output on the
breakdown of the Kspace time. For PPPM, this includes the fraction
spent on FFTs, which can be communication intensive.
style, as discussed below. Comparing how the percentages change as you
increase the processor count gives you a sense of how different
operations within the timestep are scaling. If you are using PPPM as
Kspace solver, you can turn on an additional output with
:doc:`kspace_modify fftbench yes <kspace_modify>` which measures the
time spent during PPPM on the 3d FFTs, which can be communication
intensive for larger processor counts. This provides an indication
whether it is worth trying out alternatives to the default FFT settings
for additional performance.
Another important detail in the timing info are the histograms of
atoms counts and neighbor counts. If these vary widely across

2
doc/src/fix.rst
View File

@ -208,6 +208,7 @@ accelerated styles exist.
* :doc:`ave/grid <fix_ave_grid>` - compute per-grid time-averaged quantities
* :doc:`ave/histo <fix_ave_histo>` - compute/output time-averaged histograms
* :doc:`ave/histo/weight <fix_ave_histo>` - weighted version of fix ave/histo
* :doc:`ave/moments <fix_ave_moments>` - compute moments of scalar quantities
* :doc:`ave/time <fix_ave_time>` - compute/output global time-averaged quantities
* :doc:`aveforce <fix_aveforce>` - add an averaged force to each atom
* :doc:`balance <fix_balance>` - perform dynamic load-balancing
@ -397,6 +398,7 @@ accelerated styles exist.
* :doc:`rigid/small <fix_rigid>` - constrain many small clusters of atoms to move as a rigid body with NVE integration
* :doc:`rx <fix_rx>` - solve reaction kinetic ODEs for a defined reaction set
* :doc:`saed/vtk <fix_saed_vtk>` - time-average the intensities from :doc:`compute saed <compute_saed>`
* :doc:`set <fix_set>` - reset an atom property via an atom-style variable every N steps
* :doc:`setforce <fix_setforce>` - set the force on each atom
* :doc:`setforce/spin <fix_setforce>` - set magnetic precession vectors on each atom
* :doc:`sgcmc <fix_sgcmc>` - fix for hybrid semi-grand canonical MD/MC simulations

7
doc/src/fix_ave_correlate_long.rst
View File

@ -82,10 +82,9 @@ specified values may represent calculations performed by computes and
fixes which store their own "group" definitions.
Each listed value can be the result of a compute or fix or the
evaluation of an equal-style or vector-style variable. For
vector-style variables, the specified indices can include a wildcard
character. See the :doc:`fix ave/correlate <fix_ave_correlate>` page
for details.
evaluation of an equal-style or vector-style variable. The specified
indices can include a wildcard string. See the
:doc:`fix ave/correlate <fix_ave_correlate>` page for details on that.
The *Nevery* and *Nfreq* arguments specify on what time steps the input
values will be used to calculate correlation data and the frequency

296
doc/src/fix_ave_moments.rst Normal file
View File

@ -0,0 +1,296 @@
.. index:: fix ave/moments
fix ave/moments command
=======================
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID ave/moments Nevery Nrepeat Nfreq value1 value2 ... moment1 moment2 ... keyword args ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* ave/moments = style name of this fix command
* Nevery = use input values every this many time steps
* Nrepeat = # of times to use input values for calculating averages
* Nfreq = calculate averages every this many time steps
* one or more input variables can be listed
* value = v_name
.. parsed-literal::
c_ID = global scalar calculated by a compute with ID
c_ID[I] = Ith component of global vector calculated by a compute with ID, I can include wildcard (see below)
f_ID = global scalar calculated by a fix with ID
f_ID[I] = Ith component of global vector calculated by a fix with ID, I can include wildcard (see below)
v_name = value calculated by an equal-style variable with name
v_name[I] = value calculated by a vector-style variable with name, I can include wildcard (see below)
* one or more moments to compute can be listed
* moment = *mean* or *stddev* or *variance* or *skew* or *kurtosis*, see exact definitions below.
* zero or more keyword/arg pairs may be appended
* keyword = *start* or *history*
.. parsed-literal::
*start* args = Nstart
Nstart = invoke first after this time step
*history* args = Nrecent
Nrecent = keep a history of up to Nrecent outputs
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all ave/moments 1 1000 100 v_volume mean stddev
fix 1 all ave/moments 1 200 1000 v_volume variance kurtosis history 10
Description
"""""""""""
.. versionadded:: TBD
Using one or more values as input, calculate the moments of the underlying
(population) distributions based on samples collected every few time
steps over a time step window. The definitions of the moments calculated
are given below.
The group specified with this command is ignored. However, note that
specified values may represent calculations performed by computes and
fixes which store their own "group" definitions.
Each listed value can be the result of a :doc:`compute <compute>` or
:doc:`fix <fix>` or the evaluation of an equal-style or vector-style
:doc:`variable <variable>`. In each case, the compute, fix, or variable
must produce a global quantity, not a per-atom or local quantity.
If you wish to spatial- or time-average or histogram per-atom
quantities from a compute, fix, or variable, then see the :doc:`fix
ave/chunk <fix_ave_chunk>`, :doc:`fix ave/atom <fix_ave_atom>`, or
:doc:`fix ave/histo <fix_ave_histo>` commands. If you wish to sum a
per-atom quantity into a single global quantity, see the :doc:`compute
reduce <compute_reduce>` command.
Many :doc:`computes <compute>` and :doc:`fixes <fix>` produce global
quantities. See their doc pages for details. :doc:`Variables <variable>`
of style *equal* and *vector* are the only ones that can be used with
this fix. Variables of style *atom* cannot be used, since they produce
per-atom values.
The input values must all be scalars or vectors with a bracketed term
appended, indicating the :math:`I^\text{th}` value of the vector is
used.
The result of this fix can be accessed as a vector, containing the
interleaved moments of each input in order. If M moments are requested,
then the moments of input 1 will be the first M values in the vector
output by this fix. The moments of input 2 will the next M values, etc.
If there are N values, the vector length will be N*M.
----------
For input values from a compute or fix or variable, the bracketed index
I can be specified using a wildcard asterisk with the index to
effectively specify multiple values. This takes the form "\*" or "\*n"
or "m\*" or "m\*n". If :math:`N` is the size of the vector, then an
asterisk with no numeric values means all indices from 1 to :math:`N`.
A leading asterisk means all indices from 1 to n (inclusive). A
trailing asterisk means all indices from n to :math:`N` (inclusive). A
middle asterisk means all indices from m to n (inclusive).
Using a wildcard is the same as if the individual elements of the vector
or cells of the array had been listed one by one. For examples, see the
description of this capability in :doc:`fix ave/time <fix_ave_time>`.
----------
The :math:`N_\text{every}`, :math:`N_\text{repeat}`, and
:math:`N_\text{freq}` arguments specify on what time steps the input
values will be used in order to contribute to the average. The final
statistics are generated on time steps that are a multiple of
:math:`N_\text{freq}`\ . The average is over a window of up to
:math:`N_\text{repeat}` quantities, computed in the preceding portion of
the simulation once every :math:`N_\text{every}` time steps.
.. note::
Contrary to most fix ave/* commands, it is not required that Nevery *
Nrepeat <= Nfreq. This is to allow the user to choose the time
window and number of samples contributing to the output at each
Nfreq interval.
For example, if :math:`N_\text{freq}=100` and :math:`N_\text{repeat}=5`
(and :math:`N_\text{every}=1`), then on step 100 values from time steps
96, 97, 98, 99, and 100 will be used. The fix does not compute its
inputs on steps that are not required. If :math:`N_\text{freq}=5`,
:math:`N_\text{repeat}=8` and :math:`N_\text{every}=1`, then values
will first be calculated on step 5 from steps 1-5, on step 10 from 3-10,
on step 15 from 8-15 and so on, forming a rolling average over
timesteps that span a time window larger than Nfreq.
----------
If a value begins with "c\_", a compute ID must follow which has been
previously defined in the input script. If no bracketed term is
appended, the global scalar calculated by the compute is used. If a
bracketed term is appended, the Ith element of the global vector
calculated by the compute is used. See the discussion above for how I
can be specified with a wildcard asterisk to effectively specify
multiple values.
If a value begins with "f\_", a fix ID must follow which has been
previously defined in the input script. If no bracketed term is
appended, the global scalar calculated by the fix is used. If a
bracketed term is appended, the Ith element of the global vector
calculated by the fix is used. See the discussion above for how I can
be specified with a wildcard asterisk to effectively specify multiple
values.
Note that some fixes only produce their values on certain time steps,
which must be compatible with *Nevery*, else an error will result.
Users can also write code for their own fix styles and :doc:`add them to
LAMMPS <Modify>`.
If a value begins with "v\_", a variable name must follow which has been
previously defined in the input script. Only equal-style or vector-style
variables can be used, which both produce global values. Vector-style
variables require a bracketed term to specify the Ith element of the
vector calculated by the variable.
Note that variables of style *equal* and *vector* define a formula which
can reference individual atom properties or thermodynamic keywords, or
they can invoke other computes, fixes, or variables when they are
evaluated, so this is a very general means of specifying quantities to
time average.
----------
The moments are output in the order requested in the arguments following
the last input. Any number and order of moments can be specified,
although it does not make much sense to specify the same moment multiple
times. All moments are computed using a correction of the sample estimators
used to obtain unbiased cumulants :math:`k_{1..4}` (see :ref:`(Cramer)
<Cramer1>`). The correction for variance is the standard Bessel
correction. For other moments, see :ref:`(Joanes)<Joanes1>`.
For *mean*, the arithmetic mean :math:`\bar{x} = \frac{1}{n}
\sum_{i=1}^{n} x_i` is calculated.
For *variance*, the Bessel-corrected sample variance :math:`var = k_2 =
\frac{1}{n - 1} \sum_{i=1}^{n} (x_i - \bar{x})^2` is calculated.
For *stddev*, the Bessel-corrected sample standard deviation
:math:`stddev = \sqrt{k_2}` is calculated.
For *skew*, the adjusted Fisher--Pearson standardized moment :math:`G_1
= \frac{k_3}{k_2^{3/2}} = \frac{k_3}{stddev^3}` is calculated.
For *kurtosis*, the adjusted Fisher--Pearson standardized moment
:math:`G_2 = \frac{k_4}{k_2^2}` is calculated.
----------
Fix invocation and output can be modified by optional keywords.
The *start* keyword specifies that the first computation should be no
earlier than the step number given (but will still occur on a multiple
of *Nfreq*). The default is step 0. Often input values can be 0.0 at
time 0, so setting *start* to a larger value can avoid including a 0.0
in a longer series.
The *history* keyword stores the Nrecent most recent outputs on Nfreq
timesteps, so they can be accessed as global outputs of the fix. Nrecent
must be >= 1. The default is 1, meaning only the most recent output is
accessible. For example, if history 10 is specified and Nfreq = 1000,
then on timestep 20000, the Nfreq outputs from steps 20000, 19000, ...
11000 are available for access. See below for details on how to access
the history values.
For example, this will store the outputs of the previous 10 Nfreq
time steps, i.e. a window of 10000 time steps:
.. code-block:: LAMMPS
fix 1 all ave/moments 1 200 1000 v_volume mean history 10
The previous results can be accessed as values in a global array output
by this fix. Each column of the array is the vector output of the N-th
preceding Nfreq timestep. For example, assuming a single moment is
calculated, the most recent result corresponding to the third input
value would be accessed as "f_name[3][1]", "f_name[3][4]" is the 4th
most recent and so on. The current vector output is always the first
column of the array, corresponding to the most recent result.
To illustrate the utility of keeping output history, consider using
this fix in conjunction with :doc:`fix halt <fix_halt>` to stop a run
automatically if a quantity is converged to within some desired tolerance:
.. code-block:: LAMMPS
variable target equal etot
fix aveg all ave/moments 1 200 1000 v_target mean stddev history 10
variable stopcond equal "abs(f_aveg[1]-f_aveg[1][10])<f_aveg[2]"
fix fhalt all halt 1000 v_stopcond == 1
In this example, every 1000 time steps, the average and standard
deviation of the total energy over the previous 200 time steps are
calculated. If the difference between the most recent and 10-th most
recent average is lower than the most recent standard deviation, the run
is stopped.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`.
This fix produces a global vector and global array which can be accessed
by various :doc:`output commands <Howto_output>`. The values can be
accessed on any time step, but may not be current.
A global vector is produced with the # of elements = number of moments *
number of inputs. The moments are output in the order given in the fix
definition. An array is produced having # of rows = length of vector
output (with an ordering which matches the vector) and # of columns =
value of *history*. There is always at least one column.
Each element of the global vector or array can be either "intensive" or
"extensive", depending on whether the values contributing to the element
are "intensive" or "extensive". If a compute or fix provides the value
being time averaged, then the compute or fix determines whether the value
is intensive or extensive; see the page for that compute or fix for
further info. Values produced by a variable are treated as intensive.
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
""""""""""""
This compute 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.
Related commands
""""""""""""""""
:doc:`fix ave/time <fix_ave_time>`,
Default
"""""""
The option defaults are history = 1, start = 0.
----------
.. _Cramer1:
**(Cramer)** Cramer, Mathematical Methods of Statistics, Princeton University Press (1946).
.. _Joanes1:
**(Joanes)** Joanes, Gill, The Statistician, 47, 183--189 (1998).

173
doc/src/fix_set.rst Normal file
View File

@ -0,0 +1,173 @@
.. index:: fix set
fix set command
===============
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID set Nfreq rnflag set-args
* ID, group-ID are documented in :doc:`fix <fix>` command
* set = style name of this fix command
* Nfreq = reset per-atom properties every this many timesteps
* rnflag = 1 to reneighbor on next timestep, 0 to not
* set-args = identical to args for the :doc:`set <set>` command
Examples
""""""""
.. code-block:: LAMMPS
fix 10 all set 1 0 group all i_dump v_new
fix 10 all set 1 0 group all i_dump v_turnoff
Description
"""""""""""
Reset one or more properties of one or more atoms once every *Nfreq*
steps during a simulation.
If the *rnflag* for reneighboring is set to 1, then a reneighboring
will be triggered on the next timestep (since the fix set operation
occurs at the end of the current timestep). This is important to do
if this command changes per-atom properties that need to be
communicated to ghost atoms. If this is not the case, an *rnflag*
setting of 0 can be used; reneighboring will only be triggered on
subsequent timesteps by the usual neighbor list criteria; see the
:doc:`neigh_modify command <neigh_modify>`.
Here are two examples where an *rnflag* setting of 1 are needed. If a
custom per-atom property is changed and the :doc:`fix property/atom
<fix_property_atom>` command to create the property used the *ghost
yes* keyword. Or if per-atom charges are changed, all pair styles
which compute Coulombic interactions require charge values for ghost
atoms. In both these examples, the re-neighboring will trigger the
changes in the owned atom properties to be immediately communicated to
ghost atoms.
The arguments following *Nfreq* and *rnflag* are identical to those
allowed for the :doc:`set <set>` command, as in the examples above and
below.
Note that the group-ID setting for this command is ignored. The
syntax for the :doc:`set <set>` arguments allows selection of which
atoms have their properties reset.
This command can only be used to reset an atom property using a
per-atom variable. This option in allowed by many, but not all, of
the keyword/value pairs supported by the :doc:`set <set>` command.
The reason for this restriction is that if a per-atom variable is not
used, this command will typically not change atom properties during
the simulation.
The :doc:`set <set>` command can be used with similar syntax to this
command to reset atom properties once before or between simulations.
----------
Here is an example of input script commands which will output atoms
into a dump file only when their x-velocity crosses a threshold value
*vthresh* for the first time. Their position and x-velocity will then
be output every step for *twindow* timesteps.
.. code-block:: LAMMPS
variable vthresh equal 2 # threshold velocity
variable twindow equal 10 # dump for this many steps
#
# define custom property i_dump to store timestep threshold is crossed
#
fix 2 all property/atom i_dump
set group all i_dump -1
#
# fix set command checks for threshold crossings every step
# resets i_dump from -1 to current timestep when crossing occurs
#
variable start atom "vx > v_vthresh && i_dump == -1"
variable new atom ternary(v_start,step,i_dump)
fix 3 all set 1 0 group all i_dump v_new
#
# dump command with thresh which enforces twindow
#
dump 1 all custom 1 tmp.dump id x y vx i_dump
variable dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
dump_modify 1 thresh v_dumpflag == 1
#
# run the simulation
# final dump with all atom IDs which crossed threshold on which timestep
#
run 1000
write_dump all custom tmp.dump.final id i_dump modify thresh i_dump >= 0
The tmp.dump.final file lists which atoms crossed the velocity
threshold. This command will print the *twindow* timesteps when a
specific atom ID (104 in this case) was output in the tmp.dump file:
.. code-block:: LAMMPS
% grep "^104 " tmp.dump
If these commands are used instead of the above, then an atom can
cross the velocity threshold multiple times, and will be output for
*twindow* timesteps each time. However the write_dump command is no
longer useful.
.. code-block:: LAMMPS
variable vthresh equal 2 # threshold velocity
variable twindow equal 10 # dump for this many steps
#
# define custom property i_dump to store timestep threshold is crossed
#
fix 2 all property/atom i_dump
set group all i_dump -1
#
# fix set command checks for threshold crossings every step
# resets i_dump from -1 to current timestep when crossing occurs
#
variable start atom "vx > v_vthresh && i_dump == -1"
variable turnon atom ternary(v_start,step,i_dump)
variable stop atom "v_turnon >= 0 && (step-v_turnon) < v_twindow"
variable turnoff atom ternary(v_stop,v_turnon,-1)
fix 3 all set 1 0 group all i_dump v_turnoff
#
# dump command with thresh which enforces twindow
#
dump 1 all custom 1 tmp.dump id x y vx i_dump
variable dumpflag atom "i_dump >= 0 && (step-i_dump) < v_twindow"
dump_modify 1 thresh v_dumpflag == 1
#
# run the simulation
#
run 1000
----------
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
""""""""""""
none
Related commands
""""""""""""""""
:doc:`set <set>`
Default
"""""""
none

61
doc/src/pair_hybrid.rst
View File

@ -100,6 +100,56 @@ first is assigned to intra-molecular interactions (i.e. both atoms
have the same molecule ID), the second to inter-molecular interactions
(i.e. interacting atoms have different molecule IDs).
.. admonition:: When **NOT** to use a hybrid pair style
:class: warning
Using pair style *hybrid* can be very tempting to use if you need a
**many-body potential** supporting a mix of elements for which you
cannot find a potential file that covers *all* of them. Regardless
of how this is set up, there will be *errors*. The major use case
where the error is *small*, is when the many-body sub-styles are used
on different objects (for example a slab and a liquid, a metal and a
nano-machining work piece). In that case the *mixed* terms
**should** be provided by a pair-wise additive potential (like
Lennard-Jones or Morse) to avoid unexpected behavior and reduce
errors. LAMMPS cannot easily check for this condition and thus will
accept good and bad choices alike.
Outside of this, we *strongly* recommend *against* using pair style
hybrid with many-body potentials for the following reasons:
1. When trying to combine EAM or MEAM potentials, there is a *large*
error in the embedding term, since it is computed separately for
each sub-style only.
2. When trying to combine many-body potentials like Stillinger-Weber,
Tersoff, AIREBO, Vashishta, or similar, you have to understand
that the potential of a sub-style cannot be applied in a pair-wise
fashion but will need to be applied to multiples of atoms
(e.g. a Tersoff potential of elements A and B includes the
interactions A-A, B-B, A-B, A-A-A, A-A-B, A-B-B, A-B-A, B-A-A,
B-A-B, B-B-A, B-B-B; AIREBO also considers all quadruples of
atom elements).
3. When one of the sub-styles uses charge-equilibration (= QEq; like
in ReaxFF or COMB) you have inconsistent QEq behavior because
either you try to apply QEq to *all* atoms but then you are
missing the QEq parameters for the non-QEq pair style (and it
would be inconsistent to apply QEq for pair styles that are not
parameterized for QEq) or else you would have either no charges or
fixed charges interacting with the QEq which also leads to
inconsistent behavior between two sub-styles. When attempting to
use multiple ReaxFF instances to combine different potential
files, you might be able to work around the QEq limitations, but
point 2. still applies.
We understand that it is frustrating to not be able to run simulations
due to lack of available potential files, but that does not justify
combining potentials in a broken way via pair style hybrid. This is
not what the hybrid pair styles are designed for.
----------
Here are two examples of hybrid simulations. The *hybrid* style could
be used for a simulation of a metal droplet on a LJ surface. The metal
atoms interact with each other via an *eam* potential, the surface atoms
@ -374,12 +424,11 @@ selected sub-style.
----------
.. note::
Several of the potentials defined via the pair_style command in
LAMMPS are really many-body potentials, such as Tersoff, AIREBO, MEAM,
ReaxFF, etc. The way to think about using these potentials in a
hybrid setting is as follows.
Even though the command name "pair_style" would suggest that these are
pair-wise interactions, several of the potentials defined via the
pair_style command in LAMMPS are really many-body potentials, such as
Tersoff, AIREBO, MEAM, ReaxFF, etc. The way to think about using these
potentials in a hybrid setting is as follows.
A subset of atom types is assigned to the many-body potential with a
single :doc:`pair_coeff <pair_coeff>` command, using "\* \*" to include

18
doc/src/run.rst
View File

@ -103,14 +103,16 @@ must be done.
.. note::
If your input script changes the system between 2 runs, then the
initial setup must be performed to ensure the change is recognized by
all parts of the code that are affected. Examples are adding a
:doc:`fix <fix>` or :doc:`dump <dump>` or :doc:`compute <compute>`, changing
a :doc:`neighbor <neigh_modify>` list parameter, or writing restart file
which can migrate atoms between processors. LAMMPS has no easy way to
check if this has happened, but it is an error to use the *pre no*
option in this case.
If your input script "changes" the system between 2 runs, then the
initial setup typically needs to be performed to ensure the change
is recognized by all parts of the code that are affected. Examples
are adding a :doc:`fix <fix>` or :doc:`dump <dump>` or
:doc:`compute <compute>`, changing a :doc:`neighbor <neigh_modify>`
list parameter, using the :doc:`set <set>` command, or writing a
restart file via the :doc:`write_restart <write_restart>` command,
which can migrate atoms between processors. LAMMPS has no easy way
to check if this has happened, but it is an error to use the *pre
no* option in these cases.
If *post* is specified as "no", the full timing summary is skipped;
only a one-line summary timing is printed.

791
doc/src/set.rst
View File

@ -22,21 +22,110 @@ Syntax
for style = *region*, ID = a region ID
* one or more keyword/value pairs may be appended
* keyword = *type* or *type/fraction* or *type/ratio* or *type/subset*
or *mol* or *x* or *y* or *z* or *vx* or *vy* or *vz* or *charge* or
*dipole* or *dipole/random* or *quat* or *spin/atom* or *spin/atom/random* or
*spin/electron* or *radius/electron* or
*quat* or *quat/random* or *diameter* or *shape* or *length* or *tri* or
*theta* or *theta/random* or *angmom* or *omega* or
*mass* or *density* or *density/disc* or *temperature* or
*volume* or *image* or *bond* or *angle* or *dihedral* or
*improper* or *sph/e* or *sph/cv* or *sph/rho* or
*smd/contact/radius* or *smd/mass/density* or *dpd/theta* or
*edpd/temp* or *edpd/cv* or *cc* or *epsilon* or
*i_name* or *d_name* or *i2_name* or *d2_name*
* keyword = *angle* or *angmom* or *bond* or *cc* or *charge* or
*density* or *density/disc* or *diameter* or *dihedral* or *dipole*
or *dipole/random* or *dpd/theta* or *edpd/cv* or *edpd/temp* or
*epsilon* or *image* or *improper* or *length* or *mass* or *mol* or
*omega* or *quat* or *quat/random* or *radius/electron* or *shape* or
*smd/contact/radius* or *smd/mass/density* or *sph/cv* or *sph/e* or
*sph/rho* or *spin/atom* or *spin/atom/random* or *spin/electron* or
*temperature* or *theta* or *theta/random* or *tri* or *type* or
*type/fraction* or *type/ratio* or *type/subset* or *volume* or *vx*
or *vy* or *vz* or *x* or *y* or *z* or *i_name* or *d_name* or
*i2_name* or *d2_name*
.. parsed-literal::
*angle* value = numeric angle type or angle type label, for all angles between selected atoms
*angmom* values = Lx Ly Lz
Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
any of Lx,Ly,Lz can be an atom-style variable (see below)
*bond* value = numeric bond type or bond type label, for all bonds between selected atoms
*cc* values = index cc
index = index of a chemical species (1 to Nspecies)
cc = chemical concentration of tDPD particles for a species (mole/volume units)
cc can be an atom-style variable (see below)
*charge* value = atomic charge (charge units)
value can be an atom-style variable (see below)
*density* value = particle density for a sphere or ellipsoid (mass/distance\^3 units), or for a triangle (mass/distance\^2 units) or line (mass/distance units) particle
value can be an atom-style variable (see below)
*density/disc* value = particle density for a 2d disc or ellipse (mass/distance\^2 units)
value can be an atom-style variable (see below)
*diameter* value = diameter of spherical particle (distance units)
value can be an atom-style variable (see below)
*dihedral* value = numeric dihedral type or dihedral type label, for all dihedrals between selected atoms
*dipole* values = x y z
x,y,z = orientation of dipole moment vector
any of x,y,z can be an atom-style variable (see below)
*dipole/random* values = seed Dlen
seed = random # seed (positive integer) for dipole moment orientations
Dlen = magnitude of dipole moment (dipole units)
*dpd/theta* value = internal temperature of DPD particles (temperature units)
value can be an atom-style variable (see below)
value can be NULL which sets internal temp of each particle to KE temp
*edpd/cv* value = volumetric heat capacity of eDPD particles (energy/temperature/volume units)
value can be an atom-style variable (see below)
*edpd/temp* value = temperature of eDPD particles (temperature units)
value can be an atom-style variable (see below)
*epsilon* value = dielectric constant of the medium where the atoms reside
value can be an atom-style variable (see below)
*image* values = nx ny nz
nx,ny,nz = which periodic image of the simulation box the atom is in
any of nx,ny,nz can be an atom-style variable (see below)
*improper* value = numeric improper type or improper type label, for all impropers between selected atoms
*length* value = len
len = length of line segment (distance units)
len can be an atom-style variable (see below)
*mass* value = per-atom mass (mass units)
value can be an atom-style variable (see below)
*mol* value = molecule ID
the moleclue ID can be an atom-style variable (see below)
*omega* values = Wx Wy Wz
Wx,Wy,Wz = components of angular velocity vector (radians/time units)
any of Wx,Wy,Wz can be an atom-style variable (see below)
*quat* values = a b c theta
a,b,c = unit vector to rotate particle around via right-hand rule
theta = rotation angle (degrees)
any of a,b,c,theta values can be an atom-style variable (see below)
*quat/random* value = seed
seed = random # seed (positive integer) for quaternion orientations
*radius/electron* value = eradius
eradius = electron radius (or fixed-core radius) (distance units)
value can be an atom-style variable (see below)
*shape* values = Sx Sy Sz
Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
any of Sx,Sy,Sz can be an atom-style variable (see below)
*smd/contact/radius* value = radius for short range interactions, i.e. contact and friction
value can be an atom-style variable (see below)
*smd/mass/density* value = set particle mass based on volume by providing a mass density
value can be an atom-style variable (see below)
*sph/cv* value = heat capacity of SPH particles (need units)
value can be an atom-style variable (see below)
*sph/e* value = energy of SPH particles (need units)
value can be an atom-style variable (see below)
*sph/rho* value = density of SPH particles (need units)
value can be an atom-style variable (see below)
*spin/atom* values = g x y z
g = magnitude of magnetic spin vector (in Bohr magneton's unit)
x,y,z = orientation of magnetic spin vector
any of x,y,z can be an atom-style variable (see below)
*spin/atom/random* values = seed Dlen
seed = random # seed (positive integer) for magnetic spin orientations
Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
*spin/electron* value = espin
espin = electron spin (+1/-1), 0 = nuclei, 2 = fixed-core, 3 = pseudo-cores (i.e. ECP)
value can be an atom-style variable (see below)
*temperature* value = temperature for finite-size particles (temperature units)
value can be an atom-style variable (see below)
*theta* value = angle (degrees)
angle = orientation of line segment with respect to x-axis
value can be an atom-style variable (see below)
*theta/random* value = seed
seed = random # seed (positive integer) for line segment orienations
*tri* value = side
side = side length of equilateral triangle (distance units)
value can be an atom-style variable (see below)
*type* value = numeric atom type or type label
value can be an atom-style variable (see below)
*type/fraction* values = type fraction seed
@ -51,104 +140,22 @@ Syntax
type = numeric atom type or type label
Nsubset = exact number of selected atoms to set to new atom type
seed = random # seed (positive integer)
*mol* value = molecule ID
value can be an atom-style variable (see below)
*x*,\ *y*,\ *z* value = atom coordinate (distance units)
*volume* value = particle volume for Peridynamic particle (distance\^3 units)
value can be an atom-style variable (see below)
*vx*,\ *vy*,\ *vz* value = atom velocity (velocity units)
value can be an atom-style variable (see below)
*charge* value = atomic charge (charge units)
*x*,\ *y*,\ *z* value = atom coordinate (distance units)
value can be an atom-style variable (see below)
*dipole* values = x y z
x,y,z = orientation of dipole moment vector
any of x,y,z can be an atom-style variable (see below)
*dipole/random* value = seed Dlen
seed = random # seed (positive integer) for dipole moment orientations
Dlen = magnitude of dipole moment (dipole units)
*spin/atom* values = g x y z
g = magnitude of magnetic spin vector (in Bohr magneton's unit)
x,y,z = orientation of magnetic spin vector
any of x,y,z can be an atom-style variable (see below)
*spin/atom/random* value = seed Dlen
seed = random # seed (positive integer) for magnetic spin orientations
Dlen = magnitude of magnetic spin vector (in Bohr magneton's unit)
*radius/electron* values = eradius
eradius = electron radius (or fixed-core radius) (distance units)
*spin/electron* value = espin
espin = electron spin (+1/-1), 0 = nuclei, 2 = fixed-core, 3 = pseudo-cores (i.e. ECP)
*quat* values = a b c theta
a,b,c = unit vector to rotate particle around via right-hand rule
theta = rotation angle (degrees)
any of a,b,c,theta can be an atom-style variable (see below)
*quat/random* value = seed
seed = random # seed (positive integer) for quaternion orientations
*diameter* value = diameter of spherical particle (distance units)
value can be an atom-style variable (see below)
*shape* value = Sx Sy Sz
Sx,Sy,Sz = 3 diameters of ellipsoid (distance units)
*length* value = len
len = length of line segment (distance units)
len can be an atom-style variable (see below)
*tri* value = side
side = side length of equilateral triangle (distance units)
side can be an atom-style variable (see below)
*theta* value = angle (degrees)
angle = orientation of line segment with respect to x-axis
angle can be an atom-style variable (see below)
*theta/random* value = seed
seed = random # seed (positive integer) for line segment orienations
*angmom* values = Lx Ly Lz
Lx,Ly,Lz = components of angular momentum vector (distance-mass-velocity units)
any of Lx,Ly,Lz can be an atom-style variable (see below)
*omega* values = Wx Wy Wz
Wx,Wy,Wz = components of angular velocity vector (radians/time units)
any of wx,wy,wz can be an atom-style variable (see below)
*mass* value = per-atom mass (mass units)
value can be an atom-style variable (see below)
*density* value = particle density for a sphere or ellipsoid (mass/distance\^3 units), or for a triangle (mass/distance\^2 units) or line (mass/distance units) particle
value can be an atom-style variable (see below)
*density/disc* value = particle density for a 2d disc or ellipse (mass/distance\^2 units)
value can be an atom-style variable (see below)
*temperature* value = temperature for finite-size particles (temperature units)
value can be an atom-style variable (see below)
*volume* value = particle volume for Peridynamic particle (distance\^3 units)
value can be an atom-style variable (see below)
*image* nx ny nz
nx,ny,nz = which periodic image of the simulation box the atom is in
any of nx,ny,nz can be an atom-style variable (see below)
*bond* value = numeric bond type or bond type label, for all bonds between selected atoms
*angle* value = numeric angle type or angle type label, for all angles between selected atoms
*dihedral* value = numeric dihedral type or dihedral type label, for all dihedrals between selected atoms
*improper* value = numeric improper type or improper type label, for all impropers between selected atoms
*rheo/rho* value = density of RHEO particles (mass/distance\^3)
*rheo/status* value = status or phase of RHEO particles (unitless)
*sph/e* value = energy of SPH particles (need units)
value can be an atom-style variable (see below)
*sph/cv* value = heat capacity of SPH particles (need units)
value can be an atom-style variable (see below)
*sph/rho* value = density of SPH particles (need units)
value can be an atom-style variable (see below)
*smd/contact/radius* = radius for short range interactions, i.e. contact and friction
value can be an atom-style variable (see below)
*smd/mass/density* = set particle mass based on volume by providing a mass density
value can be an atom-style variable (see below)
*dpd/theta* value = internal temperature of DPD particles (temperature units)
value can be an atom-style variable (see below)
value can be NULL which sets internal temp of each particle to KE temp
*edpd/temp* value = temperature of eDPD particles (temperature units)
value can be an atom-style variable (see below)
*edpd/cv* value = volumetric heat capacity of eDPD particles (energy/temperature/volume units)
value can be an atom-style variable (see below)
*cc* values = index cc
index = index of a chemical species (1 to Nspecies)
cc = chemical concentration of tDPD particles for a species (mole/volume units)
*epsilon* value = dielectric constant of the medium where the atoms reside
*i_name* value = custom integer vector with name
value can be an atom-style variable (see below)
*d_name* value = custom floating-point vector with name
*i2_name* value = column of a custom integer array with name
value can be an atom-style variable (see below)
*i2_name* value = custom integer array with name
column specified as i2_name[N] where N is 1 to Ncol
*d2_name* value = column of a custom floating-point array with name
value can be an atom-style variable (see below)
*d2_name* value = custom floating-point array with name
column specified as d2_name[N] where N is 1 to Ncol
value can be an atom-style variable (see below)
Examples
""""""""
@ -177,22 +184,26 @@ Description
Set one or more properties of one or more atoms. Since atom
properties are initially assigned by the :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>` or :doc:`create_atoms <create_atoms>`
commands, this command changes those assignments. This can be useful
for overriding the default values assigned by the
:doc:`create_atoms <create_atoms>` command (e.g. charge = 0.0). It can
be useful for altering pairwise and molecular force interactions,
:doc:`read_restart <read_restart>` or :doc:`create_atoms
<create_atoms>` commands, this command changes those assignments.
This can be useful for overriding the default values assigned by the
:doc:`create_atoms <create_atoms>` command (e.g. charge = 0.0). It
can be useful for altering pairwise and molecular force interactions,
since force-field coefficients are defined in terms of types. It can
be used to change the labeling of atoms by atom type or molecule ID
when they are output in :doc:`dump <dump>` files. It can also be useful
for debugging purposes; i.e. positioning an atom at a precise location
to compute subsequent forces or energy.
when they are output in :doc:`dump <dump>` files. It can also be
useful for debugging purposes; i.e. positioning an atom at a precise
location to compute subsequent forces or energy.
Note that the *style* and *ID* arguments determine which atoms have
their properties reset. The remaining keywords specify which
properties to reset and what the new values are. Some strings like
*type* or *mol* can be used as a style and/or a keyword.
The :doc:`fix set <fix_set>` command can be used with similar syntax
to this command to reset atom properties once every *N* steps during a
simulation using via atom-style variables.
----------
This section describes how to select which atoms to change
@ -211,8 +222,8 @@ can be specified, e.g. "C". The style *mol* selects all the atoms in
a range of molecule IDs.
In each of the range cases, the range can be specified as a single
numeric value, or a wildcard asterisk can be used to specify a range
of values. This takes the form "\*" or "\*n" or "n\*" or "m\*n". For
numeric value, or with a wildcard asterisk to specify a range of
values. This takes the form "\*" or "\*n" or "n\*" or "m\*n". For
example, for the style *type*, if N = the number of atom types, then
an asterisk with no numeric values means all types from 1 to N. A
leading asterisk means all types from 1 to n (inclusive). A trailing
@ -222,25 +233,25 @@ means all types from m to n (inclusive). For all the styles except
The style *group* selects all the atoms in the specified group. The
style *region* selects all the atoms in the specified geometric
region. See the :doc:`group <group>` and :doc:`region <region>` commands
for details of how to specify a group or region.
region. See the :doc:`group <group>` and :doc:`region <region>`
commands for details of how to specify a group or region.
----------
This section describes the keyword options for which properties to
The next section describes the keyword options for which properties to
change, for the selected atoms.
Note that except where explicitly prohibited below, all of the
keywords allow an :doc:`atom-style or atomfile-style variable
<variable>` to be used as the specified value(s). If the value is a
variable, it should be specified as v_name, where name is the
variable name. In this case, the variable will be evaluated, and its
resulting per-atom value used to determine the value assigned to each
selected atom. Note that the per-atom value from the variable will be
ignored for atoms that are not selected via the *style* and *ID*
settings explained above. A simple way to use per-atom values from
the variable to reset a property for all atoms is to use style *atom*
with *ID* = "\*"; this selects all atom IDs.
variable, it should be specified as v_name, where name is the variable
name. In this case, the variable will be evaluated, and its resulting
per-atom value used to determine the value assigned to each selected
atom. Note that the per-atom value from the variable will be ignored
for atoms that are not selected via the *style* and *ID* settings
explained above. A simple way to use per-atom values from the
variable to reset a property for all atoms is to use style *atom* with
*ID* = "\*"; this selects all atom IDs.
Atom-style variables can specify formulas with various mathematical
functions, and include :doc:`thermo_style <thermo_style>` command
@ -256,52 +267,110 @@ from a file.
.. note::
Atom-style and atomfile-style variables return floating point
per-atom values. If the values are assigned to an integer variable,
such as the molecule ID, then the floating point value is truncated to
its integer portion, e.g. a value of 2.6 would become 2.
per-atom values. If the values are assigned to an integer
variable, such as the molecule ID, then the floating point value is
truncated to its integer portion, e.g. a value of 2.6 would
become 2.
----------
.. versionchanged:: 28Mar2023
Support for type labels was added for setting atom, bond, angle,
dihedral, and improper types
Support for type labels was added for setting angle types
Keyword *type* sets the atom type for all selected atoms. A specified
value can be either a numeric atom type or an atom type label. When
using a numeric type, the specified value must be from 1 to ntypes,
where ntypes was set by the :doc:`create_box <create_box>` command or
the *atom types* field in the header of the data file read by the
:doc:`read_data <read_data>` command. When using a type label it must
have been defined previously. See the :doc:`Howto type labels
<Howto_type_labels>` doc page for the allowed syntax of type labels
and a general discussion of how type labels can be used.
Keyword *angle* sets the angle type of all angles of selected atoms to
the specified value. The value can be a numeric type from 1 to
nangletypes. Or it can be a angle type label. See the :doc:`Howto
type labels <Howto_type_labels>` doc page for the allowed syntax of
type labels and a general discussion of how type labels can be used.
All atoms in a particular angle must be selected atoms in order for
the change to be made. The value of nangletypes was set by the *angle
types* field in the header of the data file read by the
:doc:`read_data <read_data>` command. This keyword does NOT allow use
of an atom-style variable.
Keyword *type/fraction* sets the atom type for a fraction of the selected
atoms. The actual number of atoms changed is not guaranteed
to be exactly the specified fraction (0 <= *fraction* <= 1), but
should be statistically close. Random numbers are used in such a way
that a particular atom is changed or not changed, regardless of how
many processors are being used. This keyword does not allow use of an
atom-style variable.
Keyword *angmom* sets the angular momentum of selected atoms. The
particles must be ellipsoids as defined by the :doc:`atom_style
ellipsoid <atom_style>` command or triangles as defined by the
:doc:`atom_style tri <atom_style>` command. The angular momentum
vector of the particles is set to the 3 specified components.
Keywords *type/ratio* and *type/subset* also set the atom type for a
fraction of the selected atoms. The actual number of atoms changed
will be exactly the requested number. For *type/ratio* the specified
fraction (0 <= *fraction* <= 1) determines the number. For
*type/subset*, the specified *Nsubset* is the number. An iterative
algorithm is used which ensures the correct number of atoms are
selected, in a perfectly random fashion. Which atoms are selected
will change with the number of processors used. These keywords do not
allow use of an atom-style variable.
.. versionchanged:: 28Mar2023
Keyword *mol* sets the molecule ID for all selected atoms. The
:doc:`atom style <atom_style>` being used must support the use of
molecule IDs.
Support for type labels was added for setting bond types
Keywords *x*, *y*, *z*, and *charge* set the coordinates or
charge of all selected atoms. For *charge*, the :doc:`atom style
<atom_style>` being used must support the use of atomic
charge. Keywords *vx*, *vy*, and *vz* set the velocities of all
selected atoms.
Keyword *bond* sets the bond type of all bonds of selected atoms to
the specified value. The value can be a numeric type from 1 to
nbondtypes. Or it can be a bond type label. See the :doc:`Howto type
labels <Howto_type_labels>` doc page for the allowed syntax of type
labels and a general discussion of how type labels can be used. All
atoms in a particular bond must be selected atoms in order for the
change to be made. The value of nbondtypes was set by the *bond
types* field in the header of the data file read by the
:doc:`read_data <read_data>` command. This keyword does NOT allow use
of an atom-style variable.
Keyword *cc* sets the chemical concentration of a tDPD particle for a
specified species as defined by the DPD-MESO package. Currently, only
:doc:`atom_style tdpd <atom_style>` defines particles with this
attribute. An integer for "index" selects a chemical species (1 to
Nspecies) where Nspecies is set by the atom_style command. The value
for the chemical concentration must be >= 0.0.
Keyword *charge* set the charge of all selected atoms. The :doc:`atom
style <atom_style>` being used must support the use of atomic charge.
Keyword *density* or *density/disc* also sets the mass of all selected
particles, but in a different way. The particles must have a per-atom
mass attribute, as defined by the :doc:`atom_style <atom_style>`
command. If the atom has a radius attribute (see :doc:`atom_style
sphere <atom_style>`) and its radius is non-zero, its mass is set from
the density and particle volume for 3d systems (the input density is
assumed to be in mass/distance\^3 units). For 2d, the default is for
LAMMPS to model particles with a radius attribute as spheres.
However, if the *density/disc* keyword is used, then they can be
modeled as 2d discs (circles). Their mass is set from the density and
particle area (the input density is assumed to be in mass/distance\^2
units).
If the atom has a shape attribute (see :doc:`atom_style ellipsoid
<atom_style>`) and its 3 shape parameters are non-zero, then its mass
is set from the density and particle volume (the input density is
assumed to be in mass/distance\^3 units). The *density/disc* keyword
has no effect; it does not (yet) treat 3d ellipsoids as 2d ellipses.
If the atom has a length attribute (see :doc:`atom_style line
<atom_style>`) and its length is non-zero, then its mass is set from
the density and line segment length (the input density is assumed to
be in mass/distance units). If the atom has an area attribute (see
:doc:`atom_style tri <atom_style>`) and its area is non-zero, then its
mass is set from the density and triangle area (the input density is
assumed to be in mass/distance\^2 units).
If none of these cases are valid, then the mass is set to the density
value directly (the input density is assumed to be in mass units).
Keyword *diameter* sets the size of the selected atoms. The particles
must be finite-size spheres as defined by the :doc:`atom_style sphere
<atom_style>` command. The diameter of a particle can be set to 0.0,
which means they will be treated as point particles. Note that this
command does not adjust the particle mass, even if it was defined with
a density, e.g. via the :doc:`read_data <read_data>` command.
.. versionchanged:: 28Mar2023
Support for type labels was added for setting dihedral types
Keyword *dihedral* sets the dihedral type of all dihedrals of selected
atoms to the specified value. The value can be a numeric type from 1
to ndihedraltypes. Or it can be a dihedral type label. See the
:doc:`Howto type labels <Howto_type_labels>` doc page for the allowed
syntax of type labels and a general discussion of how type labels can
be used. All atoms in a particular dihedral must be selected atoms in
order for the change to be made. The value of ndihedraltypes was set
by the *dihedral types* field in the header of the data file read by
the :doc:`read_data <read_data>` command. This keyword does NOT allow
use of an atom-style variable.
Keyword *dipole* uses the specified x,y,z values as components of a
vector to set as the orientation of the dipole moment vectors of the
@ -313,40 +382,106 @@ moment vectors for the selected atoms and sets the magnitude of each
to the specified *Dlen* value. For 2d systems, the z component of the
orientation is set to 0.0. Random numbers are used in such a way that
the orientation of a particular atom is the same, regardless of how
many processors are being used. This keyword does not allow use of an
many processors are being used. This keyword does NOT allow use of an
atom-style variable.
.. versionchanged:: 15Sep2022
Keyword *dpd/theta* sets the internal temperature of a DPD particle as
defined by the DPD-REACT package. If the specified value is a number
it must be >= 0.0. If the specified value is NULL, then the kinetic
temperature Tkin of each particle is computed as 3/2 k Tkin = KE = 1/2
m v\^2 = 1/2 m (vx\*vx+vy\*vy+vz\*vz). Each particle's internal
temperature is set to Tkin. If the specified value is an atom-style
variable, then the variable is evaluated for each particle. If a
value >= 0.0, the internal temperature is set to that value. If it is
< 0.0, the computation of Tkin is performed and the internal
temperature is set to that value.
Keyword *spin/atom* uses the specified g value to set the magnitude of the
magnetic spin vectors, and the x,y,z values as components of a vector
to set as the orientation of the magnetic spin vectors of the selected
atoms. This keyword was previously called *spin*.
Keywords *edpd/temp* and *edpd/cv* set the temperature and volumetric
heat capacity of an eDPD particle as defined by the DPD-MESO package.
Currently, only :doc:`atom_style edpd <atom_style>` defines particles
with these attributes. The values for the temperature and heat
capacity must be positive.
.. versionchanged:: 15Sep2022
Keyword *epsilon* sets the dielectric constant of a particle to be
that of the medium where the particle resides as defined by the
DIELECTRIC package. Currently, only :doc:`atom_style dielectric
<atom_style>` defines particles with this attribute. The value for the
dielectric constant must be >= 0.0. Note that the set command with
this keyword will rescale the particle charge accordingly so that the
real charge (e.g., as read from a data file) stays intact. To change
the real charges, one needs to use the set command with the *charge*
keyword. Care must be taken to ensure that the real and scaled charges
and the dielectric constants are consistent.
Keyword *spin/atom/random* randomizes the orientation of the magnetic spin
vectors for the selected atoms and sets the magnitude of each to the
specified *Dlen* value. This keyword was previously called *spin/random*.
Keyword *image* sets which image of the simulation box the atom is
considered to be in. An image of 0 means it is inside the box as
defined. A value of 2 means add 2 box lengths to get the true value.
A value of -1 means subtract 1 box length to get the true value.
LAMMPS updates these flags as atoms cross periodic boundaries during
the simulation. The flags can be output with atom snapshots via the
:doc:`dump <dump>` command. If a value of NULL is specified for any
of nx,ny,nz, then the current image value for that dimension is
unchanged. For non-periodic dimensions only a value of 0 can be
specified. This command can be useful after a system has been
equilibrated and atoms have diffused one or more box lengths in
various directions. This command can then reset the image values for
atoms so that they are effectively inside the simulation box, e.g if a
diffusion coefficient is about to be measured via the :doc:`compute
msd <compute_msd>` command. Care should be taken not to reset the
image flags of two atoms in a bond to the same value if the bond
straddles a periodic boundary (rather they should be different by +/-
1). This will not affect the dynamics of a simulation, but may mess
up analysis of the trajectories if a LAMMPS diagnostic or your own
analysis relies on the image flags to unwrap a molecule which
straddles the periodic box.
.. versionadded:: 15Sep2022
.. versionchanged:: 28Mar2023
Keyword *radius/electron* uses the specified value to set the radius of
electrons or fixed cores.
Support for type labels was added for setting improper types
.. versionadded:: 15Sep2022
Keyword *improper* sets the improper type of all impropers of selected
atoms to the specified value. The value can be a numeric type from 1
to nimpropertypes. Or it can be a improper type label. See the
:doc:`Howto type labels <Howto_type_labels>` doc page for the allowed
syntax of type labels and a general discussion of how type labels can
be used. All atoms in a particular improper must be selected atoms in
order for the change to be made. The value of nimpropertypes was set
by the *improper types* field in the header of the data file read by
the :doc:`read_data <read_data>` command. This keyword does NOT allow
use of an atom-style variable.
Keyword *spin/electron* sets the spin of an electron (+/- 1) or indicates
nuclei (=0), fixed-cores (=2), or pseudo-cores (= 3).
Keyword *length* sets the length of selected atoms. The particles
must be line segments as defined by the :doc:`atom_style line
<atom_style>` command. If the specified value is non-zero the line
segment is (re)set to a length = the specified value, centered around
the particle position, with an orientation along the x-axis. If the
specified value is 0.0, the particle will become a point particle.
Note that this command does not adjust the particle mass, even if it
was defined with a density, e.g. via the :doc:`read_data <read_data>`
command.
Keyword *mass* sets the mass of all selected particles. The particles
must have a per-atom mass attribute, as defined by the
:doc:`atom_style <atom_style>` command. See the "mass" command for
how to set mass values on a per-type basis.
Keyword *mol* sets the molecule ID for all selected atoms. The
:doc:`atom style <atom_style>` being used must support the use of
molecule IDs.
Keyword *omega* sets the angular velocity of selected atoms. The
particles must be spheres as defined by the :doc:`atom_style sphere
<atom_style>` command. The angular velocity vector of the particles
is set to the 3 specified components.
Keyword *quat* uses the specified values to create a quaternion
(4-vector) that represents the orientation of the selected atoms. The
particles must define a quaternion for their orientation
(e.g. ellipsoids, triangles, body particles) as defined by the
:doc:`atom_style <atom_style>` command. Note that particles defined by
:doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters. The 3
values must be non-zero for each particle set by this command. They
are used to specify the aspect ratios of an ellipsoidal particle,
:doc:`atom_style <atom_style>` command. Note that particles defined
by :doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters.
The 3 values must be non-zero for each particle set by this command.
They are used to specify the aspect ratios of an ellipsoidal particle,
which is oriented by default with its x-axis along the simulation
box's x-axis, and similarly for y and z. If this body is rotated (via
the right-hand rule) by an angle theta around a unit rotation vector
@ -360,51 +495,77 @@ ignored, since a rotation vector of (0,0,1) is the only valid choice.
Keyword *quat/random* randomizes the orientation of the quaternion for
the selected atoms. The particles must define a quaternion for their
orientation (e.g. ellipsoids, triangles, body particles) as defined by
the :doc:`atom_style <atom_style>` command. Random numbers are used in
such a way that the orientation of a particular atom is the same,
the :doc:`atom_style <atom_style>` command. Random numbers are used
in such a way that the orientation of a particular atom is the same,
regardless of how many processors are being used. For 2d systems,
only orientations in the xy plane are generated. As with keyword
*quat*, for ellipsoidal particles, the 3 shape values must be non-zero
for each particle set by this command. This keyword does not allow
for each particle set by this command. This keyword does NOT allow
use of an atom-style variable.
Keyword *diameter* sets the size of the selected atoms. The particles
must be finite-size spheres as defined by the :doc:`atom_style sphere
<atom_style>` command. The diameter of a particle can be set to 0.0,
which means they will be treated as point particles. Note that this
command does not adjust the particle mass, even if it was defined with
a density, e.g. via the :doc:`read_data <read_data>` command.
.. versionadded:: 15Sep2022
Keyword *radius/electron* uses the specified value to set the radius
of electrons or fixed cores.
Keyword *shape* sets the size and shape of the selected atoms. The
particles must be ellipsoids as defined by the :doc:`atom_style
ellipsoid <atom_style>` command. The *Sx*, *Sy*, *Sz* settings
are the 3 diameters of the ellipsoid in each direction. All 3 can be
set to the same value, which means the ellipsoid is effectively a
sphere. They can also all be set to 0.0 which means the particle will
be treated as a point particle. Note that this command does not
adjust the particle mass, even if it was defined with a density,
e.g. via the :doc:`read_data <read_data>` command.
ellipsoid <atom_style>` command. The *Sx*, *Sy*, *Sz* settings are
the 3 diameters of the ellipsoid in each direction. All 3 can be set
to the same value, which means the ellipsoid is effectively a sphere.
They can also all be set to 0.0 which means the particle will be
treated as a point particle. Note that this command does not adjust
the particle mass, even if it was defined with a density, e.g. via the
:doc:`read_data <read_data>` command.
Keyword *length* sets the length of selected atoms. The particles
must be line segments as defined by the :doc:`atom_style line
<atom_style>` command. If the specified value is non-zero the line
segment is (re)set to a length = the specified value, centered around
the particle position, with an orientation along the x-axis. If the
specified value is 0.0, the particle will become a point particle.
Note that this command does not adjust the particle mass, even if it
was defined with a density, e.g. via the :doc:`read_data <read_data>`
command.
Keyword *smd/contact/radius* only applies to simulations with the
Smooth Mach Dynamics package MACHDYN. Itsets an interaction radius
for computing short-range interactions, e.g. repulsive forces to
prevent different individual physical bodies from penetrating each
other. Note that the SPH smoothing kernel diameter used for computing
long range, nonlocal interactions, is set using the *diameter*
keyword.
Keyword *tri* sets the size of selected atoms. The particles must be
triangles as defined by the :doc:`atom_style tri <atom_style>` command.
If the specified value is non-zero the triangle is (re)set to be an
equilateral triangle in the xy plane with side length = the specified
value, with a centroid at the particle position, with its base
parallel to the x axis, and the y-axis running from the center of the
base to the top point of the triangle. If the specified value is 0.0,
the particle will become a point particle. Note that this command
does not adjust the particle mass, even if it was defined with a
density, e.g. via the :doc:`read_data <read_data>` command.
Keyword *smd/mass/density* sets the mass of all selected particles,
but it is only applicable to the Smooth Mach Dynamics package MACHDYN.
It assumes that the particle volume has already been correctly set and
calculates particle mass from the provided mass density value.
Keywords *sph/cv*, *sph/e*, and *sph/rho* set the heat capacity,
energy, and density of smoothed particle hydrodynamics (SPH)
particles. See `this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to
using SPH in LAMMPS.
.. note::
Note that the SPH PDF guide file has not been updated for many
years and thus does not reflect the current *syntax* of the SPH
package commands. For that, please refer to the LAMMPS manual.
.. versionchanged:: 15Sep2022
Keyword *spin/atom* uses the specified g value to set the magnitude of
the magnetic spin vectors, and the x,y,z values as components of a
vector to set as the orientation of the magnetic spin vectors of the
selected atoms. This keyword was previously called *spin*.
.. versionchanged:: 15Sep2022
Keyword *spin/atom/random* randomizes the orientation of the magnetic
spin vectors for the selected atoms and sets the magnitude of each to
the specified *Dlen* value. This keyword does NOT allow use of an
atom-style variable. This keyword was previously called
*spin/random*.
.. versionadded:: 15Sep2022
Keyword *spin/electron* sets the spin of an electron (+/- 1) or
indicates nuclei (=0), fixed-cores (=2), or pseudo-cores (= 3).
Keyword *temperature* sets the temperature of a finite-size particle.
Currently, only the GRANULAR package supports this attribute. The
temperature must be added using an instance of :doc:`fix property/atom
<fix_property_atom>` The values for the temperature must be positive.
Keyword *theta* sets the orientation of selected atoms. The particles
must be line segments as defined by the :doc:`atom_style line
@ -413,169 +574,71 @@ orientation angle of the line segments with respect to the x axis.
Keyword *theta/random* randomizes the orientation of theta for the
selected atoms. The particles must be line segments as defined by the
:doc:`atom_style line <atom_style>` command. Random numbers are used in
such a way that the orientation of a particular atom is the same,
:doc:`atom_style line <atom_style>` command. Random numbers are used
in such a way that the orientation of a particular atom is the same,
regardless of how many processors are being used. This keyword does
not allow use of an atom-style variable.
NOT allow use of an atom-style variable.
Keyword *angmom* sets the angular momentum of selected atoms. The
particles must be ellipsoids as defined by the :doc:`atom_style
ellipsoid <atom_style>` command or triangles as defined by the
:doc:`atom_style tri <atom_style>` command. The angular momentum
vector of the particles is set to the 3 specified components.
Keyword *tri* sets the size of selected atoms. The particles must be
triangles as defined by the :doc:`atom_style tri <atom_style>`
command. If the specified value is non-zero the triangle is (re)set
to be an equilateral triangle in the xy plane with side length = the
specified value, with a centroid at the particle position, with its
base parallel to the x axis, and the y-axis running from the center of
the base to the top point of the triangle. If the specified value is
0.0, the particle will become a point particle. Note that this
command does not adjust the particle mass, even if it was defined with
a density, e.g. via the :doc:`read_data <read_data>` command.
Keyword *omega* sets the angular velocity of selected atoms. The
particles must be spheres as defined by the :doc:`atom_style sphere
<atom_style>` command. The angular velocity vector of the particles is
set to the 3 specified components.
.. versionchanged:: 28Mar2023
Keyword *mass* sets the mass of all selected particles. The particles
must have a per-atom mass attribute, as defined by the :doc:`atom_style
<atom_style>` command. See the "mass" command for how to set mass
values on a per-type basis.
Support for type labels was added for setting atom types
Keyword *density* or *density/disc* also sets the mass of all selected
particles, but in a different way. The particles must have a per-atom
mass attribute, as defined by the :doc:`atom_style <atom_style>`
command. If the atom has a radius attribute (see :doc:`atom_style
sphere <atom_style>`) and its radius is non-zero, its mass is set from
the density and particle volume for 3d systems (the input density is
assumed to be in mass/distance\^3 units). For 2d, the default is for
LAMMPS to model particles with a radius attribute as spheres. However,
if the *density/disc* keyword is used, then they can be modeled as 2d
discs (circles). Their mass is set from the density and particle area
(the input density is assumed to be in mass/distance\^2 units).
If the atom has a shape attribute (see :doc:`atom_style ellipsoid
<atom_style>`) and its 3 shape parameters are non-zero, then its mass is
set from the density and particle volume (the input density is assumed
to be in mass/distance\^3 units). The *density/disc* keyword has no
effect; it does not (yet) treat 3d ellipsoids as 2d ellipses.
If the atom has a length attribute (see :doc:`atom_style line
<atom_style>`) and its length is non-zero, then its mass is set from the
density and line segment length (the input density is assumed to be in
mass/distance units). If the atom has an area attribute (see
:doc:`atom_style tri <atom_style>`) and its area is non-zero, then its
mass is set from the density and triangle area (the input density is
assumed to be in mass/distance\^2 units).
If none of these cases are valid, then the mass is set to the density
value directly (the input density is assumed to be in mass units).
Keyword *temperature* sets the temperature of a finite-size particle.
Currently, only the GRANULAR package supports this attribute. The
temperature must be added using an instance of
:doc:`fix property/atom <fix_property_atom>` The values for the
temperature must be positive.
Keyword *volume* sets the volume of all selected particles. Currently,
only the :doc:`atom_style peri <atom_style>` command defines particles
with a volume attribute. Note that this command does not adjust the
particle mass.
Keyword *image* sets which image of the simulation box the atom is
considered to be in. An image of 0 means it is inside the box as
defined. A value of 2 means add 2 box lengths to get the true value. A
value of -1 means subtract 1 box length to get the true value. LAMMPS
updates these flags as atoms cross periodic boundaries during the
simulation. The flags can be output with atom snapshots via the
:doc:`dump <dump>` command. If a value of NULL is specified for any of
nx,ny,nz, then the current image value for that dimension is unchanged.
For non-periodic dimensions only a value of 0 can be specified. This
command can be useful after a system has been equilibrated and atoms
have diffused one or more box lengths in various directions. This
command can then reset the image values for atoms so that they are
effectively inside the simulation box, e.g if a diffusion coefficient is
about to be measured via the :doc:`compute msd <compute_msd>` command.
Care should be taken not to reset the image flags of two atoms in a bond
to the same value if the bond straddles a periodic boundary (rather they
should be different by +/- 1). This will not affect the dynamics of a
simulation, but may mess up analysis of the trajectories if a LAMMPS
diagnostic or your own analysis relies on the image flags to unwrap a
molecule which straddles the periodic box.
Keywords *bond*, *angle*, *dihedral*, and *improper*, set the bond
type (angle type, etc) of all bonds (angles, etc) of selected atoms to
the specified value. The value can be a numeric type from 1 to
nbondtypes (nangletypes, etc). Or it can be a type label (bond type
label, angle type label, etc). See the :doc:`Howto type labels
Keyword *type* sets the atom type for all selected atoms. A specified
value can be either a numeric atom type or an atom type label. When
using a numeric type, the specified value must be from 1 to ntypes,
where ntypes was set by the :doc:`create_box <create_box>` command or
the *atom types* field in the header of the data file read by the
:doc:`read_data <read_data>` command. When using a type label it must
have been defined previously. See the :doc:`Howto type labels
<Howto_type_labels>` doc page for the allowed syntax of type labels
and a general discussion of how type labels can be used. All atoms in
a particular bond (angle, etc) must be selected atoms in order for the
change to be made. The value of nbondtypes (nangletypes, etc) was set
by the *bond types* (\ *angle types*, etc) field in the header of the
data file read by the :doc:`read_data <read_data>` command. These
keywords do not allow use of an atom-style variable.
and a general discussion of how type labels can be used.
Keywords *rheo/rho* and *rheo/status* set the density and the status of
rheo particles. In particular, one can only set the phase in the status
as described by the :doc:`RHEO howto page <Howto_rheo>`.
Keyword *type/fraction* sets the atom type for a fraction of the
selected atoms. The actual number of atoms changed is not guaranteed
to be exactly the specified fraction (0 <= *fraction* <= 1), but
should be statistically close. Random numbers are used in such a way
that a particular atom is changed or not changed, regardless of how
many processors are being used. This keyword does NOT allow use of an
atom-style variable.
Keywords *sph/e*, *sph/cv*, and *sph/rho* set the energy, heat capacity,
and density of smoothed particle hydrodynamics (SPH) particles. See
`this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS.
Keywords *type/ratio* and *type/subset* also set the atom type for a
fraction of the selected atoms. The actual number of atoms changed
will be exactly the requested number. For *type/ratio* the specified
fraction (0 <= *fraction* <= 1) determines the number. For
*type/subset*, the specified *Nsubset* is the number. An iterative
algorithm is used which ensures the correct number of atoms are
selected, in a perfectly random fashion. Which atoms are selected
will change with the number of processors used. These keywords do not
allow use of an atom-style variable.
.. note::
Keyword *volume* sets the volume of all selected particles.
Currently, only the :doc:`atom_style peri <atom_style>` command
defines particles with a volume attribute. Note that this command
does not adjust the particle mass.
Please note that the SPH PDF guide file has not been updated for
many years and thus does not reflect the current *syntax* of the
SPH package commands. For that please refer to the LAMMPS manual.
Keywords *vx*, *vy*, and *vz* set the velocities of all selected
atoms.
Keyword *smd/mass/density* sets the mass of all selected particles, but
it is only applicable to the Smooth Mach Dynamics package MACHDYN. It
assumes that the particle volume has already been correctly set and
calculates particle mass from the provided mass density value.
Keyword *smd/contact/radius* only applies to simulations with the Smooth
Mach Dynamics package MACHDYN. Itsets an interaction radius for
computing short-range interactions, e.g. repulsive forces to prevent
different individual physical bodies from penetrating each other. Note
that the SPH smoothing kernel diameter used for computing long range,
nonlocal interactions, is set using the *diameter* keyword.
Keyword *dpd/theta* sets the internal temperature of a DPD particle as
defined by the DPD-REACT package. If the specified value is a number it
must be >= 0.0. If the specified value is NULL, then the kinetic
temperature Tkin of each particle is computed as 3/2 k Tkin = KE = 1/2 m
v\^2 = 1/2 m (vx\*vx+vy\*vy+vz\*vz). Each particle's internal
temperature is set to Tkin. If the specified value is an atom-style
variable, then the variable is evaluated for each particle. If a value
>= 0.0, the internal temperature is set to that value. If it is < 0.0,
the computation of Tkin is performed and the internal temperature is set
to that value.
Keywords *edpd/temp* and *edpd/cv* set the temperature and volumetric
heat capacity of an eDPD particle as defined by the DPD-MESO package.
Currently, only :doc:`atom_style edpd <atom_style>` defines particles
with these attributes. The values for the temperature and heat capacity
must be positive.
Keyword *cc* sets the chemical concentration of a tDPD particle for a
specified species as defined by the DPD-MESO package. Currently, only
:doc:`atom_style tdpd <atom_style>` defines particles with this
attribute. An integer for "index" selects a chemical species (1 to
Nspecies) where Nspecies is set by the atom_style command. The value for
the chemical concentration must be >= 0.0.
Keyword *epsilon* sets the dielectric constant of a particle, precisely
of the medium where the particle resides as defined by the DIELECTRIC
package. Currently, only :doc:`atom_style dielectric <atom_style>`
defines particles with this attribute. The value for the dielectric
constant must be >= 0.0. Note that the set command with this keyword
will rescale the particle charge accordingly so that the real charge
(e.g., as read from a data file) stays intact. To change the real
charges, one needs to use the set command with the *charge*
keyword. Care must be taken to ensure that the real and scaled charges,
and dielectric constants are consistent.
Keywords *x*, *y*, *z* set the coordinates of all selected atoms.
Keywords *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom
per-atom integer and floating-point vectors or arrays that have been
added via the :doc:`fix property/atom <fix_property_atom>` command.
When that command is used specific names are given to each attribute
which are the "name" portion of these keywords. For arrays *i2_name*
and *d2_name*, the column of the array must also be included following
the name in brackets: e.g. d2_xyz[2], i2_mySpin[3].
and *d2_name*, the column of the array to set must also be included
following the name in brackets: e.g. d2_xyz[2] or i2_mySpin[3].
Restrictions
""""""""""""
@ -584,7 +647,7 @@ You cannot set an atom attribute (e.g. *mol* or *q* or *volume*\ ) if
the :doc:`atom_style <atom_style>` does not have that attribute.
This command requires inter-processor communication to coordinate the
setting of bond types (angle types, etc). This means that your system
setting of bond types (angle types, etc). This means that the system
must be ready to perform a simulation before using one of these
keywords (force fields set, atom mass set, etc). This is not
necessary for other keywords.
@ -599,7 +662,7 @@ Related commands
""""""""""""""""
:doc:`create_box <create_box>`, :doc:`create_atoms <create_atoms>`,
:doc:`read_data <read_data>`
:doc:`read_data <read_data>`, :doc:`fix set <fix_set>`
Default
"""""""