diff --git a/doc/.gitignore b/doc/.gitignore index 88679898a89e26d53d8a43f4d7a04a60260ecc93..ca450f00f929338bc7ec31a7024c7e5f1df60d5e 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -6,3 +6,5 @@ /LAMMPS.mobi /Manual.pdf /Developer.pdf +/doctrees +/docenv diff --git a/doc/Makefile b/doc/Makefile index a702d5d169f9582554e930e0962e475192af5b23..eceae88da648960adc554ddf674baf34270c1ab7 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,12 +1,12 @@ # Makefile for LAMMPS documentation SHELL = /bin/bash -SHA1 = $(shell echo ${USER}-${PWD} | python utils/sha1sum.py) -BUILDDIR = /tmp/lammps-docs-$(SHA1) -RSTDIR = $(BUILDDIR)/rst +BUILDDIR = ${CURDIR} +RSTDIR = $(BUILDDIR)/src +TXTDIR = $(BUILDDIR)/txt VENV = $(BUILDDIR)/docenv TXT2RST = $(VENV)/bin/txt2rst -ANCHORCHECK = $(VENV)/bin/doc_anchor_check +ANCHORCHECK = $(VENV)/bin/rst_anchor_check PYTHON = $(shell which python3) VIRTUALENV = virtualenv @@ -28,10 +28,10 @@ HAS_VIRTUALENV = YES endif SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocessing.cpu_count())') -SOURCES=$(filter-out $(wildcard src/lammps_commands*.txt) src/lammps_support.txt src/lammps_tutorials.txt,$(wildcard src/*.txt)) -OBJECTS=$(SOURCES:src/%.txt=$(RSTDIR)/%.rst) +SOURCES=$(filter-out $(wildcard $(TXTDIR)/lammps_commands*.txt) $(TXTDIR)/lammps_support.txt $(TXTDIR)/lammps_tutorials.txt,$(wildcard $(TXTDIR)/*.txt)) +OBJECTS=$(SOURCES:$(TXTDIR)/%.txt=$(RSTDIR)/%.rst) -.PHONY: help clean-all clean epub mobi html pdf old venv spelling anchor_check +.PHONY: help clean-all clean epub mobi rst html pdf venv spelling anchor_check # ------------------------------------------ @@ -39,37 +39,36 @@ help: @echo "Please use \`make ' where is one of" @echo " html create HTML doc pages in html dir" @echo " pdf create Developer.pdf and Manual.pdf in this dir" - @echo " old create old-style HTML doc pages and Manual.pdf in old dir" @echo " fetch fetch HTML and PDF files from LAMMPS web site" @echo " epub create ePUB format manual for e-book readers" @echo " mobi convert ePUB to MOBI format manual for e-book readers (e.g. Kindle)" @echo " (requires ebook-convert tool from calibre)" @echo " clean remove all intermediate RST files" @echo " clean-all reset the entire build environment" - @echo " txt2html build txt2html tool" @echo " anchor_check scan for duplicate anchor labels" @echo " spelling spell-check the manual" # ------------------------------------------ clean-all: clean - rm -rf $(BUILDDIR)/* utils/txt2html/txt2html.exe + rm -rf $(BUILDDIR)/docenv $(BUILDDIR)/doctrees clean: - rm -rf $(RSTDIR) html old epub latex + rm -rf html epub latex rm -rf spelling clean-spelling: rm -rf spelling +rst: clean $(OBJECTS) $(ANCHORCHECK) + html: $(OBJECTS) $(ANCHORCHECK) @(\ . $(VENV)/bin/activate ;\ - cp -r src/* $(RSTDIR)/ ;\ sphinx-build $(SPHINXEXTRA) -b html -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) html ;\ echo "############################################" ;\ - doc_anchor_check src/*.txt ;\ - env LC_ALL=C grep -n '[^ -~]' src/*.txt ;\ + rst_anchor_check src/*.rst ;\ + env LC_ALL=C grep -n '[^ -~]' $(RSTDIR)/*.rst ;\ echo "############################################" ;\ deactivate ;\ ) @@ -89,8 +88,7 @@ spelling: $(OBJECTS) utils/sphinx-config/false_positives.txt @(\ . $(VENV)/bin/activate ;\ pip install sphinxcontrib-spelling ;\ - cp -r src/* $(RSTDIR)/ ;\ - cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ;\ + cp utils/sphinx-config/false_positives.txt $(RSTDIR)/ ;\ sphinx-build -b spelling -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) spelling ;\ deactivate ;\ ) @@ -103,7 +101,6 @@ epub: $(OBJECTS) @cp src/JPG/*.* epub/JPG @(\ . $(VENV)/bin/activate ;\ - cp -r src/* $(RSTDIR)/ ;\ sphinx-build $(SPHINXEXTRA) -b epub -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) epub ;\ deactivate ;\ ) @@ -126,10 +123,9 @@ pdf: $(OBJECTS) $(ANCHORCHECK) ) @(\ . $(VENV)/bin/activate ;\ - cp -r src/* $(RSTDIR)/ ;\ sphinx-build $(SPHINXEXTRA) -b latex -c utils/sphinx-config -d $(BUILDDIR)/doctrees $(RSTDIR) latex ;\ echo "############################################" ;\ - doc_anchor_check src/*.txt ;\ + rst_anchor_check src/*.rst ;\ echo "############################################" ;\ deactivate ;\ ) @@ -155,27 +151,6 @@ pdf: $(OBJECTS) $(ANCHORCHECK) @rm -rf latex/USER/*/*.[sg]* @echo "Build finished. Manual.pdf and Developer.pdf are in this directory." -old: utils/txt2html/txt2html.exe - @rm -rf old - @mkdir old; mkdir old/Eqs; mkdir old/JPG; mkdir old/PDF - @cd src; ../utils/txt2html/txt2html.exe -b *.txt; \ - mv *.html ../old; \ - cp Eqs/*.jpg ../old/Eqs; \ - cp JPG/* ../old/JPG; \ - cp PDF/* ../old/PDF; - @( set -e;\ - cd src/Developer; \ - pdflatex developer; \ - pdflatex developer; \ - mv developer.pdf ../../old/Developer.pdf; \ - cd ../../old; \ - for s in `echo ../src/*.txt | sed -e 's,\.\./src/,,g' -e 's/ \(pairs\|bonds\|angles\|dihedrals\|impropers\|commands_list\|fixes\|computes\).txt/ /g' | sed -e 's,\.txt,\.html,g'` ; \ - do grep -q ^$$s ../src/lammps.book || \ - echo WARNING: doc file $$s missing in src/lammps.book; done; \ - htmldoc --batch ../src/lammps.book; \ - ) - - fetch: @rm -rf html_www Manual_www.pdf Developer_www.pdf @curl -s -o Manual_www.pdf http://lammps.sandia.gov/doc/Manual.pdf @@ -184,21 +159,16 @@ fetch: @tar xzf lammps-doc.tar.gz @rm -f lammps-doc.tar.gz -txt2html: utils/txt2html/txt2html.exe - anchor_check : $(ANCHORCHECK) @(\ . $(VENV)/bin/activate ;\ - doc_anchor_check src/*.txt ;\ + rst_anchor_check src/*.txt ;\ deactivate ;\ ) # ------------------------------------------ -utils/txt2html/txt2html.exe: utils/txt2html/txt2html.cpp - g++ -O -Wall -o $@ $< - -$(RSTDIR)/%.rst : src/%.txt $(TXT2RST) +$(RSTDIR)/%.rst : $(TXTDIR)/%.txt $(TXT2RST) @(\ mkdir -p $(RSTDIR) ; \ . $(VENV)/bin/activate ;\ diff --git a/doc/lammps.1 b/doc/lammps.1 index f332a8a54937f51c8bed7c7b3c6e01e43e38df87..ec31d19b740cf24dfff2bac5c8ecdf0e31a5a74d 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,4 +1,4 @@ -.TH LAMMPS "19 September 2019" "2019-09-19" +.TH LAMMPS "30 October 2019" "2019-10-30" .SH NAME .B LAMMPS \- Molecular Dynamics Simulator. diff --git a/doc/src/.gitignore b/doc/src/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..be126ab4aa080ebeff3bbe0079444df02cfb57cc --- /dev/null +++ b/doc/src/.gitignore @@ -0,0 +1,2 @@ +Eqs +JPG diff --git a/doc/src/Build.rst b/doc/src/Build.rst new file mode 100644 index 0000000000000000000000000000000000000000..2eba3ddd48cd580447c1f0e46ff843e7ebbc6796 --- /dev/null +++ b/doc/src/Build.rst @@ -0,0 +1,28 @@ +Build LAMMPS +************ + +LAMMPS can be built as an executable or library from source code via +either traditional makefiles (which may require manual editing) +for use with GNU make or gmake, or a build environment generated by CMake +(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an +alternative you can download a package with pre-built executables +as described on the :doc:`Install ` doc page. + + +.. toctree:: + :maxdepth: 1 + + Build_cmake + Build_make + Build_link + Build_basics + Build_settings + Build_package + Build_extras + Build_windows + Build_development + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst new file mode 100644 index 0000000000000000000000000000000000000000..cf77c81e692b0d4dd9440d94f6d54c0fbae42fdd --- /dev/null +++ b/doc/src/Build_basics.rst @@ -0,0 +1,437 @@ +Basic build options +=================== + +The following topics are covered on this page, for building both with +CMake and make: + +* :ref:`Serial vs parallel build ` +* :ref:`Choice of compiler and compile/link options ` +* :ref:`Build LAMMPS as an executable or a library ` +* :ref:`Build the LAMMPS documentation ` +* :ref:`Install LAMMPS after a build ` + + +---------- + + +.. _serial: + +Serial vs parallel build +------------------------------------- + +LAMMPS can be built to run in parallel using the ubiquitous `MPI (message-passing interface) `_ +library. Or it can built to run on a single processor (serial) +without MPI. It can also be built with support for OpenMP threading +(see more discussion below). + +**CMake variables**\ : + + +.. parsed-literal:: + + -D BUILD_MPI=value # yes or no, default is yes if CMake finds MPI, else no + -D BUILD_OMP=value # yes or no (default) + -D LAMMPS_MACHINE=name # name = mpi, serial, mybox, titan, laptop, etc + # no default value + +The executable created by CMake (after running make) is lmp\_name. If +the LAMMPS\_MACHINE variable is not specified, the executable is just +lmp. Using BUILD\_MPI=no will produce a serial executable. + +**Traditional make**\ : + + +.. parsed-literal:: + + cd lammps/src + make mpi # parallel build, produces lmp_mpi using Makefile.mpi + make serial # serial build, produces lmp_serial using Makefile/serial + make mybox # uses Makefile.mybox to produce lmp_mybox + +Serial build (see src/MAKE/Makefile.serial): + + +.. parsed-literal:: + + MPI_INC = -I../STUBS + MPI_PATH = -L../STUBS + MPI_LIB = -lmpi_stubs + +For a parallel build, if MPI is installed on your system in the usual +place (e.g. under /usr/local), you do not need to specify the 3 +variables MPI\_INC, MPI\_PATH, MPI\_LIB. The MPI wrapper on the compiler +(e.g. mpicxx, mpiCC) knows where to find the needed include and +library files. Failing this, these 3 variables can be used to specify +where the mpi.h file (MPI\_INC), and the MPI library files (MPI\_PATH) +are found, and the name of the library files (MPI\_LIB). + +For a serial build, you need to specify the 3 variables, as shown +above. + +For a serial LAMMPS build, use the dummy MPI library provided in +src/STUBS. You also need to build the STUBS library for your platform +before making LAMMPS itself. A "make serial" build does this for. +Otherwise, type "make mpi-stubs" from the src directory, or "make" +from the src/STUBS dir. If the build fails, you will need to edit the +STUBS/Makefile for your platform. + +The file STUBS/mpi.c provides a CPU timer function called MPI\_Wtime() +that calls gettimeofday() . If your system doesn't support +gettimeofday() , you'll need to insert code to call another timer. +Note that the ANSI-standard function clock() rolls over after an hour +or so, and is therefore insufficient for timing long LAMMPS +simulations. + +**CMake and make info**\ : + +If you are installing MPI yourself, we recommend MPICH2 from Argonne +National Laboratory or OpenMPI. MPICH can be downloaded from the +`Argonne MPI site `_. +OpenMPI can be downloaded from the `OpenMPI site `_. Other MPI packages should also work. +If you are running on a large parallel machine, your system admins or +the vendor should have already installed a version of MPI, which is +likely to be faster than a self-installed MPICH or OpenMPI, so find +out how to build and link with it. + +The majority of OpenMP (threading) support in LAMMPS is provided by +the USER-OMP package; see the :doc:`Speed omp ` doc page for +details. The USER-INTEL package also provides OpenMP support (it is +compatible with USER-OMP) and adds vectorization support when compiled +with the Intel compilers on top of that. Also, the KOKKOS package can +be compiled for using OpenMP threading. + +However, there are a few commands in LAMMPS that have native OpenMP +support. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and +USER-DPD packages. In addition some packages support OpenMP threading +indirectly through the libraries they interface to: e.g. LATTE and +USER-COLVARS. See the :doc:`Packages details ` doc +page for more info on these packages and the doc pages for their +respective commands for OpenMP threading info. + +For CMake, if you use BUILD\_OMP=yes, you can use these packages and +turn on their native OpenMP support and turn on their native OpenMP +support at run time, by setting the OMP\_NUM\_THREADS environment +variable before you launch LAMMPS. + +For building via conventional make, the CCFLAGS and LINKFLAGS +variables in Makefile.machine need to include the compiler flag that +enables OpenMP. For GNU compilers it is -fopenmp. For (recent) Intel +compilers it is -qopenmp. If you are using a different compiler, +please refer to its documentation. + +.. _default-none-issues: + +**OpenMP Compiler compatibility info**\ : + +Some compilers do not fully support the 'default(none)' directive +and others (e.g. GCC version 9 and beyond) may implement OpenMP 4.0 +semantics, which are incompatible with the OpenMP 3.1 directives used +in LAMMPS (for maximal compatibility with compiler versions in use). +In those case, all 'default(none)' directives (which aid in detecting +incorrect and unwanted sharing) can be replaced with 'default(shared)' +while dropping all 'shared()' directives. The script +'src/USER-OMP/hack\_openmp\_for\_pgi\_gcc9.sh' can be used to automate +this conversion. + + +---------- + + +.. _compile: + +Choice of compiler and compile/link options +--------------------------------------------------------- + +The choice of compiler and compiler flags can be important for +performance. Vendor compilers can produce faster code than +open-source compilers like GNU. On boxes with Intel CPUs, we suggest +trying the `Intel C++ compiler `_. + +.. _intel: https://software.intel.com/en-us/intel-compilers + + + +On parallel clusters or supercomputers which use "modules" for their +compile/link environments, you can often access different compilers by +simply loading the appropriate module before building LAMMPS. + +**CMake variables**\ : + + +.. parsed-literal:: + + -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 + + -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 + +By default CMake will use a compiler it finds and it will add +optimization flags appropriate to that compiler and any :doc:`accelerator packages ` you have included in the build. + +You can tell CMake to look for a specific compiler with these variable +settings. Likewise you can specify the FLAGS variables if you want to +experiment with alternate optimization flags. You should specify all +3 compilers, so that the small number of LAMMPS source files written +in C or Fortran are built with a compiler consistent with the one used +for all the C++ files: + + +.. parsed-literal:: + + 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 + +.. note:: + + When the cmake command completes, it prints info to the screen + as to which compilers it is using, and what flags will be used in 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 will be listed in the CMake output. You should check to insure + you are using the compiler and optimization flags are the ones you + want. + +**Makefile.machine settings**\ : + +Parallel build (see src/MAKE/Makefile.mpi): + + +.. parsed-literal:: + + CC = mpicxx + CCFLAGS = -g -O3 + LINK = mpicxx + LINKFLAGS = -g -O + +Serial build (see src/MAKE/Makefile.serial): + + +.. parsed-literal:: + + CC = g++ + CCFLAGS = -g -O3 + LINK = g++ + LINKFLAGS = -g -O + +The "compiler/linker settings" section of a Makefile.machine lists +compiler and linker settings for your C++ compiler, including +optimization flags. You should always use mpicxx or mpiCC for +a parallel build, since these compiler wrappers will include +a variety of settings appropriate for your MPI installation. + +.. note:: + + If you build LAMMPS with any :doc:`accelerator packages ` included, they have specific + optimization flags that are either required or recommended for optimal + performance. You need to include these in the CCFLAGS and LINKFLAGS + settings above. For details, see the individual package doc pages + listed on the :doc:`Speed packages ` doc page. Or + examine these files in the src/MAKE/OPTIONS directory. They + correspond to each of the 5 accelerator packages and their hardware + variants: + + +.. parsed-literal:: + + 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) + + +---------- + + +.. _exe: + +Build LAMMPS as an executable or a library +---------------------------------------------------- + +LAMMPS can be built as either an executable or as a static or shared +library. The LAMMPS library can be called from another application or +a scripting language. See the :doc:`Howto couple ` doc +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 variables**\ : + + +.. parsed-literal:: + + -D BUILD_EXE=value # yes (default) or no + -D BUILD_LIB=value # yes or no (default) + -D BUILD_SHARED_LIBS=value # yes or no (default) + -D LAMMPS_LIB_SUFFIX=name # name = mpi, serial, mybox, titan, laptop, etc + # no default value + +Setting BUILD\_EXE=no will not produce an executable. Setting +BUILD\_LIB=yes will produce a static library named liblammps.a. +Setting both BUILD\_LIB=yes and BUILD\_SHARED\_LIBS=yes will produce a +shared library named liblammps.so. If LAMMPS\_LIB\_SUFFIX is set the generated +libraries will be named liblammps\_name.a or liblammps\_name.so instead. + +**Traditional make**\ : + + +.. parsed-literal:: + + cd lammps/src + make machine # build LAMMPS executable lmp_machine + make mode=lib machine # build LAMMPS static lib liblammps_machine.a + make mode=shlib machine # build LAMMPS shared lib liblammps_machine.so + +The two library builds also create generic soft links, named +liblammps.a and liblammps.so, which point to the liblammps\_machine +files. + +**CMake and make info**\ : + +Note that for a shared library to be usable by a calling program, all +the auxiliary libraries it depends on must also exist as shared +libraries. This will be the case for libraries included with LAMMPS, +such as the dummy MPI library in src/STUBS or any package libraries in +the lib/packages directory, since they are always built as shared +libraries using the -fPIC switch. However, if a library like MPI or +FFTW does not exist as a shared library, the shared library build will +generate an error. This means you will need to install a shared +library version of the auxiliary library. The build instructions for +the library should tell you how to do this. + +As an example, here is how to build and install the `MPICH library `_, a popular open-source version of MPI, distributed by +Argonne National Lab, as a shared library in the default +/usr/local/lib location: + +.. _mpich: http://www-unix.mcs.anl.gov/mpi + + + + +.. parsed-literal:: + + ./configure --enable-shared + make + make install + +You may need to use "sudo make install" in place of the last line if +you do not have write privileges for /usr/local/lib. The end result +should be the file /usr/local/lib/libmpich.so. + + +---------- + + +.. _doc: + +Build the LAMMPS documentation +---------------------------------------- + +**CMake variable**\ : + + +.. parsed-literal:: + + -D BUILD_DOC=value # yes or no (default) + +This will create the HTML doc pages within the CMake build directory. +The reason to do this is if you want to "install" LAMMPS on a system +after the CMake build via "make install", and include the doc pages in +the install. + +**Traditional make**\ : + + +.. parsed-literal:: + + cd lammps/doc + make html # html doc pages + make pdf # single Manual.pdf file + +This will create a lammps/doc/html dir with the HTML doc pages so that +you can browse them locally on your system. Type "make" from the +lammps/doc dir to see other options. + +.. note:: + + You can also download a tarball of the documentation for the + current LAMMPS version (HTML and PDF files), from the website + `download page `_. + + +---------- + + +.. _tools: + +Build LAMMPS tools +------------------------------ + +Some tools described in :doc:`Auxiliary tools ` can be built directly +using CMake or Make. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D BUILD_TOOLS=value # yes or no (default) + +The generated binaries will also become part of the LAMMPS installation (see below) + +**Traditional make**\ : + + +.. parsed-literal:: + + 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 + + +---------- + + +.. _install: + +Install LAMMPS after a build +------------------------------------------ + +After building LAMMPS, you may wish to copy the LAMMPS executable of +library, along with other LAMMPS files (library header, doc files) to +a globally visible place on your system, for others to access. Note +that you may need super-user privileges (e.g. sudo) if the directory +you want to copy files to is protected. + +**CMake variable**\ : + + +.. parsed-literal:: + + cmake -D CMAKE_INSTALL_PREFIX=path [options ...] ../cmake + make # perform make after CMake command + make install # perform the installation into prefix + +**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. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_cmake.rst b/doc/src/Build_cmake.rst new file mode 100644 index 0000000000000000000000000000000000000000..78459bb9906e07bdddc48b330fe48c7b12d1ec91 --- /dev/null +++ b/doc/src/Build_cmake.rst @@ -0,0 +1,245 @@ +Build LAMMPS with CMake +======================= + +This page is a short summary of how to use CMake to build LAMMPS. +Details on CMake variables that enable specific LAMMPS build options +are given on the pages linked to from the :doc:`Build ` doc page. + +Richard Berger (Temple U) has also written a `more comprehensive guide `_ +for how to use CMake to build LAMMPS. If you are new to CMake it is a +good place to start. + + +---------- + + +Building LAMMPS with CMake is a two-step process. First you use CMake +to create a build environment in a new directory. On Linux systems, +this will be based on makefiles for use with make. Then you use the +make command to build LAMMPS, which uses the created +Makefile(s). Example: + + +.. parsed-literal:: + + cd lammps # change to the LAMMPS distribution directory + mkdir build; cd build # create a new directory (folder) for build + cmake [options ...] ../cmake # configuration with (command-line) cmake + make # compilation + +The cmake command will detect available features, enable selected +packages and options, and will generate the build environment. By default +this build environment will be created for "Unix Makefiles" on most +platforms and particularly on Linux. However, alternate build tools +(e.g. Ninja) and support files for Integrated Development Environments +(IDE) like Eclipse, CodeBlocks, or Kate can be generated, too. This is +selected via the "-G" command line flag. For the rest of the documentation +we will assume that the build environment is generated for makefiles +and thus the make command will be used to compile and link LAMMPS as +indicated above, producing (by default) an executable called "lmp" and +a library called "liblammps.a" in the "build" folder. When generating +a build environment for the "Ninja" build tool, the build command would +be "ninja" instead of "make". + +If your machine has multiple CPU cores (most do these days), using a +command like "make -jN" (with N being the number of available local +CPU cores) can be much faster. If you plan to do development on +LAMMPS or need to re-compile LAMMPS repeatedly, installation of the +ccache (= Compiler Cache) software may speed up repeated compilation +even more. + +After compilation, you may optionally install the LAMMPS executable into +your system with: + + +.. parsed-literal:: + + make install # optional, copy LAMMPS executable & library elsewhere + +This will install the lammps executable and library (if requested), some +tools (if configured) and additional files like library API headers, +manpages, potential and force field files. The location of the installation +tree is set by the CMake variable "CMAKE\_INSTALL\_PREFIX" which defaults +to ${HOME}/.local + + +---------- + + +There are 3 variants of CMake: a command-line version (cmake), a text mode +UI version (ccmake), and a graphical GUI version (cmake-GUI). You can use +any of them interchangeably to configure and create the LAMMPS build +environment. On Linux all the versions produce a Makefile as their +output. See more details on each below. + +You can specify a variety of options with any of the 3 versions, which +affect how the build is performed and what is included in the LAMMPS +executable. Links to pages explaining all the options are listed on +the :doc:`Build ` doc page. + +You must perform the CMake build system generation and compilation in +a new directory you create. It can be anywhere on your local machine. +In these Build pages we assume that you are building in a directory +called "lammps/build". You can perform separate builds independently +with different options, so long as you perform each of them in a +separate directory you create. All the auxiliary files created by one +build process (executable, object files, log files, etc) are stored in +this directory or sub-directories within it that CMake creates. + +.. note:: + + To perform a CMake build, no packages can be installed or a + build been previously attempted in the LAMMPS src directory by using + "make" commands to :doc:`perform a conventional LAMMPS build `. CMake detects if this is the case and + generates an error, telling you to type "make no-all purge" in the src + directory to un-install all packages. The purge removes all the \*.h + files auto-generated by make. + +You must have CMake version 2.8 or later on your system to build +LAMMPS. A handful of LAMMPS packages (KOKKOS, LATTE, MSCG) require a +later version. CMake will print a message telling you if a later +version is required. Installation instructions for CMake are below. + +After the initial build, if you edit LAMMPS source files, or add your +own new files to the source directory, you can just re-type make from +your build directory and it will re-compile only the files that have +changed. If you want to change CMake options you can run cmake (or +ccmake or cmake-gui) again from the same build directory and alter +various options; see details below. Or you can remove the entire build +folder, recreate the directory and start over. + + +---------- + + +**Command-line version of CMake**\ : + + +.. parsed-literal:: + + cmake [options ...] /path/to/lammps/cmake # build from any dir + cmake [options ...] ../cmake # build from lammps/build + +The cmake command takes one required argument, which is the LAMMPS +cmake directory which contains the CMakeLists.txt file. + +The argument can be preceeded or followed by various CMake +command-line options. Several useful ones are: + + +.. parsed-literal:: + + -D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired + -D CMAKE_BUILD_TYPE=type # type = RelWithDebInfo (default), Release, MinSizeRel, or Debug + -G output # style of output CMake generates + -DVARIABLE=value # setting for a LAMMPS feature to enable + -D VARIABLE=value # ditto, but cannot come after CMakeLists.txt dir + -C path/to/preset/file # load some CMake settings before configuring + +All the LAMMPS-specific -D variables that a LAMMPS build supports are +described on the pages linked to from the :doc:`Build ` doc page. +All of these variable names are upper-case and their values are +lower-case, e.g. -D LAMMPS\_SIZES=smallbig. For boolean values, any of +these forms can be used: yes/no, on/off, 1/0. + +On Unix/Linux machines, CMake generates a Makefile by default to +perform the LAMMPS build. Alternate forms of build info can be +generated via the -G switch, e.g. Visual Studio on a Windows machine, +Xcode on MacOS, or KDevelop on Linux. Type "cmake --help" to see the +"Generator" styles of output your system supports. + +.. note:: + + When CMake runs, it prints configuration info to the screen. + You should review this to verify all the features you requested were + enabled, including packages. You can also see what compilers and + compile options will be used for the build. Any errors in CMake + variable syntax will also be flagged, e.g. mis-typed variable names or + variable values. + +CMake creates a CMakeCache.txt file when it runs. This stores all the +settings, so that when running CMake again you can use the current +folder '.' instead of the path to the LAMMPS cmake folder as the +required argument to the CMake command. Either way the existing +settings will be inherited unless the CMakeCache.txt file is removed. + +If you later want to change a setting you can rerun cmake in the build +directory with different setting. Please note that some automatically +detected variables will not change their value when you rerun cmake. +In these cases it is usually better to first remove all the +files/directories in the build directory, or start with a fresh build +directory. + + +---------- + + +**Curses version (terminal-style menu) of CMake**\ : + + +.. parsed-literal:: + + ccmake ../cmake + +You initiate the configuration and build environment generation steps +separately. For the first you have to type **c**\ , for the second you +have to type **g**\ . You may need to type **c** multiple times, and may be +required to edit some of the entries of CMake configuration variables +in between. Please see the `ccmake manual `_ for +more information. + + +---------- + + +**GUI version of CMake**\ : + + +.. parsed-literal:: + + cmake-gui ../cmake + +You initiate the configuration and build environment generation steps +separately. For the first you have to click on the **Configure** button, +for the second you have to click on the **Generate** button. You may +need to click on **Configure** multiple times, and may be required to +edit some of the entries of CMake configuration variables in between. +Please see the `cmake-gui manual `_ +for more information. + + +---------- + + +**Installing CMake** + +Check if your machine already has CMake installed: + + +.. parsed-literal:: + + which cmake # do you have it? + which cmake3 # version 3 may have this name + cmake --version # what specific version you have + +On clusters or supercomputers which use environment modules to manage +software packages, do this: + + +.. parsed-literal:: + + module list # is a cmake module already loaded? + module avail # is a cmake module available? + module load cmake3 # load cmake module with appropriate name + +Most Linux distributions offer pre-compiled cmake packages through +their package management system. If you do not have CMake or a new +enough version, you can download the latest version at +`https://cmake.org/download/ `_. +Instructions on how to install it on various platforms can be found +`on this page `_. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst new file mode 100644 index 0000000000000000000000000000000000000000..7286caf7b3be0b8d21cd9e839cfc456d7fe4e9ff --- /dev/null +++ b/doc/src/Build_development.rst @@ -0,0 +1,120 @@ +Development build options (CMake only) +====================================== + +The CMake build of LAMMPS has a few extra options which are useful during +development, testing or debugging. + + +---------- + + +.. _compilation: + +Verify compilation flags +------------------------------------------ + +Sometimes it is necessary to verify the complete sequence of compilation flags +generated by the CMake build. To enable a more verbose output during +compilation you can use the following option. + + +.. parsed-literal:: + + -D CMAKE_VERBOSE_MAKEFILE=value # value = no (default) or yes + +Another way of doing this without reconfiguration is calling make with variable VERBOSE set to 1: + + +.. parsed-literal:: + + make VERBOSE=1 + + +---------- + + +.. _sanitizer: + +Address, Undefined Behavior, and Thread Sanitizer Support +------------------------------------------------------------------------- + +Compilers such as GCC and Clang support generating binaries which use different +sanitizers to detect problems in code during run-time. They can detect `memory leaks `_, +code that runs into `undefined behavior `_ of the +language and `data races `_ in threaded code. + +The following settings allow you enable these features if your compiler supports +it. Please note that they come with a performance hit. However, they are +usually faster than using tools like Valgrind. + + +.. parsed-literal:: + + -D ENABLE_SANITIZE_ADDRESS=value # enable Address Sanitizer, value = no (default) or yes + -D ENABLE_SANITIZE_UNDEFINED=value # enable Undefined Behaviour Sanitizer, value = no (default) or yes + -D ENABLE_SANITIZE_THREAD=value # enable Thread Sanitizer, value = no (default) or yes + + +---------- + + +.. _testing: + +Code Coverage and Testing +--------------------------------------- + +We do extensive regression testing of the LAMMPS code base on a continuous +basis. Some of the logic to do this has been added to the CMake build so +developers can run the tests directly on their workstation. + +.. note:: + + this is incomplete and only represents a small subset of tests that we run + + +.. parsed-literal:: + + -D ENABLE_TESTING=value # enable simple run tests of LAMMPS, value = no (default) or yes + -D LAMMPS_TESTING_SOURCE_DIR=path # path to lammps-testing repository (option if in custom location) + -D LAMMPS_TESTING_GIT_TAG=value # version of lammps-testing repository that should be used, value = master (default) or custom git commit or tag + +If you enable testing in the CMake build it will create an additional target called "test". You can run them with: + + +.. parsed-literal:: + + make test + +The test cases used come from the lammps-testing repository. They are +derivatives of the examples folder with some modifications to make the run +faster. + +You can also collect code coverage metrics while running the tests by enabling +coverage support during building. + + +.. parsed-literal:: + + -D ENABLE_COVERAGE=value # enable coverage measurements, value = no (default) or yes + +This will also add the following targets to generate coverage reports after running the LAMMPS executable: + + +.. parsed-literal:: + + make test # run tests first! + make gen_coverage_html # generate coverage report in HTML format + make gen_coverage_xml # generate coverage report in XML format + +These reports require GCOVR to be installed. The easiest way to do this to install it via pip: + + +.. parsed-literal:: + + pip install git+https://github.com/gcovr/gcovr.git + + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst new file mode 100644 index 0000000000000000000000000000000000000000..61629400159e30e2b120d27bae37678cc83f2908 --- /dev/null +++ b/doc/src/Build_extras.rst @@ -0,0 +1,1399 @@ +Packages with extra build options +================================= + +When building with some packages, additional steps may be required, +in addition to: + + +.. parsed-literal:: + + -D PKG_NAME=yes # CMake + make yes-name # make + +as described on the :doc:`Build\_package ` doc page. + +For a CMake build there may be additional optional or required +variables to set. For a build with make, a provided library under the +lammps/lib directory may need to be built first. Or an external +library may need to exist on your system or be downloaded and built. +You may need to tell LAMMPS where it is found on your system. + +This is the list of packages that may require additional steps. + ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`COMPRESS ` | :ref:`GPU ` | :ref:`KIM ` | :ref:`KOKKOS ` | :ref:`LATTE ` | :ref:`MESSAGE ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`MSCG ` | :ref:`OPT ` | :ref:`POEMS ` | :ref:`PYTHON ` | :ref:`VORONOI ` | :ref:`USER-ADIOS ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-ATC ` | :ref:`USER-AWPMD ` | :ref:`USER-COLVARS ` | :ref:`USER-H5MD ` | :ref:`USER-INTEL ` | :ref:`USER-MOLFILE ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-NETCDF ` | :ref:`USER-PLUMED ` | :ref:`USER-OMP ` | :ref:`USER-QMMM ` | :ref:`USER-QUIP ` | :ref:`USER-SCAFACOS ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-SMD ` | :ref:`USER-VTK ` | | | | | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ + + +---------- + + +.. _compress: + +COMPRESS package +------------------------------- + +To build with this package you must have the zlib compression library +available on your system. + +**CMake build**\ : + +If CMake cannot find the library, you can set these variables: + + +.. parsed-literal:: + + -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file + -D ZLIB_LIBRARIES=path # path to libz.a (.so) file + +**Traditional make**\ : + +If make cannot find the library, you can edit the +lib/compress/Makefile.lammps file to specify the paths and library +name. + + +---------- + + +.. _gpu: + +GPU package +--------------------- + +To build with this package, you must choose options for precision and +which GPU hardware to build for. + +**CMake build**\ : + + +.. parsed-literal:: + + -D GPU_API=value # value = opencl (default) or cuda + -D GPU_PREC=value # precision setting + # value = double or mixed (default) or single + -D OCL_TUNE=value # hardware choice for GPU_API=opencl + # generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA) + -D GPU_ARCH=value # primary GPU hardware choice for GPU_API=cuda + # value = sm_XX, see below + # default is sm_30 + -D CUDPP_OPT=value # optimization setting for GPU_API=cuda + # enables CUDA Performance Primitives Optimizations + # value = yes (default) or no + -D CUDA_MPS_SUPPORT=value # enables some tweaks required to run with active nvidia-cuda-mps daemon + # value = yes or no (default) + +GPU\_ARCH settings for different GPU hardware is as follows: + +* 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\_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) + +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. +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. + +**Traditional make**\ : + +Before building LAMMPS, you must build the GPU library in lib/gpu. +You can do this manually if you prefer; follow the instructions in +lib/gpu/README. Note that the GPU library uses MPI calls, so you must +use the same MPI library (or the STUBS library) settings as the main +LAMMPS code. This also applies to the -DLAMMPS\_BIGBIG, +-DLAMMPS\_SMALLBIG, or -DLAMMPS\_SMALLSMALL settings in whichever +Makefile you use. + +You can also build the library in one step from the lammps/src dir, +using a command like these, which simply invoke the lib/gpu/Install.py +script with the specified args: + + +.. parsed-literal:: + + make lib-gpu # print help message + make lib-gpu args="-b" # build GPU library with default Makefile.linux + make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision + make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi + +Note that this procedure starts with a Makefile.machine in lib/gpu, as +specified by the "-m" switch. For your convenience, machine makefiles +for "mpi" and "serial" are provided, which have the same settings as +the corresponding machine makefiles in the main LAMMPS source +folder. In addition you can alter 4 important settings in the +Makefile.machine you start from via the corresponding -c, -a, -p, -e +switches (as in the examples above), and also save a copy of the new +Makefile if desired: + +* CUDA\_HOME = where NVIDIA CUDA software is installed on your system +* CUDA\_ARCH = sm\_XX, what GPU hardware you have, same as CMake GPU\_ARCH above +* CUDA\_PRECISION = precision (double, mixed, single) +* EXTRAMAKE = which Makefile.lammps.\* file to copy to Makefile.lammps + +The file Makefile.linux\_multi is set up to include support for multiple +GPU architectures as supported by the CUDA toolkit in use. This is done +through using the "--gencode " flag, which can be used multiple times and +thus support all GPU architectures supported by your CUDA compiler. + +If the library build is successful, 3 files should be created: +lib/gpu/libgpu.a, lib/gpu/nvc\_get\_devices, and +lib/gpu/Makefile.lammps. The latter has settings that enable LAMMPS +to link with CUDA libraries. If the settings in Makefile.lammps for +your machine are not correct, the LAMMPS build will fail, and +lib/gpu/Makefile.lammps may need to be edited. + +.. note:: + + If you re-build the GPU library in lib/gpu, you should always + un-install the GPU package in lammps/src, then re-install it and + re-build LAMMPS. This is because the compilation of files in the GPU + package uses the library settings from the lib/gpu/Makefile.machine + used to build the GPU library. + + +---------- + + +.. _kim: + +KIM package +--------------------- + +To build with this package, the KIM library with API v2 must be downloaded +and built on your system. It must include the KIM models that you want to +use with LAMMPS. If you want to use the :doc:`kim\_query ` +command, you also need to have libcurl installed with the matching +development headers and the curl-config tool. + +See `Obtaining KIM Models `_ to +learn how to install a pre-build binary of the OpenKIM Repository of Models. +See the list of all KIM models here: https://openkim.org/browse/models + +(Also note that when downloading and installing from source +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**\ : + + +.. parsed-literal:: + + -D DOWNLOAD_KIM=value # download OpenKIM API v2 for build, value = no (default) or yes + +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. + +**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. + + +.. parsed-literal:: + + 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 + + +---------- + + +.. _kokkos: + +KOKKOS package +--------------------------- + +To build with this package, you must choose which hardware you want to +build for, either CPUs (multi-threading via OpenMP) or KNLs (OpenMP) +or GPUs (NVIDIA Cuda). + +For a CMake or make build, these are the possible choices for the +KOKKOS\_ARCH settings described below. Note that for CMake, these are +really Kokkos variables, not LAMMPS variables. Hence you must use +case-sensitive values, e.g. BDW, not bdw. + +* ARMv80 = ARMv8.0 Compatible CPU +* ARMv81 = ARMv8.1 Compatible CPU +* ARMv8-ThunderX = ARMv8 Cavium ThunderX CPU +* BGQ = IBM Blue Gene/Q CPUs +* Power8 = IBM POWER8 CPUs +* Power9 = IBM POWER9 CPUs +* SNB = Intel Sandy/Ivy Bridge CPUs +* HSW = Intel Haswell CPUs +* BDW = Intel Broadwell Xeon E-class CPUs +* SKX = Intel Sky Lake Xeon E-class HPC CPUs (AVX512) +* KNC = Intel Knights Corner Xeon Phi +* KNL = Intel Knights Landing Xeon Phi +* Kepler30 = NVIDIA Kepler generation CC 3.0 +* Kepler32 = NVIDIA Kepler generation CC 3.2 +* Kepler35 = NVIDIA Kepler generation CC 3.5 +* Kepler37 = NVIDIA Kepler generation CC 3.7 +* Maxwell50 = NVIDIA Maxwell generation CC 5.0 +* Maxwell52 = NVIDIA Maxwell generation CC 5.2 +* Maxwell53 = NVIDIA Maxwell generation CC 5.3 +* Pascal60 = NVIDIA Pascal generation CC 6.0 +* Pascal61 = NVIDIA Pascal generation CC 6.1 +* Volta70 = NVIDIA Volta generation CC 7.0 +* Volta72 = NVIDIA Volta generation CC 7.2 +* Turing75 = NVIDIA Turing generation CC 7.5 + +**CMake build**\ : + +For multicore CPUs using OpenMP, set these 2 variables. + + +.. parsed-literal:: + + -D KOKKOS_ARCH=archCPU # archCPU = CPU from list above + -D KOKKOS_ENABLE_OPENMP=yes + +For Intel KNLs using OpenMP, set these 2 variables: + + +.. parsed-literal:: + + -D KOKKOS_ARCH=KNL + -D KOKKOS_ENABLE_OPENMP=yes + +For NVIDIA GPUs using CUDA, set these 4 variables: + + +.. parsed-literal:: + + -D KOKKOS_ARCH="archCPU;archGPU" # archCPU = CPU from list above that is hosting the GPU + # archGPU = 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 + +The wrapper value is 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. + + +.. parsed-literal:: + + -D CMAKE_CXX_COMPILER=/home/username/lammps/lib/kokkos/bin/nvcc_wrapper + +**Traditional 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. + +For multicore CPUs using OpenMP: + + +.. parsed-literal:: + + KOKKOS_DEVICES = OpenMP + KOKKOS_ARCH = archCPU # archCPU = CPU from list above + +For Intel KNLs using OpenMP: + + +.. parsed-literal:: + + KOKKOS_DEVICES = OpenMP + KOKKOS_ARCH = KNL + +For NVIDIA GPUs using CUDA: + + +.. parsed-literal:: + + KOKKOS_DEVICES = Cuda + KOKKOS_ARCH = archCPU,archGPU # archCPU = CPU from list above that is hosting the GPU + # archGPU = GPU from list above + +For GPUs, you also need these 2 lines in your Makefile.machine before +the CC line is defined, in this case for use with OpenMPI mpicxx. The +2 lines define a nvcc wrapper compiler, which will use nvcc for +compiling CUDA files and use a C++ compiler for non-Kokkos, non-CUDA +files. + + +.. parsed-literal:: + + KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) + export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper + CC = mpicxx + + +---------- + + +.. _latte: + +LATTE package +------------------------- + +To build with this package, you must download and build the LATTE +library. + +**CMake build**\ : + + +.. parsed-literal:: + + -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) + +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. + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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 into the LATTE home +dir. 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. + + +---------- + + +.. _message: + +MESSAGE package +----------------------------- + +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**\ : + + +.. parsed-literal:: + + -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) + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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. + + +---------- + + +.. _mscg: + +MSCG package +----------------------- + +To build with this package, you must download and build the MS-CG +library. Building the MS-CG library and using it from LAMMPS requires +a C++11 compatible compiler and that the GSL (GNU Scientific Library) +headers and libraries are installed on your machine. See the +lib/mscg/README and MSCG/Install files for more details. + +**CMake build**\ : + + +.. parsed-literal:: + + -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) + +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. + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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. + + +---------- + + +.. _opt: + +OPT package +--------------------- + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_OPT=yes". + +**Traditional make**\ : + +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. + + +---------- + + +.. _poems: + +POEMS package +------------------------- + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_OPT=yes". + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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. + + +---------- + + +.. _python: + +PYTHON package +--------------------------- + +Building with the PYTHON package requires you have a Python shared +library available on your system, which needs to be a Python 2 +version, 2.6 or later. Python 3 is not yet supported. See +lib/python/README for more details. + +**CMake build**\ : + + +.. parsed-literal:: + + -D PYTHON_EXECUTABLE=path # path to Python executable to use + +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. + +**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. + + +---------- + + +.. _voronoi: + +VORONOI package +----------------------------- + +To build with this package, you must download and build the `Voro++ library `_. + +.. _voro-home: http://math.lbl.gov/voro++ + + + +**CMake build**\ : + + +.. parsed-literal:: + + -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. + +**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: + + +.. parsed-literal:: + + 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++ src dir. When LAMMPS +builds in src it will use these links. You should not need to edit +the lib/voronoi/Makefile.lammps file. + + +---------- + + +.. _user-adios: + +USER-ADIOS package +----------------------------------- + +The USER-ADIOS package requires the `ADIOS I/O library `_, +version 2.3.1 or newer. Make sure that you have ADIOS built either with or +without MPI to match if you build LAMMPS with or without MPI. +ADIOS compilation settings for LAMMPS are automatically detected, if the PATH +and LD\_LIBRARY\_PATH environment variables have been updated for the local ADIOS +installation and the instructions below are followed for the respective build systems. + +**CMake build**\ : + + +.. parsed-literal:: + + -D ADIOS2_DIR=path # path is where ADIOS 2.x is installed + -D PKG_USER-ADIOS=yes + +**Traditional make**\ : + +Turn on the USER-ADIOS package before building LAMMPS. If the ADIOS 2.x software is installed in PATH, there is nothing else to do: + + +.. parsed-literal:: + + make yes-user-adios + +otherwise, set ADIOS2\_DIR environment variable when turning on the package: + + +.. parsed-literal:: + + ADIOS2_DIR=path make yes-user-adios # path is where ADIOS 2.x is installed + + +---------- + + +.. _user-atc: + +USER-ATC package +------------------------------- + +The USER-ATC package requires the MANYBODY package also be installed. + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_USER-ATC=yes" +and "-D PKG\_MANYBODY=yes". + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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 + +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.machine +file. + +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: + + +.. parsed-literal:: + + 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 + + +---------- + + +.. _user-awpmd: + +USER-AWPMD package +----------------------------------- + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_USER-AQPMD=yes". + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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 + +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.machine file. + +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: + + +.. parsed-literal:: + + 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 + + +---------- + + +.. _user-colvars: + +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. + +A few of the most recent features require C++11 support. In particular, the +library is optionally built together with the +`Lepton `_ library, a copy of which is also +included in the LAMMPS distribution. Lepton implements the +`customFunction `_ +feature, and requires C++11 support. + +See `here `_ for a detailed list of +C++11-only features. + +**CMake build**\ : + +This is the recommended build recipe: no additional settings are normally +needed besides "-D PKG\_USER-COLVARS=yes". + +Building and linking of Lepton (or other C++11-only features) is enabled +automatically when compilation is carried out with C++11 support, and disabled +otherwise. Optionally, Lepton build may be manually controlled with the flag +"-D COLVARS\_LEPTON=yes\|no". + +**Traditional make**\ : + +Before building LAMMPS, one must build the Colvars library in lib/colvars. + +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 compiler. + +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: + + +.. parsed-literal:: + + 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 + +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. + +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) + +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. + + +---------- + + +.. _user-plumed: + +USER-PLUMED package +------------------------------------- + +.. _plumedinstall: http://plumed.github.io/doc-master/user-doc/html/\_installation.html + +Before building LAMMPS with this package, you must first build PLUMED. +PLUMED can be built as part of the LAMMPS build or installed separately +from LAMMPS using the generic `plumed installation instructions `_. + + +PLUMED can be linked into MD codes in three different modes: static, +shared, and runtime. With the "static" mode, all the code that PLUMED +requires is linked statically into LAMMPS. LAMMPS is then fully +independent from the PLUMED installation, but you have to rebuild/relink +it in order to update the PLUMED code inside it. With the "shared" +linkage mode, LAMMPS is linked to a shared library that contains the +PLUMED code. This library should preferably be installed in a globally +accessible location. When PLUMED is linked in this way the same library +can be used by multiple MD packages. Furthermore, the PLUMED library +LAMMPS uses can be updated without the need for a recompile of LAMMPS +for as long as the shared PLUMED library is ABI-compatible. + +The third linkage mode is "runtime" which allows the user to specify +which PLUMED kernel should be used at runtime by using the PLUMED\_KERNEL +environment variable. This variable should point to the location of the +libplumedKernel.so dynamical shared object, which is then loaded at +runtime. This mode of linking is particularly convenient for doing +PLUMED development and comparing multiple PLUMED versions as these sorts +of comparisons can be done without recompiling the hosting MD code. All +three linkage modes are supported by LAMMPS on selected operating +systems (e.g. Linux) and using either CMake or traditional make +build. The "static" mode should be the most portable, while the +"runtime" mode support in LAMMPS makes the most assumptions about +operating system and compiler environment. If one mode does not work, +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**\ : + +When the "-D PKG\_USER-PLUMED" 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 commands that control +the manner in which PLUMED is obtained and linked into LAMMPS. + + +.. parsed-literal:: + + -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 + +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. + +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. + +**Traditional make**\ : + +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. + +Download/compilation/configuration of the plumed library can be done +from the src folder through the following make args: + + +.. parsed-literal:: + + 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 + +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: + + +.. parsed-literal:: + + make yes-user-plumed + make machine + +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. + +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. + + +---------- + + +.. _user-h5md: + +USER-H5MD package +--------------------------------- + +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**\ : + +No additional settings are needed besides "-D PKG\_USER-H5MD=yes". + +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. + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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.machine +file. + + +---------- + + +.. _user-intel: + +USER-INTEL package +----------------------------------- + +To build with this package, you must choose which hardware you want to +build for, either x86 CPUs or Intel KNLs in offload mode. You should +also typically :ref:`install the USER-OMP package `, as it can be +used in tandem with the USER-INTEL package to good effect, as explained +on the :doc:`Speed intel ` doc page. + +**CMake build**\ : + + +.. parsed-literal:: + + -D INTEL_ARCH=value # value = cpu (default) or knl + -D INTEL_LRT_MODE=value # value = threads, none, or c++11 + +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". + +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: + + +.. parsed-literal:: + + 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: + + +.. parsed-literal:: + + 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 + + +---------- + + +.. _user-molfile: + +USER-MOLFILE package +--------------------------------------- + +**CMake build**\ : + + +.. parsed-literal:: + + -D MOLFILE_INCLUDE_DIRS=path # (optional) path where VMD molfile plugin headers are installed + -D PKG_USER-MOLFILE=yes + +Using "-D PKG\_USER-MOLFILE=yes" enables the package, and setting +"-D MOLFILE\_INCLUDE DIRS" 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. + +**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. + + +---------- + + +.. _user-netcdf: + +USER-NETCDF package +------------------------------------- + +To build with this package you must have the NetCDF library installed +on your system. + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_USER-NETCDF=yes". + +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. + +**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. + + +---------- + + +.. _user-omp: + +USER-OMP package +------------------------------- + +**CMake build**\ : + +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. + +**Traditional make**\ : + +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. + + +.. parsed-literal:: + + CCFLAGS: -fopenmp # for GNU Compilers + CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux + LINKFLAGS: -fopenmp # for GNU Compilers + LINKFLAGS: -qopenmp # for Intel compilers on Linux + +For other platforms and compilers, please consult the documentation +about OpenMP support for your compiler. Please see the note about +how to address compatibility :ref:`issues with the 'default(none)' directive ` of some compilers. + + +---------- + + +.. _user-qmmm: + +USER-QMMM package +--------------------------------- + +.. note:: + + The LAMMPS executable these steps produce is not yet functional + for a QM/MM simulation. You must also build Quantum ESPRESSO and + create a new executable (pwqmmm.x) which links LAMMPS and Quantum + ESPRESSO together. These are steps 3 and 4 described in the + lib/qmmm/README file. Unfortunately, the Quantum ESPRESSO developers + have been breaking the interface that the QM/MM code in LAMMPS is using, + so that currently (Summer 2018) using this feature requires either + correcting the library interface feature in recent Quantum ESPRESSO + releases, or using an outdated version of QE. The last version of + Quantum ESPRESSO known to work with this QM/MM interface was version + 5.4.1 from 2016. + +**CMake build**\ : + +The CMake build system currently does not support building the full +QM/MM-capable hybrid executable of LAMMPS and QE called pwqmmm.x. +You must use the traditional make build for this package. + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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 + +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.machine file +for your system, which should define an EXTRAMAKE variable to specify +a corresponding Makefile.lammps.machine 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, 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. + + +---------- + + +.. _user-quip: + +USER-QUIP package +--------------------------------- + +To build with this package, you must download and build the QUIP +library. It can be obtained from GitHub. For support of GAP +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**\ : + + +.. parsed-literal:: + + -D QUIP_LIBRARY=path # path to libquip.a (only needed if a custom location) + +CMake will not download and build the QUIP library. But once you have +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. + +**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. + + +---------- + + +.. _user-scafacos: + +USER-SCAFACOS package +----------------------------------------- + +To build with this package, you must download and build the `ScaFaCoS Coulomb solver library `_ + +.. _scafacos-home: http://www.scafacos.de + + + +**CMake build**\ : + + +.. parsed-literal:: + + -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. + +**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: + +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. + + +---------- + + +.. _user-smd: + +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**\ : + + +.. parsed-literal:: + + -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) + +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. + +**Traditional make**\ : + +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: + + +.. parsed-literal:: + + 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. + + +---------- + + +.. _user-vtk: + +USER-VTK package +------------------------------- + +To build with this package you must have the VTK library installed on +your system. + +**CMake build**\ : + +No additional settings are needed besides "-D PKG\_USER-VTK=yes". + +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. + +**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. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst new file mode 100644 index 0000000000000000000000000000000000000000..8306fcb86f5930d89179a16b467a0cfecc9b0c62 --- /dev/null +++ b/doc/src/Build_link.rst @@ -0,0 +1,91 @@ +Link LAMMPS as a library to another code +======================================== + +LAMMPS can be used as a library by another application, including +Python scripts. The files src/library.cpp and library.h define the +C-style API for using LAMMPS as a library. See the :doc:`Howto library ` doc page for a description of the +interface and how to extend it for your needs. + +The :doc:`Build basics ` doc page explains how to build +LAMMPS as either a shared or static library. This results in one of +these 2 files: + +liblammps.so # shared library +liblammps.a # static library + + +---------- + + +**Link with LAMMPS as a static library**\ : + +The calling application can link to LAMMPS as a static library with a +link command like this: + +g++ caller.o -L/home/sjplimp/lammps/src -llammps -o caller + +The -L argument is the path to where the liblammps.a file is. The +-llammps argument is shorthand for the file liblammps.a. + + +---------- + + +**Link with LAMMPS as a shared library**\ : + +If you wish to link to liblammps.so, the operating system finds shared +libraries to load at run-time using the environment variable +LD\_LIBRARY\_PATH. To enable this you can do one of two things: + +(1) Copy the liblammps.so file to a location the system can find it, +such as /usr/local/lib. I.e. a directory already listed in your +LD\_LIBRARY\_PATH variable. You can type + + +.. parsed-literal:: + + printenv LD_LIBRARY_PATH + +to see what directories are in that list. + +(2) Add the LAMMPS src directory (or the directory you perform CMake +build in) to your LD\_LIBRARY\_PATH, so that the current version of the +shared library is always available to programs that use it. + +For the csh or tcsh shells, you would add something like this to your +~/.cshrc file: + + +.. parsed-literal:: + + setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src + + +---------- + + +**Calling the LAMMPS library**\ : + +Either flavor of library (static or shared) allows one or more LAMMPS +objects to be instantiated from the calling program. + +When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS\_NS +namespace; you can safely use any of its classes and methods from +within the calling code, as needed. + +When used from a C or Fortran program, the library has a simple +C-style interface, provided in src/library.cpp and src/library.h. + +See the :doc:`Python library ` doc page for a +description of the Python interface to LAMMPS, which wraps the C-style +interface. + +See the sample codes in examples/COUPLE/simple for examples of C++ and +C and Fortran codes that invoke LAMMPS through its library interface. +Other examples in the COUPLE directory use coupling ideas discussed on +the :doc:`Howto couple ` doc page. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst new file mode 100644 index 0000000000000000000000000000000000000000..8f1966f1014bc120cc9858c88fb23afe1ba92613 --- /dev/null +++ b/doc/src/Build_make.rst @@ -0,0 +1,94 @@ +Build LAMMPS with make +====================== + +Building LAMMPS with traditional makefiles requires that you have a +Makefile."machine" file appropriate for your system in the src/MAKE, +src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see +below). It can include various options for customizing your LAMMPS +build with a number of global compilation options and features. + +To include LAMMPS packages (i.e. optional commands and styles) you +must install them first, as discussed on the :doc:`Build package ` doc page. If the packages require +provided or external libraries, you must build those libraries before +building LAMMPS. Building :doc:`LAMMPS with CMake ` can +automate all of this for many types of machines, especially +workstations, desktops and laptops, so we suggest you try it first. + +These commands perform a default LAMMPS build, producing the LAMMPS +executable lmp\_serial or lmp\_mpi in lammps/src: + + +.. parsed-literal:: + + cd lammps/src + make serial # build a serial LAMMPS executable + make mpi # build a parallel LAMMPS executable with MPI + make # see a variety of make options + +This initial compilation can take a long time, since LAMMPS is a large +project with many features. If your machine has multiple CPU cores +(most do these days), using a command like "make -jN mpi" (with N = +the number of available CPU cores) can be much faster. If you plan to +do development on LAMMPS or need to re-compile LAMMPS repeatedly, the +installation of the ccache (= Compiler Cache) software may speed up +compilation even more. + +After the initial build, whenever you edit LAMMPS source files, or add +or remove new files to the source directory (e.g. by installing or +uninstalling packages), you must re-compile and relink the LAMMPS +executable with the same "make" command. This makefiles dependencies +should insure that only the subset of files that need to be are +re-compiled. + +.. note:: + + When you build LAMMPS for the first time, a long list of \*.d + files will be printed out rapidly. This is not an error; it is the + Makefile doing its normal creation of dependencies. + + +---------- + + +The lammps/src/MAKE tree contains all the Makefile.machine files +included in the LAMMPS distribution. Typing "make machine" uses +Makefile.machine. Thus the "make serial" or "make mpi" lines above +use Makefile.serial and Makefile.mpi. Others are in these dirs: + + +.. parsed-literal:: + + OPTIONS # Makefiles which enable specific options + MACHINES # Makefiles for specific machines + MINE # customized Makefiles you create (you may need to create this folder) + +Typing "make" lists all the available Makefile.machine files. A file +with the same name can appear in multiple folders (not a good idea). +The order the dirs are searched is as follows: src/MAKE/MINE, +src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference +to a customized file you put in src/MAKE/MINE. + +Makefiles you may wish to try include these (some require a package +first be installed). Many of these include specific compiler flags +for optimized performance. Please note, however, that some of these +customized machine Makefile are contributed by users. Since both +compilers, OS configurations, and LAMMPS itself keep changing, their +settings may become outdated: + + +.. parsed-literal:: + + make mac # build serial LAMMPS on a Mac + make mac_mpi # build parallel LAMMPS on a Mac + make intel_cpu # build with the USER-INTEL package optimized for CPUs + make knl # build with the USER-INTEL package optimized for KNLs + make opt # build with the OPT package optimized for CPUs + make omp # build with the USER-OMP package optimized for OpenMP + make kokkos_omp # build with the KOKKOS package for OpenMP + make kokkos_cuda_mpi # build with the KOKKOS package for GPUs + make kokkos_phi # build with the KOKKOS package for KNLs + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst new file mode 100644 index 0000000000000000000000000000000000000000..9f56f3f329d7c13d78874ddafdb0b7e7e9402ffc --- /dev/null +++ b/doc/src/Build_package.rst @@ -0,0 +1,265 @@ +Include packages in build +========================= + +In LAMMPS, a package is a group of files that enable a specific set of +features. For example, force fields for molecular systems or +rigid-body constraints are in packages. In the src directory, each +package is a sub-directory with the package name in capital letters. + +An overview of packages is given on the :doc:`Packages ` doc +page. Brief overviews of each package are on the :doc:`Packages details ` doc page. + +When building LAMMPS, you can choose to include or exclude each +package. In general there is no need to include a package if you +never plan to use its features. + +If you get a run-time error that a LAMMPS command or style is +"Unknown", it is often because the command is contained in a package, +and your build did not include that package. Running LAMMPS with the +:doc:`-h command-line switch ` will print all the included +packages and commands for that executable. + +For the majority of packages, if you follow the single step below to +include it, you can then build LAMMPS exactly the same as you would +without any packages installed. A few packages may require additional +steps, as explained on the :doc:`Build extras ` doc page. + +These links take you to the extra instructions for those select +packages: + ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`COMPRESS ` | :ref:`GPU ` | :ref:`KIM ` | :ref:`KOKKOS ` | :ref:`LATTE ` | :ref:`MESSAGE ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`MSCG ` | :ref:`OPT ` | :ref:`POEMS ` | :ref:`PYTHON ` | :ref:`VORONOI ` | :ref:`USER-ADIOS ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-ATC ` | :ref:`USER-AWPMD ` | :ref:`USER-COLVARS ` | :ref:`USER-H5MD ` | :ref:`USER-INTEL ` | :ref:`USER-MOLFILE ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-NETCDF ` | :ref:`USER-PLUMED ` | :ref:`USER-OMP ` | :ref:`USER-QMMM ` | :ref:`USER-QUIP ` | :ref:`USER-SCAFACOS ` | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ +| :ref:`USER-SMD ` | :ref:`USER-VTK ` | | | | | ++----------------------------------+----------------------------------+------------------------------------+------------------------------+--------------------------------+--------------------------------------+ + +The mechanism for including packages is simple but different for CMake +versus make. + +**CMake variables**\ : + + +.. parsed-literal:: + + -D PKG_NAME=value # yes or no (default) + +Examples: + + +.. parsed-literal:: + + -D PKG_MANYBODY=yes + -D PKG_USER-INTEL=yes + +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 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**\ : + + +.. parsed-literal:: + + 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: + + +.. parsed-literal:: + + 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 or SVN repositories, 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. + + +---------- + + +**CMake shortcuts for installing many packages**\ : + +Instead of specifying all the CMake options via the command-line, +CMake allows initializing the variable cache using script files. These +are regular CMake files which can manipulate and set variables, and +can also contain control flow constructs. + +LAMMPS includes several of these files to define configuration +"presets", similar to the options that exist for the Make based +system. Using these files you can enable/disable portions of the +available packages in LAMMPS. If you need a custom preset you can take +one of them as a starting point and customize it to your needs. + ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/all\_on.cmake [OPTIONS] ../cmake | enable all packages | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/all\_off.cmake [OPTIONS] ../cmake | disable all packages | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/minimal.cmake [OPTIONS] ../cmake | enable just a few core packages | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/most.cmake [OPTIONS] ../cmake | enable most common packages | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake | disable packages that do require extra libraries or tools | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake | change settings to use the Clang compilers by default | ++-------------------------------------------------------------+-----------------------------------------------------------+ +| cmake -C ../cmake/presets/mingw.cmake [OPTIONS] ../cmake | enable all packages compatible with MinGW compilers | ++-------------------------------------------------------------+-----------------------------------------------------------+ + +.. note:: + + Running cmake this way manipulates the variable cache in your + current build directory. You can combine multiple presets and options + in a single cmake run, or change settings incrementally by running + cmake with new flags. + +**Example:** + + +.. parsed-literal:: + + # build LAMMPS with most commonly used packages, but then remove + # those requiring additional library or tools, but still enable + # GPU package and configure it for using CUDA. You can run. + mkdir build + cd build + cmake -C ../cmake/presets/most.cmake -C ../cmake/presets/nolib.cmake -D PKG_GPU=on -D GPU_API=cuda ../cmake + + # to add another package, say BODY to the previous configuration you can run: + cmake -D PKG_BODY=on . + + # to reset the package selection from above to the default of no packages + # but leaving all other settings untouched. You can run: + cmake -C ../cmake/presets/no_all.cmake . + + +---------- + + +**Make shortcuts for installing many packages**\ : + +The following commands are useful for managing package source files +and their installation when building LAMMPS via traditional make. +Just type "make" in lammps/src to see a one-line summary. + +These commands install/un-install sets of packages: + ++-----------------------------------+-----------------------------------------------------+ +| make yes-all | install all packages | ++-----------------------------------+-----------------------------------------------------+ +| make no-all | un-install all packages | ++-----------------------------------+-----------------------------------------------------+ +| make yes-standard or make yes-std | install standard packages | ++-----------------------------------+-----------------------------------------------------+ +| make no-standard or make no-std | un-install standard packages | ++-----------------------------------+-----------------------------------------------------+ +| make yes-user | install user packages | ++-----------------------------------+-----------------------------------------------------+ +| make no-user | un-install user packages | ++-----------------------------------+-----------------------------------------------------+ +| make yes-lib | install packages that require extra libraries | ++-----------------------------------+-----------------------------------------------------+ +| make no-lib | un-install packages that require extra libraries | ++-----------------------------------+-----------------------------------------------------+ +| make yes-ext | install packages that require external libraries | ++-----------------------------------+-----------------------------------------------------+ +| make no-ext | un-install packages that require external libraries | ++-----------------------------------+-----------------------------------------------------+ + +which install/un-install various sets of packages. Typing "make +package" will list all the these commands. + +.. note:: + + Installing or un-installing a package works by simply copying + files back and forth between the main src directory and + sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), + so that the files are included or excluded when LAMMPS is built. + +The following make commands help manage files that exist in both the +src directory and in package sub-directories. You do not normally +need to use these commands unless you are editing LAMMPS files or are +:doc:`installing a patch ` downloaded from the LAMMPS web +site. + +Type "make package-status" or "make ps" to show which packages are +currently installed. For those that are installed, it will list any +files that are different in the src directory and package +sub-directory. + +Type "make package-installed" or "make pi" to show which packages are +currently installed, without listing the status of packages that are +not installed. + +Type "make package-update" or "make pu" to overwrite src files with +files from the package sub-directories if the package is installed. +It should be used after a :doc:`patch has been applied `, +since patches only update the files in the package sub-directory, but +not the src files. + +Type "make package-overwrite" to overwrite files in the package +sub-directories with src files. + +Type "make package-diff" to list all differences between pairs of +files in both the src dir and a package dir. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_settings.rst b/doc/src/Build_settings.rst new file mode 100644 index 0000000000000000000000000000000000000000..07d427db49860a522797a46d7b875177287b8948 --- /dev/null +++ b/doc/src/Build_settings.rst @@ -0,0 +1,479 @@ +Optional build settings +======================= + +LAMMPS can be built with several optional settings. Each sub-section +explain how to do this for building both with CMake and make. + +| :ref:`C++11 standard compliance test ` when building all of LAMMPS +| :ref:`FFT library ` for use with the :doc:`kspace\_style pppm ` command +| :ref:`Size of LAMMPS data types ` +| :ref:`Read or write compressed files ` +| :ref:`Output of JPG and PNG files ` via the :doc:`dump image ` command +| :ref:`Output of movie files ` via the :doc:`dump\_movie ` command +| :ref:`Memory allocation alignment ` +| :ref:`Workaround for long long integers ` +| :ref:`Error handling exceptions ` when using LAMMPS as a library +| + + +---------- + + +.. _cxx11: + +C++11 standard compliance test +------------------------------------------ + +The LAMMPS developers plan to transition to make the C++11 standard the +minimum requirement for compiling LAMMPS. Currently this only applies to +some packages like KOKKOS while the rest aims to be compatible with the C++98 +standard. Most currently used compilers are compatible with C++11; some need +to set extra flags to switch. To determine the impact of requiring C++11, +we have added a simple compliance test to the source code, that will cause +the compilation to abort, if C++11 compliance is not available or enabled. +To bypass this check, you need to change a setting in the makefile or +when calling CMake. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D DISABLE_CXX11_REQUIREMENT=yes + +You can set additional C++ compiler flags (beyond those selected by CMake) +through the CMAKE\_CXX\_FLAGS variable. Example for CentOS 7: + + +.. parsed-literal:: + + -D CMAKE_CXX_FLAGS="-O3 -g -fopenmp -DNDEBUG -std=c++11" + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_CXX98 + + +---------- + + +.. _fft: + +FFT library +--------------------- + +When the KSPACE package is included in a LAMMPS build, the +:doc:`kspace\_style pppm ` command performs 3d FFTs which +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 variables**\ : + + +.. parsed-literal:: + + -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 + +.. note:: + + 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. + +Usually these settings are all that is needed. If CMake cannot find +the FFT library, you can set these variables: + + +.. parsed-literal:: + + -D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files + -D FFTW3_LIBRARIES=path # path to FFTW3 libraries + -D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library + -D MKL_LIBRARIES=path + +**Makefile.machine settings**\ : + + +.. parsed-literal:: + + 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_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY + +# default is FFT\_PACK\_ARRAY if not specified + + +.. parsed-literal:: + + FFT_INC = -I/usr/local/include + FFT_PATH = -L/usr/local/lib + FFT_LIB = -lfftw3 # FFTW3 double precision + FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision + FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler + FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier + +As with CMake, you do not need to set paths in FFT\_INC or FFT\_PATH, if +make can find the FFT header and library files. You must specify +FFT\_LIB with the appropriate FFT libraries to include in the link. + +**CMake and make info**\ : + +The `KISS FFT library `_ is included in the LAMMPS +distribution. It is portable across all platforms. Depending on the +size of the FFTs and the number of processors used, the other +libraries listed here can be faster. + +However, note that long-range Coulombics are only a portion of the +per-timestep CPU cost, FFTs are only a portion of long-range +Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel +communication can be costly). A breakdown of these timings is printed +to the screen at the end of a run using the :doc:`kspace\_style pppm ` command. The :doc:`Run output ` +doc page gives more details. + +FFTW is a fast, portable FFT library that should also work on any +platform and can be faster than the KISS FFT library. You can +download it from `www.fftw.org `_. LAMMPS requires +version 3.X; the legacy version 2.1.X is no longer supported. + +Building FFTW for your box should be as simple as ./configure; make; +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 +various options. + +The Intel MKL math library is part of the Intel compiler suite. It +can be used with the Intel or GNU compiler (see FFT\_LIB setting above). + +Performing 3d FFTs in parallel can be time consuming due to data +access and required communication. This cost can be reduced by +performing single-precision FFTs instead of double precision. Single +precision means the real and imaginary parts of a complex datum are +4-byte floats. Double precision means they are 8-byte doubles. Note +that Fourier transform and related PPPM operations are somewhat less +sensitive to floating point truncation errors and thus the resulting +error is less than the difference in precision. Using the -DFFT\_SINGLE +setting trades off a little accuracy for reduced memory use and +parallel communication costs for transposing 3d FFT data. + +When using -DFFT\_SINGLE with FFTW3 you may need to build the FFTW +library a second time with support for single-precision. + +For FFTW3, do the following, which should produce the additional +library libfftw3f.a + + +.. parsed-literal:: + + make clean + ./configure --enable-single; make; make install + +Performing 3d FFTs requires communication to transpose the 3d FFT +grid. The data packing/unpacking for this can be done in one of 3 +modes (ARRAY, POINTER, MEMCPY) as set by the FFT\_PACK syntax above. +Depending on the machine, the size of the FFT grid, the number of +processors used, one option may be slightly faster. The default is +ARRAY mode. + + +---------- + + +.. _size: + +Size of LAMMPS data types +------------------------------------ + +LAMMPS has a few integer data types which can be defined as 4-byte or +8-byte integers. The default setting of "smallbig" is almost always +adequate. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL + +# default is LAMMPS\_SMALLBIG if not specified +**CMake and make info**\ : + +The default "smallbig" setting allows for simulations with: + +* 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 "bigbig" setting increases the latter two limits. It allows for: + +* 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) + +The "smallsmall" setting is only needed if your machine does not +support 8-byte integers. It allows for: + +* 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) + +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. + +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. + +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 +build does this automatically. When building with make, the setting +in whichever lib/gpu/Makefile is used must be the same as above. + + +---------- + + +.. _graphics: + +Output of JPG, PNG, and movie files +-------------------------------------------------- + +The :doc:`dump image ` command has options to output JPEG or +PNG image files. Likewise the :doc:`dump movie ` command +outputs movie files in MPEG format. Using these options requires the +following settings: + +**CMake variables**\ : + + +.. parsed-literal:: + + -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 + +Usually these settings are all that is needed. If CMake cannot find +the graphics header, library, executable files, you can set these +variables: + + +.. parsed-literal:: + + -D JPEG_INCLUDE_DIR=path # path to jpeglib.h header file + -D JPEG_LIBRARIES=path # path to libjpeg.a (.so) file + -D PNG_INCLUDE_DIR=path # path to png.h header file + -D PNG_LIBRARIES=path # path to libpng.a (.so) file + -D ZLIB_INCLUDE_DIR=path # path to zlib.h header file + -D ZLIB_LIBRARIES=path # path to libz.a (.so) file + -D FFMPEG_EXECUTABLE=path # path to ffmpeg executable + +**Makefile.machine settings**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_JPEG + LMP_INC = -DLAMMPS_PNG + LMP_INC = -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_LIB = -ljpeg -lpng -lz # library names + +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, +i.e. a dir in your PATH environment variable. + +**CMake and make info**\ : + +Using ffmpeg to output movie files requires that your machine +supports the "popen" function in the standard runtime library. + +.. note:: + + On some clusters with high-speed networks, using the fork() + library calls (required by popen()) can interfere with the fast + communication library and lead to simulations using ffmpeg to hang or + crash. + + +---------- + + +.. _gzip: + +Read or write compressed files +----------------------------------------- + +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 variables**\ : + + +.. parsed-literal:: + + -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 + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_GZIP + +**CMake and make info**\ : + +This option requires that your machine 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 calls (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. + + +---------- + + +.. _align: + +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 +pointers that are aligned to 16-byte boundaries. Using SSE vector +instructions efficiently, however, requires memory blocks being +aligned on 64-byte boundaries. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default) + +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. + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + 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 it does use different function calls 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 variable**\ : + + +.. parsed-literal:: + + -D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_LONGLONG_TO_LONG + + +---------- + + +.. _exceptions: + +Exception handling when using LAMMPS as a library +------------------------------------------------------------------ + +This setting is useful when external codes drive LAMMPS as a library. +With this option enabled LAMMPS errors do not kill the caller. +Instead, the call stack is unwound and control returns to the caller, +e.g. to Python. + +**CMake variable**\ : + + +.. parsed-literal:: + + -D LAMMPS_EXCEPTIONS=value # yes or no (default) + +**Makefile.machine setting**\ : + + +.. parsed-literal:: + + LMP_INC = -DLAMMPS_EXCEPTIONS + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Build_windows.rst b/doc/src/Build_windows.rst new file mode 100644 index 0000000000000000000000000000000000000000..fd96b379839bf298d9ce57d51358d206c2b6be50 --- /dev/null +++ b/doc/src/Build_windows.rst @@ -0,0 +1,111 @@ +Notes for building LAMMPS on Windows +==================================== + +* :ref:`General remarks ` +* :ref:`Running Linux on Windows ` +* :ref:`Using GNU GCC ported to Windows ` +* :ref:`Using a cross-compiler ` + + +---------- + + +.. _generic: + +General remarks +----------------------------- + +LAMMPS is developed and tested primarily on Linux machines. The vast +majority of HPC clusters and supercomputers today runs on Linux as well. +Thus portability to other platforms is desired, but not always achieved. +The LAMMPS developers strongly rely on LAMMPS users giving feedback and +providing assistance in resolving portability issues. This particularly +true for compiling LAMMPS on Windows, since this platform has significant +differences with some low-level functionality. + +.. _linux: + +Running Linux on Windows +------------------------------------ + +So before trying to build LAMMPS on Windows, please consider if using +the pre-compiled Windows binary packages are sufficient for your needs +(as an aside, those packages themselves are build on a Linux machine +using cross-compilers). If it is necessary for your to compile LAMMPS +on a Windows machine (e.g. because it is your main desktop), please also +consider using a virtual machine software and run a Linux virtual machine, +or - if have a recently updated Windows 10 installation - consider using +the Windows subsystem for Linux, which allows to run a bash shell from +Ubuntu and from there on, you can pretty much use that shell like you +are running on an Ubuntu Linux machine (e.g. installing software via +apt-get). For more details on that, please see :doc:`this tutorial ` + +.. _gnu: + +Using GNU GCC ported to Windows +----------------------------------------- + +One option for compiling LAMMPS on Windows natively, that has been known +to work in the past is to install a bash shell, unix shell utilities, +perl, GNU make, and a GNU compiler ported to Windows. The Cygwin package +provides a unix/linux interface to low-level Windows functions, so LAMMPS +can be compiled on Windows. The necessary (minor) modifications to LAMMPS +are included, but may not always up-to-date for recently added functionality +and the corresponding new code. A machine makefile for using cygwin for +the old build system is provided. Using CMake for this mode of compilation +is untested and not likely to work. + +When compiling for Windows do **not** set the -DLAMMPS\_MEMALIGN define +in the LMP\_INC makefile variable and add -lwsock32 -lpsapi to the linker +flags in LIB makefile variable. Try adding -static-libgcc or -static or +both to the linker flags when your resulting LAMMPS Windows executable +complains about missing .dll files. The CMake configuration should set +this up automatically, but is untested. + +In case of problems, you are recommended to contact somebody with +experience in using cygwin. If you do come across portability problems +requiring changes to the LAMMPS source code, or figure out corrections +yourself, please report them on the lammps-users mailing list, or file +them as an issue or pull request on the LAMMPS GitHub project. + +.. _cross: + +Using a cross-compiler +---------------------------------- + +If you need to provide custom LAMMPS binaries for Windows, but do not +need to do the compilation on Windows, please consider using a Linux +to Windows cross-compiler. This is how currently the Windows binary +packages are created by the LAMMPS developers. Because of that, this is +probably the currently best tested and supported way to build LAMMPS +executables for Windows. There are makefiles provided for the +traditional build system, but CMake has also been successfully tested +using the mingw32-cmake and mingw64-cmake wrappers that are bundled +with the cross-compiler environment on Fedora machines. A CMake preset +selecting all packages compatible with this cross-compilation build +is provided. You likely need to disable the GPU package unless you +download and install the contents of the pre-compiled `OpenCL ICD loader library `_ +into your MinGW64 cross-compiler environment. The cross-compilation +currently will only produce non-MPI serial binaries. + +Please keep in mind, though, that this only applies to compiling LAMMPS. +Whether the resulting binaries do work correctly is no tested by the +LAMMPS developers. We instead rely on the feedback of the users +of these pre-compiled LAMMPS packages for Windows. We will try to resolve +issues to the best of our abilities if we become aware of them. However +this is subject to time constraints and focus on HPC platforms. + +.. _native: + +Native Visual C++ support +-------------------------------------- + +Support for the Visual C++ compilers is currently not available. The +CMake build system is capable of creating suitable a Visual Studio +style build environment, but the LAMMPS code itself is not fully ported +to support Visual C++. Volunteers to take on this task are welcome. + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Commands.rst b/doc/src/Commands.rst new file mode 100644 index 0000000000000000000000000000000000000000..e845faa90318f01bb597e7547ddf8e5ecc9e640b --- /dev/null +++ b/doc/src/Commands.rst @@ -0,0 +1,34 @@ +Commands +******** + +These pages describe how a LAMMPS input script is formatted and the +commands in it are used to define a LAMMPS simulation. + + +.. toctree:: + :maxdepth: 1 + + Commands_input + Commands_parse + Commands_structure + Commands_category + +.. toctree:: + :maxdepth: 1 + + Commands_all + Commands_fix + Commands_compute + Commands_pair + Commands_bond + Commands_kspace + +.. toctree:: + :maxdepth: 1 + + Commands_removed + + +.. _lws: http://lammps.sandia.gov +.. _ld: Manual.html +.. _lc: Commands_all.html diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst new file mode 100644 index 0000000000000000000000000000000000000000..583e9e3c3ab34101585385b9e7d40d327a3ba733 --- /dev/null +++ b/doc/src/Commands_all.rst @@ -0,0 +1,59 @@ ++----------------------------------------+------------------------------------+------------------------------------------+ +| :doc:`General commands ` | :doc:`Fix styles ` | :doc:`Compute styles ` | ++----------------------------------------+------------------------------------+------------------------------------------+ +| :doc:`Pair styles ` | :doc:`Bond styles ` | :ref:`Angle styles ` | ++----------------------------------------+------------------------------------+------------------------------------------+ +| :ref:`Dihedral styles ` | :ref:`Improper styles ` | :doc:`KSpace styles ` | ++----------------------------------------+------------------------------------+------------------------------------------+ + +General commands +================ + +An alphabetic list of all general LAMMPS commands. + ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`angle\_coeff ` | :doc:`angle\_style ` | :doc:`atom\_modify ` | :doc:`atom\_style ` | :doc:`balance ` | :doc:`bond\_coeff ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`bond\_style ` | :doc:`bond\_write ` | :doc:`boundary ` | :doc:`box ` | :doc:`change\_box ` | :doc:`clear ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`comm\_modify ` | :doc:`comm\_style ` | :doc:`compute ` | :doc:`compute\_modify ` | :doc:`create\_atoms ` | :doc:`create\_bonds ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`create\_box ` | :doc:`delete\_atoms ` | :doc:`delete\_bonds ` | :doc:`dielectric ` | :doc:`dihedral\_coeff ` | :doc:`dihedral\_style ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`dimension ` | :doc:`displace\_atoms ` | :doc:`dump ` | :doc:`dump adios ` | :doc:`dump image ` | :doc:`dump movie ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`dump netcdf ` | :doc:`dump netcdf/mpiio ` | :doc:`dump vtk ` | :doc:`dump\_modify ` | :doc:`dynamical\_matrix ` | :doc:`echo ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`fix ` | :doc:`fix\_modify ` | :doc:`group ` | :doc:`group2ndx ` | :doc:`hyper ` | :doc:`if ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`info ` | :doc:`improper\_coeff ` | :doc:`improper\_style ` | :doc:`include ` | :doc:`jump ` | :doc:`kim\_init ` | ++-----------------------------------------+-----------------------------------------+-----------------------------------------+-----------------------------------------+---------------------------------------------+-----------------------------------------+ +| :doc:`kim\_interactions ` | :doc:`kim\_query ` | :doc:`kspace\_modify ` | :doc:`kspace\_style ` | :doc:`label