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

more build docs refactoring, correcting, and expanding

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-02-21 10:40:18 -05:00
parent 404b4cf299
commit 0ede04be6c
4 changed files with 175 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

280
doc/src/Build_basics.rst
View File

@ -19,94 +19,113 @@ CMake and make:
Serial vs parallel build
-------------------------------------
LAMMPS can be built to run in parallel using the ubiquitous `MPI (message-passing interface) <https://en.wikipedia.org/wiki/Message_Passing_Interface>`_
library. Or it can built to run on a single processor (serial)
without MPI. It can also be built with support for OpenMP threading
(see more discussion below).
LAMMPS is written to use the ubiquitous `MPI (Message Passing Interface)
<https://en.wikipedia.org/wiki/Message_Passing_Interface>`_ library API
for distributed memory parallel computation. It is compatible with the
MPI standard version 2.x and later. LAMMPS can also be build into a
"serial" executable for use with a single processor using the bundled
MPI STUBS library.
**CMake variables**\ :
Independent of the distributed memory MPI parallelization parts of
LAMMPS are also written with support for shared memory parallelization
using the OpenMP threading standard. A more detailed discussion of that
is below.
**CMake build**\ :
.. code-block:: bash
-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no
-D BUILD_OMP=value # yes or no (default)
-D BUILD_OMP=value # yes or no, default is yes if a compatible compiler is detected
-D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value
The executable created by CMake (after running make) is lmp\_name. If
the LAMMPS\_MACHINE variable is not specified, the executable is just
lmp. Using BUILD\_MPI=no will produce a serial executable.
The executable created by CMake (after running make) is named *lmp* unless
the LAMMPS\_MACHINE option is set. When setting `LAMMPS_MACHINE=name`
the executable will be named *lmp\_name*\. Using `BUILD\_MPI=no` will
enforce building a serial executable using the MPI STUBS library.
**Traditional make**\ :
The build with traditional makefiles has to be done inside the source folder `src`.
.. code-block:: bash
cd lammps/src
make mpi # parallel build, produces lmp_mpi using Makefile.mpi
make serial # serial build, produces lmp_serial using Makefile/serial
make mybox # uses Makefile.mybox to produce lmp_mybox
Serial build (see src/MAKE/Makefile.serial):
Any "make machine" command will look up the make settings from a file
Makefile.machine, create a folder Obj\_machine with all objects and
generated files and an executable called *lmp\_machine*\ . The standard
parallel build with `make mpi` assumes a standard MPI installation with
MPI compiler wrappers where all necessary compiler and linker flags to
get access and link with the suitable MPI headers and libraries are set
by the wrapper programs. For other cases or the serial build, you have
to adjust the make file variables MPI\_INC, MPI\_PATH, MPI\_LIB as well
as CC and LINK. To enable OpenMP threading usually a compiler specific
flag needs to be added to the compile and link commands. For the GNU
compilers, this is *-fopenmp*\ , which can be added to the CC and LINK
makefile variables.
For the serial build the following make variables are set (see src/MAKE/Makefile.serial):
.. code-block:: make
CC = g++
LINK = g++
MPI_INC = -I../STUBS
MPI_PATH = -L../STUBS
MPI_LIB = -lmpi_stubs
For a parallel build, if MPI is installed on your system in the usual
place (e.g. under /usr/local), you do not need to specify the 3
variables MPI\_INC, MPI\_PATH, MPI\_LIB. The MPI wrapper on the compiler
(e.g. mpicxx, mpiCC) knows where to find the needed include and
library files. Failing this, these 3 variables can be used to specify
where the mpi.h file (MPI\_INC), and the MPI library files (MPI\_PATH)
are found, and the name of the library files (MPI\_LIB).
You also need to build the STUBS library for your platform before making
LAMMPS itself. A "make serial" build does this for you automatically,
otherwise, type "make mpi-stubs" from the src directory, or "make" from
the src/STUBS dir. If the build fails, you will need to edit the
STUBS/Makefile for your platform. The stubs library does not provide
MPI/IO functions required by some LAMMPS packages, e.g. MPIIO or USER-LB,
and thus is not compatible with those packages.
For a serial build, you need to specify the 3 variables, as shown
above.
.. note::
For a serial LAMMPS build, use the dummy MPI library provided in
src/STUBS. You also need to build the STUBS library for your platform
before making LAMMPS itself. A "make serial" build does this for.
Otherwise, type "make mpi-stubs" from the src directory, or "make"
from the src/STUBS dir. 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 operating system
does not support gettimeofday() , you will 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.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 LAMMPS
simulations.
**MPI and OpenMP support info**\ :
**CMake and make info**\ :
If you are installing MPI yourself to build a parallel LAMMPS
executable, we recommend either MPICH or OpenMPI which are regularly
used and tested with LAMMPS by the LAMMPS developers. MPICH can be
downloaded from the `MPICH home page <https://www.mpich.org>`_ and
OpenMPI can be downloaded correspondingly from the `OpenMPI home page
<https://www.open-mpi.org>`_. Other MPI packages should also work. No
specific vendor provided and standard compliant MPI library is currently
known to be incompatible with LAMMPS. If you are running on a large
parallel machine, your system admins 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 you should study the provided
documentation to find out how to build and link with it.
If you are installing MPI yourself, we recommend MPICH2 from Argonne
National Laboratory 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 large parallel machine, your system admins 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.
The majority of OpenMP (threading) support in LAMMPS is provided by
the USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The USER-INTEL package also provides OpenMP support (it is
The majority of OpenMP (threading) support in LAMMPS is provided by the
USER-OMP package; see the :doc:`Speed omp <Speed_omp>` doc page for
details. The USER-INTEL package also includes OpenMP threading (it is
compatible with USER-OMP) and adds vectorization support when compiled
with the Intel compilers on top of that. Also, the KOKKOS package can
be compiled for using OpenMP threading.
with compatible compilers, in particular the Intel compilers on top of
OpenMP. Also, the KOKKOS package can be compiled to include OpenMP
threading.
However, there are a few commands in LAMMPS that have native OpenMP
support. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and
USER-DPD packages. In addition some packages support OpenMP threading
indirectly through the libraries they interface to: e.g. LATTE and
USER-COLVARS. See the :doc:`Packages details <Packages_details>` doc
page for more info on these packages and the doc pages for their
respective commands for OpenMP threading info.
In addition, there are a few commands in LAMMPS that have native OpenMP
support included as well. These are commands in the MPIIO, SNAP,
USER-DIFFRACTION, and USER-DPD packages. In addition some packages
support OpenMP threading indirectly through the libraries they interface
to: e.g. LATTE and USER-COLVARS. See the :doc:`Packages details
<Packages_details>` doc page for more info on these packages and the doc
pages for their respective commands for OpenMP threading info.
For CMake, if you use BUILD\_OMP=yes, you can use these packages and
turn on their native OpenMP support and turn on their native OpenMP
@ -143,20 +162,35 @@ Choice of compiler and compile/link options
---------------------------------------------------------
The choice of compiler and compiler flags can be important for
performance. Vendor compilers can produce faster code than
open-source compilers like GNU. On boxes with Intel CPUs, we suggest
trying the `Intel C++ compiler <intel_>`_.
performance. Vendor provided compilers for a specific hardware can
produce faster code than open-source compilers like the GNU compilers.
On x86 hardware most popular compilers are quite similar in performance
of C/C++ code at high optimization levels. When using the USER-INTEL
package, there is a distinct advantage in using the `Intel C++ compiler
<intel_>`_ due to much improved vectorization through SSE and AVX
instructions on compatible hardware as the source code includes changes
and compiler directives to enable high degrees of vectorization.
.. _intel: https://software.intel.com/en-us/intel-compilers
On parallel clusters or supercomputers which use "environment modules"
for their compile/link environments, you can often access different
compilers by simply loading the appropriate module before building
LAMMPS.
**CMake build**\ :
On parallel clusters or supercomputers which use "modules" for their
compile/link environments, you can often access different compilers by
simply loading the appropriate module before building LAMMPS.
**CMake variables**\ :
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any
:doc:`accelerator packages <Speed_packages>` you have included in the
build.
You can tell CMake to look for a specific compiler with these variable
settings. Likewise you can specify the FLAGS variables if you want to
experiment with alternate optimization flags. You should specify all
3 compilers, so that the small number of LAMMPS source files written
in C or Fortran are built with a compiler consistent with the one used
for all the C++ files:
.. code-block:: bash
@ -168,16 +202,8 @@ simply loading the appropriate module before building LAMMPS.
-D CMAKE_C_FLAGS=string # flags to use with C compiler
-D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler
By default CMake will use a compiler it finds and it will add
optimization flags appropriate to that compiler and any :doc:`accelerator packages <Speed_packages>` you have included in the build.
You can tell CMake to look for a specific compiler with these variable
settings. Likewise you can specify the FLAGS variables if you want to
experiment with alternate optimization flags. You should specify all
3 compilers, so that the small number of LAMMPS source files written
in C or Fortran are built with a compiler consistent with the one used
for all the C++ files:
A few example command lines are:
.. code-block:: bash
@ -188,6 +214,9 @@ for all the C++ files:
# Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
For compiling with the Clang/LLVM compilers a special CMake preset is
included that can be loaded with `-C ../cmake/presets/clang.cmake`.
.. note::
When the cmake command completes, it prints a summary to the screen
@ -197,11 +226,17 @@ for all the C++ files:
info is what CMake will try to determine and report. You should check
to confirm you are using the compiler and optimization flags you want.
**Makefile.machine settings**\ :
**Makefile.machine settings for traditional make**\ :
The "compiler/linker settings" section of a Makefile.machine lists
compiler and linker settings for your C++ compiler, including
optimization flags. For a parallel build it is recommended to use
mpicxx or mpiCC, since these compiler wrappers will include a variety of
settings appropriate for your MPI installation and thus avoiding the
guesswork of finding the right flags.
Parallel build (see src/MAKE/Makefile.mpi):
.. code-block:: bash
CC = mpicxx
@ -211,7 +246,6 @@ Parallel build (see src/MAKE/Makefile.mpi):
Serial build (see src/MAKE/Makefile.serial):
.. code-block:: make
CC = g++
@ -219,23 +253,17 @@ Serial build (see src/MAKE/Makefile.serial):
LINK = g++
LINKFLAGS = -g -O
The "compiler/linker settings" section of a Makefile.machine lists
compiler and linker settings for your C++ compiler, including
optimization flags. You should always use mpicxx or mpiCC for
a parallel build, since these compiler wrappers will include
a variety of settings appropriate for your MPI installation.
.. note::
If you build LAMMPS with any :doc:`accelerator packages <Speed_packages>` included, they have specific
optimization flags that are either required or recommended for optimal
performance. You need to include these in the CCFLAGS and LINKFLAGS
settings above. For details, see the individual package doc pages
listed on the :doc:`Speed packages <Speed_packages>` doc page. Or
examine these files in the src/MAKE/OPTIONS directory. They
correspond to each of the 5 accelerator packages and their hardware
variants:
If you build LAMMPS with any :doc:`accelerator packages <Speed_packages>`
included, there may be specific optimization flags that are either
required or recommended to enable required features and to achieve
optimal performance. You need to include these in the CCFLAGS and
LINKFLAGS settings above. For details, see the individual package
doc pages listed on the :doc:`Speed packages <Speed_packages>` doc
page. Or examine these files in the src/MAKE/OPTIONS directory.
They correspond to each of the 5 accelerator packages and their
hardware variants:
.. code-block:: bash
@ -248,10 +276,8 @@ a variety of settings appropriate for your MPI installation.
Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP)
Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP)
----------
.. _exe:
Build LAMMPS as an executable or a library
@ -264,8 +290,11 @@ page for more info on coupling LAMMPS to other codes. See the
:doc:`Python <Python_head>` doc page for more info on wrapping and
running LAMMPS from Python via its library interface.
**CMake variables**\ :
**CMake build**\ :
For CMake builds, you can select through setting CMake variables which
files the compilation produces during the configuration step. If none
are set, defaults are applied.
.. code-block:: bash
@ -276,24 +305,32 @@ running LAMMPS from Python via its library interface.
# no default value
Setting BUILD\_EXE=no will not produce an executable. Setting
BUILD\_LIB=yes will produce a static library named liblammps.a.
BUILD\_LIB=yes will produce a static library named *liblammps.a*\ .
Setting both BUILD\_LIB=yes and BUILD\_SHARED\_LIBS=yes will produce a
shared library named liblammps.so. If LAMMPS\_LIB\_SUFFIX is set the generated
libraries will be named liblammps\_name.a or liblammps\_name.so instead.
shared library named *liblammps.so* instead. If LAMMPS\_LIB\_SUFFIX is
set to *name* in addition, the name of the generated libraries will be
changed to either *liblammps\_name.a* or *liblammps\_name.so*\ ,
respectively.
**Traditional make**\ :
With the traditional makefile based build process, the choice of
the generated executable or library depends on the "mode" setting.
Several options are available and "mode=exe" is the default.
.. code-block:: bash
cd lammps/src
make machine # build LAMMPS executable lmp_machine
mkae mode=exe machine # same as "make machine"
make mode=lib machine # build LAMMPS static lib liblammps_machine.a
make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so
make mode=shexe machine # same as "mode=exe" but uses objects from "mode=shlib"
The two library builds also create generic soft links, named
liblammps.a and liblammps.so, which point to the liblammps\_machine
files.
The two "exe" builds will generate and executable *lmp\_machine*\ ,
while the two library builds will create a file *liblammps\_machine.a*
or *liblammps\_machine.so*\ . They will also create generic soft links,
named *liblammps.a* and *liblammps.so*\ , which point to the specific
*liblammps\_machine.a/so* files.
**CMake and make info**\ :
@ -301,21 +338,19 @@ 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 LAMMPS,
such as the dummy MPI library in src/STUBS or any package libraries in
the lib/packages directory, since they are always built as shared
libraries using the -fPIC switch. However, if a library like MPI or
FFTW does not exist as a shared library, the shared library build will
generate an error. This means you will need to install a shared
library version of the auxiliary library. 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 Lab, as a shared library in the default
/usr/local/lib location:
.. _mpich: http://www-unix.mcs.anl.gov/mpi
the lib/packages directory, since they are always built in a shared
library compatible way using the -fPIC switch. However, if a library
like MPI or FFTW does not exist as a shared library, the shared library
build may generate an error. This means you will need to install a
shared library version of the auxiliary library. 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, as a shared library
in the default /usr/local/lib location:
.. _mpich: https://www.mpich.org
.. code-block:: bash
@ -323,10 +358,20 @@ Argonne National Lab, as a shared library in the default
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.
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. On many Linux installations the
folder "${HOME}/.local" is an alternative to using /usr/local and does
not require superuser or sudo access. In that case the configuration
step becomes:
.. code-block:: bash
./configure --enable-shared --prefix=${HOME}/.local
Avoiding using "sudo" for custom software installation (i.e. from source
and not through a package manager tool provided by the OS) is generally
recommended to ensure the integrity of the system software installation.
----------
@ -400,14 +445,15 @@ Build LAMMPS tools
Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
using CMake or Make.
**CMake variable**\ :
**CMake build3**\ :
.. code-block:: bash
-D BUILD_TOOLS=value # yes or no (default)
The generated binaries will also become part of the LAMMPS installation (see below)
The generated binaries will also become part of the LAMMPS installation
(see below).
**Traditional make**\ :
@ -436,7 +482,7 @@ a globally visible place on your system, for others to access. Note
that you may need super-user privileges (e.g. sudo) if the directory
you want to copy files to is protected.
**CMake variable**\ :
**CMake build**\ :
.. code-block:: bash

