diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 45678938ef..f01c32bda9 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -37,8 +37,9 @@ standard. A more detailed discussion of that is below. .. code-block:: bash - -D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no - -D BUILD_OMP=value # yes or no, default is yes if a compatible compiler is detected + -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 LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc # no default value @@ -54,9 +55,9 @@ standard. A more detailed discussion of that is below. .. code-block:: bash - 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 + 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 Any ``make machine`` command will look up the make settings from a file ``Makefile.machine`` in the folder ``src/MAKE`` or one of its @@ -74,15 +75,15 @@ standard. A more detailed discussion of that is below. this is ``-fopenmp``\ , which can be added to the ``CC`` and ``LINK`` makefile variables. - For the serial build the following make variables are set (see src/MAKE/Makefile.serial): + For the serial build the following make variables are set (see ``src/MAKE/Makefile.serial``): .. code-block:: make - CC = g++ - LINK = g++ - MPI_INC = -I../STUBS - MPI_PATH = -L../STUBS - MPI_LIB = -lmpi_stubs + CC = g++ + LINK = g++ + MPI_INC = -I../STUBS + MPI_PATH = -L../STUBS + MPI_LIB = -lmpi_stubs You also need to build the STUBS library for your platform before making LAMMPS itself. A ``make serial`` build does this for you @@ -231,24 +232,32 @@ LAMMPS. .. code-block:: bash # 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: - 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: - 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: - 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: - 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 provided that can be loaded with - `-C ../cmake/presets/clang.cmake`. Similarly, - `-C ../cmake/presets/intel.cmake` should switch the compiler - toolchain to the legacy Intel compilers, `-C ../cmake/presets/oneapi.cmake` + ``-C ../cmake/presets/clang.cmake``. Similarly, + ``-C ../cmake/presets/intel.cmake`` should switch the compiler + toolchain to the legacy Intel compilers, ``-C ../cmake/presets/oneapi.cmake`` will switch to the LLVM based oneAPI Intel compilers, - and `-C ../cmake/presets/pgi.cmake` - will switch the compiler to the PGI compilers. + ``-C ../cmake/presets/pgi.cmake`` 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 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 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 ``liblammps_machine.a`` and an executable named ``lmp_machine``\ , @@ -450,7 +460,7 @@ installation. 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 source code a particular instruction correspond to). This can be 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: - **Traditional make**: edit your ``Makefile.`` 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 the applicable compiler flags (best done using the text mode or graphical user interface). @@ -488,7 +498,8 @@ using CMake or Make. .. 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 The generated binaries will also become part of the LAMMPS installation diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst index e622f9f208..9768d7066c 100644 --- a/doc/src/Build_cmake.rst +++ b/doc/src/Build_cmake.rst @@ -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. 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 -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 ` 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 once, as the settings from the preset files are stored in the ``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 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 but in subdirectories corresponding to the build type (i.e. Release in 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 diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst index 2abe6c4678..a2dfa386f3 100644 --- a/doc/src/Build_settings.rst +++ b/doc/src/Build_settings.rst @@ -63,8 +63,10 @@ libraries and better pipelining for packing and communication. .. code-block:: bash - -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS - -D FFT_KOKKOS=value # FFTW3 or MKL or KISS or CUFFT or HIPFFT, default is KISS + -D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, + # 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_PACK=value # array (default) or pointer or memcpy -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 FFT_MKL_THREADS=on # enable using threaded FFTs with 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 .. note:: @@ -113,7 +116,8 @@ libraries and better pipelining for packing and communication. .. 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 FFT_INC = -DFFT_KOKKOS_CUFFT # -DFFT_KOKKOS_{FFTW,FFTW3,MKL,CUFFT,HIPFFT,KISS} # default is KISS if not specified @@ -125,18 +129,19 @@ libraries and better pipelining for packing and communication. .. code-block:: make - FFT_INC = -I/usr/local/include - FFT_PATH = -L/usr/local/lib - FFT_LIB = -lhipfft # hipFFT either precision - FFT_LIB = -lcufft # cuFFT either precision - 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 = -lhipfft # hipFFT either precision + FFT_LIB = -lcufft # cuFFT either precision + 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 # serial MKL with Intel compiler, + FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # serial MKL with GNU compiler, + 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 # threaded MKL with GNU compiler + 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 @@ -152,13 +157,13 @@ libraries and better pipelining for packing and communication. FFT_PATH = FFT_LIB = $(heffte_link) $(heffte_libs) - The heFFTe install path will contain `HeffteMakefile.in`. - which will define the `heffte_` include variables needed to link to heFFTe from + The heFFTe install path will contain ``HeffteMakefile.in``. + which will define the ``heffte_`` include variables needed to link to heFFTe from an external project using traditional make. - 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`, - omitting the variable will default to the `stock` back end. - The heFFTe `stock` back end is intended to be used for testing and debugging, + The ``-DFFT_HEFFTE`` is required to switch to using heFFTe, while the optional ``-DFFT_HEFFTE_FFTW`` + selects the desired heFFTe backend, e.g., ``-DFFT_HEFFTE_FFTW`` or ``-DFFT_HEFFTE_MKL``, + omitting the variable will default to the `stock` backend. + The heFFTe `stock` backend is intended to be used for testing and debugging, but is not performance optimized for large scale production runs. The `KISS FFT library `_ is @@ -184,7 +189,7 @@ it from `www.fftw.org `_. LAMMPS requires version Building FFTW for your box should be as simple as ``./configure; make; make install``. The install command typically requires root privileges (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. The Intel MKL math library is part of the Intel compiler suite. It @@ -360,12 +365,13 @@ requires the following settings: .. code-block:: bash - -D WITH_JPEG=value # yes or no - # default = yes if CMake finds JPEG development files, else no - -D WITH_PNG=value # yes or no - # default = yes if CMake finds PNG and ZLIB development files, else no - -D WITH_FFMPEG=value # yes or no - # default = yes if CMake can find ffmpeg, else no + -D WITH_JPEG=value # yes or no + # default = yes if CMake finds JPEG development files, else no + -D WITH_PNG=value # yes or no + # default = yes if CMake finds PNG and ZLIB development files, + # else no + -D WITH_FFMPEG=value # yes or no + # default = yes if CMake can find ffmpeg, else no Usually these settings are all that is needed. If CMake cannot find the graphics header, library, executable files, you can set @@ -387,8 +393,10 @@ requires the following settings: LMP_INC = -DLAMMPS_JPEG -DLAMMPS_PNG -DLAMMPS_FFMPEG - 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_INC = -I/usr/local/include # path to jpeglib.h, png.h, zlib.h headers + # 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 As with CMake, you do not need to set ``JPG_INC`` or ``JPG_PATH``, @@ -428,8 +436,8 @@ including :doc:`read_data `, :doc:`rerun `, and .. code-block:: bash - -D WITH_GZIP=value # yes or no - # default is yes if CMake can find the gzip program, else no + -D WITH_GZIP=value # yes or no + # default is yes if CMake can find the gzip program .. tab:: Traditional make