.. index:: create_atoms create_atoms command ==================== Syntax """""" .. parsed-literal:: create_atoms type style args keyword values ... * type = atom type (1-Ntypes) of atoms to create * style = *box* or *region* or *single* or *random* .. parsed-literal:: *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* .. parsed-literal:: *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 """""""" .. parsed-literal:: 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 :doc:`read_data ` or :doc:`read_restart ` command. A simulation box must already exist, which is typically created via the :doc:`create_box ` command. Before using this command, a lattice must also be defined using the :doc:`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 :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), 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 :doc:`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 :doc:`energy minimization ` or run dynamics with :doc:`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 :doc:`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 :doc:`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 :doc:`lattice ` commands specifying different orientations, grain boundaries can be created. By using the create_atoms command in conjunction with the :doc:`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 :doc:`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 :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 * 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 :doc:`set ` command can be used to override many of these default settings. Restrictions """""""""""" An :doc:`atom_style ` must be previously defined to use this command. Related commands """""""""""""""" :doc:`lattice `, :doc:`region `, :doc:`create_box `, :doc:`read_data `, :doc:`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. .. _liws: http://www.cfdem.com .. _ld: Manual.html .. _lc: Section_commands.html#comm