shift files into doc/src

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Section_commands.html#comm)

:line

compute displace/atom command :h3

[Syntax:]

compute ID group-ID displace/atom :pre

ID, group-ID are documented in "compute"_compute.html command :ulb,l

displace/atom = style name of this compute command :l

zero or more keyword/arg pairs may be appended :l

keyword = {refresh} :l

  {replace} arg = per-atom variable ID :pre

:ule

[Examples:]

compute 1 all displace/atom

compute 1 all displace/atom refresh myVar :pre

[Description:]

Define a computation that calculates the current displacement of each

atom in the group from its original (reference) coordinates, including

all effects due to atoms passing thru periodic boundaries.

A vector of four quantities per atom is calculated by this compute.

The first 3 elements of the vector are the dx,dy,dz displacements.

The 4th component is the total displacement, i.e. sqrt(dx*dx + dy*dy +

dz*dz).

The displacement of an atom is from its original position at the time

the compute command was issued.  The value of the displacement will be

0.0 for atoms not in the specified compute group.

NOTE: Initial coordinates are stored in "unwrapped" form, by using the

image flags associated with each atom.  See the "dump

custom"_dump.html command for a discussion of "unwrapped" coordinates.

See the Atoms section of the "read_data"_read_data.html command for a

discussion of image flags and how they are set for each atom.  You can

reset the image flags (e.g. to 0) before invoking this compute by

using the "set image"_set.html command.

NOTE: If you want the quantities calculated by this compute to be

continuous when running from a "restart file"_read_restart.html, then

you should use the same ID for this compute, as in the original run.

This is so that the fix this compute creates to store per-atom

quantities will also have the same ID, and thus be initialized

correctly with time=0 atom coordinates from the restart file.

:line

The {refresh} option can be used in conjuction with the "dump_modify

refresh" command to generate incremental dump files.

The definition and motivation of an incremental dump file is as

follows.  Instead of outputting all atoms at each snapshot (with some

associated values), you may only wish to output the subset of atoms

with a value that has changed in some way compared to the value the

last time that atom was output.  In some scenarios this can result in

a dramatically smaller dump file.  If desired, by post-processing the

sequence of snapshots, the values for all atoms at all timesteps can

be inferred.

A concrete example using this compute, is a simulation of atom

diffusion in a solid, represented as atoms on a lattice.  Diffusive

hops are rare.  Imagine that when a hop occurs an atom moves more than

a distance {Dhop}.  For any snapshot we only want to output atoms that

have hopped since the last snapshot.  This can be accomplished with

something like the following commands:

write_dump      all custom tmp.dump id type x y z    # see comment below :pre

variable        Dhop equal 0.6

variable        check atom "c_dsp[4] > v_Dhop"

compute         dsp all displace/atom refresh check

dump            1 all custom 100 tmp.dump id type x y z

dump_modify     1 append yes thresh c_dsp[4] > ${Dhop} &

                refresh c_dsp delay 100 :pre

The "dump_modify thresh"_dump_modify.html command will only ouptut

atoms that have displaced more than 0.6 Angstroms on each snapshot

(assuming metal units).  The dump_modify {refresh} option triggers a

call to this compute at the end of every dump.

The {refresh} argument for this compute is the ID of an "atom-style

variable"_variable.html which calculates a Boolean value (0 or 1)

based on the same criterion used by dump_modify thresh.  This compute

evaluates the atom-style variable.  For each atom that returns 1

(true), the original (reference) coordinates of the atom (stored by

this compute) are updated.

The effect of these commands is that a particular atom will only be

output in the dump file on the snapshot after it makes a diffusive

hop.  It will not be output again until it makes another hop.

Note that in the first snapshot of a subsequent run, no atoms will be

typically be output.  That is because the initial displacement for all

atoms is 0.0.  If an initial dump snapshot is desired, containing the

initial reference positions of all atoms, one way to do this is

illustrated above.  An initial write_dump command can be used before

the first run.  It will contain the positions of all the atoms,

Options in the "dump_modify"_dump_modify.html command above will

append new output to that same file and delay the output until a later

timestep.  The {delay} setting avoids a second time = 0 snapshot which

would be empty.

:line

[Output info:]

This compute calculates a per-atom array with 4 columns, which can be

accessed by indices 1-4 by any command that uses per-atom values from

a compute as input.  See "Section

