Getting Started
===============
This section describes how to build and run LIGGGHTS(R)-PUBLIC, for both new and
experienced users.
.. contents::
:local:
:depth: 1
.. _start_1:
How to obtain LIGGGHTS(R)-PUBLIC
----------------------------------------------
We recommend to use git to download the LIGGGHTS(R)-PUBLIC package. Make sure that the
*git* command is available on your system. On a Ubuntu/Debian box this can be
achieved by
.. parsed-literal::
sudo apt-get install git
.. note::
Users of a LIGGGHTS-PREMIUM version will need to replace the
LIGGGHTS-PUBLIC strings shown below by their respective version string. This
string is equal to LIGGGHTS(R)-PUBLIC without the "(R)".
LIGGGHTS(R)-PUBLIC can then be downloaded by typing
.. parsed-literal::
git clone git@github.com:CFDEMproject/LIGGGHTS-PUBLIC.git
Under certain circumstances (e.g. company firewall) this might fail and instead
you can use
.. parsed-literal::
git clone https://github.com/CFDEMproject/LIGGGHTS-PUBLIC.git
to obtain LIGGGHTS(R)-PUBLIC. The advantage of using one of these two commands is that
you can use
.. parsed-literal::
git pull
to easily fetch the latest version of the code when we release a new version.
Note that this command needs to be executed in your LIGGGHTS-PUBLIC folder.
If none of the clone commands work you can download the package
`here <https://github.com/CFDEMproject/LIGGGHTS-PUBLIC/archive/master.zip>`_
without having to use git. Note that *git pull* will not work in this case,
instead you will have to download the full zip file again.
The LIGGGHTS-PUBLIC directory contains two files and several directories:
+----------+---------------------------------------------------+
| README | text file |
+----------+---------------------------------------------------+
| LICENSE | the GNU General Public License (GPL) |
+----------+---------------------------------------------------+
| doc | documentation |
+----------+---------------------------------------------------+
| examples | simple test problems |
+----------+---------------------------------------------------+
| lib | libraries LIGGGHTS(R)-PUBLIC can be linked with |
+----------+---------------------------------------------------+
| python | Python wrapper on LIGGGHTS(R)-PUBLIC as a library |
+----------+---------------------------------------------------+
| src | source files |
+----------+---------------------------------------------------+
----------
.. _start_2:
Making LIGGGHTS(R)-PUBLIC
---------------------------------------
This section has the following sub-sections:
* :ref:`Read this first <start_2_1>`
* :ref:`Steps to build a LIGGGHTS(R)-PUBLIC executable <start_2_2>`
* :ref:`Advanced building using custom makefiles <start_2_2_expert>`
* :ref:`Common errors that can occur when making LIGGGHTS(R)-PUBLIC <start_2_3>`
* :ref:`Additional build tips <start_2_4>`
* :ref:`Building for a Mac <start_2_5>`
* :ref:`Building for Windows <start_2_6>`
----------
.. _start_2_1:
**Read this first:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Building LIGGGHTS(R)-PUBLIC 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, PNG), LIGGGHTS(R)-PUBLIC 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 often not
LIGGGHTS(R)-PUBLIC 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 LIGGGHTS(R)-PUBLIC issue
(e.g. the compiler complains about a line of LIGGGHTS(R)-PUBLIC source code), then
please post a question to the `LIGGGHTS(R)-PUBLIC forum <http://www.cfdem.com/forum>`_.
If you succeed in building LIGGGHTS(R)-PUBLIC on a new kind of machine, for which
there isn't a similar Makefile for in the src/MAKE directory, send it
to the developers and we can include it in the LIGGGHTS(R)-PUBLIC distribution. In
particular, we are interested in cases where Makefile.auto does not work, so
that we can improve its performance.
----------
.. _start_2_2:
**Steps to build a LIGGGHTS(R)-PUBLIC executable:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With LIGGGHTS version 3.5.1 we have rolled out a all new and magic
Makefile.auto which hopefully will make building LIGGGHTS as simple as
possible. If the following steps do not work for you please see the advanced
building description :ref:`here <start_2_2_expert>`.
Before attempting a build ensure that your system has all required prerequisites
installed. A solid basis for several popular operating systems are listed below:
.. parsed-literal::
Ubuntu 16.04LTS:
sudo apt-get install openmpi-bin libopenmpi-dev libvtk6.2 libvtk6-dev
-----
Ubuntu 17.10:
sudo apt-get install openmpi-bin libopenmpi-dev libvtk6.3 libvtk6-dev
-----
Fedora 25:
su -
dnf install openmpi openmpi-devel paraview-openmpi paraview-openmpi-devel gcc-c++
exit
echo "export PATH=$PATH:/usr/lib64/openmpi/bin" >> ~/.bashrc
echo "export LIBRARY_PATH=$LIBRARY_PATH:/usr/lib64/openmpi/lib:/usr/lib64/openmpi/lib/paraview" >> ~/.bashrc
echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib64/openmpi/lib:/usr/lib64/openmpi/lib/paraview" >> ~/.bashrc
echo "export C_INCLUDE_PATH=$C_INCLUDE_PATH:/usr/lib64/openmpi/include/paraview" >> ~/.bashrc
echo "export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:/usr/lib64/openmpi/include/paraview" >> ~/.bashrc
**Step 0**
The src directory contains the C++ source and header files for LIGGGHTS(R)-PUBLIC.
It also contains a top-level Makefile and a MAKE sub-directory with
several Makefile.* files for many machines. From within the src
directory, type "make" or "gmake". You should see a list of available
choices. Of particular interest is the auto option, as it should do all the
heavy lifting for us. So start by typing
.. parsed-literal::
make auto
into the command line. If you are running this for the first time you will see
the following message:
.. parsed-literal::
>>> WARNING <<<
Created MAKE/Makefile.user for the first time. Please check that the options
in that file are set correctly and run make again.
That is perfectly normal as *MAKE/Makefile.user* does not exist by default
and contains some default options. The compilation will continue and if you are
lucky enough it will actually produce an executable called *lmp_auto* in your
*src/* folder. If this is the case you are done and can move on to :ref:`Running LIGGGHTS(R)-PUBLIC <start_6>`
Should the compilation interupt please carefully study the error message. The
following procedure will explain how to set compilation variables for *make
auto*.
**Step 1**
To configure these options open *MAKE/Makefile.user* with your favourite
text editor. There are two sections in this file. The first one specifies
which options and features in LIGGGHTS(R)-PUBLIC you would like to activate. The first
three lines are related to MPI and read:
.. parsed-literal::
# MPI: "ON" or "OFF"
# Description: Use the message passing interface for parallel execution
USE_MPI = "ON"
The first, commented line indicates that either "ON" or "OFF" are valid
parameters of the variable called *USE_MPI*. A short description of the
option follows and the last line actually sets the option to "ON". The
default *MAKE/Makefile.user* comes with some sensibly set defaults. So you
might not need to change anything at all.
The second part of this file is by default all commented out and deals with
user and machine specific paths. Say that *USE_VTK* is set to "ON" and your
VTK installation is not in your */usr* path, but in */home/liggghts/vtk*. In
that case have a look at the following lines:
.. parsed-literal::
# VTK specific variables
#
# Path that contains the includes (vtkVersion.h)
#VTK_INC_USR=-I/path/to/vtk/include
# Path that contains the VTK libraries
#VTK_LIB_USR=-L/path/to/vtk/lib
# Additional VTK libraries to include
#VTK_ADDLIBS_USR=
In this case you would want to change *VTK_INC_USR* and *VTK_LIB_USR* so
that they become
.. parsed-literal::
# VTK specific variables
#
# Path that contains the includes (vtkVersion.h)
VTK_INC_USR=-I/home/liggghts/vtk/include
# Path that contains the VTK libraries
VTK_LIB_USR=-L/home/liggghts/vtk/lib
# Additional VTK libraries to include
#VTK_ADDLIBS_USR=
Note that the two lines were uncommented and their values were changed as
required. You can also see that include paths (normally containing *INC* in
the variable name) need to be prefixed with -I and library paths (containing
*LIB*) with -L. If you have non-standard paths, this can be a bit tricky to
set up, so if you need any help ask a local expert that knows the setup of
your machine.
.. note::
If you set a *_USR* variable, such as *VTK_INC_USR* and its
corresponding non-*_USR* variable (*VTK_INC* in our example) is set. Then
the first will have no effect, as the non-*_USR* variable will have
precedence.
If you run *make auto* the Makefile will automatically check if the options
you have provided are valid. It will hopefully supply you with helpful error
messages in case some options cannot be found.
.. note::
If you change any options in the first part of your
*MAKE/Makefile.auto* after a first compilation you will be requested to
perform a *make clean-auto* to do a full recompilation of the code.
**Step 2**
After all options are set to your satisfaction. Simply run
.. parsed-literal::
make auto
again to test the options and compile LIGGGHTS(R)-PUBLIC. After the compilation is
finished you will obtain a executable name *lmp_auto* and you can continue
:ref:`here <start_6>`.
.. note::
Should the compilation not work due to some deficiency of the
*Makefile.auto* that cannot be solved by adjusting *MAKE/Makefile.user*,
then continue reading to see how to make a custom Makefile for your machine.
If you want to help us, then please send us your finished Makefile via the
`forums <http://www.cfdem.com/forum>`_ so that we can improve it for future
use.
----------
For most users it will be convenient if they are able to run LIGGGHTS(R)-PUBLIC by
simply typing *liggghts* on the command line. To make this possible we need to
create a symbolic link. So after the compilation is complete and your lmp_auto
executable was created you can run the following command to create a system-wide
link:
.. parsed-literal::
sudo ln -s lmp_auto /usr/local/bin
Since *sudo* is not available on all systems (e.g. Fedora) you can alternatively
try:
.. parsed-literal::
su -c "ln -s lmp_auto /usr/local/bin"
.. note::
You need administrator access to run the two commands listed above.
**Step 3 (Advanced usage)**
Makefile.auto accepts up to two variables as additional input which are called
*debug* and *postfix*. The former variable can be useful when debugging
LIGGGHTS(R)-PUBLIC and can be used by typing
.. parsed-literal::
make auto debug=ON
The arguments that can be passed to the debug variable are "ON" and "FULL".
This has the same effect as changing the *USE_DEBUG* variable inside your
*Makefile.user* to "ON" and "FULL", respectively. I.e. with "ON" a optimized
debug version of the code is produced, whereas with "FULL" a unoptimized
version of the is compiled. The latter can be quite useful when using a debugger
to look at the local variables inside a code fragment.
When using a debug variable the executables will be called either
*lmp_auto-debug* or *lmp_auto-fulldebug* for "ON" and "FULL", respectively.
.. note::
If you want to clean this particular compilation *make clean-auto*
also needs to have *debug=ON* or *debug=FULL* appended.
The latter variable *postfix* can be used by typing
.. parsed-literal::
make auto postifx=myString
In this case Makefile.auto will not look for the *MAKE/Makefile.user* file,
but *MAKE/Makefile.user_myString*. If it does not exist it will clone
*MAKE/Makefile.user* (instead of a default template). The resulting
executable will be called *lmp_auto_myString* (instead of *lmp_auto*).
The use of the postfix variable should not be required under normal development.
It allows advanced developers to have executables with different features
enabled or disabled and based upon the default *Makefile.user*.
.. note::
If you want to clean this particular compilation *make clean-auto*
also needs to have *postfix=myString* appended.
All model combination of LIGGGHTS(R)-PUBLIC are automatically available starting with
version 3.7. However, only a subset of them are compiled in an optimized manner.
This might give you performance losses between 5 and 20%. In case you are using
a model combination that is not optimized, LIGGGHTS(R)-PUBLIC will notify you of this.
In this case you can create a file called *style_contact_model_user.whitelist*
in your LIGGGHTS(R)-PUBLIC *src/* folder and fill it with entries such as
.. parsed-literal::
GRAN_MODEL(HERTZ, TANGENTIAL_OFF, COHESION_OFF, ROLLING_OFF, SURFACE_DEFAULT)
GRAN_MODEL(HERTZ, TANGENTIAL_HISTORY, COHESION_OFF, ROLLING_EPSD, SURFACE_DEFAULT)
After creating or modifying such a file with the appropriate entries you will need to
recompile LIGGGHTS(R)-PUBLIC and this time it will be built with optimized model
combinations specified in this file.
In addition you can automatically scan files or folders recursively for
LIGGGHTS(R)-PUBLIC input scripts and search them for their used contact model.
With this list an addition to the whitelist is automatically created.
Running the following commands within the LIGGGHTS(R)-PUBLIC src directory
.. parsed-literal::
./genAutoExamplesWhitelist.sh -h
./genAutoExamplesWhitelist.sh ../examples
The first will display the help message for genAutoExamplesWhitelist.sh.
The second will recursively search the examples folder of your LIGGGHTS(R)-PUBLIC
installation and scan all in.* files for the used contact models. It will
also create the file *style_contact_model_autoExamples.whitelist* containing
the unique used models in the whitelist format.
A third whitelist is automatically created during the compilation and is
stored in *style_contact_model.whitelist* . If this file exists, the next
compilation will NOT change this file. You can manually delete it and
recreate it with
.. parsed-literal::
sh Make.sh models
sh Make.sh models_full
During every compilation the three whitelist files *style_contact_model_user.whitelist* ,
*style_contact_model_autoExamples.whitelist* and *style_contact_model.whitelist* are
automatically merged and only unique entries are kept in the merged file.
----------
.. _start_2_2_expert:
**Advanced building using custom makefiles**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Step 0**
The src directory contains the C++ source and header files for LIGGGHTS(R)-PUBLIC. It
also contains a top-level Makefile and a MAKE sub-directory with low-level
Makefile.* files for a few selected platforms. 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:
.. parsed-literal::
make mpi
or
gmake serial
NOTE On a multi-processor or multi-core platform you can launch a
parallel make, by using the "-j *nprocessors*" switch with the make command, which
will build LIGGGHTS(R)-PUBLIC more quickly.
If you get no errors and an executable like lmp_mpi or lmp_serial is produced,
you're done; it's your lucky day.
Note that by default only a few of LIGGGHTS(R)-PUBLIC optional packages are
installed. To build LIGGGHTS(R)-PUBLIC with optional packages, see :ref:`this section <start_3>` below.
**Step 1**
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 "LIGGGHTS(R)-PUBLIC-specific settings" section.
.. note::
Do not attempt to copy and modify Makefile.auto as this is a rather
complex file and should only be modified by experts.
**Step 2**
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".
**Step 3**
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
MPI is installed on your system, though you should check which actual
compiler it wraps. Vendor compilers often produce faster code. On
boxes with Intel CPUs, we suggest using the commercial Intel icc
compiler, which can be downloaded from `Intel's compiler site <intel_>`_.
.. _intel: http://www.intel.com/software/products/noncom
If building a C++ code on your machine requires additional libraries,
then you should list them as part of the LIB variable.
The DEPFLAGS setting is what triggers the C++ compiler to create a
dependency list for a source file. This speeds re-compilation when
source (*.cpp) or header (*.h) files are edited. Some compilers do
not support dependency file creation, or may use a different switch
than -D. GNU g++ works with -D. If your compiler can't create
dependency files, then you'll need to create a Makefile.foo patterned
after Makefile.storm, which uses different rules that do not involve
dependency files. Note that when you build LIGGGHTS(R)-PUBLIC for the first time
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.
**Step 4**
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 LIGGGHTS(R)-PUBLIC code. The options that are currently recogized are:
* -DLAMMPS_GZIP
* -DLAMMPS_JPEG
* -DLAMMPS_PNG
* -DLAMMPS_FFMPEG
* -DLAMMPS_MEMALIGN
* -DLAMMPS_XDR
* -DLAMMPS_SMALLBIG
* -DLAMMPS_BIGBIG
* -DLAMMPS_SMALLSMALL
* -DLAMMPS_LONGLONG_TO_LONG
* -DPACK_ARRAY
* -DPACK_POINTER
* -DPACK_MEMCPY
The read_data and dump commands will read/write gzipped files if you
compile with -DLAMMPS_GZIP. It requires that your machine supports
the "popen" function in the standard runtime library and that a gzip
executable can be found by LIGGGHTS(R)-PUBLIC during a run.
If you use -DLAMMPS_JPEG, the :doc:`dump image <dump_image>` command
will be able to write out JPEG image files. For JPEG files, you must
also link LIGGGHTS(R)-PUBLIC with a JPEG library, as described below. If you use
-DLAMMPS_PNG, the :doc:`dump image <dump>` command will be able to write
out PNG image files. For PNG files, you must also link LIGGGHTS(R)-PUBLIC with a
PNG library, as described below. If neither of those two defines are
used, LIGGGHTS(R)-PUBLIC will only be able to write out uncompressed PPM image
files.
If you use -DLAMMPS_FFMPEG, the :doc:`dump movie <dump_image>` command
will be available to support on-the-fly generation of rendered movies
the need to store intermediate image files. It requires that your
machines supports the "popen" function in the standard runtime library
and that an FFmpeg executable can be found by LIGGGHTS(R)-PUBLIC during the run.
Using -DLAMMPS_MEMALIGN=<bytes> enables the use of the
posix_memalign() call instead of malloc() when large chunks or memory
are allocated by LIGGGHTS(R)-PUBLIC. This can help to make more efficient use of
vector instructions of modern CPUS, since dynamically allocated memory
has to be aligned on larger than default byte boundaries (e.g. 16
bytes instead of 8 bytes on x86 type platforms) for optimal
performance.
If you use -DLAMMPS_XDR, the build will include XDR compatibility
files for doing particle dumps in XTC format. This is only necessary
if your platform does have its own XDR files available. See the
Restrictions section of the :doc:`dump <dump>` command for details.
Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG,
-D-DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG.
These settings refer to use of 4-byte (small) vs 8-byte (big) integers
within LIGGGHTS(R)-PUBLIC, as specified in src/lmptype.h. The only reason to use
the BIGBIG setting is to enable simulation of huge molecular systems
with more than 2 billion atoms or to allow moving atoms to wrap back
through a periodic box more than 512 times. The only reason to use
the SMALLSMALL setting is if your machine does not support 64-bit
integers. See the :ref:`Additional build tips <start_2_4>` section below
for more details.
The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or
MPI version does not recognize "long long" data types. In this case a
"long" data type is likely already 64-bits, in which case this setting
will convert to that data type.
Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY
options can make for faster parallel FFTs (in the PPPM solver) on some
platforms. The -DPACK_ARRAY setting is the default. See the
:doc:`kspace_style <kspace_style>` command for info about PPPM. See
Step 6 below for info about building LIGGGHTS(R)-PUBLIC with an FFT library.
**Step 5**
The 3 MPI variables are used to specify an MPI library to build LAMMPS
with.
If you want LIGGGHTS(R)-PUBLIC 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 LIGGGHTS(R)-PUBLIC, 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 MPICH2
or OpenMPI. MPICH can be downloaded from the `Argonne MPI site <http://www.mcs.anl.gov/research/projects/mpich2/>`_. OpenMPI can
be downloaded from the `OpenMPI site <http://www.open-mpi.org>`_.
Other MPI packages should also work. If you are running on a big
parallel platform, your system people or the vendor should have
already installed a version of MPI, which is likely to be faster
than a self-installed MPICH or OpenMPI, so find out how to build
and link with it. If you use MPICH or OpenMPI, you will have to
configure and build it for your platform. The MPI configure script
should have compiler options to enable you to use the same compiler
you are using for the LIGGGHTS(R)-PUBLIC build, which can avoid problems that can
arise when linking LIGGGHTS(R)-PUBLIC to the MPI library.
If you just want to run LIGGGHTS(R)-PUBLIC 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 LIGGGHTS(R)-PUBLIC itself. To build from the src
directory, type "make stubs", or from the STUBS dir, type "make".
This should create a libmpi_stubs.a file suitable for linking to
LIGGGHTS(R)-PUBLIC. If the build fails, you will need to edit the STUBS/Makefile
for your platform.
The file STUBS/mpi.c 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 LIGGGHTS(R)-PUBLIC
simulations.
**Step 6**
The 3 FFT variables allow you to specify an FFT library which LIGGGHTS(R)-PUBLIC
uses (for performing 1d FFTs) when running the particle-particle
particle-mesh (PPPM) option for long-range Coulombics via the
:doc:`kspace_style <kspace_style>` command.
LIGGGHTS(R)-PUBLIC supports various open-source or vendor-supplied FFT libraries
for this purpose. If you leave these 3 variables blank, LIGGGHTS(R)-PUBLIC will
use the open-source `KISS FFT library <http://kissfft.sf.net>`_, which is
included in the LIGGGHTS(R)-PUBLIC distribution. This library is portable to all
platforms and for typical LIGGGHTS(R)-PUBLIC 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.
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.
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 called -DFFTW_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.
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 options.
**Step 7**
The 3 JPG variables allow you to specify a JPEG and/or PNG library
which LIGGGHTS(R)-PUBLIC uses when writing out JPEG or PNG files via the :doc:`dump image <dump_image>` command. These can be left blank if you do not
use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step
4, since in that case JPEG/PNG output will be disabled.
A standard JPEG library usually goes by the name libjpeg.a or
libjpeg.so 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, so that the
compiler and linker can find it.
A standard PNG library usually goes by the name libpng.a or libpng.so
and has an associated header file png.h. Whichever PNG library you
have on your platform, you'll need to set the appropriate JPG_INC,
JPG_PATH, and JPG_LIB variables, so that the compiler and linker can
find it.
As before, if these header and library files are in the usual place on
your machine, you may not need to set these variables.
**Step 8**
Note that by default only a few of LIGGGHTS(R)-PUBLIC optional packages are
installed. To build LIGGGHTS(R)-PUBLIC with optional packages, see :ref:`this section <start_3>` below, before proceeding to Step 9.
**Step 9**
That's it. Once you have a correct Makefile.foo, you have installed
the optional LIGGGHTS(R)-PUBLIC 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:
.. parsed-literal::
make foo
or
gmake foo
You should get the executable lmp_foo when the build is complete.
----------
.. _start_2_3:
**Errors that can occur when making LIGGGHTS(R)-PUBLIC:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. warning::
If an error occurs when building LIGGGHTS(R)-PUBLIC, 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 LIGGGHTS(R)-PUBLIC 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.
.. parsed-literal::
make makelist
make -f Makefile.list linux
gmake -f Makefile.list mac
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 LIGGGHTS(R)-PUBLIC. 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. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described
above in Step 4.
----------
.. _start_2_4:
**Additional build tips:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(1) Building LIGGGHTS(R)-PUBLIC for multiple platforms.
You can make LIGGGHTS(R)-PUBLIC for multiple platforms from the same src
directory. Each target creates its own object sub-directory called
Obj_target where it stores the system-specific *.o files.
(2) Cleaning up.
Typing "make clean-all" or "make clean-machine" will delete *.o object
files created when LIGGGHTS(R)-PUBLIC is built, for either all builds or for a
particular machine.
(3) Changing the LIGGGHTS(R)-PUBLIC size limits via -DLAMMPS_SMALLBIG or
-DLAMMPS_BIBIG or -DLAMMPS_SMALLSMALL
As explained above, any of these 3 settings can be specified on the
LMP_INC line in your low-level src/MAKE/Makefile.foo.
The default is -DLAMMPS_SMALLBIG which allows for systems with up to
2^63 atoms and timesteps (about 9 billion billion). The atom limit is
for atomic systems that do not require atom IDs. For molecular
models, which require atom IDs, the limit is 2^31 atoms (about 2
billion). With this setting, image flags are stored in 32-bit
integers, which means for 3 dimensions that atoms can only wrap around
a periodic box at most 512 times. If atoms move through the periodic
box more than this limit, the image flags will "roll over", e.g. from
511 to -512, which can cause diagnostics like the mean-squared
displacement, as calculated by the :doc:`compute msd <compute_msd>`
command, to be faulty.
To allow for larger molecular systems or larger image flags, compile
with -DLAMMPS_BIGBIG. This enables molecular systems with up to 2^63
atoms (about 9 billion billion). And image flags will not "roll over"
until they reach 2^20 = 1048576.
.. warning::
As of 6/2012, the BIGBIG setting does not yet enable
molecular systems to grow as large as 2^63. Only the image flag roll
over is currently affected by this compile option.
If your system does not support 8-byte integers, you will need to
compile with the -DLAMMPS_SMALLSMALL setting. This will restrict your
total number of atoms (for atomic or molecular models) and timesteps
to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512.
Note that in src/lmptype.h there are also settings for the MPI data
types associated with the integers that store atom IDs and total
system sizes. These need to be consistent with the associated C data
types, or else LIGGGHTS(R)-PUBLIC will generate a run-time error.
In all cases, the size of problem that can be run on a per-processor
basis is limited by 4-byte integer storage to 2^31 atoms per processor
(about 2 billion). This should not normally be a restriction since
such a problem would have a huge per-processor memory footprint due to
neighbor lists and would run very slowly in terms of CPU
secs/timestep.
----------
.. _start_2_5:
**Building for a Mac:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
OS X is BSD Unix, so it should just work. Try using "make auto" or use "make
serial" as fallback. This is untested but feel free to give us feedback on
`cfdem.com <www.cfdem.com>`_
----------
.. _start_2_6:
**Building for Windows:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The recommened way to do this is using CMake and Visual Studio. Install
`CMake <www.cmake.org>`_ and launch the associated GUI. Point the *Where is your
source code:* input to your *src/* folder and set the *build* folder to some
folder (recommended: make a *build* folder in your LIGGGHTS(R)-PUBLIC-base directory).
Press *Configure* to get your system settings. You will most likely have to set
the *VTK_DIR* option to the folder in which you built the VTK library. Once this
is done press *Configure* again until all errors are reolved so that you can
*Generate* the project. After that you should be able to press *Open Project* to
open Visual Studio where you can build LIGGGHTS(R)-PUBLIC.
The other way to do this is install and use `cygwin <www.cygwin.org>`_ to build
LIGGGHTS(R)-PUBLIC with a standard Linux make, just as you would on any Linux box. Your
cygwin environment will need several packages such as cmake, g++, gcc, openmpi,
make. Note that when compiling VTK you need to disable all rendering related VTK
options as OpenGL won't be available. Note that this is an option that should
only be used by advanced users.
----------
.. _start_3:
Making LIGGGHTS(R)-PUBLIC with optional packages
--------------------------------------------------------------
This section has the following sub-sections:
* :ref:`Package basics <start_3_1>`
* :ref:`Including/excluding packages <start_3_2>`
* :ref:`Packages that require extra libraries <start_3_3>`
* :ref:`Additional Makefile settings for extra libraries <start_3_4>`
----------
.. _start_3_1:
**Package basics:**
The source code for LIGGGHTS(R)-PUBLIC 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" from within
the src directory of the LIGGGHTS(R)-PUBLIC distribution.
If you use a command in a LIGGGHTS(R)-PUBLIC input script that is specific to a
particular package, you must have built LIGGGHTS(R)-PUBLIC with that package, else
you will get an error that the style is invalid or the command is
unknown. Every command's doc page specfies if it is part of a
package. You can also type
.. parsed-literal::
lmp_machine -h
to run your executable with the optional :ref:`-h command-line switch <start_7>` for "help", which will list the styles and commands
known to your executable.
There are two kinds of packages in LIGGGHTS(R)-PUBLIC, standard and user packages.
More information about the contents of standard and user packages is
given in :doc:`Section_packages <Section_packages>` of the manual. The
difference between standard and user packages is as follows:
Standard packages are supported by the LIGGGHTS(R)-PUBLIC developers and are
written in a syntax and style consistent with the rest of LIGGGHTS(R)-PUBLIC.
This means we will answer questions about them, debug and fix them if
necessary, and keep them compatible with future changes to LIGGGHTS(R)-PUBLIC.
User packages have been contributed by users, and always begin with
the user prefix. If they are a single command (single file), they are
typically in the user-misc package. Otherwise, they are a a set of
files grouped together which add a specific functionality to the code.
Some packages (both standard and user) require additional libraries.
See more details below.
----------
.. _start_3_2:
**Including/excluding packages:**
To use or not use a package you must include or exclude it before
building LIGGGHTS(R)-PUBLIC. From the src directory, this is typically as simple
as:
.. parsed-literal::
make yes-**package-name**
make g++
or
.. parsed-literal::
make no-**package-name**
make g++
.. warning::
You should NOT include/exclude packages and build
LIGGGHTS(R)-PUBLIC in a single make command by using multiple targets, e.g. make
yes-colloid g++. This is because the make procedure creates a list of
source files that will be out-of-date for the build if the package
configuration changes during the same command.
Some packages have individual files that depend on other packages
being included. LIGGGHTS(R)-PUBLIC 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. 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.
When you download a LIGGGHTS(R)-PUBLIC tarball, these packages are pre-installed
in the src directory: KSPACE, MANYBODY,MOLECULE. When you download
LIGGGHTS(R)-PUBLIC source files from the SVN or Git repositories, no packages are
pre-installed.
Packages are included or excluded by typing "make yes-name" or "make
no-name", where "name" is the name of the package in lower-case.
You can also type "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.
.. warning::
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. After
you have included or excluded a package, you must re-build LIGGGHTS(R)-PUBLIC.
Additional package-related make options exist to help manage LIGGGHTS(R)-PUBLIC
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 LIGGGHTS(R)-PUBLIC files or have downloaded a patch from
the LIGGGHTS(R)-PUBLIC 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.
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.
----------
.. _start_3_3:
**Packages that require extra libraries:**
A few of the standard and user packages require additional auxiliary
libraries. They must be compiled first, before LIGGGHTS(R)-PUBLIC is built. If
you get a LIGGGHTS(R)-PUBLIC build error about a missing library, this is likely
the reason. See the :doc:`Section_packages <Section_packages>` doc page
for a list of packages that have auxiliary libraries.
Code for some of these auxiliary libraries is included in the LIGGGHTS(R)-PUBLIC
distribution under the lib directory. Some auxiliary libraries are not
included with LIGGGHTS(R)-PUBLIC;
to use the associated package you must download and install the
auxiliary library yourself. Example is the VORONOI packages.
For libraries with provided source code, each lib directory 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:
.. parsed-literal::
make -f Makefile.g++
If one of the provided Makefiles is not
appropriate for your system you will need to edit or add one.
Note that all the Makefiles have a setting for EXTRAMAKE at
the top that names a Makefile.lammps.* file.
If successful, this will produce 2 files in the lib directory:
.. parsed-literal::
libpackage.a
Makefile.lammps
The Makefile.lammps file is a copy of the EXTRAMAKE file specified
in the Makefile you used.
You MUST insure that the settings in Makefile.lammps are appropriate
for your system. If they are not, the LIGGGHTS(R)-PUBLIC build will fail.
As explained in the lib/package/README files, they are used to specify
additional system libraries and their locations so that LIGGGHTS(R)-PUBLIC can
build with the auxiliary library. For example, if the MEAM or REAX
packages are used, the auxiliary libraries consist of F90 code, build
with a F90 complier. To link that library with LIGGGHTS(R)-PUBLIC (a C++ code)
via whatever C++ compiler LIGGGHTS(R)-PUBLIC is built with, typically requires
additional Fortran-to-C libraries be included in the link. Another
example are the BLAS and LAPACK libraries needed to use the USER-ATC
or USER-AWPMD packages.
For libraries without provided source code, see the
src/package/Makefile.lammps file for information on where to find the
library and how to build it. E.g. the file src/KIM/Makefile.lammps.
This file serves the same purpose as the lib/package/Makefile.lammps
file described above. It has settings needed when LIGGGHTS(R)-PUBLIC is built to
link with the auxiliary library. Again, you MUST insure that the
settings in src/package/Makefile.lammps are appropriate for your
system and where you installed the auxiliary library. If they are
not, the LIGGGHTS(R)-PUBLIC build will fail.
----------
.. _start_4:
Building LIGGGHTS(R)-PUBLIC via the Make.py script
----------------------------------------------------------------
The src directory includes a Make.py script, written
in Python, which can be used to automate various steps
of the build process.
You can run the script from the src directory by typing either:
.. parsed-literal::
Make.py
python Make.py
which will give you info about the tool. For the former to work, you
may need to edit the 1st line of the script to point to your local
Python. And you may need to insure the script is executable:
.. parsed-literal::
chmod +x Make.py
The following options are supported as switches:
* -i file1 file2 ...
* -p package1 package2 ...
* -u package1 package2 ...
* -e package1 arg1 arg2 package2 ...
* -o dir
* -b machine
* -s suffix1 suffix2 ...
* -l dir
* -j N
* -h switch1 switch2 ...
Help on any switch can be listed by using -h, e.g.
.. parsed-literal::
Make.py -h -i -p
At a hi-level, these are the kinds of package management
and build tasks that can be performed easily, using
the Make.py tool:
* install/uninstall packages and build the associated external libs (use -p and -u and -e)
* install packages needed for one or more input scripts (use -i and -p)
* build LIGGGHTS(R)-PUBLIC, either in the src dir or new dir (use -b)
* create a new dir with only the source code needed for one or more input scripts (use -i and -o)
The last bullet can be useful when you wish to build a stripped-down
version of LIGGGHTS(R)-PUBLIC to run a specific script(s). Or when you wish to
move the minimal amount of files to another platform for a remote
LIGGGHTS(R)-PUBLIC build.
Note that using Make.py is not a substitute for insuring you have a
valid src/MAKE/Makefile.foo for your system, or that external library
Makefiles in any lib/* directories you use are also valid for your
system. But once you have done that, you can use Make.py to quickly
include/exclude the packages and external libraries needed by your
input scripts.
----------
.. _start_5:
Building LIGGGHTS(R)-PUBLIC as a library
------------------------------------------------------
LIGGGHTS(R)-PUBLIC can be built as either a static or shared library, which can
then be called from another application or a scripting language. See
:ref:`this section <howto_10>` for more info on coupling
LIGGGHTS(R)-PUBLIC to other codes. See :doc:`this section <Section_python>` for
more info on wrapping and running LIGGGHTS(R)-PUBLIC from Python.
**Static library:**
^^^^^^^^^^^^^^^^^^^
To build LIGGGHTS(R)-PUBLIC as a static library (*.a file on Linux), type
.. parsed-literal::
make makelib
make -f Makefile.lib foo
where foo is the machine name (if you normally compile with *auto* then use
this option). This kind of library is typically used to statically link a
driver application to LIGGGHTS(R)-PUBLIC, so that you can insure all dependencies
are satisfied at compile time. 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 second "make" command will use it to build
LIGGGHTS(R)-PUBLIC as a static library, using the ARCHIVE and ARFLAGS settings in
src/MAKE/Makefile.foo. The build will create the file liblammps_foo.a which
another application can link to.
**Shared library:**
^^^^^^^^^^^^^^^^^^^
To build LIGGGHTS(R)-PUBLIC as a shared library (*.so file on Linux), which can be
dynamically loaded, e.g. from Python, type
.. parsed-literal::
make makeshlib
make -f Makefile.shlib foo
where foo is the machine name (if you normally compile with *auto* then use
this option). This kind of library is required when wrapping LIGGGHTS(R)-PUBLIC
with Python; see :doc:`Section_python <Section_python>` for details. Again,
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.shlib with all the file names in your src dir. The second
"make" command will use it to build LIGGGHTS(R)-PUBLIC as a shared library, using
the SHFLAGS and SHLIBFLAGS settings in src/MAKE/Makefile.foo. The build
will create the file liblammps_foo.so which another application can link to
dyamically. It will also create a soft link liblammps.so, which the Python
wrapper uses by default.
Note that for a shared library to be usable by a calling program, all
the auxiliary libraries it depends on must also exist as shared
libraries. This will be the case for libraries included with LIGGGHTS(R)-PUBLIC,
such as the dummy MPI library in src/STUBS or any package libraries in
lib/packges, since they are always built as shared libraries with the
-fPIC switch. However, if a library like MPI or FFTW does not exist
as a shared library, the second make command will generate an error.
This means you will need to install a shared library version of the
package. The build instructions for the library should tell you how
to do this.
As an example, here is how to build and install the `MPICH library <mpich_>`_, a popular open-source version of MPI, distributed by
Argonne National Labs, as a shared library in the default
/usr/local/lib location:
.. _mpich: http://www-unix.mcs.anl.gov/mpi
.. parsed-literal::
./configure --enable-shared
make
make install
You may need to use "sudo make install" in place of the last line if
you do not have write privileges for /usr/local/lib. The end result
should be the file /usr/local/lib/libmpich.so.
**Additional requirement for using a shared library:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The operating system finds shared libraries to load at run-time using
the environment variable LD_LIBRARY_PATH. So you may wish to copy the
file src/liblammps.so or src/liblammps_g++.so (for example) to a place
the system can find it by default, such as /usr/local/lib, or you may
wish to add the LIGGGHTS(R)-PUBLIC src directory to LD_LIBRARY_PATH, so that the
current version of the shared library is always available to programs
that use it.
For the csh or tcsh shells, you would add something like this to your
~/.cshrc file:
.. parsed-literal::
setenv LD_LIBRARY_PATH $*LD_LIBRARY_PATH*:/home/sjplimp/lammps/src
**Calling the LIGGGHTS(R)-PUBLIC library:**
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Either flavor of library (static or shared0 allows one or more LIGGGHTS(R)-PUBLIC
objects to be instantiated from the calling program.
When used from a C++ program, all of LIGGGHTS(R)-PUBLIC is wrapped in a LAMMPS_NS
namespace; you can safely use any of its classes and methods from
within the calling code, as needed.
When used from a C or Fortran program or a scripting language like
Python, the library has a simple function-style interface, provided in
src/library.cpp and src/library.h.
See the sample codes in examples/COUPLE/simple for examples of C++ and
C and Fortran codes that invoke LIGGGHTS(R)-PUBLIC thru its library interface.
There are other examples as well in the COUPLE directory which are
discussed in :ref:`Section_howto 10 <howto_10>` of the
manual. See :doc:`Section_python <Section_python>` of the manual for a
description of the Python wrapper provided with LIGGGHTS(R)-PUBLIC that operates
through the LIGGGHTS(R)-PUBLIC library interface.
The files src/library.cpp and library.h define the C-style API for
using LIGGGHTS(R)-PUBLIC as a library. See :ref:`Section_howto 19 <howto_19>` of the manual for a description of the
interface and how to extend it for your needs.
----------
.. _start_6:
Running LIGGGHTS(R)-PUBLIC
----------------------------------------
By default, LIGGGHTS(R)-PUBLIC runs by reading commands from stdin; e.g. lmp_auto
< in.file. This means you first create an input script (e.g. in.file)
containing the desired commands. :doc:`This section <Section_commands>`
describes how input scripts are structured and what commands they
contain.
You can test LIGGGHTS(R)-PUBLIC on any of the sample inputs provided in the
examples or bench directory. Input scripts are named in.* and sample
outputs are named log.*.name.P where name is a machine and P is the
number of processors it was run on.
Here is how you might run a standard chute wear benchmark on a
Linux box, using mpirun to launch a parallel job:
.. parsed-literal::
cd src
make auto
cp lmp_auto ../examples/LIGGGHTS/Tutorials_public/chute_wear
cd ../examples/LIGGGHTS/Tutorials_public/chute_wear
mpirun -np 4 lmp_auto < in.chute_wear
----------
On a Windows box, you can skip making LIGGGHTS(R)-PUBLIC and simply download an
executable, as described above, though the pre-packaged executables
include only certain packages.
To run a LIGGGHTS(R)-PUBLIC executable on a Windows machine, first decide whether
you want to download the non-MPI (serial) or the MPI (parallel)
version of the executable. Download and save the version you have
chosen.
For the non-MPI version, follow these steps:
* Get a command prompt by going to Start->Run... ,
then typing "cmd".
* Move to the directory where you have saved lmp_win_no-mpi.exe
(e.g. by typing: cd "Documents").
* At the command prompt, type "lmp_win_no-mpi -in in.lj", replacing in.lj
with the name of your LIGGGHTS(R)-PUBLIC input script.
For the MPI version, which allows you to run LIGGGHTS(R)-PUBLIC under Windows on
multiple processors, follow these steps:
* Download and install
`MPICH2 <http://www.mcs.anl.gov/research/projects/mpich2/downloads/index.php?s=downloads>`_
for Windows.
* You'll need to use the mpiexec.exe and smpd.exe files from the MPICH2 package. Put them in
same directory (or path) as the LIGGGHTS(R)-PUBLIC Windows executable.
* Get a command prompt by going to Start->Run... ,
then typing "cmd".
* Move to the directory where you have saved lmp_win_mpi.exe
(e.g. by typing: cd "Documents").
* Then type something like this: "mpiexec -np 4 -localonly lmp_win_mpi -in in.lj",
replacing in.lj with the name of your LIGGGHTS(R)-PUBLIC input script.
* Note that you may need to provide smpd with a passphrase --- it doesn't matter what you
type.
* In this mode, output may not immediately show up on the screen, so
if your input script takes a long time to execute, you may need to be
patient before the output shows up.
* Alternatively, you can still use this executable to run on a single processor by
typing something like: "lmp_win_mpi -in in.lj".
----------
The screen output from LIGGGHTS(R)-PUBLIC is described in the next section. As it
runs, LIGGGHTS(R)-PUBLIC also writes a log.lammps file with the same information.
Note that this sequence of commands copies the LIGGGHTS(R)-PUBLIC executable
(lmp_linux) to the directory with the input files. This may not be
necessary, but some versions of MPI reset the working directory to
where the executable is, rather than leave it as the directory where
you launch mpirun from (if you launch lmp_linux on its own and not
under mpirun). If that happens, LIGGGHTS(R)-PUBLIC will look for additional input
files and write its output files to the executable directory, rather
than your working directory, which is probably not what you want.
If LIGGGHTS(R)-PUBLIC encounters errors in the input script or while running a
simulation it will print an ERROR message and stop or a WARNING
message and continue. See :doc:`Section_errors <Section_errors>` for a
discussion of the various kinds of errors LIGGGHTS(R)-PUBLIC can or can't detect,
a list of all ERROR and WARNING messages, and what to do about them.
LIGGGHTS(R)-PUBLIC can run a problem on any number of processors, including a
single processor. In theory you should get identical answers on any
number of processors and on any machine. In practice, numerical
round-off can cause slight differences and eventual divergence of
molecular dynamics phase space trajectories.
LIGGGHTS(R)-PUBLIC can run as large a problem as will fit in the physical memory
of one or more processors. If you run out of memory, you must run on
more processors or setup a smaller problem.
----------
.. _start_7:
Command-line options
----------------------------------
At run time, LIGGGHTS(R)-PUBLIC recognizes several optional command-line switches
which may be used in any order. Either the full word or a one-or-two
letter abbreviation can be used:
* -e or -echo
* -i or -in
* -h or -help
* -l or -log
* -nc or -nocite
* -p or -partition
* -pl or -plog
* -ps or -pscreen
* -r or -restart
* -ro or -reorder
* -sc or -screen
* -sf or -suffix
* -v or -var
For example, lmp_auto might be launched as follows:
.. parsed-literal::
mpirun -np 16 lmp_auto -v f tmp.out -l my.log -sc none < in.alloy
mpirun -np 16 lmp_auto -var f tmp.out -log my.log -screen none < in.alloy
Here are the details on the options:
.. parsed-literal::
-echo style
Set the style of command echoing. The style can be *none* or *screen*
or *log* or *both*. Depending on the style, each command read from
the input script will be echoed to the screen and/or logfile. This
can be useful to figure out which line of your script is causing an
input error. The default value is *log*. The echo style can also be
set by using the :doc:`echo <echo>` command in the input script itself.
.. parsed-literal::
-in file
Specify a file to use as an input script. This is an optional switch
when running LIGGGHTS(R)-PUBLIC in one-partition mode. If it is not specified,
LIGGGHTS(R)-PUBLIC reads its input script from stdin - e.g. lmp_auto < in.run.
This is a required switch when running LIGGGHTS(R)-PUBLIC in multi-partition mode,
since multiple processors cannot all read from stdin.
.. parsed-literal::
-help
Print a list of options compiled into this executable for each LIGGGHTS(R)-PUBLIC
style (atom_style, fix, compute, pair_style, bond_style, etc). This
can help you know if the command you want to use was included via the
appropriate package. LIGGGHTS(R)-PUBLIC will print the info and immediately exit
if this switch is used.
.. parsed-literal::
-log file
Specify a log file for LIGGGHTS(R)-PUBLIC to write status information to. In
one-partition mode, if the switch is not used, LIGGGHTS(R)-PUBLIC writes to the
file log.lammps. If this switch is used, LIGGGHTS(R)-PUBLIC writes to the
specified file. In multi-partition mode, if the switch is not used, a
log.lammps file is created with hi-level status information. Each
partition also writes to a log.lammps.N file where N is the partition
ID. If the switch is specified in multi-partition mode, the hi-level
logfile is named "file" and each partition also logs information to a
file.N. For both one-partition and multi-partition mode, if the
specified file is "none", then no log files are created. Using a
:doc:`log <log>` command in the input script will override this setting.
Option -plog will override the name of the partition log files file.N.
.. parsed-literal::
-nocite
Disable writing the log.cite file which is normally written to list
references for specific cite-able features used during a LIGGGHTS(R)-PUBLIC run.
See the `citation page <http://lammps.sandia.gov/cite.html>`_ for more
details.
.. parsed-literal::
-partition 8x2 4 5 ...
Invoke LIGGGHTS(R)-PUBLIC in multi-partition mode. When LIGGGHTS(R)-PUBLIC is run on P
processors and this switch is not used, LIGGGHTS(R)-PUBLIC runs in one partition,
i.e. all P processors run a single simulation. If this switch is
used, the P processors are split into separate partitions and each
partition runs its own simulation. The arguments to the switch
specify the number of processors in each partition. Arguments of the
form MxN mean M partitions, each with N processors. Arguments of the
form N mean a single partition with N processors. The sum of
processors in all partitions must equal P. Thus the command
"-partition 8x2 4 5" has 10 partitions and runs on a total of 25
processors.
To run multiple independent simulatoins from one input script, using
multiple partitions, see :ref:`Section_howto 4 <howto_4>`
of the manual. World- and universe-style :doc:`variables <variable>`
are useful in this context.
.. parsed-literal::
-plog file
Specify the base name for the partition log files, so partition N
writes log information to file.N. If file is none, then no partition
log files are created. This overrides the filename specified in the
-log command-line option. This option is useful when working with
large numbers of partitions, allowing the partition log files to be
suppressed (-plog none) or placed in a sub-directory (-plog
replica_files/log.lammps) If this option is not used the log file for
partition N is log.lammps.N or whatever is specified by the -log
command-line option.
.. parsed-literal::
-pscreen file
Specify the base name for the partition screen file, so partition N
writes screen information to file.N. If file is none, then no
partition screen files are created. This overrides the filename
specified in the -screen command-line option. This option is useful
when working with large numbers of partitions, allowing the partition
screen files to be suppressed (-pscreen none) or placed in a
sub-directory (-pscreen replica_files/screen). If this option is not
used the screen file for partition N is screen.N or whatever is
specified by the -screen command-line option.
.. parsed-literal::
-restart restartfile datafile
Convert the restart file into a data file and immediately exit. This
is the same operation as if the following 2-line input script were
run:
.. parsed-literal::
read_restart restartfile
write_data datafile
Note that the specified restartfile and datafile can have wild-card
characters ("*",%") as described by the
:doc:`read_restart <read_restart>` and :doc:`write_data <write_data>`
commands. But a filename such as file.* will need to be enclosed in
quotes to avoid shell expansion of the "*" character.
.. parsed-literal::
-reorder nth N
-reorder custom filename
Reorder the processors in the MPI communicator used to instantiate
LIGGGHTS(R)-PUBLIC, in one of several ways. The original MPI communicator ranks
all P processors from 0 to P-1. The mapping of these ranks to
physical processors is done by MPI before LIGGGHTS(R)-PUBLIC begins. It may be
useful in some cases to alter the rank order. E.g. to insure that
cores within each node are ranked in a desired order. Or when using
the :doc:`run_style verlet/split <run_style>` command with 2 partitions
to insure that a specific Kspace processor (in the 2nd partition) is
matched up with a specific set of processors in the 1st partition.
See the :doc:`Section_accelerate <Section_accelerate>` doc pages for
more details.
If the keyword *nth* is used with a setting *N*, then it means every
Nth processor will be moved to the end of the ranking. This is useful
when using the :doc:`run_style verlet/split <run_style>` command with 2
partitions via the -partition command-line switch. The first set of
processors will be in the first partition, the 2nd set in the 2nd
partition. The -reorder command-line switch can alter this so that
the 1st N procs in the 1st partition and one proc in the 2nd partition
will be ordered consecutively, e.g. as the cores on one physical node.
This can boost performance. For example, if you use "-reorder nth 4"
and "-partition 9 3" and you are running on 12 processors, the
processors will be reordered from
.. parsed-literal::
0 1 2 3 4 5 6 7 8 9 10 11
to
.. parsed-literal::
0 1 2 4 5 6 8 9 10 3 7 11
so that the processors in each partition will be
.. parsed-literal::
0 1 2 4 5 6 8 9 10
3 7 11
See the "processors" command for how to insure processors from each
partition could then be grouped optimally for quad-core nodes.
If the keyword is *custom*, then a file that specifies a permutation
of the processor ranks is also specified. The format of the reorder
file is as follows. Any number of initial blank or comment lines
(starting with a "#" character) can be present. These should be
followed by P lines of the form:
.. parsed-literal::
I J
where P is the number of processors LIGGGHTS(R)-PUBLIC was launched with. Note
that if running in multi-partition mode (see the -partition switch
above) P is the total number of processors in all partitions. The I
and J values describe a permutation of the P processors. Every I and
J should be values from 0 to P-1 inclusive. In the set of P I values,
every proc ID should appear exactly once. Ditto for the set of P J
values. A single I,J pairing means that the physical processor with
rank I in the original MPI communicator will have rank J in the
reordered communicator.
Note that rank ordering can also be specified by many MPI
implementations, either by environment variables that specify how to
order physical processors, or by config files that specify what
physical processors to assign to each MPI rank. The -reorder switch
simply gives you a portable way to do this without relying on MPI
itself. See the `processors out <processors>`_ command for how to output
info on the final assignment of physical processors to the LIGGGHTS(R)-PUBLIC
simulation domain.
.. parsed-literal::
-screen file
Specify a file for LIGGGHTS(R)-PUBLIC to write its screen information to. In
one-partition mode, if the switch is not used, LIGGGHTS(R)-PUBLIC writes to the
screen. If this switch is used, LIGGGHTS(R)-PUBLIC writes to the specified file
instead and you will see no screen output. In multi-partition mode,
if the switch is not used, hi-level status information is written to
the screen. Each partition also writes to a screen.N file where N is
the partition ID. If the switch is specified in multi-partition mode,
the hi-level screen dump is named "file" and each partition also
writes screen information to a file.N. For both one-partition and
multi-partition mode, if the specified file is "none", then no screen
output is performed. Option -pscreen will override the name of the
partition screen files file.N.
.. parsed-literal::
-var name value1 value2 ...
Specify a variable that will be defined for substitution purposes when
the input script is read. "Name" is the variable name which can be a
single character (referenced as $x in the input script) or a full
string (referenced as ${abc}). An :doc:`index-style variable <variable>` will be created and populated with the
subsequent values, e.g. a set of filenames. Using this command-line
option is equivalent to putting the line "variable name index value1
value2 ..." at the beginning of the input script. Defining an index
variable as a command-line argument overrides any setting for the same
index variable in the input script, since index variables cannot be
re-defined. See the :doc:`variable <variable>` command for more info on
defining index and other kinds of variables and :ref:`this section <cmd_2>` for more info on using variables
in input scripts.
.. note::
Currently, the command-line parser looks for arguments that
start with "-" to indicate new switches. Thus you cannot specify
multiple variable values if any of they start with a "-", e.g. a
negative numeric value. It is OK if the first value1 starts with a
"-", since it is automatically skipped.
----------
.. _start_8:
LIGGGHTS(R)-PUBLIC screen output
----------------------------------------------
As LIGGGHTS(R)-PUBLIC reads an input script, it prints information to both the
screen and a log file about significant actions it takes to setup a
simulation. When the simulation is ready to begin, LIGGGHTS(R)-PUBLIC performs
various initializations and prints the amount of memory (in MBytes per
processor) that the simulation requires. It also prints details of
the initial thermodynamic state of the system. During the run itself,
thermodynamic information is printed periodically, every few
timesteps. When the run concludes, LIGGGHTS(R)-PUBLIC prints the final
thermodynamic state and a total run time for the simulation. It then
appends statistics about the CPU time and storage requirements for the
simulation. An example set of statistics is shown here:
.. parsed-literal::
Loop time of 49.002 on 2 procs for 2004 atoms
.. parsed-literal::
Pair time (%) = 35.0495 (71.5267)
Bond time (%) = 0.092046 (0.187841)
Kspce time (%) = 6.42073 (13.103)
Neigh time (%) = 2.73485 (5.5811)
Comm time (%) = 1.50291 (3.06703)
Outpt time (%) = 0.013799 (0.0281601)
Other time (%) = 2.13669 (4.36041)
.. parsed-literal::
Nlocal: 1002 ave, 1015 max, 989 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Nghost: 8720 ave, 8724 max, 8716 min
Histogram: 1 0 0 0 0 0 0 0 0 1
Neighs: 354141 ave, 361422 max, 346860 min
Histogram: 1 0 0 0 0 0 0 0 0 1
.. parsed-literal::
Total # of neighbors = 708282
Ave neighs/atom = 353.434
Ave special neighs/atom = 2.34032
Number of reneighborings = 42
Dangerous reneighborings = 2
The first section gives the breakdown of the CPU run time (in seconds)
into major categories. The second section lists the number of owned
atoms (Nlocal), ghost atoms (Nghost), and pair-wise neighbors stored
per processor. The max and min values give the spread of these values
across processors with a 10-bin histogram showing the distribution.
The total number of histogram counts is equal to the number of
processors.
The last section gives aggregate statistics for pair-wise neighbors
and special neighbors that LIGGGHTS(R)-PUBLIC keeps track of (see the
:doc:`special_bonds <special_bonds>` command). The number of times
neighbor lists were rebuilt during the run is given as well as the
number of potentially "dangerous" rebuilds. If atom movement
triggered neighbor list rebuilding (see the
:doc:`neigh_modify <neigh_modify>` command), then dangerous
reneighborings are those that were triggered on the first timestep
atom movement was checked for. If this count is non-zero you may wish
to reduce the delay factor to insure no force interactions are missed
by atoms moving beyond the neighbor skin distance before a rebuild
takes place.
The first line lists the initial and final energy, as well as the
energy on the next-to-last iteration. The next 2 lines give a measure
of the gradient of the energy (force on all atoms). The 2-norm is the
"length" of this force vector; the inf-norm is the largest component.
The last 2 lines are statistics on how many iterations and
force-evaluations the minimizer required. Multiple force evaluations
are typically done at each iteration to perform a 1d line minimization
in the search direction.
.. _liws: http://www.cfdem.com
.. _ld: Manual.html
.. _lc: Section_commands.html#comm