jianmu
/
lammps
forked from lijiext/lammps
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@5925 f3b2605a-c512-4ea7-a41b-209d697bcdaa

This commit is contained in:
sjplimp 2011-04-11 19:49:41 +00:00
parent 3b43d998c2
commit 0d56ce0615
20 changed files with 1913 additions and 214 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/Section_start.html
View File

@ -83,13 +83,13 @@ and build it yourself, as described in the next section.
<P>Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
(MPI, FFT), etc. Please read this section carefully. If you are not
comfortable with makefiles, or building codes on a Unix platform, or
running an MPI job on your machine, please find a local expert to help
you. Many compiling, linking, and run problems that users are not
really LAMMPS issues - they are peculiar to the user's system,
compilers, libraries, etc. Such questions are better answered by a
local expert.
(MPI, FFT, JPEG), etc. Please read this section carefully. If you
are not comfortable with makefiles, or building codes on a Unix
platform, or running an MPI job on your machine, please find a local
expert to help you. Many compiling, linking, and run problems that
users are not really LAMMPS issues - they are peculiar to the user's
system, compilers, libraries, etc. Such questions are better answered
by a local expert.
</P>
<P>If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
@ -196,18 +196,38 @@ which uses different rules that do not involve dependency files.
<P>(3) The "system-specific settings" section has 4 parts.
</P>
<P>(3.a) The LMP_INC variable is used to include options that turn on
system-dependent ifdefs within the LAMMPS code.
system-dependent ifdefs within the LAMMPS code. The settings
that are currently recogized are:
</P>
<UL><LI>-DLAMMPS_GZIP
<LI>-DPACK_ARRAY
<LI>-DPACK_POINTER
<LI>-DPACK_MEMCPY
<LI>-DLAMMPS_XDR
<LI>-DLAMMPS_JPEG
</UL>
<P>The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your Unix support the
"popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and
-DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
solver) on some platforms. The -DPACK_ARRAY setting is the default.
If you use -DLAMMPS_XDR, the build will include XDR compatibility
"popen" command.
</P>
<P>Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
options can make for faster parallel FFTs (in the PPPM solver) on some
platforms. The -DPACK_ARRAY setting is the default. See the
<A HREF = "kspace_style.html">kspace_style</A> command for info about PPPM. See
section (3.c) below for info about building LAMMPS with an FFT
library.
</P>
<P>If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the <A HREF = "dump.html">dump</A> command for details.
</P>
<P>If you use -DLAMMPS_JPEG, the <A HREF = "dump.html">dump image</A> command will be
able to write out JPEG image files. If not, it will only be able to
write out PPM image files. For JPEG files, you must also link LAMMPS
with a JPEG library. See section (3.d) below for more details on
this.
</P>
<P>(3.b) The 3 MPI variables are used to specify an MPI library to build
LAMMPS with.
</P>
@ -219,19 +239,20 @@ need to specify where the mpi.h file (MPI_INC) and the MPI library
(MPI_PATH) is found and its name (MPI_LIB).
</P>
<P>If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
or 2.0 which can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
site</A>. LAM MPI should also work. If
or 2.0 or OpenMPI. MPICH can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
site</A>. OpenMPI can be downloaded the
<A HREF = "http://www.open-mpi.org">OpenMPI site</A>. LAM MPI should also work. If
you are running on a big parallel platform, your system people or the
vendor should have already installed a version of MPI, which will be
faster than MPICH or LAM, so find out how to build and link with it.
If you use MPICH or LAM, you will have to configure and build it for
your platform. The MPI configure script should have compiler options
to enable you to use the same compiler you are using for the LAMMPS
build, which can avoid problems that can arise when linking LAMMPS to
the MPI library.
faster than MPICH or OpenMPI or LAM, so find out how to build and link
with it. If you use MPICH or OpenMPI or LAM, you will have to
configure and build it for your platform. The MPI configure script
should have compiler options to enable you to use the same compiler
you are using for the LAMMPS build, which can avoid problems that can
arise when linking LAMMPS to the MPI library.
</P>
<P>If you just want LAMMPS to run on a single processor, you can use the
STUBS library in place of MPI, since you don't need an MPI library
STUBS library in place of MPI, since you don't need a true MPI library
installed on your system. See the Makefile.serial file for how to
specify the 3 MPI variables. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
@ -259,7 +280,7 @@ should work on any platform. You can download it from
3.0.X. Building FFTW for your box should be as simple as ./configure;
make. Whichever FFT library you have on your platform, you'll need to
set the appropriate FFT_INC, FFT_PATH, and FFT_LIB variables in
Makefile.foo.
Makefile.foo, so the compiler and linker can find it.
</P>
<P>If you examine src/fft3d.c and src.fft3d.h you'll see it's possible to
add other vendor FFT libraries via #ifdef statements in the
@ -272,7 +293,18 @@ case you can set FFT_INC to -DFFT_NONE and leave the other 2 FFT
variables blank. Or you can exclude the KSPACE package when you build
LAMMPS (see below).
</P>
<P>(3.d) The several SYSLIB and SYSPATH variables can be ignored unless
<P>(3.d) The 3 JPG variables are used to specify a JPEG library which
LAMMPS uses when writing a JPEG file via the <A HREF = "dump_image.html">dump
image</A> command. These can be left blank if you are
not using the -DLAMMPS_JPEG switch discussed above in section (3.a).
</P>
<P>A standard JPEG library usually goes by the name libjpeg.a and has an
associated header file jpeglib.h. Whichever JPEG library you have on
your platform, you'll need to set the appropriate JPG_INC, JPG_PATH,
and JPG_LIB variables in Makefile.foo so that the compiler and linker
can find it.
</P>
<P>(3.e) The several SYSLIB and SYSPATH variables can be ignored unless
you are building LAMMPS with one or more of the LAMMPS packages that
require these extra system libraries. The names of these packages are
the prefixes on the SYSLIB and SYSPATH variables. See the <A HREF = "#2_3_4">section

76
doc/Section_start.txt
View File

@ -78,13 +78,13 @@ This section has the following sub-sections:
Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
(MPI, FFT), etc. Please read this section carefully. If you are not
comfortable with makefiles, or building codes on a Unix platform, or
running an MPI job on your machine, please find a local expert to help
you. Many compiling, linking, and run problems that users are not
really LAMMPS issues - they are peculiar to the user's system,
compilers, libraries, etc. Such questions are better answered by a
local expert.
(MPI, FFT, JPEG), etc. Please read this section carefully. If you
are not comfortable with makefiles, or building codes on a Unix
platform, or running an MPI job on your machine, please find a local
expert to help you. Many compiling, linking, and run problems that
users are not really LAMMPS issues - they are peculiar to the user's
system, compilers, libraries, etc. Such questions are better answered
by a local expert.
If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
@ -191,18 +191,38 @@ which uses different rules that do not involve dependency files.
(3) The "system-specific settings" section has 4 parts.
(3.a) The LMP_INC variable is used to include options that turn on
system-dependent ifdefs within the LAMMPS code.
system-dependent ifdefs within the LAMMPS code. The settings
that are currently recogized are:
-DLAMMPS_GZIP
-DPACK_ARRAY
-DPACK_POINTER
-DPACK_MEMCPY
-DLAMMPS_XDR
-DLAMMPS_JPEG :ul
The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your Unix support the
"popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER, and
-DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
solver) on some platforms. The -DPACK_ARRAY setting is the default.
"popen" command.
Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
options can make for faster parallel FFTs (in the PPPM solver) on some
platforms. The -DPACK_ARRAY setting is the default. See the
"kspace_style"_kspace_style.html command for info about PPPM. See
section (3.c) below for info about building LAMMPS with an FFT
library.
If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the "dump"_dump.html command for details.
If you use -DLAMMPS_JPEG, the "dump image"_dump.html command will be
able to write out JPEG image files. If not, it will only be able to
write out PPM image files. For JPEG files, you must also link LAMMPS
with a JPEG library. See section (3.d) below for more details on
this.
(3.b) The 3 MPI variables are used to specify an MPI library to build
LAMMPS with.
@ -214,19 +234,20 @@ need to specify where the mpi.h file (MPI_INC) and the MPI library
(MPI_PATH) is found and its name (MPI_LIB).
If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
or 2.0 which can be downloaded from the "Argonne MPI
site"_http://www-unix.mcs.anl.gov/mpi. LAM MPI should also work. If
or 2.0 or OpenMPI. MPICH can be downloaded from the "Argonne MPI
site"_http://www-unix.mcs.anl.gov/mpi. OpenMPI can be downloaded the
"OpenMPI site"_http://www.open-mpi.org. LAM MPI should also work. If
you are running on a big parallel platform, your system people or the
vendor should have already installed a version of MPI, which will be
faster than MPICH or LAM, so find out how to build and link with it.
If you use MPICH or LAM, you will have to configure and build it for
your platform. The MPI configure script should have compiler options
to enable you to use the same compiler you are using for the LAMMPS
build, which can avoid problems that can arise when linking LAMMPS to
the MPI library.
faster than MPICH or OpenMPI or LAM, so find out how to build and link
with it. If you use MPICH or OpenMPI or LAM, you will have to
configure and build it for your platform. The MPI configure script
should have compiler options to enable you to use the same compiler
you are using for the LAMMPS build, which can avoid problems that can
arise when linking LAMMPS to the MPI library.
If you just want LAMMPS to run on a single processor, you can use the
STUBS library in place of MPI, since you don't need an MPI library
STUBS library in place of MPI, since you don't need a true MPI library
installed on your system. See the Makefile.serial file for how to
specify the 3 MPI variables. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
@ -254,7 +275,7 @@ should work on any platform. You can download it from
3.0.X. Building FFTW for your box should be as simple as ./configure;
make. Whichever FFT library you have on your platform, you'll need to
set the appropriate FFT_INC, FFT_PATH, and FFT_LIB variables in
Makefile.foo.
Makefile.foo, so the compiler and linker can find it.
If you examine src/fft3d.c and src.fft3d.h you'll see it's possible to
add other vendor FFT libraries via #ifdef statements in the
@ -267,7 +288,18 @@ case you can set FFT_INC to -DFFT_NONE and leave the other 2 FFT
variables blank. Or you can exclude the KSPACE package when you build
LAMMPS (see below).
(3.d) The several SYSLIB and SYSPATH variables can be ignored unless
(3.d) The 3 JPG variables are used to specify a JPEG library which
LAMMPS uses when writing a JPEG file via the "dump
image"_dump_image.html command. These can be left blank if you are
not using the -DLAMMPS_JPEG switch discussed above in section (3.a).
A standard JPEG library usually goes by the name libjpeg.a and has an
associated header file jpeglib.h. Whichever JPEG library you have on
your platform, you'll need to set the appropriate JPG_INC, JPG_PATH,
and JPG_LIB variables in Makefile.foo so that the compiler and linker
can find it.
(3.e) The several SYSLIB and SYSPATH variables can be ignored unless
you are building LAMMPS with one or more of the LAMMPS packages that
require these extra system libraries. The names of these packages are
the prefixes on the SYSLIB and SYSPATH variables. See the "section

10
doc/compute_pair_local.html
View File

@ -62,6 +62,16 @@ property/local</A> command can be combined
with data from this command and output by the <A HREF = "dump.html">dump local</A>
command in a consistent way.
</P>
<P>IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the <A HREF = "special_bonds.html">special_bonds</A>
command.
</P>
<P><B>Output info:</B>
</P>
<P>This compute calculates a local vector or local array depending on the

10
doc/compute_pair_local.txt
View File

