create_atoms command

Syntax

create_atoms type style args keyword values ...

• type = atom type (1-Ntypes) of atoms to create
• style = box or region or single or random

box args = none
region args = region-ID
  region-ID = atoms will only be created if contained in the region
single args = x y z
  x,y,z = coordinates of a single atom (distance units)
random args = N seed region-ID
  N = number of atoms to create
  seed = random # seed (prime number greater 10000)
  region-ID = create atoms within this region, use NULL for entire simulation box

• zero or more keyword/value pairs may be appended
• keyword = basis or remap or units or all_in

basis values = M itype
  M = which basis atom
  itype = atom type (1-N) to assign to this basis atom
remap value = yes or no
units value = lattice or box
  lattice = the geometry is defined in lattice units
  box = the geometry is defined in simulation box units
all_in value = all_in_dist
  all_in_dist = distance from region boundary for insertion

Examples

create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5

Description

This command creates atoms on a lattice, or a single atom, or a random collection of atoms, as an alternative to reading in their coordinates explicitly via a read_data or read_restart command. A simulation box must already exist, which is typically created via the create_box command. Before using this command, a lattice must also be defined using the lattice command. The only exceptions are for the single style with units = box or the random style.

For the box style, the create_atoms command fills the entire simulation box with atoms on the lattice. If your simulation box is periodic, you should insure its size is a multiple of the lattice spacings, to avoid unwanted atom overlaps at the box boundaries. If your box is periodic and a multiple of the lattice spacing in a particular dimension, LIGGGHTS(R)-PUBLIC is careful to put exactly one atom at the boundary (on either side of the box), not zero or two.

For the region style, the geometric volume is filled that is inside the simulation box and is also consistent with the region volume. See the 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), LIGGGHTS(R)-PUBLIC does not implement the same logic as with the box style, to insure exactly one atom at the boundary. if this is what you desire, you should either use the box style, or tweak the region size to get precisely the atoms you want. With the optional all_in keyword, it can additionally be specified that the particles should be inserted a certain distance (as specified by all_in_dist) away from the region boundaries. all_in is only implemented for region insertion

For the single style, a single atom is added to the system at the specified coordinates. This can be useful for debugging purposes or to create a tiny system with a handful of atoms at specified positions.

For the random style, N atoms are added to the system at randomly generated coordinates, which can be useful for generating an amorphous system. The atoms are created one by one using the speficied random number seed, resulting in the same set of atom coordinates, independent of how many processors are being used in the simulation. If the region-ID argument is specified as NULL, then the created atoms will be anywhere in the simulation box. If a region-ID is specified, a geometric volume is filled that is inside the simulation box and is also consistent with the region volume. See the region command for details. Note that a region can be specified so that its “volume” is either inside or outside a geometric boundary.

Warning

The atoms generated by the random style will typically be highly overlapped which will cause many interatomic potentials to compute large energies and forces. Thus you should either perform an energy minimization or run dynamics with fix nve/limit to equilibrate such a system, before running normal dynamics.

The basis keyword specifies an atom type that will be assigned to specific basis atoms as they are created. See the lattice command for specifics on how basis atoms are defined for the unit cell of the lattice. By default, all created atoms are assigned the argument type as their atom type.

The remap keyword only applies to the single style. If it is set to yes, then if the specified position is outside the simulation box, it will mapped back into the box, assuming the relevant dimensions are periodic. If it is set to no, no remapping is done and no atom is created if its position is outside the box.

The units keyword determines the meaning of the distance units used to specify the coordinates of the one atom created by the single style. A box value selects standard distance units as defined by the units command, e.g. Angstroms for units = real or metal. A lattice value means the distance units are in lattice spacings.

Note that this command adds atoms to those that already exist. By using the create_atoms command multiple times, multiple sets of atoms can be added to the simulation. For example, interleaving create_atoms with lattice commands specifying different orientations, grain boundaries can be created. By using the create_atoms command in conjunction with the delete_atoms command, reasonably complex geometries can be created. The create_atoms command can also be used to add atoms to a system previously read in from a data or restart file. In all these cases, care should be taken to insure that new atoms do not overlap existing atoms inappropriately. The delete_atoms command can be used to handle overlaps.

Atom IDs are assigned to created atoms in the following way. The collection of created atoms are assigned consecutive IDs that start immediately following the largest atom ID existing before the create_atoms command was invoked. When a simulation is performed on different numbers of processors, there is no guarantee a particular created atom will be assigned the same ID.

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 atom style. See the atom style command for more details. See the set and velocity commands for info on how to change these values.

• charge = 0.0
• diameter = 1.0
• shape = 0.0 0.0 0.0
• density = 1.0
• volume = 1.0
• velocity = 0.0 0.0 0.0
• angular velocity = 0.0 0.0 0.0
• angular momentum = 0.0 0.0 0.0
• quaternion = (1,0,0,0)
• bonds = none

Note that the sphere atom style sets the default particle diameter to 1.0 as well as the density. This means the mass for the particle is not 1.0, but is PI/6 * diameter^3 = 0.5236.

Note that the ellipsoid atom style sets the default particle shape to (0.0 0.0 0.0) and the density to 1.0 which means it is a point particle, not an ellipsoid, and has a mass of 1.0.

The set command can be used to override many of these default settings.

Restrictions

An atom_style must be previously defined to use this command.

Related commands

lattice, region, create_box, read_data, read_restart

Default

The default for the basis keyword is that all created atoms are assigned the argument type as their atom type. The default for remap = no and for units = box.