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

make subheaders and typesetting more consistent

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-06-14 12:41:19 -04:00
parent 4042b836c2
commit 5abfcde3f7
3 changed files with 330 additions and 255 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
doc/src/Build_basics.rst
View File

@ -372,7 +372,8 @@ it. The build step will also create generic soft links, named
``liblammps.a`` and ``liblammps.so``\ , which point to the specific ``liblammps.a`` and ``liblammps.so``\ , which point to the specific
``liblammps_machine.a/so`` files. ``liblammps_machine.a/so`` files.
**CMake and make info**\ : CMake and make info
^^^^^^^^^^^^^^^^^^^
Note that for creating a shared library, all the libraries it depends on Note that for creating a shared library, all the libraries it depends on
must be compiled to be compatible with shared libraries. This should be must be compiled to be compatible with shared libraries. This should be
@ -462,7 +463,8 @@ tool. The actual translation is then done via make commands.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html .. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://sphinx-doc.org .. _sphinx: https://sphinx-doc.org
**Documentation make option**\ : Documentation make option
^^^^^^^^^^^^^^^^^^^^^^^^^
The following make commands can be issued in the doc folder of the The following make commands can be issued in the doc folder of the
LAMMPS source distribution. LAMMPS source distribution.
@ -489,7 +491,8 @@ your system.
current LAMMPS version (HTML and PDF files), from the website current LAMMPS version (HTML and PDF files), from the website
`download page <https://lammps.sandia.gov/download.html>`_. `download page <https://lammps.sandia.gov/download.html>`_.
**CMake build option**\ : CMake build option
^^^^^^^^^^^^^^^^^^
It is also possible to create the HTML version of the manual within It is also possible to create the HTML version of the manual within
the :doc:`CMake build directory <Build_cmake>`. The reason for this the :doc:`CMake build directory <Build_cmake>`. The reason for this
@ -512,7 +515,8 @@ Build LAMMPS tools
Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly Some tools described in :doc:`Auxiliary tools <Tools>` can be built directly
using CMake or Make. using CMake or Make.
**CMake build3**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -521,7 +525,8 @@ using CMake or Make.
The generated binaries will also become part of the LAMMPS installation The generated binaries will also become part of the LAMMPS installation
(see below). (see below).
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -545,7 +550,8 @@ 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 that you may need super-user privileges (e.g. sudo) if the directory
you want to copy files to is protected. you want to copy files to is protected.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -553,7 +559,8 @@ you want to copy files to is protected.
make # perform make after CMake command make # perform make after CMake command
make install # perform the installation into prefix make install # perform the installation into prefix
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
There is no "install" option in the ``src/Makefile`` for LAMMPS. If There is no "install" option in the ``src/Makefile`` for LAMMPS. If
you wish to do this you will need to first build LAMMPS, then manually you wish to do this you will need to first build LAMMPS, then manually

501
doc/src/Build_extras.rst
View File