@ -54,6 +54,16 @@ property/local"_compute_property_local.html command can be combined
with data from this command and output by the "dump local"_dump.html
command in a consistent way.
IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the "special_bonds"_special_bonds.html
command.
[Output info:]
This compute calculates a local vector or local array depending on the

4
doc/compute_property_local.html
View File

@ -95,9 +95,9 @@ by the <A HREF = "pair_style.html">pair_style</A> command.
</P>
<P>IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
interaction may be turned off, and thus they will not appear in the
interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
command. More specifically, this is true of I,J pairs with a
command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the <A HREF = "special_bonds.html">special_bonds</A>

4
doc/compute_property_local.txt
View File

@ -88,9 +88,9 @@ by the "pair_style"_pair_style.html command.
IMPORTANT NOTE: For pairs, if two atoms I,J are involved in 1-2, 1-3,
1-4 interactions within the molecular topology, their pairwise
interaction may be turned off, and thus they will not appear in the
interaction may be turned off, and thus they may not appear in the
neighbor list, and will not be part of the local data created by this
command. More specifically, this is true of I,J pairs with a
command. More specifically, this may be true of I,J pairs with a
weighting factor of 0.0; pairs with a non-zero weighting factor are
included. The weighting factors for 1-2, 1-3, and 1-4 pairwise
interactions are set by the "special_bonds"_special_bonds.html

11
doc/compute_rdf.html
View File

@ -73,18 +73,7 @@ a specific histogram if the following criteria are met:
<LI>the distance between atoms I,J is less than the maximum force cutoff
<LI>the type of the I atom matches itypeN (one or a range of types)
<LI>the type of the J atom matches jtypeN (one or a range of types)
<LI>the I,J interaction is included in the neighbor list
</UL>
<P>IMPORTANT NOTE: The last point is relevant for molecular systems with
bonds, because if two atoms I,J are involved in 1-2, 1-3, 1-4
interactions within the molecular topology, their pairwise interaction
may be turned off, and thus they will not appear in the neighbor list,
and will not contribute to g(r). More specifically, this is true of
I,J pairs with a weighting factor of 0.0; pairs with a non-zero
weighting factor are included. The weighting factors for 1-2, 1-3,
and 1-4 pairwise interactions are set by the
<A HREF = "special_bonds.html">special_bonds</A> command.
</P>
<P>It is OK if a particular pairwise distance is included in more than
one individual histogram, due to the way the <I>itypeN</I> and <I>jtypeN</I>
arguments are specified.

13
doc/compute_rdf.txt
View File

@ -69,18 +69,7 @@ a specific histogram if the following criteria are met:
atoms I,J are both in the specified compute group
the distance between atoms I,J is less than the maximum force cutoff
the type of the I atom matches itypeN (one or a range of types)
the type of the J atom matches jtypeN (one or a range of types)
the I,J interaction is included in the neighbor list :ul
IMPORTANT NOTE: The last point is relevant for molecular systems with
bonds, because if two atoms I,J are involved in 1-2, 1-3, 1-4
interactions within the molecular topology, their pairwise interaction
may be turned off, and thus they will not appear in the neighbor list,
and will not contribute to g(r). More specifically, this is true of
I,J pairs with a weighting factor of 0.0; pairs with a non-zero
weighting factor are included. The weighting factors for 1-2, 1-3,
and 1-4 pairwise interactions are set by the
"special_bonds"_special_bonds.html command.
the type of the J atom matches jtypeN (one or a range of types) :ul
It is OK if a particular pairwise distance is included in more than
one individual histogram, due to the way the {itypeN} and {jtypeN}

50
doc/dump.html
View File

@ -11,6 +11,8 @@
<H3>dump command
</H3>
<H3><A HREF = "dump_image.html">dump image</A> command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>dump ID group-ID style N file args
@ -19,7 +21,7 @@
<LI>group-ID = ID of the group of atoms to be dumped
<LI>style = <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>local</I> or <I>custom</I>
<LI>style = <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>image</I> or <I>local</I> or <I>custom</I>
<LI>N = dump every this many timesteps
@ -33,6 +35,8 @@
<I>xtc</I> args = none
<I>xyz</I> args = none
</PRE>
<PRE> <I>image</I> args = discussed on <A HREF = "dump_image.html">dump image</A> doc page
</PRE>
<PRE> <I>local</I> args = list of local attributes
possible attributes = index, c_ID, c_ID[N], f_ID, f_ID[N]
index = enumeration of local values
@ -95,13 +99,19 @@ dump e_data all custom 100 dump.eff id type x y z spin eradius fx fy fz eforce
<P><B>Description:</B>
</P>
<P>Dump a snapshot of atom quantities to one or more files every N
timesteps in one of several styles. As described below, the filename
determines the kind of output (text or binary or gzipped, one big file
or one per timestep, one big file or one per processor). Only
information for atoms in the specified group is dumped. The
<A HREF = "dump_modify.html">dump_modify</A> command can also alter what atoms are
included. Not all styles support all these options; see details
below.
timesteps in one of several styles. The <I>image</I> style is the
exception; it creates a JPG or PPM image file of the atom
configuration every N timesteps, as discussed on the <A HREF = "dump_image.html">dump
image</A> doc page.
</P>
<P>Only information for atoms in the specified group is dumped. The
<A HREF = "dump_modify.html">dump_modify thresh and region</A> commands can also
alter what atoms are included. Not all styles support all these
options; see details below.
</P>
<P>As described below, the filename determines the kind of output (text
or binary or gzipped, one big file or one per timestep, one big file
or one per processor).
</P>
<P>IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
@ -142,20 +152,25 @@ self-describing in the following sense.
<P>The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:
</P>
<PRE>ITEM: BOX BOUNDS
<PRE>ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi
</PRE>
<P>where xlo,xhi are the maximum extents of the simulation box in the
x-dimension, and similarly for y and z.
x-dimension, and similarly for y and z. The "xx yy zz" represent 6
characters that encode the style of boundary for each of the 6
simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each
flag is either p = periodic, f = fixed, s = shrink wrap, or m = shrink
wrapped with a minimum value. See the <A HREF = "doc/boundary.html">boundary</A>
command for details.
</P>
<P>For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:
</P>
<PRE>ITEM: BOX BOUNDS xy xz yz
<PRE>ITEM: BOX BOUNDS xx yy zz xy xz yz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz
@ -281,7 +296,10 @@ character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the <I>dcd</I> and
<I>xtc</I> styles.
<I>xtc</I> styles. Note that the <A HREF = "dump_modify.html">dump_modify pad</A>
command can be used to insure all timestep numbers are the same length
(e.g. 00010), which can make it easier to read a series of dump files
in order by some post-processing tools.
</P>
<P>If a "%" character appears in the filename, then one file is written
for each processor and the "%" character is replaced with the
@ -490,8 +508,12 @@ should also work on IBM BG/P, and Windows XP/Vista/7 machines.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "dump_modify.html">dump_modify</A>, <A HREF = "undump.html">undump</A>
<P><A HREF = "dump_image.html">dump image</A>, <A HREF = "dump_modify.html">dump_modify</A>,
<A HREF = "undump.html">undump</A>
</P>
<P><B>Default:</B> none
<P><B>Default:</B>
</P>
<P>The defaults for the image style are listed on the <A HREF = "dump_image.html">dump
image</A> doc page.
</P>
</HTML>

49
doc/dump.txt
View File

