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

doc/Section_start.html

@@ -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
+(MPI, FFT, JPEG), etc.  Please read this section carefully.  If you
-comfortable with makefiles, or building codes on a Unix platform, or
+are not comfortable with makefiles, or building codes on a Unix
-running an MPI job on your machine, please find a local expert to help
+platform, or running an MPI job on your machine, please find a local
-you.  Many compiling, linking, and run problems that users are not
+expert to help you.  Many compiling, linking, and run problems that
-really LAMMPS issues - they are peculiar to the user's system,
+users are not really LAMMPS issues - they are peculiar to the user's
-compilers, libraries, etc.  Such questions are better answered by a
+system, compilers, libraries, etc.  Such questions are better answered
-local expert.
+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
+"popen" command.
--DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
+</P>
-solver) on some platforms.  The -DPACK_ARRAY setting is the default.
+<P>Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
-If you use -DLAMMPS_XDR, the build will include XDR compatibility
+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
+or 2.0 or OpenMPI.  MPICH can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
-site</A>.  LAM MPI should also work.  If
+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.
+faster than MPICH or OpenMPI or LAM, so find out how to build and link
-If you use MPICH or LAM, you will have to configure and build it for
+with it.  If you use MPICH or OpenMPI or LAM, you will have to
-your platform.  The MPI configure script should have compiler options
+configure and build it for your platform.  The MPI configure script
-to enable you to use the same compiler you are using for the LAMMPS
+should have compiler options to enable you to use the same compiler
-build, which can avoid problems that can arise when linking LAMMPS to
+you are using for the LAMMPS build, which can avoid problems that can
-the MPI library.
+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

doc/Section_start.txt

@@ -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
+(MPI, FFT, JPEG), etc.  Please read this section carefully.  If you
-comfortable with makefiles, or building codes on a Unix platform, or
+are not comfortable with makefiles, or building codes on a Unix
-running an MPI job on your machine, please find a local expert to help
+platform, or running an MPI job on your machine, please find a local
-you.  Many compiling, linking, and run problems that users are not
+expert to help you.  Many compiling, linking, and run problems that
-really LAMMPS issues - they are peculiar to the user's system,
+users are not really LAMMPS issues - they are peculiar to the user's
-compilers, libraries, etc.  Such questions are better answered by a
+system, compilers, libraries, etc.  Such questions are better answered
-local expert.
+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
+"popen" command.
--DPACK_MEMCPY options can make for faster parallel FFTs (in the PPPM
+
-solver) on some platforms.  The -DPACK_ARRAY setting is the default.
+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
+or 2.0 or OpenMPI.  MPICH can be downloaded from the "Argonne MPI
-site"_http://www-unix.mcs.anl.gov/mpi.  LAM MPI should also work.  If
+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.
+faster than MPICH or OpenMPI or LAM, so find out how to build and link
-If you use MPICH or LAM, you will have to configure and build it for
+with it.  If you use MPICH or OpenMPI or LAM, you will have to
-your platform.  The MPI configure script should have compiler options
+configure and build it for your platform.  The MPI configure script
-to enable you to use the same compiler you are using for the LAMMPS
+should have compiler options to enable you to use the same compiler
-build, which can avoid problems that can arise when linking LAMMPS to
+you are using for the LAMMPS build, which can avoid problems that can
-the MPI library.
+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

doc/compute_pair_local.html

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

doc/compute_pair_local.txt

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

doc/compute_property_local.html

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

doc/compute_property_local.txt

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

doc/compute_rdf.html

@@ -72,19 +72,8 @@ a specific histogram if the following criteria are met:
 <UL><LI>atoms I,J are both in the specified compute group
 <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 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.

doc/compute_rdf.txt

@@ -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 type of the J atom matches jtypeN (one or a range of types) :ul
-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.
 
 It is OK if a particular pairwise distance is included in more than
 one individual histogram, due to the way the {itypeN} and {jtypeN}

doc/dump.html

@@ -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
+timesteps in one of several styles.  The <I>image</I> style is the
-determines the kind of output (text or binary or gzipped, one big file
+exception; it creates a JPG or PPM image file of the atom
-or one per timestep, one big file or one per processor).  Only
+configuration every N timesteps, as discussed on the <A HREF = "dump_image.html">dump
-information for atoms in the specified group is dumped.  The
+image</A> doc page.
-<A HREF = "dump_modify.html">dump_modify</A> command can also alter what atoms are
+</P>
-included.  Not all styles support all these options; see details
+<P>Only information for atoms in the specified group is dumped.  The
-below.
+<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>

doc/dump.txt

@@ -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
@@ -31,7 +34,7 @@ args = list of arguments for a particular style :l
       c_ID\[N\] = Nth column of local array calculated by a compute with ID
       f_ID = local vector calculated by a fix with ID
       f_ID\[N\] = Nth column of local array calculated by a fix with ID :pre
