diff --git a/doc/src/create_atoms.rst b/doc/src/create_atoms.rst index 20061930e4..4ab538475e 100644 --- a/doc/src/create_atoms.rst +++ b/doc/src/create_atoms.rst @@ -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 ` -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 +` 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 ` 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 ` 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 ` +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 ` or run dynamics with - :doc:`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 ` commands -specifying different orientations. By using the create_atoms command -in conjunction with the :doc:`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 ` 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 ` 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 `. Or run initial dynamics with +:doc:`pair_style soft ` or with :doc:`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 `. See the :doc:`atom style ` command for more details. See the -:doc:`set ` and :doc:`velocity ` commands for info on how -to change these values. +are defined by the chosen :doc:`atom style `. See the +:doc:`atom style ` command for more details. See the +:doc:`set ` and :doc:`velocity ` commands for info on +how to change these values. * charge = 0.0 * dipole moment magnitude = 0.0