@ -7,6 +7,7 @@
:line
dump command :h3
"dump image"_dump_image.html command :h3
[Syntax:]
@ -14,7 +15,7 @@ dump ID group-ID style N file args :pre
ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be dumped :l
style = {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} :l
style = {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {image} or {local} or {custom} :l
N = dump every this many timesteps :l
file = name of file to write dump info to :l
args = list of arguments for a particular style :l
@ -24,6 +25,8 @@ args = list of arguments for a particular style :l
{xtc} args = none
{xyz} args = none :pre
{image} args = discussed on "dump image"_dump_image.html doc page :pre
{local} args = list of local attributes
possible attributes = index, c_ID, c_ID\[N\], f_ID, f_ID\[N\]
index = enumeration of local values
@ -85,13 +88,19 @@ dump e_data all custom 100 dump.eff id type x y z spin eradius fx fy fz eforce :
[Description:]
Dump a snapshot of atom quantities to one or more files every N
timesteps in one of several styles. As described below, the filename
determines the kind of output (text or binary or gzipped, one big file
or one per timestep, one big file or one per processor). Only
information for atoms in the specified group is dumped. The
"dump_modify"_dump_modify.html command can also alter what atoms are
included. Not all styles support all these options; see details
below.
timesteps in one of several styles. The {image} style is the
exception; it creates a JPG or PPM image file of the atom
configuration every N timesteps, as discussed on the "dump
image"_dump_image.html doc page.
Only information for atoms in the specified group is dumped. The
"dump_modify thresh and region"_dump_modify.html commands can also
alter what atoms are included. Not all styles support all these
options; see details below.
As described below, the filename determines the kind of output (text
or binary or gzipped, one big file or one per timestep, one big file
or one per processor).
IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
@ -132,20 +141,25 @@ self-describing in the following sense.
The dimensions of the simulation box are included in each snapshot.
For an orthogonal simulation box this information is is formatted as:
ITEM: BOX BOUNDS
ITEM: BOX BOUNDS xx yy zz
xlo xhi
ylo yhi
zlo zhi :pre
where xlo,xhi are the maximum extents of the simulation box in the
x-dimension, and similarly for y and z.
x-dimension, and similarly for y and z. The "xx yy zz" represent 6
characters that encode the style of boundary for each of the 6
simulation box boundaries (xlo,xhi and ylo,yhi and zlo,zhi). Each
flag is either p = periodic, f = fixed, s = shrink wrap, or m = shrink
wrapped with a minimum value. See the "boundary"_doc/boundary.html
command for details.
For triclinic simulation boxes (non-orthogonal), an orthogonal
bounding box which encloses the triclinic simulation box is output,
along with the 3 tilt factors (xy, xz, yz) of the triclinic box,
formatted as follows:
ITEM: BOX BOUNDS xy xz yz
ITEM: BOX BOUNDS xx yy zz xy xz yz
xlo_bound xhi_bound xy
ylo_bound yhi_bound xz
zlo_bound zhi_bound yz :pre
@ -271,7 +285,10 @@ character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.* becomes tmp.dump.0, tmp.dump.10000,
tmp.dump.20000, etc. This option is not available for the {dcd} and
{xtc} styles.
{xtc} styles. Note that the "dump_modify pad"_dump_modify.html
command can be used to insure all timestep numbers are the same length
(e.g. 00010), which can make it easier to read a series of dump files
in order by some post-processing tools.
If a "%" character appears in the filename, then one file is written
for each processor and the "%" character is replaced with the
@ -480,6 +497,10 @@ should also work on IBM BG/P, and Windows XP/Vista/7 machines.
[Related commands:]
"dump_modify"_dump_modify.html, "undump"_undump.html
"dump image"_dump_image.html, "dump_modify"_dump_modify.html,
"undump"_undump.html
[Default:] none
[Default:]
The defaults for the image style are listed on the "dump
image"_dump_image.html doc page.

430
doc/dump_image.html Normal file
View File

@ -0,0 +1,430 @@
<HTML>
<CENTER><A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> - <A HREF = "Manual.html">LAMMPS Documentation</A> - <A HREF = "Section_commands.html#comm">LAMMPS Commands</A>
</CENTER>
<HR>
<H3>dump image command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>dump ID group-ID image N file keyword value ...
</PRE>
<UL><LI>ID = user-assigned name for the dump
<LI>group-ID = ID of the group of atoms to be imaged
<LI>image = style of dump command (other styles <I>atom</I> or <I>cfg</I> or <I>dcd</I> or <I>xtc</I> or <I>xyz</I> or <I>local</I> or <I>custom</I> are discussed on the <A HREF = "dump.html">dump</A> doc page)
<LI>N = dump every this many timesteps
<LI>file = name of file to write image to
<LI>zero or more keyword/value pairs may be appended
<LI>keyword = <I>atom</I> or <I>bond</I> or <I>size</I> or <I>view</I> or <I>center</I> or <I>up</I> or <I>zoom</I> or <I>persp</I> or <I>box</I> or <I>dynamic</I> or <I>box</I> or <I>axes</I> or <I>shiny</I> or <I>ssao</I>
<PRE> <I>atom</I> values = color diam
color = <I>none</I> or <I>type</I> or <I>element</I> or atom-attribute
diam = D or <I>type</I> or <I>element</I> or <I>radius</I> or <I>shape</I> or atom-attribute
D = numeric value for atom diameter (distance units)
<I>bond</I> values = color diam
color = <I>none</I> or <I>atom</I> or <I>type</I>
diam = D or <I>type</I>
D = numeric value for bond diameter (distance units)
<I>size</I> values = width height
width = width of image in # of pixels
height = height of image in # of pixels
<I>view</I> values = theta phi
theta = view angle from +z axis (degrees)
phi = azimuthal view angle (degrees)
theta or phi can be a variable (see below)
<I>center</I> values = flag Cx Cy Cz = center point of image (distance units)
flag = "s" for static, "d" for dynamic
Cx,Cy,Cz can be variables (see below)
<I>up</I> values = Ux Uy Uz = components of up vector
Ux,Uy,Uz can be variables (see below)
<I>zoom</I> value = factor = scale image size by this factor
factor can be a variable (see below)
<I>persp</I> value = factor = perspective setting
factor can be a variable (see below)
<I>box</I> values = yes/no diam
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
<I>axes</I> values = yes/no length diam
yes/no = do or do not draw xyz axes lines next to simulation box
length = length of axes lines as fraction of respective box lengths
diam = diameter of axes lines as fraction of shortest box length
<I>shiny</I> value = factor
factor = shinyness of spheres and cylinders from 0.0 to 1.0
<I>ssao</I> value = yes/no
yes/no = turn on/off SSAO depth shading
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>dump myDump all image 100 dump.*.jpg
</PRE>
<P><B>Description:</B>
</P>
<P>Dump an image (picture) of the atom configuration every N timesteps as
either a JPG or PPM file. A series of such images can easily be
converted into an animated movie of your simulation; see further
details below. Other dump styles store snapshots of atom quantities
in various formats, as discussed on the <A HREF = "dump.html">dump</A> doc page.
</P>
<P>Only atoms in the specified group are rendered in the image. The
<A HREF = "dump_modify.html">dump_modify region and thresh</A> commands can also
alter what atoms are included in the image.
</P>
<P>The filename suffix determines whether a JPG or PPM file is created.
If the suffix is ".jpg" or ".jpeg", then a JPG file is created, else a
PPM file is created. To write out JPG files, you must build LAMMPS
with a JPEG library. See <A HREF = "Section_start.html#2_2_4">this section</A> of
the manual for instructions on how to do this.
</P>
<P>IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom image may be slightly outside the simulation box.
</P>
<HR>
<P>Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the <A HREF = "dump_modify.html">dump_modify first</A> command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the <A HREF = "dump_modify.html">dump_modify every</A> command (not allowed
for <I>dcd</I> style).
</P>
<P>Dump image filenames must contain a wildcard character "*". If a "*"
character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.*.jpg becomes tmp.dump.0.jpg,
tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the
<A HREF = "dump_modify.html">dump_modify pad</A> command can be used to insure all
timestep numbers are the same length (e.g. 00010), which can make it
easier to convert a series of images into a movie in the correct
ordering.
</P>
<HR>
<P>The kewords listed above control how the image is rendered. As listed
below, all of the keywords have defaults, most of which you will
likely not need to change. The <A HREF = "dump_modify.html">dump modify</A> also
has options specific to the dump image style, particularly for
assigning colors to atoms, bonds, and other image features.
</P>
<HR>
<P>The <I>atom</I> keyword determines the color and size of atoms rendered in
the image. If <I>none</I> is specified for the color value (with any diam
value), then no atoms are drawn.
</P>
<P>The color value can be <I>type</I> or <I>element</I> or an atom-attribute.
</P>
<P>If <I>type</I> is specified for the color
value, then the color of each atom is determined by its atom type.
By default the mapping of types to colors is as follows:
</P>
<UL><LI>type 1 = red
<LI>type 2 = green
<LI>type 3 = blue
<LI>type 4 = yellow
<LI>type 5 = aqua
<LI>type 6 = cyan
</UL>
<P>and repeats itself for types > 6. This mapping can be changed by the
<A HREF = "dump_modify.html">dump_modify acolor</A> command.
</P>
<P>If <I>element</I> is specified for the color value, then the color of each
atom is determined by which element it is, which in turn is specified
by the element-to-type mapping specified by the "dump_modify element"
command. By default every atom type is C (carbon). Every element has
a color associated with it, which is the same as used by the
<A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> visualization package.
</P>
<P>An atom-attribute can also be used for the color value. Any attribute
listed on the <A HREF = "dump.html">dump custom</A> doc page can be used, e.g. vx,
fy, q, spin, etc. This includes per-atom quantities calculated by a
<A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or <A HREF = "variable.html">variable</A>.
For example, if "vx" is used as the per-atom attribute, then the color
of the atom will depend on the x-component of its velocity.
</P>
<P>The association of a per-atom value with a specific color is
determined by a "color map", which can be specified via the
<A HREF = "dump_modify.html">dump_modify</A> command. The basic idea is that the
atom-attribute will be within a range of values, and every value
within the range is mapped to a specific color. Depending on how the
color map is defined, that mapping can take place via interpolation so
that a value of -3.2 is halfway between "red" and "blue", or
discretely so that the value of -3.2 is "orange".
</P>
<P>The diam value can be a numeric value <I>D</I> or <I>type</I> or <I>element</I> or
<I>radius</I> or <I>shape</I> or an atom-attribute.
</P>
<P>If a numeric value <I>D</I> is specified, then all atoms will be drawn with
that diameter, e.g. 1.5, which is in distance units in whatever
<A HREF = "units.html">units</A> you are using, e.g. Angstroms.
</P>
<P>If <I>type</I> is specified for the diam value then the color of each atom
is determined by its atom type. By default all types have diameter
1.0. This mapping can be changed by the <A HREF = "dump_modify.html">dump_modify
adiam</A> command.
</P>
<P>If <I>element</I> is specified for the diam value, then the diamater of
each atom is determined by which element it is, which in turn is
specified by the element-to-type mapping specified by the "dump_modify
element" command. By default every atom type is C (carbon). Every
element has a diamtere associated with it, which is the same as used
by the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A> visualization package.
</P>
<P>If <I>radius</I> or <I>shape</I> is specified for the diam value then those the
atom style you are using must define those attributes. The radius or
shape of the individual atom is then used to draw it. Currently, only
spherical shapes are allowed. Support for ellipsoids will be added
later.
</P>
<P>An atom-attribute can also be used for the diam value. Any attribute
listed on the <A HREF = "dump.html">dump custom</A> doc page can be used, e.g. vx,
fy, q, spin, etc. This includes per-atom quantities calculated by a
<A HREF = "compute.html">compute</A>, <A HREF = "fix.html">fix</A>, or <A HREF = "variable.html">variable</A>.
For example, if "vx" is used as the per-atom attribute, then the
diameter of the atom will depend on the x-component of its velocity,
which will assumed to be >= 0.0, else the atom will not be drawn.
</P>
<HR>
<P>The <I>bond</I> keyword determines the color and thickness or diameter of
bonds rendered in the image. If <I>none</I> is specified for the color
value (with any diam value), then no bonds are drawn.
</P>
<P>If <I>atom</I> is specified for the color value, then the each bond is
drawn in 2 halves, with the color of each half being the color of the
atom at that end of the bond.
</P>
<P>If <I>type</I> is specified for the color value, then the color of each
bond is determined by its bond type. By default the mapping of types
to colors is as follows:
</P>
<UL><LI>type 1 = red
<LI>type 2 = green
<LI>type 3 = blue
<LI>type 4 = yellow
<LI>type 5 = aqua
<LI>type 6 = cyan
</UL>
<P>and repeats itself for types > 6. This mapping can be changed by the
<A HREF = "dump_modify.html">dump_modify bcolor</A> command.
</P>
<P>The diam value can be a numeric value <I>D</I> or <I>type</I>.
</P>
<P>If a numeric value <I>D</I> is specified, then all bond will be drawn with
that diameter, e.g. 1.0, which is in distance units in whatever
<A HREF = "units.html">units</A> you are using, e.g. Angstroms.
</P>
<P>If <I>type</I> is specified for the diam value then the color of each bond
is determined by its bond type. By default all types have diameter
0.5. This mapping can be changed by the <A HREF = "dump_modify.html">dump_modify
bdiam</A> command.
</P>
<HR>
<P>The <I>size</I> keyword determines the width and height of the created
image files, in numbers of pixels in each direction.
</P>
<HR>
<P>The <I>view</I>, <I>center</I>, <I>up</I>, <I>zoom</I>, and <I>persp</I> settings determine how
3d simulation space is mapped to the 2d plane of the image. Basically
they control how the simulation box appears in the image.
</P>
<P>All of the <I>view</I>, <I>center</I>, <I>up</I>, <I>zoom</I>, and <I>persp</I> settings can be
specified as numeric values, whose meaning is explained below. But
any of them can also be specified as an equal-style variable, by using
v_name as the setting, where "name" is the variable name. In this
case the variable will be evaluated on the timestep each image is
created to create a new setting. If the equal-style variable is
time-dependent, this is a means of changing the way the simulation box
appears from image to image, effectively doing a pan or fly-by view of
your simulation.
</P>
<P>The <I>view</I> keyword determines the viewpoint from which the simulation
box is viewed. The <I>theta</I> setting is the vertical angle from the +z
axis, and must be an angle from 0 to 180 degrees. The <I>phi</I> setting
is an azimuthal angle around the z axis and can be positive or
negative.
</P>
<P>The <I>center</I> keyword determines the point in simulation space that
will be at the center of the image. <I>Cx</I>, <I>Cy</I>, and <I>Cz</I> are
speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
the center of the simulation box. These values do not have to be
between 0.0 and 1.0, if you want the simulation box to be offset from
the center of the image. Note, however, that if you choose odd values
for <I>Cx</I>, <I>Cy</I>, or <I>Cz</I> you may get a blank image. Internally, <I>Cx</I>,
<I>Cy</I>, and <I>Cz</I> are converted into a point in simulation space. If
<I>flag</I> is set to "s" for static, then this conversion is done once, at
the time the dump command is issued. If <I>flag</I> is set to "d" for
dynamic then the conversion is performed every time a new image is
created. If the box size or shape is changing, this will adjust the
center point in simulation space.
</P>
<P>The <I>up</I> keyword determines what direction in simulation space will be
"up" in the image. Internally it is stored as a vector that is in the
plane perpendicular to the view vector implied by the <I>theta</I> and
<I>pni</I> settings, and which is in the plane defined by the view vector
and user-specified up vector. Thus this internal vector is computed
from the user-specified <I>up</I> vector as
</P>
<PRE>up_internal = view cross (up cross view)
</PRE>
<P>This means the only restriction on the specified <I>up</I> vector is that
it cannot be parallel to the <I>view</I> vector, implied by the <I>theta</I> and
<I>phi</I> settings.
</P>
<P>The <I>zoom</I> keyword scales the size of the simulation box as it appears
in the image. The default <I>factor</I> setting of 1 should display an
image mostly filled by the atoms in the simulation box. A <I>factor</I> >
1 will make the simulation box larger; a <I>factor</I> < 1 will make it
smaller.
</P>
<P>The <I>persp</I> keyword how much depth perspective is present in the
image. Depth persepctive makes lines that are parallel in simulation
space appear non-parallel in the image. A <I>factor</I> setting of 0.0
means that parallel lines will meet at infininty (1.0/factor), which
is an orthographic rendering with no persepctive. A <I>factor</I> setting
between 0.0 and 1.0 will introduce more perspective. A <I>factor</I> > 1
will create a highly skewed image with a large amount of perspective.
</P>
<P>The <I>dynamic</I> keyword
determines the color and thickness of bonds
rendered in the image.
</P>
<HR>
<P>The <I>box</I> keyword determines how the simulation box boundaries are
rendered as thin cylinders in the image. If <I>no</I> is set, then the box
boundaries are not drawn and the <I>diam</I> setting is ignored. If <I>yes</I>
is set, the 12 edges of the box are drawn, with a diameter that is a
fraction of the shortest box lenght in x, y, or z. The color of the
box boundaires can be set with the <A HREF = "dump_modify.html">dump_modify
boxcolor</A> command.
</P>
<P>The <I>axes</I> keyword determines how the coordinate axes are rendered as
thin cylinders in the image. If <I>no</I> is set, then the axes are not
drawn and the <I>length</I> and <I>diam</I> settings are ignored. If <I>yes</I> is
set, 3 thin cylinders are drawn to represent the x,y,z axes in colors
red,green/blue. The origin of these cylinders will be offset
from the lower left corner of the box by 10%. The <I>length</I> setting
determines how long the cylinders will be. The <I>diam</I> setting
determines their thickness.
</P>
<HR>
<P>The <I>shiny</I> keyword determines how shiny the objects rendered in the
image will appear. This must be a value 0.0 <= S <= 1.0, where S = 1
is a highly-reflective surface and S = 0 is a rough non-shiny surface.
</P>
<P>The <I>ssao</I> keyword turns on/off a screen space ambient occlusion
(SSAO) model for depth shading. If <I>yes</I> is set, then atoms further
away from the viewer are darkened, which is perceived as depth by the
viewer. The calculation of this effect can increase the cost of
computing the image by roughly 2x. If <I>no</I> is set, the depth shading
is not performed.
</P>
<HR>
<P>A series of JPG or PPM images can be converted into a movie file and
then played as a movie using commonly available tools.
</P>
<P>Convert JPG or PPM files into an animated GIF or MPEG or other movie
file:
</P>
<UL><LI>a) Use the ImageMagick convert program.
<PRE>% convert *.jpg foo.gif
% convert *.jpg foo.mpg
</PRE>
<LI>b) Use QuickTime.
<P>Select "Open Image Sequence" under the File menu
Load the images into QuickTime
Select "Export" under the File menu
Save the movie as a QuickTime movie (*.mov) or in another format
</P>
<LI>c) Windows-based tool.
</UL>
<P>If someone tells us how to do this a common Windows-based tool, we'll
post the instructions here.
</P>
<P>Play the movie:
</P>
<UL><LI>a) Use your browser to view an animated GIF movie.
<P>Select "Open File" under the File menu
Load the animated GIF file
</P>
<LI>b) Use the freely available mplayer tool to view an MPEG movie.
<PRE>% mplayer foo.mpg
</PRE>
<LI>c) Use the <A HREF = "http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</A>
<A HREF = "http://www.sandia.gov/~sjplimp/pizza/doc/animate.html">animate tool</A>,
which works directly on a series of image files.
<PRE>a = animate("foo*.jpg")
</PRE>
<LI>d) QuickTime and other Windows-based media players can
obviously play movie files directly.
</UL>
<HR>
<P>See <A HREF = "Section_modify.html">this section</A> of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>To write JPG images, you must link LAMMPS with a JPEG library - see
the <A HREF = "Section_start.html#2_2_4">Making LAMMPS</A> section of the
documentation for details.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "dump_modify.html">dump_modify</A>, <A HREF = "undump.html">undump</A>
</P>
<P><B>Default:</B>
</P>
<P>The defaults for the keywords are as follows:
</P>
<UL><LI>atom = type 1.0
<LI>bond = none 0.0 (if no bonds in system)
<LI>bond = atom 0.5 (if bonds in system)
<LI>size = 512 512
<LI>view = 60 30 (for 3d)
<LI>view = 0 0 (for 2d)
<LI>center = s 0.5 0.5 0.5
<LI>up = 0 0 1 (for 3d)
<LI>up = 0 1 0 (for 2d)
<LI>zoom = 1.0
<LI>persp = 0.0
<LI>dynamic = no
<LI>box = yes 0.01
<LI>axes = no 0.0 0.0
<LI>shiny = 1.0
<LI>ssao = no
</UL>
</HTML>