4
doc/src/Build_extras.rst
View File

@ -1191,9 +1191,9 @@ See src/MAKE/OPTIONS/Makefile.omp for an example.
.. parsed-literal::
CCFLAGS: -fopenmp # for GNU and CLang Compilers
CCFLAGS: -fopenmp # for GNU and Clang Compilers
CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
LINKFLAGS: -fopenmp # for GNU and CLang Compilers
LINKFLAGS: -fopenmp # for GNU and Clang Compilers
LINKFLAGS: -qopenmp # for Intel compilers on Linux
For other platforms and compilers, please consult the documentation

16
doc/src/python.rst
View File

@ -337,15 +337,15 @@ Python function is as follows:
...
The function definition must include a variable (lmpptr in this case)
which corresponds to SELF in the python command. The first line of
the function imports the Python module lammps.py in the python dir of
which corresponds to SELF in the python command. The first line of the
function imports the Python module lammps.py in the python directory of
the distribution. The second line creates a Python object "lmp" which
wraps the instance of LAMMPS that called the function. The
"ptr=lmpptr" argument is what makes that happen. The third line
invokes the command() function in the LAMMPS library interface. It
takes a single string argument which is a LAMMPS input script command
for LAMMPS to execute, the same as if it appeared in your input
script. In this case, LAMMPS should output
wraps the instance of LAMMPS that called the function. The "ptr=lmpptr"
argument is what makes that happen. The third line invokes the
command() function in the LAMMPS library interface. It takes a single
string argument which is a LAMMPS input script command for LAMMPS to
execute, the same as if it appeared in your input script. In this case,
LAMMPS should output
.. parsed-literal::

1
doc/utils/sphinx-config/false_positives.txt
View File

@ -1543,6 +1543,7 @@ Liu
Livermore
lj
llammps
LLVM
lm
lmp
lmpptr