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

Merge pull request #4567 from lammps/fix-set-command

Browse Source 
New fix set command
This commit is contained in:
Axel Kohlmeyer
2025-06-04 19:40:29 -04:00
committed by GitHub
parent 0fb02af020 ece4939708
commit b3f160c118
11 changed files with 3425 additions and 1618 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/src/Commands_fix.rst
View File

@ -219,6 +219,7 @@ OPT.
* :doc:`rigid/small (o) <fix_rigid>` * :doc:`rigid/small (o) <fix_rigid>`
* :doc:`rx (k) <fix_rx>` * :doc:`rx (k) <fix_rx>`
* :doc:`saed/vtk <fix_saed_vtk>` * :doc:`saed/vtk <fix_saed_vtk>`
* :doc:`set <fix_set>`
* :doc:`setforce (k) <fix_setforce>` * :doc:`setforce (k) <fix_setforce>`
* :doc:`setforce/spin <fix_setforce>` * :doc:`setforce/spin <fix_setforce>`
* :doc:`sgcmc <fix_sgcmc>` * :doc:`sgcmc <fix_sgcmc>`

1
doc/src/fix.rst
View File

@ -398,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:`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:`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:`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 <fix_setforce>` - set the force on each atom
* :doc:`setforce/spin <fix_setforce>` - set magnetic precession vectors 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 * :doc:`sgcmc <fix_sgcmc>` - fix for hybrid semi-grand canonical MD/MC simulations

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

18
doc/src/run.rst
View File