417
doc/dump_image.txt Normal file
View File

@ -0,0 +1,417 @@
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
dump image command :h3
[Syntax:]
dump ID group-ID image N file keyword value ... :pre
ID = user-assigned name for the dump :ulb,l
group-ID = ID of the group of atoms to be imaged :l
image = style of dump command (other styles {atom} or {cfg} or {dcd} or {xtc} or {xyz} or {local} or {custom} are discussed on the "dump"_dump.html doc page) :l
N = dump every this many timesteps :l
file = name of file to write image to :l
zero or more keyword/value pairs may be appended :l
keyword = {atom} or {bond} or {size} or {view} or {center} or {up} or {zoom} or {persp} or {box} or {dynamic} or {box} or {axes} or {shiny} or {ssao} :l
{atom} values = color diam
color = {none} or {type} or {element} or atom-attribute
diam = D or {type} or {element} or {radius} or {shape} or atom-attribute
D = numeric value for atom diameter (distance units)
{bond} values = color diam
color = {none} or {atom} or {type}
diam = D or {type}
D = numeric value for bond diameter (distance units)
{size} values = width height
width = width of image in # of pixels
height = height of image in # of pixels
{view} values = theta phi
theta = view angle from +z axis (degrees)
phi = azimuthal view angle (degrees)
theta or phi can be a variable (see below)
{center} values = flag Cx Cy Cz = center point of image (distance units)
flag = "s" for static, "d" for dynamic
Cx,Cy,Cz can be variables (see below)
{up} values = Ux Uy Uz = components of up vector
Ux,Uy,Uz can be variables (see below)
{zoom} value = factor = scale image size by this factor
factor can be a variable (see below)
{persp} value = factor = perspective setting
factor can be a variable (see below)
{box} values = yes/no diam
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
{axes} values = yes/no length diam
yes/no = do or do not draw xyz axes lines next to simulation box
length = length of axes lines as fraction of respective box lengths
diam = diameter of axes lines as fraction of shortest box length
{shiny} value = factor
factor = shinyness of spheres and cylinders from 0.0 to 1.0
{ssao} value = yes/no
yes/no = turn on/off SSAO depth shading :pre
:ule
[Examples:]
dump myDump all image 100 dump.*.jpg :pre
[Description:]
Dump an image (picture) of the atom configuration every N timesteps as
either a JPG or PPM file. A series of such images can easily be
converted into an animated movie of your simulation; see further
details below. Other dump styles store snapshots of atom quantities
in various formats, as discussed on the "dump"_dump.html doc page.
Only atoms in the specified group are rendered in the image. The
"dump_modify region and thresh"_dump_modify.html commands can also
alter what atoms are included in the image.
The filename suffix determines whether a JPG or PPM file is created.
If the suffix is ".jpg" or ".jpeg", then a JPG file is created, else a
PPM file is created. To write out JPG files, you must build LAMMPS
with a JPEG library. See "this section"_Section_start.html#2_2_4 of
the manual for instructions on how to do this.
IMPORTANT NOTE: Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom image may be slightly outside the simulation box.
:line
Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the "dump_modify first"_dump_modify.html command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the "dump_modify every"_dump_modify.html command (not allowed
for {dcd} style).
Dump image filenames must contain a wildcard character "*". If a "*"
character appears in the filename, then one file per snapshot is
written and the "*" character is replaced with the timestep value.
For example, tmp.dump.*.jpg becomes tmp.dump.0.jpg,
tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note that the
"dump_modify pad"_dump_modify.html command can be used to insure all
timestep numbers are the same length (e.g. 00010), which can make it
easier to convert a series of images into a movie in the correct
ordering.
:line
The kewords listed above control how the image is rendered. As listed
below, all of the keywords have defaults, most of which you will
likely not need to change. The "dump modify"_dump_modify.html also
has options specific to the dump image style, particularly for
assigning colors to atoms, bonds, and other image features.
:line
The {atom} keyword determines the color and size of atoms rendered in
the image. If {none} is specified for the color value (with any diam
value), then no atoms are drawn.
The color value can be {type} or {element} or an atom-attribute.
If {type} is specified for the color
value, then the color of each atom is determined by its atom type.
By default the mapping of types to colors is as follows:
type 1 = red
type 2 = green
type 3 = blue
type 4 = yellow
type 5 = aqua
type 6 = cyan :ul
and repeats itself for types > 6. This mapping can be changed by the
"dump_modify acolor"_dump_modify.html command.
If {element} is specified for the color value, then the color of each
atom is determined by which element it is, which in turn is specified
by the element-to-type mapping specified by the "dump_modify element"
command. By default every atom type is C (carbon). Every element has
a color associated with it, which is the same as used by the
"AtomEye"_atomeye visualization package.
:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A)
An atom-attribute can also be used for the color value. Any attribute
listed on the "dump custom"_dump.html doc page can be used, e.g. vx,
fy, q, spin, etc. This includes per-atom quantities calculated by a
"compute"_compute.html, "fix"_fix.html, or "variable"_variable.html.
For example, if "vx" is used as the per-atom attribute, then the color
of the atom will depend on the x-component of its velocity.
The association of a per-atom value with a specific color is
determined by a "color map", which can be specified via the
"dump_modify"_dump_modify.html command. The basic idea is that the
atom-attribute will be within a range of values, and every value
within the range is mapped to a specific color. Depending on how the
color map is defined, that mapping can take place via interpolation so
that a value of -3.2 is halfway between "red" and "blue", or
discretely so that the value of -3.2 is "orange".
The diam value can be a numeric value {D} or {type} or {element} or
{radius} or {shape} or an atom-attribute.
If a numeric value {D} is specified, then all atoms will be drawn with
that diameter, e.g. 1.5, which is in distance units in whatever
"units"_units.html you are using, e.g. Angstroms.
If {type} is specified for the diam value then the color of each atom
is determined by its atom type. By default all types have diameter
1.0. This mapping can be changed by the "dump_modify
adiam"_dump_modify.html command.
If {element} is specified for the diam value, then the diamater of
each atom is determined by which element it is, which in turn is
specified by the element-to-type mapping specified by the "dump_modify
element" command. By default every atom type is C (carbon). Every
element has a diamtere associated with it, which is the same as used
by the "AtomEye"_atomeye visualization package.
If {radius} or {shape} is specified for the diam value then those the
atom style you are using must define those attributes. The radius or
shape of the individual atom is then used to draw it. Currently, only
spherical shapes are allowed. Support for ellipsoids will be added
later.
An atom-attribute can also be used for the diam value. Any attribute
listed on the "dump custom"_dump.html doc page can be used, e.g. vx,
fy, q, spin, etc. This includes per-atom quantities calculated by a
"compute"_compute.html, "fix"_fix.html, or "variable"_variable.html.
For example, if "vx" is used as the per-atom attribute, then the
diameter of the atom will depend on the x-component of its velocity,
which will assumed to be >= 0.0, else the atom will not be drawn.
:line
The {bond} keyword determines the color and thickness or diameter of
bonds rendered in the image. If {none} is specified for the color
value (with any diam value), then no bonds are drawn.
If {atom} is specified for the color value, then the each bond is
drawn in 2 halves, with the color of each half being the color of the
atom at that end of the bond.
If {type} is specified for the color value, then the color of each
bond is determined by its bond type. By default the mapping of types
to colors is as follows:
type 1 = red
type 2 = green
type 3 = blue
type 4 = yellow
type 5 = aqua
type 6 = cyan :ul
and repeats itself for types > 6. This mapping can be changed by the
"dump_modify bcolor"_dump_modify.html command.
The diam value can be a numeric value {D} or {type}.
If a numeric value {D} is specified, then all bond will be drawn with
that diameter, e.g. 1.0, which is in distance units in whatever
"units"_units.html you are using, e.g. Angstroms.
If {type} is specified for the diam value then the color of each bond
is determined by its bond type. By default all types have diameter
0.5. This mapping can be changed by the "dump_modify
bdiam"_dump_modify.html command.
:line
The {size} keyword determines the width and height of the created
image files, in numbers of pixels in each direction.
:line
The {view}, {center}, {up}, {zoom}, and {persp} settings determine how
3d simulation space is mapped to the 2d plane of the image. Basically
they control how the simulation box appears in the image.
All of the {view}, {center}, {up}, {zoom}, and {persp} settings can be
specified as numeric values, whose meaning is explained below. But
any of them can also be specified as an equal-style variable, by using
v_name as the setting, where "name" is the variable name. In this
case the variable will be evaluated on the timestep each image is
created to create a new setting. If the equal-style variable is
time-dependent, this is a means of changing the way the simulation box
appears from image to image, effectively doing a pan or fly-by view of
your simulation.
The {view} keyword determines the viewpoint from which the simulation
box is viewed. The {theta} setting is the vertical angle from the +z
axis, and must be an angle from 0 to 180 degrees. The {phi} setting
is an azimuthal angle around the z axis and can be positive or
negative.
The {center} keyword determines the point in simulation space that
will be at the center of the image. {Cx}, {Cy}, and {Cz} are
speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
the center of the simulation box. These values do not have to be
between 0.0 and 1.0, if you want the simulation box to be offset from
the center of the image. Note, however, that if you choose odd values
for {Cx}, {Cy}, or {Cz} you may get a blank image. Internally, {Cx},
{Cy}, and {Cz} are converted into a point in simulation space. If
{flag} is set to "s" for static, then this conversion is done once, at
the time the dump command is issued. If {flag} is set to "d" for
dynamic then the conversion is performed every time a new image is
created. If the box size or shape is changing, this will adjust the
center point in simulation space.
The {up} keyword determines what direction in simulation space will be
"up" in the image. Internally it is stored as a vector that is in the
plane perpendicular to the view vector implied by the {theta} and
{pni} settings, and which is in the plane defined by the view vector
and user-specified up vector. Thus this internal vector is computed
from the user-specified {up} vector as
up_internal = view cross (up cross view) :pre
This means the only restriction on the specified {up} vector is that
it cannot be parallel to the {view} vector, implied by the {theta} and
{phi} settings.
The {zoom} keyword scales the size of the simulation box as it appears
in the image. The default {factor} setting of 1 should display an
image mostly filled by the atoms in the simulation box. A {factor} >
1 will make the simulation box larger; a {factor} < 1 will make it
smaller.
The {persp} keyword how much depth perspective is present in the
image. Depth persepctive makes lines that are parallel in simulation
space appear non-parallel in the image. A {factor} setting of 0.0
means that parallel lines will meet at infininty (1.0/factor), which
is an orthographic rendering with no persepctive. A {factor} setting
between 0.0 and 1.0 will introduce more perspective. A {factor} > 1
will create a highly skewed image with a large amount of perspective.
The {dynamic} keyword
determines the color and thickness of bonds
rendered in the image.
:line
The {box} keyword determines how the simulation box boundaries are
rendered as thin cylinders in the image. If {no} is set, then the box
boundaries are not drawn and the {diam} setting is ignored. If {yes}
is set, the 12 edges of the box are drawn, with a diameter that is a
fraction of the shortest box lenght in x, y, or z. The color of the
box boundaires can be set with the "dump_modify
boxcolor"_dump_modify.html command.
The {axes} keyword determines how the coordinate axes are rendered as
thin cylinders in the image. If {no} is set, then the axes are not
drawn and the {length} and {diam} settings are ignored. If {yes} is
set, 3 thin cylinders are drawn to represent the x,y,z axes in colors
red,green/blue. The origin of these cylinders will be offset
from the lower left corner of the box by 10%. The {length} setting
determines how long the cylinders will be. The {diam} setting
determines their thickness.
:line
The {shiny} keyword determines how shiny the objects rendered in the
image will appear. This must be a value 0.0 <= S <= 1.0, where S = 1
is a highly-reflective surface and S = 0 is a rough non-shiny surface.
The {ssao} keyword turns on/off a screen space ambient occlusion
(SSAO) model for depth shading. If {yes} is set, then atoms further
away from the viewer are darkened, which is perceived as depth by the
viewer. The calculation of this effect can increase the cost of
computing the image by roughly 2x. If {no} is set, the depth shading
is not performed.
:line
A series of JPG or PPM images can be converted into a movie file and
then played as a movie using commonly available tools.
Convert JPG or PPM files into an animated GIF or MPEG or other movie
file:
a) Use the ImageMagick convert program. :ulb,l
% convert *.jpg foo.gif
% convert *.jpg foo.mpg :pre
b) Use QuickTime. :l
Select "Open Image Sequence" under the File menu
Load the images into QuickTime
Select "Export" under the File menu
Save the movie as a QuickTime movie (*.mov) or in another format
c) Windows-based tool. :ule,l
If someone tells us how to do this a common Windows-based tool, we'll
post the instructions here.
Play the movie:
a) Use your browser to view an animated GIF movie. :ulb,l
Select "Open File" under the File menu
Load the animated GIF file
b) Use the freely available mplayer tool to view an MPEG movie. :l
% mplayer foo.mpg :pre
c) Use the "Pizza.py"_http://www.sandia.gov/~sjplimp/pizza.html
"animate tool"_http://www.sandia.gov/~sjplimp/pizza/doc/animate.html,
which works directly on a series of image files. :l
a = animate("foo*.jpg") :pre
d) QuickTime and other Windows-based media players can
obviously play movie files directly. :ule,l
:line
See "this section"_Section_modify.html of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.
:line
[Restrictions:]
To write JPG images, you must link LAMMPS with a JPEG library - see
the "Making LAMMPS"_Section_start.html#2_2_4 section of the
documentation for details.
[Related commands:]
"dump"_dump.html, "dump_modify"_dump_modify.html, "undump"_undump.html
[Default:]
The defaults for the keywords are as follows:
atom = type 1.0
bond = none 0.0 (if no bonds in system)
bond = atom 0.5 (if bonds in system)
size = 512 512
view = 60 30 (for 3d)
view = 0 0 (for 2d)
center = s 0.5 0.5 0.5
up = 0 0 1 (for 3d)
up = 0 1 0 (for 2d)
zoom = 1.0
persp = 0.0
dynamic = no
box = yes 0.01
axes = no 0.0 0.0
shiny = 1.0
ssao = no :ul

