"LIGGGHTS(R)-PUBLIC WWW Site"_liws - "LIGGGHTS(R)-PUBLIC Documentation"_ld - "LIGGGHTS(R)-PUBLIC Commands"_lc :c

:link(liws,http://www.cfdem.com)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

create_atoms command :h3

[Syntax:]

create_atoms type style args keyword values ... :pre

type = atom type (1-Ntypes) of atoms to create :ulb,l
style = {box} or {region} or {single} or {random} :l
  {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 (positive integer)
    region-ID = create atoms within this region, use NULL for entire simulation box :pre
zero or more keyword/value pairs may be appended :l
keyword = {basis} or {remap} or {units} or {all_in} :l
  {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 :pre
:ule

[Examples:]

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

[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"_read_data.html or
"read_restart"_read_restart.html command.  A simulation box must
already exist, which is typically created via the
"create_box"_create_box.html command.  Before using this command, a
lattice must also be defined using the "lattice"_lattice.html 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"_region.html 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"_region.html command for details.  Note that a region can be
specified so that its "volume" is either inside or outside a geometric
boundary.

IMPORTANT NOTE: 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"_minimize.html or run dynamics
with "fix nve/limit"_fix_nve_limit.html 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"_lattice.html 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"_units.html 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"_lattice.html commands specifying different
orientations, grain boundaries can be created.  By using the
create_atoms command in conjunction with the
"delete_atoms"_delete_atoms.html 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"_delete_atoms.html 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"_atom_style.html.  See the "atom
style"_atom_style.html command for more details.  See the
"set"_set.html and "velocity"_velocity.html 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 :ul

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"_set.html command can be used to override many of these
default settings.

[Restrictions:]

An "atom_style"_atom_style.html must be previously defined to use this
command.

[Related commands:]

"lattice"_lattice.html, "region"_region.html, "create_box"_create_box.html,
"read_data"_read_data.html, "read_restart"_read_restart.html

[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.