@ -103,14 +103,16 @@ must be done.
.. note:: .. note::
If your input script changes the system between 2 runs, then the If your input script "changes" the system between 2 runs, then the
initial setup must be performed to ensure the change is recognized by initial setup typically needs to be performed to ensure the change
all parts of the code that are affected. Examples are adding a is recognized by all parts of the code that are affected. Examples
:doc:`fix <fix>` or :doc:`dump <dump>` or :doc:`compute <compute>`, changing are adding a :doc:`fix <fix>` or :doc:`dump <dump>` or
a :doc:`neighbor <neigh_modify>` list parameter, or writing restart file :doc:`compute <compute>`, changing a :doc:`neighbor <neigh_modify>`
which can migrate atoms between processors. LAMMPS has no easy way to list parameter, using the :doc:`set <set>` command, or writing a
check if this has happened, but it is an error to use the *pre no* restart file via the :doc:`write_restart <write_restart>` command,
option in this case. 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; If *post* is specified as "no", the full timing summary is skipped;
only a one-line summary timing is printed. 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 for style = *region*, ID = a region ID
* one or more keyword/value pairs may be appended * 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 * keyword = *angle* or *angmom* or *bond* or *cc* or *charge* or
*dipole* or *dipole/random* or *quat* or *spin/atom* or *spin/atom/random* or *density* or *density/disc* or *diameter* or *dihedral* or *dipole*
*spin/electron* or *radius/electron* or or *dipole/random* or *dpd/theta* or *edpd/cv* or *edpd/temp* or
*quat* or *quat/random* or *diameter* or *shape* or *length* or *tri* or *epsilon* or *image* or *improper* or *length* or *mass* or *mol* or
*theta* or *theta/random* or *angmom* or *omega* or *omega* or *quat* or *quat/random* or *radius/electron* or *shape* or
*mass* or *density* or *density/disc* or *temperature* or *smd/contact/radius* or *smd/mass/density* or *sph/cv* or *sph/e* or
*volume* or *image* or *bond* or *angle* or *dihedral* or *sph/rho* or *spin/atom* or *spin/atom/random* or *spin/electron* or
*improper* or *sph/e* or *sph/cv* or *sph/rho* or *temperature* or *theta* or *theta/random* or *tri* or *type* or
*smd/contact/radius* or *smd/mass/density* or *dpd/theta* or *type/fraction* or *type/ratio* or *type/subset* or *volume* or *vx*
*edpd/temp* or *edpd/cv* or *cc* or *epsilon* or or *vy* or *vz* or *x* or *y* or *z* or *i_name* or *d_name* or
*i_name* or *d_name* or *i2_name* or *d2_name* *i2_name* or *d2_name*
.. parsed-literal:: .. 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 *type* value = numeric atom type or type label
value can be an atom-style variable (see below) value can be an atom-style variable (see below)
*type/fraction* values = type fraction seed *type/fraction* values = type fraction seed
@ -51,104 +140,22 @@ Syntax
type = numeric atom type or type label type = numeric atom type or type label
Nsubset = exact number of selected atoms to set to new atom type Nsubset = exact number of selected atoms to set to new atom type
seed = random # seed (positive integer) seed = random # seed (positive integer)
*mol* value = molecule ID *volume* value = particle volume for Peridynamic particle (distance\^3 units)
value can be an atom-style variable (see below)
*x*,\ *y*,\ *z* value = atom coordinate (distance units)
value can be an atom-style variable (see below) value can be an atom-style variable (see below)
*vx*,\ *vy*,\ *vz* value = atom velocity (velocity units) *vx*,\ *vy*,\ *vz* value = atom velocity (velocity units)
value can be an atom-style variable (see below) 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) 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 *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 *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 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 column specified as d2_name[N] where N is 1 to Ncol
value can be an atom-style variable (see below)
Examples Examples
"""""""" """"""""
@ -177,22 +184,26 @@ Description
Set one or more properties of one or more atoms. Since atom Set one or more properties of one or more atoms. Since atom
properties are initially assigned by the :doc:`read_data <read_data>`, properties are initially assigned by the :doc:`read_data <read_data>`,
:doc:`read_restart <read_restart>` or :doc:`create_atoms <create_atoms>` :doc:`read_restart <read_restart>` or :doc:`create_atoms
commands, this command changes those assignments. This can be useful <create_atoms>` commands, this command changes those assignments.
for overriding the default values assigned by the 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 :doc:`create_atoms <create_atoms>` command (e.g. charge = 0.0). It
be useful for altering pairwise and molecular force interactions, can be useful for altering pairwise and molecular force interactions,
since force-field coefficients are defined in terms of types. It can 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 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 when they are output in :doc:`dump <dump>` files. It can also be
for debugging purposes; i.e. positioning an atom at a precise location useful for debugging purposes; i.e. positioning an atom at a precise
to compute subsequent forces or energy. location to compute subsequent forces or energy.
Note that the *style* and *ID* arguments determine which atoms have Note that the *style* and *ID* arguments determine which atoms have
their properties reset. The remaining keywords specify which their properties reset. The remaining keywords specify which
properties to reset and what the new values are. Some strings like 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. *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 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. a range of molecule IDs.
In each of the range cases, the range can be specified as a single 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 numeric value, or with a wildcard asterisk to specify a range of
of values. This takes the form "\*" or "\*n" or "n\*" or "m\*n". For 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 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 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 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 The style *group* selects all the atoms in the specified group. The
style *region* selects all the atoms in the specified geometric style *region* selects all the atoms in the specified geometric
region. See the :doc:`group <group>` and :doc:`region <region>` commands region. See the :doc:`group <group>` and :doc:`region <region>`
for details of how to specify a group or 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. change, for the selected atoms.
Note that except where explicitly prohibited below, all of the Note that except where explicitly prohibited below, all of the
keywords allow an :doc:`atom-style or atomfile-style variable 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>` 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, it should be specified as v_name, where name is the variable
variable name. In this case, the variable will be evaluated, and its name. In this case, the variable will be evaluated, and its resulting
resulting per-atom value used to determine the value assigned to each per-atom value used to determine the value assigned to each selected
selected atom. Note that the per-atom value from the variable will be atom. Note that the per-atom value from the variable will be ignored
ignored for atoms that are not selected via the *style* and *ID* for atoms that are not selected via the *style* and *ID* settings
settings explained above. A simple way to use per-atom values from explained above. A simple way to use per-atom values from the
the variable to reset a property for all atoms is to use style *atom* variable to reset a property for all atoms is to use style *atom* with
with *ID* = "\*"; this selects all atom IDs. *ID* = "\*"; this selects all atom IDs.
Atom-style variables can specify formulas with various mathematical Atom-style variables can specify formulas with various mathematical
functions, and include :doc:`thermo_style <thermo_style>` command functions, and include :doc:`thermo_style <thermo_style>` command
@ -256,52 +267,110 @@ from a file.
.. note:: .. note::
Atom-style and atomfile-style variables return floating point Atom-style and atomfile-style variables return floating point
per-atom values. If the values are assigned to an integer variable, per-atom values. If the values are assigned to an integer
such as the molecule ID, then the floating point value is truncated to variable, such as the molecule ID, then the floating point value is
its integer portion, e.g. a value of 2.6 would become 2. truncated to its integer portion, e.g. a value of 2.6 would
become 2.
----------
.. versionchanged:: 28Mar2023 .. versionchanged:: 28Mar2023
Support for type labels was added for setting atom, bond, angle, Support for type labels was added for setting angle types
dihedral, and improper types
Keyword *type* sets the atom type for all selected atoms. A specified Keyword *angle* sets the angle type of all angles of selected atoms to
value can be either a numeric atom type or an atom type label. When the specified value. The value can be a numeric type from 1 to
using a numeric type, the specified value must be from 1 to ntypes, nangletypes. Or it can be a angle type label. See the :doc:`Howto
where ntypes was set by the :doc:`create_box <create_box>` command or type labels <Howto_type_labels>` doc page for the allowed syntax of
the *atom types* field in the header of the data file read by the type labels and a general discussion of how type labels can be used.
:doc:`read_data <read_data>` command. When using a type label it must All atoms in a particular angle must be selected atoms in order for
have been defined previously. See the :doc:`Howto type labels the change to be made. The value of nangletypes was set by the *angle
<Howto_type_labels>` doc page for the allowed syntax of type labels types* field in the header of the data file read by the
and a general discussion of how type labels can be used. :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 Keyword *angmom* sets the angular momentum of selected atoms. The
atoms. The actual number of atoms changed is not guaranteed particles must be ellipsoids as defined by the :doc:`atom_style
to be exactly the specified fraction (0 <= *fraction* <= 1), but ellipsoid <atom_style>` command or triangles as defined by the
should be statistically close. Random numbers are used in such a way :doc:`atom_style tri <atom_style>` command. The angular momentum
that a particular atom is changed or not changed, regardless of how vector of the particles is set to the 3 specified components.
many processors are being used. This keyword does not allow use of an
atom-style variable.
Keywords *type/ratio* and *type/subset* also set the atom type for a .. versionchanged:: 28Mar2023
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.
Keyword *mol* sets the molecule ID for all selected atoms. The Support for type labels was added for setting bond types
:doc:`atom style <atom_style>` being used must support the use of
molecule IDs.
Keywords *x*, *y*, *z*, and *charge* set the coordinates or Keyword *bond* sets the bond type of all bonds of selected atoms to
charge of all selected atoms. For *charge*, the :doc:`atom style the specified value. The value can be a numeric type from 1 to
<atom_style>` being used must support the use of atomic nbondtypes. Or it can be a bond type label. See the :doc:`Howto type
charge. Keywords *vx*, *vy*, and *vz* set the velocities of all labels <Howto_type_labels>` doc page for the allowed syntax of type
selected atoms. 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 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 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 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 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 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. 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 Keywords *edpd/temp* and *edpd/cv* set the temperature and volumetric
magnetic spin vectors, and the x,y,z values as components of a vector heat capacity of an eDPD particle as defined by the DPD-MESO package.
to set as the orientation of the magnetic spin vectors of the selected Currently, only :doc:`atom_style edpd <atom_style>` defines particles
atoms. This keyword was previously called *spin*. 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 Keyword *image* sets which image of the simulation box the atom is
vectors for the selected atoms and sets the magnitude of each to the considered to be in. An image of 0 means it is inside the box as
specified *Dlen* value. This keyword was previously called *spin/random*. 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 Support for type labels was added for setting improper types
electrons or fixed cores.
.. 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 Keyword *length* sets the length of selected atoms. The particles
nuclei (=0), fixed-cores (=2), or pseudo-cores (= 3). 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 Keyword *quat* uses the specified values to create a quaternion
(4-vector) that represents the orientation of the selected atoms. The (4-vector) that represents the orientation of the selected atoms. The
particles must define a quaternion for their orientation particles must define a quaternion for their orientation
(e.g. ellipsoids, triangles, body particles) as defined by the (e.g. ellipsoids, triangles, body particles) as defined by the
:doc:`atom_style <atom_style>` command. Note that particles defined by :doc:`atom_style <atom_style>` command. Note that particles defined
:doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters. The 3 by :doc:`atom_style ellipsoid <atom_style>` have 3 shape parameters.
values must be non-zero for each particle set by this command. They The 3 values must be non-zero for each particle set by this command.
are used to specify the aspect ratios of an ellipsoidal particle, They are used to specify the aspect ratios of an ellipsoidal particle,
which is oriented by default with its x-axis along the simulation 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 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 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 Keyword *quat/random* randomizes the orientation of the quaternion for
the selected atoms. The particles must define a quaternion for their the selected atoms. The particles must define a quaternion for their
orientation (e.g. ellipsoids, triangles, body particles) as defined by orientation (e.g. ellipsoids, triangles, body particles) as defined by
the :doc:`atom_style <atom_style>` command. Random numbers are used in the :doc:`atom_style <atom_style>` command. Random numbers are used
such a way that the orientation of a particular atom is the same, 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, regardless of how many processors are being used. For 2d systems,
only orientations in the xy plane are generated. As with keyword only orientations in the xy plane are generated. As with keyword
*quat*, for ellipsoidal particles, the 3 shape values must be non-zero *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. use of an atom-style variable.
Keyword *diameter* sets the size of the selected atoms. The particles .. versionadded:: 15Sep2022
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, Keyword *radius/electron* uses the specified value to set the radius
which means they will be treated as point particles. Note that this of electrons or fixed cores.
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 *shape* sets the size and shape of the selected atoms. The Keyword *shape* sets the size and shape of the selected atoms. The
particles must be ellipsoids as defined by the :doc:`atom_style particles must be ellipsoids as defined by the :doc:`atom_style
ellipsoid <atom_style>` command. The *Sx*, *Sy*, *Sz* settings ellipsoid <atom_style>` command. The *Sx*, *Sy*, *Sz* settings are
are the 3 diameters of the ellipsoid in each direction. All 3 can be the 3 diameters of the ellipsoid in each direction. All 3 can be set
set to the same value, which means the ellipsoid is effectively a to the same value, which means the ellipsoid is effectively a sphere.
sphere. They can also all be set to 0.0 which means the particle will They can also all be set to 0.0 which means the particle will be
be treated as a point particle. Note that this command does not treated as a point particle. Note that this command does not adjust
adjust the particle mass, even if it was defined with a density, the particle mass, even if it was defined with a density, e.g. via the
e.g. via the :doc:`read_data <read_data>` command. :doc:`read_data <read_data>` command.
Keyword *length* sets the length of selected atoms. The particles Keyword *smd/contact/radius* only applies to simulations with the
must be line segments as defined by the :doc:`atom_style line Smooth Mach Dynamics package MACHDYN. Itsets an interaction radius
<atom_style>` command. If the specified value is non-zero the line for computing short-range interactions, e.g. repulsive forces to
segment is (re)set to a length = the specified value, centered around prevent different individual physical bodies from penetrating each
the particle position, with an orientation along the x-axis. If the other. Note that the SPH smoothing kernel diameter used for computing
specified value is 0.0, the particle will become a point particle. long range, nonlocal interactions, is set using the *diameter*
Note that this command does not adjust the particle mass, even if it keyword.
was defined with a density, e.g. via the :doc:`read_data <read_data>`
command.
Keyword *tri* sets the size of selected atoms. The particles must be Keyword *smd/mass/density* sets the mass of all selected particles,
triangles as defined by the :doc:`atom_style tri <atom_style>` command. but it is only applicable to the Smooth Mach Dynamics package MACHDYN.
If the specified value is non-zero the triangle is (re)set to be an It assumes that the particle volume has already been correctly set and
equilateral triangle in the xy plane with side length = the specified calculates particle mass from the provided mass density value.
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 Keywords *sph/cv*, *sph/e*, and *sph/rho* set the heat capacity,
base to the top point of the triangle. If the specified value is 0.0, energy, and density of smoothed particle hydrodynamics (SPH)
the particle will become a point particle. Note that this command particles. See `this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to
does not adjust the particle mass, even if it was defined with a using SPH in LAMMPS.
density, e.g. via the :doc:`read_data <read_data>` command.
.. 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 Keyword *theta* sets the orientation of selected atoms. The particles
must be line segments as defined by the :doc:`atom_style line 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 Keyword *theta/random* randomizes the orientation of theta for the
selected atoms. The particles must be line segments as defined by 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 :doc:`atom_style line <atom_style>` command. Random numbers are used
such a way that the orientation of a particular atom is the same, 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 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 Keyword *tri* sets the size of selected atoms. The particles must be
particles must be ellipsoids as defined by the :doc:`atom_style triangles as defined by the :doc:`atom_style tri <atom_style>`
ellipsoid <atom_style>` command or triangles as defined by the command. If the specified value is non-zero the triangle is (re)set
:doc:`atom_style tri <atom_style>` command. The angular momentum to be an equilateral triangle in the xy plane with side length = the
vector of the particles is set to the 3 specified components. 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 .. versionchanged:: 28Mar2023
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 *mass* sets the mass of all selected particles. The particles Support for type labels was added for setting atom types
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 *density* or *density/disc* also sets the mass of all selected Keyword *type* sets the atom type for all selected atoms. A specified
particles, but in a different way. The particles must have a per-atom value can be either a numeric atom type or an atom type label. When
mass attribute, as defined by the :doc:`atom_style <atom_style>` using a numeric type, the specified value must be from 1 to ntypes,
command. If the atom has a radius attribute (see :doc:`atom_style where ntypes was set by the :doc:`create_box <create_box>` command or
sphere <atom_style>`) and its radius is non-zero, its mass is set from the *atom types* field in the header of the data file read by the
the density and particle volume for 3d systems (the input density is :doc:`read_data <read_data>` command. When using a type label it must
assumed to be in mass/distance\^3 units). For 2d, the default is for have been defined previously. See the :doc:`Howto type labels
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
<Howto_type_labels>` doc page for the allowed syntax of 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 and a general discussion of how type labels can be used.
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.
Keywords *rheo/rho* and *rheo/status* set the density and the status of Keyword *type/fraction* sets the atom type for a fraction of the
rheo particles. In particular, one can only set the phase in the status selected atoms. The actual number of atoms changed is not guaranteed
as described by the :doc:`RHEO howto page <Howto_rheo>`. 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, Keywords *type/ratio* and *type/subset* also set the atom type for a
and density of smoothed particle hydrodynamics (SPH) particles. See fraction of the selected atoms. The actual number of atoms changed
`this PDF guide <PDF/SPH_LAMMPS_userguide.pdf>`_ to using SPH in LAMMPS. 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 Keywords *vx*, *vy*, and *vz* set the velocities of all selected
many years and thus does not reflect the current *syntax* of the atoms.
SPH package commands. For that please refer to the LAMMPS manual.
Keyword *smd/mass/density* sets the mass of all selected particles, but Keywords *x*, *y*, *z* set the coordinates of all selected atoms.
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 *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom Keywords *i_name*, *d_name*, *i2_name*, *d2_name* refer to custom
per-atom integer and floating-point vectors or arrays that have been per-atom integer and floating-point vectors or arrays that have been
added via the :doc:`fix property/atom <fix_property_atom>` command. added via the :doc:`fix property/atom <fix_property_atom>` command.
When that command is used specific names are given to each attribute When that command is used specific names are given to each attribute
which are the "name" portion of these keywords. For arrays *i2_name* 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 and *d2_name*, the column of the array to set must also be included
the name in brackets: e.g. d2_xyz[2], i2_mySpin[3]. following the name in brackets: e.g. d2_xyz[2] or i2_mySpin[3].
Restrictions 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. the :doc:`atom_style <atom_style>` does not have that attribute.
This command requires inter-processor communication to coordinate the 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 must be ready to perform a simulation before using one of these
keywords (force fields set, atom mass set, etc). This is not keywords (force fields set, atom mass set, etc). This is not
necessary for other keywords. necessary for other keywords.
@ -599,7 +662,7 @@ Related commands
"""""""""""""""" """"""""""""""""
:doc:`create_box <create_box>`, :doc:`create_atoms <create_atoms>`, :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 Default
""""""" """""""

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -3369,6 +3369,7 @@ Rmin
RMS RMS
rmsd rmsd
rnage rnage
rnflag
rng rng
rNEMD rNEMD
ro ro