6.15"_Section_howto.html#howto_15 for an overview of LAMMPS output

options.

The per-atom array values will be in distance "units"_units.html.

This compute supports the {refresh} option as explained above, for use

in conjunction with "dump_modify refresh"_dump_modify.html to generate

incremental dump files.

[Restrictions:] none

[Related commands:]

"compute msd"_compute_msd.html, "dump custom"_dump.html, "fix

store/state"_fix_store_state.html

[Default:] none

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

: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 (offset for molecule creation) :ulb,l

style = {box} or {region} or {single} or {random} :l

  {box} args = none

  {region} args = region-ID

    region-ID = particles will only be created if contained in the region

  {single} args = x y z

    x,y,z = coordinates of a single particle (distance units)

  {random} args = N seed region-ID

    N = number of particles 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 = {mol} or {basis} or {remap} or {var} or {set} or {units} :l

  {mol} value = template-ID seed

    template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command

    seed = random # seed (positive integer)

  {basis} values = M itype

    M = which basis atom

    itype = atom type (1-N) to assign to this basis atom

  {remap} value = {yes} or {no}

  {var} value = name = variable name to evaluate for test of atom creation

  {set} values = dim name

    dim = {x} or {y} or {z}

    name = name of variable to set with x, y, or z atom position

  {rotate} values = theta Rx Ry Rz

    theta = rotation angle for single molecule (degrees)

    Rx,Ry,Rz = rotation vector for single molecule

  {units} value = {lattice} or {box}

    {lattice} = the geometry is defined in lattice units

    {box} = the geometry is defined in simulation box units :pre

:ule

[Examples:]

create_atoms 1 box

create_atoms 3 region regsphere basis 2 3

create_atoms 3 single 0 0 5

create_atoms 1 box var v set x xpos set y ypos :pre

[Description:]

This command creates atoms (or molecules) on a lattice, or a single

atom (or molecule), or a random collection of atoms (or molecules), 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, unless you specify the {single} style

with units = box or the {random} style.  For the remainder of this doc

page, a created atom or molecule is referred to as a "particle".

If created particles are individual atoms, they are assigned the

specified atom {type}, though this can be altered via the {basis}

keyword as discussed below.  If molecules are being created, the type

of each atom in the created molecule is specified in the file read by

the "molecule"_molecule.html command, and those values are added to

the specified atom {type}.  E.g. if {type} = 2, and the file specifies

atom types 1,2,3, then each created molecule will have atom types

3,4,5.

For the {box} style, the create_atoms command fills the entire

simulation box with particles 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, 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 "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), 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.

For the {single} style, a single particle 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 particles at specified

positions.

For the {random} style, N particles are added to the system at

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

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

NOTE: Particles 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.

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 "lattice"_lattice.html commands

specifying different orientations.  By using the create_atoms command

in conjunction with the "delete_atoms"_delete_atoms.html command,

reasonably complex geometries can be created, or a protein can be

solvated with a surrounding box of water molecules.

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.  The "delete_atoms"_delete_atoms.html command can be

used to remove overlapping atoms or molecules.

NOTE: You cannot use any of the styles explained above to create atoms

that are outside the simulation box; they will just be ignored by

LAMMPS.  This is true even if you are using shrink-wrapped box

boundaries, as specified by the "boundary"_boundary.html command.

However, you can first use the "change_box"_change_box.html command to

temporarily expand the box, then add atoms via create_atoms, then

finally use change_box command again if needed to re-shrink-wrap the

new atoms.  See the "change_box"_change_box.html doc page for an

example of how to do this, using the create_atoms {single} style to

insert a new atom outside the current simulation box.

:line

Individual atoms are inserted by this command, unless the {mol}

keyword is used.  It specifies a {template-ID} previously defined

using the "molecule"_molecule.html command, which reads a file that

defines the molecule.  The coordinates, atom types, charges, etc, as

well as any bond/angle/etc and special neighbor information for the

molecule can be specified in the molecule file.  See the

"molecule"_molecule.html command for details.  The only settings

required to be in this file are the coordinates and types of atoms in

the molecule.

Using a lattice to add molecules, e.g. via the {box} or {region} or

{single} styles, is exactly the same as adding atoms on lattice

points, except that entire molecules are added at each point, i.e. on

the point defined by each basis atom in the unit cell as it tiles the

