View source for Code: WARP - Description

Warp 2001 - Atomistic Stress Simulator, Copyright 1998-2001

Authored by Steve Plimpton

(505) 845-7873, sjplimp@sandia.gov

Dept 9233, MS 1111, Sandia National Labs, Albuquerque, NM 87185-1111
----

To download this description right click on this [[Media:WARP-Overwiev.txt‎|link]] and select "Save Link As...".


== Synopsis ==
Warp 2001 - Copyright 1998-2001 - January 2001 release

This distribution contains the Warp code which is a parallel molecular
dynamics simulation for modeling stress and strain in materials using
embedded atom method (EAM) and Lennard-Jones (LJ) potentials.  It is
written in F90 and performs message-passing via MPI calls.  Thus it
should be portable to virtually any parallel or single-processor
machine.  This code is copyrighted property of Sandia National
Laboratories.  Please contact the author(s) for a copy of the source
code or further information.

== Compiling WARP ==
Type make to see a list of supported machines.  You can add a new
machine to the list by creating an appopriate Makefile.machine file
and adding the new machine to the target list in Makefile.  The
"serial" target does not require MPI be installed on your workstation.
The other targets require MPI.

If the -DCRACK compiler flag is set in Makefile.machine, Warp adds the
command "no neighbor" that enables crack propagation simulations.


== Running WARP ==
Warp is run by redirecting an input script to stdin, e.g.

warp_machine < in.file
mpirun -np 16 warp_machine < in.file 

== Input file ==

The input script consists of a series of single-line commands.  Most
of the input commands take one or more parameters.  The keyword for
each command should begin in the leftmost column and all characters in
the command should be in lower-case.  Parameters can be separated by
arbitrary numbers of spaces and/or tabs (so long as the command fits
on one line).

The order of commands for performing a simulation are as follows:

<pre>
(1) set parameters			   only those different than defaults
(2) create box				   mandatory

Either:
  (3) orient and origin                    as needed
  (4) select region			   mandatory
  (5) define cutout			   as needed
  (6) create atoms			   mandatory (loop on 3-6 as desired)
  (7) check for atom overlap		   as needed
  (8) select and create types and eltypes  as needed
  (9) select and create vels		   as needed
Or:
  (3) scale read                           as needed
  (4) type translate                       as needed
  (5) read atoms			   mandatory
  (6) check for atom overlap		   as needed
  (7) select and create types and eltypes  as needed
  (8) select and create vels		   as needed
Or:
  (3) read restart                         mandatory

(10) select and create fixes		   as needed
(11) apply temp and pres controls	   as needed

(12) run				   can perform multiple times,
					      changing parameters as desired
Or:
(13) relax				   minimize potential energy
</pre>

Note that several parameters must be defined (if not default) before
the global simulation box is created and memory is allocated in step
(2).  These settings include units, extra memory, potential, neighbor,
processor grid, periodicity, and lattice.

----------------------------------------------------------------------------

The following is a complete list of valid Warp inputs and the "type"
of parameters that should be used (i=integer,r=real,c=character
string) in the input script.  More details are given below.  Some of
the commands are only available with certain compiler flags.

----------------------------------------------------------------------------

<pre>
# comment

units			lj				(c)
extra memory		2.0 1.5 2.0 2.5			(rrrr)

timestep		0.001				(r)
augment t1  1           (i)
use interp  1           (i)
use dimer   0           (i)
gsmooth factor 99.0     (r)

potential		eam 0 ../potentials/cuu7	(cic)
potential		lj/cut 2.5			(cr)
potential		lj/smooth			(c)
potential		meam matlibfile meamcardfile    (ccc)
table			10000				(i)

neighbor                0.3 10                          (ri)
no neighbor		2 3				(ii)
processor grid          10 10 10                        (iii)

thermo			0				(i)
snapshot		1000 file xmovie		(icc)
snap thresh		centro 2.0			(cr)
snap column		2				(i)
snap limits		inf inf inf inf -1.0 1.0	(rrrrrr)
restart			1000 file			(ic)
write atoms		1000 file			(ic)
write dynamo		1000 file			(ic)
write meamstat		1000 file			(ic)
diagnostic		name 100 diagfile 2 10.0 ...	(cicirrrrr)

numatoms		1000			  	(i)
periodicity		0 1 0				(iii)
lattice			fcc 1.0				(cr)

create box		-10.0 10.0 0.0 20.0 0.0 20.0	(rrrrrr)

orient			x 1 0 0				(ciii)
orient			y 0 1 0				(ciii)
orient			z 0 0 1				(ciii)
origin			0.0 0.0 0.0			(rrr)

select region		all
select region		0.0 inf 0.0 inf inf inf		(rrrrrr)
select type		1				(i)
set eltype		1				(i)

define cutout		0 region -5.0 5.0 inf inf -3.0 inf  (icrrrrrr)
define cutout		1 cylinder x y z 3.0 4.0 2.0 -10.0 inf   (iccccrrrrr)
define cutout		0 sphere 0.0 0.0 2.0 1.0	(icrrrr)
define cutout		1 cylinder x y z 3.0 4.0 2.0 -10.0 inf   (iccccrrrrr)

create atoms		1				(i)

scale read		1.0 1.0 1.0			(rrr)
type translate          28 1                            (ii)
type translate          1  3                            (ii)
box toler  		0.00005       (r)
read atoms		atomfile			(c)