377
doc/dump_modify.html
View File

@ -19,9 +19,48 @@
<LI>one or more keyword/value pairs may be appended
<LI>keyword = <I>append</I> or <I>every</I> or <I>flush</I> or <I>format</I> or <I>image</I> or <I>label</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>
<LI>keyword = <I>acolor</I> or <I>adiam</I> or <I>amap</I> or <I>append</I> or <I>bcolor</I> or <I>bdiam</I> or <I>bgcolor</I> or <I>boxcolor</I> or <I>color</I> or <I>every</I> or <I>flush</I> or <I>format</I> or <I>image</I> or <I>label</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>
<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 N delta 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 = "b" or "c" 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" = sequential)
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 value
entry = color (for sequential style)
color = name of color used for a bin within range
<I>append</I> arg = <I>yes</I> or <I>no</I>
<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>bgcolor</I> arg = color
color = name of color for background
<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>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
@ -60,11 +99,162 @@ dump_modify xtcdump precision 10000
dump_modify 1 every 1000
dump_modify 1 every v_myVar
</PRE>
<P>NOTE: add some image examples
</P>
<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>
<HR>
<P>The <I>acolor</I> keyword applies only to the dump <I>image</I> style. It can
be used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>atom</I>
keyword, when its 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 colorname 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 applies only to the dump <I>image</I> style. It can be
used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>atom</I>
keyword, when its diam 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> you are using, e.g. Angstroms.
</P>
<HR>
<P>The <I>amap</I> keyword applies only to the dump <I>image</I> style. It 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. There are other options for the mapping mechanism, all of
which are explained on the <A HREF = "dump_modify.html">dump_modify</A> doc page.
</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 will the lower and/or
upper bound will be calculated each time an image is drawn.
</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 is only specified if the style is sequential. 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 colorname 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 hte 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, including sub-ranges of
values that 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>
<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 files. If specified as <I>yes</I>, then dump snapshots are
@ -76,14 +266,73 @@ 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>
<P>The <I>element</I> keyword applies only to the the dump <I>cfg</I> style. It
associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
that the <A HREF = "http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</A>
visualization package can render atoms with the appropriate size and
color. 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.
<HR>
<P>The <I>bcolor</I> keyword applies only to the dump <I>image</I> style. It 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 colorname 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 applies only to the dump <I>image</I> style. It 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>bgcolor</I> keyword applies only to the dump <I>image</I> style. It sets
the background color of each image. The color name can be any of the
140 pre-defined colors (see below) or a colorname defined by the
dump_modify color option.
</P>
<HR>
<P>The <I>boxcolor</I> keyword applies only to the dump <I>image</I> style. It
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 colorname defined by the dump_modify color option.
</P>
<HR>
<P>The <I>element</I> keyword applies only to the the dump <I>cfg</I> and <I>image</I>
styles. It associates element names (e.g. H, C, Fe) with LAMMPS atom
types. In the case of dump <I>cfg</I>, it 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. 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>
<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
@ -109,6 +358,8 @@ write snapshots at timesteps 0,10,20,30,100,200,300,1000,2000,etc:
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes
</PRE>
<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
@ -117,6 +368,8 @@ 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
@ -133,6 +386,8 @@ 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>
<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
@ -143,6 +398,8 @@ 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 informatoin, such as bond or angle topology
to a dump file, it will use the specified <I>label</I> to format
@ -154,6 +411,8 @@ ITEM: ENTRIES ...
<P>The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
</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
@ -164,19 +423,25 @@ 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>
<P>The <I>region</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I>
styles. If specified, only atoms in the region will be written to the
dump file. 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.
<HR>
<P>The <I>region</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
<I>image</I> styles. If specified, only atoms in the region will be
written to the dump file or included in the image. 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
@ -184,6 +449,8 @@ value of <I>yes</I> means atom coords are written in normalized units from
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
@ -201,17 +468,22 @@ the output file correctly.
file output requires extra overhead in terms of CPU and communication
cost, as well as memory, versus unsorted output.
</P>
<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I> and <I>cfg</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. 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. 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.
<HR>
<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
<I>image</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. 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
@ -220,21 +492,29 @@ 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>
<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "dump.html">dump</A>, <A HREF = "undump.html">undump</A>
<P><A HREF = "dump.html">dump</A>, <A HREF = "dump_image.html">dump image</A>, <A HREF = "undump.html">undump</A>
</P>
<P><B>Default:</B>
</P>
<P>The option defaults are
</P>
<UL><LI>append = no
<UL><LI>acolor = * red/green/blue/yellow/aqua/cyan
<LI>adiam = * 1.0
<LI>amap = min max cf 2 0.0 blue 1.0 red
<LI>append = no
<LI>bgcolor = black
<LI>boxcolor = yellow
<LI>color = 140 color names are pre-defined as listed below
<LI>element = "C" for every atom type
<LI>every = whatever it was set to via the <A HREF = "dump.html">dump</A> command
<LI>first = no
<LI>flush = yes (except for the dump <I>xtc</I> style)
<LI>flush = yes
<LI>format = %d and %g for each integer or floating point value
<LI>image = no
<LI>label = ENTRIES
@ -247,4 +527,43 @@ box size stored with the snapshot.
<LI>thresh = none
<LI>unwrap = no
</UL>
<HR>
<P>These are the 140 colors that LAMMPS pre-defines for use with the
<A HREF = "dump_image.html">dump image</A> and dump_modify commands. Additional
colors can be defined with the dump_modify color command. The 3
numbers listed for each name are the RGB (red/green/blue) values.
Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
</P>
<DIV ALIGN=center><TABLE BORDER=1 >
<TR><TD >aliceblue = 240, 248, 255 </TD><TD >antiquewhite = 250, 235, 215 </TD><TD >aqua = 0, 255, 255 </TD><TD >aquamarine = 127, 255, 212 </TD><TD >azure = 240, 255, 255 </TD></TR>
<TR><TD >beige = 245, 245, 220 </TD><TD >bisque = 255, 228, 196 </TD><TD >black = 0, 0, 0 </TD><TD >blanchedalmond = 255, 255, 205 </TD><TD >blue = 0, 0, 255 </TD></TR>
<TR><TD >blueviolet = 138, 43, 226 </TD><TD >brown = 165, 42, 42 </TD><TD >burlywood = 222, 184, 135 </TD><TD >cadetblue = 95, 158, 160 </TD><TD >chartreuse = 127, 255, 0 </TD></TR>
<TR><TD >chocolate = 210, 105, 30 </TD><TD >coral = 255, 127, 80 </TD><TD >cornflowerblue = 100, 149, 237 </TD><TD >cornsilk = 255, 248, 220 </TD><TD >crimson = 220, 20, 60 </TD></TR>
<TR><TD >cyan = 0, 255, 255 </TD><TD >darkblue = 0, 0, 139 </TD><TD >darkcyan = 0, 139, 139 </TD><TD >darkgoldenrod = 184, 134, 11 </TD><TD >darkgray = 169, 169, 169 </TD></TR>
<TR><TD >darkgreen = 0, 100, 0 </TD><TD >darkkhaki = 189, 183, 107 </TD><TD >darkmagenta = 139, 0, 139 </TD><TD >darkolivegreen = 85, 107, 47 </TD><TD >darkorange = 255, 140, 0 </TD></TR>
<TR><TD >darkorchid = 153, 50, 204 </TD><TD >darkred = 139, 0, 0 </TD><TD >darksalmon = 233, 150, 122 </TD><TD >darkseagreen = 143, 188, 143 </TD><TD >darkslateblue = 72, 61, 139 </TD></TR>
<TR><TD >darkslategray = 47, 79, 79 </TD><TD >darkturquoise = 0, 206, 209 </TD><TD >darkviolet = 148, 0, 211 </TD><TD >deeppink = 255, 20, 147 </TD><TD >deepskyblue = 0, 191, 255 </TD></TR>
<TR><TD >dimgray = 105, 105, 105 </TD><TD >dodgerblue = 30, 144, 255 </TD><TD >firebrick = 178, 34, 34 </TD><TD >floralwhite = 255, 250, 240 </TD><TD >forestgreen = 34, 139, 34 </TD></TR>
<TR><TD >fuchsia = 255, 0, 255 </TD><TD >gainsboro = 220, 220, 220 </TD><TD >ghostwhite = 248, 248, 255 </TD><TD >gold = 255, 215, 0 </TD><TD >goldenrod = 218, 165, 32 </TD></TR>
<TR><TD >gray = 128, 128, 128 </TD><TD >green = 0, 128, 0 </TD><TD >greenyellow = 173, 255, 47 </TD><TD >honeydew = 240, 255, 240 </TD><TD >hotpink = 255, 105, 180 </TD></TR>
<TR><TD >indianred = 205, 92, 92 </TD><TD >indigo = 75, 0, 130 </TD><TD >ivory = 255, 240, 240 </TD><TD >khaki = 240, 230, 140 </TD><TD >lavender = 230, 230, 250 </TD></TR>
<TR><TD >lavenderblush = 255, 240, 245 </TD><TD >lawngreen = 124, 252, 0 </TD><TD >lemonchiffon = 255, 250, 205 </TD><TD >lightblue = 173, 216, 230 </TD><TD >lightcoral = 240, 128, 128 </TD></TR>
<TR><TD >lightcyan = 224, 255, 255 </TD><TD >lightgoldenrodyellow = 250, 250, 210 </TD><TD >lightgreen = 144, 238, 144 </TD><TD >lightgrey = 211, 211, 211 </TD><TD >lightpink = 255, 182, 193 </TD></TR>
<TR><TD >lightsalmon = 255, 160, 122 </TD><TD >lightseagreen = 32, 178, 170 </TD><TD >lightskyblue = 135, 206, 250 </TD><TD >lightslategray = 119, 136, 153 </TD><TD >lightsteelblue = 176, 196, 222 </TD></TR>
<TR><TD >lightyellow = 255, 255, 224 </TD><TD >lime = 0, 255, 0 </TD><TD >limegreen = 50, 205, 50 </TD><TD >linen = 250, 240, 230 </TD><TD >magenta = 255, 0, 255 </TD></TR>
<TR><TD >maroon = 128, 0, 0 </TD><TD >mediumaquamarine = 102, 205, 170 </TD><TD >mediumblue = 0, 0, 205 </TD><TD >mediumorchid = 186, 85, 211 </TD><TD >mediumpurple = 147, 112, 219 </TD></TR>
<TR><TD >mediumseagreen = 60, 179, 113 </TD><TD >mediumslateblue = 123, 104, 238 </TD><TD >mediumspringgreen = 0, 250, 154 </TD><TD >mediumturquoise = 72, 209, 204 </TD><TD >mediumvioletred = 199, 21, 133 </TD></TR>
<TR><TD >midnightblue = 25, 25, 112 </TD><TD >mintcream = 245, 255, 250 </TD><TD >mistyrose = 255, 228, 225 </TD><TD >moccasin = 255, 228, 181 </TD><TD >navajowhite = 255, 222, 173 </TD></TR>
<TR><TD >navy = 0, 0, 128 </TD><TD >oldlace = 253, 245, 230 </TD><TD >olive = 128, 128, 0 </TD><TD >olivedrab = 107, 142, 35 </TD><TD >orange = 255, 165, 0 </TD></TR>
<TR><TD >orangered = 255, 69, 0 </TD><TD >orchid = 218, 112, 214 </TD><TD >palegoldenrod = 238, 232, 170 </TD><TD >palegreen = 152, 251, 152 </TD><TD >paleturquoise = 175, 238, 238 </TD></TR>
<TR><TD >palevioletred = 219, 112, 147 </TD><TD >papayawhip = 255, 239, 213 </TD><TD >peachpuff = 255, 239, 213 </TD><TD >peru = 205, 133, 63 </TD><TD >pink = 255, 192, 203 </TD></TR>
<TR><TD >plum = 221, 160, 221 </TD><TD >powderblue = 176, 224, 230 </TD><TD >purple = 128, 0, 128 </TD><TD >red = 255, 0, 0 </TD><TD >rosybrown = 188, 143, 143 </TD></TR>
<TR><TD >royalblue = 65, 105, 225 </TD><TD >saddlebrown = 139, 69, 19 </TD><TD >salmon = 250, 128, 114 </TD><TD >sandybrown = 244, 164, 96 </TD><TD >seagreen = 46, 139, 87 </TD></TR>
<TR><TD >seashell = 255, 245, 238 </TD><TD >sienna = 160, 82, 45 </TD><TD >silver = 192, 192, 192 </TD><TD >skyblue = 135, 206, 235 </TD><TD >slateblue = 106, 90, 205 </TD></TR>
<TR><TD >slategray = 112, 128, 144 </TD><TD >snow = 255, 250, 250 </TD><TD >springgreen = 0, 255, 127 </TD><TD >steelblue = 70, 130, 180 </TD><TD >tan = 210, 180, 140 </TD></TR>
<TR><TD >teal = 0, 128, 128 </TD><TD >thistle = 216, 191, 216 </TD><TD >tomato = 253, 99, 71 </TD><TD >turquoise = 64, 224, 208 </TD><TD >violet = 238, 130, 238 </TD></TR>
<TR><TD >wheat = 245, 222, 179 </TD><TD >white = 255, 255, 255 </TD><TD >whitesmoke = 245, 245, 245 </TD><TD >yellow = 255, 255, 0 </TD><TD >yellowgreen = 154, 205, 50
</TD></TR></TABLE></DIV>
</HTML>

