diff --git a/doc/Section_start.html b/doc/Section_start.html
index 2d1c658de..00cb165ad 100644
--- a/doc/Section_start.html
+++ b/doc/Section_start.html
@@ -1,682 +1,682 @@
<HTML>
<CENTER><A HREF = "Section_intro.html">Previous Section</A> - <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> - <A HREF = "Section_commands.html">Next Section</A>
</CENTER>
<HR>
<H3>2. Getting Started
</H3>
<P>This section describes how to unpack, make, and run LAMMPS, for both
new and experienced users.
</P>
2.1 <A HREF = "#2_1">What's in the LAMMPS distribution</A><BR>
2.2 <A HREF = "#2_2">Making LAMMPS</A><BR>
2.3 <A HREF = "#2_3">Making LAMMPS with optional packages</A><BR>
2.4 <A HREF = "#2_4">Building LAMMPS as a library</A><BR>
2.5 <A HREF = "#2_5">Running LAMMPS</A><BR>
2.6 <A HREF = "#2_6">Command-line options</A><BR>
2.7 <A HREF = "#2_7">Screen output</A><BR>
2.8 <A HREF = "#2_8">Tips for users of previous versions</A> <BR>
<HR>
<H4><A NAME = "2_1"></A>2.1 What's in the LAMMPS distribution
</H4>
<P>When you download SLAMMPS you will need to unzip and untar the
downloaded file with the following commands, after placing the file in
an appropriate directory.
</P>
<PRE>gunzip lammps*.tar.gz
tar xvf lammps*.tar
</PRE>
<P>This will create a LAMMPS directory containing two files and several
sub-directories:
</P>
<DIV ALIGN=center><TABLE WIDTH="0%" BORDER=1 >
<TR><TD >README</TD><TD > text file</TD></TR>
<TR><TD >LICENSE</TD><TD > the GNU General Public License (GPL)</TD></TR>
<TR><TD >bench</TD><TD > benchmark problems</TD></TR>
<TR><TD >doc</TD><TD > documentation</TD></TR>
<TR><TD >examples</TD><TD > simple test problems</TD></TR>
<TR><TD >potentials</TD><TD > embedded atom method (EAM) potential files</TD></TR>
<TR><TD >src</TD><TD > source files</TD></TR>
<TR><TD >tools</TD><TD > pre- and post-processing tools
</TD></TR></TABLE></DIV>
<HR>
<H4><A NAME = "2_2"></A>2.2 Making LAMMPS
</H4>
<P><B><I>Read this first:</I></B>
</P>
<P>Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
(MPI, FFT), etc. Please read this section carefully. If you are not
comfortable with makefiles, or building codes on a Unix platform, or
running an MPI job on your machine, please find a local expert to help
you. Many compiling, linking, and run problems users have do not
really have to do with LAMMPS - they are peculiar to the user's
system, compilers, libraries, etc. Such questions are better answered
by a local expert.
</P>
<P>If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
please send an email to the
<A HREF = "http://lammps.sandia.gov/authors.html">developers</A>.
</P>
<P>If you succeed in building LAMMPS on a new kind of machine (which
there isn't a similar Makefile for in the distribution), send it to
the developers and we'll include it in future LAMMPS releases.
</P>
<P><B><I>Building a LAMMPS executable:</I></B>
</P>
<P>The src directory contains the C++ source and header files for LAMMPS.
It also contains a top-level Makefile and a MAKE directory with
low-level Makefile.* files for several machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. If one of those is the machine and options you want, you can
type a command like:
</P>
<PRE>make linux
gmake mac
</PRE>
<P>If you get no errors and an executable like lmp_linux or lmp_mac is
produced, you're done; it's your lucky day.
</P>
<P><B><I>Errors that can occur when making LAMMPS:</I></B>
</P>
<P>(1) If the make command breaks immediately with errors that indicate
it can't find files with a "*" in their names, this can be because
your machine's make doesn't support wildcard expansion in a makefile.
Try gmake instead of make. If that doesn't work, try using a -f
switch with your make command to use Makefile.list which explicitly
lists all the needed files, e.g.
</P>
<PRE>make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac
</PRE>
<P>The first "make" command will create a current Makefile.list with all
the file names in your src dir. The 2nd "make" command (make or
gmake) will use it to build LAMMPS.
</P>
<P>(2) Other errors typically occur because the low-level Makefile isn't
setup correctly for your machine. If your platform is named "foo",
you need to create a Makefile.foo in the MAKE directory. Use whatever
existing file is closest to your platform as a starting point. See
the next section for more instructions.
</P>
<P><B><I>Editing a new low-level Makefile.foo:</I></B>
</P>
<P>These are the issues you need to address when editing a low-level
Makefile for your machine. With a couple exceptions, the only portion
of the file you should need to edit is the "System-specific Settings"
section.
</P>
<P>(1) Change the first line of Makefile.foo to include the word "foo"
and whatever other options you set. This is the line you will see if
you just type "make".
</P>
<P>(2) Set the paths and flags for your C++ compiler, including
optimization flags. You can use g++, the open-source GNU compiler,
which is available on all Unix systems. Vendor compilers often
produce faster code. On boxes with Intel CPUs, I use the free Intel
icc compiler, which you can download from <A HREF = "http://www.intel.com/software/products/noncom">Intel's compiler
site</A>.
</P>
<P>(3) If you want LAMMPS to run in parallel, you must have an MPI
library installed on your platform. Makefile.foo needs to specify
where the mpi.h file (-I switch) and the libmpi.a library (-L switch)
is found. On my Linux box, I use Argonne's MPICH 1.2 which can be
downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
site</A>. LAM MPI should also work. If
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 link against it. If you
use MPICH or LAM, you will have to configure and build it for your
platform. The MPI configure script should have compiler options to
enable you to use the same compiler you are using for the LAMMPS
build, which can avoid problems that may arise when linking LAMMPS to
the MPI library.
</P>
<P>(4) 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
installed on your system. See the Makefile.serial file for how to
specify the -I and -L switches. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
dir, type "make" and it will hopefully create a libmpi.a suitable for
linking to LAMMPS. If the build fails, you will need to edit the
STUBS/Makefile for your platform.
</P>
<P>The file STUBS/mpi.cpp has a CPU timer function MPI_Wtime() that calls
gettimeofday() . If your system doesn't support gettimeofday() ,
you'll need to insert code to call another timer. Note that the
ANSI-standard function clock() rolls over after an hour or so, and is
therefore insufficient for timing long LAMMPS runs.
</P>
<P>(5) If you want to use the particle-particle particle-mesh (PPPM)
option in LAMMPS for long-range Coulombics, you must have a 1d FFT
library installed on your platform. This is specified by a switch of
the form -DFFT_XXX where XXX = INTEL, DEC, SGI, SCSL, or FFTW. All
but the last one are native vendor-provided libraries. FFTW is a
fast, portable library that should work on any platform. You can
download it from <A HREF = "http://www.fftw.org">www.fftw.org</A>. Use version
2.1.X, not the newer 3.0.X. Building FFTW for my box was as simple as
./configure; make. Whichever FFT library you have on your platform,
you'll need to set the appropriate -I and -L switches in Makefile.foo.
</P>
<P>If you examine fft3d.c and fft3d.h you'll see it's possible to add
other vendor FFT libraries via #ifdef statements in the appropriate
places. If you successfully add a new FFT option, like -DFFT_IBM,
please send the <A HREF = "http://lammps.sandia.gov">developers</A> an email; we'd
like to add it to LAMMPS.
</P>
<P>(6) If you don't plan to use PPPM, you don't need an FFT library. Use
a -DFFT_NONE switch in the CCFLAGS setting of Makefile.foo, or exclude
the KSPACE package (see below).
</P>
<P>(7) There are a few other -D compiler switches you can set as part of
CCFLAGS. The read_data and dump commands will read/write gzipped
files if you compile with -DGZIP. It requires that your Unix support
the "popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER,
and -DPACK_MEMCPY options can make for faster parallel FFTs (in the
PPPM solver) on some platforms. The -DPACK_ARRAY setting is the
default.
</P>
<P>(8) The DEPFLAGS setting is how the C++ compiler creates a dependency
file for each source file. This speeds re-compilation when source
(*.cpp) or header (*.h) files are edited. Some compilers do not
support dependency file creation, or may use a different switch than
-D. GNU g++ works with -D. If your compiler can't create dependency
files (a long list of errors involving *.d files), then you'll need to
create a Makefile.foo patterned after Makefile.tflop, which uses
different rules that do not involve dependency files.
</P>
<P>That's it. Once you have a correct Makefile.foo and you have
pre-built the MPI and FFT libraries it will use, all you need to do
from the src directory is type one of these 2 commands:
</P>
<PRE>make foo
gmake foo
</PRE>
<P>You should get the executable lmp_foo when the build is complete.
</P>
<P><B><I>Additional build tips:</I></B>
</P>
<P>(1) Building LAMMPS for multiple platforms.
</P>
<P>You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-dir called Obj_name
where it stores the system-specific *.o files.
</P>
<P>(2) Cleaning up.
</P>
<P>Typing "make clean" will delete all *.o object files created when
LAMMPS is built.
</P>
<P>(3) On some machines with some compiler options, the Coulomb tabling
option that is enabled by default for "long" <A HREF = "pair_style.html">pair
styles</A> such as <I>lj/cut/coul/long</I> and
<I>lj/charmm/coul/long</I> does not work. Tables are used by these styles
since it can offer a 2x speed-up. A symptom of this problem is
getting wildly large energies on timestep 0 of the examples/peptide
simulation.
</P>
<P>Here are several work-arounds. Coulomb tables can be disabled by
setting "table 0" in the <A HREF = "pair_modify.html">pair_modify</A> command.
</P>
<P>The associated files (e.g. pair_lj_cut_coul_long.cpp) can be compiled
at a lower optimization level like -O2, or with the compiler flag
<I>-fno-strict-aliasing</I>. The latter can be done by adding something
like these lines in your Makefile.machine:
</P>
<PRE>NOALIAS = -fno-strict-aliasing
</PRE>
<PRE>pair_lj_cut_coul_long.o : pair_lj_cut_coul_long.cpp
$(CC) $(CCFLAGS) $(NOALIAS) -c $<
</PRE>
<PRE>pair_lj_charmm_coul_long.o : pair_lj_charmm_coul_long.cpp
$(CC) $(CCFLAGS) $(NOALIAS) -c $<
</PRE>
<P>On a Macintosh, try compiling the pair "long" files without the -fast
compiler option.
</P>
<P>(4) Building for a Macintosh.
</P>
<P>OS X is BSD Unix, so it already works. See the Makefile.mac file.
</P>
<P>(5) Building for MicroSoft Windows.
</P>
<P>I've never done this, but LAMMPS is just standard C++ with MPI and FFT
calls. You should be able to use cygwin to build LAMMPS with a Unix
make. Or you should be able to pull all the source files into Visual
C++ (ugh) or some similar development environment and build it. In
the src/MAKE/Windows directory are some notes from users on how they
built LAMMPS under Windows, so you can look at their instructions for
tips. Good luck - we can't help you on this one.
</P>
<H4><A NAME = "2_3"></A>2.3 Making LAMMPS with optional packages
</H4>
<P>The source code for LAMMPS is structured as a large set of core files
that are always used plus additional packages, which are groups of
files that enable a specific set of features. For example, force
fields for molecular systems or granular systems are in packages. You
can see the list of packages by typing "make package". The current
list of packages is as follows:
</P>
<DIV ALIGN=center><TABLE WIDTH="0%" BORDER=1 >
<TR><TD >asphere </TD><TD > aspherical particles</TD></TR>
<TR><TD >class2 </TD><TD > class 2 force fields</TD></TR>
<TR><TD >dpd </TD><TD > dissipative particle dynamics (DPD) force field</TD></TR>
<TR><TD >granular </TD><TD > force fields and boundary conditions for granular systems</TD></TR>
<TR><TD >kspace </TD><TD > long-range Ewald and particle-mesh (PPPM) solvers</TD></TR>
<TR><TD >manybody </TD><TD > metal, 3-body, bond-order potentials</TD></TR>
<TR><TD >meam </TD><TD > modified embedded atom method (MEAM) potential</TD></TR>
<TR><TD >molecule </TD><TD > force fields for molecular systems</TD></TR>
<TR><TD >opt </TD><TD > optimized versions of a few pair potentials</TD></TR>
<TR><TD >poems </TD><TD > coupled rigid body motion</TD></TR>
<TR><TD >xtc </TD><TD > dump atom snapshots in XTC format
</TD></TR></TABLE></DIV>
<P>Any or all packages can be included or excluded when LAMMPS is built.
The one exception is that to use the "opt" package, you must also be
using the "molecule" and "manybody" packages. You may wish to exclude
certain packages if you will never run certain kinds of simulations.
This will produce a smaller executable which may run a bit faster.
</P>
<P>By default, LAMMPS includes only the "kspace", "manybody", and
"molecule" packages. As described below, some packages require LAMMPS
be linked to separately built library files, which will require
editing of your src/MAKE/Makefile.machine.
</P>
<P>Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package. You can also type
"make yes-all" or "make no-all" to include/exclude all optional
packages. These commands work by simply moving files back and forth
between the main src directory and sub-directories with the package
name, so that the files are seen or not seen when LAMMPS is built.
After you have included or excluded a package, you must re-make
LAMMPS.
</P>
<P>Additional make options exist to help manage LAMMPS files that exist
in both the src directory and in package sub-directories. You do not
normally need to use these commands unless you are editing LAMMPS
files or have downloaded a patch from the LAMMPS WWW site. Typing
"make package-update" will overwrite src files with files from the
package directories if the package has been included. It should be
used after a patch is installed, since patches only update the master
package version of a file. Typing "make package-overwrite" will
overwrite files in the package directories with src files. Typing
"make package-check" will list differences between src and package
versions of the same files.
</P>
<P>To use the "meam" package you must build LAMMPS with the MEAM library
in lib/meam, which computes the modified embedded atom method
potential, which is a generalization of EAM potentials that can be
used to model a wider variety of materials. This MEAM implementation
was written by Greg Wagner at Sandia. To build LAMMPS with MEAM, you
must use a low-level LAMMPS Makefile that includes the MEAM directory
in its paths. See Makefile.linux_meam as an example. You must also
build MEAM itself as a library before building LAMMPS, so that LAMMPS
can link against it. This requires a F90 compiler. The library is
built by typing "make" from within the meam directory with the
appropriate Makefile, e.g. "make -f Makefile.icc". If one of the
provided Makefiles is not appropriate for your system you can edit or
add one as needed.
</P>
<P>Note that linking a Fortran library to a C++ code can be problematic
(e.g. Fortran routine names can't be found due to non-standard
underscore rules) and typically requires additional C++ or F90
libraries be included in the link. You may need to read documentation
for your compiler about how to do this correctly.
</P>
<P>To use the "poems" package you must build LAMMPS with the POEMS
library in lib/poems, which computes the constrained rigid-body motion
of articulated (jointed) multibody systems. POEMS was written and is
distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic
Institute (RPI). To build LAMMPS with POEMS, you must use a low-level
LAMMPS Makefile that includes the POEMS directory in its paths. See
Makefile.g++_poems as an example. You must also build POEMS itself as
a library before building LAMMPS, so that LAMMPS can link against it.
The POEMS library is built by typing "make" from within the poems
directory with the appropriate Makefile, e.g. "make -f Makefile.g++".
If one of the provided Makefiles is not appropriate for your system
you can edit or add one as needed.
</P>
<H4><A NAME = "2_4"></A>2.4 Building LAMMPS as a library
</H4>
<P>LAMMPS can be built as a library, which can then be called from
another application or a scripting language. See <A HREF = "Section_howto.html#4_10">this
section</A> for more info on coupling LAMMPS to
other codes. Building LAMMPS as a library is done by typing
</P>
<PRE>make makelib
make -f Makefile.lib foo
</PRE>
<P>where foo is the machine name. The first "make" command will create a
current Makefile.lib with all the file names in your src dir. The 2nd
"make" command will use it to build LAMMPS as a library. This
requires that Makefile.foo have a library target (lib) and
system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux
for an example. The build will create the file liblmp_foo.a which
another application can link to.
</P>
<P>When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed. See the sample code
examples/couple/c++_driver.cpp as an example.
</P>
<P>When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in library.cpp
and library.h. See the sample code examples/couple/c_driver.cpp as an
example.
</P>
<P>You can add as many functions as you wish to library.cpp and
library.h. In a general sense, those functions can access LAMMPS data
and return it to the caller or set LAMMPS data values as specified by
the caller. These 4 functions are currently included in library.cpp:
</P>
<PRE>void lammps_open(int, char **, MPI_Comm, void **ptr);
void lammps_close(void *ptr);
int lammps_file(void *ptr, char *);
int lammps_command(void *ptr, char *);
</PRE>
<P>The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were <A HREF = "#2_6">command-line arguments</A> when
LAMMPS is run from the command line and a MPI communicator for LAMMPS
to run under. It returns a ptr to the LAMMPS object that is created,
and which should be used in subsequent library calls. Note that
lammps_open() can be called multiple times to create multiple LAMMPS
objects.
</P>
<P>The lammps_close() function is used to shut down LAMMPS and free all
its memory. The lammps_file() and lammps_command() functions are used
to pass a file or string to LAMMPS as if it were an input file or
single command read from an input script.
</P>
<HR>
<H4><A NAME = "2_5"></A>2.5 Running LAMMPS
</H4>
<P>By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. <A HREF = "Section_commands.html">This section</A>
describes how input scripts are structured and what commands they
contain.
</P>
<P>You can test LAMMPS on any of the sample inputs provided in the
examples directory. Input scripts are named in.* and sample outputs
are named log.*.name.P where name is a machine and P is the number of
processors it was run on.
</P>
<P>Here is how you might run one of the Lennard-Jones tests on a Linux
box, using mpirun to launch a parallel job:
</P>
<PRE>cd src
make linux
cp lmp_linux ../examples/lj
cd ../examples/lj
mpirun -np 4 lmp_linux < in.lj.nve
</PRE>
<P>The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.
</P>
<P>Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from. If that happens, LAMMPS will look for
additional input files and write its output files to the executable
directory, rather than your working directory, which is probably not
what you want.
</P>
<P>If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See <A HREF = "Section_errors.html">this section</A> for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
</P>
<P>LAMMPS can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
</P>
<P>LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
</P>
<HR>
<H4><A NAME = "2_6"></A>2.6 Command-line options
</H4>
<P>At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. For example, lmp_ibm might be
launched as follows:
</P>
<PRE>mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none < in.alloy
</PRE>
<P>These are the command-line options:
</P>
<PRE>-echo style
</PRE>
<P>Set the style of command echoing. The style can be <I>none</I> or <I>screen</I>
or <I>log</I> or <I>both</I>. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is <I>log</I>. The echo style can also be
set by using the <A HREF = "echo.html">echo</A> command in the input script itself.
</P>
<PRE>-partition 8x2 4 5 ...
</PRE>
<P>Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
</P>
<P>The input script specifies what simulation is run on which partition;
see the <A HREF = "variable.html">variable</A> and <A HREF = "next.html">next</A> commands.
Simulations running on different partitions can also communicate with
each other; see the <A HREF = "temper.html">temper</A> command.
</P>
<PRE>-in file
</PRE>
<P>Specify a file to use as an input script. This is an optional switch
when running LAMMPS in one-partition mode. If it is not specified,
LAMMPS reads its input script from stdin - e.g. lmp_linux < in.run.
This is a required switch when running LAMMPS in multi-partition mode,
since multiple processors cannot all read from stdin.
</P>
<PRE>-log file
</PRE>
<P>Specify a log file for LAMMPS to write status information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps. If this switch is used, LAMMPS writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
<A HREF = "log.html">log</A> command in the input script will override this setting.
</P>
<PRE>-screen file
</PRE>
<P>Specify a file for LAMMPS to write its screen information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen. If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed.
</P>
<PRE>-var name value
</PRE>
<P>Specify a variable that will be defined for substitution purposes when
the input script is read. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as ${abc}). The value can be any string. Using
this command-line option is equivalent to putting the line "variable
-name equal value" at the beginning of the input script. See the
+name index value" at the beginning of the input script. See the
<A HREF = "variable.html">variable</A> command for more info on defining variables
and <A HREF = "Section_commands.html#3_2">this section</A> for more info on using
variables in input scripts.
</P>
<HR>
<H4><A NAME = "2_7"></A>2.7 LAMMPS screen output
</H4>
<P>As LAMMPS reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LAMMPS performs
various initializations and prints the amount of memory (in MBytes per
processor) that the simulation requires. It also prints details of
the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LAMMPS prints the final
thermodynamic state and a total run time for the simulation. It then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
</P>
<PRE>Loop time of 49.002 on 2 procs for 2004 atoms
</PRE>
<PRE>Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041)
</PRE>
<PRE>Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1
</PRE>
<PRE>Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2
</PRE>
<P>The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section lists the number of owned
atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values
across processors with a 10-bin histogram showing the distribution.
The total number of histogram counts is equal to the number of
processors.
</P>
<P>The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LAMMPS keeps track of (see the
<A HREF = "special_bonds.html">special_bonds</A> command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially "dangerous" rebuilds. If atom movement
triggered neighbor list rebuilding (see the
<A HREF = "neigh_modify.html">neigh_modify</A> command), then dangerous
reneighborings are those that were triggered on the first timestep
atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed
by atoms moving beyond the neighbor skin distance before a rebuild
takes place.
</P>
<P>If an energy minimization was performed via the
<A HREF = "minimize.html">minimize</A> command, additional information is printed,
e.g.
</P>
<PRE>Minimization stats:
E initial, next-to-last, final = -0.895962 -2.94193 -2.94342
Gradient 2-norm init/final= 1920.78 20.9992
Gradient inf-norm init/final= 304.283 9.61216
Iterations = 36
Force evaluations = 177
</PRE>
<P>The first line lists the initial and final energy, as well as the
energy on the next-to-last iteration. The next 2 lines give a measure
of the gradient of the energy (force on all atoms). The 2-norm is the
"length" of this force vector; the inf-norm is the largest component.
The last 2 lines are statistics on how many iterations and
force-evaluations the minimizer required. Multiple force evaluations
are typically done at each iteration to perform a 1d line minimization
in the search direction.
</P>
<P>If a <A HREF = "kspace_style.html">kspace_style</A> long-range Coulombics solve was
performed during the run (PPPM, Ewald), then additional information is
printed, e.g.
</P>
<PRE>FFT time (% of Kspce) = 0.200313 (8.34477)
FFT Gflps 3d 1d-only = 2.31074 9.19989
</PRE>
<P>The first line gives the time spent doing 3d FFTs (4 per timestep) and
the fraction it represents of the total KSpace time (listed above).
Each 3d FFT requires computation (3 sets of 1d FFTs) and communication
(transposes). The total flops performed is 5Nlog_2(N), where N is the
number of points in the 3d grid. The FFTs are timed with and without
the communication and a Gflop rate is computed. The 3d rate is with
communication; the 1d rate is without (just the 1d FFTs). Thus you
can estimate what fraction of your FFT time was spent in
communication, roughly 75% in the example above.
</P>
<HR>
<H4><A NAME = "2_8"></A>2.8 Tips for users of previous LAMMPS versions
</H4>
<P>LAMMPS 2003 is a complete C++ rewrite of LAMMPS 2001, which was
written in F90. Features of earlier versions of LAMMPS are listed in
<A HREF = "Section_history.html">this section</A>. The F90 and F77 versions (2001
and 99) are also freely distributed as open-source codes; check the
<A HREF = "http://lammps.sandia.gov">LAMMPS WWW Site</A> for distribution information if you prefer those
versions. The 99 and 2001 versions are no longer under active
development; they do not have all the features of LAMMPS 2003.
</P>
<P>If you are a previous user of LAMMPS 2001, these are the most
significant changes you will notice in LAMMPS 2003:
</P>
<P>(1) The names and arguments of many input script commands have
changed. All commands are now a single word (e.g. read_data instead
of read data).
</P>
<P>(2) All the functionality of LAMMPS 2001 is included in LAMMPS 2003,
but you may need to specify the relevant commands in different ways.
</P>
<P>(3) The format of the data file can be streamlined for some problems.
See the <A HREF = "read_data.html">read_data</A> command for details. The data file
section "Nonbond Coeff" has been renamed to "Pair Coeff" in LAMMPS
2003.
</P>
<P>(4) Binary restart files written by LAMMPS 2001 cannot be read by
LAMMPS 2003 with a <A HREF = "read_restart.html">read_restart</A> command. This is
because they were output by F90 which writes in a different binary
format than C or C++ writes or reads. Use the <I>restart2data</I> tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text
data file. Then edit the data file as necessary before using the
LAMMPS 2003 <A HREF = "read_data.html">read_data</A> command to read it in.
</P>
<P>(5) There are numerous small numerical changes in LAMMPS 2003 that
mean you will not get identical answers when comparing to a 2001 run.
However, your initial thermodynamic energy and MD trajectory should be
close if you have setup the problem for both codes the same.
</P>
</HTML>
diff --git a/doc/Section_start.txt b/doc/Section_start.txt
index a0b6de21a..aae316f66 100644
--- a/doc/Section_start.txt
+++ b/doc/Section_start.txt
@@ -1,673 +1,673 @@
"Previous Section"_Section_intro.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Section_commands.html :c
:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)
:line
2. Getting Started :h3
This section describes how to unpack, make, and run LAMMPS, for both
new and experienced users.
2.1 "What's in the LAMMPS distribution"_#2_1
2.2 "Making LAMMPS"_#2_2
2.3 "Making LAMMPS with optional packages"_#2_3
2.4 "Building LAMMPS as a library"_#2_4
2.5 "Running LAMMPS"_#2_5
2.6 "Command-line options"_#2_6
2.7 "Screen output"_#2_7
2.8 "Tips for users of previous versions"_#2_8 :all(b)
:line
2.1 What's in the LAMMPS distribution :h4,link(2_1)
When you download SLAMMPS you will need to unzip and untar the
downloaded file with the following commands, after placing the file in
an appropriate directory.
gunzip lammps*.tar.gz
tar xvf lammps*.tar :pre
This will create a LAMMPS directory containing two files and several
sub-directories:
README: text file
LICENSE: the GNU General Public License (GPL)
bench: benchmark problems
doc: documentation
examples: simple test problems
potentials: embedded atom method (EAM) potential files
src: source files
tools: pre- and post-processing tools :tb(s=:)
:line
2.2 Making LAMMPS :h4,link(2_2)
[{Read this first:}]
Building LAMMPS can be non-trivial. You will likely need to edit a
makefile, there are compiler options, additional libraries can be used
(MPI, FFT), etc. Please read this section carefully. If you are not
comfortable with makefiles, or building codes on a Unix platform, or
running an MPI job on your machine, please find a local expert to help
you. Many compiling, linking, and run problems users have do not
really have to do with LAMMPS - they are peculiar to the user's
system, compilers, libraries, etc. Such questions are better answered
by a local expert.
If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
please send an email to the
"developers"_http://lammps.sandia.gov/authors.html.
If you succeed in building LAMMPS on a new kind of machine (which
there isn't a similar Makefile for in the distribution), send it to
the developers and we'll include it in future LAMMPS releases.
[{Building a LAMMPS executable:}]
The src directory contains the C++ source and header files for LAMMPS.
It also contains a top-level Makefile and a MAKE directory with
low-level Makefile.* files for several machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. If one of those is the machine and options you want, you can
type a command like:
make linux
gmake mac :pre
If you get no errors and an executable like lmp_linux or lmp_mac is
produced, you're done; it's your lucky day.
[{Errors that can occur when making LAMMPS:}]
(1) If the make command breaks immediately with errors that indicate
it can't find files with a "*" in their names, this can be because
your machine's make doesn't support wildcard expansion in a makefile.
Try gmake instead of make. If that doesn't work, try using a -f
switch with your make command to use Makefile.list which explicitly
lists all the needed files, e.g.
make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac :pre
The first "make" command will create a current Makefile.list with all
the file names in your src dir. The 2nd "make" command (make or
gmake) will use it to build LAMMPS.
(2) Other errors typically occur because the low-level Makefile isn't
setup correctly for your machine. If your platform is named "foo",
you need to create a Makefile.foo in the MAKE directory. Use whatever
existing file is closest to your platform as a starting point. See
the next section for more instructions.
[{Editing a new low-level Makefile.foo:}]
These are the issues you need to address when editing a low-level
Makefile for your machine. With a couple exceptions, the only portion
of the file you should need to edit is the "System-specific Settings"
section.
(1) Change the first line of Makefile.foo to include the word "foo"
and whatever other options you set. This is the line you will see if
you just type "make".
(2) Set the paths and flags for your C++ compiler, including
optimization flags. You can use g++, the open-source GNU compiler,
which is available on all Unix systems. Vendor compilers often
produce faster code. On boxes with Intel CPUs, I use the free Intel
icc compiler, which you can download from "Intel's compiler
site"_intel.
:link(intel,http://www.intel.com/software/products/noncom)
(3) If you want LAMMPS to run in parallel, you must have an MPI
library installed on your platform. Makefile.foo needs to specify
where the mpi.h file (-I switch) and the libmpi.a library (-L switch)
is found. On my Linux box, I use Argonne's MPICH 1.2 which can be
downloaded from the "Argonne MPI
site"_http://www-unix.mcs.anl.gov/mpi. 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 link against it. If you
use MPICH or LAM, you will have to configure and build it for your
platform. The MPI configure script should have compiler options to
enable you to use the same compiler you are using for the LAMMPS
build, which can avoid problems that may arise when linking LAMMPS to
the MPI library.
(4) 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
installed on your system. See the Makefile.serial file for how to
specify the -I and -L switches. You will also need to build the STUBS
library for your platform before making LAMMPS itself. From the STUBS
dir, type "make" and it will hopefully create a libmpi.a suitable for
linking to LAMMPS. If the build fails, you will need to edit the
STUBS/Makefile for your platform.
The file STUBS/mpi.cpp has a CPU timer function MPI_Wtime() that calls
gettimeofday() . If your system doesn't support gettimeofday() ,
you'll need to insert code to call another timer. Note that the
ANSI-standard function clock() rolls over after an hour or so, and is
therefore insufficient for timing long LAMMPS runs.
(5) If you want to use the particle-particle particle-mesh (PPPM)
option in LAMMPS for long-range Coulombics, you must have a 1d FFT
library installed on your platform. This is specified by a switch of
the form -DFFT_XXX where XXX = INTEL, DEC, SGI, SCSL, or FFTW. All
but the last one are native vendor-provided libraries. FFTW is a
fast, portable library that should work on any platform. You can
download it from "www.fftw.org"_http://www.fftw.org. Use version
2.1.X, not the newer 3.0.X. Building FFTW for my box was as simple as
./configure; make. Whichever FFT library you have on your platform,
you'll need to set the appropriate -I and -L switches in Makefile.foo.
If you examine fft3d.c and fft3d.h you'll see it's possible to add
other vendor FFT libraries via #ifdef statements in the appropriate
places. If you successfully add a new FFT option, like -DFFT_IBM,
please send the "developers"_http://lammps.sandia.gov an email; we'd
like to add it to LAMMPS.
(6) If you don't plan to use PPPM, you don't need an FFT library. Use
a -DFFT_NONE switch in the CCFLAGS setting of Makefile.foo, or exclude
the KSPACE package (see below).
(7) There are a few other -D compiler switches you can set as part of
CCFLAGS. The read_data and dump commands will read/write gzipped
files if you compile with -DGZIP. It requires that your Unix support
the "popen" command. Using one of the -DPACK_ARRAY, -DPACK_POINTER,
and -DPACK_MEMCPY options can make for faster parallel FFTs (in the
PPPM solver) on some platforms. The -DPACK_ARRAY setting is the
default.
(8) The DEPFLAGS setting is how the C++ compiler creates a dependency
file for each source file. This speeds re-compilation when source
(*.cpp) or header (*.h) files are edited. Some compilers do not
support dependency file creation, or may use a different switch than
-D. GNU g++ works with -D. If your compiler can't create dependency
files (a long list of errors involving *.d files), then you'll need to
create a Makefile.foo patterned after Makefile.tflop, which uses
different rules that do not involve dependency files.
That's it. Once you have a correct Makefile.foo and you have
pre-built the MPI and FFT libraries it will use, all you need to do
from the src directory is type one of these 2 commands:
make foo
gmake foo :pre
You should get the executable lmp_foo when the build is complete.
[{Additional build tips:}]
(1) Building LAMMPS for multiple platforms.
You can make LAMMPS for multiple platforms from the same src
directory. Each target creates its own object sub-dir called Obj_name
where it stores the system-specific *.o files.
(2) Cleaning up.
Typing "make clean" will delete all *.o object files created when
LAMMPS is built.
(3) On some machines with some compiler options, the Coulomb tabling
option that is enabled by default for "long" "pair
styles"_pair_style.html such as {lj/cut/coul/long} and
{lj/charmm/coul/long} does not work. Tables are used by these styles
since it can offer a 2x speed-up. A symptom of this problem is
getting wildly large energies on timestep 0 of the examples/peptide
simulation.
Here are several work-arounds. Coulomb tables can be disabled by
setting "table 0" in the "pair_modify"_pair_modify.html command.
The associated files (e.g. pair_lj_cut_coul_long.cpp) can be compiled
at a lower optimization level like -O2, or with the compiler flag
{-fno-strict-aliasing}. The latter can be done by adding something
like these lines in your Makefile.machine:
NOALIAS = -fno-strict-aliasing :pre
pair_lj_cut_coul_long.o : pair_lj_cut_coul_long.cpp
$(CC) $(CCFLAGS) $(NOALIAS) -c $< :pre
pair_lj_charmm_coul_long.o : pair_lj_charmm_coul_long.cpp
$(CC) $(CCFLAGS) $(NOALIAS) -c $< :pre
On a Macintosh, try compiling the pair "long" files without the -fast
compiler option.
(4) Building for a Macintosh.
OS X is BSD Unix, so it already works. See the Makefile.mac file.
(5) Building for MicroSoft Windows.
I've never done this, but LAMMPS is just standard C++ with MPI and FFT
calls. You should be able to use cygwin to build LAMMPS with a Unix
make. Or you should be able to pull all the source files into Visual
C++ (ugh) or some similar development environment and build it. In
the src/MAKE/Windows directory are some notes from users on how they
built LAMMPS under Windows, so you can look at their instructions for
tips. Good luck - we can't help you on this one.
2.3 Making LAMMPS with optional packages :h4,link(2_3)
The source code for LAMMPS is structured as a large set of core files
that are always used plus additional packages, which are groups of
files that enable a specific set of features. For example, force
fields for molecular systems or granular systems are in packages. You
can see the list of packages by typing "make package". The current
list of packages is as follows:
asphere : aspherical particles
class2 : class 2 force fields
dpd : dissipative particle dynamics (DPD) force field
granular : force fields and boundary conditions for granular systems
kspace : long-range Ewald and particle-mesh (PPPM) solvers
manybody : metal, 3-body, bond-order potentials
meam : modified embedded atom method (MEAM) potential
molecule : force fields for molecular systems
opt : optimized versions of a few pair potentials
poems : coupled rigid body motion
xtc : dump atom snapshots in XTC format :tb(s=:)
Any or all packages can be included or excluded when LAMMPS is built.
The one exception is that to use the "opt" package, you must also be
using the "molecule" and "manybody" packages. You may wish to exclude
certain packages if you will never run certain kinds of simulations.
This will produce a smaller executable which may run a bit faster.
By default, LAMMPS includes only the "kspace", "manybody", and
"molecule" packages. As described below, some packages require LAMMPS
be linked to separately built library files, which will require
editing of your src/MAKE/Makefile.machine.
Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package. You can also type
"make yes-all" or "make no-all" to include/exclude all optional
packages. These commands work by simply moving files back and forth
between the main src directory and sub-directories with the package
name, so that the files are seen or not seen when LAMMPS is built.
After you have included or excluded a package, you must re-make
LAMMPS.
Additional make options exist to help manage LAMMPS files that exist
in both the src directory and in package sub-directories. You do not
normally need to use these commands unless you are editing LAMMPS
files or have downloaded a patch from the LAMMPS WWW site. Typing
"make package-update" will overwrite src files with files from the
package directories if the package has been included. It should be
used after a patch is installed, since patches only update the master
package version of a file. Typing "make package-overwrite" will
overwrite files in the package directories with src files. Typing
"make package-check" will list differences between src and package
versions of the same files.
To use the "meam" package you must build LAMMPS with the MEAM library
in lib/meam, which computes the modified embedded atom method
potential, which is a generalization of EAM potentials that can be
used to model a wider variety of materials. This MEAM implementation
was written by Greg Wagner at Sandia. To build LAMMPS with MEAM, you
must use a low-level LAMMPS Makefile that includes the MEAM directory
in its paths. See Makefile.linux_meam as an example. You must also
build MEAM itself as a library before building LAMMPS, so that LAMMPS
can link against it. This requires a F90 compiler. The library is
built by typing "make" from within the meam directory with the
appropriate Makefile, e.g. "make -f Makefile.icc". If one of the
provided Makefiles is not appropriate for your system you can edit or
add one as needed.
Note that linking a Fortran library to a C++ code can be problematic
(e.g. Fortran routine names can't be found due to non-standard
underscore rules) and typically requires additional C++ or F90
libraries be included in the link. You may need to read documentation
for your compiler about how to do this correctly.
To use the "poems" package you must build LAMMPS with the POEMS
library in lib/poems, which computes the constrained rigid-body motion
of articulated (jointed) multibody systems. POEMS was written and is
distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic
Institute (RPI). To build LAMMPS with POEMS, you must use a low-level
LAMMPS Makefile that includes the POEMS directory in its paths. See
Makefile.g++_poems as an example. You must also build POEMS itself as
a library before building LAMMPS, so that LAMMPS can link against it.
The POEMS library is built by typing "make" from within the poems
directory with the appropriate Makefile, e.g. "make -f Makefile.g++".
If one of the provided Makefiles is not appropriate for your system
you can edit or add one as needed.
2.4 Building LAMMPS as a library :h4,link(2_4)
LAMMPS can be built as a library, which can then be called from
another application or a scripting language. See "this
section"_Section_howto.html#4_10 for more info on coupling LAMMPS to
other codes. Building LAMMPS as a library is done by typing
make makelib
make -f Makefile.lib foo :pre
where foo is the machine name. The first "make" command will create a
current Makefile.lib with all the file names in your src dir. The 2nd
"make" command will use it to build LAMMPS as a library. This
requires that Makefile.foo have a library target (lib) and
system-specific settings for ARCHIVE and ARFLAGS. See Makefile.linux
for an example. The build will create the file liblmp_foo.a which
another application can link to.
When used from a C++ program, the library allows one or more LAMMPS
objects to be instantiated. All of LAMMPS is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within your application code, as needed. See the sample code
examples/couple/c++_driver.cpp as an example.
When used from a C or Fortran program or a scripting language, the
library has a simple function-style interface, provided in library.cpp
and library.h. See the sample code examples/couple/c_driver.cpp as an
example.
You can add as many functions as you wish to library.cpp and
library.h. In a general sense, those functions can access LAMMPS data
and return it to the caller or set LAMMPS data values as specified by
the caller. These 4 functions are currently included in library.cpp:
void lammps_open(int, char **, MPI_Comm, void **ptr);
void lammps_close(void *ptr);
int lammps_file(void *ptr, char *);
int lammps_command(void *ptr, char *); :pre
The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were "command-line arguments"_#2_6 when
LAMMPS is run from the command line and a MPI communicator for LAMMPS
to run under. It returns a ptr to the LAMMPS object that is created,
and which should be used in subsequent library calls. Note that
lammps_open() can be called multiple times to create multiple LAMMPS
objects.
The lammps_close() function is used to shut down LAMMPS and free all
its memory. The lammps_file() and lammps_command() functions are used
to pass a file or string to LAMMPS as if it were an input file or
single command read from an input script.
:line
2.5 Running LAMMPS :h4,link(2_5)
By default, LAMMPS runs by reading commands from stdin; e.g. lmp_linux
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. "This section"_Section_commands.html
describes how input scripts are structured and what commands they
contain.
You can test LAMMPS on any of the sample inputs provided in the
examples directory. Input scripts are named in.* and sample outputs
are named log.*.name.P where name is a machine and P is the number of
processors it was run on.
Here is how you might run one of the Lennard-Jones tests on a Linux
box, using mpirun to launch a parallel job:
cd src
make linux
cp lmp_linux ../examples/lj
cd ../examples/lj
mpirun -np 4 lmp_linux < in.lj.nve :pre
The screen output from LAMMPS is described in the next section. As it
runs, LAMMPS also writes a log.lammps file with the same information.
Note that this sequence of commands copies the LAMMPS executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from. If that happens, LAMMPS will look for
additional input files and write its output files to the executable
directory, rather than your working directory, which is probably not
what you want.
If LAMMPS encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See "this section"_Section_errors.html for a
discussion of the various kinds of errors LAMMPS can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
LAMMPS can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
LAMMPS can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
:line
2.6 Command-line options :h4,link(2_6)
At run time, LAMMPS recognizes several optional command-line switches
which may be used in any order. For example, lmp_ibm might be
launched as follows:
mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none < in.alloy :pre
These are the command-line options:
-echo style :pre
Set the style of command echoing. The style can be {none} or {screen}
or {log} or {both}. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is {log}. The echo style can also be
set by using the "echo"_echo.html command in the input script itself.
-partition 8x2 4 5 ... :pre
Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P
processors and this switch is not used, LAMMPS runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
The input script specifies what simulation is run on which partition;
see the "variable"_variable.html and "next"_next.html commands.
Simulations running on different partitions can also communicate with
each other; see the "temper"_temper.html command.
-in file :pre
Specify a file to use as an input script. This is an optional switch
when running LAMMPS in one-partition mode. If it is not specified,
LAMMPS reads its input script from stdin - e.g. lmp_linux < in.run.
This is a required switch when running LAMMPS in multi-partition mode,
since multiple processors cannot all read from stdin.
-log file :pre
Specify a log file for LAMMPS to write status information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
file log.lammps. If this switch is used, LAMMPS writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
"log"_log.html command in the input script will override this setting.
-screen file :pre
Specify a file for LAMMPS to write its screen information to. In
one-partition mode, if the switch is not used, LAMMPS writes to the
screen. If this switch is used, LAMMPS writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed.
-var name value :pre
Specify a variable that will be defined for substitution purposes when
the input script is read. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as $\{abc\}). The value can be any string. Using
this command-line option is equivalent to putting the line "variable
-name equal value" at the beginning of the input script. See the
+name index value" at the beginning of the input script. See the
"variable"_variable.html command for more info on defining variables
and "this section"_Section_commands.html#3_2 for more info on using
variables in input scripts.
:line
2.7 LAMMPS screen output :h4,link(2_7)
As LAMMPS reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LAMMPS performs
various initializations and prints the amount of memory (in MBytes per
processor) that the simulation requires. It also prints details of
the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LAMMPS prints the final
thermodynamic state and a total run time for the simulation. It then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
Loop time of 49.002 on 2 procs for 2004 atoms :pre
Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041) :pre
Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1 :pre
Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2 :pre
The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section lists the number of owned
atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values
across processors with a 10-bin histogram showing the distribution.
The total number of histogram counts is equal to the number of
processors.
The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LAMMPS keeps track of (see the
"special_bonds"_special_bonds.html command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially "dangerous" rebuilds. If atom movement
triggered neighbor list rebuilding (see the
"neigh_modify"_neigh_modify.html command), then dangerous
reneighborings are those that were triggered on the first timestep
atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed
by atoms moving beyond the neighbor skin distance before a rebuild
takes place.
If an energy minimization was performed via the
"minimize"_minimize.html command, additional information is printed,
e.g.
Minimization stats:
E initial, next-to-last, final = -0.895962 -2.94193 -2.94342
Gradient 2-norm init/final= 1920.78 20.9992
Gradient inf-norm init/final= 304.283 9.61216
Iterations = 36
Force evaluations = 177 :pre
The first line lists the initial and final energy, as well as the
energy on the next-to-last iteration. The next 2 lines give a measure
of the gradient of the energy (force on all atoms). The 2-norm is the
"length" of this force vector; the inf-norm is the largest component.
The last 2 lines are statistics on how many iterations and
force-evaluations the minimizer required. Multiple force evaluations
are typically done at each iteration to perform a 1d line minimization
in the search direction.
If a "kspace_style"_kspace_style.html long-range Coulombics solve was
performed during the run (PPPM, Ewald), then additional information is
printed, e.g.
FFT time (% of Kspce) = 0.200313 (8.34477)
FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre
The first line gives the time spent doing 3d FFTs (4 per timestep) and
the fraction it represents of the total KSpace time (listed above).
Each 3d FFT requires computation (3 sets of 1d FFTs) and communication
(transposes). The total flops performed is 5Nlog_2(N), where N is the
number of points in the 3d grid. The FFTs are timed with and without
the communication and a Gflop rate is computed. The 3d rate is with
communication; the 1d rate is without (just the 1d FFTs). Thus you
can estimate what fraction of your FFT time was spent in
communication, roughly 75% in the example above.
:line
2.8 Tips for users of previous LAMMPS versions :h4,link(2_8)
LAMMPS 2003 is a complete C++ rewrite of LAMMPS 2001, which was
written in F90. Features of earlier versions of LAMMPS are listed in
"this section"_Section_history.html. The F90 and F77 versions (2001
and 99) are also freely distributed as open-source codes; check the
"LAMMPS WWW Site"_lws for distribution information if you prefer those
versions. The 99 and 2001 versions are no longer under active
development; they do not have all the features of LAMMPS 2003.
If you are a previous user of LAMMPS 2001, these are the most
significant changes you will notice in LAMMPS 2003:
(1) The names and arguments of many input script commands have
changed. All commands are now a single word (e.g. read_data instead
of read data).
(2) All the functionality of LAMMPS 2001 is included in LAMMPS 2003,
but you may need to specify the relevant commands in different ways.
(3) The format of the data file can be streamlined for some problems.
See the "read_data"_read_data.html command for details. The data file
section "Nonbond Coeff" has been renamed to "Pair Coeff" in LAMMPS
2003.
(4) Binary restart files written by LAMMPS 2001 cannot be read by
LAMMPS 2003 with a "read_restart"_read_restart.html command. This is
because they were output by F90 which writes in a different binary
format than C or C++ writes or reads. Use the {restart2data} tool
provided with LAMMPS 2001 to convert the 2001 restart file to a text
data file. Then edit the data file as necessary before using the
LAMMPS 2003 "read_data"_read_data.html command to read it in.
(5) There are numerous small numerical changes in LAMMPS 2003 that
mean you will not get identical answers when comparing to a 2001 run.
However, your initial thermodynamic energy and MD trajectory should be
close if you have setup the problem for both codes the same.
diff --git a/doc/variable.html b/doc/variable.html
index e03c58bfe..59c9a77f1 100644
--- a/doc/variable.html
+++ b/doc/variable.html
@@ -1,299 +1,300 @@
<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>variable command
</H3>
<P><B>Syntax:</B>
</P>
<PRE>variable name style args ...
</PRE>
<UL><LI>name = name of variable to define
<LI>style = <I>index</I> or <I>loop</I> or <I>world</I> or <I>universe</I> or <I>uloop</I> or <I>equal</I> or <I>atom</I>
<PRE> <I>index</I> args = one or more strings
<I>loop</I> args = N = integer size of loop
<I>world</I> args = one string for each partition of processors
<I>universe</I> args = one or more strings
<I>uloop</I> args = N = integer size of loop
<I>equal</I> or <I>atom</I> args = one equation containing numbers, thermo keywords, math functions, group functions, atom vectors, compute references, other variables
numbers = 0.0, -5.4, 2.8e-4, etc
thermo keywords = vol, ke, press, etc from <A HREF = "thermo_style.html">thermo_style</A>
math functions = add(x,y), sub(x,y), mult(x,y), div(x,y),
neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
group functions = mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group)
atom vectors for <I>equal</I> = mass[N], x[N], y[N], z[N],
vx[N], vy[N], vz[N],
fx[N], fy[N], fz[N]
atom vectors for <I>atom</I> = mass[], x[], y[], z[],
vx[], vy[], vz[],
fx[], fy[], fz[]
compute references = c_ID[0], c_ID[N]
other variables = v_abc, v_x, etc
</PRE>
</UL>
<P><B>Examples:</B>
</P>
<PRE>variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop 20
variable beta equal div(temp,3.0)
variable b1 equal add(x[234],mult(0.5,vol))
variable b equal div(xcm(mol1,x),2.0)
variable b equal c_myTemp[0]
variable b atom div(mult(x<B></B>,y<B></B>),vol)
variable temp world 300.0 310.0 320.0 330.0
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15
</PRE>
<P><B>Description:</B>
</P>
<P>This command assigns one or more strings to a variable name.
Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script. For variable styles that
store multiple strings, the <A HREF = "next.html">next</A> command can be used to
increment which string is assigned to the variable. Variables can be
evaluated to produce a numeric value which can be output either
directly (see the <A HREF = "print.html">print</A>, <A HREF = "fix_print.html">fix print</A>, and
<A HREF = "run.html">run every</A> commands) or as part of thermodynamic output (see
the <A HREF = "thermo_style.html">thermo_style</A> command), fix output (see the
<A HREF = "fix_ave_spatial.html">fix ave/spatial</A> and <A HREF = "compute_variable_atom.html">compute
variable/atom</A> commands), or dump output
(see the <A HREF = "dump.html">dump custom</A> and <A HREF = "compute_variable_atom.html">compute
variable/atom</A> commands).
</P>
<P>In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
The "string" is one of the subsequent arguments. The "value" is the
numeric quantity resulting from evaluation of the string. Note that
the same string can generate different values when it is evaluated at
different times during a simulation.
</P>
<P>IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script. This is to allow an input script to be processed multiple
times without resetting the variables; see the <A HREF = "jump.html">jump</A> or
<A HREF = "include.html">include</A> commands. It also means that using a
command-line switch -var will override a corresponding variable
setting in the input script.
</P>
<P>There is one exception to this rule. As described below, if a
variable is iterated on to the end of its list of strings via the
<A HREF = "next.html">next</A> command, it is available to be re-defined in a
subsequent variable command.
</P>
<HR>
<P><A HREF = "Section_commands.html#3_2">This section</A> of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as ${LoopVar} if the name
"LoopVar" is one or more characters.
</P>
<P>As described below, for variable styles <I>index</I>, <I>loop</I>, <I>universe</I>,
and <I>uloop</I>, the string assigned to a variable can be incremented via
the <A HREF = "next.html">next</A> command. When there are no more strings to
assign, the variable is "exhausted" and a flag is set that causes the
next <A HREF = "jump.html">jump</A> command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and exited from.
</P>
<HR>
<P>For the <I>index</I> style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
<A HREF = "next.html">next</A> command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
</P>
+<P><I>Index</I> style variables with a single string value can also be set by
+using the command-line switch -var; see <A HREF = "Section_start.html#2_6">this
+section</A> for details.
+</P>
<P>The <I>loop</I> style is identical to the <I>index</I> style except that the
strings are the integers from 1 to N. This allows generation of a
long list of runs (e.g. 1000) without having to list N strings in the
input script. Initially, the string "1" is assigned to the variable.
Each time a <A HREF = "next.html">next</A> command is used with the variable name,
the next string ("2", "3", etc) is assigned. All processors assign
the same string to the variable.
</P>
<P>For the <I>world</I> style, one or more strings are specified. There must
be one string for each processor partition or "world". See <A HREF = "Section_start.html#2_6">this
section</A> of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with <I>equal</I> style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
<A HREF = "temper.html">temper</A> command), to assign different temperatures to
different partitions.
</P>
<P>For the <I>universe</I> style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See <A HREF = "Section_start.html#2_6">this page</A> for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a <A HREF = "next.html">next</A> command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. <I>Universe</I> style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
</P>
<P>The <I>uloop</I> style is identical to the <I>universe</I> style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
</P>
<HR>
<P>For the <I>equal</I> and <I>atom</I> styles, a single string is specified which
represents an equation that will be evaluated afresh each time the
variable is used. For <I>equal</I> style variables this equation computes
a scalar quantity, which becomes the value of the variable whenever it
is evaluated. For <I>atom</I> style variables it computes a quantity for
each atom, which is used by the "compute variable/atom" command and
its associated output.
</P>
<P>Note that <I>equal</I> and <I>atom</I> variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an <I>equal</I> variable is used in a <A HREF = "fix_print.html">fix
print</A> command, different values could be printed each
timestep it was invoked.
</P>
-<P><I>Equal</I> style variables can also be set by using the command-line
-switch -var; see <A HREF = "Section_start.html#2_6">this section</A> for details.
-</P>
<P>The next command cannot be used with <I>equal</I> or <I>atom</I> style
variables, since there is only one string.
</P>
<P>The equation for an <I>equal</I> or <I>atom</I> variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable equation:
</P>
<PRE>variable x equal div(add(pe,c_MyTemp[0]),pow(vol,div(1,3)))
</PRE>
<P>Specifically, an equation can contain numbers, thermo keywords, math
functions, group functions, atom vectors, compute references, and
other variables. There is one difference between <I>equal</I> and <I>atom</I>
variables; the syntax of Atom vector references is different.
</P>
<DIV ALIGN=center><TABLE WIDTH="0%" BORDER=1 >
<TR><TD >Number</TD><TD > 0.2, 1.0e20, -15.4, etc</TD></TR>
<TR><TD >Thermo keywords</TD><TD > vol, pe, ebond, etc</TD></TR>
<TR><TD >Math functions</TD><TD > add(x,y), sub(x,y), mult(x,y), div(x,y), neg(x), pow(x,y), exp(x), ln(x), sqrt(x)</TD></TR>
<TR><TD >Group functions</TD><TD > mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim) bound(ID,dir), gyration(ID)</TD></TR>
<TR><TD >Atom vectors for <I>equal</I></TD><TD > mass[N], x[N], y[N], z[N], vx[N], vy[N], vz[N], fx[N], fy[N], fz[N]</TD></TR>
<TR><TD >Atom vectors for <I>atom</I></TD><TD > mass[], x[], y[], z[], vx[], vy[], vz[], fx[], fy[], fz[]</TD></TR>
<TR><TD >Compute references</TD><TD > c_ID[0], c_ID[N]</TD></TR>
<TR><TD >Other variables</TD><TD > v_abc, v_x, etc
</TD></TR></TABLE></DIV>
<P>The thermo keywords allowed in the equation are those defined by the
"thermo_style custom" command. Note that many thermodyanmic
quantities are only computable after the first simulation has begun.
Likewise, many thermodynamic quantities (such as energies) are only
computed on timesteps when thermodyanmic output is being performed.
If the variable equation these quantities at other times, out-of-date
or invalid values may be used.
</P>
<P>Math functions take one or two arguments, each of which may be an
equation containing any of the quantities defined above. This allows
equations to be nested, as in the examples above.
</P>
<P>Group functions take one or two arguments. The first argument is the
group-ID. The <I>dim</I> argument is <I>x</I> or <I>y</I> or <I>z</I>. The <I>dir</I>
argument is <I>xmin</I>, <I>xmax</I>, <I>ymin</I>, <I>ymax</I>, <I>zmin</I>, or <I>zmax</I>. The
group functions mass() and charge() are the total mass and charge of
the group of atoms. Xcm() and vcm() return components of the position
and velocity of the center of mass of the group. Fcm() returns a
component of the total force on the group of atoms. Bound() returns
the min/max of a particular coordinate for all atoms in the group.
Gyration() computes the radius-of-gyration of the group of atoms. See
the <A HREF = "fix_gyration.html">fix gyration</A> command for the formula.
</P>
<P>For <I>equal</I> style variables, atom vectors take a single integer
argument from 1-N, which is the desired atom-ID, e.g. x[243]. For
<I>atom</I> style variables, atom vectors take no argument. Since <I>atom</I>
style variables compute one value per atom, a reference like x[]
means the x-coord of each atom will be used when evaluating the
variable.
</P>
<P>Compute references access scalar or vector quantities calculated by a
<A HREF = "compute.html">compute</A>. The ID in the reference should be replaced by
the actual ID of the compute defined elsewhere in the input script.
See the <A HREF = "compute.html">compute</A> command for details. Note that
per-atom quantities calculated by a compute cannot be accessed this
way, but only global scalar or vector quantities.
</P>
<P>If <I>c_ID[0]</I> is used as a keyword, then the scalar quantity
calculated by the compute is printed. If <I>c_ID[N]</I> is used, then N
in the range from 1-M will print the Mth component of the N-length
vector calculated by the compute.
</P>
<P>The current values of other variables can be accessed by prepending a
"v_" to the variable name. This will cause the other variable to be
evaulated. Note that if you do something circular like this:
</P>
<PRE>variable a equal v_b
variable b equal v_a
print $a
</PRE>
<P>then LAMMPS will run for a while when the print statement is invoked.
</P>
<P>Note that there is a subtle difference between using a variable in a
<I>equal</I> or <I>atom</I> style equation in the form $x versus v_x.
</P>
<P>In the former case, as with any other input script command, the
variable's value is substituted for immediately when the line is read
from the input script. Thus if the current simulation box volume was
1000.0, then these lines:
</P>
<PRE>variable x equal vol
variable y equal mult($x,2)
</PRE>
<P>would associate the equation string "mult(1000.0,2)" with variable y.
</P>
<P>By contrast, these lines:
</P>
<PRE>variable x equal vol
variable y equal mult(v_x,2)
</PRE>
<P>would associate the equation string "mult(v_x,2)" with variable y.
</P>
<P>Thus if the variable y were evaluated periodically during a run where
the box volume changed, the resulting value would always be 2000.0 for
the first case, but would change dynamically for the second case.
</P>
<HR>
<P><B>Restrictions:</B>
</P>
<P>The use of atom vectors in <I>equal</I> style variables requires the atom
style to use a global mapping in order to look up the vector indices.
Only atom styles with molecular information create global maps unless
the <A HREF = "atom_modify.html">atom_modify map</A> command is used.
</P>
<P><B>Related commands:</B>
</P>
<P><A HREF = "next.html">next</A>, <A HREF = "jump.html">jump</A>, <A HREF = "include.html">include</A>,
<A HREF = "temper.html">temper</A>, <A HREF = "fix_print.html">fix print</A>, <A HREF = "print.html">print</A>
</P>
<P><B>Default:</B> none
</P>
</HTML>
diff --git a/doc/variable.txt b/doc/variable.txt
index 1c4e8250e..345939594 100644
--- a/doc/variable.txt
+++ b/doc/variable.txt
@@ -1,295 +1,296 @@
"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
variable command :h3
[Syntax:]
variable name style args ... :pre
name = name of variable to define :ulb,l
style = {index} or {loop} or {world} or {universe} or {uloop} or {equal} or {atom} :l
{index} args = one or more strings
{loop} args = N = integer size of loop
{world} args = one string for each partition of processors
{universe} args = one or more strings
{uloop} args = N = integer size of loop
{equal} or {atom} args = one equation containing numbers, thermo keywords, math functions, group functions, atom vectors, compute references, other variables
numbers = 0.0, -5.4, 2.8e-4, etc
thermo keywords = vol, ke, press, etc from "thermo_style"_thermo_style.html
math functions = add(x,y), sub(x,y), mult(x,y), div(x,y),
neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
group functions = mass(group), charge(group),
xcm(group,dim), vcm(group,dim), fcm(group,dim),
bound(group,xmin), gyration(group)
atom vectors for {equal} = mass\[N\], x\[N\], y\[N\], z\[N\],
vx\[N\], vy\[N\], vz\[N\],
fx\[N\], fy\[N\], fz\[N\]
atom vectors for {atom} = mass\[\], x\[\], y\[\], z\[\],
vx\[\], vy\[\], vz\[\],
fx\[\], fy\[\], fz\[\]
compute references = c_ID\[0\], c_ID\[N\]
other variables = v_abc, v_x, etc :pre
:ule
[Examples:]
variable x index run1 run2 run3 run4 run5 run6 run7 run8
variable LoopVar loop 20
variable beta equal div(temp,3.0)
variable b1 equal add(x\[234\],mult(0.5,vol))
variable b equal div(xcm(mol1,x),2.0)
variable b equal c_myTemp\[0\]
variable b atom div(mult(x[],y[]),vol)
variable temp world 300.0 310.0 320.0 330.0
variable x universe 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
variable x uloop 15 :pre
[Description:]
This command assigns one or more strings to a variable name.
Variables can be used in several ways in LAMMPS. A variable can be
referenced elsewhere in an input script. For variable styles that
store multiple strings, the "next"_next.html command can be used to
increment which string is assigned to the variable. Variables can be
evaluated to produce a numeric value which can be output either
directly (see the "print"_print.html, "fix print"_fix_print.html, and
"run every"_run.html commands) or as part of thermodynamic output (see
the "thermo_style"_thermo_style.html command), fix output (see the
"fix ave/spatial"_fix_ave_spatial.html and "compute
variable/atom"_compute_variable_atom.html commands), or dump output
(see the "dump custom"_dump.html and "compute
variable/atom"_compute_variable_atom.html commands).
In the discussion that follows, the "name" of the variable is the
arbitrary string that is the 1st argument in the variable command.
The "string" is one of the subsequent arguments. The "value" is the
numeric quantity resulting from evaluation of the string. Note that
the same string can generate different values when it is evaluated at
different times during a simulation.
IMPORTANT NOTE: When a variable command is encountered in the input
script and the variable name has already been specified, the command
is ignored. This means variables can NOT be re-defined in an input
script. This is to allow an input script to be processed multiple
times without resetting the variables; see the "jump"_jump.html or
"include"_include.html commands. It also means that using a
command-line switch -var will override a corresponding variable
setting in the input script.
There is one exception to this rule. As described below, if a
variable is iterated on to the end of its list of strings via the
"next"_next.html command, it is available to be re-defined in a
subsequent variable command.
:line
"This section"_Section_commands.html#3_2 of the manual explains how
occurrences of a variable name in an input script line are replaced by
the variable's string. The variable name can be referenced as $x if
the name "x" is a single character, or as $\{LoopVar\} if the name
"LoopVar" is one or more characters.
As described below, for variable styles {index}, {loop}, {universe},
and {uloop}, the string assigned to a variable can be incremented via
the "next"_next.html command. When there are no more strings to
assign, the variable is "exhausted" and a flag is set that causes the
next "jump"_jump.html command encountered in the input script to be
skipped. This enables the construction of simple loops in the input
script that are iterated over and exited from.
:line
For the {index} style, one or more strings are specified. Initially,
the 1st string is assigned to the variable. Each time a
"next"_next.html command is used with the variable name, the next
string is assigned. All processors assign the same string to the
variable.
+{Index} style variables with a single string value can also be set by
+using the command-line switch -var; see "this
+section"_Section_start.html#2_6 for details.
+
The {loop} style is identical to the {index} style except that the
strings are the integers from 1 to N. This allows generation of a
long list of runs (e.g. 1000) without having to list N strings in the
input script. Initially, the string "1" is assigned to the variable.
Each time a "next"_next.html command is used with the variable name,
the next string ("2", "3", etc) is assigned. All processors assign
the same string to the variable.
For the {world} style, one or more strings are specified. There must
be one string for each processor partition or "world". See "this
section"_Section_start.html#2_6 of the manual for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command assigns one string to each
world. All processors in the world are assigned the same string. The
next command cannot be used with {equal} style variables, since there
is only one value per world. This style of variable is useful when
you wish to run different simulations on different partitions, or when
performing a parallel tempering simulation (see the
"temper"_temper.html command), to assign different temperatures to
different partitions.
For the {universe} style, one or more strings are specified. There
must be at least as many strings as there are processor partitions or
"worlds". See "this page"_Section_start.html#2_6 for information on
running LAMMPS with multiple partitions via the "-partition"
command-line switch. This variable command initially assigns one
string to each world. When a "next"_next.html command is encountered
using this variable, the first processor partition to encounter it, is
assigned the next available string. This continues until all the
variable strings are consumed. Thus, this command can be used to run
50 simulations on 8 processor partitions. The simulations will be run
one after the other on whatever partition becomes available, until
they are all finished. {Universe} style variables are incremented
using the files "tmp.lammps.variable" and "tmp.lammps.variable.lock"
which you will see in your directory during such a LAMMPS run.
The {uloop} style is identical to the {universe} style except that the
strings are the integers from 1 to N. This allows generation of long
list of runs (e.g. 1000) without having to list N strings in the input
script.
:line
For the {equal} and {atom} styles, a single string is specified which
represents an equation that will be evaluated afresh each time the
variable is used. For {equal} style variables this equation computes
a scalar quantity, which becomes the value of the variable whenever it
is evaluated. For {atom} style variables it computes a quantity for
each atom, which is used by the "compute variable/atom" command and
its associated output.
Note that {equal} and {atom} variables can produce different values at
different stages of the input script or at different times during a
run. For example, if an {equal} variable is used in a "fix
print"_fix_print.html command, different values could be printed each
timestep it was invoked.
-{Equal} style variables can also be set by using the command-line
-switch -var; see "this section"_Section_start.html#2_6 for details.
-
The next command cannot be used with {equal} or {atom} style
variables, since there is only one string.
The equation for an {equal} or {atom} variable can contain a variety
of quantities. The syntax for each kind of quantity is simple, but
multiple quantities can be nested and combined in various ways to
build up formulas of arbitrary complexity. For example, this is a
valid (though strange) variable equation:
variable x equal div(add(pe,c_MyTemp\[0\]),pow(vol,div(1,3))) :pre
Specifically, an equation can contain numbers, thermo keywords, math
functions, group functions, atom vectors, compute references, and
other variables. There is one difference between {equal} and {atom}
variables; the syntax of Atom vector references is different.
Number: 0.2, 1.0e20, -15.4, etc
Thermo keywords: vol, pe, ebond, etc
Math functions: add(x,y), sub(x,y), mult(x,y), div(x,y), \
neg(x), pow(x,y), exp(x), ln(x), sqrt(x)
Group functions: mass(ID), charge(ID), xcm(ID,dim), vcm(ID,dim), fcm(ID,dim) \
bound(ID,dir), gyration(ID)
Atom vectors for {equal}: mass\[N\], x\[N\], y\[N\], z\[N\], \
vx\[N\], vy\[N\], vz\[N\], \
fx\[N\], fy\[N\], fz\[N\]
Atom vectors for {atom}: mass\[\], x\[\], y\[\], z\[\], \
vx\[\], vy\[\], vz\[\], \
fx\[\], fy\[\], fz\[\]
Compute references: c_ID\[0\], c_ID\[N\]
Other variables: v_abc, v_x, etc :tb(s=:)
The thermo keywords allowed in the equation are those defined by the
"thermo_style custom" command. Note that many thermodyanmic
quantities are only computable after the first simulation has begun.
Likewise, many thermodynamic quantities (such as energies) are only
computed on timesteps when thermodyanmic output is being performed.
If the variable equation these quantities at other times, out-of-date
or invalid values may be used.
Math functions take one or two arguments, each of which may be an
equation containing any of the quantities defined above. This allows
equations to be nested, as in the examples above.
Group functions take one or two arguments. The first argument is the
group-ID. The {dim} argument is {x} or {y} or {z}. The {dir}
argument is {xmin}, {xmax}, {ymin}, {ymax}, {zmin}, or {zmax}. The
group functions mass() and charge() are the total mass and charge of
the group of atoms. Xcm() and vcm() return components of the position
and velocity of the center of mass of the group. Fcm() returns a
component of the total force on the group of atoms. Bound() returns
the min/max of a particular coordinate for all atoms in the group.
Gyration() computes the radius-of-gyration of the group of atoms. See
the "fix gyration"_fix_gyration.html command for the formula.
For {equal} style variables, atom vectors take a single integer
argument from 1-N, which is the desired atom-ID, e.g. x\[243\]. For
{atom} style variables, atom vectors take no argument. Since {atom}
style variables compute one value per atom, a reference like x\[\]
means the x-coord of each atom will be used when evaluating the
variable.
Compute references access scalar or vector quantities calculated by a
"compute"_compute.html. The ID in the reference should be replaced by
the actual ID of the compute defined elsewhere in the input script.
See the "compute"_compute.html command for details. Note that
per-atom quantities calculated by a compute cannot be accessed this
way, but only global scalar or vector quantities.
If {c_ID\[0\]} is used as a keyword, then the scalar quantity
calculated by the compute is printed. If {c_ID\[N\]} is used, then N
in the range from 1-M will print the Mth component of the N-length
vector calculated by the compute.
The current values of other variables can be accessed by prepending a
"v_" to the variable name. This will cause the other variable to be
evaulated. Note that if you do something circular like this:
variable a equal v_b
variable b equal v_a
print $a :pre
then LAMMPS will run for a while when the print statement is invoked.
Note that there is a subtle difference between using a variable in a
{equal} or {atom} style equation in the form $x versus v_x.
In the former case, as with any other input script command, the
variable's value is substituted for immediately when the line is read
from the input script. Thus if the current simulation box volume was
1000.0, then these lines:
variable x equal vol
variable y equal mult($x,2) :pre
would associate the equation string "mult(1000.0,2)" with variable y.
By contrast, these lines:
variable x equal vol
variable y equal mult(v_x,2) :pre
would associate the equation string "mult(v_x,2)" with variable y.
Thus if the variable y were evaluated periodically during a run where
the box volume changed, the resulting value would always be 2000.0 for
the first case, but would change dynamically for the second case.
:line
[Restrictions:]
The use of atom vectors in {equal} style variables requires the atom
style to use a global mapping in order to look up the vector indices.
Only atom styles with molecular information create global maps unless
the "atom_modify map"_atom_modify.html command is used.
[Related commands:]
"next"_next.html, "jump"_jump.html, "include"_include.html,
"temper"_temper.html, "fix print"_fix_print.html, "print"_print.html
[Default:] none