check overlap		0.25 1				(ir)

create types		1				(i)
create eltypes		1				(i)

displace atoms		100.0 xyz 1.0 0.0 0.0		(rcrrr)
displace atoms		100.0 ramp vy 0.0 5.0 x -10.0 10.0	(rccrrcrr)
displace atoms		100.0 twist 0.0 1.0 x y z 0.0 5.0 -10.0 10.0
							(rcrrcccrrrr)
displace atoms		100.0 expand 1 1 0 0.0 0.0 0.0 1000.0	(rciiirrrr) 

check vels              1                               (i)
create vels		thermal 300.0 39480		(cri)
create vels		ramp vy 0.0 5.0	x -10.0 10.0	(ccrrcrr)
create vels		twist 0.0 1.0 x y z 0.0 5.0 -10.0 10.0   (crrcccrrrr)
create vels		expand 1 1 0 0.0 0.0 0.0 1000.0	(ciiirrrr) 

create fixes		none				(c)
create fixes		xyz 0 1 -1			(ciii)
create fixes		twist x y z 0.0 2.0 1 1 1	(ccccrriii)
create fixes		external 0.1 0.0 0.0		(crrr)

temp type		0				(i)
temp control		none				(c)
temp control		rescale 300.0 10 10.0		(crir)
temp control		hoover 300.0 1.0		(crr)
temp adjust		none				(c)
temp adjust		xyz 0 1 1			(ciii)
temp adjust		ramp vy 0.0 5.0 x -10.0 10.0	(ccrrcrr)
temp adjust		twist 0.0 1.0 x y z 0.0 5.0 -10.0 10.0   (crrcccrrrr)

pres control		volume 0.0 0.5			(crr)

read restart		filename			(c)

reset timestep		0				(i)
run			1000			  	(i)

relax			0				(i)
relaxp		1 1500 4 40 1e-8 1e-6 (iiiirr)

----------------------------------------------------------------------------

# comments

blank lines are ignored
everything on a line after last parameter is ignored
lines starting with a # are echoed into the log file

----------------------------------------------------------------------------

# units

kind of units to use in the simulation

options:	lj	Lennard Jones reduced units
		real	Angstroms, degrees K, eV, etc

must be specified before "create box" command
default = lj

----------------------------------------------------------------------------

# extra memory

1st parameter = extra_own = padding factor on allocation of
				owned atom arrays 
2nd parameter = extra_ghost = padding factor on allocation of
				ghost atom arrays 
3rd parameter = extra_neigh = padding factor on allocation of
				neighbor lists 
4th parameter = extra_buf = padding factor on allocation of
				communication buffers 

factors that affect how much extra memory is allocated when a problem is setup
factor of 1.0 means no padding, factor of 2.0 means 2x longer arrays
typically don't need to change default settings unless Warp tells you
  to "boost" some factor at run-time
must be specified before "create box" command
default = 2.0 2.0 2.0 3.0

----------------------------------------------------------------------------

# timestep

timestep size for MD run
for lj units, is in units of tau
for real units, is in picoseconds
default = 0.001 for both lj and real

----------------------------------------------------------------------------

# augment t1

flag specifying whether augmentation of t1 coefficient is needed,
     only significant for MEAM
0 = don't augment t1
1 = do augment t1
if don't augment t1, t1 value from the input file is not modified
if augment t1, then 3/5*t3 is added to t1

default = 1

----------------------------------------------------------------------------

# use interp

flag specifying whether interpolation of phi is used for energy calculation
     only significant for MEAM
0 = don't use interpolation
1 = do use interpolation
if not use interp then phi is calculated precisely
                       # and -100 is used for small log values (as Dynamo)
if use interp, polynomial interpolation of phi is used (faster)

default = 1

----------------------------------------------------------------------------

# use dimer

flag specifying whether dimer is used to calculate reference density and phi
     only significant for MEAM
0 = don't use dimer
1 = do use dimer
if use dimer then density (and phi) is calculated the same way as in Dynamo
             otherwise dimer is not used

default = 0

----------------------------------------------------------------------------

# gsmooth factor

factor determining the length of the G smoothing region
  must be positive number
  only significant for MEAM if ibar is 0 or 4
if gsmooth factor is larger, G smoothing region is smaller, sharper step
99.0 = short smoothing region, sharp step
0.5  = long smoothing region, smooth step
power of the smoothing function will be -(gsmooth_factor/2)

default = 99.00

----------------------------------------------------------------------------

# potential

kind of potential energy and force interactions to use between all
  pairs of interacting atoms

examples:
	potential	eam 0 filename
	potential	lj/cut 2.5
	potential	lj/smooth
	potential	meam matlibfile meamcardfile

eam option means use a EAM potential from the specified file, the cutoff
  for the potential is contained in the file
for the eam option, if the integer flag is 0, the EAM file is assumed 
  to be in the DYNAMO single-element funcfl format
for the eam option, if the integer flag is 1, the EAM file is assumed
  to be in the DYNAMO setfl alloy format, and the potentials are assigned
  to element type numbers in the order in which they appear in the file

lj/cut option means use a cutoff LJ potential with the specified
  cutoff in units of sigma
lj/smooth option means use a LJ potential that goes smoothly to zero
  in both the energy and force at a hard-wired cutoff value of
  approximately 1.71 sigma