483
doc/dump_modify.txt
View File

@ -14,8 +14,47 @@ dump_modify dump-ID keyword values ... :pre
dump-ID = ID of dump to modify :ulb,l
one or more keyword/value pairs may be appended :l
keyword = {append} or {every} or {flush} or {format} or {image} or {label} or {precision} or {region} or {scale} or {sort} or {thresh} or {unwrap} :l
keyword = {acolor} or {adiam} or {amap} or {append} or {bcolor} or {bdiam} or {bgcolor} or {boxcolor} or {color} or {every} or {flush} or {format} or {image} or {label} or {precision} or {region} or {scale} or {sort} or {thresh} or {unwrap} :l
{acolor} args = type color
type = atom type or range of types (see below)
color = name of color or color1/color2/...
{adiam} args = type diam
type = atom type or range of types (see below)
diam = diameter of atoms of that type (distance units)
{amap} args = lo hi style N delta entry1 entry2 ... entryN
lo = number or {min} = lower bound of range of color map
hi = number or {max} = upper bound of range of color map
style = 2 letters = "b" or "c" 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" = sequential)
binsize = range is divided into bins of this width
N = # of subsequent entries
entry = value color (for continuous style)
value = number or {min} or {max} = single value within range
color = name of color used for that value
entry = lo hi color (for discrete style)
lo/hi = number or {min} or {max} = lower/upper bound of subset of range
color = name of color used for that value
entry = color (for sequential style)
color = name of color used for a bin within range
{append} arg = {yes} or {no}
{bcolor} args = type color
type = bond type or range of types (see below)
color = name of color or color1/color2/...
{bdiam} args = type diam
type = bond type or range of types (see below)
diam = diameter of bonds of that type (distance units)
{bgcolor} arg = color
color = name of color for background
{boxcolor} arg = color
color = name of color for box lines
{color} args = name R G B
name = name of color
R,G,B = red/green/blue numeric values from 0.0 to 1.0
{element} args = E1 E2 ... EN, where N = # of atom types
E1,...,EN = element name, e.g. C or Fe or Ga
{every} arg = N
@ -53,11 +92,162 @@ dump_modify xtcdump precision 10000
dump_modify 1 every 1000
dump_modify 1 every v_myVar :pre
NOTE: add some image examples
[Description:]
Modify the parameters of a previously defined dump command. Not all
parameters are relevant to all dump styles.
:line
The {acolor} keyword applies only to the dump {image} style. It can
be used with the "dump image"_dump_image.html command, with its {atom}
keyword, when its color setting is {type}, to set the color that atoms
of each type will be drawn in the image.
The specified {type} 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 {type} 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).
The specified {color} can be a single color which is any of the 140
pre-defined colors (see below) or a colorname 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.
:line
The {adiam} keyword applies only to the dump {image} style. It can be
used with the "dump image"_dump_image.html command, with its {atom}
keyword, when its diam setting is {type}, to set the size that atoms
of each type will be drawn in the image. The specified {type} should
be an integer from 1 to Ntypes. As with the {acolor} keyword, a
wildcard asterisk can be used as part of the {type} argument to
specify a range of atomt types. The specified {diam} is the size in
whatever distance "units"_units.html you are using, e.g. Angstroms.
:line
The {amap} keyword applies only to the dump {image} style. It can be
used with the "dump image"_dump_image.html command, with its {atom}
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.
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. There are other options for the mapping mechanism, all of
which are explained on the "dump_modify"_dump_modify.html doc page.
There are many possible options for the color map, enabled by the
{amap} keyword. Here are the details.
The {lo} and {hi} settings determine the range of values allowed for
the atom attribute. If numeric values are used for {lo} and/or {hi},
then values that are lower/higher than that value are set to the
value. I.e. the range is static. If {lo} is specified as {min} or
{hi} as {max} then the range is dynamic, and will the lower and/or
upper bound will be calculated each time an image is drawn.
The {style} 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.
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.
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.
The {delta} setting is only specified if the style is sequential. 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 {delta} 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.
The {N} 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 {color} setting can be any of the 140
pre-defined colors (see below) or a colorname defined by the
dump_modify color option.
For continuous color maps, each entry has a {value} and a {color}.
The {value} is either a number within the range of values or {min} or
{max}. The {value} of the first entry must be {min} and the {value}
of hte last entry must be {max}. 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.
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".
For discrete color maps, each entry has a {lo} and {hi} value and a
{color}. The {lo} and {hi} settings are either numbers within the
range of values or {lo} can be {min} or {hi} can be {max}. The {lo}
and {hi} settings of the last entry must be {min} and {max}. Other
entries can have any {lo} and {hi} values, including sub-ranges of
values that overlap. Note that numeric {lo} and {hi} 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.
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 {lo} <= X <=
{hi}, 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.
For sequential color maps, each entry has only a {color}. 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 {binsize}. 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.
:line
The {append} keyword applies to all dump styles except {cfg} and {xtc}
and {dcd}. It also applies only to text output files, not to binary
or gzipped files. If specified as {yes}, then dump snapshots are
@ -69,13 +259,72 @@ before the first command that causes dump snapshots to be output,
e.g. a "run"_run.html or "minimize"_minimize.html command. Once the
dump file has been opened, this keyword has no further effect.
The {element} keyword applies only to the the dump {cfg} style. It
associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
that the "AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A
visualization package can render atoms with the appropriate size and
color. 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.
:line
The {bcolor} keyword applies only to the dump {image} style. It can
be used with the "dump image"_dump_image.html command, with its {bond}
keyword, when its color setting is {type}, to set the color that bonds
of each type will be drawn in the image.
The specified {type} 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 {type} 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).
The specified {color} can be a single color which is any of the 140
pre-defined colors (see below) or a colorname 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.
:line
The {bdiam} keyword applies only to the dump {image} style. It can be
used with the "dump image"_dump_image.html command, with its {bond}
keyword, when its diam setting is {type}, to set the diameter that
bonds of each type will be drawn in the image. The specified {type}
should be an integer from 1 to Nbondtypes. As with the {bcolor}
keyword, a wildcard asterisk can be used as part of the {type}
argument to specify a range of bond types. The specified {diam} is
the size in whatever distance "units"_units.html you are using,
e.g. Angstroms.
:line
The {bgcolor} keyword applies only to the dump {image} style. It sets
the background color of each image. The color name can be any of the
140 pre-defined colors (see below) or a colorname defined by the
dump_modify color option.
:line
The {boxcolor} keyword applies only to the dump {image} style. It
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 colorname defined by the dump_modify color option.
:line
The {element} keyword applies only to the the dump {cfg} and {image}
styles. It associates element names (e.g. H, C, Fe) with LAMMPS atom
types. In the case of dump {cfg}, it allows the "AtomEye"_atomeye
visualization package to read the dump file and render atoms with the
appropriate size and color. In the case of dump {image}, the output
images will follow the same "AtomEye"_atomeye 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.
:link(atomeye,http://mt.seas.upenn.edu/Archive/Graphics/A)
:line
The {every} keyword changes the dump frequency originally specified by
the "dump"_dump.html command to a new value. The every keyword can be
@ -102,6 +351,8 @@ variable s equal logfreq(10,3,10)
dump 1 all atom 100 tmp.dump
dump_modify 1 every v_s first yes :pre
:line
The {first} 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
@ -110,6 +361,8 @@ if this is not the case, a dump snapshot will only be written if the
setting of this keyword is {yes}. If it is {no}, which is the
default, then it will not be written.
:line
The {flush} 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
@ -126,6 +379,8 @@ 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.
:line
The {image} keyword applies only to the dump {atom} style. If the
image value is {yes}, 3 flags are appended to each atom's coords which
are the absolute box image of the atom in each dimension. For
@ -136,6 +391,8 @@ current coordinate. Note that for dump style {custom} these various
values can be printed in the dump file by using the appropriate atom
attributes in the dump command itself.
:line
The {label} keyword applies only to the dump {local} style. When
it writes local informatoin, such as bond or angle topology
to a dump file, it will use the specified {label} to format
@ -147,6 +404,8 @@ ITEM: ENTRIES ... :pre
The word "ENTRIES" will be replaced with the string specified,
e.g. BONDS or ANGLES.
:line
The {pad} keyword only applies when the dump filename is specified
with a wildcard "*" character which becomes the timestep. If {pad} is
0, which is the default, the timestep is converted into a string of
@ -157,18 +416,24 @@ yield 0000100, 0012000, 2000000. This can be useful so that
post-processing programs can easily read the files in ascending
timestep order.
:line
The {precision} keyword only applies to the dump {xtc} 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.
The {region} keyword only applies to the dump {custom} and {cfg}
styles. If specified, only atoms in the region will be written to the
dump file. Only one region can be applied as a filter (the last one
specified). See the "region"_region.html 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.
:line
The {region} keyword only applies to the dump {custom} and {cfg} and
{image} styles. If specified, only atoms in the region will be
written to the dump file or included in the image. Only one region
can be applied as a filter (the last one specified). See the
"region"_region.html 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.
:line
The {scale} keyword applies only to the dump {atom} style. A scale
value of {yes} means atom coords are written in normalized units from
@ -177,6 +442,8 @@ value of {yes} means atom coords are written in normalized units from
value of {no} means they are written in absolute distance units
(e.g. Angstroms or sigma).
:line
The {sort} keyword determines whether lines of per-atom output in a
snapshot are sorted or not. A sort value of {off} means they will
typically be written in indeterminate order, either in serial or
@ -194,16 +461,21 @@ 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.
The {thresh} keyword only applies to the dump {custom} and {cfg}
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. The possible attributes that can be tested for are the
same as those that can be specified in the "dump custom"_dump.html
command. 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.
:line
The {thresh} keyword only applies to the dump {custom} and {cfg} and
{image} 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 "dump custom"_dump.html command. 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.
:line
The {unwrap} keyword only applies to the dump {dcd} and {xtc} styles.
If set to {yes}, coordinates will be written "unwrapped" by the image
@ -213,21 +485,29 @@ 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.
:line
[Restrictions:] none
[Related commands:]
"dump"_dump.html, "undump"_undump.html
"dump"_dump.html, "dump image"_dump_image.html, "undump"_undump.html
[Default:]
The option defaults are
acolor = * red/green/blue/yellow/aqua/cyan
adiam = * 1.0
amap = min max cf 2 0.0 blue 1.0 red
append = no
bgcolor = black
boxcolor = yellow
color = 140 color names are pre-defined as listed below
element = "C" for every atom type
every = whatever it was set to via the "dump"_dump.html command
first = no
flush = yes (except for the dump {xtc} style)
flush = yes
format = %d and %g for each integer or floating point value
image = no
label = ENTRIES
@ -239,3 +519,152 @@ sort = off for dump styles {atom}, {custom}, {cfg}, and {local}
sort = id for dump styles {dcd}, {xtc}, and {xyz}
thresh = none
unwrap = no :ul
:line
These are the 140 colors that LAMMPS pre-defines for use with the
"dump image"_dump_image.html and dump_modify commands. Additional
colors can be defined with the dump_modify color command. The 3
numbers listed for each name are the RGB (red/green/blue) values.
Divide each value by 255 to get the equivalent 0.0 to 1.0 value.
aliceblue = 240, 248, 255 |
antiquewhite = 250, 235, 215 |
aqua = 0, 255, 255 |
aquamarine = 127, 255, 212 |
azure = 240, 255, 255 |
beige = 245, 245, 220 |
bisque = 255, 228, 196 |
black = 0, 0, 0 |
blanchedalmond = 255, 255, 205 |
blue = 0, 0, 255 |
blueviolet = 138, 43, 226 |
brown = 165, 42, 42 |
burlywood = 222, 184, 135 |
cadetblue = 95, 158, 160 |
chartreuse = 127, 255, 0 |
chocolate = 210, 105, 30 |
coral = 255, 127, 80 |
cornflowerblue = 100, 149, 237 |
cornsilk = 255, 248, 220 |
crimson = 220, 20, 60 |
cyan = 0, 255, 255 |
darkblue = 0, 0, 139 |
darkcyan = 0, 139, 139 |
darkgoldenrod = 184, 134, 11 |
darkgray = 169, 169, 169 |
darkgreen = 0, 100, 0 |
darkkhaki = 189, 183, 107 |
darkmagenta = 139, 0, 139 |
darkolivegreen = 85, 107, 47 |
darkorange = 255, 140, 0 |
darkorchid = 153, 50, 204 |
darkred = 139, 0, 0 |
darksalmon = 233, 150, 122 |
darkseagreen = 143, 188, 143 |
darkslateblue = 72, 61, 139 |
darkslategray = 47, 79, 79 |
darkturquoise = 0, 206, 209 |
darkviolet = 148, 0, 211 |
deeppink = 255, 20, 147 |
deepskyblue = 0, 191, 255 |
dimgray = 105, 105, 105 |
dodgerblue = 30, 144, 255 |
firebrick = 178, 34, 34 |
floralwhite = 255, 250, 240 |
forestgreen = 34, 139, 34 |
fuchsia = 255, 0, 255 |
gainsboro = 220, 220, 220 |
ghostwhite = 248, 248, 255 |
gold = 255, 215, 0 |
goldenrod = 218, 165, 32 |
gray = 128, 128, 128 |
green = 0, 128, 0 |
greenyellow = 173, 255, 47 |
honeydew = 240, 255, 240 |
hotpink = 255, 105, 180 |
indianred = 205, 92, 92 |
indigo = 75, 0, 130 |
ivory = 255, 240, 240 |
khaki = 240, 230, 140 |
lavender = 230, 230, 250 |
lavenderblush = 255, 240, 245 |
lawngreen = 124, 252, 0 |
lemonchiffon = 255, 250, 205 |
lightblue = 173, 216, 230 |
lightcoral = 240, 128, 128 |
lightcyan = 224, 255, 255 |
lightgoldenrodyellow = 250, 250, 210 |
lightgreen = 144, 238, 144 |
lightgrey = 211, 211, 211 |
lightpink = 255, 182, 193 |
lightsalmon = 255, 160, 122 |
lightseagreen = 32, 178, 170 |
lightskyblue = 135, 206, 250 |
lightslategray = 119, 136, 153 |
lightsteelblue = 176, 196, 222 |
lightyellow = 255, 255, 224 |
lime = 0, 255, 0 |
limegreen = 50, 205, 50 |
linen = 250, 240, 230 |
magenta = 255, 0, 255 |
maroon = 128, 0, 0 |
mediumaquamarine = 102, 205, 170 |
mediumblue = 0, 0, 205 |
mediumorchid = 186, 85, 211 |
mediumpurple = 147, 112, 219 |
mediumseagreen = 60, 179, 113 |
mediumslateblue = 123, 104, 238 |
mediumspringgreen = 0, 250, 154 |
mediumturquoise = 72, 209, 204 |
mediumvioletred = 199, 21, 133 |
midnightblue = 25, 25, 112 |
mintcream = 245, 255, 250 |
mistyrose = 255, 228, 225 |
moccasin = 255, 228, 181 |
navajowhite = 255, 222, 173 |
navy = 0, 0, 128 |
oldlace = 253, 245, 230 |
olive = 128, 128, 0 |
olivedrab = 107, 142, 35 |
orange = 255, 165, 0 |
orangered = 255, 69, 0 |
orchid = 218, 112, 214 |
palegoldenrod = 238, 232, 170 |
palegreen = 152, 251, 152 |
paleturquoise = 175, 238, 238 |
palevioletred = 219, 112, 147 |
papayawhip = 255, 239, 213 |
peachpuff = 255, 239, 213 |
peru = 205, 133, 63 |
pink = 255, 192, 203 |
plum = 221, 160, 221 |
powderblue = 176, 224, 230 |
purple = 128, 0, 128 |
red = 255, 0, 0 |
rosybrown = 188, 143, 143 |
royalblue = 65, 105, 225 |
saddlebrown = 139, 69, 19 |
salmon = 250, 128, 114 |
sandybrown = 244, 164, 96 |
seagreen = 46, 139, 87 |
seashell = 255, 245, 238 |
sienna = 160, 82, 45 |
silver = 192, 192, 192 |
skyblue = 135, 206, 235 |
slateblue = 106, 90, 205 |
slategray = 112, 128, 144 |
snow = 255, 250, 250 |
springgreen = 0, 255, 127 |
steelblue = 70, 130, 180 |
tan = 210, 180, 140 |
teal = 0, 128, 128 |
thistle = 216, 191, 216 |
tomato = 253, 99, 71 |
turquoise = 64, 224, 208 |
violet = 238, 130, 238 |
wheat = 245, 222, 179 |
white = 255, 255, 255 |
whitesmoke = 245, 245, 245 |
yellow = 255, 255, 0 |
yellowgreen = 154, 205, 50 :tb(c=5,s=|)

6
doc/fix_srd.html
View File

@ -343,7 +343,7 @@ beginning of the run.
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> none
<P><B>Restrictions:</B>
</P>
<P>This command can only be used if LAMMPS was built with the "srd"
package. See the <A HREF = "Section_start.html#2_3">Making LAMMPS</A> section for
@ -370,6 +370,8 @@ search = hgrid, cubic = error 0.01, shift = no, stream = yes.
<P><B>(Petersen)</B> Petersen, Lechman, Plimpton, Grest, in' t Veld, Schunk, J
Chem Phys, 132, 174106 (2010).
</P>
<P>:link(Lechman) <B>(Lechman)</B> Lechman, et al, in preparation (2010).
<A NAME = "Lechman"></A>
<P><B>(Lechman)</B> Lechman, et al, in preparation (2010).
</P>
</HTML>

5
doc/fix_srd.txt
View File

@ -337,7 +337,7 @@ 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:] none
[Restrictions:]
This command can only be used if LAMMPS was built with the "srd"
package. See the "Making LAMMPS"_Section_start.html#2_3 section for
@ -362,4 +362,5 @@ search = hgrid, cubic = error 0.01, shift = no, stream = yes.
[(Petersen)] Petersen, Lechman, Plimpton, Grest, in' t Veld, Schunk, J
Chem Phys, 132, 174106 (2010).
:link(Lechman) [(Lechman)] Lechman, et al, in preparation (2010).
:link(Lechman)
[(Lechman)] Lechman, et al, in preparation (2010).