@ -59,12 +59,13 @@ This is the list of packages that may require additional steps.
.. _compress: .. _compress:
COMPRESS package COMPRESS package
------------------------------- ----------------
To build with this package you must have the zlib compression library To build with this package you must have the zlib compression library
available on your system. available on your system.
**CMake build**\ : CMake build
^^^^^^^^^^^
If CMake cannot find the library, you can set these variables: If CMake cannot find the library, you can set these variables:
@ -73,10 +74,11 @@ If CMake cannot find the library, you can set these variables:
-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file -D ZLIB_LIBRARIES=path # path to libz.a (.so) file
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
If make cannot find the library, you can edit the file If make cannot find the library, you can edit the file
lib/compress/Makefile.lammps to specify the paths and library ``lib/compress/Makefile.lammps`` to specify the paths and library
name. name.
---------- ----------
@ -90,7 +92,8 @@ To build with this package, you must choose options for precision and
which GPU hardware to build for. The GPU package currently supports which GPU hardware to build for. The GPU package currently supports
three different types of backends: OpenCL, CUDA and HIP. three different types of backends: OpenCL, CUDA and HIP.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -158,7 +161,8 @@ and the linker to work correctly.
cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=sm_70 .. cmake -D PKG_GPU=on -D GPU_API=HIP -D HIP_ARCH=sm_70 ..
make -j 4 make -j 4
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ . Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ .
You can do this manually if you prefer; follow the instructions in You can do this manually if you prefer; follow the instructions in
@ -207,10 +211,10 @@ your machine are not correct, the LAMMPS build will fail, and
.. note:: .. note::
If you re-build the GPU library in lib/gpu, you should always If you re-build the GPU library in ``lib/gpu``, you should always
un-install the GPU package in lammps/src, then re-install it and un-install the GPU package in ``lammps/src``, then re-install it and
re-build LAMMPS. This is because the compilation of files in the GPU re-build LAMMPS. This is because the compilation of files in the GPU
package uses the library settings from the lib/gpu/Makefile.machine package uses the library settings from the ``lib/gpu/Makefile.machine``
used to build the GPU library. used to build the GPU library.
---------- ----------
@ -249,7 +253,8 @@ See the list of all KIM models here: https://openkim.org/browse/models
the KIM API library with all its models, may take a long time (tens of the KIM API library with all its models, may take a long time (tens of
minutes to hours) to build. Of course you only need to do that once.) minutes to hours) to build. Of course you only need to do that once.)
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -281,7 +286,8 @@ As an alternative, you can specify your own CA cert path by setting the
environment variable ``CURL_CA_BUNDLE`` to the path of your choice. A call environment variable ``CURL_CA_BUNDLE`` to the path of your choice. A call
to the KIM web query would get this value from the environmental variable. to the KIM web query would get this value from the environmental variable.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download and build the KIM library manually if you prefer; You can download and build the KIM library manually if you prefer;
follow the instructions in ``lib/kim/README``\ . You can also do it in one follow the instructions in ``lib/kim/README``\ . You can also do it in one
@ -299,7 +305,7 @@ invoke the ``lib/kim/Install.py`` script with the specified args.
$ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
Settings for OpenKIM web queries discussed above need to be applied by adding Settings for OpenKIM web queries discussed above need to be applied by adding
them to the ``LMP_INC`` variable through editing the Makefile.machine you are them to the ``LMP_INC`` variable through editing the ``Makefile.machine`` you are
using. For example: using. For example:
.. code-block:: make .. code-block:: make
@ -604,7 +610,8 @@ LATTE package
To build with this package, you must download and build the LATTE To build with this package, you must download and build the LATTE
library. library.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -617,7 +624,8 @@ already on your system (in a location CMake cannot find it),
``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library file, ``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library file,
not the directory the library file is in. not the directory the library file is in.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download and build the LATTE library manually if you prefer; You can download and build the LATTE library manually if you prefer;
follow the instructions in ``lib/latte/README``\ . You can also do it in follow the instructions in ``lib/latte/README``\ . You can also do it in
@ -633,11 +641,12 @@ args:
$ make lib-latte args="-b -m gfortran" # download and build in lib/latte and $ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps # copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, "includelink" and "liblink" and Note that 3 symbolic (soft) links, ``includelink`` and ``liblink`` and
"filelink.o", are created in lib/latte to point into the LATTE home ``filelink.o``, are created in ``lib/latte`` to point to required
dir. When LAMMPS itself is built it will use these links. You should folders and files in the LATTE home directory. When LAMMPS itself is
also check that the Makefile.lammps file you create is appropriate for built it will use these links. You should also check that the
the compiler you use on your system to build LATTE. ``Makefile.lammps`` file you create is appropriate for the compiler you
use on your system to build LATTE.
---------- ----------
@ -650,7 +659,8 @@ This package can optionally include support for messaging via sockets,
using the open-source `ZeroMQ library <http://zeromq.org>`_, which must using the open-source `ZeroMQ library <http://zeromq.org>`_, which must
be installed on your system. be installed on your system.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -658,7 +668,8 @@ be installed on your system.
-D ZMQ_LIBRARY=path # ZMQ library file (only needed if a custom location) -D ZMQ_LIBRARY=path # ZMQ library file (only needed if a custom location)
-D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location) -D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location)
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the CSlib library in Before building LAMMPS, you must build the CSlib library in
``lib/message``\ . You can build the CSlib library manually if you prefer; ``lib/message``\ . You can build the CSlib library manually if you prefer;
@ -673,8 +684,8 @@ simply invoke the ``lib/message/Install.py`` script with the specified args:
$ make lib-message args="-s" # build as serial lib with no ZMQ support $ make lib-message args="-s" # build as serial lib with no ZMQ support
The build should produce two files: ``lib/message/cslib/src/libmessage.a`` The build should produce two files: ``lib/message/cslib/src/libmessage.a``
and ``lib/message/Makefile.lammps``\ . The latter is copied from an and ``lib/message/Makefile.lammps``. The latter is copied from an
existing ``Makefile.lammps.\*`` and has settings to link with the ZeroMQ existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ
library if requested in the build. library if requested in the build.
---------- ----------
@ -690,7 +701,8 @@ library. Building the MS-CG library requires that the GSL
machine. See the ``lib/mscg/README`` and ``MSCG/Install`` files for machine. See the ``lib/mscg/README`` and ``MSCG/Install`` files for
more details. more details.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -705,7 +717,8 @@ filename (plus path) of the MSCG library file, not the directory the
library file is in. ``MSCG_INCLUDE_DIR`` is the directory the MSCG library file is in. ``MSCG_INCLUDE_DIR`` is the directory the MSCG
include file is in. include file is in.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download and build the MS-CG library manually if you prefer; You can download and build the MS-CG library manually if you prefer;
follow the instructions in ``lib/mscg/README``\ . You can also do it in one follow the instructions in ``lib/mscg/README``\ . You can also do it in one
@ -733,16 +746,18 @@ not need to edit the ``lib/mscg/Makefile.lammps`` file.
OPT package OPT package
--------------------- ---------------------
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides ``-D PKG_OPT=yes`` No additional settings are needed besides ``-D PKG_OPT=yes``
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The compile flag "-restrict" must be used to build LAMMPS with the OPT The compile flag ``-restrict`` must be used to build LAMMPS with the OPT
package when using Intel compilers. It should be added to the CCFLAGS package when using Intel compilers. It should be added to the CCFLAGS
line of your Makefile.machine. See src/MAKE/OPTIONS/Makefile.opt for line of your ``Makefile.machine``. See
an example. ``src/MAKE/OPTIONS/Makefile.opt`` for an example.
---------- ----------
@ -751,11 +766,13 @@ an example.
POEMS package POEMS package
------------------------- -------------------------
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides ``-D PKG_OPT=yes`` No additional settings are needed besides ``-D PKG_OPT=yes``
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the POEMS library in ``lib/poems``\ . Before building LAMMPS, you must build the POEMS library in ``lib/poems``\ .
You can do this manually if you prefer; follow the instructions in You can do this manually if you prefer; follow the instructions in
@ -771,8 +788,8 @@ dir, using a command like these, which simply invoke the
$ make lib-poems args="-m icc" # build with Intel icc compiler $ make lib-poems args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/poems/libpoems.a`` and The build should produce two files: ``lib/poems/libpoems.a`` and
``lib/poems/Makefile.lammps``\ . The latter is copied from an existing ``lib/poems/Makefile.lammps``. The latter is copied from an existing
``Makefile.lammps.\*`` and has settings needed to build LAMMPS with the ``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
POEMS library (though typically the settings are just blank). If POEMS library (though typically the settings are just blank). If
necessary, you can edit/create a new ``lib/poems/Makefile.machine`` file necessary, you can edit/create a new ``lib/poems/Makefile.machine`` file
for your system, which should define an ``EXTRAMAKE`` variable to specify for your system, which should define an ``EXTRAMAKE`` variable to specify
@ -790,7 +807,8 @@ library available on your system, which needs to be a Python 2.7
version or a Python 3.x version. See ``lib/python/README`` for more version or a Python 3.x version. See ``lib/python/README`` for more
details. details.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -803,11 +821,12 @@ PYTHON_EXECUTABLE variable to specify which Python interpreter should
be used. Note note that you will also need to have the development be used. Note note that you will also need to have the development
headers installed for this version, e.g. python2-devel. headers installed for this version, e.g. python2-devel.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The build uses the ``lib/python/Makefile.lammps`` file in the compile/link The build uses the ``lib/python/Makefile.lammps`` file in the compile/link
process to find Python. You should only need to create a new process to find Python. You should only need to create a new
``Makefile.lammps.\*`` file (and copy it to ``Makefile.lammps``\ ) if ``Makefile.lammps.*`` file (and copy it to ``Makefile.lammps``) if
the LAMMPS build fails. the LAMMPS build fails.
---------- ----------
@ -821,7 +840,8 @@ To build with this package, you must download and build the `Voro++ library <vor
.. _voro-home: http://math.lbl.gov/voro++ .. _voro-home: http://math.lbl.gov/voro++
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -829,19 +849,20 @@ To build with this package, you must download and build the `Voro++ library <vor
-D VORO_LIBRARY=path # Voro++ library file (only needed if at custom location) -D VORO_LIBRARY=path # Voro++ library file (only needed if at custom location)
-D VORO_INCLUDE_DIR=path # Voro++ include directory (only needed if at custom location) -D VORO_INCLUDE_DIR=path # Voro++ include directory (only needed if at custom location)
If DOWNLOAD_VORO is set, the Voro++ library will be downloaded and If ``DOWNLOAD_VORO`` is set, the Voro++ library will be downloaded and
built inside the CMake build directory. If the Voro++ library is built inside the CMake build directory. If the Voro++ library is
already on your system (in a location CMake cannot find it), already on your system (in a location CMake cannot find it),
VORO_LIBRARY is the filename (plus path) of the Voro++ library file, ``VORO_LIBRARY`` is the filename (plus path) of the Voro++ library file,
not the directory the library file is in. VORO_INCLUDE_DIR is the not the directory the library file is in. ``VORO_INCLUDE_DIR`` is the
directory the Voro++ include file is in. directory the Voro++ include file is in.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download and build the Voro++ library manually if you prefer; You can download and build the Voro++ library manually if you prefer;
follow the instructions in lib/voronoi/README. You can also do it in follow the instructions in ``lib/voronoi/README``. You can also do it in
one step from the lammps/src dir, using a command like these, which one step from the ``lammps/src`` dir, using a command like these, which
simply invoke the lib/voronoi/Install.py script with the specified simply invoke the ``lib/voronoi/Install.py`` script with the specified
args: args:
.. code-block:: bash .. code-block:: bash
@ -851,10 +872,10 @@ args:
$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++ $ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6 $ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
Note that 2 symbolic (soft) links, "includelink" and "liblink", are Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are
created in lib/voronoi to point to the Voro++ src dir. When LAMMPS created in lib/voronoi to point to the Voro++ source dir. When LAMMPS
builds in src it will use these links. You should not need to edit builds in ``src`` it will use these links. You should not need to edit
the lib/voronoi/Makefile.lammps file. the ``lib/voronoi/Makefile.lammps`` file.
---------- ----------
@ -863,23 +884,28 @@ the lib/voronoi/Makefile.lammps file.
USER-ADIOS package USER-ADIOS package
----------------------------------- -----------------------------------
The USER-ADIOS package requires the `ADIOS I/O library <https://github.com/ornladios/ADIOS2>`_, The USER-ADIOS package requires the `ADIOS I/O library
version 2.3.1 or newer. Make sure that you have ADIOS built either with or <https://github.com/ornladios/ADIOS2>`_, version 2.3.1 or newer. Make
without MPI to match if you build LAMMPS with or without MPI. sure that you have ADIOS built either with or without MPI to match if
ADIOS compilation settings for LAMMPS are automatically detected, if the PATH you build LAMMPS with or without MPI. ADIOS compilation settings for
and LD_LIBRARY_PATH environment variables have been updated for the local ADIOS LAMMPS are automatically detected, if the PATH and LD_LIBRARY_PATH
installation and the instructions below are followed for the respective build systems. environment variables have been updated for the local ADIOS installation
and the instructions below are followed for the respective build
systems.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D ADIOS2_DIR=path # path is where ADIOS 2.x is installed -D ADIOS2_DIR=path # path is where ADIOS 2.x is installed
-D PKG_USER-ADIOS=yes -D PKG_USER-ADIOS=yes
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Turn on the USER-ADIOS package before building LAMMPS. If the ADIOS 2.x software is installed in PATH, there is nothing else to do: Turn on the USER-ADIOS package before building LAMMPS. If the ADIOS 2.x
software is installed in PATH, there is nothing else to do:
.. code-block:: bash .. code-block:: bash
@ -900,18 +926,20 @@ USER-ATC package
The USER-ATC package requires the MANYBODY package also be installed. The USER-ATC package requires the MANYBODY package also be installed.
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides "-D PKG_USER-ATC=yes" No additional settings are needed besides "-D PKG_USER-ATC=yes"
and "-D PKG_MANYBODY=yes". and "-D PKG_MANYBODY=yes".
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the ATC library in lib/atc. Before building LAMMPS, you must build the ATC library in ``lib/atc``.
You can do this manually if you prefer; follow the instructions in You can do this manually if you prefer; follow the instructions in
lib/atc/README. You can also do it in one step from the lammps/src ``lib/atc/README``. You can also do it in one step from the
dir, using a command like these, which simply invoke the ``lammps/src`` dir, using a command like these, which simply invoke the
lib/atc/Install.py script with the specified args: ``lib/atc/Install.py`` script with the specified args:
.. code-block:: bash .. code-block:: bash
@ -920,19 +948,19 @@ lib/atc/Install.py script with the specified args:
$ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi") $ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-atc args="-m icc" # build with Intel icc compiler $ make lib-atc args="-m icc" # build with Intel icc compiler
The build should produce two files: lib/atc/libatc.a and The build should produce two files: ``lib/atc/libatc.a`` and
lib/atc/Makefile.lammps. The latter is copied from an existing ``lib/atc/Makefile.lammps``. The latter is copied from an existing
Makefile.lammps.\* and has settings needed to build LAMMPS with the ATC ``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
library. If necessary, you can edit/create a new ATC library. If necessary, you can edit/create a new
lib/atc/Makefile.machine file for your system, which should define an ``lib/atc/Makefile.machine`` file for your system, which should define
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine an ``EXTRAMAKE`` variable to specify a corresponding
file. ``Makefile.lammps.<machine>`` file.
Note that the Makefile.lammps file has settings for the BLAS and Note that the Makefile.lammps file has settings for the BLAS and
LAPACK linear algebra libraries. As explained in lib/atc/README these LAPACK linear algebra libraries. As explained in ``lib/atc/README`` these
can either exist on your system, or you can use the files provided in can either exist on your system, or you can use the files provided in
lib/linalg. In the latter case you also need to build the library in ``lib/linalg``. In the latter case you also need to build the library in
lib/linalg with a command like these: ``lib/linalg`` with a command like these:
.. code-block:: bash .. code-block:: bash
@ -946,19 +974,21 @@ lib/linalg with a command like these:
.. _user-awpmd: .. _user-awpmd:
USER-AWPMD package USER-AWPMD package
----------------------------------- ------------------
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides "-D PKG_USER-AQPMD=yes". No additional settings are needed besides ``-D PKG_USER-AQPMD=yes``.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the AWPMD library in lib/awpmd. Before building LAMMPS, you must build the AWPMD library in ``lib/awpmd``.
You can do this manually if you prefer; follow the instructions in You can do this manually if you prefer; follow the instructions in
lib/awpmd/README. You can also do it in one step from the lammps/src ``lib/awpmd/README``. You can also do it in one step from the ``lammps/src``
dir, using a command like these, which simply invoke the dir, using a command like these, which simply invoke the
lib/awpmd/Install.py script with the specified args: ``lib/awpmd/Install.py`` script with the specified args:
.. code-block:: bash .. code-block:: bash
@ -967,19 +997,19 @@ lib/awpmd/Install.py script with the specified args:
$ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi") $ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-awpmd args="-m icc" # build with Intel icc compiler $ make lib-awpmd args="-m icc" # build with Intel icc compiler
The build should produce two files: lib/awpmd/libawpmd.a and The build should produce two files: ``lib/awpmd/libawpmd.a`` and
lib/awpmd/Makefile.lammps. The latter is copied from an existing ``lib/awpmd/Makefile.lammps``. The latter is copied from an existing
Makefile.lammps.\* and has settings needed to build LAMMPS with the ``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
AWPMD library. If necessary, you can edit/create a new AWPMD library. If necessary, you can edit/create a new
lib/awpmd/Makefile.machine file for your system, which should define ``lib/awpmd/Makefile.machine`` file for your system, which should define
an EXTRAMAKE variable to specify a corresponding an ``EXTRAMAKE`` variable to specify a corresponding
Makefile.lammps.machine file. ``Makefile.lammps.<machine>`` file.
Note that the Makefile.lammps file has settings for the BLAS and Note that the ``Makefile.lammps`` file has settings for the BLAS and
LAPACK linear algebra libraries. As explained in lib/awpmd/README LAPACK linear algebra libraries. As explained in ``lib/awpmd/README``
these can either exist on your system, or you can use the files these can either exist on your system, or you can use the files
provided in lib/linalg. In the latter case you also need to build the provided in ``lib/linalg``. In the latter case you also need to build the
library in lib/linalg with a command like these: library in ``lib/linalg`` with a command like these:
.. code-block:: bash .. code-block:: bash
@ -998,36 +1028,26 @@ USER-COLVARS package
This package includes into the LAMMPS distribution the Colvars library, which This package includes into the LAMMPS distribution the Colvars library, which
can be built for the most part with all major versions of the C++ language. can be built for the most part with all major versions of the C++ language.
A few of the most recent features require C++11 support. In particular, the
library is optionally built together with the
`Lepton <https://simtk.org/projects/lepton>`_ library, a copy of which is also
included in the LAMMPS distribution. Lepton implements the
`customFunction <http://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#colvar|customFunction>`_
feature, and requires C++11 support.
See `here <https://colvars.github.io/README-c++11.html>`_ for a detailed list of CMake build
C++11-only features. ^^^^^^^^^^^
**CMake build**\ :
This is the recommended build recipe: no additional settings are normally This is the recommended build recipe: no additional settings are normally
needed besides "-D PKG_USER-COLVARS=yes". needed besides ``-D PKG_USER-COLVARS=yes``.
Building and linking of Lepton (or other C++11-only features) is enabled Traditional make
automatically when compilation is carried out with C++11 support, and disabled ^^^^^^^^^^^^^^^^
otherwise. Optionally, Lepton build may be manually controlled with the flag
"-D COLVARS_LEPTON=yes\|no".
**Traditional make**\ :
Before building LAMMPS, one must build the Colvars library in lib/colvars. Before building LAMMPS, one must build the Colvars library in lib/colvars.
This can be done manually in the same folder by using or adapting one of the This can be done manually in the same folder by using or adapting one of
provided Makefiles: for example, Makefile.g++ for the GNU compiler. the provided Makefiles: for example, ``Makefile.g++`` for the GNU C++
compiler. C++11 compatibility may need to be enabled for some older
compilers (as is done in the example makefile).
In general, it is safer to use build setting consistent with the rest of In general, it is safer to use build setting consistent with the rest of
LAMMPS. This is best carried out from the LAMMPS src directory using a LAMMPS. This is best carried out from the LAMMPS src directory using a
command like these, which simply invoke the lib/colvars/Install.py script with command like these, which simply invoke the ``lib/colvars/Install.py`` script with
the specified args: the specified args:
.. code-block:: bash .. code-block:: bash
@ -1038,7 +1058,7 @@ the specified args:
$ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled $ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
The "machine" argument of the "-m" flag is used to find a Makefile.machine to The "machine" argument of the "-m" flag is used to find a Makefile.machine to
use as build recipe. If it does not already exist in lib/colvars, it will be use as build recipe. If it does not already exist in ``lib/colvars``, it will be
auto-generated by using compiler flags consistent with those parsed from the auto-generated by using compiler flags consistent with those parsed from the
core LAMMPS makefiles. core LAMMPS makefiles.
@ -1049,9 +1069,9 @@ Optional flags may be specified as environment variables:
$ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower) $ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
$ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise) $ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
The build should produce two files: the library lib/colvars/libcolvars.a The build should produce two files: the library ``lib/colvars/libcolvars.a``
(which also includes Lepton objects if enabled) and the specification file (which also includes Lepton objects if enabled) and the specification file
lib/colvars/Makefile.lammps. The latter is auto-generated, and normally does ``lib/colvars/Makefile.lammps``. The latter is auto-generated, and normally does
not need to be edited. not need to be edited.
---------- ----------
@ -1098,12 +1118,14 @@ try a different one, switch to a different build system, consider a
global PLUMED installation or consider downloading PLUMED during the global PLUMED installation or consider downloading PLUMED during the
LAMMPS build. LAMMPS build.
**CMake build**\ : CMake build
^^^^^^^^^^^
When the "-D PKG_USER-PLUMED" flag is included in the cmake command you When the ``-D PKG_USER-PLUMED=yes`` flag is included in the cmake
must ensure that GSL is installed in locations that are specified in command you must ensure that GSL is installed in locations that are
your environment. There are then two additional commands that control specified in your environment. There are then two additional variables
the manner in which PLUMED is obtained and linked into LAMMPS. that control the manner in which PLUMED is obtained and linked into
LAMMPS.
.. code-block:: bash .. code-block:: bash
@ -1113,21 +1135,22 @@ the manner in which PLUMED is obtained and linked into LAMMPS.
If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be
downloaded (the version of PLUMED that will be downloaded is hard-coded downloaded (the version of PLUMED that will be downloaded is hard-coded
to a vetted version of PLUMED, usually a recent stable release version) to a vetted version of PLUMED, usually a recent stable release version)
and built inside the CMake build directory. If DOWNLOAD_PLUMED is set and built inside the CMake build directory. If ``DOWNLOAD_PLUMED`` is
to "no" (the default), CMake will try to detect and link to an installed set to "no" (the default), CMake will try to detect and link to an
version of PLUMED. For this to work, the PLUMED library has to be installed version of PLUMED. For this to work, the PLUMED library has
installed into a location where the pkg-config tool can find it or the to be installed into a location where the ``pkg-config`` tool can find
PKG_CONFIG_PATH environment variable has to be set up accordingly. it or the PKG_CONFIG_PATH environment variable has to be set up
PLUMED should be installed in such a location if you compile it using accordingly. PLUMED should be installed in such a location if you
the default make; make install commands. compile it using the default make; make install commands.
The PLUMED_MODE setting determines the linkage mode for the PLUMED The ``PLUMED_MODE`` setting determines the linkage mode for the PLUMED
library. The allowed values for this flag are "static" (default), library. The allowed values for this flag are "static" (default),
"shared", or "runtime". For a discussion of PLUMED linkage modes, "shared", or "runtime". For a discussion of PLUMED linkage modes,
please see above. When DOWNLOAD_PLUMED is enabled the static linkage please see above. When ``DOWNLOAD_PLUMED`` is enabled the static
mode is recommended. linkage mode is recommended.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
PLUMED needs to be installed before the USER-PLUMED package is installed PLUMED needs to be installed before the USER-PLUMED package is installed
so that LAMMPS can find the right settings when compiling and linking so that LAMMPS can find the right settings when compiling and linking
@ -1148,9 +1171,9 @@ from the src folder through the following make args:
$ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in $ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in
# /usr/local and use shared linkage mode # /usr/local and use shared linkage mode
Note that 2 symbolic (soft) links, "includelink" and "liblink" are Note that 2 symbolic (soft) links, ``includelink`` and ``liblink`` are
created in lib/plumed that point to the location of the PLUMED build to created in lib/plumed that point to the location of the PLUMED build to
use. A new file lib/plumed/Makefile.lammps is also created with settings use. A new file ``lib/plumed/Makefile.lammps`` is also created with settings
suitable for LAMMPS to compile and link PLUMED using the desired linkage suitable for LAMMPS to compile and link PLUMED using the desired linkage
mode. After this step is completed, you can install the USER-PLUMED mode. After this step is completed, you can install the USER-PLUMED
package and compile LAMMPS in the usual manner: package and compile LAMMPS in the usual manner:
@ -1185,9 +1208,10 @@ To build with this package you must have the HDF5 software package
installed on your system, which should include the h5cc compiler and installed on your system, which should include the h5cc compiler and
the HDF5 library. the HDF5 library.
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides "-D PKG_USER-H5MD=yes". No additional settings are needed besides ``-D PKG_USER-H5MD=yes``.
This should auto-detect the H5MD library on your system. Several This should auto-detect the H5MD library on your system. Several
advanced CMake H5MD options exist if you need to specify where it is advanced CMake H5MD options exist if you need to specify where it is
@ -1195,26 +1219,27 @@ installed. Use the ccmake (terminal window) or cmake-gui (graphical)
tools to see these options and set them interactively from their user tools to see these options and set them interactively from their user
interfaces. interfaces.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the CH5MD library in lib/h5md. Before building LAMMPS, you must build the CH5MD library in
You can do this manually if you prefer; follow the instructions in ``lib/h5md``. You can do this manually if you prefer; follow the
lib/h5md/README. You can also do it in one step from the lammps/src instructions in ``lib/h5md/README``. You can also do it in one step
dir, using a command like these, which simply invoke the from the ``lammps/src`` dir, using a command like these, which simply
lib/h5md/Install.py script with the specified args: invoke the ``lib/h5md/Install.py`` script with the specified args:
.. code-block:: bash .. code-block:: bash
$ make lib-h5md # print help message $ make lib-h5md # print help message
$ make lib-h5md args="-m h5cc" # build with h5cc compiler $ make lib-h5md args="-m h5cc" # build with h5cc compiler
The build should produce two files: lib/h5md/libch5md.a and The build should produce two files: ``lib/h5md/libch5md.a`` and
lib/h5md/Makefile.lammps. The latter is copied from an existing ``lib/h5md/Makefile.lammps``. The latter is copied from an existing
Makefile.lammps.\* and has settings needed to build LAMMPS with the ``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
system HDF5 library. If necessary, you can edit/create a new system HDF5 library. If necessary, you can edit/create a new
lib/h5md/Makefile.machine file for your system, which should define an ``lib/h5md/Makefile.machine`` file for your system, which should define
EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine an EXTRAMAKE variable to specify a corresponding
file. ``Makefile.lammps.<machine>`` file.
---------- ----------
@ -1229,7 +1254,8 @@ also typically :ref:`install the USER-OMP package <user-omp>`, as it can be
used in tandem with the USER-INTEL package to good effect, as explained used in tandem with the USER-INTEL package to good effect, as explained
on the :doc:`Speed intel <Speed_intel>` doc page. on the :doc:`Speed intel <Speed_intel>` doc page.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -1248,11 +1274,12 @@ Best performance is achieved with Intel hardware, Intel compilers, as well as
the Intel TBB and MKL libraries. However, the code also compiles, links, and the Intel TBB and MKL libraries. However, the code also compiles, links, and
runs with other compilers and without TBB and MKL. runs with other compilers and without TBB and MKL.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Choose which hardware to compile for in Makefile.machine via the Choose which hardware to compile for in Makefile.machine via the
following settings. See src/MAKE/OPTIONS/Makefile.intel_cpu\* and following settings. See ``src/MAKE/OPTIONS/Makefile.intel_cpu*`` and
Makefile.knl files for examples. and src/USER-INTEL/README for ``Makefile.knl`` files for examples. and ``src/USER-INTEL/README`` for
additional information. additional information.
For CPUs: For CPUs:
@ -1280,7 +1307,8 @@ For KNLs:
USER-MOLFILE package USER-MOLFILE package
--------------------------------------- ---------------------------------------
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -1295,13 +1323,14 @@ folder of the local VMD installation in use. LAMMPS ships with a
couple of default header files that correspond to a popular VMD couple of default header files that correspond to a popular VMD
version, usually the latest release. version, usually the latest release.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The lib/molfile/Makefile.lammps file has a setting for a dynamic The ``lib/molfile/Makefile.lammps`` file has a setting for a dynamic
loading library libdl.a that is typically present on all systems. It loading library libdl.a that is typically present on all systems. It
is required for LAMMPS to link with this package. If the setting is is required for LAMMPS to link with this package. If the setting is
not valid for your system, you will need to edit the Makefile.lammps not valid for your system, you will need to edit the Makefile.lammps
file. See lib/molfile/README and lib/molfile/Makefile.lammps for file. See ``lib/molfile/README`` and ``lib/molfile/Makefile.lammps`` for
details. It is also possible to configure a different folder with details. It is also possible to configure a different folder with
the VMD molfile plugin header files. LAMMPS ships with a couple of the VMD molfile plugin header files. LAMMPS ships with a couple of
default headers, but these are not compatible with all VMD versions, default headers, but these are not compatible with all VMD versions,
@ -1318,22 +1347,24 @@ USER-NETCDF package
To build with this package you must have the NetCDF library installed To build with this package you must have the NetCDF library installed
on your system. on your system.
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides "-D PKG_USER-NETCDF=yes". No additional settings are needed besides ``-D PKG_USER-NETCDF=yes``.
This should auto-detect the NETCDF library if it is installed on your This should auto-detect the NETCDF library if it is installed on your
system at standard locations. Several advanced CMake NETCDF options system at standard locations. Several advanced CMake NETCDF options
exist if you need to specify where it was installed. Use the ccmake exist if you need to specify where it was installed. Use the ``ccmake``
(terminal window) or cmake-gui (graphical) tools to see these options (terminal window) or ``cmake-gui`` (graphical) tools to see these
and set them interactively from their user interfaces. options and set them interactively from their user interfaces.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The lib/netcdf/Makefile.lammps file has settings for NetCDF include The ``lib/netcdf/Makefile.lammps`` file has settings for NetCDF include
and library files which LAMMPS needs to build with this package. If and library files which LAMMPS needs to build with this package. If
the settings are not valid for your system, you will need to edit the the settings are not valid for your system, you will need to edit the
Makefile.lammps file. See lib/netcdf/README for details. ``Makefile.lammps`` file. See ``lib/netcdf/README`` for details.
---------- ----------
@ -1342,18 +1373,20 @@ Makefile.lammps file. See lib/netcdf/README for details.
USER-OMP package USER-OMP package
------------------------------- -------------------------------
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are required besides "-D PKG_USER-OMP=yes". If No additional settings are required besides ``-D PKG_USER-OMP=yes``. If
CMake detects OpenMP support, the USER-OMP code will be compiled with CMake detects OpenMP support, the USER-OMP code will be compiled with
multi-threading support enabled, otherwise as optimized serial code. multi-threading support enabled, otherwise as optimized serial code.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
To enable multi-threading support in the USER-OMP package (and other To enable multi-threading support in the USER-OMP package (and other
styles supporting OpenMP) the following compile and link flags must styles supporting OpenMP) the following compile and link flags must be
be added to your Makefile.machine file. added to your Makefile.machine file. See
See src/MAKE/OPTIONS/Makefile.omp for an example. ``src/MAKE/OPTIONS/Makefile.omp`` for an example.
.. parsed-literal:: .. parsed-literal::
@ -1363,8 +1396,7 @@ See src/MAKE/OPTIONS/Makefile.omp for an example.
LINKFLAGS: -qopenmp # for Intel compilers on Linux LINKFLAGS: -qopenmp # for Intel compilers on Linux
For other platforms and compilers, please consult the documentation For other platforms and compilers, please consult the documentation
about OpenMP support for your compiler. Please see the note about about OpenMP support for your compiler.
how to address compatibility :ref:`issues with the 'default(none)' directive <default-none-issues>` of some compilers.
---------- ----------
@ -1374,19 +1406,20 @@ USER-QMMM package
--------------------------------- ---------------------------------
For using LAMMPS to do QM/MM simulations via the USER-QMMM package you For using LAMMPS to do QM/MM simulations via the USER-QMMM package you
need to build LAMMPS as a library. A LAMMPS executable with fix qmmm need to build LAMMPS as a library. A LAMMPS executable with :doc:`fix
included can be built, but will not be able to do a QM/MM simulation qmmm <fix_qmmm>` included can be built, but will not be able to do a
on as such. You must also build a QM code - currently only Quantum QM/MM simulation on as such. You must also build a QM code - currently
ESPRESSO (QE) is supported - and create a new executable which links only Quantum ESPRESSO (QE) is supported - and create a new executable
LAMMPS and the QM code together. Details are given in the which links LAMMPS and the QM code together. Details are given in the
lib/qmmm/README file. It is also recommended to read the instructions ``lib/qmmm/README`` file. It is also recommended to read the
for :doc:`linking with LAMMPS as a library <Build_link>` for instructions for :doc:`linking with LAMMPS as a library <Build_link>`
background information. This requires compatible Quantum Espresso for background information. This requires compatible Quantum Espresso
and LAMMPS versions. The current interface and makefiles have last and LAMMPS versions. The current interface and makefiles have last been
been verified to work in February 2020 with Quantum Espresso versions verified to work in February 2020 with Quantum Espresso versions 6.3 to
6.3 to 6.5. 6.5.
**CMake build**\ : CMake build
^^^^^^^^^^^
When using CMake, building a LAMMPS library is required and it is When using CMake, building a LAMMPS library is required and it is
recommended to build a shared library, since any libraries built from recommended to build a shared library, since any libraries built from
@ -1403,17 +1436,18 @@ would be:
After completing the LAMMPS build and also configuring and compiling After completing the LAMMPS build and also configuring and compiling
Quantum ESPRESSO with external library support (via "make couple"), Quantum ESPRESSO with external library support (via "make couple"),
go back to the lib/qmmm folder and follow the instructions on the go back to the ``lib/qmmm` folder and follow the instructions on the
README file to build the combined LAMMPS/QE QM/MM executable README file to build the combined LAMMPS/QE QM/MM executable
(pwqmmm.x) in the lib/qmmm folder. You need to make certain, that (pwqmmm.x) in the ``lib/qmmm`` folder. You need to make certain, that
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
Before building LAMMPS, you must build the QMMM library in lib/qmmm. Before building LAMMPS, you must build the QMMM library in ``lib/qmmm``.
You can do this manually if you prefer; follow the first two steps You can do this manually if you prefer; follow the first two steps
explained in lib/qmmm/README. You can also do it in one step from the explained in ``lib/qmmm/README``. You can also do it in one step from
lammps/src dir, using a command like these, which simply invoke the the ``lammps/src`` dir, using a command like these, which simply invoke
lib/qmmm/Install.py script with the specified args: the ``lib/qmmm/Install.py`` script with the specified args:
.. code-block:: bash .. code-block:: bash
@ -1422,18 +1456,18 @@ lib/qmmm/Install.py script with the specified args:
$ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi") $ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler $ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
The build should produce two files: lib/qmmm/libqmmm.a and The build should produce two files: ``lib/qmmm/libqmmm.a`` and
lib/qmmm/Makefile.lammps. The latter is copied from an existing ``lib/qmmm/Makefile.lammps``. The latter is copied from an existing
Makefile.lammps.\* and has settings needed to build LAMMPS with the ``Makefile.lammps.*`` and has settings needed to build LAMMPS with the
QMMM library (though typically the settings are just blank). If QMMM library (though typically the settings are just blank). If
necessary, you can edit/create a new lib/qmmm/Makefile.machine file necessary, you can edit/create a new ``lib/qmmm/Makefile.<machine>`` file
for your system, which should define an EXTRAMAKE variable to specify for your system, which should define an ``EXTRAMAKE`` variable to
a corresponding Makefile.lammps.machine file. specify a corresponding ``Makefile.lammps.<machine>`` file.
You can then install QMMM package and build LAMMPS in the usual You can then install QMMM package and build LAMMPS in the usual
manner. After completing the LAMMPS build and compiling Quantum manner. After completing the LAMMPS build and compiling Quantum
ESPRESSO with external library support (via "make couple"), go back to ESPRESSO with external library support (via "make couple"), go back to
the lib/qmmm folder and follow the instructions in the README file to the ``lib/qmmm`` folder and follow the instructions in the README file to
build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the build the combined LAMMPS/QE QM/MM executable (pwqmmm.x) in the
lib/qmmm folder. lib/qmmm folder.
@ -1448,26 +1482,28 @@ To build with this package, you must download and build the QUIP
library. It can be obtained from GitHub. For support of GAP library. It can be obtained from GitHub. For support of GAP
potentials, additional files with specific licensing conditions need potentials, additional files with specific licensing conditions need
to be downloaded and configured. See step 1 and step 1.1 in the to be downloaded and configured. See step 1 and step 1.1 in the
lib/quip/README file for details on how to do this. ``lib/quip/README`` file for details on how to do this.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location) -D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location)
CMake will not download and build the QUIP library. But once you have CMake will not download and build the QUIP library. But once you have
done that, a CMake build of LAMMPS with "-D PKG_USER-QUIP=yes" should done that, a CMake build of LAMMPS with ``-D PKG_USER-QUIP=yes`` should
work. Set QUIP_LIBRARY if CMake cannot find the QUIP library. work. Set QUIP_LIBRARY if CMake cannot find the QUIP library.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The download/build procedure for the QUIP library, described in The download/build procedure for the QUIP library, described in
lib/quip/README file requires setting two environment variables, ``lib/quip/README`` file requires setting two environment variables,
QUIP_ROOT and QUIP_ARCH. These are accessed by the QUIP_ROOT and QUIP_ARCH. These are accessed by the
lib/quip/Makefile.lammps file which is used when you compile and link lib/quip/Makefile.lammps file which is used when you compile and link
LAMMPS with this package. You should only need to edit LAMMPS with this package. You should only need to edit
Makefile.lammps if the LAMMPS build can not use its settings to ``Makefile.lammps`` if the LAMMPS build can not use its settings to
successfully build on your system. successfully build on your system.
---------- ----------
@ -1477,11 +1513,13 @@ successfully build on your system.
USER-SCAFACOS package USER-SCAFACOS package
----------------------------------------- -----------------------------------------
To build with this package, you must download and build the `ScaFaCoS Coulomb solver library <scafacos-home_>`_ To build with this package, you must download and build the `ScaFaCoS
Coulomb solver library <scafacos-home_>`_
.. _scafacos-home: http://www.scafacos.de .. _scafacos-home: http://www.scafacos.de
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -1496,22 +1534,23 @@ SCAFACOS_LIBRARY is the filename (plus path) of the ScaFaCoS library
file, not the directory the library file is in. SCAFACOS_INCLUDE_DIR file, not the directory the library file is in. SCAFACOS_INCLUDE_DIR
is the directory the ScaFaCoS include file is in. is the directory the ScaFaCoS include file is in.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download and build the ScaFaCoS library manually if you You can download and build the ScaFaCoS library manually if you
prefer; follow the instructions in lib/scafacos/README. You can also prefer; follow the instructions in ``lib/scafacos/README``. You can also
do it in one step from the lammps/src dir, using a command like these, do it in one step from the ``lammps/src`` dir, using a command like these,
which simply invoke the lib/scafacos/Install.py script with the which simply invoke the ``lib/scafacos/Install.py`` script with the
specified args: specified args:
make lib-scafacos # print help message make lib-scafacos # print help message
make lib-scafacos args="-b" # download and build in lib/scafacos/scafacos-<version> make lib-scafacos args="-b" # download and build in lib/scafacos/scafacos-<version>
make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS installation in $HOME/scafacos make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS installation in $HOME/scafacos
Note that 2 symbolic (soft) links, "includelink" and "liblink", are Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are
created in lib/scafacos to point to the ScaFaCoS src dir. When LAMMPS created in ``lib/scafacos`` to point to the ScaFaCoS src dir. When LAMMPS
builds in src it will use these links. You should not need to edit builds in src it will use these links. You should not need to edit
the lib/scafacos/Makefile.lammps file. the ``lib/scafacos/Makefile.lammps`` file.
---------- ----------
@ -1523,24 +1562,26 @@ USER-SMD package
To build with this package, you must download the Eigen3 library. To build with this package, you must download the Eigen3 library.
Eigen3 is a template library, so you do not need to build it. Eigen3 is a template library, so you do not need to build it.
**CMake build**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes -D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes
-D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom location) -D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom location)
If DOWNLOAD_EIGEN3 is set, the Eigen3 library will be downloaded and If ``DOWNLOAD_EIGEN3`` is set, the Eigen3 library will be downloaded and
inside the CMake build directory. If the Eigen3 library is already on inside the CMake build directory. If the Eigen3 library is already on
your system (in a location CMake cannot find it), EIGEN3_INCLUDE_DIR your system (in a location CMake cannot find it), ``EIGEN3_INCLUDE_DIR``
is the directory the Eigen3++ include file is in. is the directory the Eigen3++ include file is in.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
You can download the Eigen3 library manually if you prefer; follow the You can download the Eigen3 library manually if you prefer; follow the
instructions in lib/smd/README. You can also do it in one step from instructions in ``lib/smd/README``. You can also do it in one step from
the lammps/src dir, using a command like these, which simply invoke the ``lammps/src`` dir, using a command like these, which simply invoke
the lib/smd/Install.py script with the specified args: the ``lib/smd/Install.py`` script with the specified args:
.. code-block:: bash .. code-block:: bash
@ -1548,9 +1589,9 @@ the lib/smd/Install.py script with the specified args:
$ make lib-smd args="-b" # download to lib/smd/eigen3 $ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3 $ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
Note that a symbolic (soft) link named "includelink" is created in Note that a symbolic (soft) link named ``includelink`` is created in
lib/smd to point to the Eigen dir. When LAMMPS builds it will use ``lib/smd`` to point to the Eigen dir. When LAMMPS builds it will use
this link. You should not need to edit the lib/smd/Makefile.lammps this link. You should not need to edit the ``lib/smd/Makefile.lammps``
file. file.
---------- ----------
@ -1563,21 +1604,23 @@ USER-VTK package
To build with this package you must have the VTK library installed on To build with this package you must have the VTK library installed on
your system. your system.
**CMake build**\ : CMake build
^^^^^^^^^^^
No additional settings are needed besides "-D PKG_USER-VTK=yes". No additional settings are needed besides ``-D PKG_USER-VTK=yes``.
This should auto-detect the VTK library if it is installed on your This should auto-detect the VTK library if it is installed on your
system at standard locations. Several advanced VTK options exist if system at standard locations. Several advanced VTK options exist if
you need to specify where it was installed. Use the ccmake (terminal you need to specify where it was installed. Use the ``ccmake`` (terminal
window) or cmake-gui (graphical) tools to see these options and set window) or ``cmake-gui`` (graphical) tools to see these options and set
them interactively from their user interfaces. them interactively from their user interfaces.
**Traditional make**\ : Traditional make
^^^^^^^^^^^^^^^^
The lib/vtk/Makefile.lammps file has settings for accessing VTK files The ``lib/vtk/Makefile.lammps`` file has settings for accessing VTK files
and its library, which LAMMPS needs to build with this package. If and its library, which LAMMPS needs to build with this package. If
the settings are not valid for your system, check if one of the other the settings are not valid for your system, check if one of the other
lib/vtk/Makefile.lammps.\* files is compatible and copy it to ``lib/vtk/Makefile.lammps.*`` files is compatible and copy it to
Makefile.lammps. If none of the provided files work, you will need to Makefile.lammps. If none of the provided files work, you will need to
edit the Makefile.lammps file. See lib/vtk/README for details. edit the ``Makefile.lammps`` file. See ``lib/vtk/README`` for details.

63
doc/src/Build_settings.rst
View File

@ -44,7 +44,8 @@ require use of an FFT library to compute 1d FFTs. The KISS FFT
library is included with LAMMPS but other libraries can be faster. library is included with LAMMPS but other libraries can be faster.
LAMMPS can use them if they are available on your system. LAMMPS can use them if they are available on your system.
**CMake variables**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -74,7 +75,12 @@ to assist:
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries -D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARIES=path -D MKL_LIBRARIES=path
**Makefile.machine settings**\ : Traditional make
^^^^^^^^^^^^^^^^
To change the FFT library to be used and its options, you have to edit
your machine Makefile. Below are examples how the makefile variables
could be changed.
.. code-block:: make .. code-block:: make
@ -104,7 +110,8 @@ As with CMake, you do not need to set paths in ``FFT_INC`` or ``FFT_PATH``, if
the compiler can find the FFT header and library files in its default search path. the compiler can find the FFT header and library files in its default search path.
You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link. You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link.
**CMake and make info**\ : CMake build
^^^^^^^^^^^
The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS The `KISS FFT library <http://kissfft.sf.net>`_ is included in the LAMMPS
distribution. It is portable across all platforms. Depending on the size distribution. It is portable across all platforms. Depending on the size
@ -127,7 +134,7 @@ download it from `www.fftw.org <http://www.fftw.org>`_. LAMMPS requires
version 3.X; the legacy version 2.1.X is no longer supported. version 3.X; the legacy version 2.1.X is no longer supported.
Building FFTW for your box should be as simple as ``./configure; make; Building FFTW for your box should be as simple as ``./configure; make;
make install``\ . The install command typically requires root privileges make install``. The install command typically requires root privileges
(e.g. invoke it via sudo), unless you specify a local directory with (e.g. invoke it via sudo), unless you specify a local directory with
the "--prefix" option of configure. Type ``./configure --help`` to see the "--prefix" option of configure. Type ``./configure --help`` to see
various options. various options.
@ -176,13 +183,18 @@ LAMMPS has a few integer data types which can be defined as either
4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time. 4-byte (= 32-bit) or 8-byte (= 64-bit) integers at compile time.
The default setting of "smallbig" is almost always adequate. The default setting of "smallbig" is almost always adequate.
**CMake variable**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
**Makefile.machine setting**\ : Traditional build
^^^^^^^^^^^^^^^^^
If you want a setting different from the default, you need to edit your
machine Makefile.
.. code-block:: make .. code-block:: make
@ -190,7 +202,8 @@ The default setting of "smallbig" is almost always adequate.
The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
**CMake and make info**\ : CMake and make info
^^^^^^^^^^^^^^^^^^^
The default "smallbig" setting allows for simulations with: The default "smallbig" setting allows for simulations with:
@ -251,7 +264,8 @@ PNG image files. Likewise the :doc:`dump movie <dump_image>` command
outputs movie files in MPEG format. Using these options requires the outputs movie files in MPEG format. Using these options requires the
following settings: following settings:
**CMake variables**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -276,7 +290,8 @@ variables:
-D ZLIB_LIBRARIES=path # path to libz.a (.so) file -D ZLIB_LIBRARIES=path # path to libz.a (.so) file
-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable -D FFMPEG_EXECUTABLE=path # path to ffmpeg executable
**Makefile.machine settings**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make
@ -295,7 +310,8 @@ with a list of graphics libraries to include in the link. You must
insure ffmpeg is in a directory where LAMMPS can find it at runtime, insure ffmpeg is in a directory where LAMMPS can find it at runtime,
that is a directory in your PATH environment variable. that is a directory in your PATH environment variable.
**CMake and make info**\ : CMake and make info
^^^^^^^^^^^^^^^^^^^
Using ``ffmpeg`` to output movie files requires that your machine Using ``ffmpeg`` to output movie files requires that your machine
supports the "popen" function in the standard runtime library. supports the "popen" function in the standard runtime library.
@ -318,7 +334,8 @@ If this option is enabled, large files can be read or written with
gzip compression by several LAMMPS commands, including gzip compression by several LAMMPS commands, including
:doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`. :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and :doc:`dump <dump>`.
**CMake variables**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -326,13 +343,15 @@ gzip compression by several LAMMPS commands, including
# default is yes if CMake can find gzip, else no # default is yes if CMake can find gzip, else no
-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it -D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it
**Makefile.machine setting**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make
LMP_INC = -DLAMMPS_GZIP LMP_INC = -DLAMMPS_GZIP
**CMake and make info**\ : CMake and make info
^^^^^^^^^^^^^^^^^^^
This option requires that your machine supports the "popen()" function This option requires that your machine supports the "popen()" function
in the standard runtime library and that a gzip executable can be in the standard runtime library and that a gzip executable can be
@ -363,7 +382,8 @@ pointers that are aligned to 16-byte boundaries. Using SSE vector
instructions efficiently, however, requires memory blocks being instructions efficiently, however, requires memory blocks being
aligned on 64-byte boundaries. aligned on 64-byte boundaries.
**CMake variable**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
@ -374,7 +394,8 @@ and revert to using the malloc() C-library function instead. When
compiling LAMMPS for Windows systems, malloc() will always be used compiling LAMMPS for Windows systems, malloc() will always be used
and this setting ignored. and this setting ignored.
**Makefile.machine setting**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make
@ -398,13 +419,15 @@ types, the following setting will be needed. It converts "long long"
to a "long" data type, which should be the desired 8-byte integer on to a "long" data type, which should be the desired 8-byte integer on
those systems: those systems:
**CMake variable**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) -D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default)
**Makefile.machine setting**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make
@ -423,13 +446,15 @@ Instead, the call stack is unwound and control returns to the caller,
e.g. to Python. Of course, the calling code has to be set up to e.g. to Python. Of course, the calling code has to be set up to
*catch* exceptions thrown from within LAMMPS. *catch* exceptions thrown from within LAMMPS.
**CMake variable**\ : CMake build
^^^^^^^^^^^
.. code-block:: bash .. code-block:: bash
-D LAMMPS_EXCEPTIONS=value # yes or no (default) -D LAMMPS_EXCEPTIONS=value # yes or no (default)
**Makefile.machine setting**\ : Traditional make
^^^^^^^^^^^^^^^^
.. code-block:: make .. code-block:: make