extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LAMMPS.
</P>
<P>For extract_global() see the src/library.cpp file for the list of
valid names. New names could easily be added. A double or integer is
returned. You need to specify the appropriate data type via the type
argument.
</P>
<P>For extract_atom(), a pointer to internal LAMMPS atom-based data is
returned, which you can use via normal Python subscripting. See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added. A pointer to a vector of
doubles or integers, or a pointer to an array of doubles (double **)
or integers (int **) is returned. You need to specify the appropriate
data type via the type argument.
</P>
<P>For extract_compute() and extract_fix(), the global, per-atom, or
local data calulated by the compute or fix can be accessed. What is
returned depends on whether the compute or fix calculates a scalar or
vector or array. For a scalar, a single double value is returned. If
the compute or fix calculates a vector or array, a pointer to the
internal LAMMPS data is returned, which you can use via normal Python
subscripting. The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices. The I,J arguments can be left out if not needed.
See <A HREF = "Section_howto.html#howto_15">Section_howto 15</A> of the manual for a
discussion of global, per-atom, and local data, and of scalar, vector,
and array data types. See the doc pages for individual
<A HREF = "compute.html">computes</A> and <A HREF = "fix.html">fixes</A> for a description of what
they calculate and store.
</P>
<P>For extract_variable(), an <A HREF = "variable.html">equal-style or atom-style
variable</A> is evaluated and its result returned.
</P>
<P>For equal-style variables a single double value is returned and the
group argument is ignored. For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
</P>
<P>The get_natoms() method returns the total number of atoms in the
simulation, as an int.
</P>
<P>The gather_atoms() method returns a ctypes vector of ints or doubles
as specified by type, of length count*natoms, for the property of all
the atoms in the simulation specified by name, ordered by count and
then by atom ID. The vector can be used via normal Python
subscripting. If atom IDs are not consecutively ordered within
LAMMPS, a None is returned as indication of an error.
</P>
<P>Note that the data structure gather_atoms("x") returns is different
from the data structure returned by extract_atom("x") in four ways.
(1) Gather_atoms() returns a vector which you index as x[i];
extract_atom() returns an array which you index as x[i][j]. (2)
Gather_atoms() orders the atoms by atom ID while extract_atom() does
not. (3) Gathert_atoms() returns a list of all atoms in the
simulation; extract_atoms() returns just the atoms local to each
processor. (4) Finally, the gather_atoms() data structure is a copy
of the atom coords stored internally in LAMMPS, whereas extract_atom()
returns an array that effectively points directly to the internal
data. This means you can change values inside LAMMPS from Python by
assigning a new values to the extract_atom() array. To do this with
the gather_atoms() vector, you need to change values in the vector,
then invoke the scatter_atoms() method.
</P>
<P>The scatter_atoms() method takes a vector of ints or doubles as
specified by type, of length count*natoms, for the property of all the
atoms in the simulation specified by name, ordered by bount and then
by atom ID. It uses the vector of data to overwrite the corresponding
properties for each atom inside LAMMPS. This requires LAMMPS to have
its "map" option enabled; see the <A HREF = "atom_modify.html">atom_modify</A>
command for details. If it is not, or if atom IDs are not
consecutively ordered, no coordinates are reset.
</P>
<P>The array of coordinates passed to scatter_atoms() must be a ctypes
vector of ints or doubles, allocated and initialized something like
this:
</P>
<PRE>from ctypes import *
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
-x<B>0</B> = x coord of atom with ID 1
-x<B>1</B> = y coord of atom with ID 1
-x<B>2</B> = z coord of atom with ID 1
-x<B>3</B> = x coord of atom with ID 2
+x[0] = x coord of atom with ID 1
+x[1] = y coord of atom with ID 1
+x[2] = z coord of atom with ID 1
+x[3] = x coord of atom with ID 2
...
-x<B>n3-1</B> = z coord of atom with ID natoms
+x[n3-1] = z coord of atom with ID natoms
lmp.scatter_coords("x",1,3,x)
</PRE>
<P>Alternatively, you can just change values in the vector returned by
gather_atoms("x",1,3), since it is a ctypes vector of doubles.
</P>
<HR>
<P>As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in src/library.cpp and
library.h. This means you can extend the Python wrapper via the
following steps:
</P>
<UL><LI>Add a new interface function to src/library.cpp and
src/library.h.
<LI>Rebuild LAMMPS as a shared library.
<LI>Add a wrapper method to python/lammps.py for this interface
function.
<LI>You should now be able to invoke the new interface function from a
Python script. Isn't ctypes amazing?
</UL>
<HR>
<HR>
<A NAME = "py_6"></A><H4>11.6 Example Python scripts that use LAMMPS
</H4>
<P>These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of
things that are possible when Python wraps LAMMPS. If you create your
own scripts, send them to us and we can include them in the LAMMPS
distribution.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >trivial.py</TD><TD > read/run a LAMMPS input script thru Python</TD></TR>
<TR><TD >demo.py</TD><TD > invoke various LAMMPS library interface routines</TD></TR>
<TR><TD >simple.py</TD><TD > mimic operation of couple/simple/simple.cpp in Python</TD></TR>
<TR><TD >gui.py</TD><TD > GUI go/stop/temperature-slider to control LAMMPS</TD></TR>
<TR><TD >plot.py</TD><TD > real-time temeperature plot with GnuPlot via Pizza.py</TD></TR>
<TR><TD >viz_tool.py</TD><TD > real-time viz via some viz package</TD></TR>
<TR><TD >vizplotgui_tool.py</TD><TD > combination of viz_tool.py and plot.py and gui.py
</TD></TR></TABLE></DIV>
<HR>
<P>For the viz_tool.py and vizplotgui_tool.py commands, replace "tool"
with "gl" or "atomeye" or "pymol" or "vmd", depending on what
visualization package you have installed.
</P>
<P>Note that for GL, you need to be able to run the Pizza.py GL tool,
which is included in the pizza sub-directory. See the <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py doc
pages</A> for more info:
</P>
<P>Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye WWW pages <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">here</A> or <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html">here</A> for more details:
<LI>group-ID = ID of the group of atoms to be dumped
-<LI>style = <I>atom</I> or <I>atom/mpiio</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>xyz/mpiio</I> or <I>image</I> or <I>molfile</I> or <I>local</I> or <I>custom</I> or <I>custom/mpiio</I>
+<LI>style = <I>atom</I> or <I>atom/mpiio</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>xyz/mpiio</I> or <I>image</I> or <I>movie</I> or <I>molfile</I> or <I>local</I> or <I>custom</I> or <I>custom/mpiio</I>
<LI>N = dump every this many timesteps
<LI>file = name of file to write dump info to
<LI>args = list of arguments for a particular style
<PRE> <I>atom</I> args = none
<I>atom/mpiio</I> args = none
<I>cfg</I> args = same as <I>custom</I> args, see below
<LI>one or more keyword/value pairs may be appended
<LI>these keywords apply to various dump styles
<LI>keyword = <I>append</I> or <I>buffer</I> or <I>element</I> or <I>every</I> or <I>fileper</I> or <I>first</I> or <I>flush</I> or <I>format</I> or <I>image</I> or <I>label</I> or <I>nfile</I> or <I>pad</I> or <I>precision</I> or <I>region</I> or <I>scale</I> or <I>sort</I> or <I>thresh</I> or <I>unwrap</I>
<PRE> <I>append</I> arg = <I>yes</I> or <I>no</I>
<I>buffer</I> arg = <I>yes</I> or <I>no</I>
<I>element</I> args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
<I>every</I> arg = N
N = dump every this many timesteps
N can be a variable (see below)
<I>fileper</I> arg = Np
Np = write one file for every this many processors
<I>first</I> arg = <I>yes</I> or <I>no</I>
<I>format</I> arg = C-style format string for one line of output
<I>flush</I> arg = <I>yes</I> or <I>no</I>
<I>image</I> arg = <I>yes</I> or <I>no</I>
<I>label</I> arg = string
string = character string (e.g. BONDS) to use in header of dump local file
<I>nfile</I> arg = Nf
Nf = write this many files, one from each of Nf processors
<I>pad</I> arg = Nchar = # of characters to convert timestep to
<I>precision</I> arg = power-of-10 value from 10 to 1000000
<I>region</I> arg = region-ID or "none"
<I>scale</I> arg = <I>yes</I> or <I>no</I>
<I>sort</I> arg = <I>off</I> or <I>id</I> or N or -N
off = no sorting of per-atom lines within a snapshot
id = sort per-atom lines by atom ID
N = sort per-atom lines in ascending order by the Nth column
-N = sort per-atom lines in descending order by the Nth column
<I>thresh</I> args = attribute operation value
attribute = same attributes (x,fy,etotal,sxx,etc) used by dump custom style
operation = "<" or "<=" or ">" or ">=" or "==" or "!="
value = numeric value to compare to
these 3 args can be replaced by the word "none" to turn off thresholding
<I>unwrap</I> arg = <I>yes</I> or <I>no</I>
</PRE>
<LI>these keywords apply only to the <I>image</I> and <I>movie</I> <A HREF = "dump_image.html">styles</A>
<LI>keyword = <I>acolor</I> or <I>adiam</I> or <I>amap</I> or <I>bcolor</I> or <I>bdiam</I> or <I>backcolor</I> or <I>boxcolor</I> or <I>color</I> or <I>bitrate</I> or <I>framerate</I>
<PRE> <I>acolor</I> args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
<I>adiam</I> args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
<I>amap</I> args = lo hi style delta N entry1 entry2 ... entryN
lo = number or <I>min</I> = lower bound of range of color map
hi = number or <I>max</I> = upper bound of range of color map
style = 2 letters = "c" or "d" or "s" plus "a" or "f"
"c" for continuous
"d" for discrete
"s" for sequential
"a" for absolute
"f" for fractional
delta = binsize (only used for style "s", otherwise ignored)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or <I>min</I> or <I>max</I> = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or <I>min</I> or <I>max</I> = lower/upper bound of subset of range
color = name of color used for that subset of values
entry = color (for sequential style)
color = name of color used for a bin of values
<I>backcolor</I> arg = color
color = name of color for background
<I>bcolor</I> args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
<I>bdiam</I> args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
<I>bitrate</I> arg = rate
rate = target bitrate for movie in kbps
<I>boxcolor</I> arg = color
color = name of color for box lines
<I>color</I> args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
<I>framerate</I> arg = fps
fps = frames per second for movie
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>dump_modify 1 format "%d %d %20.15g %g %g" scale yes
dump_modify myDump image yes scale no flush yes
dump_modify 1 region mySphere thresh x < 0.0 thresh epair >= 3.2
dump_modify xtcdump precision 10000
dump_modify 1 every 1000 nfile 20
dump_modify 1 every v_myVar
dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
</PRE>
<P><B>Description:</B>
</P>
<P>Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
</P>
<P>As explained on the <A HREF = "dump.html">dump</A> doc page, the <I>atom/mpiio</I>,
<I>custom/mpiio</I>, and <I>xyz/mpiio</I> dump styles are identical in command
syntax and in the format of the dump files they create, to the
corresponding styles without "mpiio", except the single dump file they
produce is written in parallel via the MPI-IO library. Thus if a
dump_modify option below is valid for the <I>atom</I> style, it is also
valid for the <I>atom/mpiio</I> style, and similarly for the other styles
which allow for use of MPI-IO.
</P>
<HR>
<HR>
<P>These keywords apply to various dump styles, including the <A HREF = "dump_image.html">dump
image</A> and <A HREF = "dump_image.html">dump movie</A> styles. The
description gives details.
</P>
<HR>
<P>The <I>append</I> keyword applies to all dump styles except <I>cfg</I> and <I>xtc</I>
and <I>dcd</I>. It also applies only to text output files, not to binary
or gzipped or image/movie files. If specified as <I>yes</I>, then dump
snapshots are appended to the end of an existing dump file. If
specified as <I>no</I>, then a new dump file will be created which will
overwrite an existing file with the same name. This keyword can only
take effect if the dump_modify command is used after the
<A HREF = "dump.html">dump</A> command, but before the first command that causes
dump snapshots to be output, e.g. a <A HREF = "run.html">run</A> or
<A HREF = "minimize.html">minimize</A> command. Once the dump file has been opened,
this keyword has no further effect.
</P>
<HR>
<P>The <I>buffer</I> keyword applies only to dump styles <I>atom</I>, <I>cfg</I>,
<I>custom</I>, <I>local</I>, and <I>xyz</I>. It also applies only to text output
files, not to binary or gzipped files. If specified as <I>yes</I>, which
is the default, then each processor writes its output into an internal
text buffer, which is then sent to the processor(s) which perform file
writes, and written by those processors(s) as one large chunk of text.
If specified as <I>no</I>, each processor sends its per-atom data in binary
format to the processor(s) which perform file wirtes, and those
processor(s) format and write it line by line into the output file.
</P>
<P>The buffering mode is typically faster since each processor does the
relatively expensive task of formatting the output for its own atoms.
However it requires about twice the memory (per processor) for the
extra buffering.
</P>
<HR>
<P>The <I>element</I> keyword applies only to the the dump <I>cfg</I>, <I>xyz</I>, and
<I>image</I> styles. It associates element names (e.g. H, C, Fe) with
LAMMPS atom types. See the list of element names at the bottom of
this page.
</P>
<P>In the case of dump <I>cfg</I>, this allows the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A>
visualization package to read the dump file and render atoms with the
appropriate size and color.
</P>
<P>In the case of dump <I>image</I>, the output images will follow the same
<A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> convention. An element name is specified for each
atom type (1 to Ntype) in the simulation. The same element name can
be given to multiple atom types.
</P>
<P>In the case of <I>xyz</I> format dumps, there are no restrictions to what
label can be used as an element name. Any whitespace separated text
will be accepted.
</P>
<HR>
<P>The <I>every</I> keyword changes the dump frequency originally specified by
the <A HREF = "dump.html">dump</A> command to a new value. The every keyword can be
specified in one of two ways. It can be a numeric value in which case
it must be > 0. Or it can be an <A HREF = "variable.html">equal-style variable</A>,
which should be specified as v_name, where name is the variable name.
</P>
<P>In this case, the variable is evaluated at the beginning of a run to
determine the next timestep at which a dump snapshot will be written
out. On that timestep the variable will be evaluated again to
determine the next timestep, etc. Thus the variable should return
timestep values. See the stagger() and logfreq() and stride() math
functions for <A HREF = "variable.html">equal-style variables</A>, as examples of
useful functions to use in this context. Other similar math functions
could easily be added as options for <A HREF = "variable.html">equal-style
variables</A>. Also see the next() function, which allows
use of a file-style variable which reads successive values from a
file, each time the variable is evaluated. Used with the <I>every</I>
keyword, if the file contains a list of ascending timesteps, you can
output snapshots whenever you wish.
</P>
<P>Note that when using the variable option with the <I>every</I> keyword, you
need to use the <I>first</I> option if you want an initial snapshot written
to the dump file. The <I>every</I> keyword cannot be used with the dump
<I>dcd</I> style.
</P>
<P>For example, the following commands will
write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
</P>
<PRE>variable s equal logfreq(10,3,10)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes
</PRE>
<P>The following commands would write snapshots at the timesteps listed
in file tmp.times:
</P>
<PRE>variable f file tmp.times
variable s equal next(f)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s
</PRE>
<P>IMPORTANT NOTE: When using a file-style variable with the <I>every</I>
keyword, the file of timesteps must list a first timestep that is
beyond the current timestep (e.g. it cannot be 0). And it must list
one or more timesteps beyond the length of the run you perform. This
is because the dump command will generate an error if the next
timestep it reads from the file is not a value greater than the
current timestep. Thus if you wanted output on steps 0,15,100 of a
100-timestep run, the file should contain the values 15,100,101 and
you should also use the dump_modify first command. Any final value >
100 could be used in place of 101.
</P>
<HR>
<P>The <I>first</I> keyword determines whether a dump snapshot is written on
the very first timestep after the dump command is invoked. This will
always occur if the current timestep is a multiple of N, the frequency
specified in the <A HREF = "dump.html">dump</A> command, including timestep 0. But
if this is not the case, a dump snapshot will only be written if the
setting of this keyword is <I>yes</I>. If it is <I>no</I>, which is the
default, then it will not be written.
</P>
<HR>
<P>The <I>flush</I> keyword determines whether a flush operation is invoked
after a dump snapshot is written to the dump file. A flush insures
the output in that file is current (no buffering by the OS), even if
LAMMPS halts before the simulation completes. Flushes cannot be
performed with dump style <I>xtc</I>.
</P>
<HR>
<P>The text-based dump styles have a default C-style format string which
simply specifies %d for integers and %g for floating-point values.
The <I>format</I> keyword can be used to override the default with a new
C-style format string. Do not include a trailing "\n" newline
character in the format string. This option has no effect on the
<I>dcd</I> and <I>xtc</I> dump styles since they write binary files. Note that
for the <I>cfg</I> style, the first two fields (atom id and type) are not
actually written into the CFG file, though you must include formats
for them in the format string.
</P>
<P>IMPORTANT NOTE: Any value written to a text-based dump file that is a
per-atom quantity calculated by a <A HREF = "compute.html">compute</A> or
<A HREF = "fix.html">fix</A> is stored internally as a floating-point value. If the
value is actually an integer and you wish it to appear in the text
dump file as a (large) integer, then you need to use an appropriate
format. For example, these commands:
</P>
<PRE>compute 1 all property/local batom1 batom2
-dump 1 all local 100 tmp.bonds index c_1<B>1</B> c_1<B>2</B>
+dump 1 all local 100 tmp.bonds index c_1[1] c_1[2]
dump_modify 1 format "%d %0.0f %0.0f"
</PRE>
<P>will output the two atom IDs for atoms in each bond as integers. If
the dump_modify command were omitted, they would appear as
floating-point values, assuming they were large integers (more than 6
digits). The "index" keyword should use the "%d" format since it is
not generated by a compute or fix, and is stored internally as an
integer.
</P>
<HR>
<P>The <I>fileper</I> keyword is documented below with the <I>nfile</I> keyword.
</P>
<HR>
<P>The <I>image</I> keyword applies only to the dump <I>atom</I> style. If the
image value is <I>yes</I>, 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
example, an x image flag of -2 with a normalized coord of 0.5 means
the atom is in the center of the box, but has passed thru the box
boundary 2 times and is really 2 box lengths to the left of its
current coordinate. Note that for dump style <I>custom</I> these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
</P>
<HR>
<P>The <I>label</I> keyword applies only to the dump <I>local</I> style. When
it writes local information, such as bond or angle topology
to a dump file, it will use the specified <I>label</I> to format
the header. By default this includes 2 lines:
</P>
<PRE>ITEM: NUMBER OF ENTRIES
ITEM: ENTRIES ...
</PRE>
<P>The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
</P>
<HR>
<P>The <I>nfile</I> or <I>fileper</I> keywords can be used in conjunction with the
"%" wildcard character in the specified dump file name, for all dump
styles except the <I>dcd</I>, <I>image</I>, <I>movie</I>, <I>xtc</I>, and <I>xyz</I> styles
(for which "%" is not allowed). As explained on the <A HREF = "dump.html">dump</A>
command doc page, the "%" character causes the dump file to be written
in pieces, one piece for each of P processors. By default P = the
number of processors the simulation is running on. The <I>nfile</I> or
<I>fileper</I> keyword can be used to set P to a smaller value, which can
be more efficient when running on a large number of processors.
</P>
<P>The <I>nfile</I> keyword sets P to the specified Nf value. For example, if
Nf = 4, and the simulation is running on 100 processors, 4 files will
be written, by processors 0,25,50,75. Each will collect information
from itself and the next 24 processors and write it to a dump file.
</P>
<P>For the <I>fileper</I> keyword, the specified value of Np means write one
file for every Np processors. For example, if Np = 4, every 4th
processor (0,4,8,12,etc) will collect information from itself and the
next 3 processors and write it to a dump file.
</P>
<HR>
<P>The <I>pad</I> keyword only applies when the dump filename is specified
with a wildcard "*" character which becomes the timestep. If <I>pad</I> is
0, which is the default, the timestep is converted into a string of
unpadded length, e.g. 100 or 12000 or 2000000. When <I>pad</I> is
specified with <I>Nchar</I> > 0, the string is padded with leading zeroes
so they are all the same length = <I>Nchar</I>. For example, pad 7 would
yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending
timestep order.
</P>
<HR>
<P>The <I>precision</I> keyword only applies to the dump <I>xtc</I> style. A
specified value of N means that coordinates are stored to 1/N
nanometer accuracy, e.g. for N = 1000, the coordinates are written to
1/1000 nanometer accuracy.
</P>
<HR>
<P>The <I>region</I> keyword only applies to the dump <I>custom</I>, <I>cfg</I>,
<I>image</I>, and <I>movie</I> styles. If specified, only atoms in the region
will be written to the dump file or included in the image/movie. Only
one region can be applied as a filter (the last one specified). See
the <A HREF = "region.html">region</A> command for more details. Note that a region
can be defined as the "inside" or "outside" of a geometric shape, and
it can be the "union" or "intersection" of a series of simpler
regions.
</P>
<HR>
<P>The <I>scale</I> keyword applies only to the dump <I>atom</I> style. A scale
value of <I>yes</I> means atom coords are written in normalized units from
0.0 to 1.0 in each box dimension. If the simluation box is triclinic
(tilted), then all atom coords will still be between 0.0 and 1.0. A
value of <I>no</I> means they are written in absolute distance units
(e.g. Angstroms or sigma).
</P>
<HR>
<P>The <I>sort</I> keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of <I>off</I> means they will
typically be written in indeterminate order, either in serial or
parallel. This is the case even in serial if the <A HREF = "atom_modify.html">atom_modify
sort</A> option is turned on, which it is by default, to
improve performance. A sort value of <I>id</I> means sort the output by
atom ID. A sort value of N or -N means sort the output by the value
in the Nth column of per-atom info in either ascending or descending
order.
</P>
<P>The dump <I>local</I> style cannot be sorted by atom ID, since there are
typically multiple lines of output per atom. Some dump styles, such
as <I>dcd</I> and <I>xtc</I>, require sorting by atom ID to format the output
file correctly. If multiple processors are writing the dump file, via
the "%" wildcard in the dump filename, then sorting cannot be
performed.
</P>
<P>IMPORTANT NOTE: Unless it is required by the dump style, sorting dump
file output requires extra overhead in terms of CPU and communication
cost, as well as memory, versus unsorted output.
</P>
<HR>
<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I>, <I>cfg</I>,
<I>image</I>, and <I>movie</I> styles. Multiple thresholds can be specified.
Specifying "none" turns off all threshold criteria. If thresholds are
specified, only atoms whose attributes meet all the threshold criteria
are written to the dump file or included in the image. The possible
attributes that can be tested for are the same as those that can be
specified in the <A HREF = "dump.html">dump custom</A> command, with the exception
of the <I>element</I> attribute, since it is not a numeric value. Note
that different attributes can be output by the dump custom command
than are used as threshold criteria by the dump_modify command.
E.g. you can output the coordinates and stress of atoms whose energy
is above some threshold.
</P>
<HR>
<P>The <I>unwrap</I> keyword only applies to the dump <I>dcd</I> and <I>xtc</I> styles.
If set to <I>yes</I>, coordinates will be written "unwrapped" by the image
flags for each atom. Unwrapped means that if the atom has passed thru
a periodic boundary one or more times, the value is printed for what
the coordinate would be if it had not been wrapped back into the
periodic box. Note that these coordinates may thus be far outside the
box size stored with the snapshot.
</P>
<HR>
<HR>
<P>These keywords apply only to the <A HREF = "dump_image.html">dump image</A> and
<A HREF = "dump_image.html">dump movie</A> styles. Any keyword that affects an
image, also affects a movie, since the movie is simply a collection of
images. Some of the keywords only affect the <A HREF = "dump_image.html">dump
movie</A> style. The description gives details.
</P>
<HR>
<P>The <I>acolor</I> keyword can be used with the <A HREF = "dump_image.html">dump image</A>
command, when its atom color setting is <I>type</I>, to set the color that
atoms of each type will be drawn in the image.
</P>
<P>The specified <I>type</I> should be an integer from 1 to Ntypes = the
number of atom types. A wildcard asterisk can be used in place of or
in conjunction with the <I>type</I> argument to specify a range of atom
types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
number of atom types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
</P>
<P>The specified <I>color</I> can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option. Or it can be two or more colors separated
by a "/" character, e.g. red/green/blue. In the former case, that
color is assigned to all the specified atom types. In the latter
case, the list of colors are assigned in a round-robin fashion to each
of the specified atom types.
</P>
<HR>
<P>The <I>adiam</I> keyword can be used with the <A HREF = "dump_image.html">dump image</A>
command, when its atom diameter setting is <I>type</I>, to set the size
that atoms of each type will be drawn in the image. The specified
<I>type</I> should be an integer from 1 to Ntypes. As with the <I>acolor</I>
keyword, a wildcard asterisk can be used as part of the <I>type</I>
argument to specify a range of atomt types. The specified <I>diam</I> is
the size in whatever distance <A HREF = "units.html">units</A> the input script is
using, e.g. Angstroms.
</P>
<HR>
<P>The <I>amap</I> keyword can be used with the <A HREF = "dump_image.html">dump image</A>
command, with its <I>atom</I> keyword, when its atom setting is an
atom-attribute, to setup a color map. The color map is used to assign
a specific RGB (red/green/blue) color value to an individual atom when
it is drawn, based on the atom's attribute, which is a numeric value,
e.g. its x-component of velocity if the atom-attribute "vx" was
specified.
</P>
<P>The basic idea of a color map is that the atom-attribute will be
within a range of values, and that range is associated with a a series
of colors (e.g. red, blue, green). An atom's specific value (vx =
-3.2) can then mapped to the series of colors (e.g. halfway between
red and blue), and a specific color is determined via an interpolation
procedure.
</P>
<P>There are many possible options for the color map, enabled by the
<I>amap</I> keyword. Here are the details.
</P>
<P>The <I>lo</I> and <I>hi</I> settings determine the range of values allowed for
the atom attribute. If numeric values are used for <I>lo</I> and/or <I>hi</I>,
then values that are lower/higher than that value are set to the
value. I.e. the range is static. If <I>lo</I> is specified as <I>min</I> or
<I>hi</I> as <I>max</I> then the range is dynamic, and the lower and/or
upper bound will be calculated each time an image is drawn, based
on the set of atoms being visualized.
</P>
<P>The <I>style</I> setting is two letters, such as "ca". The first letter is
either "c" for continuous, "d" for discrete, or "s" for sequential.
The second letter is either "a" for absolute, or "f" for fractional.
</P>
<P>A continuous color map is one in which the color changes continuously
from value to value within the range. A discrete color map is one in
which discrete colors are assigned to sub-ranges of values within the
range. A sequential color map is one in which discrete colors are
assigned to a sequence of sub-ranges of values covering the entire
range.
</P>
<P>An absolute color map is one in which the values to which colors are
assigned are specified explicitly as values within the range. A
fractional color map is one in which the values to which colors are
assigned are specified as a fractional portion of the range. For
example if the range is from -10.0 to 10.0, and the color red is to be
assigned to atoms with a value of 5.0, then for an absolute color map
the number 5.0 would be used. But for a fractional map, the number
0.75 would be used since 5.0 is 3/4 of the way from -10.0 to 10.0.
</P>
<P>The <I>delta</I> setting must be specified for all styles, but is only used
for the sequential style; otherwise the value is ignored. It
specifies the bin size to use within the range for assigning
consecutive colors to. For example, if the range is from -10.0 to
10.0 and a <I>delta</I> of 1.0 is used, then 20 colors will be assigned to
the range. The first will be from -10.0 <= color1 < -9.0, then 2nd
from -9.0 <= color2 < -8.0, etc.
</P>
<P>The <I>N</I> setting is how many entries follow. The format of the entries
depends on whether the color map style is continuous, discrete or
sequential. In all cases the <I>color</I> setting can be any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option.
</P>
<P>For continuous color maps, each entry has a <I>value</I> and a <I>color</I>.
The <I>value</I> is either a number within the range of values or <I>min</I> or
<I>max</I>. The <I>value</I> of the first entry must be <I>min</I> and the <I>value</I>
of the last entry must be <I>max</I>. Any entries in between must have
increasing values. Note that numeric values can be specified either
as absolute numbers or as fractions (0.0 to 1.0) of the range,
depending on the "a" or "f" in the style setting for the color map.
</P>
<P>Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. X will fall
between 2 of the entry values. The color of the atom is linearly
interpolated (in each of the RGB values) between the 2 colors
associated with those entries. For example, if X = -5.0 and the 2
surrounding entries are "red" at -10.0 and "blue" at 0.0, then the
atom's color will be halfway between "red" and "blue", which happens
to be "purple".
</P>
<P>For discrete color maps, each entry has a <I>lo</I> and <I>hi</I> value and a
<I>color</I>. The <I>lo</I> and <I>hi</I> settings are either numbers within the
range of values or <I>lo</I> can be <I>min</I> or <I>hi</I> can be <I>max</I>. The <I>lo</I>
and <I>hi</I> settings of the last entry must be <I>min</I> and <I>max</I>. Other
entries can have any <I>lo</I> and <I>hi</I> values and the sub-ranges of
different values can overlap. Note that numeric <I>lo</I> and <I>hi</I> values
can be specified either as absolute numbers or as fractions (0.0 to
1.0) of the range, depending on the "a" or "f" in the style setting
for the color map.
</P>
<P>Here is how the entries are used to determine the color of an
individual atom, given the value X of its atom attribute. The entries
are scanned from first to last. The first time that <I>lo</I> <= X <=
<I>hi</I>, X is assigned the color associated with that entry. You can
think of the last entry as assigning a default color (since it will
always be matched by X), and the earlier entries as colors that
override the default. Also note that no interpolation of a color RGB
is done. All atoms will be drawn with one of the colors in the list
of entries.
</P>
<P>For sequential color maps, each entry has only a <I>color</I>. Here is how
the entries are used to determine the color of an individual atom,
given the value X of its atom attribute. The range is partitioned
into N bins of width <I>binsize</I>. Thus X will fall in a specific bin
from 1 to N, say the Mth bin. If it falls on a boundary between 2
bins, it is considered to be in the higher of the 2 bins. Each bin is
assigned a color from the E entries. If E < N, then the colors are
repeated. For example if 2 entries with colors red and green are
specified, then the odd numbered bins will be red and the even bins
green. The color of the atom is the color of its bin. Note that the
sequential color map is really a shorthand way of defining a discrete
color map without having to specify where all the bin boundaries are.
</P>
<P>Here is an example of using a sequential color map to color all the
atoms in individual molecules with a different color. See the
examples/pour/in.pour.2d.molecule input script for an example of how
this is used.
</P>
<PRE>variable colors string &
"red green blue yellow white &
purple pink orange lime gray"
variable mol atom mol%10
dump 1 all image 250 image.*.jpg v_mol type &
zoom 1.6 adiam 1.5
dump_modify 1 pad 5 amap 0 10 sa 1 10 ${colors}
</PRE>
<P>In this case, 10 colors are defined, and molecule IDs are
mapped to one of the colors, even if there are 1000s of molecules.
</P>
<HR>
<P>The <I>backcolor</I> sets the background color of the images. The color
name can be any of the 140 pre-defined colors (see below) or a color
name defined by the dump_modify color option.
</P>
<HR>
<P>The <I>bcolor</I> keyword can be used with the <A HREF = "dump_image.html">dump image</A>
command, with its <I>bond</I> keyword, when its color setting is <I>type</I>, to
set the color that bonds of each type will be drawn in the image.
</P>
<P>The specified <I>type</I> should be an integer from 1 to Nbondtypes = the
number of bond types. A wildcard asterisk can be used in place of or
in conjunction with the <I>type</I> argument to specify a range of bond
types. This takes the form "*" or "*n" or "n*" or "m*n". If N = the
number of bond types, then an asterisk with no numeric values means
all types from 1 to N. A leading asterisk means all types from 1 to n
(inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
</P>
<P>The specified <I>color</I> can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
dump_modify color option. Or it can be two or more colors separated
by a "/" character, e.g. red/green/blue. In the former case, that
color is assigned to all the specified bond types. In the latter
case, the list of colors are assigned in a round-robin fashion to each
of the specified bond types.
</P>
<HR>
<P>The <I>bdiam</I> keyword can be used with the <A HREF = "dump_image.html">dump image</A>
command, with its <I>bond</I> keyword, when its diam setting is <I>type</I>, to
set the diameter that bonds of each type will be drawn in the image.
The specified <I>type</I> should be an integer from 1 to Nbondtypes. As
with the <I>bcolor</I> keyword, a wildcard asterisk can be used as part of
the <I>type</I> argument to specify a range of bond types. The specified
<I>diam</I> is the size in whatever distance <A HREF = "units.html">units</A> you are
using, e.g. Angstroms.
</P>
<HR>
<P>The <I>bitrate</I> keyword can be used with the <A HREF = "dump_movie.html">dump
movie</A> command to define the size of the resulting
movie file and its quality via setting how many kbits per second are
to be used for the movie file. Higher bitrates require less
compression and will result in higher quality movies. The quality is
also determined by the compression format and encoder. The default
setting is 2000 kbit/s, which will result in average quality with
older compression formats.
</P>
<P>IMPORTANT NOTE: Not all movie file formats supported by dump movie
allow the bitrate to be set. If not, the setting is silently ignored.
</P>
<HR>
<P>The <I>boxcolor</I> keyword sets the color of the simulation box drawn
around the atoms in each image. See the "dump image box" command for
how to specify that a box be drawn. The color name can be any of the
140 pre-defined colors (see below) or a color name defined by the
dump_modify color option.
</P>
<HR>
<P>The <I>color</I> keyword allows definition of a new color name, in addition
to the 140-predefined colors (see below), and associates 3
red/green/blue RGB values with that color name. The color name can
then be used with any other dump_modify keyword that takes a color
name as a value. The RGB values should each be floating point values
between 0.0 and 1.0 inclusive.
</P>
<P>When a color name is converted to RGB values, the user-defined color
names are searched first, then the 140 pre-defined color names. This
means you can also use the <I>color</I> keyword to overwrite one of the
pre-defined color names with new RBG values.
</P>
<HR>
<P>The <I>framerate</I> keyword can be used with the <A HREF = "dump_movie.html">dump
movie</A> command to define the duration of the resulting
movie file. Movie files written by the dump <I>movie</I> command have a
default frame rate of 24 frames per second and the images generated
will be converted at that rate. Thus a sequence of 1000 dump images
will result in a movie of about 42 seconds. To make a movie run
longer you can either generate images more frequently or lower the
frame rate. To speed a movie up, you can do the inverse. Using a
frame rate higher than 24 is not recommended, as it will result in
simply dropping the rendered images. It is more efficient to dump
<PRE>fix ID group-ID deposit N type M seed keyword values ...
</PRE>
<UL><LI>ID, group-ID are documented in <A HREF = "fix.html">fix</A> command
<LI>deposit = style name of this fix command
<LI>N = # of atoms or molecules to insert
<LI>type = atom type to assign to inserted atoms (offset for moleclue insertion)
<LI>M = insert a single atom or molecule every M steps
<LI>seed = random # seed (positive integer)
<LI>one or more keyword/value pairs may be appended to args
<LI>keyword = <I>region</I> or <I>id</I> or <I>global</I> or <I>local</I> or <I>near</I> or <I>attempt</I> or <I>rate</I> or <I>vx</I> or <I>vy</I> or <I>vz</I> or <I>mol</I> or <I>rigid</I> or <I>shake</I> or <I>units</I>
<PRE> <I>region</I> value = region-ID
region-ID = ID of region to use as insertion volume
<I>id</I> value = <I>max</I> or <I>next</I>
max = atom ID for new atom(s) is max ID of all current atoms plus one
next = atom ID for new atom(s) increments by one for every deposition
<I>global</I> values = lo hi
lo,hi = put new atom/molecule a distance lo-hi above all other atoms (distance units)
<I>local</I> values = lo hi delta
lo,hi = put new atom/molecule a distance lo-hi above any nearby atom beneath it (distance units)
delta = lateral distance within which a neighbor is considered "nearby" (distance units)
<I>near</I> value = R
R = only insert atom/molecule if further than R from existing particles (distance units)
<I>attempt</I> value = Q
Q = attempt a single insertion up to Q times
<I>rate</I> value = V
V = z velocity (y in 2d) at which insertion volume moves (velocity units)
<I>vx</I> values = vxlo vxhi
vxlo,vxhi = range of x velocities for inserted atom/molecule (velocity units)
<I>vy</I> values = vylo vyhi
vylo,vyhi = range of y velocities for inserted atom/molecule (velocity units)
<I>vz</I> values = vzlo vzhi
vzlo,vzhi = range of z velocities for inserted atom/molecule (velocity units)
<I>target</I> values = tx ty tz
tx,ty,tz = location of target point (distance units)
<I>mol</I> value = template-ID
template-ID = ID of molecule template specified in a separate <A HREF = "molecule.html">molecule</A> command
<I>rigid</I> value = fix-ID
fix-ID = ID of <A HREF = "fix_rigid.html">fix rigid/small</A> command
<I>shake</I> value = fix-ID
fix-ID = ID of <A HREF = "fix_shake.html">fix shake</A> command
<I>units</I> value = <I>lattice</I> or <I>box</I>
lattice = the geometry is defined in lattice units
box = the geometry is defined in simulation box units
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>fix 3 all deposit 1000 2 100 29494 region myblock local 1.0 1.0 1.0 units box
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0 units lattice
</PRE>
<P><B>Description:</B>
</P>
<P>Insert a single atom or molecule into the simulation domain every M
timesteps until N atoms or molecules have been inserted. This is
useful for simulating deposition onto a surface. For the remainder of
this doc page, a single inserted atom or molecule is referred to as a
"particle".
</P>
<P>If inserted particles are individual atoms, they are assigned the
specified atom type. If they are molecules, the type of each atom in
the inserted molecule is specified in the file read by the
<A HREF = "molecule.html">molecule</A> command, and those values are added to the
specified atom type. E.g. if the file specifies atom types 1,2,3, and
those are the atom types you want for inserted molecules, then specify
<I>type</I> = 0. If you specify <I>type</I> = 2, the in the inserted molecule
will have atom types 3,4,5.
</P>
<P>All atoms in the inserted particle are assigned to two groups: the
default group "all" and the group specified in the fix deposit command
(which can also be "all").
</P>
<P>If you are computing temperature values which include inserted
particles, you will want to use the
<A HREF = "compute_modify.html">compute_modify</A> dynamic option, which insures the
current number of atoms is used as a normalizing factor each time the
temperature is computed.
</P>
<P>Care must be taken that inserted particles are not too near existing
atoms, using the options described below. When inserting particles
above a surface in a non-periodic box (see the
<A HREF = "boundary.html">boundary</A> command), the possibility of a particle
escaping the surface and flying upward should be considered, since the
particle may be lost or the box size may grow infinitely large. A
<A HREF = "fix_wall_reflect.html">fix wall/reflect</A> command can be used to
prevent this behavior. Note that if a shrink-wrap boundary is used,
it is OK to insert the new particle outside the box, however the box
will immediately be expanded to include the new particle. When
simulating a sputtering experiment it is probably more realistic to
ignore those atoms using the <A HREF = "thermo_modify.html">thermo_modify</A>
command with the <I>lost ignore</I> option and a fixed
<A HREF = "boundary.html">boundary</A>.
</P>
<P>The fix deposit command must use the <I>region</I> keyword to define an
insertion volume. The specified region must have been previously
defined with a <A HREF = "region.html">region</A> command. It must be defined with
side = <I>in</I>.
</P>
<P>Individual atoms are inserted, unless the <I>mol</I> keyword is used. It
specifies a <I>template-ID</I> previously defined using the
<A HREF = "molecule.html">molecule</A> 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 <A HREF = "molecule.html">molecule</A>
command for details. The only settings required to be in this file
are the coordinates and types of atoms in the molecule.
</P>
<P>If you wish to insert molecules via the <I>mol</I> keyword, that will be
treated as rigid bodies, use the <I>rigid</I> keyword, specifying as its
value the ID of a separate <A HREF = "fix_rigid_small.html">fix rigid/small</A>
command which also appears in your input script.
</P>
<P>If you wish to insert molecules via the <I>mol</I> keyword, that will have
their bonds or angles constrained via SHAKE, use the <I>shake</I> keyword,
specifying as its value the ID of a separate <A HREF = "fix_shake.html">fix
shake</A> command which also appears in your input script.
</P>
<P>Each timestep a particle is inserted, the coordinates for its atoms
are chosen as follows. For insertion of individual atoms, the
"position" referred to in the following description is the coordinate
of the atom. For insertion of molecule, the "position<A HREF = "molecule.html"> is the
geometric center of the molecule; see the (molecule</A> doc
page for details. A random rotation of the molecule around its center
point is performed, which determines the coordinates all the
individual atoms.
</P>
<P>A random position within the region insertion volume is generated. If
neither the <I>global</I> or <I>local</I> keyword is used, the random position
is the trial position. If the <I>global</I> keyword is used, the random
x,y values are used, but the z position of the new particle is set
above the highest current atom in the simulation by a distance
randomly chosen between lo/hi. (For a 2d simulation, this is done for
the y position.) If the <I>local</I> keyword is used, the z position is
set a distance between lo/hi above the highest current atom in the
simulation that is "nearby" the chosen x,y position. In this context,
"nearby" means the lateral distance (in x,y) between the new and old
particles is less than the <I>delta</I> setting.
</P>
<P>Once a trial x,y,z position has been selected, the insertion is only
performed if no current atom in the simulation is within a distance R
of any atom in the new particle, including the effect of periodic
boundary conditions if applicable. Note that the default value for R
is 0.0, which will allow atoms to strongly overlap if you are
inserting where other atoms are present. This distance test is
performed independently for each atom in an inserted molecule, based
on the randomly rotated configuration of the molecule. If this test
fails, a new random position within the insertion volume is chosen and
another trial is made. Up to Q attempts are made. If the particle is
not successfully inserted, LAMMPS prints a warning message.
</P>
<P>The <I>rate</I> option moves the insertion volume in the z direction (3d)
or y direction (2d). This enables particles to be inserted from a
successively higher height over time. Note that this parameter is
ignored if the <I>global</I> or <I>local</I> keywords are used, since those
options choose a z-coordinate for insertion independently.
</P>
<P>The vx, vy, and vz components of velocity for the inserted particle
are set using the values specified for the <I>vx</I>, <I>vy</I>, and <I>vz</I>
keywords. Note that normally, new particles should be a assigned a
negative vertical velocity so that they move towards the surface. For
molecules, the same velocity is given to every particle (no rotation
or bond vibration).
</P>
<P>If the <I>target</I> option is used, the velocity vector of the inserted
particle is changed so that it points from the insertion position
towards the specified target point. The magnitude of the velocity is
unchanged. This can be useful, for example, for simulating a
sputtering process. E.g. the target point can be far away, so that
all incident particles strike the surface as if they are in an
incident beam of particles at a prescribed angle.
</P>
<P>The <I>id</I> keyword determines how atom IDs and molecule IDs are assigned
to newly deposited particles. Molecule IDs are only assigned if
molecules are being inserted. For the <I>max</I> setting, the atom and
molecule IDs of all current atoms are checked. Atoms in the new
particle are assigned IDs starting with the current maximum plus one.
If a molecule is inserted it is assigned an ID = current maximum plus
one. This means that if particles leave the system, the new IDs may
replace the lost ones. For the <I>next</I> setting, the maximum ID of any
atom and molecule is stored at the time the fix is defined. Each time
a new particle is added, this value is incremented to assign IDs to
the new atom(s) or molecule. Thus atom and molecule IDs for deposited
particles will be consecutive even if particles leave the system over
time.
</P>
<P>The <I>units</I> keyword determines the meaning of the distance units used
for the other deposition parameters. A <I>box</I> value selects standard
distance units as defined by the <A HREF = "units.html">units</A> command,
e.g. Angstroms for units = real or metal. A <I>lattice</I> value means the
distance units are in lattice spacings. The <A HREF = "lattice.html">lattice</A>
command must have been previously used to define the lattice spacing.
Note that the units choice affects all the keyword values that have
units of distance or velocity.
</P>
+<P>IMPORTANT NOTE: If you are monitoring the temperature of a system
+where the atom count is changing due to adding atoms, you typically
+should use the <A HREF = "compute_modify.html">compute_modify dynamic yes</A>
+command for the temperature compute you are using.
+</P>
<P><B>Restart, fix_modify, output, run start/stop, minimize info:</B>
</P>
<P>This fix writes the state of the deposition to <A HREF = "restart.html">binary restart
files</A>. This includes information about how many
particles have been depositied, the random number generator seed, the
next timestep for deposition, etc. See the
<A HREF = "read_restart.html">read_restart</A> command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
</P>
<P>None of the <A HREF = "fix_modify.html">fix_modify</A> options are relevant to this
fix. No global or per-atom quantities are stored by this fix for
access by various <A HREF = "Section_howto.html#howto_15">output commands</A>. No
parameter of this fix can be used with the <I>start/stop</I> keywords of
the <A HREF = "run.html">run</A> command. This fix is not invoked during <A HREF = "minimize.html">energy
minimization</A>.
</P>
<P><B>Restrictions:</B>
</P>
<P>This fix is part of the MISC package. It is only enabled if LAMMPS
was built with that package. See the <A HREF = "Section_start.html#start_3">Making
LAMMPS</A> section for more info.
</P>
<P>The specified insertion region cannot be a "dynamic" region, as
defined by the <A HREF = "region.html">region</A> command.
fix ID group-ID deposit N type M seed keyword values ... :pre
ID, group-ID are documented in "fix"_fix.html command :ulb,l
deposit = style name of this fix command :l
N = # of atoms or molecules to insert :l
type = atom type to assign to inserted atoms (offset for moleclue insertion) :l
M = insert a single atom or molecule every M steps :l
seed = random # seed (positive integer) :l
one or more keyword/value pairs may be appended to args :l
keyword = {region} or {id} or {global} or {local} or {near} or {attempt} or {rate} or {vx} or {vy} or {vz} or {mol} or {rigid} or {shake} or {units} :l
{region} value = region-ID
region-ID = ID of region to use as insertion volume
{id} value = {max} or {next}
max = atom ID for new atom(s) is max ID of all current atoms plus one
next = atom ID for new atom(s) increments by one for every deposition
{global} values = lo hi
lo,hi = put new atom/molecule a distance lo-hi above all other atoms (distance units)
{local} values = lo hi delta
lo,hi = put new atom/molecule a distance lo-hi above any nearby atom beneath it (distance units)
delta = lateral distance within which a neighbor is considered "nearby" (distance units)
{near} value = R
R = only insert atom/molecule if further than R from existing particles (distance units)
{attempt} value = Q
Q = attempt a single insertion up to Q times
{rate} value = V
V = z velocity (y in 2d) at which insertion volume moves (velocity units)
{vx} values = vxlo vxhi
vxlo,vxhi = range of x velocities for inserted atom/molecule (velocity units)
{vy} values = vylo vyhi
vylo,vyhi = range of y velocities for inserted atom/molecule (velocity units)
{vz} values = vzlo vzhi
vzlo,vzhi = range of z velocities for inserted atom/molecule (velocity units)
{target} values = tx ty tz
tx,ty,tz = location of target point (distance units)
{mol} value = template-ID
template-ID = ID of molecule template specified in a separate "molecule"_molecule.html command
{rigid} value = fix-ID
fix-ID = ID of "fix rigid/small"_fix_rigid.html command
{shake} value = fix-ID
fix-ID = ID of "fix shake"_fix_shake.html command
{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:]
fix 3 all deposit 1000 2 100 29494 region myblock local 1.0 1.0 1.0 units box
fix 2 newatoms deposit 10000 1 500 12345 region disk near 2.0 vz -1.0 -0.8
fix 4 sputter deposit 1000 2 500 12235 region sphere vz -1.0 -1.0 target 5.0 5.0 0.0 units lattice :pre
[Description:]
Insert a single atom or molecule into the simulation domain every M
timesteps until N atoms or molecules have been inserted. This is
useful for simulating deposition onto a surface. For the remainder of
this doc page, a single inserted atom or molecule is referred to as a
"particle".
If inserted particles are individual atoms, they are assigned the
specified atom type. If they are molecules, the type of each atom in
the inserted 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 the file specifies atom types 1,2,3, and
those are the atom types you want for inserted molecules, then specify
{type} = 0. If you specify {type} = 2, the in the inserted molecule
will have atom types 3,4,5.
All atoms in the inserted particle are assigned to two groups: the
default group "all" and the group specified in the fix deposit command
(which can also be "all").
If you are computing temperature values which include inserted
particles, you will want to use the
"compute_modify"_compute_modify.html dynamic option, which insures the
current number of atoms is used as a normalizing factor each time the
temperature is computed.
Care must be taken that inserted particles are not too near existing
atoms, using the options described below. When inserting particles
above a surface in a non-periodic box (see the
"boundary"_boundary.html command), the possibility of a particle
escaping the surface and flying upward should be considered, since the
particle may be lost or the box size may grow infinitely large. A
"fix wall/reflect"_fix_wall_reflect.html command can be used to
prevent this behavior. Note that if a shrink-wrap boundary is used,
it is OK to insert the new particle outside the box, however the box
will immediately be expanded to include the new particle. When
simulating a sputtering experiment it is probably more realistic to
ignore those atoms using the "thermo_modify"_thermo_modify.html
command with the {lost ignore} option and a fixed
"boundary"_boundary.html.
The fix deposit command must use the {region} keyword to define an
insertion volume. The specified region must have been previously
defined with a "region"_region.html command. It must be defined with
side = {in}.
Individual atoms are inserted, 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.
If you wish to insert molecules via the {mol} keyword, that will be
treated as rigid bodies, use the {rigid} keyword, specifying as its
value the ID of a separate "fix rigid/small"_fix_rigid_small.html
command which also appears in your input script.
If you wish to insert molecules via the {mol} keyword, that will have
their bonds or angles constrained via SHAKE, use the {shake} keyword,
specifying as its value the ID of a separate "fix
shake"_fix_shake.html command which also appears in your input script.
Each timestep a particle is inserted, the coordinates for its atoms
are chosen as follows. For insertion of individual atoms, the
"position" referred to in the following description is the coordinate
of the atom. For insertion of molecule, the "position" is the
geometric center of the molecule; see the (molecule"_molecule.html doc
page for details. A random rotation of the molecule around its center
point is performed, which determines the coordinates all the
individual atoms.
A random position within the region insertion volume is generated. If
neither the {global} or {local} keyword is used, the random position
is the trial position. If the {global} keyword is used, the random
x,y values are used, but the z position of the new particle is set
above the highest current atom in the simulation by a distance
randomly chosen between lo/hi. (For a 2d simulation, this is done for
the y position.) If the {local} keyword is used, the z position is
set a distance between lo/hi above the highest current atom in the
simulation that is "nearby" the chosen x,y position. In this context,
"nearby" means the lateral distance (in x,y) between the new and old
particles is less than the {delta} setting.
Once a trial x,y,z position has been selected, the insertion is only
performed if no current atom in the simulation is within a distance R
of any atom in the new particle, including the effect of periodic
boundary conditions if applicable. Note that the default value for R
is 0.0, which will allow atoms to strongly overlap if you are
inserting where other atoms are present. This distance test is
performed independently for each atom in an inserted molecule, based
on the randomly rotated configuration of the molecule. If this test
fails, a new random position within the insertion volume is chosen and
another trial is made. Up to Q attempts are made. If the particle is
not successfully inserted, LAMMPS prints a warning message.
The {rate} option moves the insertion volume in the z direction (3d)
or y direction (2d). This enables particles to be inserted from a
successively higher height over time. Note that this parameter is
ignored if the {global} or {local} keywords are used, since those
options choose a z-coordinate for insertion independently.
The vx, vy, and vz components of velocity for the inserted particle
are set using the values specified for the {vx}, {vy}, and {vz}
keywords. Note that normally, new particles should be a assigned a
negative vertical velocity so that they move towards the surface. For
molecules, the same velocity is given to every particle (no rotation
or bond vibration).
If the {target} option is used, the velocity vector of the inserted
particle is changed so that it points from the insertion position
towards the specified target point. The magnitude of the velocity is
unchanged. This can be useful, for example, for simulating a
sputtering process. E.g. the target point can be far away, so that
all incident particles strike the surface as if they are in an
incident beam of particles at a prescribed angle.
The {id} keyword determines how atom IDs and molecule IDs are assigned
to newly deposited particles. Molecule IDs are only assigned if
molecules are being inserted. For the {max} setting, the atom and
molecule IDs of all current atoms are checked. Atoms in the new
particle are assigned IDs starting with the current maximum plus one.
If a molecule is inserted it is assigned an ID = current maximum plus
one. This means that if particles leave the system, the new IDs may
replace the lost ones. For the {next} setting, the maximum ID of any
atom and molecule is stored at the time the fix is defined. Each time
a new particle is added, this value is incremented to assign IDs to
the new atom(s) or molecule. Thus atom and molecule IDs for deposited
particles will be consecutive even if particles leave the system over
time.
The {units} keyword determines the meaning of the distance units used
for the other deposition parameters. 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. The "lattice"_lattice.html
command must have been previously used to define the lattice spacing.
Note that the units choice affects all the keyword values that have
units of distance or velocity.
+IMPORTANT NOTE: If you are monitoring the temperature of a system
+where the atom count is changing due to adding atoms, you typically
+should use the "compute_modify dynamic yes"_compute_modify.html
+command for the temperature compute you are using.
+
[Restart, fix_modify, output, run start/stop, minimize info:]
This fix writes the state of the deposition to "binary restart
files"_restart.html. This includes information about how many
particles have been depositied, the random number generator seed, the
next timestep for deposition, etc. See the
"read_restart"_read_restart.html command for info on how to re-specify
a fix in an input script that reads a restart file, so that the
operation of the fix continues in an uninterrupted fashion.
None of the "fix_modify"_fix_modify.html options are relevant to this
fix. No global or per-atom quantities are stored by this fix for
access by various "output commands"_Section_howto.html#howto_15. No
parameter of this fix can be used with the {start/stop} keywords of
the "run"_run.html command. This fix is not invoked during "energy
minimization"_minimize.html.
[Restrictions:]
This fix is part of the MISC package. It is only enabled if LAMMPS
was built with that package. See the "Making
LAMMPS"_Section_start.html#start_3 section for more info.
The specified insertion region cannot be a "dynamic" region, as
defined by the "region"_region.html command.
[Related commands:]
"fix_pour"_fix_pour.html, "region"_region.html
[Default:]
Insertions are performed for individual atoms, i.e. no {mol} setting
is defined. Additional option defaults are id = max, delta = 0.0,
<LI>style = <I>delete</I> or <I>region</I> or <I>type</I> or <I>id</I> or <I>molecule</I> or <I>variable</I> or <I>subtract</I> or <I>union</I> or <I>intersect</I> or <I>dynamic</I> or <I>static</I>
<PRE> <I>delete</I> = no args
<I>region</I> args = region-ID
<I>type</I> or <I>id</I> or <I>molecule</I>
args = list of one or more atom types, atom IDs, or molecule IDs
any entry in list can be a sequence formatted as A:B or A:B:C where
A = starting index, B = ending index,
C = increment between indices, 1 if not specified
args = logical value
logical = "<" or "<=" or ">" or ">=" or "==" or "!="
value = an atom type or atom ID or molecule ID (depending on <I>style</I>)
args = logical value1 value2
logical = "<>"
value1,value2 = atom types or atom IDs or molecule IDs (depending on <I>style</I>)
<I>variable</I> args = variable-name
<I>subtract</I> args = two or more group IDs
<I>union</I> args = one or more group IDs
<I>intersect</I> args = two or more group IDs
<I>dynamic</I> args = parent-ID keyword value ...
one or more keyword/value pairs may be appended
keyword = <I>region</I> or <I>var</I> or <I>every</I>
<I>region</I> value = region-ID
<I>var</I> value = name of variable
<I>every</I> value = N = update group every this many timesteps
<I>static</I> = no args
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>group edge region regstrip
group water type 3 4
group sub id 10 25 50
group sub id 10 25 50 500:1000
group sub id 100:10000:10
group sub id <= 150
group polyA molecule <> 50 250
group hienergy variable eng
group boundary subtract all a2 a3
group boundary union lower upper
group boundary intersect upper flow
group boundary delete
group mine dynamic all region myRegion every 100
</PRE>
<P><B>Description:</B>
</P>
<P>Identify a collection of atoms as belonging to a group. The group ID
can then be used in other commands such as <A HREF = "fix.html">fix</A>,
<LI>style = <I>delete</I> or <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or <I>uloop</I> or <I>string</I> or <I>format</I> or <I>getenv</I> or <I>file</I> or <I>atomfile</I> or <I>equal</I> or <I>atom</I>
<PRE> <I>delete</I> = no args
<I>index</I> args = one or more strings
<I>loop</I> args = N
N = integer size of loop, loop from 1 to N inclusive
<I>loop</I> args = N pad
N = integer size of loop, loop from 1 to N inclusive
pad = all values will be same length, e.g. 001, 002, ..., 100
<I>loop</I> args = N1 N2
N1,N2 = loop from N1 to N2 inclusive
<I>loop</I> args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100
<I>world</I> args = one string for each partition of processors
<I>universe</I> args = one or more strings
<I>uloop</I> args = N
N = integer size of loop
<I>uloop</I> args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
<I>string</I> arg = one string
<I>format</I> args = vname fstr
vname = name of equal-style variable to evaluate
fstr = C-style format string
<I>getenv</I> arg = one string
<I>file</I> arg = filename
<I>atomfile</I> arg = filename
<I>equal</I> or <I>atom</I> args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
style = {delete} or {index} or {loop} or {world} or {universe} or {uloop} or {string} or {format} or {getenv} or {file} or {atomfile} or {equal} or {atom} :l
{delete} = no args
{index} args = one or more strings
{loop} args = N
N = integer size of loop, loop from 1 to N inclusive
{loop} args = N pad
N = integer size of loop, loop from 1 to N inclusive
pad = all values will be same length, e.g. 001, 002, ..., 100
{loop} args = N1 N2
N1,N2 = loop from N1 to N2 inclusive
{loop} args = N1 N2 pad
N1,N2 = loop from N1 to N2 inclusive
pad = all values will be same length, e.g. 050, 051, ..., 100
{world} args = one string for each partition of processors
{universe} args = one or more strings
{uloop} args = N
N = integer size of loop
{uloop} args = N pad
N = integer size of loop
pad = all values will be same length, e.g. 001, 002, ..., 100
{string} arg = one string
{format} args = vname fstr
vname = name of equal-style variable to evaluate
fstr = C-style format string
{getenv} arg = one string
{file} arg = filename
{atomfile} arg = filename
{equal} or {atom} args = one formula containing numbers, thermo keywords, math operations, group functions, atom values and vectors, compute/fix/variable references
numbers = 0.0, 100, -5.4, 2.8e-4, etc
constants = PI
thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html
math operators = (), -x, x+y, x-y, x*y, x/y, x^y,
x==y, x!=y, x<y, x<=y, x>y, x>=y, x&&y, x||y, !x
math functions = sqrt(x), exp(x), ln(x), log(x), abs(x),
+----- DETAILS: Editing the "oplsaa_subset.prm" file -------
+
+Again, before you run "oplsaa_moltemplate.py", you must edit the "oplsaa.prm"
+file (or "oplsaa_subset.prm file) and eliminate atom types which do not
+correspond to any of the atoms in your simulation. This means you must
+look for lines near the beginning of this file which begin with the word "atom"
+and refer to atom types which appear in the simulation you plan to run. All
+other lines (beginning with the word "atom") must be deleted or commented out.
+(Leave the rest of the file alone.)
For example:
-Let's assume this new file is called "oplsaa_subset.txt". If you were
-working with ethylene you would delete every atom except for atom 85(C=)
-and 86(H-C=) and use that as the input file for oplsaa_moltemplate.py
+If you were working with ethylene and benzene you would delete every line
+beginning with the word "atom", except for these four lines:
-atom 85 37 CM "Alkene H2-C=" 6 12.011 3
-atom 86 36 HC "Alkene H-C=" 1 1.008 1
+# for ethylene:
+atom 88 47 CM "Alkene H2-C=" 6 12.011 3
+atom 89 46 HC "Alkene H-C=" 1 1.008 1
+# for benzene:
+atom 90 48 CA "Aromatic C" 6 12.011 3
+atom 91 49 HA "Aromatic H-C" 1 1.008 1
-You do not need to make any other changes other than that. Then run:
+Then you are ready to run oplsaa_moltemplate.py on this file.
-python oplsaa_moltemplate.py oplsaa_subset.txt
+(You can try to delete more irrelevant information, but be careful.
+ It is not necessary, and it is easy to make mistakes.)
- ...this will create a file named "oplsaa.lt"
-Look over the newly created "oplsaa.lt" file. Then copy it to the "common" directory (where other force-field files like gaff.lt are located, ...or just copy it to wherever you plan to run moltemplate).
+----- Using the "oplsaa.lt" file -----
-Then you can create molecules that refer to it using:
+Once you have created the "oplsaa.lt" file, you can create files (like
+ethylene.lt) which define molecules that refer to these atom types.
+Here is an excerpt from "ethyelene.lt":
Ethylene inherits OPLSAA {
- # Definition of Ethylene molecule goes here.
+ write('Data Atoms') {
+ list of atoms goes here ...
+ }
+ write('Data Bond List') {
+ list of bonds goes here ...
+ }
}
-CHARGE:
+And then run moltemplate.
+
+
+----------- CHARGE: -----------
By default, the OPLSAA force-field assigns atom charge according to atom type.
When you run moltemplate, it will create a file named "system.in.charges",
containing commands like:
set type 2 charge -0.42
set type 3 charge 0.21
(This assumes your main moltemplate file is named "system.lt". If it was
named something else, eg "polymer.lt", then the file created by moltemplate
will be named "polymer.in.charges".)
Include these commands somewhere in your LAMMPS input script
(or use the LAMMPS "include" command to load the commands in system.in.charges)
Note that the atom numbers (eg "2", "3") in this file will not match the
OPLS atom numbers. (Check the output_ttree/ttree_assignments.txt file,
created by moltemplate, to see a table of "@atom" type numbers translated
from OPLSAA into LAMMPS.)
--Jason Lambert
-February, 2014
+----------- CREDIT -----------
+
+If you use these tools and you publish a paper using OPLSAA, please also cite
+the TINKER program. (Because the original "oplsaa.prm" file which we depend on
+is distributed with TINKER.) I think these are the relevant citations:
+
+1) Ponder, J. W., & Richards, F. M. (1987). "An efficient newtonâlike method for molecular mechanics energy minimization of large molecules. Journal of Computational Chemistry", 8(7), 1016-1024.
+
+2) Ponder, J. W, (2004) "TINKER: Software tools for molecular design", http://dasher.wustl.edu/tinker/
+
+-------------------------------
+
+Jason Lambert and Andrew Jewett
+April, 2014
-Please email bugs to jewett.aij@gmail.com
+Please email bugs to jewett.aij@gmail.com and jlamber9@gmail.com
+The original oplsaa.txt from moltemplate version 1.20 file is located here.
+Feel free to pick whichever one works well for your application, but
+if you publish a paper using these parameters please cite TINKER,
+since that appears to be the source of all of these files.
+I think these are the relevant citations:
+
+Ponder, J. W., & Richards, F. M. (1987). "An efficient newtonâlike method for molecular mechanics energy minimization of large molecules. Journal of Computational Chemistry", 8(7), 1016-1024.
+
+Ponder, J. W, (2004) "TINKER: Software tools for molecular design", http://dasher.wustl.edu/tinker/
+
+
+Here is a discussion of a difference between these two files:
+
+>> On Fri, Apr 11, 2014 at 6:44 PM, Andrew Jewett <jewett.aij@gmail.com> wrote:
+>> Jason
+>> Lambert graciously wrote the "oplsaa_moltemplate.py" script and
+>> provided the "oplsaa.txt" file which it reads as an input file (after
+>> some minor manual editing on the part of the user). I did some
+>> googling, and I noticed that this file is very similar to the
+and save this file as "oplsaa_subset.prm". Then you must EDIT THIS FILE
+so that it only contains atom types you plan to have in your simulation
+(see below for details). Then run the opls_moltemplate.py script this way:
+
+
+python oplsaa_moltemplate.py oplsaa_subset.prm
+
+
+This will create a file named "oplsaa.lt"
+Look over the newly created "oplsaa.lt" file.
+Then move this file to wherever you plan to run moltemplate. For example:
+
+mv -f oplsaa.lt ..
+
+----- DETAILS: Editing the "oplsaa_subset.prm" file -------
+
+Again, before you run "oplsaa_moltemplate.py", you must edit the "oplsaa.prm"
+file (or "oplsaa_subset.prm file) and eliminate atom types which do not
+correspond to any of the atoms in your simulation. This means you must
+look for lines near the beginning of this file which begin with the word "atom"
+and refer to atom types which appear in the simulation you plan to run. All
+other lines (beginning with the word "atom") must be deleted or commented out.
+(Leave the rest of the file alone.)
+
+For example:
+If you were working with ethylene and benzene you would delete every line
+beginning with the word "atom", except for these four lines:
+
+# for ethylene:
+atom 88 47 CM "Alkene H2-C=" 6 12.011 3
+atom 89 46 HC "Alkene H-C=" 1 1.008 1
+# for benzene:
+atom 90 48 CA "Aromatic C" 6 12.011 3
+atom 91 49 HA "Aromatic H-C" 1 1.008 1
+
+Then you are ready to run oplsaa_moltemplate.py on this file.
+
+(You can try to delete more irrelevant information, but be careful.
+ It is not necessary, and it is easy to make mistakes.)
+
+
+----- Using the "oplsaa.lt" file -----
+
+Once you have created the "oplsaa.lt" file, you can create files (like
+ethylene.lt) which define molecules that refer to these atom types.
+Here is an excerpt from "ethyelene.lt":
+
+Ethylene inherits OPLSAA {
+ write('Data Atoms') {
+ list of atoms goes here ...
+ }
+ write('Data Bond List') {
+ list of bonds goes here ...
+ }
+}
+
+And then run moltemplate.
+
+
+----------- CHARGE: -----------
+
+By default, the OPLSAA force-field assigns atom charge according to atom type.
+When you run moltemplate, it will create a file named "system.in.charges",
+containing commands like:
+
+set type 2 charge -0.42
+set type 3 charge 0.21
+
+(This assumes your main moltemplate file is named "system.lt". If it was
+named something else, eg "polymer.lt", then the file created by moltemplate
+will be named "polymer.in.charges".)
+
+Include these commands somewhere in your LAMMPS input script
+(or use the LAMMPS "include" command to load the commands in system.in.charges)
+
+Note that the atom numbers (eg "2", "3") in this file will not match the
+OPLS atom numbers. (Check the output_ttree/ttree_assignments.txt file,
+created by moltemplate, to see a table of "@atom" type numbers translated
+from OPLSAA into LAMMPS.)
+
+----------- CREDIT -----------
+
+If you use these tools and you publish a paper using OPLSAA, please also cite
+the TINKER program. (Because these examples use the "oplsaa.prm" file which
+is distributed with TINKER.) I think these are the relevant citations:
+
+1) Ponder, J. W., & Richards, F. M. (1987). "An efficient newtonâlike method for molecular mechanics energy minimization of large molecules. Journal of Computational Chemistry", 8(7), 1016-1024.
+
+2) Ponder, J. W, (2004) "TINKER: Software tools for molecular design", http://dasher.wustl.edu/tinker/
+
+-------------------------------
+
+Jason Lambert and Andrew Jewett
+April, 2014
+
+Please email bugs to jewett.aij@gmail.com and jlamber9@gmail.com
+and save this file as "oplsaa_subset.prm". Then you must EDIT THIS FILE
+so that it only contains atom types you plan to have in your simulation
+(see below for details). Then run the opls_moltemplate.py script this way:
------------ GENERAL DOCUMENTATION -----------
-The "oplsaa_subset.txt" file should contain force-field information
-for a subset of the atoms in the oplsaa forcefield. This directory
-also contains the python code ("oplsaa_moltemplate.py") used to
-generate that file, as well as the full oplsaa force field file: "oplsaa.txt".
-NOTE: THE ORIGINAL "oplsaa.txt" FILE IS LOCATED IN THE "common/opls/" DIRECTORY.
- (I deleted it here to save space.)
+python oplsaa_moltemplate.py oplsaa_subset.prm
-python oplsaa_moltemplate.py <force field file name>
-First, back-up the oplsaa.txt file and then delete all the unnecessary atoms
-from the file.
+This will create a file named "oplsaa.lt"
+Look over the newly created "oplsaa.lt" file.
+Then move this file to wherever you plan to run moltemplate. For example:
-It is ideal for you to run this on a subset of the OPLS forcefield relevant
-to your problem. (It is possible for you to generate a full OPLS force field
-moltemplate file but that demands a lot of time and generates a file that is
-on the order 100 gigabytes, which moltemplate can not read.)
-Save yourself time and energy, and make a copy of the oplsaa.txt. Then edit
-this file and delete or comment out any line beginning with the word "atom"
-which is not relevant to your problem. (However keep the rest of the file.)
+mv -f oplsaa.lt ..
+
+----- DETAILS: Editing the "oplsaa_subset.prm" file -------
+
+Again, before you run "oplsaa_moltemplate.py", you must edit the "oplsaa.prm"
+file (or "oplsaa_subset.prm file) and eliminate atom types which do not
+correspond to any of the atoms in your simulation. This means you must
+look for lines near the beginning of this file which begin with the word "atom"
+and refer to atom types which appear in the simulation you plan to run. All
+other lines (beginning with the word "atom") must be deleted or commented out.
+(Leave the rest of the file alone.)
For example:
-Let's assume this new file is called "oplsaa_subset.txt". If you were
-working with ethylene you would delete every atom except for atom 85(C=)
-and 86(H-C=) and use that as the input file for oplsaa_moltemplate.py
+If you were working with ethylene, you would delete every line
+beginning with the word "atom", except for these two lines:
+
-atom 85 37 CM "Alkene H2-C=" 6 12.011 3
-atom 86 36 HC "Alkene H-C=" 1 1.008 1
+atom 88 47 CM "Alkene H2-C=" 6 12.011 3
+atom 89 46 HC "Alkene H-C=" 1 1.008 1
-You do not need to make any other changes other than that. Then run:
-python oplsaa_moltemplate.py oplsaa_subset.txt
+Then you are ready to run oplsaa_moltemplate.py on this file.
- ...this will create a file named "oplsaa.lt"
+(You can try to delete more irrelevant information, but be careful.
+ It is not necessary, and it is easy to make mistakes.)
-Look over the newly created "oplsaa.lt" file. Then copy it to the "common" directory (where other force-field files like gaff.lt are located, ...or just copy it to wherever you plan to run moltemplate).
-Then you can create molecules that refer to it using:
+----- Using the "oplsaa.lt" file -----
+
+Once you have created the "oplsaa.lt" file, you can create files (like
+ethylene.lt) which define molecules that refer to these atom types.
+Here is an excerpt from "ethyelene.lt":
Ethylene inherits OPLSAA {
- # Definition of Ethylene molecule goes here.
+ write('Data Atoms') {
+ list of atoms goes here ...
+ }
+ write('Data Bond List') {
+ list of bonds goes here ...
+ }
}
-CHARGE:
+And then run moltemplate.
+
+
+----------- CHARGE: -----------
By default, the OPLSAA force-field assigns atom charge according to atom type.
When you run moltemplate, it will create a file named "system.in.charges",
containing commands like:
set type 2 charge -0.42
set type 3 charge 0.21
(This assumes your main moltemplate file is named "system.lt". If it was
named something else, eg "polymer.lt", then the file created by moltemplate
will be named "polymer.in.charges".)
Include these commands somewhere in your LAMMPS input script
(or use the LAMMPS "include" command to load the commands in system.in.charges)
Note that the atom numbers (eg "2", "3") in this file will not match the
OPLS atom numbers. (Check the output_ttree/ttree_assignments.txt file,
created by moltemplate, to see a table of "@atom" type numbers translated
from OPLSAA into LAMMPS.)
--Jason Lambert
-February, 2014
+----------- CREDIT -----------
+
+If you use these tools and you publish a paper using OPLSAA, please also cite
+the TINKER program. (Because these examples use the "oplsaa.prm" file which
+is distributed with TINKER.) I think these are the relevant citations:
+
+1) Ponder, J. W., & Richards, F. M. (1987). "An efficient newtonâlike method for molecular mechanics energy minimization of large molecules. Journal of Computational Chemistry", 8(7), 1016-1024.
+
+2) Ponder, J. W, (2004) "TINKER: Software tools for molecular design", http://dasher.wustl.edu/tinker/
+
+-------------------------------
-Please email bugs to jewett.aij@gmail.com
+Jason Lambert and Andrew Jewett
+April, 2014
+Please email bugs to jewett.aij@gmail.com and jlamber9@gmail.com