85
src/fix_set.cpp Normal file
View File

@ -0,0 +1,85 @@
/* ----------------------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
#include "fix_set.h"
#include "atom.h"
#include "error.h"
#include "set.h"
#include "update.h"
using namespace LAMMPS_NS;
using namespace FixConst;
enum{SETCOMMAND,FIXSET}; // also used in Set class
/* ---------------------------------------------------------------------- */
FixSet::FixSet(LAMMPS *lmp, int narg, char **arg) : Fix(lmp, narg, arg)
{
if (narg < 8) error->all(FLERR, 1, "Illegal fix set command: need at least eight arguments");
nevery = utils::inumeric(FLERR, arg[3], false, lmp);
if (nevery <= 0) error->all(FLERR, "Fix {} Nevery must be > 0", style);
reneighbor = utils::inumeric(FLERR, arg[4], false, lmp);
if (reneighbor < 0 || reneighbor > 1)
error->all(FLERR, "Fix {} rnflag must be 0/1", style);
// create instance of Set class
set = new Set(lmp);
// pass remaining args to Set class
// only keywords which use per-atom variables are currently allowed
// NOTE: could also allow when set style = region,
// since atoms may move in/out of regions
set->process_args(FIXSET,narg-5,&arg[5]);
}
/* ---------------------------------------------------------------------- */
FixSet::~FixSet()
{
delete set;
}
/* ---------------------------------------------------------------------- */
int FixSet::setmask()
{
int mask = 0;
mask |= END_OF_STEP;
return mask;
}
/* ----------------------------------------------------------------------
use the Set instance to update per-atom properties
NOTE: could return count of updated atoms from Set for use as fix output
---------------------------------------------------------------------- */
void FixSet::end_of_step()
{
// select which atoms to act on
set->selection(atom->nlocal);
// loop over list of actions to reset atom attributes
set->invoke_actions();
// trigger reneighboring on next timestep if requested
if (reneighbor) next_reneighbor = update->ntimestep + 1;
}