must be specified before "create box" command
default = lj/cut with 2.5 sigma cutoff

meam option means use a MEAM (modified EAM) potential, reading material
  parameters from the matlibfile and the meam card data from meamcardfile.
  See the file MEAM.README for an overview of what data is needed in the
  meam card.

----------------------------------------------------------------------------

# table

pre-tabulate the potential energy and force functions in a table of the
  specified size to speed force computations
the force and energy routines perform linear interpolations between
  adjacent table values to estimate a force and energy
the specified size is the length of the table, the larger the number
  the more accurate the table and the more memory used
10000 is a typical table length
a value of 0 means no tables are used, the forces and energies are
  evaluated in the usual analytic fashion
default: 0

----------------------------------------------------------------------------

# neighbor

1st parameter = skin thickness of neighbor shell
2nd parameter = delay check for neighbor re-build 
		until this many steps since last build

factors that affect how and when neighbor lists are constructed
communication is done to acquire all atoms within distance cutoff + skin
after delay # of steps, check is done every timestep based on
  atom movement to see if neighbor list should be rebuilt -
  e.g. delay = 5 means start checking 5 timesteps after last rebuild
must be specified before "create box" command
default: skin = 0.3, delay = 10

----------------------------------------------------------------------------

# no neighbor               (ONLY available with CRACK compiler flag)

1st parameter = type A
2nd parameter = type B

turn-off force interactions between atom pairs of types A and B
can be used to create an initial slit crack
works because neighbor-list formation routine checks for these interactions
setting both types to 0 essentially turns off this command
default = 0 0

----------------------------------------------------------------------------

# processor grid

parameters = # of processors in x,y,z dimensions

specify 3-d grid of processors to map to physical simulation domain
total # of processors must equal product of 3 parameters
must be specified before "create box" command
if you do not specify this, code will make best guess of how to map
  procs to the box, so as to minimize the surface area of proc sub-domains
if the 1st param is zero, then the code reverts to its default assignment
  and you don't need the other 2 parameters
default = code matches procs to simulation box

----------------------------------------------------------------------------

# thermo

print thermodynamic info to screen and log file every this many timesteps
value of 0 means print only at beginning and end of a run
default = 0

----------------------------------------------------------------------------

# snapshot

1st parameter = call snapshot routine every this many steps
2nd parameter = filename to dump shapshots to
3rd parameter = "xmovie" or "pds" or "ensight6bin" or "ensight6text" or
                "ensight6binc"

dump snapshot of atom positions to a file every this many timesteps
value of 0 means never dump
non-zero value also writes snapshot at start and end of run
any previous snapshot file is closed
new filename can exist, will be overwritten
snapshot info is dumped in one of 4 formats:
  "xmovie" format, which is ASCII text with descriptors for timestep,
    number of atoms, bounding box, and one line per atom
  "pds" format  writes snapshots in Sandia's PDS format, which is
    portable binary format, the tools/pds2xmovie.f file can be used
    to extract XMOVIE snapshots from a PDS file
  "ensight6bin"/"ensight6binc" format writes case and variable file
    for the visualization software Ensight. Variable file is written
    in Fortran/C binary form, one variable file for all time steps
  "ensight6text" writes case and variable files for the visualization
    software Ensight, one variable file for one time step
if the 3rd parameter is omitted, default "ensight6bin" format is used
info in snapshot file is affected by "snap thresh" and "snap column" commands
default = 0

----------------------------------------------------------------------------

# snap thresh

1st parameter = "none" or "energy" or "centro"
2nd parameter = value

only dump an atom to the snapshot file if a value associated with the atom
  is larger than the specified threshhold value
choices for the value are "none" = all atoms are dumped out in which case
  the 2nd parameter need not be specified, "energy" = potential energy
  of the atom, and "centro" = centrosymmetry value of the atom
energy and distance^2 units for the threshhold value are in appropriate
  real or lj units
can be used to throttle the output to only defect atoms
default = none

----------------------------------------------------------------------------

# snap column

1st parameter = 0,1,2,3,4,5,6,7

add columns of output to the snapshot file for each dumped atom
for parameter = 0, no additional info beyond the atom type and xyz coords is
  dumped
for parameter = 1, the atom's potential energy is also dumped 
for parameter = 2, the atom's centrosymmetry value is also dumped 
for parameter = 3, both the atom's pot eng and centrosymmetry values are dumped
for parameter = 4, the atom's stress is dumped
for parameter = 5, the atom's stress and pot eng are dumped
for parameter = 6, the atom's stress and centrosymmetry are dumped
for parameter = 7, the atom's stress, centrosymmetry and pot eng are dumped
default = 0

----------------------------------------------------------------------------

# snap limits

6 parameters = xlo xhi ylo yhi zlo zhi (in cubic lattice units)

only dump an atom to the snapshot file if its coordinates lie within the
  specified region.
for a simulation with variable domain size (e.g. constant pressure), this
  region grows in proportion with the box size
default = inf inf inf inf inf inf


----------------------------------------------------------------------------

# restart

1st parameter = write a restart file every this many steps
2nd parameter = prefix file name to write to