-      
+
   {custom} args = list of atom attributes
     possible attributes = id, mol, type, mass,
 			  x, y, z, xs, ys, zs, xu, yu, zu, ix, iy, iz,
@@ -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
+timesteps in one of several styles.  The {image} style is the
-determines the kind of output (text or binary or gzipped, one big file
+exception; it creates a JPG or PPM image file of the atom
-or one per timestep, one big file or one per processor).  Only
+configuration every N timesteps, as discussed on the "dump
-information for atoms in the specified group is dumped.  The
+image"_dump_image.html doc page.
-"dump_modify"_dump_modify.html command can also alter what atoms are
+
-included.  Not all styles support all these options; see details
+Only information for atoms in the specified group is dumped.  The
-below.
+"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.

doc/dump_image.html

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

doc/dump_image.txt

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

doc/dump_modify.html

@@ -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
+<HR>
-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>
+<P>The <I>bcolor</I> keyword applies only to the dump <I>image</I> style.  It can
-visualization package can render atoms with the appropriate size and
+be used with the <A HREF = "dump_image.html">dump image</A> command, with its <I>bond</I>
-color.  An element name is specified for each atom type (1 to Ntype)
+keyword, when its color setting is <I>type</I>, to set the color that bonds
-in the simulation.  The same element name can be given to multiple
+of each type will be drawn in the image.
-atom types.
 </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>
+<HR>
-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
+<P>The <I>region</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
-specified).  See the <A HREF = "region.html">region</A> command for more details.
+<I>image</I> styles.  If specified, only atoms in the region will be
-Note that a region can be defined as the "inside" or "outside" of a
+written to the dump file or included in the image.  Only one region
-geometric shape, and it can be the "union" or "intersection" of a
+can be applied as a filter (the last one specified).  See the
-series of simpler regions.
+<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>
+<HR>
-styles.  Multiple thresholds can be specified.  Specifying "none"
+
-turns off all threshold criteria.  If thresholds are specified, only
+<P>The <I>thresh</I> keyword only applies to the dump <I>custom</I> and <I>cfg</I> and
-atoms whose attributes meet all the threshold criteria are written to
+<I>image</I> styles.  Multiple thresholds can be specified.  Specifying
-the dump file.  The possible attributes that can be tested for are the
+"none" turns off all threshold criteria.  If thresholds are specified,
-same as those that can be specified in the <A HREF = "dump.html">dump custom</A>
+only atoms whose attributes meet all the threshold criteria are
-command.  Note that different attributes can be output by the dump
+written to the dump file or included in the image.  The possible
-custom command than are used as threshold criteria by the dump_modify
+attributes that can be tested for are the same as those that can be
-command.  E.g. you can output the coordinates and stress of atoms
+specified in the <A HREF = "dump.html">dump custom</A> command.  Note that different
-whose energy is above some threshold.
+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>

doc/dump_modify.txt

@@ -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
+:line
-associates element names (e.g. H, C, Fe) with LAMMPS atom types, so
+
-that the "AtomEye"_http://mt.seas.upenn.edu/Archive/Graphics/A
+The {bcolor} keyword applies only to the dump {image} style.  It can
-visualization package can render atoms with the appropriate size and
+be used with the "dump image"_dump_image.html command, with its {bond}
-color.  An element name is specified for each atom type (1 to Ntype)
+keyword, when its color setting is {type}, to set the color that bonds
-in the simulation.  The same element name can be given to multiple
+of each type will be drawn in the image.
-atom types.
+
+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}
+:line
-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
+The {region} keyword only applies to the dump {custom} and {cfg} and
-specified).  See the "region"_region.html command for more details.
+{image} styles.  If specified, only atoms in the region will be
-Note that a region can be defined as the "inside" or "outside" of a
+written to the dump file or included in the image.  Only one region
-geometric shape, and it can be the "union" or "intersection" of a
+can be applied as a filter (the last one specified).  See the
-series of simpler regions.
+"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}
+:line
-styles.  Multiple thresholds can be specified.  Specifying "none"
+
-turns off all threshold criteria.  If thresholds are specified, only
+The {thresh} keyword only applies to the dump {custom} and {cfg} and
-atoms whose attributes meet all the threshold criteria are written to
+{image} styles.  Multiple thresholds can be specified.  Specifying
-the dump file.  The possible attributes that can be tested for are the
+"none" turns off all threshold criteria.  If thresholds are specified,
-same as those that can be specified in the "dump custom"_dump.html
+only atoms whose attributes meet all the threshold criteria are
-command.  Note that different attributes can be output by the dump
+written to the dump file or included in the image.  The possible
-custom command than are used as threshold criteria by the dump_modify
+attributes that can be tested for are the same as those that can be
-command.  E.g. you can output the coordinates and stress of atoms
+specified in the "dump custom"_dump.html command.  Note that different
-whose energy is above some threshold.
+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=|)

doc/fix_srd.html

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

doc/fix_srd.txt