43
src/fix_set.h Normal file
View File

@ -0,0 +1,43 @@
/* -*- c++ -*- ----------------------------------------------------------
LAMMPS - Large-scale Atomic/Molecular Massively Parallel Simulator
https://www.lammps.org/, Sandia National Laboratories
LAMMPS development team: developers@lammps.org
Copyright (2003) Sandia Corporation. Under the terms of Contract
DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains
certain rights in this software. This software is distributed under
the GNU General Public License.
See the README file in the top-level LAMMPS directory.
------------------------------------------------------------------------- */
#ifdef FIX_CLASS
// clang-format off
FixStyle(set,FixSet);
// clang-format on
#else
#ifndef LMP_FIX_SET_H
#define LMP_FIX_SET_H
#include "fix.h"
namespace LAMMPS_NS {
class FixSet : public Fix {
public:
FixSet(class LAMMPS *, int, char **);
~FixSet() override;
int setmask() override;
void end_of_step() override;
private:
int reneighbor;
class Set *set;
};
} // namespace LAMMPS_NS
#endif
#endif

3814
src/set.cpp
View File

File diff suppressed because it is too large Load Diff

179
src/set.h
View File

@ -26,29 +26,168 @@ namespace LAMMPS_NS {
class Set : public Command { class Set : public Command {
public: public:
Set(class LAMMPS *lmp) : Command(lmp) {}; Set(class LAMMPS *lmp);
~Set() override;
void command(int, char **) override; void command(int, char **) override;
private: void process_args(int, int, char **);
char *id;
int *select;
int style, ivalue, newtype, count, index_custom, icol_custom;
int ximage, yimage, zimage, ximageflag, yimageflag, zimageflag;
int cc_index;
bigint nsubset;
double dvalue, xvalue, yvalue, zvalue, wvalue, fraction;
int varflag, varflag1, varflag2, varflag3, varflag4;
int ivar1, ivar2, ivar3, ivar4;
double *vec1, *vec2, *vec3, *vec4;
int discflag;
void selection(int); void selection(int);
void set(int); void invoke_actions();
void setrandom(int);
void topology(int); private:
void varparse(const char *, int); int caller; // SETCOMMAND or FIXSET
// params for atom selection
int style;
char *id;
int nlo, nhi;
bigint nlobig, nhibig;
int groupbit;
class Region *region;
// one Action = one keyword/value pair
struct Action {
int keyword;
int argindex;
int count_select, count_action;
int varflag;
int varflag1, varflag2, varflag3, varflag4;
int ivar1, ivar2, ivar3, ivar4;
int ivalue1, ivalue2, ivalue3, ivalue4, ivalue5, ivalue6;
tagint tvalue1;
bigint bvalue1;
double dvalue1, dvalue2, dvalue3, dvalue4;
};
int naction, maxaction;
Action *actions;
typedef void (Set::*FnPtrPack)(Action *);
FnPtrPack *invoke_choice; // list of ptrs to invoke functions
double *vec1, *vec2, *vec3, *vec4; // storage for evaluated peratom variables
int varflag; // 1 if any action uses a per-atom variable
int varflag1, varflag2, varflag3, varflag4; // 1 if any action uses this variable
int maxvariable; // size of peratom variable vectors
int *select; // flag for selected atoms
int maxselect; // size of select vector
int count_select; // count of selected atoms on this proc
int count_action; // count of actions on this proc, only if different than selected
// private functions
void varparse(const char *, int, Action *);
void setrandom(int, Action *);
void topology(int, Action *);
// customize by adding a process method
void process_angle(int &, int, char **, Action *);
void process_angmom(int &, int, char **, Action *);
void process_bond(int &, int, char **, Action *);
void process_cc(int &, int, char **, Action *);
void process_charge(int &, int, char **, Action *);
void process_density(int &, int, char **, Action *);
void process_diameter(int &, int, char **, Action *);
void process_dihedral(int &, int, char **, Action *);
void process_dipole(int &, int, char **, Action *);
void process_dipole_random(int &, int, char **, Action *);
void process_dpd_theta(int &, int, char **, Action *);
void process_edpd_cv(int &, int, char **, Action *);
void process_edpd_temp(int &, int, char **, Action *);
void process_epsilon(int &, int, char **, Action *);
void process_image(int &, int, char **, Action *);
void process_improper(int &, int, char **, Action *);
void process_length(int &, int, char **, Action *);
void process_mass(int &, int, char **, Action *);
void process_mol(int &, int, char **, Action *);
void process_omega(int &, int, char **, Action *);
void process_quat(int &, int, char **, Action *);
void process_quat_random(int &, int, char **, Action *);
void process_radius_election(int &, int, char **, Action *);
void process_shape(int &, int, char **, Action *);
void process_smd_contact_radius(int &, int, char **, Action *);
void process_smd_mass_density(int &, int, char **, Action *);
void process_sph_cv(int &, int, char **, Action *);
void process_sph_e(int &, int, char **, Action *);
void process_sph_rho(int &, int, char **, Action *);
void process_spin_atom(int &, int, char **, Action *);
void process_spin_atom_random(int &, int, char **, Action *);
void process_spin_electron(int &, int, char **, Action *);
void process_temperature(int &, int, char **, Action *);
void process_theta(int &, int, char **, Action *);
void process_theta_random(int &, int, char **, Action *);
void process_tri(int &, int, char **, Action *);
void process_type(int &, int, char **, Action *);
void process_type_fraction(int &, int, char **, Action *);
void process_type_ratio(int &, int, char **, Action *);
void process_type_subset(int &, int, char **, Action *);
void process_volume(int &, int, char **, Action *);
void process_vx(int &, int, char **, Action *);
void process_vy(int &, int, char **, Action *);
void process_vz(int &, int, char **, Action *);
void process_x(int &, int, char **, Action *);
void process_y(int &, int, char **, Action *);
void process_z(int &, int, char **, Action *);
void process_custom(int &, int, char **, Action *);
// customize by adding an invoke method
void invoke_angle(Action *);
void invoke_angmom(Action *);
void invoke_bond(Action *);
void invoke_cc(Action *);
void invoke_charge(Action *);
void invoke_density(Action *);
void invoke_diameter(Action *);
void invoke_dihedral(Action *);
void invoke_dipole(Action *);
void invoke_dipole_random(Action *);
void invoke_dpd_theta(Action *);
void invoke_edpd_cv(Action *);
void invoke_edpd_temp(Action *);
void invoke_epsilon(Action *);
void invoke_image(Action *);
void invoke_improper(Action *);
void invoke_length(Action *);
void invoke_mass(Action *);
void invoke_mol(Action *);
void invoke_omega(Action *);
void invoke_quat(Action *);
void invoke_quat_random(Action *);
void invoke_radius_election(Action *);
void invoke_shape(Action *);
void invoke_smd_contact_radius(Action *);
void invoke_smd_mass_density(Action *);
void invoke_sph_cv(Action *);
void invoke_sph_e(Action *);
void invoke_sph_rho(Action *);
void invoke_spin_atom(Action *);
void invoke_spin_atom_random(Action *);
void invoke_spin_electron(Action *);
void invoke_temperature(Action *);
void invoke_theta(Action *);
void invoke_theta_random(Action *);
void invoke_tri(Action *);
void invoke_type(Action *);
void invoke_type_fraction(Action *);
void invoke_type_ratio(Action *);
void invoke_type_subset(Action *);
void invoke_volume(Action *);
void invoke_vx(Action *);
void invoke_vy(Action *);
void invoke_vz(Action *);
void invoke_x(Action *);
void invoke_y(Action *);
void invoke_z(Action *);
void invoke_custom(Action *);
}; };
} // namespace LAMMPS_NS } // namespace LAMMPS_NS