create a restart file every this many timesteps
full filename is prefix.timestep
value of 0 means never create one (don't need filenames in this case)
restart file stores atom positions and velocities in binary form
allows program to restart from where it left off via "read restart" commmand
new restart files overwrite any previous files
restart files are written in one of 2 formats, depending on which
  file is compiled into the code: restart.f or restart_pds.f
the restart.f file writes in a machine-specific binary format
the restart_pds.f file writes in Sandia's PDS format, which is
  portable binary format
default = 0

----------------------------------------------------------------------------

# write atoms

1st parameter = write an atom file every this many steps
2nd parameter = prefix file name to write to

create an atom file every this many timesteps
full filename is prefix_timestep.atoms
value of 0 means never create one (don't need filenames in this case)
atom file stores header with time step, number of atoms and box bounds
 also, element type, atom type and position are stored for every atom
new atom files overwrite any previous files
default = 0

----------------------------------------------------------------------------

# write dynamo

1st parameter = write a dynamo format restart file every this many steps
2nd parameter = prefix file name to write to

create a dynamo format file every this many timesteps
full filename is prefix_timestep.dynamo
value of 0 means never create one (don't need filenames in this case)
dynamo format restart file stores:
 comment line
 numatoms, numelementypes, constant, angle
 box bounds
 atomic masses and atomic numbers
 also, for each atom it stores:
 position, velocity and type
new dynamo files overwrite any previous files
default = 0

----------------------------------------------------------------------------

# write meamstat

1st parameter = write a dynamo format meamstat file every this many steps
2nd parameter = prefix file name to write to

create a dynamo format meamstat file every this many timesteps
full filename is prefix_timestep.meamstat
value of 0 means never create one (don't need filenames in this case)
dynamo format meamstat file stores:
 atomic data:number, type, positions, energy
             velocities
             forces
             el. density, f(rho), phi(r)
             rho0  rho(1)^2  rho(2)^2  rho(3)^2
new meamstat files overwrite any previous files
default = 0

----------------------------------------------------------------------------

# numatoms

number of atoms - if specified before create box, it saves memory, otherwise
                  maximum number of atoms is estimated from lattice constant
                  and box size
default = 0

----------------------------------------------------------------------------

# diagnostic

1st parameter = identifier name of routine
2nd parameter = call diagnostic routine every this many steps
3rd parameter = filename to dump diagnostic results to
4th parameter = # of remaining parameters (maximum of 5)
5th-9th parameters = parameters to pass to diagnostic routine

call a user-specified diagnostic routine and write results into file
1st parameter is a string that is checked inside diagnostic.f
  in the diagalloc routine when a run is performed
if 2nd parameter = 0, turn off diagnositcs (no need for rest of parameters)
non-zero value also calls routine at start and end of run
any previous diagnostic file is closed
new filename can exist, will be overwritten
4th parameter can be from 0 to 5
5th-9th parameters are visible by diagnostic routine
default = 0

----------------------------------------------------------------------------

# diag types

whether to write a separate diagnostic file for each type
0 = write one diagnostic file providing average for all types
1 = write separate diagnostic files for each atom type

default = 0

----------------------------------------------------------------------------

# periodicity

whether each x,y,z dimension is periodic or not
0 = non-periodic, 1 = periodic
if non-periodic, forces do not interact across the boundary,
  atoms do not migrate across the boundary, and ghost atoms are not
  created across the boundary
if non-periodic, atoms will be "lost" if they move outsize the simulation
  box specified by the "create box" command
must be specified before "create box" command
default = 1 1 1

----------------------------------------------------------------------------

# lattice

1st parameter = fcc
2nd parameter = density or lattice constant of cubic unit cell

what type and what spacing will be used for the fundamental lattice of atoms
fcc = 4 atoms per cubic unit cell
2nd parameter determines how closely the atoms are packed on the lattice
for lj units, 2nd parameter is reduced density, from which a lattice
  constant is derived
for real units, 2nd parameter is the cubic lattice constant in Angstroms
must be specified before "create box" command
default = fcc and 1.0

----------------------------------------------------------------------------

# create box

parameters = xlo xhi ylo yhi zlo zhi

bounds of the global simulation box in cubic lattice units
for example, 0 10 0 10 0 10 = a box of size 10x10x10 cubic unit cells of atoms
  which means 4000 atoms (in a 100 orientation) will fit in the box
  for a fcc lattice (4 atoms/cubic unit cell)
if non-periodic boundaries are specified, you must insure the box is
  large enough that atoms will never leave the box during the course
  of the simulation, else they will be lost
unlike the other "create" commands, this one does not work in conjunction
  with "select" commands, all 6 parameters must be explicitly specified
when this command is executed, the processor grid is layed out, the global
  box is partitioned across procs, neighbor list and communication data
  structures are setup, and all memory is allocated for the simulation
re-issuing this command essentially starts a simulation from scratch, all old
  information (including atoms) is deleted

----------------------------------------------------------------------------

# orient

1st parameter = "x" or "y" or "z" = box direction
2nd-4th parameters = lattice orientation that is along this box direction
			(e.g. 111 or 110 or 1,1,-2)

specify orientation of lattice (in cubic sense) along box directions (xyz)
3 basis vectors must be mutually orthogonal and be a right-handed system
  such that (X cross Y) is in same direction as Z
each orientation vector should be in irreducible form (minimum integers)
these vectors are used when the "create atoms" command generates a lattice
  of atoms
default: x = 100, y = 010, z = 001

----------------------------------------------------------------------------

# origin

x,y,z origin of a cubic lattice in lattice units
for example, 0.5 0.5 0.0 means a lattice displaced by 1/2 a cubic cell
  in both the x and y box dimensions
this origin is used as a starting point when the "create atoms" command
  generates a lattice of atoms
default = 0.0 0.0 0.0

----------------------------------------------------------------------------

# select region

one parameter = all (entire simulation box)
6 parameters = xlo xhi ylo yhi zlo zhi (in cubic lattice units)

this command must be used prior to each "create atoms" or "create types"
  command to specify the volume of interest
if used prior to a "create atoms" command, means to select a
  rectangular volume to create atoms within
if used prior to a "create types" command, means to select all
  previously created atoms within a rectangular volume
if a single parameter "all" is used, this selects the entire box
if 6 parameters are used, they specify the bounds of the rectangular region
  in cubic lattice units (NOT in reduced units of sigma or in Angstroms)
if "inf" is used as one of the 6 parameters, it means extend the bound
  to the global simulation box boundary in that direction
a specified parameter must be contained in the simulation box
this command must be used after the "create box" command

----------------------------------------------------------------------------

# select type

this command must be used prior to each "create vels" or "create fixes"
  command to specify the atoms of interest
selects all previously created atoms of the specified type

----------------------------------------------------------------------------

# set eltype

this command may be used prior to "create atoms" to set the element type
  of the atoms to be created.

----------------------------------------------------------------------------

# define cutout

if desired, this command must be used prior to each "create atoms" or
  "create types" command to define a cutout volume (inside or outside)
  that will be intersected with the selected region to form a new complex
  volume that will be used by the "create atoms" and "create types" commands

examples:
	define cutout		0 region xlo xhi ylo yhi zlo zhi
	define cutout		1 cylinder x y z c0 c1 rad zlo zhi
	define cutout		0 sphere cx cy cz rad
	define cutout		1 cylshell x y z c0 c1
                                           radouter radinner zlo zhi

the 1st argument is 0 if the "inside" of the cutout
  volume should be included and the "outside" excluded, the 1st argument
  is 1 if the "outside" of the cutout volume should be included and the
  "inside" excluded
for the region option, a rectangular volume is defined as the cutout volume,
  the meaning of the 6 parameters is the same as for the "select region"
  command, "inf" can be used for any of the 6 parameters
for the cylinder option, a cylindrical volume is defined as the cutout
  volume, the x y z parameters define the orientation of the cylinder
  with respect to the simulation box directions and the other 5 parameters
  define the size of the cylinder: c0 and c1 are the coordinates of the
  center axis of the cylinder in the 1st 2 dimensions, rad is its radius,
  and the cylinder extends along its axis in the 3rd dimension from
  zlo to zhi where either of zlo,zhi may be "inf" which means extend
  to the simulation box boundary - e.g. "cylinder y z x 0.0 2.0 1.0 -5.0 inf"
  means the cylinder axis lies along the x direction of the simulation box
  at y = 0.0 and z = 2.0, the cylinder has a radius of 1.0, and it extends
  from x = -5.0 to the upper +x box boundary
for the sphere option, a spherical volume is defined as the cutout volume,
  the next 3 parameters are the origin of the sphere, and the last parameter
  is the radius
for the cylshell option, the meaning of all arguments is the same as
  for the cylinder option, except that 2 radii are defined, radouter
  and radinner, the created atoms lie between (or outside of) the 2 radii
default = none

----------------------------------------------------------------------------

# create atoms

parameter = type of atoms to be created

create a lattice of atoms so as to tile the entire volume specified by
  the "select region" and "define cutout" commands
the atoms are created at an orientation and from an origin specified
  by the most recent "orient" and "origin" commands
the created atoms are assigned a velocity of 0.0

----------------------------------------------------------------------------

# scale read

parameters = x, y, and z direction scale factors

scale all atomic coordinates read in by the given factor in each
  direction.  Note that this is only applied to read-in, not created
  atoms, and must be specified before the atom file is read.

----------------------------------------------------------------------------

# type translate

translate a given atom type in the atom coord file to another type in Warp

1st parameter = atom type in atom coord file
2nd parameter = atom type in Warp

This command is convenient when the atom coord file lists atoms by atomic
  number (e.g. Ni=28, Al=13, H=1) and these must be converted to another
  enumeration (e.g. Ni=1, Al=2, H=3 for the nialhjea EAM potential file)

----------------------------------------------------------------------------

# box toler

distance determining the tolerance of simulation box size
  must be positive number
  only significant if atoms are read from file
  must be specified before "read atoms" command

default = 1.0E-14

----------------------------------------------------------------------------

# read atoms

parameter = file to read atom coords from

read a single XMOVIE snapshot from a file to initialize all the atoms
  for the simulations
takes the place of "create atoms" or "read restart" command
atom coords and types are extracted from the file
box size specified in snapshot is assumed to be equal or smaller
  than box specified by "create box" command
all atom coords in file are used as-is and must fit in simulation box,
  are not checked for periodic boundary conditions
atom coords are NOT in cubic lattice units, but in simulation box units,
  e.g. Angstroms for real units or reduced units for lj units
the created atoms are assigned a velocity of 0.0

----------------------------------------------------------------------------

# check overlap

check all atoms for too-close an overlap with neighboring atoms
  and delete one atom in the overlapping pair

1st parameter = overlap occurs within this distance (in cubic lattice units)
2nd parameter = type of atom to delete if overlap occurs

this command is useful if previous "create atoms" commands may have
  created duplicate atoms on region boundaries or created 2 atoms too close
  together (e.g. at a grain boundary)
the specified type is used to choose which atom of the overlapped pair
  can be deleted
all atom pairs are checked and the code attempts to delete one atom in 
  an overlapping pair if it is of the specified type
if neither or both of the overlapping atoms can be deleted, various errors
  and warnings may be generated if the code cannot uniquely choose which
  atom to delete, the only solution for this may be to
  use the "select" commands more carefully with epsilon increments to
  prevent atom overlap at creation time
using a type of 0 will flag errors or warnings for all overlaps since
  neither atom in the overlapped pair can be deleted
this command can be done anytime after atoms are created

----------------------------------------------------------------------------

# create types

parameter = type to be assigned

assign the specified type to all atoms within the entire volume specified by
  the "select region" and "define cutout" commands

----------------------------------------------------------------------------

# create eltypes

parameter = element type to be assigned

assign the specified element type to all atoms within the entire volume 
  specified by the "select region" and "define cutout" commands
note that currently multiple element types are available only for the
  MEAM potential

----------------------------------------------------------------------------

# displace atoms

displace all atoms selected by the "select type" command to new positions
useful for setting up an initial strain on the system

examples:		
	displace atoms		dt xyz vx vy vz
	displace atoms		dt ramp vy vlo vhi x clo chi
	displace atoms		dt twist vlo vhi x y z c0 c1 clo chi
	displace atoms		dt expand 1 1 0 cx cy cz doubletime 

for all options, a "select type" must be in effect to first select
  atoms of a particular type
for all options, a velocity is computed for each selected atom, exactly
  as it would be by the "create vels" command for that option,
  the velocity is not assigned to the atom, rather the atom is moved
  to a new position as if that velocity were applied for a time dt
for all options, the velocity parameters and their meaning and units are 
  exactly the same as they are for the corresponding "create vels" command
for the xyz option, the velocity for each atom is the specified vx,vy,vz
for the twist option, the new atom coordinate is computed by rotating
  the atom to a new coord, not by moving the atom in a straight line
the units of dt are in tau (lj units) or picoseconds (real units)
for the xyz option, the velocity units are cubic lattice units
  per time - e.g. lattice-spacings/tau or lattice-spacings/picosecond

----------------------------------------------------------------------------

# check vels

check or do not check velocities
0 = don't check velocities
1 = check velocities
if check velocities, vhi must be greater than vlo
if don't check velocities, vhi can be lower than vlo, thus compression
  can be applied

default = 1

----------------------------------------------------------------------------

# snap types

whether to snapshot types or eltypes
0 = snapshot eltypes
1 = snapshot types

default = 0

----------------------------------------------------------------------------

# recalculate output

whether to rebuild neighbors and recalculate values before output
0 = don't reneighbor before output
1 = reneighbor and recalculate values before output

default = 0

----------------------------------------------------------------------------

# create vels

assign initial velocities to all atoms selected by the "select type" command
this command adds a new velocity to a current initial velocity for each atom,
  thus multiple "create vels" commands can be used to build up a
  desired velocity distribution - e.g. a ramp profile superposed on a
  thermal background

examples:		
	create vels	thermal 300.0 seed
	create vels	ramp vy vlo vhi x clo chi
	create vels	twist vlo vhi x y z c0 c1 clo chi
	create vels	expand 1 1 0 cx cy cz doubletime

for all options, a "select type" must be in effect to first select
  atoms of a particular type
thermal option means create a Boltzmann distribution at the specified
  temperature using a random number generator initialized with the
  specified integer seed
for the thermal option the units of temperature are reduced units or
  degrees Kelvin depending on the "units" command previously specified
for the thermal option, the center-of-mass motion of the selected atoms
  will be zeroed
ramp option means assign velocities ranging from vlo -> vhi to a
  specfied velocity component (vx or vy of vz) of the selected atoms
for the ramp option, the assigned velocity value depends on where the
  specified coordinate (x or y or z) of the atom falls
  within the specified coordinate clo -> chi bounds - e.g. for a clo -> chi
  region ranging from -10.0 to 10.0 in "x" and a vlo -> vhi specification
  of 0.0 -> 5.0 for "vy", then a selected atom with an x-coord of 0.0 will
  be assigned a vy velocity of 2.5
for the ramp option, an atom whose coordinate falls outside the specified
  bounds will be given the min or max velocity
for the ramp option, if vlo = vhi then all the selected atoms will be
  assigned the same velocity, however clo and chi must still be specified
for the ramp option, clo must be smaller than chi
for the ramp option the units of vlo and vhi are in cubic lattice units
  per time - e.g. lattice-spacings/tau or lattice-spacings/picosecond -
  and the units of clo and chi are in cubic lattice units as well
twist option means assign velocities to selected atoms in a cylinder so that
  the cylinder initially spins about its axis at a rotation rate varying
  from vlo -> vhi from one end to the other, the cylinder is centered
  on c0,c1 in a coordinate system defined by x y z and the velocities
  are applied along the cylinder's z axis from clo to chi
for the twist option the units of vlo and vhi are in rotations per time -
  e.g. rotations/tau or rotations/picosecond depending on the "units" flag -
  and the units of c0, c1, clo, and chi are in cubic lattice units
for the twist option the x,y,z specification defines which box directions
  correspond to the x,y plane and z-axis of the cylinder
for the twist option, the assigned velocity depends on where the atom's
  coordinates fall within the cylinder - e.g. for the command
  "create vels twist 0.0 0.1 y z x 0.0 2.0 -10.0 10.0" the cylinder lies
  along the x-axis from x = -10 to 10 and the circular cross-section 
  of the cylinder is the y-z plane with the center axis at y = 0.0, z = 2.0 -
  each atom will be given 0.0 velocity in x, and a y-z velocity that will
  rotate the atom around the cylinder axis at a rotational rate from 0.0 to
  0.1 revolutions/time which depends on where the atom's x-coord lies between
  -10.0 and 10.0
for the twist option, if vlo = vhi then all the selected atoms will be
  assigned the same rotational velocity, however clo and chi must still
  be specified
expand option means assign velocities to selected atoms in a radial direction
  away from (or towards) a center point so that the system expands
  (or contracts) at a uniform rate - useful for biaxial stress simulations
for the expand option, the 1st 3 parameters are flags on the x,y,z
  dimensions for whether to include them or not in radial direction
  computation - a value of 0 means do not include, a value of 1 means include
for the expand option, the radial distance r of each selected atom from the
  center point (cx,cy,cz) is computed using only included dimensions -
  the atom is given a velocity in the radial direction of magnitude
  alpha*r where alpha is computed from doubletime factor (see units below)
for the expand option the units of cx, cy, cz are cubic lattice units
  and the units of doubletime = time in tau (lj units) or picoseconds
  (real time) to double the linear dimension of the system - e.g. a
  value of doubletime = 1000.0 means each atom will be 2x farther from
  the center point after 1000 tau or picoseconds
for the expand option, a negative doubletime means compression instead
  of expansion, i.e. the time for the system to implode to a single point

----------------------------------------------------------------------------

# create fixes

assign a force fix to all atoms selected by the "select type" command
force fixes are applied each timestep after forces are computed and
  communicated, but before they are used to update velocities

examples:
	create fixes	none
	create fixes	xyz 0 1 -1
	create fixes	twist x y z c0 c1 1 1 1
	create fixes	external 0.1 0.0 0.0

none option means erase all previously specified force fixes
for all other options, a "select type" must be in effect to first select
  atoms of a particular type
each time the "create fixes" command is used, a new fix is added,
  so the only way to change a previously specified fix, is to use the
  "none" option to erase them all, then re-specify the desired fixes
xyz option means to not-change, zero-out, or average the force on
  each x, y, z component of force for the selected atoms, a flag
  is used to specify for each of the components whether it should be
  unchanged (-1) or zeroed (0) or averaged (1) - e.g. the command
  "create fixes xyz 0 -1 1" will zero the x component of force on each atom,
  not alter the y force component, and compute the total z force on all
  selected atoms, divide it by the number of selected atoms,
  and then set the z force component of each atom to the same average force
for the twist option, the 3 final flags refer to the radial,
  theta (azimuthal), and z-components of force for the specified cylinder
twist option means to add a centripetal force to each selected atom
  so as to keep it rotating at its current angular velocity in the
  specified cylinder, additionally a flag is used to specify for each of
  the force components in the cylinder frame-of-reference whether it
  should be unchanged (-1) or zeroed (0) or averaged (1)
for the twist option the x,y,z specification defines which box directions
  correspond to the x,y plane and z-axis of the cylinder
for the twist option, unchanged (-1) means do not alter the component
  unless it is the radial component which always has a centripetal term
  added, zero (0) means zero out the component unless it is the radial
  one in which case the centripetal term will remain, and average (1)
  can only be applied to the z-component of the cylinder and means to
  compute the total force on all selected atoms, divide it by the
  number of selected atoms, and then set the force component along the
  cylinder axis for each atom to the same average force
an example for the twist option is
  "create fixes twist y z x 0.0 2.0 0 0 1" which will treat the line in the
  the x-dimension at y = 0.0, z = 2.0 (in cubic lattice units) as the axis
  of a cylinder, the Cartesian x,y,z force on each selected atom will be
  recast in r,theta,z components depending on the atoms current position
  relative to the cylinder axis, the atom's theta velocity will be computed, 
  each of the 3 recast force components will be zeroed if the corresponding
  flag is set to 0 (in this case the radial and azimuthal forces will be
  zeroed, the z-component along the cylinder axis will be averaged),
  a centripetal v_theta**2/r term will be added to the radial force,
  and the forces are mapped back to the Cartesian x,y,z form
external option means simply add the given external forces (input in the x, y,
  and z directions) to the already-computed forces.  Note that this does not
  zero out the forces before adding the given force.  Units are eV/A.
IMPORTANT NOTE: the "temp control" command can also alter
  atom velocities, so may want to use "temp type" to exclude
  fixed atoms from the control

----------------------------------------------------------------------------

# temp type

compute temperature only using atoms with types <= specified type
can be used to exclude constrained atoms from temperature calculation
  and temperature control in "temp control" command
value of 0 means use all atoms to compute temperature
must be done after "create box" command
default = 0

----------------------------------------------------------------------------

# temp control

which style of temperature control to use

examples:
	temp control	none
	temp control	rescale 300.0 20 10.0
	temp control	hoover 300.0 10.0

none means constant NVE -> no temperature control
rescale means rescale the temperature to exactly the desired value
  every so many timesteps
hoover means do true NVT temperature control via Nose/Hoover thermostat
1st parameter for rescale is desired temperature in LJ or real units
2nd parameter for rescale is every how many timesteps to do rescaling
3rd parameter for rescale is temperature window, rescaling is only
  done if temperature is outside this +/- window
1st parameter for hoover is desired temperature in LJ or real units
2nd parameter for hoover is a frequency constant for the damping which
  is like an inverse "piston" mass, it determines how rapidly the
  temperature fluctuates in response to a restoring force,
  large frequency -> small mass -> rapid fluctations
for hoover, units of frequency/damping constant are inverse time,
  so a value of 0.1 means relax in a timespan on the
  order of 10 tau (lj units) or 10 picoseconds (real units)
all controls are only performed on atoms with types <= specified type
  in "temp type" command
must be done after "create box" command
default = none

----------------------------------------------------------------------------

# temp adjust

adjust the temperature calculation and control to compensate for
  non-thermal components of velocity

example:		
	temp adjust	none
	temp adjust	xyz 0 1 1
	temp adjust	ramp vy vlo vhi x clo chi
	temp adjust	twist vlo vhi x y z c0 c1 clo chi

before computing a temperature and before modifying an atom's velocity
  via the "temp control" command, its velocities are adjusted to compensate
  for non-thermal velocity component(s)
if the adjustment subtracts out a particular velocity component(s),
  then the subtracted component(s) are added back in after the 
  "temp control" is performed
none means do no adjustment
xyz option means only the specified components contribute to the velocity
  and are controlled, a 0 means do not include that component, a 1 means
  do include that component
ramp option means subtract a particular velocity component based on the
  atom's current coordinate between 2 bounds in a particular dimension,
  an atom whose coordinate falls outside the specified bounds will be
  adjusted by the min or max velocity
for the ramp option the parameters and their meaning and units are 
  exactly the same as they are for the "create vels ramp" command
twist option means subtract out angular velocity in the two components
  orthogonal to the cylinder axis, depending on where the atom's current
  coordinates lie along the cylinder axis, an atom whose coordinate falls
  beyond the end of the cylinder will be adjusted by the min or max rotation
for the twist option the parameters and their meaning and units are
  exactly the same as they are for the "create vels twist" command
all adjustments are only performed on atoms with types <= specified type
  in "temp type" command
must be done after "create box" command
default = none

----------------------------------------------------------------------------

# pres control

apply pressure control

example:
	pres control	none
	pres control	rescale 0.0 0.5

none means constant volume -> no pressure control
rescale means rescale the box volume to maintain pressure at the desired
   value.  The volume is an extra degree of freedom with a corresponding
   spring-mass-damper type equation.
1st parameter for rescale is desired pressure in bars.
2nd parameter for rescale is time constant in ps for the volume equation.

WARNING: currently pressure control cannot be used with restarts, since
	the box size changes when pressure control is turned on.  The box
	size in the restart file will not match that in the command input
	file.

----------------------------------------------------------------------------

# read restart

read atom coords, velocities, types from specified file
allows continuation of a previous run via "restart" command
file is binary to enable exact restarts, assuming simulation box is
  created in the same fashion
do not have to restart on same # of processors, but can only do exact
  restarts on same # of processors
must do a "create box" with all associated settings before reading a 
  restart file
after reading a restart file, do not use the "create atoms" and
  "create vels" commands
still do "create fixes" after reading a restart file since fixes are
  not stored in the file

----------------------------------------------------------------------------

# reset timestep

reset the global timestep # to the specified value
useful to do after equilibration run, before data-gathering run

----------------------------------------------------------------------------

# run

run or continue MD for specified # of timesteps
must have performed "create box" and "create atoms" commands first

----------------------------------------------------------------------------

# relax

minimize potential energy using a conjugate gradient solver; repeated for
a specified number of timesteps (between which atoms with fixed velocities
are updated, although solution is quasistatic)


----------------------------------------------------------------------------

# relaxp

relax with parameters

example:
  relaxp 1 1500 4 40 1e-8 1e-6 1e-10

1st parameter is number of steps (atoms with fixed velocities are updated)
2nd parameter = "imax" is max number of cg iterations
3rd parameter = "jmax" is number of secant method iterations
4th parameter = "kres" number of iterations to restart nonlinear cg
5th parameter = "eps" cg error tolerance (< 1)
6th parameter = "sigma" secant method step parameter
7th parameter = "res_limit" smallest residual value worthy to improve
                 introduced to ensure numerical stability of relaxation


----------------------------------------------------------------------------

# relaxf

relax with parameters from a specified file

example:
  relaxf 1 RELAX

1st parameter is number of steps (atoms with fixed velocities are updated)
other six parameters (2nd to 7-th parameter of relaxp) are read from a
specified file, in the same order as relaxp parameters

example RELAX file:

2000  ! imax
4     ! jmax
40    ! kres
1e-8  ! eps
1e-6  ! sigma
1e-9  ! res_limit

----------------------------------------------------------------------------
----------------------------------------------------------------------------
</pre>



[[Category: WARP]]
[[Category: Nanoscale]]
[[Category: Tutorial]]