ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
sjplimp
2011-08-18 17:31:58 +00:00
parent bb37321e9f
commit 6b0cca4397
2 changed files with 565 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

595
doc/Section_start.html
View File

@ -72,26 +72,28 @@ as described in the next section.
<P>This section has the following sub-sections:
</P>
<UL><LI><A HREF = "#2_2_1">Read this first</A>
<LI><A HREF = "#2_2_2">Building a LAMMPS executable</A>
<LI><A HREF = "#2_2_2">Steps to build a LAMMPS executable</A>
<LI><A HREF = "#2_2_3">Common errors that can occur when making LAMMPS</A>
<LI><A HREF = "#2_2_4">Editing a new low-level Makefile</A>
<LI><A HREF = "#2_2_5">Additional build tips</A>
<LI><A HREF = "#2_2_6">Building for a Mac</A>
<LI><A HREF = "#2_2_7">Building for Windows</A>
<LI><A HREF = "#2_2_4">Additional build tips</A>
<LI><A HREF = "#2_2_5">Building for a Mac</A>
<LI><A HREF = "#2_2_6">Building for Windows</A>
</UL>
<HR>
<A NAME = "2_2_1"></A><B><I>Read this first:</I></B>
<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, JPEG), etc. Please read this section carefully. If you
are not comfortable with makefiles, or building codes on a Unix
platform, or running an MPI job on your machine, please find a local
expert to help you. Many compiling, linking, and run problems that
users are not really LAMMPS issues - they are peculiar to the user's
system, compilers, libraries, etc. Such questions are better answered
by a local expert.
<P>Building LAMMPS can be non-trivial. You may need to edit a makefile,
there are compiler options to consider, additional libraries can be
used (MPI, FFT, JPEG), LAMMPS packages may be included or excluded,
some of these packages use auxiliary libraries which need to be
pre-built, etc.
</P>
<P>Please read this section carefully. If you are not comfortable with
makefiles, or building codes on a Unix platform, or running an MPI job
on your machine, please find a local expert to help you. Many
compiling, linking, and run problems that users have are not really
LAMMPS issues - they are peculiar to the user's system, compilers,
libraries, etc. Such questions are better answered by a local expert.
</P>
<P>If you have a build problem that you are convinced is a LAMMPS issue
(e.g. the compiler complains about a line of LAMMPS source code), then
@ -104,16 +106,19 @@ to the developers and we'll include it in future LAMMPS releases.
</P>
<HR>
<A NAME = "2_2_2"></A><B><I>Building a LAMMPS executable:</I></B>
<A NAME = "2_2_2"></A><B><I>Steps to build a LAMMPS executable:</I></B>
<P><B>Step 0</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 sub-directory with
low-level Makefile.* files for several machines. From within the src
low-level Makefile.* files for many 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
or
gmake mac
</PRE>
<P>Note that on a multi-processor or multi-core platform you can launch a
@ -123,62 +128,27 @@ will build LAMMPS more quickly.
<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>
<HR>
<A NAME = "2_2_3"></A><B><I>Common errors that can occur when making LAMMPS:</I></B>
<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>Note that by default only a few of LAMMPS optional pacakges are
installed. To build LAMMPS with optional packages, see <A HREF = "#2_3">this
section</A> below.
</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><B>Step 1</B>
</P>
<P>(2) If you get an error that says something like 'identifier "atoll"
is undefined', then your machine does not support "long long"
integers, and you need to edit the src/lmptype.h file. There is a
comment in the file about what to do. Basically you replace
MPI_LONG_LONG with MPI_LONG and atoll with atol.
<P>If Step 0 did not work, you will need to create a low-level Makefile
for your machine, like Makefile.foo. You should make a copy of an
existing src/MAKE/Makefile.* as a starting point. The only portions
of the file you need to edit are the first line, the "compiler/linker
settings" section, and the "LAMMPS-specific settings" section.
</P>
<P>(3) Other errors typically occur because the low-level Makefile isn't
setup correctly for your machine. If your platform is named "foo",
you will need to create a Makefile.foo in the MAKE sub-directory. Use
whatever existing file is closest to your platform as a starting
point. See the next section for more instructions.
<P><B>Step 2</B>
</P>
<P>(4) If you get a link-time error about missing libraries or missing
dependencies, then it can be because:
<P>Change the first line of src/MAKE/Makefile.foo to list the word "foo"
after the "#", and whatever other options it will set. This is the
line you will see if you just type "make".
</P>
<UL><LI>you are including a package that needs an extra library, but have not pre-built the necessary <A HREF = "#2_3_3">package library</A>
<LI>you are linking to a library that doesn't exist on your system
<LI>you are not linking to the necessary system library
</UL>
<P>The first issue is discussed below. The other two issue mean you need
to edit your low-level Makefile.foo, as discussed in the next
sub-section.
<P><B>Step 3</B>
</P>
<HR>
<A NAME = "2_2_4"></A><B><I>Editing a new low-level Makefile.foo:</I></B>
<P>These are the issues you need to address when editing a low-level
Makefile for your machine. The portions of the file you typically
need to edit are the first line, the "compiler/linker settings"
section, and the "system-specific settings" section.
</P>
<P>(1) Change the first line of Makefile.foo to list the word "foo" after
the "#", and whatever other options you set. This is the line you
will see if you just type "make".
</P>
<P>(2) The "compiler/linker settings" section lists compiler and linker
<P>The "compiler/linker settings" section lists compiler and linker
settings for your C++ compiler, including optimization flags. You can
use g++, the open-source GNU compiler, which is available on all Unix
systems. You can also use mpicc which will typically be available if
@ -204,11 +174,15 @@ on a new platform, a long list of *.d files will be printed out
rapidly. This is not an error; it is the Makefile doing its normal
creation of dependencies.
</P>
<P>(3) The "system-specific settings" section has 6 parts.
<P><B>Step 4</B>
</P>
<P>(3.a) The LMP_INC variable is used to include options that turn on
system-dependent ifdefs within the LAMMPS code. The settings
that are currently recogized are:
<P>The "system-specific settings" section has several parts. Note that
if you change any -D setting in this section, you should do a full
re-compile, after typing "make clean" (which will describe different
clean options).
</P>
<P>The LMP_INC variable is used to include options that turn on ifdefs
within the LAMMPS code. The options that are currently recogized are:
</P>
<UL><LI>-DLAMMPS_GZIP
<LI>-DPACK_ARRAY
@ -236,18 +210,27 @@ Restrictions section of the <A HREF = "dump.html">dump</A> command for details.
<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 text-based 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.
link LAMMPS with a JPEG library, as described below.
</P>
<P>(3.b) The 3 MPI variables are used to specify an MPI library to build
LAMMPS with.
<P><B>Step 5</B>
</P>
<P>The 3 MPI variables are used to specify an MPI library to build LAMMPS
with.
</P>
<P>If you want LAMMPS to run in parallel, you must have an MPI library
installed on your platform. If you use an MPI-wrapped compiler, such
as "mpicc" to build LAMMPS, you can probably leave these 3 variables
blank. If you do not use "mpicc" as your compiler/linker, then you
need to specify where the mpi.h file (MPI_INC) and the MPI library
(MPI_PATH) is found and its name (MPI_LIB).
as "mpicc" to build LAMMPS, you should be able to leave these 3
variables blank; the MPI wrapper knows where to find the needed files.
If not, and MPI is installed on your system in the usual place (under
/usr/local), you also may not need to specify these 3 variables. On
some large parallel machines which use "modules" for their
compile/link environements, you may simply need to include the correct
module in your build environment. Or the parallel machine may have a
vendor-provided MPI which the compiler has no trouble finding.
</P>
<P>Failing this, with these 3 variables you can specify where the mpi.h
file (MPI_INC) and the MPI library file (MPI_PATH) are found and the
name of the library file (MPI_LIB).
</P>
<P>If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
or 2.0 or OpenMPI. MPICH can be downloaded from the <A HREF = "http://www-unix.mcs.anl.gov/mpi">Argonne MPI
@ -262,100 +245,154 @@ should have compiler options to enable you to use the same compiler
you are using for the LAMMPS build, which can avoid problems that can
arise when linking LAMMPS to the MPI library.
</P>
<P>If you just want LAMMPS to run on a single processor, you can use the
STUBS library in place of MPI, since you don't need 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
dir, type "make" and it will hopefully create a libmpi.a suitable for
linking to LAMMPS. If this build fails, you will need to edit the
STUBS/Makefile for your platform.
<P>If you just want to run LAMMPS on a single processor, you can use the
dummy MPI library provided in src/STUBS, since you don't need a true
MPI library installed on your system. See the
src/MAKE/Makefile.serial file for how to specify the 3 MPI variables
in this case. You will also need to build the STUBS library for your
platform before making LAMMPS itself. From the src directory, type
"make stubs", or from the STUBS dir, type "make" and it should create
a libmpi.a suitable for linking to LAMMPS. If this 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 simulations.
<P>The file STUBS/mpi.cpp provides a CPU timer function called
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
simulations.
</P>
<P>(3.c) The 3 FFT variables are used to specify an FFT library which
LAMMPS uses when using the particle-particle particle-mesh (PPPM)
option in LAMMPS for long-range Coulombics via the
<P><B>Step 6</B>
</P>
<P>The 3 FFT variables allow you to specify an FFT library which LAMMPS
uses (for performing 1d FFTs) when running the particle-particle
particle-mesh (PPPM) option for long-range Coulombics via the
<A HREF = "kspace_style.html">kspace_style</A> command.
</P>
<P>LAMMPS supports various open-source or vendor-supplied libraries for
this purpose. You need to set the appropriate FFT_INC, FFT_PATH, and
FFT_LIB variables, so the compiler and linker can find the needed
files.
<P>LAMMPS supports various open-source or vendor-supplied FFT libraries
for this purpose. If you leave these 3 variables blank, LAMMPS will
use the open-source <A HREF = "http://kissfft.sf.net">KISS FFT library</A>, which is
included in the LAMMPS distribution. This library is portable to all
platforms and for typical LAMMPS simulations is almost as fast as FFTW
or vendor optimized libraries. If you are not including the KSPACE
package in your build, you can also leave the 3 variables blank.
</P>
<P>If nothing is specified for these 3 variables, LAMMPS uses an internal
FFT library which is derived from <A HREF = "http://kissfft.sf.net">KISSFFT</A>.
This library is portable to all platforms and for typical LAMMPS
simulations it is almost as fast as vendor optimized libraries.
<P>Otherwise, select which kinds of FFTs to use as part of the FFT_INC
setting by a switch of the form -DFFT_XXX. Recommended values for XXX
are: MKL, SCSL, FFTW2, and FFTW3. Legacy options are: INTEL, SGI,
ACML, and T3E. For backward compatability, using -DFFT_FFTW will use
the FFTW2 library. Using -DFFT_NONE will use the KISS library
described above.
</P>
<P>Other open-source or vendor-supplied FFT libaries can be specified as
part of the FFT_INC setting by a switch of the form -DFFT_XXX where
recommended values for XXX are: MKL, SCSL, FFTW2, FFTW3 or NONE.
Legacy options are: INTEL, SGI, ACML, and T3E. For backward
compatability, using -DFFT_FFTW will use the FFTW2 library. Using
-DFFT_NONE will use the KISS library described above.
<P>You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables,
so the compiler and linker can find the needed FFT header and library
files. Note that on some large parallel machines which use "modules"
for their compile/link environements, you may simply need to include
the correct module in your build environment. Or the parallel machine
may have a vendor-provided FFT library which the compiler has no
trouble finding.
</P>
<P>FFTW is a fast, portable library that should also work on any
platform. You can download it from
<A HREF = "http://www.fftw.org">www.fftw.org</A>. Both, the legacy version 2.1.X
and the newer 3.X versions are supported as -DFFT_FFTW2 or
-DFFT_FFTW3. Building FFTW for your box should be as simple as
./configure; make. Note that on some platforms FFTW2 has been
pre-installed, and uses renamed files indicating the precision it was
compiled with, e.g. sfftw.h, or dfftw.h instead of fftw.h. In this
case, you can specify an additional define variable for FFT_INC in
your lo-level LAMMPS Makefile, called -DFFTW2_SIZE, which will select
the correct include file. In this case, For FFT_LIB you still must
manually specify the correct -lsfftw or -ldfftw.
<A HREF = "http://www.fftw.org">www.fftw.org</A>. Both the legacy version 2.1.X and
the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3.
Building FFTW for your box should be as simple as ./configure; make.
Note that on some platforms FFTW2 has been pre-installed, and uses
renamed files indicating the precision it was compiled with,
e.g. sfftw.h, or dfftw.h instead of fftw.h. In this case, you can
specify an additional define variable for FFT_INC called -DFFTW2_SIZE,
which will select the correct include file. In this case, for FFT_LIB
you must also manually specify the correct library, namely -lsfftw or
-ldfftw.
</P>
<P>(3.d) The FFT_INC variable also allows for a -DFFT_SINGLE setting that
will use single-precision FFTs with PPPM, which can speed-up
long-range calulations, particularly in parallel or on GPUs. Fourier
transform and related PPPM operations are somewhat insensitive to
floating point truncation errors and thus do not always need to be
performed in double precision. Using the -DFFT_SINGLE setting trades
off a little accuracy for reduced memory use and parallel
communication costs for transposing 3d FFT data. Note that single
precision FFTs have only been tested with the FFTW3, FFTW2, MKL, and
the internal KISS FFTs options.
<P>The FFT_INC variable also allows for a -DFFT_SINGLE setting that will
use single-precision FFTs with PPPM, which can speed-up long-range
calulations, particularly in parallel or on GPUs. Fourier transform
and related PPPM operations are somewhat insensitive to floating point
truncation errors and thus do not always need to be performed in
double precision. Using the -DFFT_SINGLE setting trades off a little
accuracy for reduced memory use and parallel communication costs for
transposing 3d FFT data. Note that single precision FFTs have only
been tested with the FFTW3, FFTW2, MKL, and KISS FFT packages.
</P>
<P>(3.e) 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><B>Step 7</B>
</P>
<P>The 3 JPG variables allow you to specify a JPEG library which LAMMPS
uses when writing out JPEG files via the <A HREF = "dump_image.html">dump image</A>
command. These can be left blank if you do not use the -DLAMMPS_JPEG
switch discussed above in Step 4, since in that case JPEG output will
be disabled.
</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.
and JPG_LIB variables, 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
below</A> for more details. The SYSLIB variables list the system
libraries. The SYSPATH variables are where they are located on your
machine, which is typically only needed if they are in some
non-standard place, that is not in your library search path.
<P>As before, if these header and library files are in the usual place on
your machine, you may not need to set these variables.
</P>
<P>That's it. Once you have a correct Makefile.foo and you have
pre-built any other libraries it will use (e.g. MPI, FFT, package
libraries), all you need to do from the src directory is type one of
these 2 commands:
<P><B>Step 8</B>
</P>
<P>Note that by default only a few of LAMMPS optional pacakges are
installed. To build LAMMPS with optional packages, see <A HREF = "#2_3">this
section</A> below, before proceeding to Step 9.
</P>
<P><B>Step 9</B>
</P>
<P>That's it. Once you have a correct Makefile.foo, you have installed
the optional LAMMPS packages you want to include in your build, and
you have pre-built any other needed libraries (e.g. MPI, FFT, package
libraries), all you need to do from the src directory is type
something like this:
</P>
<PRE>make foo
or
gmake foo
</PRE>
<P>You should get the executable lmp_foo when the build is complete.
</P>
<HR>
<A NAME = "2_2_5"></A><B><I>Additional build tips:</I></B>
<A NAME = "2_2_3"></A><B><I>Errors that can occur when making LAMMPS:</I></B>
<P>IMPORTANT NOTE: If an error occurs when building LAMMPS, the compiler
or linker will state very explicitly what the problem is. The error
message should give you a hint as to which of the steps above has
failed, and what you need to do in order to fix it. Building a code
with a Makefile is a very logical process. The compiler and linker
need to find the appropriate files and those files need to be
compatible with LAMMPS source files. When a make fails, there is
usually a very simple reason, which you or a local expert will need to
fix.
</P>
<P>Here are two non-obvious errors that can occur:
</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 native 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 a pre-generated
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. Note that you should
include/exclude any desired optional packages before using the "make
makelist" command.
</P>
<P>(2) If you get an error that says something like 'identifier "atoll"
is undefined', then your machine does not support "long long"
integers, and you need to edit the src/lmptype.h file. There is a
comment in the file about what to do. Basically you replace
MPI_LONG_LONG with MPI_LONG and atoll with atol.
</P>
<HR>
<A NAME = "2_2_4"></A><B><I>Additional build tips:</I></B>
<P>(1) Building LAMMPS for multiple platforms.
</P>
@ -410,13 +447,13 @@ secs/timestep.
</P>
<HR>
<A NAME = "2_2_6"></A><B><I>Building for a Mac:</I></B>
<A NAME = "2_2_5"></A><B><I>Building for a Mac:</I></B>
<P>OS X is BSD Unix, so it should just work. See the Makefile.mac file.
</P>
<HR>
<A NAME = "2_2_7"></A><B><I>Building for Windows:</I></B>
<A NAME = "2_2_6"></A><B><I>Building for Windows:</I></B>
<P>The LAMMPS download page has an option to download both a serial and
parallel pre-built Windows exeutable. See the <A HREF = "#2_5">Running LAMMPS</A>
@ -459,12 +496,11 @@ and USER-REAXC. The fourth project includes the USER-AWPMD package.
<A NAME = "2_3_1"></A><B><I>Package basics:</I></B>
<P>The source code for LAMMPS is structured as a large set of core files
which are always included, plus optional packages. Packages 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 all packages by typing "make
package".
<P>The source code for LAMMPS is structured as a set of core files which
are always included, plus optional packages. Packages 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 all packages by typing "make package".
</P>
<P>The current list of standard packages is as follows:
</P>
@ -490,12 +526,13 @@ package".
<TR><TD >xtc </TD><TD > dump atom snapshots in XTC format
</TD></TR></TABLE></DIV>
<P>There are also user-contributed packages which may be as simple as a
single additional file (see the src/USER-MISC directory) or many files
grouped together which add a specific functionality to the code.
<P>There are also several user-contributed packages which may be as
simple as a single additional file (see the src/USER-MISC directory)
or many files grouped together which add a specific functionality to
the code.
</P>
<P>The difference between a <I>standard</I> package versus a <I>user</I> package is
as follows.
as follows:
</P>
<P>Standard packages are supported by the LAMMPS developers and are
written in a syntax and style consistent with the rest of LAMMPS.
@ -513,19 +550,28 @@ documentation.
<A NAME = "2_3_2"></A><B><I>Including/excluding packages:</I></B>
<P>To use or not use a package you must be include or exclude it before
LAMMPS is built.
<P>To use or not use a package you must include or exclude it before
building LAMMPS. From the src directory, this is typically as simple
as:
</P>
<PRE>make yes-colloid
make g++
</PRE>
<P>or
</P>
<PRE>make no-manybody
make g++
</PRE>
<P>Some packages have individual files that depend on other packages
being included, but LAMMPS checks for this and does the right thing.
being included. LAMMPS checks for this and does the right thing.
I.e. individual files are only included if their dependencies are
already included. Likewise, if a package is excluded, other files
dependent on that package are also excluded.
</P>
<P>The reason to exclude packages is if you will never run certain kinds
of simulations. This will keep you from having to build auxiliary
libraries (see below) and will produce a smaller executable which may
run a bit faster.
of simulations. For some packages, this will keep you from having to
build auxiliary libraries (see below), and will also produce a smaller
executable which may run a bit faster.
</P>
<P>By default, LAMMPS includes only the "kspace", "manybody", and
"molecule" packages.
@ -537,168 +583,90 @@ no-user", "make yes-all" or "make no-all" to include/exclude various
sets of packages. Type "make package" to see the all of the
package-related make options.
</P>
<P>IMPORTANT NOTE: These make 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-build LAMMPS.
<P>IMPORTANT NOTE: Inclusion/exclusion of a package works by simply
moving files back and forth between the main src directory and
sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC),
so that the files are seen or not seen when LAMMPS is built. After
you have included or excluded a package, you must re-build LAMMPS.
</P>
<P>Additional package-related 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.
<P>Additional package-related 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.
</P>
<P>Typing "make package-update" will overwrite src files with files from
the package sub-directories if the package has been included. It should
be used after a patch is installed, since patches only update the
files in the package sub-directory, but not the src files.
Typing "make package-overwrite"
will overwrite files in the package sub-directories with src files.
the package sub-directories if the package has been included. It
should be used after a patch is installed, since patches only update
the files in the package sub-directory, but not the src files. Typing
"make package-overwrite" will overwrite files in the package
sub-directories with src files.
</P>
<P>Typing "make package-status" will show which packages are currently
included. Of those that are included, it will list files that
are different in the src directory and package sub-directory.
Typing "make package-diff" lists all differences between these files.
Again, type "make package" to see all of the
package-related make options.
included. Of those that are included, it will list files that are
different in the src directory and package sub-directory. Typing
"make package-diff" lists all differences between these files. Again,
type "make package" to see all of the package-related make options.
</P>
<HR>
<A NAME = "2_3_3"></A><B><I>Packages that require extra LAMMPS libraries:</I></B>
<P>A few standard or user packages require that additional libraries be
compiled first, which LAMMPS will link to when it builds. The source
code for these libraries is included in the LAMMPS distribution under
the "lib" directory. Look at the README files in the lib directories
(e.g. lib/reax/README) for instructions on how to build each library.
<P>A few of the standard and user packages require additional auxiliary
libraries be compiled first. If you get a LAMMPS build error about a
missing library, this is likely the reason. The source code for these
libraries is included in the LAMMPS distribution under the "lib"
directory. Look at the lib/README file for a list of these.
</P>
<P>IMPORTANT NOTE: If you are including a package in your LAMMPS build
that uses one of these libraries, then you must build the library
BEFORE building LAMMPS itself, since the LAMMPS build will attempt to
link with the library file.
</P>
<P>Here is a bit of information about each library:
</P>
<P>The "atc" library in lib/atc is used by the user-atc package. It
provides continuum field estimation and molecular dynamics-finite
element coupling methods. It was written by Reese Jones, Jeremy
Templeton and Jonathan Zimmerman at Sandia.
</P>
<P>The "cuda" library in lib/cuda is used by the user-cuda package. It
was written by Christian Trott at U of Technology Ilmenau in Germany.
It contains code to enable portions of LAMMPS to run on NVIDIA GPUs
associated with your CPUs. Currently, only NVIDIA GPUs are supported.
Building this library requires NVIDIA Cuda tools to be installed on
your system. See <A HREF = "Section_accelerate.html#10_3">this section</A> of the
manual for more information about using this package effectively and
how it differs from the gpu package.
</P>
<P>The "gpu" library in lib/gpu is used by the gpu package. It was
written by Mike Brown at ORNL. It contains code to enable portions of
LAMMPS to run on GPUs associated with your CPUs. Currently, only
NVIDIA GPUs are supported, but eventually this may be extended to
OpenCL. Building this library requires NVIDIA Cuda tools to be
installed on your system. See <A HREF = "Section_accelerate.html#10_2">this
section</A> of the manual for more
information about using this package effectively and how it differs
from the user-cuda package.
</P>
<P>The "meam" library in lib/meam is used by the meam package. It was
written by Greg Wagner at Sandia. It 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. It requires a
F90 compiler to build. The C++ to FORTRAN function calls in
pair_meam.cpp assumes that FORTRAN object names are converted to C
object names by appending an underscore character. This is generally
the case, but on machines that do not conform to this convention, you
will need to modify either the C++ code or your compiler settings.
</P>
<P>The "poems" library in lib/poems is used by the poems package. It was
written by Rudra Mukherjee at JPL. It computes the constrained
rigid-body motion of articulated (jointed) multibody systems. POEMS
is distributed by Prof Kurt Anderson's group at Rensselaer Polytechnic
Institute (RPI).
</P>
<P>The "reax" library in lib/reax is used by the reax package. It was
written by Aidan Thompson at Sandia. It computes the Reactive Force
Field (ReaxFF) potential, developed by Adri van Duin in Bill Goddard's
group at CalTech. This implementation in LAMMPS uses many of Adri's
files and was developed by Aidan Thompson at Sandia and Hansohl Cho at
MIT. It requires a F77 or F90 compiler to build. The C++ to FORTRAN
function calls in pair_reax.cpp assume that FORTRAN object names are
converted to C object names by appending an underscore character. This
is generally the case, but on machines that do not conform to this
convention, you will need to modify either the C++ code or your
compiler settings. The name conversion is handled by the preprocessor
macro called FORTRAN in pair_reax_fortran.h. Different definitions of
this macro can be obtained by adding a machine-specific macro
definition to the CCFLAGS variable in your Makefile e.g. -D_IBM. See
pair_reax_fortran.h for more info.
</P>
<P>As described in the README file in each lib directory, each library is
typically built by typing something like
<P>Each lib directly has a README file (e.g. lib/reax/README) with
instructions on how to build that library. Typically this is done by
typing something like:
</P>
<PRE>make -f Makefile.g++
</PRE>
<P>in the appropriate directory, e.g. in lib/reax.
<P>in the appropriate directory, e.g. in lib/reax. Some of the libraries
do not build this way. Again, see the libary README file for details.
</P>
<P>You must use a Makefile that is a match for your system. If one of
the provided Makefiles is not appropriate for your system you will
need to edit or add one. For example, in the case of Fotran-based
libraries, your system must have a Fortran compiler, the settings for
which will be in the Makefile.
<P>In any event, you will need to use a Makefile that is a match for your
system. If one of the provided Makefiles is not appropriate for your
system you will need to edit or add one. For example, in the case of
Fortran-based libraries, your system must have a Fortran compiler, the
settings for which will need to be listed in the Makefile.
</P>
<P>Note that the cuda library, used by the user-cuda package is an
exception. See its README file and <A HREF = "Section_accelerate.html#10_3">this
section</A> of the manual for instructions
on how to build it.
<P>When you have built one of these libraries, there are 2 things to
check:
</P>
<HR>
<A NAME = "2_3_4"></A><B><I>Additional Makefile settings for extra libraries:</I></B>
<P>After the desired library or libraries are built, and the package has
been included, you can build LAMMPS itself. For example, from the
lammps/src directory you would type this, to build LAMMPS with ReaxFF.
Note that as discussed in the preceding section, the package library
itself, namely lib/reax/libreax.a, must already have been built, for
the LAMMPS build to be successful.
<P>(1) The file libname.a should now exist in lib/name.
E.g. lib/reax/libreax.a. This is the library file LAMMPS will link
against. One exception is the lib/cuda library which produces the
file liblammpscuda.a, because there is already a system library
libcuda.a.
</P>
<PRE>make yes-reax
make g++
</PRE>
<P>Also note that simply building the library is not sufficient to use it
from LAMMPS. As in this example, you must also include the package
that uses and wraps the library before you build LAMMPS itself.
<P>(2) The file Makefile.lammps should exist in lib/name. E.g.
lib/cuda/Makefile.lammps. This file may be auto-generated by the
build of the library, or you may need to make a copy of the
appropriate provided file (e.g. lib/meam/Makefile.lammps.gfortran).
Either way you should insure that the settings in this file are
appropriate for your system.
</P>
<P>As discussed in point (3.e) of <A HREF = "#2_2_4">this section</A> above, there are
settings in the low-level Makefile that specify additional system
libraries needed by some of the LAMMPS add-on libraries. These are
the settings you must specify correctly in your low-level Makefile in
lammps/src/MAKE, such as Makefile.foo:
<P>There are typically 3 settings in the Makefile.lammps file (unless
some are blank or not needed): a SYSINC, SYSPATH, and SYSLIB setting,
specific to this package. These are settings the LAMMPS build will
import when compiling the LAMMPS package files (not the library
files), and linking to the auxiliary library. They typically list any
other system libraries needed to support the package and where to find
them. An example is the BLAS and LAPACK libraries needed by the
USER-ATC package. Or the system libraries that support calling
Fortran from C++, as the MEAM and REAX packages do.
</P>
<P>To use the gpu package and library, the settings for gpu_SYSLIB and
gpu_SYSPATH must be correct. These are specific to the NVIDIA CUDA
software which must be installed on your system.
</P>
<P>To use the meam or reax packages and their libraries which are Fortran
based, the settings for meam_SYSLIB, reax_SYSLIB, meam_SYSPATH, and
reax_SYSPATH must be correct. This is so that the C++ compiler can
perform a cross-language link using the appropriate system Fortran
libraries.
</P>
<P>To use the user-atc package and atc library, the settings for
user-atc_SYSLIB and user-atc_SYSPATH must be correct. This is so that
the appropriate BLAS and LAPACK libs, used by the user-atc library,
can be found.
<P>Note that if these settings are not correct for your box, the LAMMPS
build will likely fail.
</P>
<HR>
<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
<P>LAMMPS itself 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
@ -706,13 +674,14 @@ other codes. Building LAMMPS as a library is done by typing
<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>where foo is the machine name. Note that inclusion or exclusion of
any desired optional packages should be done before typing "make
makelib". 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
@ -768,8 +737,8 @@ on various platforms.
<HR>
<P>On a Windows box, you can skip making LAMMPS and simply download an
executable, as described above. though the pre-packaged executables
make only certain packages available.
executable, as described above, though the pre-packaged executables
include only certain packages.
</P>
<P>To run a LAMMPS executable on a Windows machine, first decide whether
you want to download the non-MPI (serial) or the MPI (parallel)
@ -851,8 +820,8 @@ more processors or setup a smaller problem.
<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. Either the full word or a one-letter
abbreviation can be used:
which may be used in any order. Either the full word or a one-or-two
letter abbreviation can be used:
</P>
<UL><LI>-c or -cuda
<LI>-e or -echo