diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 7548a8a6e9..3b20209e5c 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -32,74 +32,80 @@ 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**\ : +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no - -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 + .. code-block:: bash -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 called ``lmp_name``. Using ``BUILD_MPI=no`` will -enforce building a serial executable using the MPI STUBS library. + -D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no + -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 -**Traditional make**\ : + 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 called + ``lmp_name``. Using ``BUILD_MPI=no`` will enforce building a + serial executable using the MPI STUBS library. -The build with traditional makefiles has to be done inside the source folder ``src``. + .. tab:: Traditional make -.. code-block:: bash + The build with traditional makefiles has to be done inside the source folder ``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 + .. code-block:: bash -Any ``make machine`` command will look up the make settings from a file -``Makefile.machine`` in the folder ``src/MAKE`` or one of its -sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, 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. + 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 -For the serial build the following make variables are set (see src/MAKE/Makefile.serial): + Any ``make machine`` command will look up the make settings from a + file ``Makefile.machine`` in the folder ``src/MAKE`` or one of its + sub-directories ``MINE``, ``MACHINES``, or ``OPTIONS``, 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. -.. code-block:: make + For the serial build the following make variables are set (see src/MAKE/Makefile.serial): - CC = g++ - LINK = g++ - MPI_INC = -I../STUBS - MPI_PATH = -L../STUBS - MPI_LIB = -lmpi_stubs + .. code-block:: make -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 may 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. + CC = g++ + LINK = g++ + MPI_INC = -I../STUBS + MPI_PATH = -L../STUBS + MPI_LIB = -lmpi_stubs -.. note:: + 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 may 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. - The file ``src/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. + .. note:: -**MPI and OpenMP support info**\ : + The file ``src/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. + +MPI and OpenMP support in LAMMPS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you are installing MPI yourself to build a parallel LAMMPS executable, we recommend either MPICH or OpenMPI which are regularly @@ -145,18 +151,19 @@ please refer to its documentation. .. _default-none-issues: -**OpenMP Compiler compatibility info**\ : +OpenMP Compiler compatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Some compilers do not fully support the ``default(none)`` directive -and others (e.g. GCC version 9 and beyond, Clang version 10 and later) -may implement strict OpenMP 4.0 and later semantics, which are incompatible +Some compilers do not fully support the ``default(none)`` directive and +others (e.g. GCC version 9 and beyond, Clang version 10 and later) may +implement strict OpenMP 4.0 and later semantics, which are incompatible with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility with compiler versions in use. If compilation with OpenMP enabled fails because of your compiler requiring strict OpenMP 4.0 semantic, you can -change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the ``LMP_INC`` -variable in your makefile, or add it to the command line while configuring -with CMake. CMake will detect the suitable setting for the GNU, Clang, -and Intel compilers. +change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the +``LMP_INC`` variable in your makefile, or add it to the command line +while configuring with CMake. CMake will detect the suitable setting for +the GNU, Clang, and Intel compilers. ---------- @@ -185,131 +192,139 @@ for their compile/link environments, you can often access different compilers by simply loading the appropriate module before building LAMMPS. -**CMake build**\ : +.. tabs:: -By default CMake will use a compiler it finds according to internal -preferences and it will add optimization flags appropriate to that -compiler and any :doc:`accelerator packages ` you have -included in the build. + .. tab:: CMake build -You can tell CMake to look for a specific compiler with setting CMake -variables (listed below) during configuration. For a few common -choices, there are also presets in the ``cmake/presets`` folder. For -convenience, there is a ``CMAKE_TUNE_FLAGS`` variable that can be set to -apply global compiler options (applied to compilation only), to be used -for adding compiler or host specific optimization flags in addition to -the "flags" variables listed below. You may also specify the -corresponding ``CMAKE_*_FLAGS`` variables individually, if you want to -experiment with alternate optimization flags. You should specify all 3 -compilers, so that the (few) LAMMPS source files written in C or Fortran -are built with a compiler consistent with the one used for the C++ -files: + By default CMake will use the compiler it finds according to + internal preferences and it will add optimization flags + appropriate to that compiler and any :doc:`accelerator packages + ` you have included in the build. CMake will + check if the detected or selected compiler is compatible with the + C++ support requirements of LAMMPS and stop with an error, if this + is not the case. -.. code-block:: bash + You can tell CMake to look for a specific compiler with setting + CMake variables (listed below) during configuration. For a few + common choices, there are also presets in the ``cmake/presets`` + folder. For convenience, there is a ``CMAKE_TUNE_FLAGS`` variable + that can be set to apply global compiler options (applied to + compilation only), to be used for adding compiler or host specific + optimization flags in addition to the "flags" variables listed + below. You may also specify the corresponding ``CMAKE_*_FLAGS`` + variables individually, if you want to experiment with alternate + optimization flags. You should specify all 3 compilers, so that + the (few) LAMMPS source files written in C or Fortran are built + with a compiler consistent with the one used for the C++ files: - -D CMAKE_CXX_COMPILER=name # name of C++ compiler - -D CMAKE_C_COMPILER=name # name of C compiler - -D CMAKE_Fortran_COMPILER=name # name of Fortran compiler + .. code-block:: bash - -D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler - -D CMAKE_C_FLAGS=string # flags to use with C compiler - -D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler + -D CMAKE_CXX_COMPILER=name # name of C++ compiler + -D CMAKE_C_COMPILER=name # name of C compiler + -D CMAKE_Fortran_COMPILER=name # name of Fortran compiler -A few example command lines are: + -D CMAKE_CXX_FLAGS=string # flags to use with C++ compiler + -D CMAKE_C_FLAGS=string # flags to use with C compiler + -D CMAKE_Fortran_FLAGS=string # flags to use with Fortran compiler -.. code-block:: bash + A few example command lines are: - # Building with GNU Compilers: - cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran - # Building with Intel Compilers: - cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort - # Building with LLVM/Clang Compilers: - cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang + .. code-block:: bash -For compiling with the Clang/LLVM compilers a CMake preset is provided that -can be loaded with `-C ../cmake/presets/clang.cmake`. Similarly, -`-C ../cmake/presets/intel.cmake` should switch the + # Building with GNU Compilers: + cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran + # Building with Intel Compilers: + cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort + # Building with LLVM/Clang Compilers: + cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang -In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add -compiler flags to tune for optimal performance on given hosts. By -default this variable is empty. + For compiling with the Clang/LLVM compilers a CMake preset is + provided that can be loaded with + `-C ../cmake/presets/clang.cmake`. Similarly, + `-C ../cmake/presets/intel.cmake` should switch the compiler + toolchain to the Intel compilers. -.. note:: + In addition you can set ``CMAKE_TUNE_FLAGS`` to specifically add + compiler flags to tune for optimal performance on given hosts. By + default this variable is empty. - When the cmake command completes, it prints a summary to the screen - which compilers it is using and what flags and settings will be used - for the compilation. Note that if the top-level compiler is mpicxx, - it is simply a wrapper on a real compiler. The underlying compiler - 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. + .. note:: -**Makefile.machine settings for traditional make**\ : + When the cmake command completes, it prints a summary to the + screen which compilers it is using and what flags and settings + will be used for the compilation. Note that if the top-level + compiler is mpicxx, it is simply a wrapper on a real compiler. + The underlying compiler 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. -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. + .. tab:: Makefile.machine settings for traditional make -Parallel build (see ``src/MAKE/Makefile.mpi``): + 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. -.. code-block:: bash + Parallel build (see ``src/MAKE/Makefile.mpi``): - CC = mpicxx - CCFLAGS = -g -O3 - LINK = mpicxx - LINKFLAGS = -g -O + .. code-block:: bash -Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``): + CC = mpicxx + CCFLAGS = -g -O3 + LINK = mpicxx + LINKFLAGS = -g -O -.. code-block:: make + Serial build with GNU gcc (see ``src/MAKE/Makefile.serial``): - CC = g++ - CCFLAGS = -g -O3 - LINK = g++ - LINKFLAGS = -g -O + .. code-block:: make + CC = g++ + CCFLAGS = -g -O3 + LINK = g++ + LINKFLAGS = -g -O -.. note:: + .. note:: - If compilation stops with a message like the following: + If compilation stops with a message like the following: - .. code-block:: + .. code-block:: - g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp - In file included from ../pointers.h:24:0, - from ../input.h:17, - from ../main.cpp:16: - ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler. + g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp + In file included from ../pointers.h:24:0, + from ../input.h:17, + from ../main.cpp:16: + ../lmptype.h:34:2: error: #error LAMMPS requires a C++11 (or later) compliant compiler. Enable C++11 compatibility or upgrade the compiler. - then you have either an unsupported (old) compiler or you have to - turn on C++11 mode. The latter applies to GCC 4.8.x shipped with - RHEL 7.x and CentOS 7.x. For those compilers, you need to add the - ``-std=c++11`` flag. Otherwise, you would have to install a newer - compiler that supports C++11; either as a binary package or through - compiling from source. + then you have either an unsupported (old) compiler or you have + to turn on C++11 mode. The latter applies to GCC 4.8.x shipped + with RHEL 7.x and CentOS 7.x. For those compilers, you need to + add the ``-std=c++11`` flag. Otherwise, you would have to + install a newer compiler that supports C++11; either as a + binary package or through compiling from source. -If you build LAMMPS with any :doc:`Speed_packages` included, there may -be specific compiler or linker 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` -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:`Speed_packages` included, + there may be specific compiler or linker 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` 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 + .. code-block:: bash - Makefile.opt # OPT package - Makefile.omp # USER-OMP package - Makefile.intel_cpu # USER-INTEL package for CPUs - Makefile.intel_coprocessor # USER-INTEL package for KNLs - Makefile.gpu # GPU package - Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs - Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP) - Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP) + Makefile.opt # OPT package + Makefile.omp # USER-OMP package + Makefile.intel_cpu # USER-INTEL package for CPUs + Makefile.intel_coprocessor # USER-INTEL package for KNLs + Makefile.gpu # GPU package + Makefile.kokkos_cuda_mpi # KOKKOS package for GPUs + Makefile.kokkos_omp # KOKKOS package for CPUs (OpenMP) + Makefile.kokkos_phi # KOKKOS package for KNLs (OpenMP) ---------- @@ -328,51 +343,56 @@ page for more info on coupling LAMMPS to other codes. See the :doc:`Python ` doc page for more info on wrapping and running LAMMPS from Python via its library interface. -**CMake build**\ : +.. tabs:: -For CMake builds, you can select through setting CMake variables between -building a shared or a static LAMMPS library and what kind of suffix is -added to them (in case you want to concurrently install multiple variants -of binaries with different settings). If none are set, defaults are applied. + .. tab:: CMake build -.. code-block:: bash + For CMake builds, you can select through setting CMake variables + between building a shared or a static LAMMPS library and what kind + of suffix is added to them (in case you want to concurrently + install multiple variants of binaries with different settings). If + none are set, defaults are applied. - -D BUILD_SHARED_LIBS=value # yes or no (default) - -D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc - # no default value + .. code-block:: bash -The compilation will always produce a LAMMPS library and an executable -linked to it. By default this will be a static library named -``liblammps.a`` and an executable named ``lmp`` Setting -``BUILD_SHARED_LIBS=yes`` will instead produce a shared library called -``liblammps.so`` (or ``liblammps.dylib`` or ``liblammps.dll`` depending -on the platform) If ``LAMMPS_MACHINE=name`` is set in addition, the name -of the generated libraries will be changed to either -``liblammps_name.a`` or ``liblammps_name.so``\ , respectively and the -executable will be called ``lmp_name``. + -D BUILD_SHARED_LIBS=value # yes or no (default) + -D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc + # no default value -**Traditional make**\ : + The compilation will always produce a LAMMPS library and an + executable linked to it. By default this will be a static library + named ``liblammps.a`` and an executable named ``lmp`` Setting + ``BUILD_SHARED_LIBS=yes`` will instead produce a shared library + called ``liblammps.so`` (or ``liblammps.dylib`` or + ``liblammps.dll`` depending on the platform) If + ``LAMMPS_MACHINE=name`` is set in addition, the name of the + generated libraries will be changed to either ``liblammps_name.a`` + or ``liblammps_name.so``\ , respectively and the executable will + be called ``lmp_name``. -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=static`` is the default. + .. tab:: Traditional make -.. code-block:: bash + 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=static`` is the default. - make machine # build LAMMPS executable lmp_machine - make mode=static machine # same as "make machine" - make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead + .. code-block:: bash -The "static" build will generate a static library called -``liblammps_machine.a`` and an executable named ``lmp_machine``\ , while -the "shared" build will generate a shared library -``liblammps_machine.so`` instead and ``lmp_machine`` will be linked to -it. The build step will also create generic soft links, named -``liblammps.a`` and ``liblammps.so``\ , which point to the specific -``liblammps_machine.a/so`` files. + make machine # build LAMMPS executable lmp_machine + make mode=static machine # same as "make machine" + make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead -CMake and make info -^^^^^^^^^^^^^^^^^^^ + The "static" build will generate a static library called + ``liblammps_machine.a`` and an executable named ``lmp_machine``\ , + while the "shared" build will generate a shared library + ``liblammps_machine.so`` instead and ``lmp_machine`` will be + linked to it. The build step will also create generic soft links, + named ``liblammps.a`` and ``liblammps.so``\ , which point to the + specific ``liblammps_machine.a/so`` files. + + +Additional information +^^^^^^^^^^^^^^^^^^^^^^ 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 @@ -462,8 +482,8 @@ tool. The actual translation is then done via make commands. .. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html .. _sphinx: https://www.sphinx-doc.org -Documentation make option -^^^^^^^^^^^^^^^^^^^^^^^^^ +Documentation makefile options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following make commands can be issued in the doc folder of the LAMMPS source distribution. @@ -490,15 +510,16 @@ your system. current LAMMPS version (HTML and PDF files), from the website `download page `_. -CMake build option -^^^^^^^^^^^^^^^^^^ +CMake build options +^^^^^^^^^^^^^^^^^^^ -It is also possible to create the HTML version of the manual within -the :doc:`CMake build directory `. The reason for this -option is to include the installation of the HTML manual pages into -the "install" step when installing LAMMPS after the CMake build via -``make install``. The documentation build is included in the default -build target, but can also be requested independently with ``make doc``. +It is also possible to create the HTML version (and only the HTML +version) of the manual within the :doc:`CMake build directory +`. The reason for this option is to include the +installation of the HTML manual pages into the "install" step when +installing LAMMPS after the CMake build via ``make install``. The +documentation build is included in the default build target, but can +also be requested independently with ``make doc``. .. code-block:: bash @@ -514,27 +535,27 @@ Build LAMMPS tools Some tools described in :doc:`Auxiliary tools ` can be built directly using CMake or Make. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D BUILD_TOOLS=value # yes or no (default) + .. code-block:: bash -The generated binaries will also become part of the LAMMPS installation -(see below). + -D BUILD_TOOLS=value # yes or no (default) -Traditional make -^^^^^^^^^^^^^^^^ + The generated binaries will also become part of the LAMMPS installation + (see below). -.. code-block:: bash + .. tab:: Traditional make - cd lammps/tools - make all # build all binaries of tools - make binary2txt # build only binary2txt tool - make chain # build only chain tool - make micelle2d # build only micelle2d tool - make thermo_extract # build only thermo_extract tool + .. code-block:: bash + + cd lammps/tools + make all # build all binaries of tools + make binary2txt # build only binary2txt tool + make chain # build only chain tool + make micelle2d # build only micelle2d tool + make thermo_extract # build only thermo_extract tool ---------- @@ -549,18 +570,19 @@ 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 build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake - make # perform make after CMake command - make install # perform the installation into prefix + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake + make # perform make after CMake command + make install # perform the installation into prefix -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 -copy the desired LAMMPS files to the appropriate system directories. + .. tab:: Traditional make + + 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 copy the desired LAMMPS files to the appropriate system + directories. diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index 55a41a4ba2..79e38ab2b4 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -2,17 +2,21 @@ Packages with extra build options ================================= When building with some packages, additional steps may be required, -in addition to: +in addition to -.. code-block:: bash +.. list-table:: + :align: center + :header-rows: 1 - $ cmake -D PKG_NAME=yes + * - CMake build + - Traditional make + * - .. code-block:: bash -or + $ cmake -D PKG_NAME=yes -.. code-block:: bash + - .. code-block:: bash - $ make yes-name + $ make yes-name as described on the :doc:`Build_package ` doc page. @@ -62,25 +66,39 @@ This is the list of packages that may require additional steps. COMPRESS package ---------------- -To build with this package you must have the zlib compression library -available on your system. +To build with this package you must have the `zlib compression library +`_ available on your system to build dump styles with +a '/gz' suffix. There are also styles using the +`Zstandard `_ library which have a +'/zstd' suffix. -CMake build -^^^^^^^^^^^ +.. tabs:: -If CMake cannot find the library, you can set these variables: + .. tab:: CMake build -.. code-block:: bash + If CMake cannot find the zlib library or include files, you can set + these variables: - -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file - -D ZLIB_LIBRARY=path # path to libz.a (.so) file + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file + -D ZLIB_LIBRARY=path # path to libz.a (.so) file -If make cannot find the library, you can edit the file -``lib/compress/Makefile.lammps`` to specify the paths and library -name. + Support for Zstandard compression is auto-detected and for that + CMake depends on the `pkg-config + `_ tool to + identify the necessary flags to compile with this library, so the + corresponding ``libzstandard.pc`` file must be in a folder where + pkg-config can find it, which may require adding it to the + ``PKG_CONFIG_PATH`` environment variable. + + .. tab:: Traditional make + + To include support for Zstandard compression, ``-DLAMMPS_ZSTD`` + must be added to the compiler flags. If make cannot find the + libraries, you can edit the file ``lib/compress/Makefile.lammps`` + to specify the paths and library names. This must be done + **before** the package is installed. ---------- @@ -121,17 +139,19 @@ CMake build * sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5) * sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5) -* sm_30 or sm_35 or sm_37 for Kepler (supported since CUDA 5) +* sm_30 for Kepler (supported since CUDA 5 and until CUDA 10.x) +* sm_35 or sm_37 for Kepler (supported since CUDA 5 and until CUDA 11.x) * sm_50 or sm_52 for Maxwell (supported since CUDA 6) * sm_60 or sm_61 for Pascal (supported since CUDA 8) * sm_70 for Volta (supported since CUDA 9) * sm_75 for Turing (supported since CUDA 10) +* sm_80 for Ampere (supported since CUDA 11) A more detailed list can be found, for example, at `Wikipedia's CUDA article `_ -CMake can detect which version of the CUDA toolkit is used and thus can -include support for **all** major GPU architectures supported by this toolkit. +CMake can detect which version of the CUDA toolkit is used and thus will try +to include support for **all** major GPU architectures supported by this toolkit. Thus the GPU_ARCH setting is merely an optimization, to have code for the preferred GPU architecture directly included rather than having to wait for the JIT compiler of the CUDA driver to translate it. @@ -155,7 +175,7 @@ and the linker to work correctly. .. code:: bash - # CUDA target + # CUDA target (not recommended, use GPU_ARCH=cuda) # !!! DO NOT set CMAKE_CXX_COMPILER !!! export HIP_PLATFORM=nvcc export CUDA_PATH=/usr/local/cuda @@ -253,64 +273,70 @@ 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 minutes to hours) to build. Of course you only need to do that once.) -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value = no (default) or yes - -D LMP_DEBUG_CURL=value # set libcurl verbose mode on/off, value = off (default) or on - -D LMP_NO_SSL_CHECK=value # tell libcurl to not verify the peer, value = no (default) or yes + .. code-block:: bash -If ``DOWNLOAD_KIM`` is set, the KIM library will be downloaded and built -inside the CMake build directory. If the KIM library is already on -your system (in a location CMake cannot find it), set the ``PKG_CONFIG_PATH`` -environment variable so that libkim-api can be found. + -D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value = no (default) or yes + -D LMP_DEBUG_CURL=value # set libcurl verbose mode on/off, value = off (default) or on + -D LMP_NO_SSL_CHECK=value # tell libcurl to not verify the peer, value = no (default) or yes -*For using OpenKIM web queries in LAMMPS*\ : + If ``DOWNLOAD_KIM`` is set to *yes* (or *on*), the KIM API library + will be downloaded and built inside the CMake build directory. If + the KIM library is already installed on your system (in a location + where CMake cannot find it), you may need to set the + ``PKG_CONFIG_PATH`` environment variable so that libkim-api can be + found, or run the command ``source kim-api-activate``. -If the ``LMP_DEBUG_CURL`` environment variable is set, the libcurl verbose -mode will be on, and any libcurl calls within the KIM web query display a -lot of information about libcurl operations. You hardly ever want this -set in production use, you will almost always want this when you debug or + .. tab:: Traditional make + + You can download and build the KIM library manually if you prefer; + follow the instructions in ``lib/kim/README``. You can also do + this in one step from the lammps/src dir, using a command like + these, which simply invoke the ``lib/kim/Install.py`` script with + the specified args. + + .. code-block:: bash + + $ make lib-kim # print help message + $ make lib-kim args="-b " # (re-)install KIM API lib with only example models + $ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model + $ make lib-kim args="-b -a everything" # install KIM API lib with all models + $ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver + $ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location + $ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver + + Settings for debugging OpenKIM web queries discussed below need to + be applied by adding them to the ``LMP_INC`` variable through + editing the ``Makefile.machine`` you are using. For example: + + .. code-block:: make + + LMP_INC = -DLMP_NO_SSL_CHECK + +Debugging OpenKIM web queries in LAMMPS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If ``LMP_DEBUG_CURL`` is set, the libcurl verbose mode will be turned +on, and any libcurl calls within the KIM web query display a lot of +information about libcurl operations. You hardly ever want this set in +production use, you will almost always want this when you debug or report problems. -The libcurl performs peer SSL certificate verification by default. This -verification is done using a CA certificate store that the SSL library can -use to make sure the peer's server certificate is valid. If SSL reports an -error ("certificate verify failed") during the handshake and thus refuses -further communication with that server, you can set ``LMP_NO_SSL_CHECK``\ . -If ``LMP_NO_SSL_CHECK`` is set, libcurl does not verify the peer and connection -succeeds regardless of the names in the certificate. This option is insecure. -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 -to the KIM web query would get this value from the environmental variable. - -Traditional make -^^^^^^^^^^^^^^^^ - -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 -step from the lammps/src dir, using a command like these, which simply -invoke the ``lib/kim/Install.py`` script with the specified args. - -.. code-block:: bash - - $ make lib-kim # print help message - $ make lib-kim args="-b " # (re-)install KIM API lib with only example models - $ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model - $ make lib-kim args="-b -a everything" # install KIM API lib with all models - $ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver - $ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location - $ 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 -them to the ``LMP_INC`` variable through editing the ``Makefile.machine`` you are -using. For example: - -.. code-block:: make - - LMP_INC = -DLMP_NO_SSL_CHECK +The libcurl library performs peer SSL certificate verification by +default. This verification is done using a CA certificate store that +the SSL library can use to make sure the peer's server certificate is +valid. If SSL reports an error ("certificate verify failed") during the +handshake and thus refuses further communicate with that server, you can +set ``LMP_NO_SSL_CHECK`` to override that behavior. When LAMMPS is +compiled with ``LMP_NO_SSL_CHECK`` set, libcurl does not verify the peer +and connection attempts will succeed regardless of the names in the +certificate. This option is insecure. 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 to the KIM web +query would get this value from the environment variable. ---------- @@ -347,8 +373,8 @@ More information on Kokkos can be found on the Available Architecture settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -These are the possible choices for the Kokkos architecture ID. They must -be specified in uppercase. +These are the possible choices for the Kokkos architecture ID as of +version 3.2 of the Kokkos library. They must be specified in uppercase. .. list-table:: :header-rows: 0 @@ -460,111 +486,115 @@ be specified in uppercase. - GPU - Intel GPUs Gen9+ -Basic CMake build settings: -^^^^^^^^^^^^^^^^^^^^^^^^^^^ -For multicore CPUs using OpenMP, set these 2 variables. +.. tabs:: -.. code-block:: bash + .. tab:: Basic CMake build settings: - -D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above - -D Kokkos_ENABLE_OPENMP=yes - -D BUILD_OMP=yes + For multicore CPUs using OpenMP, set these 2 variables. -Please note that enabling OpenMP for KOKKOS requires that OpenMP is -also :ref:`enabled for the rest of LAMMPS `. + .. code-block:: bash -For Intel KNLs using OpenMP, set these variables: + -D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above + -D Kokkos_ENABLE_OPENMP=yes + -D BUILD_OMP=yes -.. code-block:: bash + Please note that enabling OpenMP for KOKKOS requires that OpenMP is + also :ref:`enabled for the rest of LAMMPS `. - -D Kokkos_ARCH_KNL=yes - -D Kokkos_ENABLE_OPENMP=yes + For Intel KNLs using OpenMP, set these variables: -For NVIDIA GPUs using CUDA, set these variables: + .. code-block:: bash -.. code-block:: bash + -D Kokkos_ARCH_KNL=yes + -D Kokkos_ENABLE_OPENMP=yes - -D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above - -D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above - -D Kokkos_ENABLE_CUDA=yes - -D Kokkos_ENABLE_OPENMP=yes - -D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper + For NVIDIA GPUs using CUDA, set these variables: -This will also enable executing FFTs on the GPU, either via the internal -KISSFFT library, or - by preference - with the cuFFT library bundled -with the CUDA toolkit, depending on whether CMake can identify its -location. The *wrapper* value for ``CMAKE_CXX_COMPILER`` variable is -the path to the CUDA nvcc compiler wrapper provided in the Kokkos -library: ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include -the full path name to the wrapper, e.g. + .. code-block:: bash -.. code-block:: bash + -D Kokkos_ARCH_HOSTARCH=yes # HOSTARCH = HOST from list above + -D Kokkos_ARCH_GPUARCH=yes # GPUARCH = GPU from list above + -D Kokkos_ENABLE_CUDA=yes + -D Kokkos_ENABLE_OPENMP=yes + -D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper - -D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper + This will also enable executing FFTs on the GPU, either via the + internal KISSFFT library, or - by preference - with the cuFFT + library bundled with the CUDA toolkit, depending on whether CMake + can identify its location. The *wrapper* value for + ``CMAKE_CXX_COMPILER`` variable is the path to the CUDA nvcc + compiler wrapper provided in the Kokkos library: + ``lib/kokkos/bin/nvcc_wrapper``\ . The setting should include the + full path name to the wrapper, e.g. -To simplify the compilation, three preset files are included in the -``cmake/presets`` folder, ``kokkos-serial.cmake``, ``kokkos-openmp.cmake``, -and ``kokkos-cuda.cmake``. They will enable the KOKKOS package and -enable some hardware choice. So to compile with OpenMP host parallelization, -CUDA device parallelization (for GPUs with CC 5.0 and up) with some -common packages enabled, you can do the following: + .. code-block:: bash -.. code-block:: bash + -D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper - mkdir build-kokkos-cuda - cd build-kokkos-cuda - cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake - cmake --build . + To simplify compilation, three preset files are included in the + ``cmake/presets`` folder, ``kokkos-serial.cmake``, + ``kokkos-openmp.cmake``, and ``kokkos-cuda.cmake``. They will + enable the KOKKOS package and enable some hardware choice. So to + compile with OpenMP host parallelization, CUDA device + parallelization (for GPUs with CC 5.0 and up) with some common + packages enabled, you can do the following: -Basic traditional make settings: -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: bash -Choose which hardware to support in ``Makefile.machine`` via -``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the -``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples. + mkdir build-kokkos-cuda + cd build-kokkos-cuda + cmake -C ../cmake/presets/minimal.cmake -C ../cmake/presets/kokkos-cuda.cmake ../cmake + cmake --build . -For multicore CPUs using OpenMP: + .. tab:: Basic traditional make settings: -.. code-block:: make + Choose which hardware to support in ``Makefile.machine`` via + ``KOKKOS_DEVICES`` and ``KOKKOS_ARCH`` settings. See the + ``src/MAKE/OPTIONS/Makefile.kokkos*`` files for examples. - KOKKOS_DEVICES = OpenMP - KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above + For multicore CPUs using OpenMP: -For Intel KNLs using OpenMP: + .. code-block:: make -.. code-block:: make + KOKKOS_DEVICES = OpenMP + KOKKOS_ARCH = HOSTARCH # HOSTARCH = HOST from list above - KOKKOS_DEVICES = OpenMP - KOKKOS_ARCH = KNL + For Intel KNLs using OpenMP: -For NVIDIA GPUs using CUDA: + .. code-block:: make -.. code-block:: make + KOKKOS_DEVICES = OpenMP + KOKKOS_ARCH = KNL - KOKKOS_DEVICES = Cuda - KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is hosting the GPU - KOKKOS_CUDA_OPTIONS = "enable_lambda" - # GPUARCH = GPU from list above - FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional) - FFT_LIB = -lcufft # link to cuFFT library + For NVIDIA GPUs using CUDA: -For GPUs, you also need the following lines in your ``Makefile.machine`` -before the CC line is defined. They tell ``mpicxx`` to use an ``nvcc`` -compiler wrapper, which will use ``nvcc`` for compiling CUDA files and a -C++ compiler for non-Kokkos, non-CUDA files. + .. code-block:: make -.. code-block:: make + KOKKOS_DEVICES = Cuda + KOKKOS_ARCH = HOSTARCH,GPUARCH # HOSTARCH = HOST from list above that is hosting the GPU + KOKKOS_CUDA_OPTIONS = "enable_lambda" + # GPUARCH = GPU from list above + FFT_INC = -DFFT_CUFFT # enable use of cuFFT (optional) + FFT_LIB = -lcufft # link to cuFFT library - # For OpenMPI - KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) - export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper - CC = mpicxx + For GPUs, you also need the following lines in your + ``Makefile.machine`` before the CC line is defined. They tell + ``mpicxx`` to use an ``nvcc`` compiler wrapper, which will use + ``nvcc`` for compiling CUDA files and a C++ compiler for + non-Kokkos, non-CUDA files. -.. code-block:: make + .. code-block:: make - # For MPICH and derivatives - KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) - CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper + # For OpenMPI + KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) + export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper + CC = mpicxx + + .. code-block:: make + + # For MPICH and derivatives + KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) + CC = mpicxx -cxx=$(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper Advanced KOKKOS compilation settings @@ -619,43 +649,43 @@ LATTE package To build with this package, you must download and build the LATTE library. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or yes - -D LATTE_LIBRARY=path # LATTE library file (only needed if a custom location) + .. code-block:: bash -If ``DOWNLOAD_LATTE`` is set, the LATTE library will be downloaded and -built inside the CMake build directory. If the LATTE library is -already on your system (in a location CMake cannot find it), -``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library file, -not the directory the library file is in. + -D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or yes + -D LATTE_LIBRARY=path # LATTE library file (only needed if a custom location) -Traditional make -^^^^^^^^^^^^^^^^ + If ``DOWNLOAD_LATTE`` is set, the LATTE library will be downloaded + and built inside the CMake build directory. If the LATTE library + is already on your system (in a location CMake cannot find it), + ``LATTE_LIBRARY`` is the filename (plus path) of the LATTE library + file, not the directory the library file is in. -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 -one step from the ``lammps/src`` dir, using a command like these, which -simply invokes the ``lib/latte/Install.py`` script with the specified -args: + .. tab:: Traditional make -.. code-block:: bash + 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 one step from the ``lammps/src`` dir, using a + command like these, which simply invokes the + ``lib/latte/Install.py`` script with the specified args: - $ make lib-latte # print help message - $ make lib-latte args="-b" # download and build in lib/latte/LATTE-master - $ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte - $ make lib-latte args="-b -m gfortran" # download and build in lib/latte and - # copy Makefile.lammps.gfortran to Makefile.lammps + .. code-block:: bash -Note that 3 symbolic (soft) links, ``includelink`` and ``liblink`` and -``filelink.o``, are created in ``lib/latte`` to point to required -folders and files in the LATTE home directory. When LAMMPS itself is -built it will use these links. You should also check that the -``Makefile.lammps`` file you create is appropriate for the compiler you -use on your system to build LATTE. + $ make lib-latte # print help message + $ make lib-latte args="-b" # download and build in lib/latte/LATTE-master + $ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte + $ make lib-latte args="-b -m gfortran" # download and build in lib/latte and + # copy Makefile.lammps.gfortran to Makefile.lammps + + Note that 3 symbolic (soft) links, ``includelink`` and ``liblink`` + and ``filelink.o``, are created in ``lib/latte`` to point to + required folders and files in the LATTE home directory. When + LAMMPS itself is built it will use these links. You should also + check that the ``Makefile.lammps`` file you create is appropriate + for the compiler you use on your system to build LATTE. ---------- @@ -668,34 +698,35 @@ This package can optionally include support for messaging via sockets, using the open-source `ZeroMQ library `_, which must be installed on your system. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D MESSAGE_ZMQ=value # build with ZeroMQ support, value = no (default) or yes - -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) + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D MESSAGE_ZMQ=value # build with ZeroMQ support, value = no (default) or yes + -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) -Before building LAMMPS, you must build the CSlib library in -``lib/message``\ . You can build the CSlib library manually if you prefer; -follow the instructions in ``lib/message/README``\ . You can also do it in -one step from the ``lammps/src`` dir, using a command like these, which -simply invoke the ``lib/message/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the CSlib library in + ``lib/message``\ . You can build the CSlib library manually if + you prefer; follow the instructions in ``lib/message/README``\ . + You can also do it in one step from the ``lammps/src`` dir, using + a command like these, which simply invoke the + ``lib/message/Install.py`` script with the specified args: - $ make lib-message # print help message - $ make lib-message args="-m -z" # build with MPI and socket (ZMQ) support - $ make lib-message args="-s" # build as serial lib with no ZMQ support + .. code-block:: bash -The build should produce two files: ``lib/message/cslib/src/libmessage.a`` -and ``lib/message/Makefile.lammps``. The latter is copied from an -existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ -library if requested in the build. + $ make lib-message # print help message + $ make lib-message args="-m -z" # build with MPI and socket (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`` + and ``lib/message/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ + library if requested in the build. ---------- @@ -710,43 +741,45 @@ library. Building the MS-CG library requires that the GSL machine. See the ``lib/mscg/README`` and ``MSCG/Install`` files for more details. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D DOWNLOAD_MSCG=value # download MSCG for build, value = no (default) or yes - -D MSCG_LIBRARY=path # MSCG library file (only needed if a custom location) - -D MSCG_INCLUDE_DIR=path # MSCG include directory (only needed if a custom location) + .. code-block:: bash -If ``DOWNLOAD_MSCG`` is set, the MSCG library will be downloaded and built -inside the CMake build directory. If the MSCG library is already on -your system (in a location CMake cannot find it), ``MSCG_LIBRARY`` is the -filename (plus path) of the MSCG library file, not the directory the -library file is in. ``MSCG_INCLUDE_DIR`` is the directory the MSCG -include file is in. + -D DOWNLOAD_MSCG=value # download MSCG for build, value = no (default) or yes + -D MSCG_LIBRARY=path # MSCG library file (only needed if a custom location) + -D MSCG_INCLUDE_DIR=path # MSCG include directory (only needed if a custom location) -Traditional make -^^^^^^^^^^^^^^^^ + If ``DOWNLOAD_MSCG`` is set, the MSCG library will be downloaded + and built inside the CMake build directory. If the MSCG library + is already on your system (in a location CMake cannot find it), + ``MSCG_LIBRARY`` is the filename (plus path) of the MSCG library + file, not the directory the library file is in. + ``MSCG_INCLUDE_DIR`` is the directory the MSCG include file is in. -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 -step from the ``lammps/src`` dir, using a command like these, which simply -invoke the ``lib/mscg/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + 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 step from the ``lammps/src`` dir, using a + command like these, which simply invoke the + ``lib/mscg/Install.py`` script with the specified args: - $ make lib-mscg # print help message - $ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master - # with the settings compatible with "make serial" - $ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master - # with the settings compatible with "make mpi" - $ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release + .. code-block:: bash -Note that 2 symbolic (soft) links, "includelink" and "liblink", will -be created in ``lib/mscg`` to point to the MS-CG ``src/installation`` -dir. When LAMMPS is built in src it will use these links. You should -not need to edit the ``lib/mscg/Makefile.lammps`` file. + $ make lib-mscg # print help message + $ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make serial" + $ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make mpi" + $ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release + + Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, + will be created in ``lib/mscg`` to point to the MS-CG + ``src/installation`` dir. When LAMMPS is built in src it will use + these links. You should not need to edit the + ``lib/mscg/Makefile.lammps`` file. ---------- @@ -755,18 +788,18 @@ not need to edit the ``lib/mscg/Makefile.lammps`` file. OPT package --------------------- -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_OPT=yes`` + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + No additional settings are needed besides ``-D PKG_OPT=yes`` -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 -line of your ``Makefile.machine``. See -``src/MAKE/OPTIONS/Makefile.opt`` for an example. + .. tab:: Traditional make + + The compiler flag ``-restrict`` must be used to build LAMMPS with + the OPT package when using Intel compilers. It should be added to + the :code:`CCFLAGS` line of your ``Makefile.machine``. See + ``src/MAKE/OPTIONS/Makefile.opt`` for an example. ---------- @@ -775,34 +808,36 @@ line of your ``Makefile.machine``. See POEMS package ------------------------- -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_OPT=yes`` + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + No additional settings are needed besides ``-D PKG_OPT=yes`` -Before building LAMMPS, you must build the POEMS library in ``lib/poems``\ . -You can do this manually if you prefer; follow the instructions in -``lib/poems/README``\ . You can also do it in one step from the ``lammps/src`` -dir, using a command like these, which simply invoke the -``lib/poems/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the POEMS library in + ``lib/poems``\ . You can do this manually if you prefer; follow + the instructions in ``lib/poems/README``\ . You can also do it in + one step from the ``lammps/src`` dir, using a command like these, + which simply invoke the ``lib/poems/Install.py`` script with the + specified args: - $ make lib-poems # print help message - $ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial") - $ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi") - $ make lib-poems args="-m icc" # build with Intel icc compiler + .. code-block:: bash -The build should produce two files: ``lib/poems/libpoems.a`` and -``lib/poems/Makefile.lammps``. The latter is copied from an existing -``Makefile.lammps.*`` and has settings needed to build LAMMPS with the -POEMS library (though typically the settings are just blank). If -necessary, you can edit/create a new ``lib/poems/Makefile.machine`` file -for your system, which should define an ``EXTRAMAKE`` variable to specify -a corresponding ``Makefile.lammps.machine`` file. + $ make lib-poems # print help message + $ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial") + $ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi") + $ make lib-poems args="-m icc" # build with Intel icc compiler + + The build should produce two files: ``lib/poems/libpoems.a`` and + ``lib/poems/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings needed to build + LAMMPS with the POEMS library (though typically the settings are + just blank). If necessary, you can edit/create a new + ``lib/poems/Makefile.machine`` file for your system, which should + define an ``EXTRAMAKE`` variable to specify a corresponding + ``Makefile.lammps.machine`` file. ---------- @@ -817,27 +852,28 @@ version or a Python 3.x version. Since support for Python 2.x has ended, using Python 3.x is strongly recommended. See ``lib/python/README`` for additional details. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D PYTHON_EXECUTABLE=path # path to Python executable to use + .. code-block:: bash -Without this setting, CMake will guess the default Python on your -system. To use a different Python version, you can either create a -virtualenv, activate it and then run cmake. Or you can set the -PYTHON_EXECUTABLE variable to specify which Python interpreter should -be used. Note note that you will also need to have the development -headers installed for this version, e.g. python2-devel. + -D PYTHON_EXECUTABLE=path # path to Python executable to use -Traditional make -^^^^^^^^^^^^^^^^ + Without this setting, CMake will guess the default Python version + on your system. To use a different Python version, you can either + create a virtualenv, activate it and then run cmake. Or you can + set the PYTHON_EXECUTABLE variable to specify which Python + interpreter should be used. Note note that you will also need to + have the development headers installed for this version, + e.g. python2-devel. -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 -``Makefile.lammps.*`` file (and copy it to ``Makefile.lammps``) if -the LAMMPS build fails. + .. tab:: Traditional make + + 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 ``Makefile.lammps.*`` file (and copy it to + ``Makefile.lammps``) if the LAMMPS build fails. ---------- @@ -846,46 +882,48 @@ the LAMMPS build fails. VORONOI package ----------------------------- -To build with this package, you must download and build the `Voro++ library `_. +To build with this package, you must download and build the +`Voro++ library `_ or install a +binary package provided by your operating system. -.. _voro-home: http://math.lbl.gov/voro++ +.. tabs:: -CMake build -^^^^^^^^^^^ + .. tab:: CMake build -.. code-block:: bash + .. code-block:: bash - -D DOWNLOAD_VORO=value # download Voro++ for build, value = no (default) or yes - -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 DOWNLOAD_VORO=value # download Voro++ for build, value = no (default) or yes + -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) -If ``DOWNLOAD_VORO`` is set, the Voro++ library will be downloaded and -built inside the CMake build directory. If the Voro++ library is -already on your system (in a location CMake cannot find it), -``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 -directory the Voro++ include file is in. + If ``DOWNLOAD_VORO`` is set, the Voro++ library will be downloaded + and built inside the CMake build directory. If the Voro++ library + is already on your system (in a location CMake cannot find it), + ``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 directory the Voro++ include file is + in. -Traditional make -^^^^^^^^^^^^^^^^ + .. tab:: Traditional make -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 -one step from the ``lammps/src`` dir, using a command like these, which -simply invoke the ``lib/voronoi/Install.py`` script with the specified -args: + 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 one step from the ``lammps/src`` dir, using a + command like these, which simply invoke the + ``lib/voronoi/Install.py`` script with the specified args: -.. code-block:: bash + .. code-block:: bash - $ make lib-voronoi # print help message - $ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/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 # print help message + $ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/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 -Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are -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 -the ``lib/voronoi/Makefile.lammps`` file. + Note that 2 symbolic (soft) links, ``includelink`` and + ``liblink``, are 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 the + ``lib/voronoi/Makefile.lammps`` file. ---------- @@ -903,29 +941,30 @@ environment variables have been updated for the local ADIOS installation and the instructions below are followed for the respective build systems. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D ADIOS2_DIR=path # path is where ADIOS 2.x is installed - -D PKG_USER-ADIOS=yes + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D ADIOS2_DIR=path # path is where ADIOS 2.x is installed + -D PKG_USER-ADIOS=yes -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: + .. tab:: Traditional make -.. code-block:: bash + 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: - $ make yes-user-adios + .. code-block:: bash -otherwise, set ADIOS2_DIR environment variable when turning on the package: + $ make yes-user-adios -.. code-block:: bash + otherwise, set ADIOS2_DIR environment variable when turning on the package: - $ ADIOS2_DIR=path make yes-user-adios # path is where ADIOS 2.x is installed + .. code-block:: bash + + $ ADIOS2_DIR=path make yes-user-adios # path is where ADIOS 2.x is installed ---------- @@ -936,48 +975,50 @@ USER-ATC package The USER-ATC package requires the MANYBODY package also be installed. -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides "-D PKG_USER-ATC=yes" -and "-D PKG_MANYBODY=yes". + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + No additional settings are needed besides ``-D PKG_USER-ATC=yes`` + and ``-D PKG_MANYBODY=yes``. -Before building LAMMPS, you must build the ATC library in ``lib/atc``. -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`` dir, using a command like these, which simply invoke the -``lib/atc/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the ATC library in + ``lib/atc``. 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`` dir, using a command like these, + which simply invoke the ``lib/atc/Install.py`` script with the + specified args: - $ make lib-atc # print help message - $ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") - $ 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 + .. code-block:: bash -The build should produce two files: ``lib/atc/libatc.a`` and -``lib/atc/Makefile.lammps``. The latter is copied from an existing -``Makefile.lammps.*`` and has settings needed to build LAMMPS with the -ATC library. If necessary, you can edit/create a new -``lib/atc/Makefile.machine`` file for your system, which should define -an ``EXTRAMAKE`` variable to specify a corresponding -``Makefile.lammps.`` file. + $ make lib-atc # print help message + $ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") + $ 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 -Note that the Makefile.lammps file has settings for the BLAS and -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 -``lib/linalg``. In the latter case you also need to build the library in -``lib/linalg`` with a command like these: + The build should produce two files: ``lib/atc/libatc.a`` and + ``lib/atc/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings needed to build + LAMMPS with the ATC library. If necessary, you can edit/create a + new ``lib/atc/Makefile.machine`` file for your system, which + should define an ``EXTRAMAKE`` variable to specify a corresponding + ``Makefile.lammps.`` file. -.. code-block:: bash + Note that the Makefile.lammps file has settings for the BLAS and + 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 ``lib/linalg``. In the latter case + you also need to build the library in ``lib/linalg`` with a + command like these: - $ make lib-linalg # print help message - $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") - $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") - $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler + .. code-block:: bash + + $ make lib-linalg # print help message + $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") + $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") + $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler ---------- @@ -986,47 +1027,49 @@ can either exist on your system, or you can use the files provided in USER-AWPMD package ------------------ -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_USER-AQPMD=yes``. + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + No additional settings are needed besides ``-D PKG_USER-AQPMD=yes``. -Before building LAMMPS, you must build the AWPMD library in ``lib/awpmd``. -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`` -dir, using a command like these, which simply invoke the -``lib/awpmd/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the AWPMD library in + ``lib/awpmd``. 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`` dir, using a command like these, + which simply invoke the ``lib/awpmd/Install.py`` script with the + specified args: - $ make lib-awpmd # print help message - $ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") - $ 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 + .. code-block:: bash -The build should produce two files: ``lib/awpmd/libawpmd.a`` and -``lib/awpmd/Makefile.lammps``. The latter is copied from an existing -``Makefile.lammps.*`` and has settings needed to build LAMMPS with the -AWPMD library. If necessary, you can edit/create a new -``lib/awpmd/Makefile.machine`` file for your system, which should define -an ``EXTRAMAKE`` variable to specify a corresponding -``Makefile.lammps.`` file. + $ make lib-awpmd # print help message + $ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") + $ 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 -Note that the ``Makefile.lammps`` file has settings for the BLAS and -LAPACK linear algebra libraries. As explained in ``lib/awpmd/README`` -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 -library in ``lib/linalg`` with a command like these: + The build should produce two files: ``lib/awpmd/libawpmd.a`` and + ``lib/awpmd/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings needed to build + LAMMPS with the AWPMD library. If necessary, you can edit/create + a new ``lib/awpmd/Makefile.machine`` file for your system, which + should define an ``EXTRAMAKE`` variable to specify a corresponding + ``Makefile.lammps.`` file. -.. code-block:: bash + Note that the ``Makefile.lammps`` file has settings for the BLAS + and LAPACK linear algebra libraries. As explained in + ``lib/awpmd/README`` 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 library in ``lib/linalg`` with a + command like these: - $ make lib-linalg # print help message - $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") - $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") - $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler + .. code-block:: bash + + $ make lib-linalg # print help message + $ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") + $ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") + $ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler ---------- @@ -1035,54 +1078,57 @@ library in ``lib/linalg`` with a command like these: USER-COLVARS package --------------------------------------- -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. +This package includes the `Colvars library +`_ into the LAMMPS distribution, which can +be built for the most part with all major versions of the C++ language. -CMake build -^^^^^^^^^^^ +.. tabs:: -This is the recommended build recipe: no additional settings are normally -needed besides ``-D PKG_USER-COLVARS=yes``. + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + This is the recommended build procedure for using Colvars in + LAMMPS. No additional settings are normally needed besides + ``-D PKG_USER-COLVARS=yes``. -Before building LAMMPS, one must build the Colvars library in lib/colvars. + .. tab:: Traditional make -This can be done manually in the same folder by using or adapting one of -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). + Before building LAMMPS, one must build the Colvars library in lib/colvars. -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 -command like these, which simply invoke the ``lib/colvars/Install.py`` script with -the specified args: + This can be done manually in the same folder by using or adapting + one of 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). -.. code-block:: bash + 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 command like these, which simply invoke the + ``lib/colvars/Install.py`` script with the specified args: - $ make lib-colvars # print help message - $ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial") - $ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi") - $ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled + .. code-block:: bash -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 -auto-generated by using compiler flags consistent with those parsed from the -core LAMMPS makefiles. + $ make lib-colvars # print help message + $ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial") + $ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi") + $ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled -Optional flags may be specified as environment variables: + 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 auto-generated by using + compiler flags consistent with those parsed from the core LAMMPS + makefiles. -.. code-block:: bash + Optional flags may be specified as environment variables: - $ 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) + .. code-block:: bash -The build should produce two files: the library ``lib/colvars/libcolvars.a`` -(which also includes Lepton objects if enabled) and the specification file -``lib/colvars/Makefile.lammps``. The latter is auto-generated, and normally does -not need to be edited. + $ 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) + + The build should produce two files: the library ``lib/colvars/libcolvars.a`` + (which also includes Lepton objects if enabled) and the specification file + ``lib/colvars/Makefile.lammps``. The latter is auto-generated, and normally does + not need to be edited. ---------- @@ -1128,84 +1174,91 @@ try a different one, switch to a different build system, consider a global PLUMED installation or consider downloading PLUMED during the LAMMPS build. -CMake build -^^^^^^^^^^^ +.. tabs:: -When the ``-D PKG_USER-PLUMED=yes`` flag is included in the cmake -command you must ensure that GSL is installed in locations that are -specified in your environment. There are then two additional variables -that control the manner in which PLUMED is obtained and linked into -LAMMPS. + .. tab:: CMake build -.. code-block:: bash + When the ``-D PKG_USER-PLUMED=yes`` flag is included in the cmake + command you must ensure that GSL is installed in locations that + are specified in your environment. There are then two additional + variables that control the manner in which PLUMED is obtained and + linked into LAMMPS. - -D DOWNLOAD_PLUMED=value # download PLUMED for build, value = no (default) or yes - -D PLUMED_MODE=value # Linkage mode for PLUMED, value = static (default), shared, or runtime + .. code-block:: bash -If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be -downloaded (the version of PLUMED that will be downloaded is hard-coded -to a vetted version of PLUMED, usually a recent stable release version) -and built inside the CMake build directory. If ``DOWNLOAD_PLUMED`` is -set to "no" (the default), CMake will try to detect and link to an -installed version of PLUMED. For this to work, the PLUMED library has -to be installed into a location where the ``pkg-config`` tool can find -it or the PKG_CONFIG_PATH environment variable has to be set up -accordingly. PLUMED should be installed in such a location if you -compile it using the default make; make install commands. + -D DOWNLOAD_PLUMED=value # download PLUMED for build, value = no (default) or yes + -D PLUMED_MODE=value # Linkage mode for PLUMED, value = static (default), shared, or runtime -The ``PLUMED_MODE`` setting determines the linkage mode for the PLUMED -library. The allowed values for this flag are "static" (default), -"shared", or "runtime". For a discussion of PLUMED linkage modes, -please see above. When ``DOWNLOAD_PLUMED`` is enabled the static -linkage mode is recommended. + If DOWNLOAD_PLUMED is set to "yes", the PLUMED library will be + downloaded (the version of PLUMED that will be downloaded is + hard-coded to a vetted version of PLUMED, usually a recent stable + release version) and built inside the CMake build directory. If + ``DOWNLOAD_PLUMED`` is set to "no" (the default), CMake will try + to detect and link to an installed version of PLUMED. For this to + work, the PLUMED library has to be installed into a location where + the ``pkg-config`` tool can find it or the PKG_CONFIG_PATH + environment variable has to be set up accordingly. PLUMED should + be installed in such a location if you compile it using the + default make; make install commands. -Traditional make -^^^^^^^^^^^^^^^^ + The ``PLUMED_MODE`` setting determines the linkage mode for the + PLUMED library. The allowed values for this flag are "static" + (default), "shared", or "runtime". If you want to switch the + linkage mode, just re-run CMake with a different setting. For a + discussion of PLUMED linkage modes, please see above. When + ``DOWNLOAD_PLUMED`` is enabled the static linkage mode is + recommended. -PLUMED needs to be installed before the USER-PLUMED package is installed -so that LAMMPS can find the right settings when compiling and linking -the LAMMPS executable. You can either download and build PLUMED inside -the LAMMPS plumed library folder or use a previously installed PLUMED -library and point LAMMPS to its location. You also have to choose the -linkage mode: "static" (default), "shared" or "runtime". For a -discussion of PLUMED linkage modes, please see above. + .. tab:: Traditional make -Download/compilation/configuration of the plumed library can be done -from the src folder through the following make args: + PLUMED needs to be installed before the USER-PLUMED package is + installed so that LAMMPS can find the right settings when + compiling and linking the LAMMPS executable. You can either + download and build PLUMED inside the LAMMPS plumed library folder + or use a previously installed PLUMED library and point LAMMPS to + its location. You also have to choose the linkage mode: "static" + (default), "shared" or "runtime". For a discussion of PLUMED + linkage modes, please see above. -.. code-block:: bash + Download/compilation/configuration of the plumed library can be done + from the src folder through the following make args: - $ make lib-plumed # print help message - $ make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2 - $ make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local - $ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in - # /usr/local and use shared linkage mode + .. code-block:: bash -Note that 2 symbolic (soft) links, ``includelink`` and ``liblink`` are -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 -suitable for LAMMPS to compile and link PLUMED using the desired linkage -mode. After this step is completed, you can install the USER-PLUMED -package and compile LAMMPS in the usual manner: + $ make lib-plumed # print help message + $ make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2 + $ make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local + $ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in + # /usr/local and use shared linkage mode -.. code-block:: bash + Note that 2 symbolic (soft) links, ``includelink`` and ``liblink`` + are 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 suitable for LAMMPS to compile and link + PLUMED using the desired linkage mode. After this step is + completed, you can install the USER-PLUMED package and compile + LAMMPS in the usual manner: - $ make yes-user-plumed - $ make machine + .. code-block:: bash -Once this compilation completes you should be able to run LAMMPS in the -usual way. For shared linkage mode, libplumed.so must be found by the -LAMMPS executable, which on many operating systems means, you have to -set the LD_LIBRARY_PATH environment variable accordingly. + $ make yes-user-plumed + $ make machine -Support for the different linkage modes in LAMMPS varies for different -operating systems, using the static linkage is expected to be the most -portable, and thus set to be the default. + Once this compilation completes you should be able to run LAMMPS + in the usual way. For shared linkage mode, libplumed.so must be + found by the LAMMPS executable, which on many operating systems + means, you have to set the LD_LIBRARY_PATH environment variable + accordingly. -If you want to change the linkage mode, you have to re-run "make -lib-plumed" with the desired settings **and** do a re-install if the -USER-PLUMED package with "make yes-user-plumed" to update the required -makefile settings with the changes in the lib/plumed folder. + Support for the different linkage modes in LAMMPS varies for + different operating systems, using the static linkage is expected + to be the most portable, and thus set to be the default. + + If you want to change the linkage mode, you have to re-run "make + lib-plumed" with the desired settings **and** do a re-install if + the USER-PLUMED package with "make yes-user-plumed" to update the + required makefile settings with the changes in the lib/plumed + folder. ---------- @@ -1218,38 +1271,39 @@ To build with this package you must have the HDF5 software package installed on your system, which should include the h5cc compiler and the HDF5 library. -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_USER-H5MD=yes``. + .. tab:: CMake build -This should auto-detect the H5MD library on your system. Several -advanced CMake H5MD options exist if you need to specify where it is -installed. Use the ccmake (terminal window) or cmake-gui (graphical) -tools to see these options and set them interactively from their user -interfaces. + No additional settings are needed besides ``-D PKG_USER-H5MD=yes``. -Traditional make -^^^^^^^^^^^^^^^^ + This should auto-detect the H5MD library on your system. Several + advanced CMake H5MD options exist if you need to specify where it + is installed. Use the ccmake (terminal window) or cmake-gui + (graphical) tools to see these options and set them interactively + from their user interfaces. -Before building LAMMPS, you must build the CH5MD library in -``lib/h5md``. You can do this manually if you prefer; follow the -instructions in ``lib/h5md/README``. You can also do it in one step -from the ``lammps/src`` dir, using a command like these, which simply -invoke the ``lib/h5md/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the CH5MD library in + ``lib/h5md``. You can do this manually if you prefer; follow the + instructions in ``lib/h5md/README``. You can also do it in one + step from the ``lammps/src`` dir, using a command like these, + which simply invoke the ``lib/h5md/Install.py`` script with the + specified args: - $ make lib-h5md # print help message - $ make lib-h5md args="-m h5cc" # build with h5cc compiler + .. code-block:: bash -The build should produce two files: ``lib/h5md/libch5md.a`` and -``lib/h5md/Makefile.lammps``. The latter is copied from an existing -``Makefile.lammps.*`` and has settings needed to build LAMMPS with the -system HDF5 library. If necessary, you can edit/create a new -``lib/h5md/Makefile.machine`` file for your system, which should define -an EXTRAMAKE variable to specify a corresponding -``Makefile.lammps.`` file. + $ make lib-h5md # print help message + $ make lib-h5md args="-m h5cc" # build with h5cc compiler + + The build should produce two files: ``lib/h5md/libch5md.a`` and + ``lib/h5md/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings needed to build + LAMMPS with the system HDF5 library. If necessary, you can + edit/create a new ``lib/h5md/Makefile.machine`` file for your + system, which should define an EXTRAMAKE variable to specify a + corresponding ``Makefile.lammps.`` file. ---------- @@ -1273,51 +1327,53 @@ incorrectly and thus can cause segmentation faults in otherwise correct code when using features from the USER-INTEL package. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D INTEL_ARCH=value # value = cpu (default) or knl - -D INTEL_LRT_MODE=value # value = threads, none, or c++11 + .. code-block:: bash + + -D INTEL_ARCH=value # value = cpu (default) or knl + -D INTEL_LRT_MODE=value # value = threads, none, or c++11 + + .. tab:: Traditional make + + Choose which hardware to compile for in Makefile.machine via the + following settings. See ``src/MAKE/OPTIONS/Makefile.intel_cpu*`` + and ``Makefile.knl`` files for examples. and + ``src/USER-INTEL/README`` for additional information. + + For CPUs: + + .. code-block:: make + + OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high + CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) + LINKFLAGS = -g -qopenmp $(OPTFLAGS) + LIB = -ltbbmalloc + + For KNLs: + + .. code-block:: make + + OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits + CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) + LINKFLAGS = -g -qopenmp $(OPTFLAGS) + LIB = -ltbbmalloc In Long-range thread mode (LRT) a modified verlet style is used, that operates the Kspace calculation in a separate thread concurrently to -other calculations. This has to be enabled in the :doc:`package intel ` -command at runtime. With the setting "threads" it used the pthreads -library, while c++11 will use the built-in thread support of C++11 -compilers. The option "none" skips compilation of this feature. The -default is to use "threads" if pthreads is available and otherwise "none". +other calculations. This has to be enabled in the :doc:`package intel +` command at runtime. With the setting "threads" it used the +pthreads library, while "c++11" will use the built-in thread support +of C++11 compilers. The option "none" skips compilation of this +feature. The default is to use "threads" if pthreads is available and +otherwise "none". -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 -runs with other compilers and without TBB and MKL. - -Traditional make -^^^^^^^^^^^^^^^^ - -Choose which hardware to compile for in Makefile.machine via the -following settings. See ``src/MAKE/OPTIONS/Makefile.intel_cpu*`` and -``Makefile.knl`` files for examples. and ``src/USER-INTEL/README`` for -additional information. - -For CPUs: - -.. code-block:: make - - OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high - CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) - LINKFLAGS = -g -qopenmp $(OPTFLAGS) - LIB = -ltbbmalloc - -For KNLs: - -.. code-block:: make - - OPTFLAGS = -xMIC-AVX512 -O2 -fp-model fast=2 -no-prec-div -qoverride-limits - CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload -fno-alias -ansi-alias -restrict $(OPTFLAGS) - LINKFLAGS = -g -qopenmp $(OPTFLAGS) - LIB = -ltbbmalloc +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 runs with other compilers / hardware and without +TBB and MKL. ---------- @@ -1332,31 +1388,34 @@ compile it. Also, the files with the force field data for running the bundled examples are not included in the source distribution. Instead they will be downloaded the first time this package is installed. -**CMake build**\ : +.. tabs:: -No additional settings are needed besides ``-D PKG_USER-MESONT=yes`` + .. tab:: CMake build -**Traditional make**\ : + No additional settings are needed besides ``-D PKG_USER-MESONT=yes`` -Before building LAMMPS, you must build the *mesont* library in ``lib/mesont``\ . -You can also do it in one step from the ``lammps/src`` dir, using a command like -these, which simply invoke the ``lib/mesont/Install.py`` script with the specified -args: + .. tab:: Traditional make -.. code-block:: bash + Before building LAMMPS, you must build the *mesont* library in + ``lib/mesont``\ . You can also do it in one step from the + ``lammps/src`` dir, using a command like these, which simply + invoke the ``lib/mesont/Install.py`` script with the specified + args: - $ make lib-mesont # print help message - $ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial") - $ make lib-mesont args="-m ifort" # build with Intel icc compiler + .. code-block:: bash -The build should produce two files: ``lib/mesont/libmesont.a`` and -``lib/mesont/Makefile.lammps``\ . The latter is copied from an existing -``Makefile.lammps.\*`` and has settings needed to build LAMMPS with the -*mesont* library (though typically the settings contain only the Fortran -runtime library). If necessary, you can edit/create a new -``lib/mesont/Makefile.machine`` file for your system, which should -define an ``EXTRAMAKE`` variable to specify a corresponding -``Makefile.lammps.machine`` file. + $ make lib-mesont # print help message + $ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial") + $ make lib-mesont args="-m ifort" # build with Intel icc compiler + + The build should produce two files: ``lib/mesont/libmesont.a`` and + ``lib/mesont/Makefile.lammps``\ . The latter is copied from an + existing ``Makefile.lammps.\*`` and has settings needed to build + LAMMPS with the *mesont* library (though typically the settings + contain only the Fortran runtime library). If necessary, you can + edit/create a new ``lib/mesont/Makefile.machine`` file for your + system, which should define an ``EXTRAMAKE`` variable to specify a + corresponding ``Makefile.lammps.machine`` file. ---------- @@ -1365,35 +1424,36 @@ define an ``EXTRAMAKE`` variable to specify a corresponding USER-MOLFILE package --------------------------------------- -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D MOLFILE_INCLUDE_DIR=path # (optional) path where VMD molfile plugin headers are installed - -D PKG_USER-MOLFILE=yes + .. code-block:: bash -Using "-D PKG_USER-MOLFILE=yes" enables the package, and setting -"-D MOLFILE_INCLUDE DIR" allows to provide a custom location for -the molfile plugin header files. These should match the ABI of the -plugin files used, and thus one typically sets them to include -folder of the local VMD installation in use. LAMMPS ships with a -couple of default header files that correspond to a popular VMD -version, usually the latest release. + -D MOLFILE_INCLUDE_DIR=path # (optional) path where VMD molfile plugin headers are installed + -D PKG_USER-MOLFILE=yes -Traditional make -^^^^^^^^^^^^^^^^ + Using ``-D PKG_USER-MOLFILE=yes`` enables the package, and setting + ``-D MOLFILE_INCLUDE_DIR`` allows to provide a custom location for + the molfile plugin header files. These should match the ABI of the + plugin files used, and thus one typically sets them to include + folder of the local VMD installation in use. LAMMPS ships with a + couple of default header files that correspond to a popular VMD + version, usually the latest release. -The ``lib/molfile/Makefile.lammps`` file has a setting for a dynamic -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 -not valid for your system, you will need to edit the Makefile.lammps -file. See ``lib/molfile/README`` and ``lib/molfile/Makefile.lammps`` for -details. It is also possible to configure a different folder with -the VMD molfile plugin header files. LAMMPS ships with a couple of -default headers, but these are not compatible with all VMD versions, -so it is often best to change this setting to the location of the -same include files of the local VMD installation in use. + .. tab:: Traditional make + + The ``lib/molfile/Makefile.lammps`` file has a setting for a + dynamic 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 not valid for your system, you will need to edit + the Makefile.lammps file. See ``lib/molfile/README`` and + ``lib/molfile/Makefile.lammps`` for details. It is also possible + to configure a different folder with the VMD molfile plugin header + files. LAMMPS ships with a couple of default headers, but these + are not compatible with all VMD versions, so it is often best to + change this setting to the location of the same include files of + the local VMD installation in use. ---------- @@ -1405,24 +1465,26 @@ USER-NETCDF package To build with this package you must have the NetCDF library installed on your system. -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_USER-NETCDF=yes``. + .. tab:: CMake build -This should auto-detect the NETCDF library if it is installed on your -system at standard locations. Several advanced CMake NETCDF options -exist if you need to specify where it was installed. Use the ``ccmake`` -(terminal window) or ``cmake-gui`` (graphical) tools to see these -options and set them interactively from their user interfaces. + No additional settings are needed besides ``-D PKG_USER-NETCDF=yes``. -Traditional make -^^^^^^^^^^^^^^^^ + This should auto-detect the NETCDF library if it is installed on + your system at standard locations. Several advanced CMake NETCDF + options exist if you need to specify where it was installed. Use + the ``ccmake`` (terminal window) or ``cmake-gui`` (graphical) + tools to see these options and set them interactively from their + user interfaces. -The ``lib/netcdf/Makefile.lammps`` file has settings for NetCDF include -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 -``Makefile.lammps`` file. See ``lib/netcdf/README`` for details. + .. tab:: Traditional make + + The ``lib/netcdf/Makefile.lammps`` file has settings for NetCDF + include 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 ``Makefile.lammps`` file. See + ``lib/netcdf/README`` for details. ---------- @@ -1431,30 +1493,31 @@ the settings are not valid for your system, you will need to edit the USER-OMP package ------------------------------- -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are required besides ``-D PKG_USER-OMP=yes``. If -CMake detects OpenMP support, the USER-OMP code will be compiled with -multi-threading support enabled, otherwise as optimized serial code. + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + No additional settings are required besides ``-D + PKG_USER-OMP=yes``. If CMake detects OpenMP compiler support, the + USER-OMP code will be compiled with multi-threading support + enabled, otherwise as optimized serial code. -To enable multi-threading support in the USER-OMP package (and other -styles supporting OpenMP) the following compile and link flags must be -added to your Makefile.machine file. See -``src/MAKE/OPTIONS/Makefile.omp`` for an example. + .. tab:: Traditional make -.. parsed-literal:: + To enable multi-threading support in the USER-OMP package (and + other styles supporting OpenMP) the following compile and link + flags must be added to your Makefile.machine file. See + ``src/MAKE/OPTIONS/Makefile.omp`` for an example. - CCFLAGS: -fopenmp # for GNU and Clang Compilers - CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux - LINKFLAGS: -fopenmp # for GNU and Clang Compilers - LINKFLAGS: -qopenmp # for Intel compilers on Linux + .. parsed-literal:: -For other platforms and compilers, please consult the documentation -about OpenMP support for your compiler. + CCFLAGS: -fopenmp # for GNU and Clang Compilers + CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux + LINKFLAGS: -fopenmp # for GNU and Clang Compilers + LINKFLAGS: -qopenmp # for Intel compilers on Linux + + For other platforms and compilers, please consult the + documentation about OpenMP support for your compiler. ---------- @@ -1476,58 +1539,60 @@ and LAMMPS versions. The current interface and makefiles have last been verified to work in February 2020 with Quantum Espresso versions 6.3 to 6.5. -CMake build -^^^^^^^^^^^ +.. tabs:: -When using CMake, building a LAMMPS library is required and it is -recommended to build a shared library, since any libraries built from -the sources in the *lib* folder (including the essential libqmmm.a) -are not included in the static LAMMPS library and (currently) not -installed, while their code is included in the shared LAMMPS library. -Thus a typical command line to configure building LAMMPS for USER-QMMM -would be: + .. tab:: CMake build -.. code-block:: bash + When using CMake, building a LAMMPS library is required and it is + recommended to build a shared library, since any libraries built + from the sources in the *lib* folder (including the essential + libqmmm.a) are not included in the static LAMMPS library and + (currently) not installed, while their code is included in the + shared LAMMPS library. Thus a typical command line to configure + building LAMMPS for USER-QMMM would be: - cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \ - -D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake + .. code-block:: bash -After completing the LAMMPS build and also configuring and compiling -Quantum ESPRESSO with external library support (via "make couple"), -go back to the ``lib/qmmm` folder and follow the instructions on the -README file to build the combined LAMMPS/QE QM/MM executable -(pwqmmm.x) in the ``lib/qmmm`` folder. You need to make certain, that + cmake -C ../cmake/presets/minimal.cmake -D PKG_USER-QMMM=yes \ + -D BUILD_LIB=yes -DBUILD_SHARED_LIBS=yes ../cmake -Traditional make -^^^^^^^^^^^^^^^^ + After completing the LAMMPS build and also configuring and + compiling Quantum ESPRESSO with external library support (via + "make couple"), go back to the ``lib/qmmm`` folder and follow the + instructions on the README file to build the combined LAMMPS/QE + QM/MM executable (pwqmmm.x) in the ``lib/qmmm`` folder. -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 -explained in ``lib/qmmm/README``. You can also do it in one step from -the ``lammps/src`` dir, using a command like these, which simply invoke -the ``lib/qmmm/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + 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 explained in ``lib/qmmm/README``. You can also do + it in one step from the ``lammps/src`` dir, using a command like + these, which simply invoke the ``lib/qmmm/Install.py`` script with + the specified args: - $ make lib-qmmm # print help message - $ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial") - $ 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 + .. code-block:: bash -The build should produce two files: ``lib/qmmm/libqmmm.a`` and -``lib/qmmm/Makefile.lammps``. The latter is copied from an existing -``Makefile.lammps.*`` and has settings needed to build LAMMPS with the -QMMM library (though typically the settings are just blank). If -necessary, you can edit/create a new ``lib/qmmm/Makefile.`` file -for your system, which should define an ``EXTRAMAKE`` variable to -specify a corresponding ``Makefile.lammps.`` file. + $ make lib-qmmm # print help message + $ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial") + $ 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 -You can then install QMMM package and build LAMMPS in the usual -manner. After completing the LAMMPS build and compiling Quantum -ESPRESSO with external library support (via "make couple"), go back 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 -lib/qmmm folder. + The build should produce two files: ``lib/qmmm/libqmmm.a`` and + ``lib/qmmm/Makefile.lammps``. The latter is copied from an + existing ``Makefile.lammps.*`` and has settings needed to build + LAMMPS with the QMMM library (though typically the settings are + just blank). If necessary, you can edit/create a new + ``lib/qmmm/Makefile.`` file for your system, which should + define an ``EXTRAMAKE`` variable to specify a corresponding + ``Makefile.lammps.`` file. + + You can then install QMMM package and build LAMMPS in the usual + manner. After completing the LAMMPS build and compiling Quantum + ESPRESSO with external library support (via "make couple"), go + back 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 lib/qmmm folder. ---------- @@ -1542,27 +1607,27 @@ potentials, additional files with specific licensing conditions need 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. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location) + .. code-block:: bash -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 -work. Set QUIP_LIBRARY if CMake cannot find the QUIP library. + -D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location) -Traditional make -^^^^^^^^^^^^^^^^ + 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 + work. Set the ``QUIP_LIBRARY`` variable if CMake cannot find the QUIP library. -The download/build procedure for the QUIP library, described in -``lib/quip/README`` file requires setting two environment variables, -QUIP_ROOT and QUIP_ARCH. These are accessed by the -lib/quip/Makefile.lammps file which is used when you compile and link -LAMMPS with this package. You should only need to edit -``Makefile.lammps`` if the LAMMPS build can not use its settings to -successfully build on your system. + .. tab:: Traditional make + + The download/build procedure for the QUIP library, described in + ``lib/quip/README`` file requires setting two environment + variables, ``QUIP_ROOT`` and ``QUIP_ARCH``. These are accessed by + the ``lib/quip/Makefile.lammps`` file which is used when you + compile and link LAMMPS with this package. You should only need + to edit ``Makefile.lammps`` if the LAMMPS build can not use its + settings to successfully build on your system. ---------- @@ -1571,44 +1636,45 @@ successfully build on your system. USER-SCAFACOS package ----------------------------------------- -To build with this package, you must download and build the `ScaFaCoS -Coulomb solver library `_ +To build with this package, you must download and build the +`ScaFaCoS Coulomb solver library `_ -.. _scafacos-home: http://www.scafacos.de +.. tabs:: -CMake build -^^^^^^^^^^^ + .. tab:: CMake build -.. code-block:: bash + .. code-block:: bash - -D DOWNLOAD_SCAFACOS=value # download ScaFaCoS for build, value = no (default) or yes - -D SCAFACOS_LIBRARY=path # ScaFaCos library file (only needed if at custom location) - -D SCAFACOS_INCLUDE_DIR=path # ScaFaCoS include directory (only needed if at custom location) + -D DOWNLOAD_SCAFACOS=value # download ScaFaCoS for build, value = no (default) or yes + -D SCAFACOS_LIBRARY=path # ScaFaCos library file (only needed if at custom location) + -D SCAFACOS_INCLUDE_DIR=path # ScaFaCoS include directory (only needed if at custom location) -If DOWNLOAD_SCAFACOS is set, the ScaFaCoS library will be downloaded -and built inside the CMake build directory. If the ScaFaCoS library -is already on your system (in a location CMake cannot find it), -SCAFACOS_LIBRARY is the filename (plus path) of the ScaFaCoS library -file, not the directory the library file is in. SCAFACOS_INCLUDE_DIR -is the directory the ScaFaCoS include file is in. + If ``DOWNLOAD_SCAFACOS`` is set, the ScaFaCoS library will be + downloaded and built inside the CMake build directory. If the + ScaFaCoS library is already on your system (in a location CMake + cannot find it), ``SCAFACOS_LIBRARY`` is the filename (plus path) of + the ScaFaCoS library file, not the directory the library file is + in. ``SCAFACOS_INCLUDE_DIR`` is the directory the ScaFaCoS include + file is in. -Traditional make -^^^^^^^^^^^^^^^^ + .. tab:: Traditional make -You can download and build the ScaFaCoS library manually if you -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, -which simply invoke the ``lib/scafacos/Install.py`` script with the -specified args: + You can download and build the ScaFaCoS library manually if you + 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, which simply invoke the + ``lib/scafacos/Install.py`` script with the specified args: -make lib-scafacos # print help message -make lib-scafacos args="-b" # download and build in lib/scafacos/scafacos- -make lib-scafacos args="-p $HOME/scafacos # use existing ScaFaCoS installation in $HOME/scafacos + .. code-block:: bash -Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``, are -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 -the ``lib/scafacos/Makefile.lammps`` file. + make lib-scafacos # print help message + make lib-scafacos args="-b" # download and build in lib/scafacos/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 + 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 + the ``lib/scafacos/Makefile.lammps`` file. ---------- @@ -1620,37 +1686,39 @@ USER-SMD package To build with this package, you must download the Eigen3 library. Eigen3 is a template library, so you do not need to build it. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -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) + .. code-block:: bash -If ``DOWNLOAD_EIGEN3`` is set, the Eigen3 library will be downloaded and -inside the CMake build directory. If the Eigen3 library is already on -your system (in a location CMake cannot find it), ``EIGEN3_INCLUDE_DIR`` -is the directory the Eigen3++ include file is in. + -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) -Traditional make -^^^^^^^^^^^^^^^^ + If ``DOWNLOAD_EIGEN3`` is set, the Eigen3 library will be + downloaded and inside the CMake build directory. If the Eigen3 + library is already on your system (in a location where CMake + cannot find it), set ``EIGEN3_INCLUDE_DIR`` to the directory the + ``Eigen3`` include file is in. -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 -the ``lammps/src`` dir, using a command like these, which simply invoke -the ``lib/smd/Install.py`` script with the specified args: + .. tab:: Traditional make -.. code-block:: bash + 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 the ``lammps/src`` dir, using a command like these, + which simply invoke the ``lib/smd/Install.py`` script with the + specified args: - $ make lib-smd # print help message - $ 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 + .. code-block:: bash -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 -this link. You should not need to edit the ``lib/smd/Makefile.lammps`` -file. + $ make lib-smd # print help message + $ 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 + + 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 this link. You should not need to edit the + ``lib/smd/Makefile.lammps`` file. ---------- @@ -1662,23 +1730,24 @@ USER-VTK package To build with this package you must have the VTK library installed on your system. -CMake build -^^^^^^^^^^^ +.. tabs:: -No additional settings are needed besides ``-D PKG_USER-VTK=yes``. + .. tab:: CMake build -This should auto-detect the VTK library if it is installed on your -system at standard locations. Several advanced VTK options exist if -you need to specify where it was installed. Use the ``ccmake`` (terminal -window) or ``cmake-gui`` (graphical) tools to see these options and set -them interactively from their user interfaces. + No additional settings are needed besides ``-D PKG_USER-VTK=yes``. -Traditional make -^^^^^^^^^^^^^^^^ + This should auto-detect the VTK library if it is installed on your + system at standard locations. Several advanced VTK options exist + if you need to specify where it was installed. Use the ``ccmake`` + (terminal window) or ``cmake-gui`` (graphical) tools to see these + options and set them interactively from their user interfaces. -The ``lib/vtk/Makefile.lammps`` file has settings for accessing VTK files -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 -``lib/vtk/Makefile.lammps.*`` files is compatible and copy it 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. + .. tab:: Traditional make + + The ``lib/vtk/Makefile.lammps`` file has settings for accessing + VTK files 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 ``lib/vtk/Makefile.lammps.*`` files is compatible + and copy it 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. diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index 87899739bc..3d66371304 100644 --- a/doc/src/Build_link.rst +++ b/doc/src/Build_link.rst @@ -41,42 +41,45 @@ The benefit of linking to a static library is, that the resulting executable is independent of that library since all required executable code from the library is copied into the calling executable. -CMake build -^^^^^^^^^^^ +.. tabs:: -This assumes that LAMMPS has been configured without setting a -``LAMMPS_MACHINE`` name, installed with "make install", and the -``PKG_CONFIG_PATH`` environment variable has been updated to include the -``liblammps.pc`` file installed into the configured destination folder. -The commands to compile and link a coupled executable are then: + .. tab:: CMake build -.. code-block:: bash + This assumes that LAMMPS has been configured without setting a + ``LAMMPS_MACHINE`` name, installed with "make install", and the + ``PKG_CONFIG_PATH`` environment variable has been updated to + include the ``liblammps.pc`` file installed into the configured + destination folder. The commands to compile and link a coupled + executable are then: - mpicc -c -O $(pkgconf liblammps --cflags) caller.c - mpicxx -o caller caller.o -$(pkgconf liblammps --libs) + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + mpicc -c -O $(pkgconf liblammps --cflags) caller.c + mpicxx -o caller caller.o -$(pkgconf liblammps --libs) -This assumes that LAMMPS has been compiled in the folder -``${HOME}/lammps/src`` with "make mpi". The commands to compile and link -a coupled executable are then: + .. tab:: Traditional make -.. code-block:: bash + This assumes that LAMMPS has been compiled in the folder + ``${HOME}/lammps/src`` with "make mpi". The commands to compile + and link a coupled executable are then: - mpicc -c -O -I${HOME}/lammps/src caller.c - mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi + .. code-block:: bash -The *-I* argument is the path to the location of the ``library.h`` -header file containing the interface to the LAMMPS C-style library -interface. The *-L* argument is the path to where the ``liblammps_mpi.a`` -file is located. The *-llammps_mpi* argument is shorthand for telling the -compiler to link the file ``liblammps_mpi.a``. If LAMMPS has been -built as a shared library, then the linker will use ``liblammps_mpi.so`` -instead. If both files are available, the linker will usually prefer -the shared library. In case of a shared library, you may need to update -the ``LD_LIBRARY_PATH`` environment variable or running the ``caller`` -executable will fail since it cannot find the shared library at runtime. + mpicc -c -O -I${HOME}/lammps/src caller.c + mpicxx -o caller caller.o -L${HOME}/lammps/src -llammps_mpi + + The *-I* argument is the path to the location of the ``library.h`` + header file containing the interface to the LAMMPS C-style library + interface. The *-L* argument is the path to where the + ``liblammps_mpi.a`` file is located. The *-llammps_mpi* argument + is shorthand for telling the compiler to link the file + ``liblammps_mpi.a``. If LAMMPS has been built as a shared + library, then the linker will use ``liblammps_mpi.so`` instead. + If both files are available, the linker will usually prefer the + shared library. In case of a shared library, you may need to + update the ``LD_LIBRARY_PATH`` environment variable or running the + ``caller`` executable will fail since it cannot find the shared + library at runtime. However, it is only as simple as shown above for the case of a plain LAMMPS library without any optional packages that depend on libraries @@ -84,61 +87,62 @@ LAMMPS library without any optional packages that depend on libraries need to include all flags, libraries, and paths for the coupled executable, that are also required to link the LAMMPS executable. -CMake build -^^^^^^^^^^^ +.. tabs:: -When using CMake, additional libraries with sources in the lib folder -are built, but not included in ``liblammps.a`` and (currently) not -installed with ``make install`` and not included in the ``pkgconfig`` -configuration file. They can be found in the top level build folder, -but you have to determine the necessary link flags manually. It is -therefore recommended to either use the traditional make procedure to -build and link with a static library or build and link with a shared -library instead. + .. tab:: CMake build -Traditional make -^^^^^^^^^^^^^^^^ + When using CMake, additional libraries with sources in the lib + folder are built, but not included in ``liblammps.a`` and + (currently) not installed with ``make install`` and not included + in the ``pkgconfig`` configuration file. They can be found in the + top level build folder, but you have to determine the necessary + link flags manually. It is therefore recommended to either use + the traditional make procedure to build and link with a static + library or build and link with a shared library instead. -After you have compiled a static LAMMPS library using the conventional -build system for example with "make mode=static serial". And you also -have installed the ``POEMS`` package after building its bundled library -in ``lib/poems``. Then the commands to build and link the coupled executable -change to: + .. tab:: Traditional make -.. code-block:: bash + After you have compiled a static LAMMPS library using the + conventional build system for example with "make mode=static + serial". And you also have installed the ``POEMS`` package after + building its bundled library in ``lib/poems``. Then the commands + to build and link the coupled executable change to: - gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c - g++ -o caller caller.o -L${HOME}/lammps/lib/poems \ - -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src -llammps_serial -lpoems -lmpi_stubs + .. code-block:: bash -Note, that you need to link with ``g++`` instead of ``gcc`` even if you have -written your code in C, since LAMMPS itself is C++ code. You can display the -currently applied settings for building LAMMPS for the "serial" machine target -by using the command: + gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c + g++ -o caller caller.o -L${HOME}/lammps/lib/poems \ + -L${HOME}/lammps/src/STUBS -L${HOME}/lammps/src \ + -llammps_serial -lpoems -lmpi_stubs -.. code-block:: bash + Note, that you need to link with ``g++`` instead of ``gcc`` even + if you have written your code in C, since LAMMPS itself is C++ + code. You can display the currently applied settings for building + LAMMPS for the "serial" machine target by using the command: - make mode=print serial + .. code-block:: bash -Which should output something like: + make mode=print serial -.. code-block:: bash + Which should output something like: - # Compiler: - CXX=g++ - # Linker: - LD=g++ - # Compilation: - CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS - # Linking: - LDFLAGS=-g -O - # Libraries: - LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs + .. code-block:: bash -From this you can gather the necessary paths and flags. With -makefiles for other *machine* configurations you need to do the -equivalent and replace "serial" with the corresponding "machine" name -of the makefile. + # Compiler: + CXX=g++ + # Linker: + LD=g++ + # Compilation: + CXXFLAGS=-g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I${HOME}/compile/lammps/lib/poems -I${HOME}/compile/lammps/src/STUBS + # Linking: + LDFLAGS=-g -O + # Libraries: + LDLIBS=-L${HOME}/compile/lammps/src -llammps_serial -L${HOME}/compile/lammps/lib/poems -L${HOME}/compile/lammps/src/STUBS -lpoems -lmpi_stubs + + From this you can gather the necessary paths and flags. With + makefiles for other *machine* configurations you need to do the + equivalent and replace "serial" with the corresponding "machine" + name of the makefile. Link with LAMMPS as a shared library ------------------------------------ @@ -151,35 +155,36 @@ linking the calling executable. Only the *-I* flags are needed. So the example case from above of the serial version static LAMMPS library with the POEMS package installed becomes: -CMake build -^^^^^^^^^^^ +.. tabs:: -The commands with a shared LAMMPS library compiled with the CMake -build process are the same as for the static library. + .. tab:: CMake build -.. code-block:: bash + The commands with a shared LAMMPS library compiled with the CMake + build process are the same as for the static library. - mpicc -c -O $(pkgconf liblammps --cflags) caller.c - mpicxx -o caller caller.o -$(pkgconf --libs) + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + mpicc -c -O $(pkgconf liblammps --cflags) caller.c + mpicxx -o caller caller.o -$(pkgconf --libs) -The commands with a shared LAMMPS library compiled with the -traditional make build using ``make mode=shared serial`` becomes: + .. tab:: Traditional make -.. code-block:: bash + The commands with a shared LAMMPS library compiled with the + traditional make build using ``make mode=shared serial`` becomes: - gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c - g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial + .. code-block:: bash -*Locating liblammps.so at runtime*\ : + gcc -c -O -I${HOME}/lammps/src/STUBS -I${HOME}/lammps/src -caller.c + g++ -o caller caller.o -L${HOME}/lammps/src -llammps_serial -However, now the ``liblammps.so`` file is required at runtime and needs -to be in a folder, where the shared linker program of the operating -system can find it. This would be either a folder like ``/usr/local/lib64`` -or ``${HOME}/.local/lib64`` or a folder pointed to by the ``LD_LIBRARY_PATH`` -environment variable. You can type +Locating liblammps.so at runtime +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Unlike with a static link, now the ``liblammps.so`` file is required at +runtime and needs to be in a folder, where the shared linker program of +the operating system can find it. This would be either a folder like +``/usr/local/lib64`` or ``${HOME}/.local/lib64`` or a folder pointed to +by the ``LD_LIBRARY_PATH`` environment variable. You can type .. code-block:: bash @@ -187,9 +192,10 @@ environment variable. You can type to see what directories are in that list. -Or you can add the LAMMPS src directory (or the directory you performed -a CMake style build in) to your ``LD_LIBRARY_PATH``, so that the current -version of the shared library is always available to programs that use it. +Or you can add the LAMMPS src directory or the directory you performed a +CMake style build in to your ``LD_LIBRARY_PATH`` environment variable, +so that the current version of the shared library is always available to +programs that use it. For the Bourne or Korn shells (/bin/sh, /bin/ksh, /bin/bash etc.), you would add something like this to your ``${HOME}/.profile`` file: diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index 32b72c544a..72f7ba74f3 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -45,91 +45,92 @@ packages: The mechanism for including packages is simple but different for CMake versus make. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: csh + .. tab:: CMake build - -D PKG_NAME=value # yes or no (default) + .. code-block:: csh -Examples: + -D PKG_NAME=value # yes or no (default) -.. code-block:: csh + Examples: - -D PKG_MANYBODY=yes - -D PKG_USER-INTEL=yes + .. code-block:: csh -All standard and user packages are included the same way. Note that -USER packages have a hyphen between USER and the rest of the package -name, not an underscore. + -D PKG_MANYBODY=yes + -D PKG_USER-INTEL=yes -See the shortcut section below for how to install many packages at -once with CMake. + All standard and user packages are included the same way. Note + that USER packages have a hyphen between USER and the rest of the + package name, not an underscore. + + See the shortcut section below for how to install many packages at + once with CMake. + + .. note:: + + If you switch between building with CMake and make builds, no + packages in the src directory can be installed when you invoke + ``cmake``. CMake will give an error if that is not the case, + indicating how you can un-install all packages in the src dir. + + .. tab:: Traditional make + + .. code-block:: bash + + cd lammps/src + make ps # check which packages are currently installed + make yes-name # install a package with name + make no-name # un-install a package with name + make mpi # build LAMMPS with whatever packages are now installed + + Examples: + + .. code-block:: bash + + make no-rigid + make yes-user-intel + + All standard and user packages are included the same way. + + See the shortcut section below for how to install many packages at + once with make. + + .. note:: + + You must always re-build LAMMPS (via make) after installing or + un-installing a package, for the action to take effect. The + included dependency tracking will make certain only files that + are required to be rebuilt are recompiled. + + .. note:: + + You cannot install or un-install packages and build LAMMPS in a + single make command with multiple targets, e.g. ``make + yes-colloid mpi``. 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 within the same command. + You can include or exclude multiple packages in a single make + command, e.g. ``make yes-colloid no-manybody``. + + +Information for both build systems +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Almost all packages can be included or excluded in a LAMMPS build, +independent of the other packages. However, some packages include files +derived from files in other packages. LAMMPS checks for this and does +the right thing. 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. .. note:: - If you toggle back and forth between building with CMake vs - make, no packages in the src directory can be installed when you - invoke cmake. CMake will give an error if that is not the case, - indicating how you can un-install all packages in the src dir. - -Traditional make -^^^^^^^^^^^^^^^^ - -.. code-block:: bash - - cd lammps/src - make ps # check which packages are currently installed - make yes-name # install a package with name - make no-name # un-install a package with name - make mpi # build LAMMPS with whatever packages are now installed - -Examples: - -.. code-block:: bash - - make no-rigid - make yes-user-intel - -All standard and user packages are included the same way. - -See the shortcut section below for how to install many packages at -once with make. - -.. note:: - - You must always re-build LAMMPS (via make) after installing or - un-installing a package, for the action to take effect. - -.. note:: - - You cannot install or un-install packages and build LAMMPS in a - single make command with multiple targets, e.g. make yes-colloid mpi. - 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 - within the same command. You can include or exclude multiple packages - in a single make command, e.g. make yes-colloid no-manybody. - -CMake and make info -^^^^^^^^^^^^^^^^^^^ - -Any package can be included or excluded in a LAMMPS build, independent -of all other packages. However, some packages include files derived -from files in other packages. LAMMPS checks for this and does the -right thing. 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. - -When you download a LAMMPS tarball or download LAMMPS source files -from the git repository, no packages are pre-installed in the -src directory. - -.. note:: - - Prior to Aug 2018, if you downloaded a tarball, 3 packages - (KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory. - That is no longer the case, so that CMake will build as-is without the - need to un-install those packages. + By default no package is installed. Prior to August 2018, however, + if you downloaded a tarball, 3 packages (KSPACE, MANYBODY, MOLECULE) + were pre-installed via the traditional make procedure in the ``src`` + directory. That is no longer the case, so that CMake will build + as-is without needing to un-install those packages. ---------- diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 46ae728a5e..b6b0e9bab2 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -44,74 +44,71 @@ require use of an FFT library to compute 1d FFTs. The KISS FFT library is included with LAMMPS but other libraries can be faster. LAMMPS can use them if they are available on your system. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS - -D FFT_SINGLE=value # yes or no (default), no = double precision - -D FFT_PACK=value # array (default) or pointer or memcpy + .. code-block:: bash -.. note:: + -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS + -D FFT_SINGLE=value # yes or no (default), no = double precision + -D FFT_PACK=value # array (default) or pointer or memcpy - The values for the FFT variable must be in upper-case. This is - an exception to the rule that all CMake variables can be specified - with lower-case values. + .. note:: -Usually these settings are all that is needed. If FFTW3 is selected, -then CMake will try to detect, if threaded FFTW libraries are available -and enable them by default. This setting is independent of whether -OpenMP threads are enabled and a packages like KOKKOS or USER-OMP is -used. If CMake cannot detect the FFT library, you can set these variables -to assist: + The values for the FFT variable must be in upper-case. This is + an exception to the rule that all CMake variables can be specified + with lower-case values. -.. code-block:: bash + Usually these settings are all that is needed. If FFTW3 is + selected, then CMake will try to detect, if threaded FFTW + libraries are available and enable them by default. This setting + is independent of whether OpenMP threads are enabled and a + packages like KOKKOS or USER-OMP is used. If CMake cannot detect + the FFT library, you can set these variables to assist: - -D FFTW3_INCLUDE_DIR=path # path to FFTW3 include files - -D FFTW3_LIBRARY=path # path to FFTW3 libraries - -D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries - -D MKL_INCLUDE_DIR=path # ditto for Intel MKL library - -D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries - -D MKL_LIBRARY=path # path to MKL libraries + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D FFTW3_INCLUDE_DIR=pat h # path to FFTW3 include files + -D FFTW3_LIBRARY=path # path to FFTW3 libraries + -D FFT_FFTW_THREADS=on # enable using threaded FFTW3 libraries + -D MKL_INCLUDE_DIR=path # ditto for Intel MKL library + -D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries + -D MKL_LIBRARY=path # path to MKL libraries -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. + .. tab:: Traditional make -.. code-block:: 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. - FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS - # default is KISS if not specified - FFT_INC = -DFFT_SINGLE # do not specify for double precision - FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries - FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries - FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY + .. code-block:: make -# default is FFT_PACK_ARRAY if not specified + FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS + # default is KISS if not specified + FFT_INC = -DFFT_SINGLE # do not specify for double precision + FFT_INC = -DFFT_FFTW_THREADS # enable using threaded FFTW3 libraries + FFT_INC = -DFFT_MKL_THREADS # enable using threaded FFTs with MKL libraries + FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY + # default is FFT_PACK_ARRAY if not specified -.. code-block:: make + .. code-block:: make - FFT_INC = -I/usr/local/include - FFT_PATH = -L/usr/local/lib - FFT_LIB = -lfftw3 # FFTW3 double precision - FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS) - FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision - FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface - FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface - FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface - FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface - FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs + FFT_INC = -I/usr/local/include + FFT_PATH = -L/usr/local/lib + FFT_LIB = -lfftw3 # FFTW3 double precision + FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS) + FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision + FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler, serial interface + FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface + FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface + FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface + FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs -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. -You must specify ``FFT_LIB`` with the appropriate FFT libraries to include in the link. - -CMake build -^^^^^^^^^^^ + 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. You must specify ``FFT_LIB`` + with the appropriate FFT libraries to include in the link. The `KISS FFT library `_ is included in the LAMMPS distribution. It is portable across all platforms. Depending on the size @@ -177,76 +174,104 @@ ARRAY mode. .. _size: -Size of LAMMPS integer types ------------------------------------- +Size of LAMMPS integer types and size limits +-------------------------------------------- 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. +This has an impact on the size of a system that can be simulated +or how large counters can become before "rolling over". The default setting of "smallbig" is almost always adequate. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall + With CMake the choice of integer types is made via setting a + variable during configuration. -Traditional build -^^^^^^^^^^^^^^^^^ + .. code-block:: bash -If you want a setting different from the default, you need to edit your -machine Makefile. + -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall -.. code-block:: make + If the variable is not set explicitly, "smallbig" is used. - LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL + .. tab:: Traditional build -The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified + If you want a setting different from the default, you need to edit the + ``LMP_INC`` variable setting your machine Makefile. -CMake and make info -^^^^^^^^^^^^^^^^^^^ + .. code-block:: make -The default "smallbig" setting allows for simulations with: + LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL -* total atom count = 2\^63 atoms (about 9e18) -* total timesteps = 2\^63 (about 9e18) -* atom IDs = 2\^31 (about 2 billion) -* image flags = roll over at 512 + The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified -The "bigbig" setting increases the latter two limits. It allows for: +LAMMPS system size restrictions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* total atom count = 2\^63 atoms (about 9e18) -* total timesteps = 2\^63 (about 9e18) -* atom IDs = 2\^63 (about 9e18) -* image flags = roll over at about 1 million (2\^20) +.. list-table:: + :header-rows: 1 + :widths: auto + :align: center -The "smallsmall" setting is only needed if your machine does not -support 8-byte integers. It allows for: + * - + - smallbig + - bigbig + - smallsmall + * - Total atom count + - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`) + - :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`) + - :math:`2^{31}` atoms (= :math:`2.147 \cdot 10^9`) + * - Total timesteps + - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`) + - :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`) + - :math:`2^{31}` steps (= :math:`2.147 \cdot 10^9`) + * - Atom ID values + - :math:`1 \le i \le 2^{31} (= 2.147 \dot 10^9)` + - :math:`1 \le i \le 2^{63} (= 9.223 \cdot 10^{18})` + - :math:`1 \le i \le 2^{31} (= 2.147 \dot 10^9)` + * - Image flag values + - :math:`-512 \le i \le 511` + - :math:`- 1\,048\,576 \le i \le 1\,048\,575` + - :math:`-512 \le i \le 511` -* total atom count = 2\^31 atoms (about 2 billion) -* total timesteps = 2\^31 (about 2 billion) -* atom IDs = 2\^31 (about 2 billion) -* image flags = roll over at 512 (2\^9) +The "bigbig" setting increases the size of image flags and atom IDs over +"smallbig" and the "smallsmall" setting is only needed if your machine +does not support 64-bit integers or incurs performance penalties when +using them. + +These are limits for the core of the LAMMPS code, specific features or +some styles may impose additional limits. The :ref:`USER-ATC +` package cannot be compiled with the "bigbig" setting. +Also, there are limitations when using the library interface where some +functions with known issues have been replaced by dummy calls printing a +corresponding error message rather than crashing randomly or corrupting +data. Atom IDs are not required for atomic systems which do not store bond topology information, though IDs are enabled by default. The :doc:`atom_modify id no ` command will turn them off. Atom IDs are required for molecular systems with bond topology (bonds, -angles, dihedrals, etc). Thus if you model a molecular system with -more than 2 billion atoms, you need the "bigbig" setting. +angles, dihedrals, etc). Similarly, some force or compute or fix styles +require atom IDs. Thus if you model a molecular system or use one of +those styles with more than 2 billion atoms, you need the "bigbig" +setting. -Image flags store 3 values per atom which count the number of times an -atom has moved through the periodic box in each dimension. See the -:doc:`dump ` doc page for a discussion. If an atom moves through -the periodic box more than this limit, the value 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 ` command, to be faulty. +Regardless of the total system size limits, the maximum number of atoms +per MPI rank (local + ghost atoms) is limited to 2 billion for atomic +systems and 500 million for systems with bonds (the additional +restriction is due to using the 2 upper bits of the local atom index +in neighbor lists for storing special bonds info). + +Image flags store 3 values per atom in a single integer which count the +number of times an atom has moved through the periodic box in each +dimension. See the :doc:`dump ` doc page for a discussion. If an +atom moves through the periodic box more than this limit, the value 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 +` command, to be faulty. -Note that the USER-ATC package and the USER-INTEL package are currently -not compatible with the "bigbig" setting. Also, there are limitations -when using the library interface. Some functions with known issues -have been replaced by dummy calls printing a corresponding error rather -than crashing randomly or corrupting data. Also note that the GPU package requires its lib/gpu library to be compiled with the same size setting, or the link will fail. A CMake @@ -265,54 +290,51 @@ PNG image files. Likewise the :doc:`dump movie ` command outputs movie files in MPEG format. Using these options requires the following settings: -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D WITH_JPEG=value # yes or no - # default = yes if CMake finds JPEG files, else no - -D WITH_PNG=value # yes or no - # default = yes if CMake finds PNG and ZLIB files, else no - -D WITH_FFMPEG=value # yes or no - # default = yes if CMake can find ffmpeg, else no + .. code-block:: bash -Usually these settings are all that is needed. If CMake cannot find -the graphics header, library, executable files, you can set these -variables: + -D WITH_JPEG=value # yes or no + # default = yes if CMake finds JPEG files, else no + -D WITH_PNG=value # yes or no + # default = yes if CMake finds PNG and ZLIB files, else no + -D WITH_FFMPEG=value # yes or no + # default = yes if CMake can find ffmpeg, else no -.. code-block:: bash + Usually these settings are all that is needed. If CMake cannot + find the graphics header, library, executable files, you can set + these variables: - -D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file - -D JPEG_LIBRARY=path # path to libjpeg.a (.so) file - -D PNG_INCLUDE_DIR=path # path to png.h header file - -D PNG_LIBRARY=path # path to libpng.a (.so) file - -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file - -D ZLIB_LIBRARY=path # path to libz.a (.so) file - -D FFMPEG_EXECUTABLE=path # path to ffmpeg executable + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file + -D JPEG_LIBRARY=path # path to libjpeg.a (.so) file + -D PNG_INCLUDE_DIR=path # path to png.h header file + -D PNG_LIBRARY=path # path to libpng.a (.so) file + -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file + -D ZLIB_LIBRARY=path # path to libz.a (.so) file + -D FFMPEG_EXECUTABLE=path # path to ffmpeg executable -.. code-block:: make + .. tab:: Traditional make - LMP_INC = -DLAMMPS_JPEG - LMP_INC = -DLAMMPS_PNG - LMP_INC = -DLAMMPS_FFMPEG + .. code-block:: make - JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them - JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them - JPG_LIB = -ljpeg -lpng -lz # library names + LMP_INC = -DLAMMPS_JPEG + LMP_INC = -DLAMMPS_PNG + LMP_INC = -DLAMMPS_FFMPEG -As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, -if make can find the graphics header and library files. You must -specify ``JPG_LIB`` -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, -that is a directory in your PATH environment variable. + JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them + JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them + JPG_LIB = -ljpeg -lpng -lz # library names -CMake and make info -^^^^^^^^^^^^^^^^^^^ + As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, + if make can find the graphics header and library files. You must + specify ``JPG_LIB`` 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, that is a directory in your PATH + environment variable. Using ``ffmpeg`` to output movie files requires that your machine supports the "popen" function in the standard runtime library. @@ -335,37 +357,34 @@ If this option is enabled, large files can be read or written with gzip compression by several LAMMPS commands, including :doc:`read_data `, :doc:`rerun `, and :doc:`dump `. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D WITH_GZIP=value # yes or no - # default is yes if CMake can find gzip, else no - -D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D WITH_GZIP=value # yes or no + # default is yes if CMake can find gzip, else no + -D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it -.. code-block:: make + .. tab:: Traditional make - LMP_INC = -DLAMMPS_GZIP + .. code-block:: make -CMake and make info -^^^^^^^^^^^^^^^^^^^ + LMP_INC = -DLAMMPS_GZIP -This option requires that your machine supports the "popen()" function -in the standard runtime library and that a gzip executable can be +This option requires that your operating system fully supports the "popen()" +function in the standard runtime library and that a ``gzip`` executable can be found by LAMMPS during a run. .. note:: - On some clusters with high-speed networks, using the fork() - library call (required by popen()) can interfere with the fast - communication library and lead to simulations using compressed output - or input to hang or crash. For selected operations, compressed file - I/O is also available using a compression library instead, which is - what the :ref:`COMPRESS package ` enables. + On some clusters with high-speed networks, using the "fork()" library + call (required by "popen()") can interfere with the fast communication + library and lead to simulations using compressed output or input to + hang or crash. For selected operations, compressed file I/O is also + available using a compression library instead, which is what the + :ref:`COMPRESS package ` enables. ---------- @@ -374,65 +393,66 @@ found by LAMMPS during a run. Memory allocation alignment --------------------------------------- -This setting enables the use of the posix_memalign() call instead of -malloc() when LAMMPS allocates large chunks or memory. This can make -vector instructions on CPUs more efficient, if dynamically allocated -memory is aligned on larger-than-default byte boundaries. -On most current systems, the malloc() implementation returns +This setting enables the use of the "posix_memalign()" call instead of +"malloc()" when LAMMPS allocates large chunks or memory. Vector +instructions on CPUs may become more efficient, if dynamically allocated +memory is aligned on larger-than-default byte boundaries. On most +current operating systems, the "malloc()" implementation returns pointers that are aligned to 16-byte boundaries. Using SSE vector -instructions efficiently, however, requires memory blocks being -aligned on 64-byte boundaries. +instructions efficiently, however, requires memory blocks being aligned +on 64-byte boundaries. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default) + .. code-block:: bash -Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using posix_memalign() -and revert to using the malloc() C-library function instead. When -compiling LAMMPS for Windows systems, malloc() will always be used -and this setting ignored. + -D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default) -Traditional make -^^^^^^^^^^^^^^^^ + Use a ``LAMMPS_MEMALIGN`` value of 0 to disable using + "posix_memalign()" and revert to using the "malloc()" C-library + function instead. When compiling LAMMPS for Windows systems, + "malloc()" will always be used and this setting is ignored. -.. code-block:: make + .. tab:: Traditional make - LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 + .. code-block:: make -Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory allocated -with the malloc() function call instead. ``-DLAMMPS_MEMALIGN`` **cannot** -be used on Windows, as it does use different function calls for -allocating aligned memory, that are not compatible with how LAMMPS -manages its dynamical memory. + LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 + + Do not set ``-DLAMMPS_MEMALIGN``, if you want to have memory + allocated with the "malloc()" function call + instead. ``-DLAMMPS_MEMALIGN`` **cannot** be used on Windows, as + Windows different function calls with different semantics for + allocating aligned memory, that are not compatible with how LAMMPS + manages its dynamical memory. ---------- .. _longlong: Workaround for long long integers ------------------------------------------------- +--------------------------------- If your system or MPI version does not recognize "long long" data 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 those systems: -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) -.. code-block:: make + .. tab:: Traditional make - LMP_INC = -DLAMMPS_LONGLONG_TO_LONG + .. code-block:: make + + LMP_INC = -DLAMMPS_LONGLONG_TO_LONG ---------- @@ -447,19 +467,19 @@ 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 *catch* exceptions thrown from within LAMMPS. -CMake build -^^^^^^^^^^^ +.. tabs:: -.. code-block:: bash + .. tab:: CMake build - -D LAMMPS_EXCEPTIONS=value # yes or no (default) + .. code-block:: bash -Traditional make -^^^^^^^^^^^^^^^^ + -D LAMMPS_EXCEPTIONS=value # yes or no (default) -.. code-block:: make + .. tab:: Traditional make - LMP_INC = -DLAMMPS_EXCEPTIONS + .. code-block:: make + + LMP_INC = -DLAMMPS_EXCEPTIONS .. note:: diff --git a/doc/src/_ext/tab_or_note.py b/doc/src/_ext/tab_or_note.py new file mode 100644 index 0000000000..40a27deca5 --- /dev/null +++ b/doc/src/_ext/tab_or_note.py @@ -0,0 +1,15 @@ + +def replace_tabs_handler(app, docname, source): + """ When builder is not 'html', remove 'tabs' directive + and replace any 'tab' directive with 'admonition'""" + if app.builder.name != 'html': + for i in range(len(source)): + source[i] = source[i].replace('.. tabs::','').replace('.. tab::','.. admonition::') + +def setup(app): + app.connect('source-read', replace_tabs_handler) + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/doc/utils/requirements.txt b/doc/utils/requirements.txt index 2312037b5c..e025e23b09 100644 --- a/doc/utils/requirements.txt +++ b/doc/utils/requirements.txt @@ -1,5 +1,6 @@ Sphinx sphinxcontrib-spelling git+https://github.com/akohlmey/sphinx-fortran@parallel-read +sphinx_tabs breathe Pygments diff --git a/doc/utils/sphinx-config/conf.py.in b/doc/utils/sphinx-config/conf.py.in index c6b161ee14..23168bf080 100644 --- a/doc/utils/sphinx-config/conf.py.in +++ b/doc/utils/sphinx-config/conf.py.in @@ -47,7 +47,9 @@ extensions = [ 'sphinx.ext.imgmath', 'sphinx.ext.autodoc', 'sphinxfortran.fortran_domain', + 'sphinx_tabs.tabs', 'table_from_list', + 'tab_or_note', 'breathe', ] # 2017-12-07: commented out, since this package is broken with Sphinx 16.x diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 586e14da88..56ee6cb0bd 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -3460,6 +3460,7 @@ zz Zm PowerShell filesystems +Zstandard Zstd zstd checksum diff --git a/lib/compress/Makefile.lammps b/lib/compress/Makefile.lammps index 2d06990d82..c0a42443ba 100644 --- a/lib/compress/Makefile.lammps +++ b/lib/compress/Makefile.lammps @@ -1,21 +1,24 @@ # This file contains the settings to build and link LAMMPS with # support for data compression libraries. -# +# # When you build LAMMPS with the COMPRESS package installed, it will # use the 3 settings in this file. They should be set as follows. -# -# The compress_SYSLIB setting is for linking the compression library. -# By default, the setting will point to zlib (-lz). -# -# The compress_SYSINC and compress_SYSPATH variables do not typically need -# to be set, as compression libraries are usually installed as packages -# in system locations. Otherwise, specify its directory via the -# compress_SYSPATH variable, e.g. -Ldir or compress_SYSINC variable( -Idir) +# +# The compress_SYSLIB setting is for linking the compression libraries. +# By default, the setting will point to zlib (-lz). For including +# Zstandard support add -DLAMMPS_ZSTD to compress_SYSINC and also +# add -lzstd to compress_SYSLIB to link to the library. +# +# The compress_SYSINC and compress_SYSPATH variables typically do not +# need any additional settings, as compression libraries are usually +# installed as packages in system locations. Otherwise, specify its +# library directory via the compress_SYSPATH variable, e.g. -Ldir or +# its include directory via the compress_SYSINC variable( -Idir) # ----------------------------------------------------------- # Settings that the LAMMPS build will import when this package is installed -compress_SYSINC = -compress_SYSLIB = -lz +compress_SYSINC = # -DLAMMPS_ZSTD +compress_SYSLIB = -lz # -lzstd compress_SYSPATH =