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

docs: update build section

Browse Source
This commit is contained in:
Richard Berger
2024-08-14 00:42:30 -06:00
parent cf0bc0e6bb
commit e1a0cc29be
3 changed files with 82 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
doc/src/Build_basics.rst
View File

@ -37,8 +37,9 @@ standard. A more detailed discussion of that is below.
.. code-block:: bash .. code-block:: bash
-D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no -D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI
-D BUILD_OMP=value # yes or no, default is yes if a compatible compiler is detected -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 -D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc
# no default value # no default value
@ -74,7 +75,7 @@ standard. A more detailed discussion of that is below.
this is ``-fopenmp``\ , which can be added to the ``CC`` and this is ``-fopenmp``\ , which can be added to the ``CC`` and
``LINK`` makefile variables. ``LINK`` makefile variables.
For the serial build the following make variables are set (see src/MAKE/Makefile.serial): For the serial build the following make variables are set (see ``src/MAKE/Makefile.serial``):
.. code-block:: make .. code-block:: make
@ -231,24 +232,32 @@ LAMMPS.
.. code-block:: bash .. code-block:: bash
# Building with GNU Compilers: # Building with GNU Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ \
-DCMAKE_Fortran_COMPILER=gfortran ../cmake
# Building with Intel Compilers: # Building with Intel Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc \
-DCMAKE_Fortran_COMPILER=ifort ../cmake
# Building with Intel oneAPI Compilers: # Building with Intel oneAPI Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DCMAKE_Fortran_COMPILER=ifx cmake -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx \
-DCMAKE_Fortran_COMPILER=ifx ../cmake
# Building with LLVM/Clang Compilers: # Building with LLVM/Clang Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
-DCMAKE_Fortran_COMPILER=flang ../cmake
# Building with PGI/Nvidia Compilers: # Building with PGI/Nvidia Compilers:
cmake ../cmake -DCMAKE_C_COMPILER=pgcc -DCMAKE_CXX_COMPILER=pgc++ -DCMAKE_Fortran_COMPILER=pgfortran cmake -DCMAKE_C_COMPILER=pgcc -DCMAKE_CXX_COMPILER=pgc++ \
-DCMAKE_Fortran_COMPILER=pgfortran ../cmake
# Building with the NVHPC Compilers:
cmake -DCMAKE_C_COMPILER=nvc -DCMAKE_CXX_COMPILER=nvc++ \
-DCMAKE_Fortran_COMPILER=nvfortran ../cmake
For compiling with the Clang/LLVM compilers a CMake preset is For compiling with the Clang/LLVM compilers a CMake preset is
provided that can be loaded with provided that can be loaded with
`-C ../cmake/presets/clang.cmake`. Similarly, ``-C ../cmake/presets/clang.cmake``. Similarly,
`-C ../cmake/presets/intel.cmake` should switch the compiler ``-C ../cmake/presets/intel.cmake`` should switch the compiler
toolchain to the legacy Intel compilers, `-C ../cmake/presets/oneapi.cmake` toolchain to the legacy Intel compilers, ``-C ../cmake/presets/oneapi.cmake``
will switch to the LLVM based oneAPI Intel compilers, will switch to the LLVM based oneAPI Intel compilers,
and `-C ../cmake/presets/pgi.cmake` ``-C ../cmake/presets/pgi.cmake`` will switch the compiler to the PGI compilers,
will switch the compiler to the PGI compilers. and ``-C ../cmake/presets/nvhpc.cmake`` will switch to the NVHPC compilers.
Furthermore, you can set ``CMAKE_TUNE_FLAGS`` to specifically add Furthermore, you can set ``CMAKE_TUNE_FLAGS`` to specifically add
compiler flags to tune for optimal performance on given hosts. compiler flags to tune for optimal performance on given hosts.
@ -388,7 +397,8 @@ running LAMMPS from Python via its library interface.
make machine # build LAMMPS executable lmp_machine make machine # build LAMMPS executable lmp_machine
make mode=static machine # same as "make machine" make mode=static machine # same as "make machine"
make mode=shared machine # build LAMMPS shared lib liblammps_machine.so instead make mode=shared machine # build LAMMPS shared lib liblammps_machine.so
# instead
The "static" build will generate a static library called The "static" build will generate a static library called
``liblammps_machine.a`` and an executable named ``lmp_machine``\ , ``liblammps_machine.a`` and an executable named ``lmp_machine``\ ,
@ -450,7 +460,7 @@ installation.
Including or removing debug support Including or removing debug support
----------------------------------- -----------------------------------
By default the compilation settings will include the *-g* flag which By default the compilation settings will include the ``-g`` flag which
instructs the compiler to include debug information (e.g. which line of instructs the compiler to include debug information (e.g. which line of
source code a particular instruction correspond to). This can be source code a particular instruction correspond to). This can be
extremely useful in case LAMMPS crashes and can help to provide crucial extremely useful in case LAMMPS crashes and can help to provide crucial
@ -463,7 +473,7 @@ If this is a concern, you can change the compilation settings or remove
the debug information from the LAMMPS executable: the debug information from the LAMMPS executable:
- **Traditional make**: edit your ``Makefile.<machine>`` to remove the - **Traditional make**: edit your ``Makefile.<machine>`` to remove the
*-g* flag from the ``CCFLAGS`` and ``LINKFLAGS`` definitions ``-g`` flag from the ``CCFLAGS`` and ``LINKFLAGS`` definitions
- **CMake**: use ``-D CMAKE_BUILD_TYPE=Release`` or explicitly reset - **CMake**: use ``-D CMAKE_BUILD_TYPE=Release`` or explicitly reset
the applicable compiler flags (best done using the text mode or the applicable compiler flags (best done using the text mode or
graphical user interface). graphical user interface).
@ -488,7 +498,8 @@ using CMake or Make.
.. code-block:: bash .. code-block:: bash
-D BUILD_TOOLS=value # yes or no (default). Build binary2txt, chain.x, micelle2d.x, msi2lmp, phana, stl_bin2txt -D BUILD_TOOLS=value # yes or no (default). Build binary2txt, chain.x,
# micelle2d.x, msi2lmp, phana, stl_bin2txt
-D BUILD_LAMMPS_GUI=value # yes or no (default). Build LAMMPS-GUI -D BUILD_LAMMPS_GUI=value # yes or no (default). Build LAMMPS-GUI
The generated binaries will also become part of the LAMMPS installation The generated binaries will also become part of the LAMMPS installation

