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

edits to doc page

Browse Source
This commit is contained in:
Steve Plimpton
2022-04-26 13:58:18 -06:00
parent 782add6943
commit d04cb4ba42
1 changed files with 89 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
doc/src/create_atoms.rst
View File

@ -26,7 +26,7 @@ Syntax
region-ID = create atoms within this region, use NULL for entire simulation box
* zero or more keyword/value pairs may be appended
* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *rotate* or *maxtries* or *overlap* or *units*
* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *rotate* or *overlap* or *maxtry* or *units*
.. parsed-literal::
@ -50,8 +50,10 @@ Syntax
*rotate* values = theta Rx Ry Rz
theta = rotation angle for single molecule (degrees)
Rx,Ry,Rz = rotation vector for single molecule
*maxtries* value = N = number of tries (for a single particle to be created) before failure
*overlap* value = radius = the minimum distance from existing atoms (to avoid overlapping/huge forces)
*maxtry* value = Ntry
Ntry = number of attempts to insert a particle before failure
*overlap* value = radius
radius = only insert if at least this distance from all existing atoms
*units* value = *lattice* or *box*
*lattice* = the geometry is defined in lattice units
*box* = the geometry is defined in simulation box units
@ -100,16 +102,16 @@ particular dimension, LAMMPS is careful to put exactly one particle at
the boundary (on either side of the box), not zero or two.
For the *region* style, a geometric volume is filled with particles on
the lattice. This volume what is inside the simulation box and is
also consistent with the region volume. See the :doc:`region <region>`
command for details. Note that a region can be specified so that its
"volume" is either inside or outside a geometric boundary. Also note
that if your region is the same size as a periodic simulation box (in
some dimension), LAMMPS does not implement the same logic described
above as for the *box* style, to insure exactly one particle at
periodic boundaries. if this is what you desire, you should either
use the *box* style, or tweak the region size to get precisely the
particles you want.
the lattice. This volume is what is both inside the simulation box
and also consistent with the region volume. See the :doc:`region
<region>` command for details. Note that a region can be specified so
that its "volume" is either inside or outside its geometric boundary.
Also note that if a region is the same size as a periodic simulation
box (in some dimension), LAMMPS does not implement the same logic
described above for the *box* style, to insure exactly one particle at
periodic boundaries. If this is desired, you should either use the
*box* style, or tweak the region size to get precisely the particles
you want.
For the *single* style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
@ -121,39 +123,44 @@ randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
specified random number *seed*, resulting in the same set of particles
coordinates, independent of how many processors are being used in the
simulation. If the *region-ID* argument is specified as NULL, then
simulation. Unless the *overlap* keyword is specified, particles
created by the *random* style will typically be highly overlapped.
If the *region-ID* argument is specified as NULL, then
the created particles will be anywhere in the simulation box. If a
*region-ID* is specified, a geometric volume is filled which is both
inside the simulation box and is also consistent with the region
volume. See the :doc:`region <region>` command for details. Note that
a region can be specified so that its "volume" is either inside or
outside a geometric boundary.
volume. See the :doc:`region <region>` command for details. Note
that a region can be specified so that its "volume" is either inside
or outside its geometric boundary.
.. note::
Note that the create_atoms command adds particles to those that
already exist. This means it can be used to add particles to a system
previously read in from a data or restart file. Or the create_atoms
command can be used multiple times, to add multiple sets of particles
to the simulation. For example, grain boundaries can be created, by
interleaving the create_atoms command with :doc:`lattice <lattice>`
commands specifying different orientations.
Particles generated by the *random* style (without the *overlap* keyword)
will typically be highly overlapped which will cause many interatomic
potentials to compute large energies and forces. Thus you should either
perform an :doc:`energy minimization <minimize>` or run dynamics with
:doc:`fix nve/limit <fix_nve_limit>` to equilibrate such a system, before
running normal dynamics.
Whenever this command is used, care care should be taken to insure
that the resulting system does not contain particles which are highly
overlapped. Such overlaps will cause many interatomic potentials to
compute huge energies and forces, leading to bad dynamics. There are
several strategies to avoid this problem:
Note that this command adds particles to those that already exist.
This means it can be used to add particles to a system previously read
in from a data or restart file. Or the create_atoms command can be
used multiple times, to add multiple sets of particles to the
simulation. For example, grain boundaries can be created, by
interleaving create_atoms with :doc:`lattice <lattice>` commands
specifying different orientations. By using the create_atoms command
in conjunction with the :doc:`delete_atoms <delete_atoms>` command,
reasonably complex geometries can be created, or a protein can be
solvated with a surrounding box of water molecules.
* Use the :doc:`delete_atoms overlap <delete_atoms>` command after
create_atoms. For example, this could be used to overlay and surround
a large protein molecule with a volume of water molecules, then delete
water molecules that overlap with the protein atoms.
In all these cases, care should be taken to insure that new atoms do
not overlap existing atoms inappropriately, especially if molecules
are being added. For this reason the *overlap* keyword is provided,
also the :doc:`delete_atoms <delete_atoms>` command can be used to remove
overlapping atoms or molecules.
* For the *random* style, use the optional *overlap* keyword to avoid
overlaps when each new particle is created.
* Before running dynamics on an overlapped system, perform an
:doc:`energy minimization <minimize>`. Or run initial dynamics with
:doc:`pair_style soft <pair_soft>` or with :doc:`fix nve/limit
<fix_nve_limit>` to un-overlap the system, before running normal
dynamics.
.. note::
@ -209,7 +216,7 @@ not overlap, regardless of their relative orientations.
----------
This is the meaning of the other allowed keywords.
This is the meaning of the other optional keywords.
The *basis* keyword is only used when atoms (not molecules) are being
created. It specifies an atom type that will be assigned to specific
@ -296,33 +303,47 @@ the atoms around the rotation axis is consistent with the right-hand
rule: if your right-hand's thumb points along *R*, then your fingers
wrap around the axis in the direction of rotation.
The *maxtries* keyword limits the number of tries to generate coordinates
for a new particle that satisfies all requirements (region, var, overlap,
...) before the command fails. This keyword is available only with the
*random* style and the default number of tries is 1000 per particle. The
use of this keyword is recommended when using the *overlap* keyword,
otherwise it is usually not necessary (but can be useful).
The *overlap* keyword can be used with the *random* style (and only the
*random* style) to prevent the newly created particles from overlapping or being
created too close to others. When the particles being created are **single
atoms** the *radius* parameter passed with the keyword denotes the distance
between particle locations/centers, meaning that all new atoms will be created
at locations not closer than *radius* from the location of any other atom in
the system. When the particles being created are **molecules** the molecule
radius is taken into account so that all new molecules will be created
at locations not closer than (*radius* + molecule radius) from the location
of any existing atom in the system.
The *overlap* keyword only applies to the *random* style. It prevent
the newly created particles from overlapping or being created too
close to others. When the particles being created are **single atoms**
the *radius* parameter passed with the keyword denotes the distance
between particle locations/centers, meaning that all new atoms will be
created at locations not closer than *radius* from the location of any
other atom in the system. When the particles being created are
**molecules** the molecule radius is taken into account so that all
new molecules will be created at locations not closer than (*radius* +
molecule radius) from the location of any existing atom in the system.
.. note::
Checking for overlaps is a very costly operation (O(N) for each new atom/molecule,
where N is the number of existing atoms) and the intended use of this keyword is,
for example, adding small amounts of new atoms/molecules to relatively sparse systems
mid simulation (between consecutive runs), i.e. where running an energy minimization
procedure isn't an option.
In any case, the use of the *maxtries* keyword in combination with *overlap* is
highly recommended.
Checking for overlaps is a very costly operation (O(N) for each new
atom/molecule, where N is the number of existing atoms) and the
intended use of this keyword is, for example, adding small amounts
of new atoms/molecules to relatively sparse systems mid simulation
(between consecutive runs), i.e. where running an energy
minimization procedure isn't an option. The use of the *maxtry*
keyword in combination with *overlap* is highly recommended.
Note: does maxtry apply to var/set as well ?
The *maxtry* keyword only applies to the *random* style. It limits
the number of attempts to generate valid coordinates for a single new
particle that satisfies all requirements imposed by the *region*,
*var*, and *overlap* keywords. The default is 10 attempts per
particle before the loop over the requested *N* particles advances to
the next particle. Note that setting the *maxtry* keyword to a large
value may result in the create_atoms command running for a long time
for
before the
command fails. This keyword is available only with the *random* style
and the default number of tries is 1000 per particle. The use of this
keyword is recommended when using the *overlap* keyword, otherwise it
is usually not necessary (but can be useful).
The *units* keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the *single*
@ -348,9 +369,10 @@ assigned to created molecules in a similar fashion.
Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen :doc:`atom style <atom_style>`. See the :doc:`atom style <atom_style>` command for more details. See the
:doc:`set <set>` and :doc:`velocity <velocity>` commands for info on how
to change these values.
are defined by the chosen :doc:`atom style <atom_style>`. See the
:doc:`atom style <atom_style>` command for more details. See the
:doc:`set <set>` and :doc:`velocity <velocity>` commands for info on
how to change these values.
* charge = 0.0
* dipole moment magnitude = 0.0