9
unittest/commands/test_set_property.cpp
View File

@ -90,8 +90,9 @@ TEST_F(SetTest, NoBoxNoAtoms)
ASSERT_EQ(compute->vector_atom[0], 0); ASSERT_EQ(compute->vector_atom[0], 0);
TEST_FAILURE(".*ERROR: Illegal set command: need at least four.*", command("set type 1 x");); TEST_FAILURE(".*ERROR: Illegal set command: need at least four.*", command("set type 1 x"););
TEST_FAILURE(".*ERROR: Unknown set command style: xxx.*", command("set xxx 1 x 0.0");); TEST_FAILURE(".*ERROR: Unknown set or fix set command style: xxx.*",
TEST_FAILURE(".*ERROR: Set keyword or custom property yyy does not exist.*", command("set xxx 1 x 0.0"););
TEST_FAILURE(".*ERROR: Unrecognized set or fix set command keyword yyy.*",
command("set type 1 yyy 0.0");); command("set type 1 yyy 0.0"););
TEST_FAILURE(".*ERROR: Cannot set attribute spin/atom for atom style atomic.*", TEST_FAILURE(".*ERROR: Cannot set attribute spin/atom for atom style atomic.*",
@ -447,9 +448,9 @@ TEST_F(SetTest, EffPackage)
EXPECT_EQ(compute->array_atom[6][1], 0.5); EXPECT_EQ(compute->array_atom[6][1], 0.5);
EXPECT_EQ(compute->array_atom[7][1], 1.0); EXPECT_EQ(compute->array_atom[7][1], 1.0);
TEST_FAILURE(".*ERROR on proc 0: Incorrect value for electron spin: 0.5.*", TEST_FAILURE(".*Expected integer parameter instead of '0.5' in input script.*",
command("set atom * spin/electron 0.5");); command("set atom * spin/electron 0.5"););
TEST_FAILURE(".*ERROR on proc 0: Incorrect value for electron radius: -0.5.*", TEST_FAILURE(".*ERROR on proc 0: Invalid electron radius -0.5 in set.*",
command("set atom * radius/electron -0.5");); command("set atom * radius/electron -0.5"););
} }