10
doc/src/Build_cmake.rst
View File

@ -131,17 +131,17 @@ file called ``CMakeLists.txt`` (for LAMMPS it is located in the
configuration step. The cache file contains all current CMake settings. configuration step. The cache file contains all current CMake settings.
To modify settings, enable or disable features, you need to set To modify settings, enable or disable features, you need to set
*variables* with either the *-D* command line flag (``-D *variables* with either the ``-D`` command line flag (``-D
VARIABLE1_NAME=value``) or change them in the text mode of the graphical VARIABLE1_NAME=value``) or change them in the text mode of the graphical
user interface. The *-D* flag can be used several times in one command. user interface. The ``-D`` flag can be used several times in one command.
For your convenience, we provide :ref:`CMake presets <cmake_presets>` For your convenience, we provide :ref:`CMake presets <cmake_presets>`
that combine multiple settings to enable optional LAMMPS packages or use that combine multiple settings to enable optional LAMMPS packages or use
a different compiler tool chain. Those are loaded with the *-C* flag a different compiler tool chain. Those are loaded with the ``-C`` flag
(``-C ../cmake/presets/basic.cmake``). This step would only be needed (``-C ../cmake/presets/basic.cmake``). This step would only be needed
once, as the settings from the preset files are stored in the once, as the settings from the preset files are stored in the
``CMakeCache.txt`` file. It is also possible to customize the build ``CMakeCache.txt`` file. It is also possible to customize the build
by adding one or more *-D* flags to the CMake command line. by adding one or more ``-D`` flags to the CMake command line.
Generating files for alternate build tools (e.g. Ninja) and project files Generating files for alternate build tools (e.g. Ninja) and project files
for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G* for IDEs like Eclipse, CodeBlocks, or Kate can be selected using the *-G*
@ -171,7 +171,7 @@ files. E.g. with:
In that case the resulting binaries are not in the build folder directly In that case the resulting binaries are not in the build folder directly
but in subdirectories corresponding to the build type (i.e. Release in but in subdirectories corresponding to the build type (i.e. Release in
the example from above). Similarly, for running unit tests the the example from above). Similarly, for running unit tests the
configuration is selected with the *-C* flag: configuration is selected with the ``-C`` flag:
.. code-block:: bash .. code-block:: bash

48
doc/src/Build_settings.rst
View File

@ -63,8 +63,10 @@ libraries and better pipelining for packing and communication.
.. code-block:: bash .. code-block:: bash
-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found,
-D FFT_KOKKOS=value # FFTW3 or MKL or KISS or CUFFT or HIPFFT, default is KISS # else KISS
-D FFT_KOKKOS=value # FFTW3 or MKL or KISS or CUFFT or HIPFFT,
# default is KISS
-D FFT_SINGLE=value # yes or no (default), no = double precision -D FFT_SINGLE=value # yes or no (default), no = double precision
-D FFT_PACK=value # array (default) or pointer or memcpy -D FFT_PACK=value # array (default) or pointer or memcpy
-D FFT_USE_HEFFTE=value # yes or no (default), yes links to heFFTe -D FFT_USE_HEFFTE=value # yes or no (default), yes links to heFFTe
@ -94,7 +96,8 @@ libraries and better pipelining for packing and communication.
-D MKL_INCLUDE_DIR=path # ditto for Intel MKL library -D MKL_INCLUDE_DIR=path # ditto for Intel MKL library
-D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries -D FFT_MKL_THREADS=on # enable using threaded FFTs with MKL libraries
-D MKL_LIBRARY=path # path to MKL libraries -D MKL_LIBRARY=path # path to MKL libraries
-D FFT_HEFFTE_BACKEND=value # FFTW or MKL or empty/undefined for the stock heFFTe back end -D FFT_HEFFTE_BACKEND=value # FFTW or MKL or empty/undefined for the stock
# heFFTe backend
-D Heffte_ROOT=path # path to an existing heFFTe installation -D Heffte_ROOT=path # path to an existing heFFTe installation
.. note:: .. note::
@ -113,7 +116,8 @@ libraries and better pipelining for packing and communication.
.. code-block:: make .. code-block:: make
FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3),
# -DFFT_MKL, or -DFFT_KISS
# default is KISS if not specified # default is KISS if not specified
FFT_INC = -DFFT_KOKKOS_CUFFT # -DFFT_KOKKOS_{FFTW,FFTW3,MKL,CUFFT,HIPFFT,KISS} FFT_INC = -DFFT_KOKKOS_CUFFT # -DFFT_KOKKOS_{FFTW,FFTW3,MKL,CUFFT,HIPFFT,KISS}
# default is KISS if not specified # default is KISS if not specified
@ -130,12 +134,13 @@ libraries and better pipelining for packing and communication.
FFT_LIB = -lhipfft # hipFFT either precision FFT_LIB = -lhipfft # hipFFT either precision
FFT_LIB = -lcufft # cuFFT either precision FFT_LIB = -lcufft # cuFFT either precision
FFT_LIB = -lfftw3 # FFTW3 double precision FFT_LIB = -lfftw3 # FFTW3 double precision
FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads (needs -DFFT_FFTW_THREADS) FFT_LIB = -lfftw3 -lfftw3_omp # FFTW3 double precision with threads
# (needs -DFFT_FFTW_THREADS)
FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision 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_intel_lp64 -lmkl_sequential -lmkl_core # serial MKL with Intel compiler,
FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compiler, serial interface FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # serial MKL with GNU compiler,
FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # MKL with Intel compiler, threaded interface FFT_LIB = -lmkl_intel_lp64 -lmkl_intel_thread -lmkl_core # threaded MKL with Intel compiler
FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # MKL with GNU compiler, threaded interface FFT_LIB = -lmkl_gf_lp64 -lmkl_gnu_thread -lmkl_core # threaded MKL with GNU compiler
FFT_LIB = -lmkl_rt # MKL with automatic runtime selection of interface libs 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 As with CMake, you do not need to set paths in ``FFT_INC`` or
@ -152,13 +157,13 @@ libraries and better pipelining for packing and communication.
FFT_PATH = FFT_PATH =
FFT_LIB = $(heffte_link) $(heffte_libs) FFT_LIB = $(heffte_link) $(heffte_libs)
The heFFTe install path will contain `HeffteMakefile.in`. The heFFTe install path will contain ``HeffteMakefile.in``.
which will define the `heffte_` include variables needed to link to heFFTe from which will define the ``heffte_`` include variables needed to link to heFFTe from
an external project using traditional make. an external project using traditional make.
The `-DFFT_HEFFTE` is required to switch to using heFFTe, while the optional `-DFFT_HEFFTE_FFTW` The ``-DFFT_HEFFTE`` is required to switch to using heFFTe, while the optional ``-DFFT_HEFFTE_FFTW``
selects the desired heFFTe back end, e.g., `-DFFT_HEFFTE_FFTW` or `-DFFT_HEFFTE_MKL`, selects the desired heFFTe backend, e.g., ``-DFFT_HEFFTE_FFTW`` or ``-DFFT_HEFFTE_MKL``,
omitting the variable will default to the `stock` back end. omitting the variable will default to the `stock` backend.
The heFFTe `stock` back end is intended to be used for testing and debugging, The heFFTe `stock` backend is intended to be used for testing and debugging,
but is not performance optimized for large scale production runs. but is not performance optimized for large scale production runs.
The `KISS FFT library <https://github.com/mborgerding/kissfft>`_ is The `KISS FFT library <https://github.com/mborgerding/kissfft>`_ is
@ -184,7 +189,7 @@ it from `www.fftw.org <https://www.fftw.org>`_. LAMMPS requires version
Building FFTW for your box should be as simple as ``./configure; make; Building FFTW for your box should be as simple as ``./configure; make;
make install``. The install command typically requires root privileges make install``. The install command typically requires root privileges
(e.g. invoke it via sudo), unless you specify a local directory with (e.g. invoke it via sudo), unless you specify a local directory with
the "--prefix" option of configure. Type ``./configure --help`` to see the ``--prefix`` option of configure. Type ``./configure --help`` to see
various options. various options.
The Intel MKL math library is part of the Intel compiler suite. It The Intel MKL math library is part of the Intel compiler suite. It
@ -363,7 +368,8 @@ requires the following settings:
-D WITH_JPEG=value # yes or no -D WITH_JPEG=value # yes or no
# default = yes if CMake finds JPEG development files, else no # default = yes if CMake finds JPEG development files, else no
-D WITH_PNG=value # yes or no -D WITH_PNG=value # yes or no
# default = yes if CMake finds PNG and ZLIB development files, else no # default = yes if CMake finds PNG and ZLIB development files,
# else no
-D WITH_FFMPEG=value # yes or no -D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no # default = yes if CMake can find ffmpeg, else no
@ -387,8 +393,10 @@ requires the following settings:
LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG <other LMP_INC settings> LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG <other LMP_INC settings>
JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h header files if make cannot find them JPG_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h headers
JPG_PATH = -L/usr/lib # paths to libjpeg.a, libpng.a, libz.a (.so) files if make cannot find them # 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 JPG_LIB = -ljpeg -lpng -lz # library names
As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``,
@ -429,7 +437,7 @@ including :doc:`read_data <read_data>`, :doc:`rerun <rerun>`, and
.. code-block:: bash .. code-block:: bash
-D WITH_GZIP=value # yes or no -D WITH_GZIP=value # yes or no
# default is yes if CMake can find the gzip program, else no # default is yes if CMake can find the gzip program
.. tab:: Traditional make .. tab:: Traditional make