46
doc/tad.html
View File

@ -180,35 +180,33 @@ files, and restart files.
</P>
<P>Event statistics are printed to the screen and master log.lammps file
each time an event is executed. The quantities are the timestep, CPU
time, global event number <I>N</I>, local event number <I>M</I>,
event status, energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>.
The timestep is the usual LAMMPS
timestep, which corresponds to the high-temperature time at which the
event was detected, in units of timestep. The CPU time is the total
processor time since the start of the TAD run.
The global event number <I>N</I> is a counter
that increments with each executed event. The local event number <I>M</I>
is a counter that resets to zero upon entering each new basin.
The event status is <I>E</I> when an event is executed, and
is <I>D</I> for an event that is detected, while <I>DF</I> is for a detected
event that is also the earliest (first) event at the low temperature.
time, global event number <I>N</I>, local event number <I>M</I>, event status,
energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>. The timestep is
the usual LAMMPS timestep, which corresponds to the high-temperature
time at which the event was detected, in units of timestep. The CPU
time is the total processor time since the start of the TAD run. The
global event number <I>N</I> is a counter that increments with each
executed event. The local event number <I>M</I> is a counter that resets to
zero upon entering each new basin. The event status is <I>E</I> when an
event is executed, and is <I>D</I> for an event that is detected, while
<I>DF</I> is for a detected event that is also the earliest (first) event
at the low temperature.
</P>
<P>The time margin is the ratio of the high temperature time in the current
basin to the stopping time. This last number can be used to judge
whether the stopping time is too short or too long (see above).
<P>The time margin is the ratio of the high temperature time in the
current basin to the stopping time. This last number can be used to
judge whether the stopping time is too short or too long (see above).
</P>
<P><I>t_lo</I> is the low-temperature event time when the current basin was entered,
in units of timestep. del<I>t_lo</I> is the time of each detected
event, measured relative to <I>t_lo</I>. <I>delt_lo</I>
is equal to the high-temperature time since entering the current
basin, scaled by an
<P><I>t_lo</I> is the low-temperature event time when the current basin was
entered, in units of timestep. del<I>t_lo</I> is the time of each detected
event, measured relative to <I>t_lo</I>. <I>delt_lo</I> is equal to the
high-temperature time since entering the current basin, scaled by an
exponential factor that depends on the hi/lo temperature ratio and the
energy barrier for that event.
</P>
<P>On lines for executed events, with status <I>E</I>, the global event number is
incremented by one, and the timestep, local event number,
energy barrier, <I>t_lo</I>, and <I>delt_lo</I> match the last event with status <I>DF</I> in the
immediately preceding block of detected events.
<P>On lines for executed events, with status <I>E</I>, the global event number
is incremented by one, and the timestep, local event number, energy
barrier, <I>t_lo</I>, and <I>delt_lo</I> match the last event with status <I>DF</I>
in the immediately preceding block of detected events.
</P>
<P>The NEB statistics are written to the file specified by the <I>neb_log</I>
keyword. If the keyword value is "none", then no NEB statistics are