simulation box or region.  This is done by placing the geometric

center of the molecule at the lattice point, and giving the molecule a

random orientation about the point.  The random {seed} specified with

the {mol} keyword is used for this operation, and the random numbers

generated by each processor are different.  This means the coordinates

of individual atoms (in the molecules) will be different when running

on different numbers of processors, unlike when atoms are being

created in parallel.

Also note that because of the random rotations, it may be important to

use a lattice with a large enough spacing that adjacent molecules will

not overlap, regardless of their relative orientations.

NOTE: If the "create_box"_create_box.html command is used to create

the simulation box, followed by the create_atoms command with its

{mol} option for adding molecules, then you typically need to use the

optional keywords allowed by the "create_box"_create_box.html command

for extra bonds (angles,etc) or extra special neighbors.  This is

because by default, the "create_box"_create_box.html command sets up a

non-molecular system which doesn't allow molecules to be added.

:line

This is the meaning of the other allowed 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

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 particle is created if its position is outside the box.

The {var} and {set} keywords can be used together to provide a

criterion for accepting or rejecting the addition of an individual

atom, based on its coordinates.  The {name} specified for the {var}

keyword is the name of an "equal-style variable"_variable.html which

should evaluate to a zero or non-zero value based on one or two or

three variables which will store the x, y, or z coordinates of an atom

(one variable per coordinate).  If used, these other variables must be

"internal-style variables"_variable.html defined in the input script;

their initial numeric value can be anything.  They must be

internal-style variables, because this command resets their values

directly.  The {set} keyword is used to identify the names of these

other variables, one variable for the x-coordinate of a created atom,

one for y, and one for z.

When an atom is created, its x,y,z coordinates become the values for

any {set} variable that is defined.  The {var} variable is then

evaluated.  If the returned value is 0.0, the atom is not created.  If

it is non-zero, the atom is created.

As an example, these commands can be used in a 2d simulation, to

create a sinusoidal surface.  Note that the surface is "rough" due to

individual lattice points being "above" or "below" the mathematical

expression for the sinusoidal curve.  If a finer lattice were used,

the sinusoid would appear to be "smoother".  Also note the use of the

"xlat" and "ylat" "thermo_style"_thermo_style.html keywords which

converts lattice spacings to distance.  Click on the image for a

larger version.

dimension       2

variable        x equal 100

variable        y equal 25

lattice         hex 0.8442

region          box block 0 $x 0 $y -0.5 0.5

create_box      1 box :pre

variable        xx internal 0.0

variable        yy internal 0.0

variable        v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) > 0.0"

create_atoms    1 box var v set x xx set y yy

write_dump      all atom sinusoid.lammpstrj :pre

:c,image(JPG/sinusoid_small.jpg,JPG/sinusoid.jpg)

The {rotate} keyword can only be used with the {single} style and

when adding a single molecule. It allows to specify the orientation

at which the molecule is inserted.  The axis of rotation is

determined by the rotation vector (Rx,Ry,Rz) that goes through the

insertion point.  The specified {theta} determines the angle of

rotation around that axis.  Note that the direction of rotation for

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 {units} keyword determines the meaning of the distance units used

to specify the coordinates of the one particle 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.

:line

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.  This is done by the processor's

communicating the number of atoms they each own, the first processor

numbering its atoms from 1 to N1, the second processor from N1+1 to

N2, etc.  Where N1 = number of atoms owned by the first processor, N2

= number owned by the second processor, etc.  Thus when the same

simulation is performed on different numbers of processors, there is

no guarantee a particular created atom will be assigned the same ID in

both simulations.  If molecules are being created, molecule IDs are

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 "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

dipole moment magnitude = 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, angles, dihedrals, impropers = none :ul

If molecules are being created, these defaults can be overridden by

values specified in the file read by the "molecule"_molecule.html

command.  E.g. the file typically defines bonds (angles,etc) between

atoms in the molecule, and can optionally define charges on each atom.

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.

Note that the {peri} style sets the default volume and density to 1.0

and thus also set the mass for the particle to 1.0.

The "set"_set.html command can be used to override many of these

default settings.

:line

[Restrictions:]

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

command.

A rotation vector specified for a single molecule must be in

the z-direction for a 2d model.

[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 (when single atoms are

being created).  The other defaults are {remap} = no, {rotate} =

random, and {units} = lattice.