@@ -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).

doc/tad.html

@@ -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>,
+time, global event number <I>N</I>, local event number <I>M</I>, event status,
-event status, energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>.  
+energy barrier, time margin, <I>t_lo</I> and <I>delt_lo</I>.  The timestep is
-The timestep is the usual LAMMPS
+the usual LAMMPS timestep, which corresponds to the high-temperature
-timestep, which corresponds to the high-temperature time at which the
+time at which the event was detected, in units of timestep.  The CPU
-event was detected, in units of timestep.  The CPU time is the total
+time is the total processor time since the start of the TAD run.  The
-processor time since the start of the TAD run.  
+global event number <I>N</I> is a counter that increments with each
-The global event number <I>N</I> is a counter 
+executed event. The local event number <I>M</I> is a counter that resets to
-that increments with each executed event. The local event number <I>M</I>
+zero upon entering each new basin.  The event status is <I>E</I> when an
-is a counter that resets to zero upon entering each new basin.
+event is executed, and is <I>D</I> for an event that is detected, while
-The event status is <I>E</I> when an event is executed, and 
+<I>DF</I> is for a detected event that is also the earliest (first) event
-is <I>D</I> for an event that is detected, while <I>DF</I> is for a detected
+at the low temperature.
-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
+<P>The time margin is the ratio of the high temperature time in the
-basin to the stopping time. This last number can be used to judge
+current basin to the stopping time. This last number can be used to
-whether the stopping time is too short or too long (see above). 
+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, 
+<P><I>t_lo</I> is the low-temperature event time when the current basin was
-in units of timestep.  del<I>t_lo</I> is the time of each detected 
+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>
+event, measured relative to <I>t_lo</I>.  <I>delt_lo</I> is equal to the
-is equal to the high-temperature time since entering the current
+high-temperature time since entering the current basin, scaled by an
-basin, scaled by an
 exponential factor that depends on the hi/lo temperature ratio and the
-energy barrier for that event.  
+energy barrier for that event.
 </P>
-<P>On lines for executed events, with status <I>E</I>, the global event number is
+<P>On lines for executed events, with status <I>E</I>, the global event number
-incremented by one, and the timestep, local event number, 
+is incremented by one, and the timestep, local event number, energy
-energy barrier, <I>t_lo</I>, and <I>delt_lo</I>  match the last event with status <I>DF</I> in the 
+barrier, <I>t_lo</I>, and <I>delt_lo</I> match the last event with status <I>DF</I>
-immediately preceding block of detected events.
+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

doc/tad.txt

@@ -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},
+time, global event number {N}, local event number {M}, event status,
-event status, energy barrier, time margin, {t_lo} and {delt_lo}.  
+energy barrier, time margin, {t_lo} and {delt_lo}.  The timestep is
-The timestep is the usual LAMMPS
+the usual LAMMPS timestep, which corresponds to the high-temperature
-timestep, which corresponds to the high-temperature time at which the
+time at which the event was detected, in units of timestep.  The CPU
-event was detected, in units of timestep.  The CPU time is the total
+time is the total processor time since the start of the TAD run.  The
-processor time since the start of the TAD run.  
+global event number {N} is a counter that increments with each
-The global event number {N} is a counter 
+executed event. The local event number {M} is a counter that resets to
-that increments with each executed event. The local event number {M}
+zero upon entering each new basin.  The event status is {E} when an
-is a counter that resets to zero upon entering each new basin.
+event is executed, and is {D} for an event that is detected, while
-The event status is {E} when an event is executed, and 
+{DF} is for a detected event that is also the earliest (first) event
-is {D} for an event that is detected, while {DF} is for a detected
+at the low temperature.
-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
+The time margin is the ratio of the high temperature time in the
-basin to the stopping time. This last number can be used to judge
+current basin to the stopping time. This last number can be used to
-whether the stopping time is too short or too long (see above). 
+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, 
+{t_lo} is the low-temperature event time when the current basin was
-in units of timestep.  del{t_lo} is the time of each detected 
+entered, in units of timestep.  del{t_lo} is the time of each detected
-event, measured relative to {t_lo}.  {delt_lo}
+event, measured relative to {t_lo}.  {delt_lo} is equal to the
-is equal to the high-temperature time since entering the current
+high-temperature time since entering the current basin, scaled by an
-basin, scaled by an
 exponential factor that depends on the hi/lo temperature ratio and the
-energy barrier for that event.  
+energy barrier for that event.
 
-On lines for executed events, with status {E}, the global event number is
+On lines for executed events, with status {E}, the global event number
-incremented by one, and the timestep, local event number, 
+is incremented by one, and the timestep, local event number, energy
-energy barrier, {t_lo}, and {delt_lo}  match the last event with status {DF} in the 
+barrier, {t_lo}, and {delt_lo} match the last event with status {DF}
-immediately preceding block of detected events.
+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

doc/variable.html

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

doc/variable.txt

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