46
doc/tad.txt
View File

@ -170,35 +170,33 @@ files, and restart files.
Event statistics are printed to the screen and master log.lammps file
each time an event is executed. The quantities are the timestep, CPU
time, global event number {N}, local event number {M},
event status, energy barrier, time margin, {t_lo} and {delt_lo}.
The timestep is the usual LAMMPS
timestep, which corresponds to the high-temperature time at which the
event was detected, in units of timestep. The CPU time is the total
processor time since the start of the TAD run.
The global event number {N} is a counter
that increments with each executed event. The local event number {M}
is a counter that resets to zero upon entering each new basin.
The event status is {E} when an event is executed, and
is {D} for an event that is detected, while {DF} is for a detected
event that is also the earliest (first) event at the low temperature.
time, global event number {N}, local event number {M}, event status,
energy barrier, time margin, {t_lo} and {delt_lo}. The timestep is
the usual LAMMPS timestep, which corresponds to the high-temperature
time at which the event was detected, in units of timestep. The CPU
time is the total processor time since the start of the TAD run. The
global event number {N} is a counter that increments with each
executed event. The local event number {M} is a counter that resets to
zero upon entering each new basin. The event status is {E} when an
event is executed, and is {D} for an event that is detected, while
{DF} is for a detected event that is also the earliest (first) event
at the low temperature.
The time margin is the ratio of the high temperature time in the current
basin to the stopping time. This last number can be used to judge
whether the stopping time is too short or too long (see above).
The time margin is the ratio of the high temperature time in the
current basin to the stopping time. This last number can be used to
judge whether the stopping time is too short or too long (see above).
{t_lo} is the low-temperature event time when the current basin was entered,
in units of timestep. del{t_lo} is the time of each detected
event, measured relative to {t_lo}. {delt_lo}
is equal to the high-temperature time since entering the current
basin, scaled by an
{t_lo} is the low-temperature event time when the current basin was
entered, in units of timestep. del{t_lo} is the time of each detected
event, measured relative to {t_lo}. {delt_lo} is equal to the
high-temperature time since entering the current basin, scaled by an
exponential factor that depends on the hi/lo temperature ratio and the
energy barrier for that event.
On lines for executed events, with status {E}, the global event number is
incremented by one, and the timestep, local event number,
energy barrier, {t_lo}, and {delt_lo} match the last event with status {DF} in the
immediately preceding block of detected events.
On lines for executed events, with status {E}, the global event number
is incremented by one, and the timestep, local event number, energy
barrier, {t_lo}, and {delt_lo} match the last event with status {DF}
in the immediately preceding block of detected events.
The NEB statistics are written to the file specified by the {neb_log}
keyword. If the keyword value is "none", then no NEB statistics are

2
doc/variable.html
View File

@ -172,7 +172,7 @@ commands before the variable would become exhausted. For example,
<PRE>label loop
variable a loop 5
print "A = $a"
if $a > 2 then "jump in.script break"
if "$a > 2" then "jump in.script break"
next a
jump in.script loop
label break

2
doc/variable.txt
View File

@ -166,7 +166,7 @@ commands before the variable would become exhausted. For example,
label loop
variable a loop 5
print "A = $a"
if $a > 2 then "jump in.script break"
if "$a > 2" then "jump in.script break"
next a
jump in.script loop
label break