git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@6726 f3b2605a-c512-4ea7-a41b-209d697bcdaa
This commit is contained in:
sjplimp
@ -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
|
||||
|
||||
@ -67,26 +67,28 @@ as described in the next section.
|
||||
This section has the following sub-sections:
|
||||
|
||||
"Read this first"_#2_2_1
|
||||
"Building a LAMMPS executable"_#2_2_2
|
||||
"Steps to build a LAMMPS executable"_#2_2_2
|
||||
"Common errors that can occur when making LAMMPS"_#2_2_3
|
||||
"Editing a new low-level Makefile"_#2_2_4
|
||||
"Additional build tips"_#2_2_5
|
||||
"Building for a Mac"_#2_2_6
|
||||
"Building for Windows"_#2_2_7 :ul
|
||||
"Additional build tips"_#2_2_4
|
||||
"Building for a Mac"_#2_2_5
|
||||
"Building for Windows"_#2_2_6 :ul
|
||||
|
||||
:line
|
||||
|
||||
[{Read this first:}] :link(2_2_1)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
@ -99,16 +101,19 @@ to the developers and we'll include it in future LAMMPS releases.
|
||||
|
||||
:line
|
||||
|
||||
[{Building a LAMMPS executable:}] :link(2_2_2)
|
||||
[{Steps to build a LAMMPS executable:}] :link(2_2_2)
|
||||
|
||||
[Step 0]
|
||||
|
||||
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:
|
||||
|
||||
make linux
|
||||
or
|
||||
gmake mac :pre
|
||||
|
||||
Note that on a multi-processor or multi-core platform you can launch a
|
||||
@ -118,62 +123,27 @@ will build LAMMPS more quickly.
|
||||
If you get no errors and an executable like lmp_linux or lmp_mac is
|
||||
produced, you're done; it's your lucky day.
|
||||
|
||||
:line
|
||||
Note that by default only a few of LAMMPS optional pacakges are
|
||||
installed. To build LAMMPS with optional packages, see "this
|
||||
section"_#2_3 below.
|
||||
|
||||
[{Common errors that can occur when making LAMMPS:}] :link(2_2_3)
|
||||
[Step 1]
|
||||
|
||||
(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.
|
||||
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.
|
||||
|
||||
make makelist
|
||||
make -f Makefile.list linux
|
||||
gmake -f Makefile.list mac :pre
|
||||
[Step 2]
|
||||
|
||||
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.
|
||||
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".
|
||||
|
||||
(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.
|
||||
[Step 3]
|
||||
|
||||
(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.
|
||||
|
||||
(4) If you get a link-time error about missing libraries or missing
|
||||
dependencies, then it can be because:
|
||||
|
||||
you are including a package that needs an extra library, but have not pre-built the necessary "package library"_#2_3_3
|
||||
you are linking to a library that doesn't exist on your system
|
||||
you are not linking to the necessary system library :ul
|
||||
|
||||
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.
|
||||
|
||||
:line
|
||||
|
||||
[{Editing a new low-level Makefile.foo:}] :link(2_2_4)
|
||||
|
||||
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.
|
||||
|
||||
(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".
|
||||
|
||||
(2) The "compiler/linker settings" section lists compiler and linker
|
||||
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
|
||||
@ -199,11 +169,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.
|
||||
|
||||
(3) The "system-specific settings" section has 6 parts.
|
||||
[Step 4]
|
||||
|
||||
(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:
|
||||
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).
|
||||
|
||||
The LMP_INC variable is used to include options that turn on ifdefs
|
||||
within the LAMMPS code. The options that are currently recogized are:
|
||||
|
||||
-DLAMMPS_GZIP
|
||||
-DPACK_ARRAY
|
||||
@ -231,18 +205,27 @@ Restrictions section of the "dump"_dump.html command for details.
|
||||
If you use -DLAMMPS_JPEG, the "dump image"_dump.html command will be
|
||||
able to write out JPEG image files. If not, it will only be able to
|
||||
write out 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.
|
||||
|
||||
(3.b) The 3 MPI variables are used to specify an MPI library to build
|
||||
LAMMPS with.
|
||||
[Step 5]
|
||||
|
||||
The 3 MPI variables are used to specify an MPI library to build LAMMPS
|
||||
with.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
If you are installing MPI yourself, we recommend Argonne's MPICH 1.2
|
||||
or 2.0 or OpenMPI. MPICH can be downloaded from the "Argonne MPI
|
||||
@ -257,100 +240,155 @@ should have compiler options to enable you to use the same compiler
|
||||
you are using for the LAMMPS build, which can avoid problems that can
|
||||
arise when linking LAMMPS to the MPI library.
|
||||
|
||||
If you just want LAMMPS to run on a single processor, you can use the
|
||||
STUBS library in place of MPI, since you don't need 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
(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
|
||||
[Step 6]
|
||||
|
||||
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
|
||||
"kspace_style"_kspace_style.html command.
|
||||
|
||||
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.
|
||||
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 "KISS FFT library"_http://kissfft.sf.net, 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.
|
||||
|
||||
If nothing is specified for these 3 variables, LAMMPS uses an internal
|
||||
FFT library which is derived from "KISSFFT"_http://kissfft.sf.net.
|
||||
This library is portable to all platforms and for typical LAMMPS
|
||||
simulations it is almost as fast as vendor optimized libraries.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
FFTW is a fast, portable library that should also work on any
|
||||
platform. You can download it from
|
||||
"www.fftw.org"_http://www.fftw.org. 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.
|
||||
"www.fftw.org"_http://www.fftw.org. 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.
|
||||
|
||||
(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.
|
||||
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.
|
||||
|
||||
(3.e) The 3 JPG variables are used to specify a JPEG library which
|
||||
LAMMPS uses when writing a JPEG file via the "dump
|
||||
image"_dump_image.html command. These can be left blank if you are
|
||||
not using the -DLAMMPS_JPEG switch discussed above in section (3.a).
|
||||
[Step 7]
|
||||
|
||||
The 3 JPG variables allow you to specify a JPEG library which LAMMPS
|
||||
uses when writing out JPEG files via the "dump image"_dump_image.html
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
(3.e) The several SYSLIB and SYSPATH variables can be ignored unless
|
||||
you are building LAMMPS with one or more of the LAMMPS packages that
|
||||
require these extra system libraries. The names of these packages are
|
||||
the prefixes on the SYSLIB and SYSPATH variables. See the "section
|
||||
below"_#2_3_4 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.
|
||||
As before, if these header and library files are in the usual place on
|
||||
your machine, you may not need to set these variables.
|
||||
|
||||
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:
|
||||
[Step 8]
|
||||
|
||||
Note that by default only a few of LAMMPS optional pacakges are
|
||||
installed. To build LAMMPS with optional packages, see "this
|
||||
section"_#2_3 below, before proceeding to Step 9.
|
||||
|
||||
[Step 9]
|
||||
|
||||
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:
|
||||
|
||||
make foo
|
||||
or
|
||||
gmake foo :pre
|
||||
|
||||
You should get the executable lmp_foo when the build is complete.
|
||||
|
||||
|
||||
:line
|
||||
|
||||
[{Additional build tips:}] :link(2_2_5)
|
||||
[{Errors that can occur when making LAMMPS:}] :link(2_2_3)
|
||||
|
||||
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.
|
||||
|
||||
Here are two non-obvious errors that can occur:
|
||||
|
||||
(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.
|
||||
|
||||
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. Note that you should
|
||||
include/exclude any desired optional packages before using the "make
|
||||
makelist" command.
|
||||
|
||||
(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.
|
||||
|
||||
:line
|
||||
|
||||
[{Additional build tips:}] :link(2_2_4)
|
||||
|
||||
(1) Building LAMMPS for multiple platforms.
|
||||
|
||||
@ -405,13 +443,13 @@ secs/timestep.
|
||||
|
||||
:line
|
||||
|
||||
[{Building for a Mac:}] :link(2_2_6)
|
||||
[{Building for a Mac:}] :link(2_2_5)
|
||||
|
||||
OS X is BSD Unix, so it should just work. See the Makefile.mac file.
|
||||
|
||||
:line
|
||||
|
||||
[{Building for Windows:}] :link(2_2_7)
|
||||
[{Building for Windows:}] :link(2_2_6)
|
||||
|
||||
The LAMMPS download page has an option to download both a serial and
|
||||
parallel pre-built Windows exeutable. See the "Running LAMMPS"_#2_5
|
||||
@ -454,12 +492,11 @@ This section has the following sub-sections:
|
||||
|
||||
[{Package basics:}] :link(2_3_1)
|
||||
|
||||
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".
|
||||
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".
|
||||
|
||||
The current list of standard packages is as follows:
|
||||
|
||||
@ -483,12 +520,13 @@ shock : methods for MD simulations of shock loading
|
||||
srd : stochastic rotation dynamics (SRD)
|
||||
xtc : dump atom snapshots in XTC format :tb(s=:)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
The difference between a {standard} package versus a {user} package is
|
||||
as follows.
|
||||
as follows:
|
||||
|
||||
Standard packages are supported by the LAMMPS developers and are
|
||||
written in a syntax and style consistent with the rest of LAMMPS.
|
||||
@ -506,19 +544,28 @@ documentation.
|
||||
|
||||
[{Including/excluding packages:}] :link(2_3_2)
|
||||
|
||||
To use or not use a package you must be include or exclude it before
|
||||
LAMMPS is built.
|
||||
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:
|
||||
|
||||
make yes-colloid
|
||||
make g++ :pre
|
||||
|
||||
or
|
||||
|
||||
make no-manybody
|
||||
make g++ :pre
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
By default, LAMMPS includes only the "kspace", "manybody", and
|
||||
"molecule" packages.
|
||||
@ -530,168 +577,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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
:line
|
||||
|
||||
[{Packages that require extra LAMMPS libraries:}] :link(2_3_3)
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Here is a bit of information about each library:
|
||||
|
||||
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.
|
||||
|
||||
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 "this section"_Section_accelerate.html#10_3 of the
|
||||
manual for more information about using this package effectively and
|
||||
how it differs from the gpu package.
|
||||
|
||||
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 "this
|
||||
section"_Section_accelerate.html#10_2 of the manual for more
|
||||
information about using this package effectively and how it differs
|
||||
from the user-cuda package.
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
As described in the README file in each lib directory, each library is
|
||||
typically built by typing something like
|
||||
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:
|
||||
|
||||
make -f Makefile.g++ :pre
|
||||
|
||||
in the appropriate directory, e.g. in lib/reax.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Note that the cuda library, used by the user-cuda package is an
|
||||
exception. See its README file and "this
|
||||
section"_Section_accelerate.html#10_3 of the manual for instructions
|
||||
on how to build it.
|
||||
When you have built one of these libraries, there are 2 things to
|
||||
check:
|
||||
|
||||
:line
|
||||
(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.
|
||||
|
||||
[{Additional Makefile settings for extra libraries:}] :link(2_3_4)
|
||||
(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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
make yes-reax
|
||||
make g++ :pre
|
||||
|
||||
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.
|
||||
|
||||
As discussed in point (3.e) of "this section"_#2_2_4 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:
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
Note that if these settings are not correct for your box, the LAMMPS
|
||||
build will likely fail.
|
||||
|
||||
:line
|
||||
|
||||
2.4 Building LAMMPS as a library :h4,link(2_4)
|
||||
|
||||
LAMMPS can be built as a library, which can then be called from
|
||||
LAMMPS itself 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
|
||||
@ -699,13 +668,14 @@ 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.
|
||||
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.
|
||||
|
||||
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
|
||||
@ -761,8 +731,8 @@ on various platforms.
|
||||
:line
|
||||
|
||||
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.
|
||||
|
||||
To run a LAMMPS executable on a Windows machine, first decide whether
|
||||
you want to download the non-MPI (serial) or the MPI (parallel)
|
||||
@ -841,8 +811,8 @@ more processors or setup a smaller problem.
|
||||
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. 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:
|
||||
|
||||
-c or -cuda
|
||||
-e or -echo
|
||||
|
||||
Reference in New Issue
Block a user