diff --git a/doc/src/Build.txt b/doc/src/Build.txt new file mode 100644 index 0000000000..653c217d4c --- /dev/null +++ b/doc/src/Build.txt @@ -0,0 +1,50 @@ +"Previous Section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Run.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS :h2 + +LAMMPS can be built as an executable or library from source code via +either CMake or traditional make. As an alternative you can download +a pre-built executable file as described on the "Install"_Install.html +doc page. + + + + + +"Build LAMMPS with CMake"_Build_cmake.html +"Build LAMMPS with make"_Build_make.html +"Link LAMMPS as a library to another code"_Build_link.html :all(b) + +Build options: + +"Basic build options: serial/parallel, compilers, executable/library"_Build_basics.html +"Optional build settings"_Build_settings.html :all(b) +"Include packages in build"_Build_package.html +"Packages with extra build options"_Build_extras.html :all(b) + +If you have problems building LAMMPS, it is often due to software +issues on your local machine. If you can, find a local expert to +help. If you're still stuck, send an email to the "LAMMPS mail +list"_http://lammps.sandia.gov/mail.html. diff --git a/doc/src/Build_basics.txt b/doc/src/Build_basics.txt new file mode 100644 index 0000000000..b2816b7acb --- /dev/null +++ b/doc/src/Build_basics.txt @@ -0,0 +1,318 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Basic build options :h3 + +The following topics are covered on this page, for building both with +CMake and make: + +"Serial vs parallel build"_#serial +"Choice of compiler and compile/link options"_#compile +"Build LAMMPS as an executable or a library"_#exe +"Build the LAMMPS documentation"_#doc +"Install LAMMPS after a build"_#install :ul + +:line +:line + +Serial vs parallel build :h3,link(serial) + +LAMMPS can be built to run in parallel using the ubiquitous "MPI +(message-passing +interface)"_https://en.wikipedia.org/wiki/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]: + +-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 :pre + +The executable CMake creates (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]: + +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 :pre # uses Makefile.mybox, produces lmp_mybox :pre + +Serial build (see src/MAKE/Makefile.serial): + +MPI_INC = -I../STUBS +MPI_PATH = -L../STUBS +MPI_LIB = -lmpi_stubs :pre + +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 varaibles, 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 Argonne's MPICH2 or +OpenMPI. MPICH can be downloaded from the "Argonne MPI +site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can +be downloaded from the "OpenMPI site"_http://www.open-mpi.org. 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 "Speed omp"_Speed_omp.html doc page for +details. + +However, there are a few commands in LAMMPS that have native OpenMP +support. These are commands in the MPIIO, SNAP, USER-COLVARS, and +USER-DPD packages. See the "Packages details"_Packages_details.html +doc page for more info on these packages and the doc pages for their +respective commands for OpenMP threading info. + +TODO: is this the complete list of native OpenMP commands in LAMMPS? + +For CMake, if you use BUILD_OMP=yes, then you can use these packages +and turn on their native OpenMP support at run time, by first setting +the OMP_NUM_THREADS environment variable. + +For make, ... + +TODO: how do we build LAMMPS with make, to include OpenMP support +(separate from USER-OMP package). Akin to CMake with BUILD_OMP=yes. + +:line + +Choice of compiler and compile/link options :h3,link(compile) + +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. + +:link(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]: + +-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 :pre + +-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 :pre + +By default CMake will use a compiler it finds and it will use +optimization flags appropriate to that compiler and any "accelerator +packages"_Speed_packages.html you have included in the build. + +You can tell CMake to look for a specific compiler with these varaible +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: + +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 :pre + +NOTE: When the cmake command completes, it prints info to the screen +as to what 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 low-level compiler info is +also in the output. You should check to insure you are using the +compiler and optimization flags that are the ones you want. + +[Makefile.machine settings]: + +Parallel build (see src/MAKE/Makefile.mpi): + +CC = mpicxx +CCFLAGS = -g -O3 +LINK = mpicxx +LINKFLAGS = -g -O :pre + +Serial build (see src/MAKE/Makefile.serial): + +CC = g++ +CCFLAGS = -g -O3 +LINK = g++ +LINKFLAGS = -g -O :pre + +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 "accelerator +packages"_Speed_packages.html 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 "Speed packages"_Speed_packages.html 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: + +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) :pre + +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. + +:line + +Build LAMMPS as an executable or a library :h3,link(exe) + +LAMMPS can be built as either an executable or as a static or shared +library. The library can be called from another application or a +scripting language. See the "Howto couple"_Howto_couple.html doc page +for more info on coupling LAMMPS to other codes. See the +"Python"_Python doc page for more info on wrapping and running LAMMPS +from Python. + +[CMake variables]: + +-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) :pre + +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 +static library named liblammps.so. + +[Traditional make]: + +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 :pre + +The two library builds also create generic links 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 +lib/packages, 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"_mpich, a popular open-source version of MPI, distributed by +Argonne National Labs, as a shared library in the default +/usr/local/lib location: + +:link(mpich,http://www-unix.mcs.anl.gov/mpi) + +./configure --enable-shared +make +make install :pre + +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. + +:line + +Build the LAMMPS documentation :h3,link(doc) + +[CMake variable]: + +-D BUILD_DOC=value # yes or no (default) :pre + +This will create the HTML doc pages within the CMake build dir. The +reason to do this is if you want to "install" LAMMPS on a system after +the CMake build, and include the doc pages in the install. + +[Traditional make]: + +cd lammps/doc +make html # html doc pages +make pdf # single Manual.pdf file :pre + +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 the +lammps/doc dir to see other options. + +:line + +Install LAMMPS after a build :h3,link(install) + +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 priveleges (e.g. sudo) if the place you +want to copy files to is protected. + +[CMake variable]: + +cmake CMAKE_INSTALL_PREFIX=path \[options ...\] ~/lammps/cmake +make # perform make after CMake command +make install # perform the installation :pre + +Note that The CMAKE_INSTALL_PREFIX=path is not a -D variable like +other LAMMPS settings, but rather an option to the cmake command. The +path is where to install the LAMMPS files. + +TODO: is this sub-section correct? + +[Traditional make]: + +There is no "install" option in the src/Makefile for LAMMPS. If you +wish to do this you will need to build, then manually copy the +desired LAMMPS files to the appopriate system directories. diff --git a/doc/src/Build_cmake.txt b/doc/src/Build_cmake.txt new file mode 100644 index 0000000000..2bc10d1463 --- /dev/null +++ b/doc/src/Build_cmake.txt @@ -0,0 +1,159 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS with CMake :h3 + +This page is a short summary of how to use CMake to build LAMMPS. +Specific details on CMake variables that enable LAMMPS build options +are given on the pages linked to from the "Build"_Build.html 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: + +"Bulding LAMMPS using +CMake"_https://github.com/rbberger/lammps/tree/cmake_documentation/cmake + +:line + +Building LAMMPS with CMake is a two-step process. First use CMake to +create a Makefile. Then use the standard make command to build +LAMMPS, which uses the created Makefile. + +mkdir mydir; cd mydir # create a new dir for build +cmake ~/lammps/cmake \[options ...\] # command-line version +ccmake ~/lammps/cmake # curses version (terminal-style menu) +cmake-gui ~/lammps/cmake # GUI version +make # traditional make command +make install # optional, copy LAMMPS executable & library elsewhere :pre + +The make command will compile and link LAMMPS, producing the +executable lmp and the library liblammps.a in mydir. + +If your machine has multiple cores (most do), using a command like +"make -j" will be much faster. + +:line + +There are 3 variants of CMake: a command-line verison, a curses +version (teminal-style menu), and a GUI version. You can use any of +them to build LAMMPS. 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 "Build"_Build.html doc page. + +Perform the build in a new directory you create. It can be a sub-dir +within lammps/cmake or anywhere you wish. You can perform separate +builds, with different options, in as many directories as you like. +All the auxiliary files created by the build (executable, object +files, log files, etc) are stored in that directory or sub-directories +within it that CMake creates. + +NOTE: To perform a CMake build, no packages can be installed in the +LAMMPS src dir. Likewise no style*.h or a lmpinstalledpkgs.h file can +exist, which are auto-generated by "building LAMMPS via traditional +make"_Build_make.html. CMake detects if this is not 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 +auto-generated *.h files. + +You must have CMake version 2.8 or later on your system to build +LAMMPS. If you include the GPU package, version 3.2 or later 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 remove the +cache file CMakeCache.txt in the build directory and start over. Or +you can run cmake again from the same build directory and alter +various options; see details below. + +:line + +[Command-line version of CMake]: + +cmake \[options ...\] ~/lammps/cmake # build from any dir +cmake \[options ...\] .. # build from lammps/cmake/newdir :pre + +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: + +CAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired +CMAKE_BUILD_TYPE=type # type = Release 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 + +All the LAMMPS-specific -D variables that a LAMMPS build supports are +described on the pages linked to from the "Build"_Build.html 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. + +By default CMake generates a Makefile 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. 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 scan this to verify all the features you requested were +enabled, including packages. You can also see what compiler and +compile options will be used for the build. Any errors 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 running CMake again from the same directory will +inherit those settings. + +TODO: explain how to change settings on a subsequent cmake in the same +build dir. In that case is "." the final arg of cmake? + +[Curses version (terminal-style menu) of CMake]: + +ccmake ~/lammps/cmake :pre + +TODO: give brief explanation of how to find and toggle options, how to +perform the generate, how to use it multiple times. + +[GUI version of CMake]: + +cmake-gui ~/lammps/cmake :pre + +TODO: give brief explanation of how to find and toggle options, how to +perform the generate, how to use it multiple times. + +:line + +[Installing CMake] + +Check if your machine already has CMake installed: + +which cmake # do you have it? +which cmake3 # version 3 may have this name +cmake --version # what specific version you have :pre + +On clusters or supercomputers which use modules to manage software +packages, do this: + +module list # is a cmake module is already loaded +module avail # is a cmake module available? +module load cmake3 # load cmake module with appropriate name :pre + +If you do not have CMake or a new enough version, you can install it +as follows: + +TODO: give install instructions for Linux, Mac, Windows + diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt new file mode 100644 index 0000000000..82f720791d --- /dev/null +++ b/doc/src/Build_extras.txt @@ -0,0 +1,803 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Packages with extra build options :h3 + +When building with some packages, additional steps may be required, +beyond just "-D PKG_NAME=yes" for CMake or "make yes-name" for make, +as described on the "Build_package"_Build_package.html doc page. + +For a CMake build there may be additional variables that can be 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 be downloaded and built, and you may need to tell LAMMPS where it +is found on your system. + +This is the list of packages that may require additional steps. + +"GPU"_#gpu, +"KIM"_#kim, +"KOKKOS"_#kokkos, +"LATTE"_#latte, +"MEAM"_#meam, +"MSCG"_#mscg, +"OPT"_#opt, +"POEMS"_#poems, +"PYTHON"_#python, +"REAX"_#reax, +"VORONOI"_#voronoi, +"USER-ATC"_#user-atc, +"USER-AWPMD"_#user-awpmd, +"USER-COLVARS"_#user-colvars, +"USER-H5MD"_#user-h5md, +"USER-INTEL"_#user-intel, +"USER-MOLFILE"_#user-molfile, +"USER-NETCDF"_#user-netcdf, +"USER-OMP"_#user-omp, +"USER-QMMM"_#user-qmmm, +"USER-QUIP"_#user-quip, +"USER-SMD"_#user-smd, +"USER-VTK"_#user-vtk :tb(c=6,ea=c) + +:line +:line + +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: + +-D ZLIB_INCLUDE_DIR=path # path to zlib.h header file +-D ZLIB_LIBRARIES=path # path to libzlib.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. + +:line + +GPU package :h3,link(gpu) + +To build with this package, you need to choose options for precision +and which GPU hardware to build for. To build with make you also need +to build the library in lib/gpu first. + +[CMake build]: + +-D GPU_API=value # value = opencl (default) or cuda +-D GPU_PREC=value # precision setting + # value = single or mixed (default) or double +-D OCL_TUNE=value # hardware choice for GPU_API=opencl + # generic (default) or intel (Intel CPU) or phi (Intel Xeon Phi) or fermi (NVIDIA) or kepler (NVIDIA) or cypress (NVIDIA) +-D GPU_ARCH=value # hardware choice for GPU_API=cuda + # value = sm20 (Fermi) or sm30 (Kepler) or sm50 (Maxwell) or sm60 (Pascal) or sm70 (Volta) + # default is Cuda-compiler dependent, but typically Fermi +-D CUDPP_OPT=value # optimization setting for GPU_API=cudea + # enables CUDA Performance Primitives Optimizations + # on (default) or off + +[Traditional make]: + +You must first 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: + +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 -p mixed -b" # build GPU library with mixed precision using settings in Makefile.mpi :pre + +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 -h, -a, -p, -e switches, and +also save a copy of the new Makefile, if desired: + +CUDA_HOME = where NVIDIA CUDA software is installed on your system +CUDA_ARCH = what GPU hardware you have (see help message for details) +CUDA_PRECISION = precision (double, mixed, single) +EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps :ul + +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, then re-install it and re-build LAMMPS. +This is because the compilation of files in the GPU package use the +library settings from the lib/gpu/Makefile.machine used to build the +GPU library. + +:line + +KIM package :h3,link(kim) + +To build with this package, the KIM library must be downloaded and +built on your system. It must include the KIM models that you want to +use with LAMMPS. + +Note that in LAMMPS lingo, a KIM model driver is a pair style +(e.g. EAM or Tersoff). A KIM model is a pair style for a particular +element or alloy and set of parameters, e.g. EAM for Cu with a +specific EAM potential file. Also note that installing the KIM API +library with all its models, may take around 30 min to build. Of +course you only need to do that once. + +See the list of KIM model drivers here: +https://openkim.org/kim-items/model-drivers/alphabetical + +See the list of all KIM models here: +https://openkim.org/kim-items/models/by-model-drivers + +See the list of example KIM models included by default here: +https://openkim.org/kim-api on the "What is in the KIM API source +package?" page. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +You can do 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. + +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/kim-api" # use an existing KIM API installation at the provided location +make lib-kim args="-p /usr/local/kim-api -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver :pre + +:line + +KOKKOS package :h3,link(kokkos) + +To build with this package, you have to choose a Kokkos setting for +either CPU (multi-threading via OpenMP) or KNL (OpenMP) or GPU (Cuda) +support. + +[CMake build]: + +TODO: how to do this, how to select CPU vs KNL vs GPU, and other +traditional make settings + +[Traditional make]: + + how to choose these 3 things: mode archgpu=N archcpu=SNB + mode = omp or cuda or phi (def = KOKKOS_DEVICES setting in Makefile ) + archgpu = number like 35 (Kepler) or 21 (Fermi) (def = none) + sets KOKKOS_ARCH for GPU to appropriate value + archcpu = SNB or HSW or BGQ or Power7 or Power8 (def = none) + for CPU = SandyBridge, Haswell, BGQ, Power7, Power8 + sets KOKKOS_ARCH for GPU to appropriate value + +For the KOKKOS package, you have 3 choices when building. You can +build with either CPU or KNL or GPU support. Each choice requires +additional settings in your Makefile.machine for the KOKKOS_DEVICES +and KOKKOS_ARCH settings. See the src/MAKE/OPTIONS/Makefile.kokkos* +files for examples. + +For multicore CPUs using OpenMP: + +KOKKOS_DEVICES = OpenMP +KOKKOS_ARCH = HSW # HSW = Haswell, SNB = SandyBridge, BDW = Broadwell, etc :pre + +For Intel KNLs using OpenMP: + +KOKKOS_DEVICES = OpenMP +KOKKOS_ARCH = KNL :pre + +For NVIDIA GPUs using CUDA: + +KOKKOS_DEVICES = Cuda +KOKKOS_ARCH = Pascal60,Power8 # P100 hosted by an IBM Power8, etc +KOKKOS_ARCH = Kepler37,Power8 # K80 hosted by an IBM Power8, etc :pre + +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 or use a C++ compiler for non-Kokkos, non-CUDA +files. + +KOKKOS_ABSOLUTE_PATH = $(shell cd $(KOKKOS_PATH); pwd) +export OMPI_CXX = $(KOKKOS_ABSOLUTE_PATH)/config/nvcc_wrapper +CC = mpicxx :pre + +Once you have an appropriate Makefile.machine, you can +install/un-install the package and build LAMMPS in the usual manner. +Note that you cannot build one executable to run on multiple hardware +targets (CPU or KNL or GPU). You need to build LAMMPS once for each +hardware target, to produce a separate executable. Also note that we +do not recommend building with other acceleration packages installed +(GPU, OPT, USER-INTEL, USER-OMP) when also building with KOKKOS. + +:line + +LATTE package :h3,link(latte) + +To build with this package, you must download and build the LATTE +library. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +You can do this manually if you prefer; follow the instructions in +lib/latte/README. You can also do it in one step from the lammps/src +dir, using a command like these, which simply invokes the +lib/latte/Install.py script with the specified args: + +make lib-latte # print help message +make lib-latte args="-b" # download and build in lib/latte/LATTE-master +make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte +make lib-latte args="-b -m gfortran" # download and build in lib/latte and + # copy Makefile.lammps.gfortran to Makefile.lammps +:pre + +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 builds in src 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. + +:line + +MEAM package :h3,link(meam) + +NOTE: You should test building the MEAM library with both the Intel +and GNU compilers to see if a simulation runs faster with one versus +the other on your system. + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +MEAM library in lib/meam. You can do this manually if you prefer; +follow the instructions in lib/meam/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/meam/Install.py script with the specified args: + +make lib-meam # print help message +make lib-meam args="-m mpi" # build with default Fortran compiler compatible with your MPI library +make lib-meam args="-m serial" # build with compiler compatible with "make serial" (GNU Fortran) +make lib-meam args="-m ifort" # build with Intel Fortran compiler using Makefile.ifort :pre + +The build should produce two files: lib/meam/libmeam.a and +lib/meam/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with +Fortran (MEAM library). Typically the two compilers used for LAMMPS +and the MEAM library need to be consistent (e.g. both Intel or both +GNU compilers). If necessary, you can edit/create a new +lib/meam/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +:line + +MSCG package :h3,link(mscg) + +Before building LAMMPS with this package, you must first download and +build the MS-CG library. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +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. + +Assuming these libraries are in place, you can do the download and +build of MS-CG manually if you prefer; follow the instructions in +lib/mscg/README. You can also do it in one step from the lammps/src +dir, using a command like these, which simply invoke the +lib/mscg/Install.py script with the specified args: + +make lib-mscg # print help message +make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make serial" +make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master + # with the settings compatible with "make mpi" +make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release :pre + +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. + +:line + +OPT package :h3,link(opt) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +NOTE: 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 Makefile.opt in +src/MAKE/OPTIONS for an example. + +CCFLAGS: add -restrict for Intel compilers :ul + +:line + +POEMS package :h3,link(poems) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +POEMS library in lib/poems. You can do this manually if you prefer; +follow the instructions in lib/poems/README. You can also do it in +one step from the lammps/src dir, using a command like these, which +simply invoke the lib/poems/Install.py script with the specified args: + +make lib-poems # print help message +make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial") +make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi") +make lib-poems args="-m icc" # build with Intel icc compiler :pre + +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. + +:line + +PYTHON package :h3,link(python) + +Building with the PYTHON package assumes 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 the +lib/python/README for more details. + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +The build uses the lib/python/Makefile.lammps file in the compile/link +process. You should only need to create a new Makefile.lammps.* file +(and copy it to Makefile.lammps) if the LAMMPS build fails. + +:line + +REAX package :h3,link(reax) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +REAX library in lib/reax. You can do this manually if you prefer; +follow the instructions in lib/reax/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/reax/Install.py script with the specified args: + +make lib-reax # print help message +make lib-reax args="-m serial" # build with GNU Fortran compiler (settings as with "make serial") +make lib-reax args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi") +make lib-reax args="-m ifort" # build with Intel ifort compiler :pre + +The build should produce two files: lib/reax/libreax.a and +lib/reax/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to link C++ (LAMMPS) with +Fortran (REAX library). Typically the two compilers used for LAMMPS +and the REAX library need to be consistent (e.g. both Intel or both +GNU compilers). If necessary, you can edit/create a new +lib/reax/Makefile.machine file for your system, which should define an +EXTRAMAKE variable to specify a corresponding Makefile.lammps.machine +file. + +:line + +VORONOI package :h3,link(voronoi) + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Before building LAMMPS with this package, you must first download and +build the Voro++ library. You can do this 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: + +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 :pre + +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. + +:line +:line + +USER-ATC package :h3,link(user-atc) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the ATC +library in lib/atc. You can do this manually if you prefer; follow +the instructions in lib/atc/README. You can also do it in one step +from the lammps/src dir, using a command like these, which simply +invoke the lib/atc/Install.py script with the specified args: + +make lib-atc # print help message +make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") +make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-atc args="-m icc" # build with Intel icc compiler :pre + +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: + +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 :pre + + +:line + +USER-AWPMD package :h3,link(user-awpmd) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +AWPMD library in lib/awpmd. You can do this manually if you prefer; +follow the instructions in lib/awpmd/README. You can also do it in +one step from the lammps/src dir, using a command like these, which +simply invoke the lib/awpmd/Install.py script with the specified args: + +make lib-awpmd # print help message +make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial") +make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-awpmd args="-m icc" # build with Intel icc compiler :pre + +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: + +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 :pre + +:line + +USER-COLVARS package :h3,link(user-colvars) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +COLVARS library in lib/colvars. You can do this manually if you +prefer; follow the instructions in lib/colvars/README. You can also +do it in one step from the lammps/src dir, using a command like these, +which simply invoke the lib/colvars/Install.py script with the +specified args: + +make lib-colvars # print help message +make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial") +make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi") +make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled :pre + +The build should produce two files: lib/colvars/libcolvars.a and +lib/colvars/Makefile.lammps. The latter is copied from an existing +Makefile.lammps.* and has settings needed to build LAMMPS with the +COLVARS library (though typically the settings are just blank). If +necessary, you can edit/create a new lib/colvars/Makefile.machine file +for your system, which should define an EXTRAMAKE variable to specify +a corresponding Makefile.lammps.machine file. + +:line + +USER-H5MD package :h3,link(user-h5md) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that to follow these steps to compile and link to the CH5MD +library, you need the standard HDF5 software package installed on your +system, which should include the h5cc compiler and the HDF5 library. + +Before building LAMMPS with this package, you must first build the +CH5MD library in lib/h5md. You can do this manually if you prefer; +follow the instructions in lib/h5md/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/h5md/Install.py script with the specified args: + +make lib-h5md # print help message +make lib-hm5d args="-m h5cc" # build with h5cc compiler :pre + +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. + +:line + +USER-INTEL package :h3,link(user-intel) + +[CMake build]: + +TODO: how to choose CPU vs KNL ?? + +[Traditional make]: + +For the USER-INTEL package, you have 2 choices when building. You can +build with either CPU or KNL support. Each choice requires additional +settings in your Makefile.machine for CCFLAGS and LINKFLAGS and +optimized malloc libraries. See the +src/MAKE/OPTIONS/Makefile.intel_cpu and src/MAKE/OPTIONS/Makefile.knl +files for examples. + +For CPUs: + +OPTFLAGS = -xHost -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 -ltbbmalloc_proxy :pre + +For KNLs: + +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 :pre + +Once you have an appropriate Makefile.machine, you can +install/un-install the package and build LAMMPS in the usual manner. +Note that you cannot build one executable to run on multiple hardware +targets (Intel CPUs or KNL). You need to build LAMMPS once for each +hardware target, to produce a separate executable. + +You should also typically install the USER-OMP package, as it can be +used in tandem with the USER-INTEL package to good effect, as +explained on the "Speed intel"_Speed_intel.html doc page. + +:line + +USER-MOLFILE package :h3,link(user-molfile) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that the lib/molfile/Makefile.lammps file has a setting for a +dynamic loading library libdl.a that should is typically present on +all systems, which 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. + +:line + +USER-NETCDF package :h3,link(user-netcdf) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +Note that to follow these steps, you need the standard NetCDF software +package installed on your system. The lib/netcdf/Makefile.lammps file +has settings for NetCDF include and library files that LAMMPS needs to +compile and linkk 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. + +:line + +USER-OMP package :h3,link(user-omp) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +CCFLAGS: add -fopenmp (and -restrict when using Intel compilers) +LINKFLAGS: add -fopenmp :ul + +:line + +USER-QMMM package :h3,link(user-qmmm) + +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 which links LAMMPS and Quantum ESPRESSO together. +These are steps 3 and 4 described in the lib/qmmm/README file. + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Before building LAMMPS with this package, you must first build the +QMMM library in lib/qmmm. You can do this manually if you prefer; +follow the first two steps explained in lib/qmmm/README. You can +also do it in one step from the lammps/src dir, using a command like +these, which simply invoke the lib/qmmm/Install.py script with the +specified args: + +make lib-qmmm # print help message +make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial") +make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi") +make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler :pre + +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/un-install the package and build LAMMPS in the +usual manner: + +:line + +USER-QUIP package :h3,link(user-quip) + +[CMake build]: + +TODO: how to do this + +[Traditional make]: + +Note that to follow these steps to compile and link to the QUIP +library, you must first download and build QUIP on your systems. It +can be obtained from GitHub. See step 1 and step 1.1 in the +lib/quip/README file for details on how to do this. Note that it +requires setting two environment variables, QUIP_ROOT and QUIP_ARCH, +which will be 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 this file if the LAMMPS build can not use its +settings to successfully build on your system. + +:line + +USER-SMD package :h3,link(user-smd) + +[CMake build]: + +-D EIGEN3_INCLUDE_DIR + +[Traditional make]: + +Before building LAMMPS with this package, you must first download the +Eigen library. Eigen is a template library, so you do not need to +build it, just download it. You can do this manually if you prefer; +follow the instructions in lib/smd/README. You can also do it in one +step from the lammps/src dir, using a command like these, which simply +invoke the lib/smd/Install.py script with the specified args: + +make lib-smd # print help message +make lib-smd args="-b" # download and build in default lib/smd/eigen-eigen-... +make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3 :pre + +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. + +You can then install/un-install the package and build LAMMPS in the +usual manner: + +:line + +USER-VTK package :h3,link(user-vtk) + +[CMake build]: + +TODO: automatic, i.e. nothing to do? + +[Traditional make]: + +The lib/vtk/Makefile.lammps file has settings for accessing VTK files +and its library, which are required for LAMMPS to build and link 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. + +You can then install/un-install the package and build LAMMPS in the +usual manner: diff --git a/doc/src/Build_link.txt b/doc/src/Build_link.txt new file mode 100644 index 0000000000..1a1b387f3f --- /dev/null +++ b/doc/src/Build_link.txt @@ -0,0 +1,85 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Link LAMMPS as a library to another code :h3 + +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 "Howto +library"_Howto_library.html doc page for a description of the +interface and how to extend it for your needs. + +The "Build basics"_Build_basics.html 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 + +:line + +[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. + +:line + +[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 + +printenv LD_LIBRARY_PATH :pre + +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: + +setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre + +:line + +[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 "Python library"_Python_library.html 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 thru its library interface. +Other examples in the COUPLE directory use coupling ideas discussed on +the "Howto couple"_Howto_couple.html doc page. + + diff --git a/doc/src/Build_make.txt b/doc/src/Build_make.txt new file mode 100644 index 0000000000..4603a986a3 --- /dev/null +++ b/doc/src/Build_make.txt @@ -0,0 +1,66 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Build LAMMPS with make :h3 + +Building LAMMPS with traditional make requires you have a +Makefile.machine file in the src/MAKE directory appropriate for your +system (see below). It can list various options for what to +include/exclude in a LAMMPS build. To include LAMMPS packages you +must install them first, as discussed on the "Build +package"_Build_package.html doc page. If the packages use provided or +external libraries, you must build those libraries before building +LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html can automate +all of this, 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: + +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 :pre + +If your machine has multiple cores (most do), using a command like +"make -j mpi" will be much faster. + +After the initial build, if you edit LAMMPS source files, or add new +files to the source directory, you can re-type make and it will only +re-compile the files that have changed. + +:line + +The lammps/src/MAKE directory 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: + +OPTIONS # Makefiles which enable specific options +MACHINES # Makefiles for specific machines +MINE # customized Makefiles you create :pre + +Typing "make" lists all the available Makefile.machine files. A file +with the same name can appear in multiple dirs (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: + +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 :pre diff --git a/doc/src/Build_package.txt b/doc/src/Build_package.txt new file mode 100644 index 0000000000..e59bf2b9d6 --- /dev/null +++ b/doc/src/Build_package.txt @@ -0,0 +1,182 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Include packages in build :h3 + +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. + +A complete list of packages with brief overviews of each are on the +"Packages details"_Packages_details.html 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 the package. Running LAMMPS with the +"-h command-line switch"_Run_options.html will print all the included +packages and commands for that executable. + +The mechanism for including packages is different for CMake versus a +traditional make. + +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 "Build extras"_Build_extras.html doc page. + +These links take you to the extra instructions for those select +packages: + +"GPU"_Build_extras.html#gpu, +"KIM"_Build_extras.html#kim, +"KOKKOS"_Build_extras.html#kokkos, +"LATTE"_Build_extras.html#latte, +"MEAM"_Build_extras.html#meam, +"MSCG"_Build_extras.html#mscg, +"OPT"_Build_extras.html#opt, +"POEMS"_Build_extras.html#poems, +"PYTHON"_Build_extras.html#python, +"REAX"_Build_extras.html#reax, +"VORONOI"_Build_extras.html#voronoi, +"USER-ATC"_Build_extras.html#user-atc, +"USER-AWPMD"_Build_extras.html#user-awpmd, +"USER-COLVARS"_Build_extras.html#user-colvars, +"USER-H5MD"_Build_extras.html#user-h5md, +"USER-INTEL"_Build_extras.html#user-intel, +"USER-MOLFILE"_Build_extras.html#user-molfile, +"USER-NETCDF"_Build_extras.html#user-netcdf, +"USER-OMP"_Build_extras.html#user-omp, +"USER-QMMM"_Build_extras.html#user-qmmm, +"USER-QUIP"_Build_extras.html#user-quip, +"USER-SMD"_Build_extras.html#user-smd, +"USER-VTK"_Build_extras.html#user-vtk :tb(c=6,ea=c) + +[CMake variables]: + +-D PKG_NAME=value # yes or no (default) :pre + +Examples: + +-D PKG_MANYBODY=yes +-D PKG_USER-INTEL=yes :pre + +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. + +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]: + +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 :pre + +Examples: + +make no-rigid +make yes-user-intel :pre + +All standard and user packages are included the same way. + +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. + +NOTE: The one exception is that for a build via make (ok via CMake), +we do not recommend building with the KOKKOS package installed along +with any of the other acceleration packages (GPU, OPT, USER-INTEL, +USER-OMP) also installed. This is because of how Kokkos sometimes +builds using a wrapper compiler which can make it difficult to invoke +all the compile/link flags correctly for both Kokkos and non-Kokkos +files. + +When you download a LAMMPS tarball, three packages are pre-installed +in the src directory: KSPACE, MANYBODY, MOLECULE. This is because +they are so commonly used. When you download LAMMPS source files from +the Git or SVN repositories, no packages are pre-installed. + +:line + +The following make 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 :tb(s=|,a=l) + +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 +"installing a patch"_Install_patch.html 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 "patch has been applied"_Install_patch.html, +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. diff --git a/doc/src/Build_settings.txt b/doc/src/Build_settings.txt new file mode 100644 index 0000000000..1969e9588b --- /dev/null +++ b/doc/src/Build_settings.txt @@ -0,0 +1,327 @@ +"Higher level section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Optional build settings :h3 + +LAMMPS can be built with several optional settings. Each sub-section +explain how to do this for either a CMake build or traditional make. + +"FFT library"_#fft for use with "kspace_style pppm"_kspace_style.html command +"Size of LAMMPS data types"_#size +"Read or write compressed files"_#compress +"Output of JPG and PNG files"_#graphics via "dump image"_dump_image.html command +"Output of movie files"_#graphics via "dump_movie"_dump_image.html command +"Memory allocation alignment"_#align +"Workaround for long long integers"_#longlong +"Error handling exceptions"_#exceptions when using LAMMPS as a library :all(b) + +:line +:line + +FFT library :h3,link(fft) + +When the KSPACE package is included in a LAMMPS build, the +"kspace_style pppm"_kspace_style.html 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 are typically +faster if they are available on your system. See details on other FFT +libraries below. + +[CMake variables]: + +-D FFT=value # kiss or fftw3 or fftw2 or mkl, 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 :pre + +Usually these settings are all that is needed. If CMake cannot find +the FFT library, you can set these variables: + +-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files +-D FFTW2_LIBRARIES=path # path to FFTW3 libraries +-D FFTW2_INCLUDE_DIRS=path # ditto for FFTW2 +-D FFTW3_LIBRARIES=path +-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library +-D MKL_LIBRARIES=path :pre + +[Makefile.machine settings]: + +FFT_INC = -DFFT_FFTW3 # FFTW3, FFTW2, FFTW (same as FFTW3), MKL, or 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 :pre + +TODO: change code to use FFT_PACK_OPTION + +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 = -lfftw # FFTW2 double precision, or -ldfftw +FFT_LIB = -lsfftw # FFTW2 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 :pre + +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"_http://kissfft.sf.net is included in the LAMMPS +distribution, so not FFT_LIB setting is required. It is portable +across all platforms. + +FFTW is fast, portable library that should also work on any platform +and typically be faster than KISS FFT. You can download it from +"www.fftw.org"_http://www.fftw.org. Both the legacy version 2.1.X and +the newer 3.X versions are 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). + +3d FFTs can be computationally expensive. Their 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 precesion means they are 8-byte doubles. +Note that Fourier transform and related PPPM operations are somewhat +insensitive to floating point truncation errors and thus do not always +need to be performed in double precision. Using this 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 or FFTW2, 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 + +make clean +./configure --enable-single; make; make install :pre + +For FFTW2, do the following, which should produce the additional +library libsfftw.a + +make clean +./configure --enable-float --enable-type-prefix; make; make install :pre + +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. + +:line + +Size of LAMMPS data types :h3,link(size) + +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]: + +-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :pre + +[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 :ul + +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) :ul + +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) :ul + +Atom IDs are not required for atomic systems which do not store bond +topology information, though IDs are enabled by default. The +"atom_modify id no"_atom_modify.html 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 +"dump"_dump.html 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 "compute +msd"_compute_msd.html command, to be faulty. + +Note that the USER-ATC package is not currently compatible with the +"bigbig" setting. + +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. + +:line + +Output of JPG, PNG, and movie files :h3,link(graphics) + +The "dump image"_dump_image.html command has options to output JPEG or +PNG image files. Likewise the "dump movie"_dump_image.html command +ouputs movie files in MPEG format. Using these options requires the +following settings: + +[CMake variables]: + +-D LAMMPS_JPEG=value # yes or no + # default = yes if CMake finds JPEG files, else no +-D LAMMPS_PNG=value # yes or no + # default = yes if CMake finds PNG and ZLIB files, else no +-D LAMMPS_FFMPEG=value # yes or no + # default = yes if CMake can find ffmpeg, else no :pre + +Usually these settings are all that is needed. If CMake cannot find +the graphics header, library, executuable files, you can set these +variables: + +-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 libzlib.a (.so) file +-D FFMPEG_EXECUTABLE=path # path to ffmpeg executable :pre + +[Makefile.machine settings]: + +LMP_INC = -DLAMMPS_JPEG +LMP_INC = -DLAMMPS_PNG +LMP_INC = -DLAMMPS_FFMPEG :pre + +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, libzlib.a (.so) files if make cannot find them +JPG_LIB = -ljpeg -lpng -lzlib # library names :pre + +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. + +:line + +Read or write compressed files :h3,link(compress) + +If this option is enabled, large files can be read or written with +gzip compression by several LAMMPS commands, including +"read_data"_read_data.html, "rerun"_rerun.html, and "dump"_dump.html. + +[CMake variables]: + +-D LAMMPS_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]: + +LMP_INC = -DLAMMPS_GZIP :pre + +[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 "COMPRESS package"_Packages.html enables. + +:line + +Memory allocation alignment :h3,link(align) + +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. + +[CMake variable]: + +-D LAMMPS_MEMALIGN=value # 8, 16, 32, 64 (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 :pre + +TODO: I think the make default (no LAMMPS_MEMALIGN) is to not +use posix_memalign(), just malloc(). Does a CMake build have +an equivalent option? I.e. none. + +:line + +Workaround for long long integers :h3,link(longlong) + +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]: + +-D LAMMPS_LONGLONG_TO_LONG=value # yes or no (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_LONGLONG_TO_LONG :pre + +:line + +Exception handling when using LAMMPS as a library :h3,link(exceptions) + +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]: + +-D LAMMPS_EXCEPTIONS=value # yes or no (default) :pre + +[Makefile.machine setting]: + +LMP_INC = -DLAMMPS_EXCEPTIONS :pre diff --git a/doc/src/Install.txt b/doc/src/Install.txt new file mode 100644 index 0000000000..d59c23d319 --- /dev/null +++ b/doc/src/Install.txt @@ -0,0 +1,64 @@ +"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next Section"_Build.html +:c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Install LAMMPS :h2 + +You can download LAMMPS as an executable or as source code. + +With source code, you also have to "build LAMMPS"_Build.html. But you +have more flexibility as to what features to include or exclude in the +build. If you plan to "modify or extend LAMMPS"_Modify.html, then you +need the source code. + + + + + +"Download an executable for Linux"_Install_linux.html +"Download an executable for Mac"_Install_mac.html +"Download an executable for Windows"_Install_windows.html :all(b) + +"Download source as a tarball"_Install_tarball.html +"Donwload source via Git"_Install_git.html +"Donwload source via SVN"_Install_svn.html +"Install patch files"_Install_patch.html :all(b) + + + +These are the files and sub-directories in the LAMMPS distribution: + +README: text file +LICENSE: GNU General Public License (GPL) +bench: benchmark problems +cmake: CMake build files +doc: documentation +examples: simple test problems +lib: additional provided or external libraries +potentials: interatomic potential files +python: Python wrapper on LAMMPS +src: source files +tools: pre- and post-processing tools :tb(s=:,a=l) + +You will have all of these if you download source. You will only have +some of them if you download executables, as explained on the pages +listed above. diff --git a/doc/src/Install_git.txt b/doc/src/Install_git.txt new file mode 100644 index 0000000000..1d043c30d2 --- /dev/null +++ b/doc/src/Install_git.txt @@ -0,0 +1,120 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source via Git :h3 + +All LAMMPS development is coordinated through the "LAMMPS GitHub +site". If you clone the LAMMPS repository onto your local machine, it +has several advantages: + +You can stay current with changes to LAMMPS with a single git +command. :ulb,l + +You can create your own development branches to add code to LAMMPS. :l + +You can submit your new features back to GitHub for inclusion in +LAMMPS. :l,ule + +You must have "Git"_git installed on your system to communicate with +the public Git server for LAMMPS. + +IMPORTANT NOTE: As of Oct 2016, the official home of public LAMMPS +development is on GitHub. The previously advertised LAMMPS git +repositories on git.lammps.org and bitbucket.org are now deprecated, +may not be up-to-date, and may go away at any time. + +:link(git,http://git-scm.com) + +You can follow LAMMPS development on 3 different Git branches: + +[stable] : this branch is updated with every stable release +[unstable] : this branch is updated with every patch release +[master] : this branch continuously follows ongoing development :ul + +To access the Git repositories on your box, use the clone command to +create a local copy of the LAMMPS repository with a command like: + +git clone -b unstable https://github.com/lammps/lammps.git mylammps :pre + +where "mylammps" is the name of the directory you wish to create on +your machine and "unstable" is one of the 3 branches listed above. +(Note that you actually download all 3 branches; you can switch +between them at any time using "git checkout ".) + +Once the command completes, your directory will contain the same files +as if you unpacked a current LAMMPS tarball, with two exceptions: + +1) No LAMMPS packages are initially installed in the src dir (a few +packages are installed by default in the tarball src dir). You can +install whichever packages you wish before building LAMMPS; type "make +package" from the src dir to see the options, and the +"Packages"_Packages.html doc page for a discussion of packages. + +2) The HTML documentation files are not included. They can be fetched +from the LAMMPS website by typing "make fetch" in the doc directory. +Or they can be generated from the content provided in doc/src by +typing "make html" from the the doc directory. + +After initial cloning, as bug fixes and new features are added to +LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by +typing the following Git commands from within the "mylammps" +directory: + +git checkout unstable # not needed if you always stay in this branch +git checkout stable # use one of the 3 checkout commands +git checkout master +git pull :pre + +Doing a "pull" will not change any files you have added to the LAMMPS +directory structure. It will also not change any existing LAMMPS +files you have edited, unless those files have changed in the +repository. In that case, Git will attempt to merge the new +repository file with your version of the file and tell you if there +are any conflicts. See the Git documentation for details. + +If you want to access a particular previous release version of LAMMPS, +you can instead "checkout" any version with a published tag. See the +output of "git tag -l" for the list of tags. The Git command to do +this is as follows. + +git checkout tagID :pre + +Stable versions and what tagID to use for a particular stable version +are discussed on "this page"_bug.html. Note that this command will +print some warnings, because in order to get back to the latest +revision and to be able to update with "git pull" again, you first +will need to first type "git checkout unstable" (or check out any +other desired branch). + +Once you have updated your local files with a "git pull" (or "git +checkout"), you still need to re-build LAMMPS if any source files have +changed. To do this, you should cd to the src directory and type: + +make purge # remove any deprecated src files +make package-update # sync package files with src files +make foo # re-build for your machine (mpi, serial, etc) :pre + +just as described on the "Install patch"_Install_patch.html doc page, +after a patch has been installed. + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-directory with src, then re-install the package. The version in +the src dir is merely a copy and will be wiped out if you type "make +package-update". + +IMPORTANT NOTE: The GitHub servers support both the "git://" and +"https://" access protocols for anonymous read-only access. If you +have a correspondingly configured GitHub account, you may also use SSH +with "git@github.com:/lammps/lammps.git". + +The LAMMPS GitHub project is managed by Christoph Junghans (LANL, +junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at +gmail.com) and Richard Berger (Temple U, richard.berger at +temple.edu). diff --git a/doc/src/Install_linux.txt b/doc/src/Install_linux.txt new file mode 100644 index 0000000000..10da3d933f --- /dev/null +++ b/doc/src/Install_linux.txt @@ -0,0 +1,120 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Linux :h3 + +Binaries are available for many different versions of Linux: + +"Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE"_#rpm +"Pre-built Ubuntu Linux executables"_#unbuntu +"Pre-built Gentoo Linux executable"_#gentoo :all(b) + +:line +:line + +Pre-built binary RPMs for Fedora/RedHat/CentOS/openSUSE :h4,link(rpm) + +Pre-built LAMMPS executables for various Linux distributions +can be downloaded as binary RPM files from this site: + +"http://rpm.lammps.org"_http://rpm.lammps.org + +There are multiple package variants supporting serial, parallel and +Python wrapper versions. The LAMMPS binaries contain all optional +packages included in the source distribution except: GPU, KIM, REAX, +and USER-INTEL. + +Installation instructions for the various versions are here: + +"http://rpm.lammps.org/install.html"_http://rpm.lammps.org/install.html + +The instructions show how to enable the repository in the respective +system's package management system. Installing and updating are then +straightforward and automatic. + +Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting +up this RPM capability. + +:line + +Pre-built Ubuntu Linux executables :h4,link(ubuntu) + +A pre-built LAMMPS executable suitable for running on the latest +Ubuntu Linux versions, can be downloaded as a Debian package. This +allows you to install LAMMPS with a single command, and stay +up-to-date with the current version of LAMMPS by simply updating your +operating system. + +To install the appropriate personal-package archive (PPA), do the +following once: + +sudo add-apt-repository ppa:gladky-anton/lammps +sudo apt-get update :pre + +To install LAMMPS do the following once: + +sudo apt-get install lammps-daily :pre + +This downloads an executable named "lammps-daily" to your box, which +can then be used in the usual way to run input scripts: + +lammps-daily < in.lj :pre + +To update LAMMPS to the most current version, do the following: + +sudo apt-get update :pre + +which will also update other packages on your system. + +To get a copy of the current documentation and examples: + +sudo apt-get install lammps-daily-doc :pre + +which will download the doc files in +/usr/share/doc/lammps-daily-doc/doc and example problems in +/usr/share/doc/lammps-doc/examples. + +Note that you may still wish to download the tarball to get potential +files and auxiliary tools. + +To un-install LAMMPS, do the following: + +sudo apt-get remove lammps-daily :pre + +Note that the lammps-daily executable is built with the following +sequence of make commands, as if you had done the same with the +unpacked tarball files in the src directory: + +make yes-all; make no-lib; make openmpi + +Thus it builds with FFTW3 and OpenMPI. + +Thanks to Anton Gladky (gladky.anton at gmail.com) for setting up this +Ubuntu package capability. + +:line + +Pre-built Gentoo Linux executable :h4,link(gentoo) + +LAMMPS is part of Gentoo's main package tree and can be installed by +typing: + +% emerge --ask lammps :pre + +Note that in Gentoo the LAMMPS source is downloaded and the package is +built on the your machine. + +Certain LAMMPS packages can be enable via USE flags, type + +% equery uses lammps :pre + +for details. + +Thanks to Nicolas Bock and Christoph Junghans (LANL) for setting up +this Gentoo capability. diff --git a/doc/src/Install_mac.txt b/doc/src/Install_mac.txt new file mode 100644 index 0000000000..3fcc55b8ab --- /dev/null +++ b/doc/src/Install_mac.txt @@ -0,0 +1,55 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Mac :h3 + +LAMMPS can be downloaded, built, and configured for OS X on a Mac with +"Homebrew"_homebrew. Only four of the LAMMPS packages are unavailable +at this time because of additional needs not yet met: KIM, GPU, +USER-INTEL, USER-ATC. + +After installing Homebrew, you can install LAMMPS on your system with +the following commands: + +% brew tap homebrew/science +% brew install lammps # serial version +% brew install lammps --with-mpi # mpi support :pre + +This will install the executable "lammps", a python module named +"lammps", and additional resources with all the standard packages. To +get the location of the additional resources type this: + +% brew info lammps :pre + +This command also tells you additional installation options available. +The user-packages are available as options, just install them like +this example for the USER-OMP package: + +% brew install lammps --enable-user-omp :pre + +It is usually best to install LAMMPS with the most up to date source +files, which can be done with the "--HEAD" option: + +% brew install lammps --HEAD :pre + +To re-install the LAMMPS HEAD, run this command occasionally (make sure +to use the desired options). + +% brew install --force lammps --HEAD $\{options\} :pre + +Once LAMMPS is installed, you can test the installation with the +Lennard-Jones benchmark file: + +% brew test lammps -v :pre + +If you have problems with the installation you can post issues to +"this link"_https://github.com/Homebrew/homebrew-science/issues. + +Thanks to Derek Thomas (derekt at cello.t.u-tokyo.ac.jp) for setting +up the Homebrew capability. diff --git a/doc/src/Install_patch.txt b/doc/src/Install_patch.txt new file mode 100644 index 0000000000..3d0b27370e --- /dev/null +++ b/doc/src/Install_patch.txt @@ -0,0 +1,67 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Applying patches :h3 + +It is easy to stay current with the most recent LAMMPS patch releases +if you use Git or SVN to track LAMMPS development. Instructions for +how to stay current are on the "Install git"_Install_git.html and +"Install svn"_Install_svn.html doc pages. + +If you prefer to download a tarball, as described on the "Install +git"_Install_tarball.html doc page, you can stay current by +downloading "patch files" when new patch releases are made. A link to +a patch file is posted on the "bug and feature page"_bug of the +website, along with a list of changed files and details about what is +in the new patch release. This page explains how to apply the patch +file to your local LAMMPS directory. + +NOTE: You should not apply patch files to a local Git or SVN repo of +LAMMPS, only to an unpacked tarball. Use Git and SVN commands to +update repo versions of LAMMPS. + +Here are the steps to apply a patch file. Note that if your version +of LAMMPS is several patch releases behind, you need to apply all the +intervening patch files in succession to bring your version of LAMMPS +up to date. + +Download the patch file. You may have to shift-click in your browser +to download the file instead of display it. Patch files have names +like patch.12Dec16. :ulb,l + +Put the patch file in your top-level LAMMPS directory, where the +LICENSE and README files are. :l + +Apply the patch by typing the following command from your top-level +LAMMPS directory, where the redirected file is the name of the patch +file. :l + +patch -bp1 < patch.12Dec16 :pre + +A list of updated files print out to the screen. The -b switch +creates backup files of your originals (e.g. src/force.cpp.orig), so +you can manually undo the patch if something goes wrong. :l + +Type the following from the src directory, to enforce consistency +between the src and package directories. This is OK to do even if you +don't use one or more packages. If you are applying several patches +successively, you only need to type this once at the end. The purge +command removes deprecated src files if any were removed by the patch +from package sub-directories. :l + +make purge +make package-update :pre + +Re-build LAMMPS via the "make" command. :l,ule + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-dir of src, then re-install the package. The version in the src +dir is merely a copy and will be wiped out if you type "make +package-update". diff --git a/doc/src/Install_svn.txt b/doc/src/Install_svn.txt new file mode 100644 index 0000000000..64fd1077cb --- /dev/null +++ b/doc/src/Install_svn.txt @@ -0,0 +1,95 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source via SVN :h3 + +IMPORTANT NOTE: As of Oct 2016, SVN support is now implemented via a +git-to-subversion interface service on GitHub and no longer through a +mirror of the internal SVN repository at Sandia. + +You must have the "Subversion (SVN) client software"_svn installed on +your system to communicate with the Git server in this mode. + +:link(svn,http://subversion.apache.org) + +You can follow LAMMPS development on 3 different SVN branches: + +[stable] : this branch is updated with every stable release +[unstable] : this branch is updated with every patch release +[master] : this branch continuously follows ongoing development :ul + +The corresponding command lines to do an initial checkout are as +follows. (Note that unlike Git, you must perform a separate checkout +into a unique directory for each of the 3 branches.) + +svn checkout https://github.com/lammps/lammps.git/branches/unstable mylammps +svn checkout https://github.com/lammps/lammps.git/branches/stable mylammps +svn checkout https://github.com/lammps/lammps.git/trunk mylammps :pre + +where "mylammps" is the name of the directory you wish to create on +your machine. + +Once the command completes, your directory will contain the same files +as if you unpacked a current LAMMPS tarball, with two exceptions: + +1) No LAMMPS packages are initially installed in the src dir (a few +packages are installed by default in the tarball src dir). You can +install whichever packages you wish before building LAMMPS; type "make +package" from the src dir to see the options, and the +"Packages"_Packages.html doc page for a discussion of packages. + +2) The HTML documentation files are not included. They can be fetched +from the LAMMPS website by typing "make fetch" in the doc directory. +Or they can be generated from the content provided in doc/src by +typing "make html" from the the doc directory. + +After initial checkout, as bug fixes and new features are added to +LAMMPS, as listed on "this page"_bug.html, you can stay up-to-date by +typing the following SVN commands from within the "mylammps" +directory: + +svn update :pre + +You can also check if there are any updates by typing: + +svn -qu status :pre + +Doing an "update" will not change any files you have added to the +LAMMPS directory structure. It will also not change any existing +LAMMPS files you have edited, unless those files have changed in the +repository. In that case, SVN will attempt to merge the new +repository file with your version of the file and tell you if there +are any conflicts. See the SVN documentation for details. + +Please refer to the "subversion client support help pages on +GitHub"_https://help.github.com/articles/support-for-subversion-clients +if you want to use advanced features like accessing particular +previous release versions via tags. + +Once you have updated your local files with an "svn update" (or "svn +co"), you still need to re-build LAMMPS if any source files have +changed. To do this, you should cd to the src directory and type: + +make purge # remove any deprecated src files +make package-update # sync package files with src files +make foo # re-build for your machine (mpi, serial, etc) :pre + +just as described on the "Install patch"_Install_patch.html doc page, +after a patch has been installed. + +IMPORTANT NOTE: If you wish to edit/change a src file that is from a +package, you should edit the version of the file inside the package +sub-directory with src, then re-install the package. The version in +the src dir is merely a copy and will be wiped out if you type "make +package-update". + +The LAMMPS GitHub project is managed by Christoph Junghans (LANL, +junghans at lanl.gov), Axel Kohlmeyer (Temple U, akohlmey at +gmail.com) and Richard Berger (Temple U, richard.berger at +temple.edu). diff --git a/doc/src/Install_tarball.txt b/doc/src/Install_tarball.txt new file mode 100644 index 0000000000..b672c5ff25 --- /dev/null +++ b/doc/src/Install_tarball.txt @@ -0,0 +1,64 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download source as a tarball :h3 + +You can download a current LAMMPS tarball from the "download page"_download +of the "LAMMPS website"_lws. + +:link(download,http://lammps.sandia.gov/download.html) +:link(bug,http://lammps.sandia.gov/bug.html) +:link(older,http://lammps.sandia.gov/tars) + +You have two choices of tarballs, either the most recent stable +release or the most current patch release. Stable releases occur a +few times per year, and undergo more testing before release. Patch +releases occur a couple times per month. The new contents in all +releases are listed on the "bug and feature page"_bug of the website. + +Older versions of LAMMPS can also be downloaded from "this +page"_older. + +Once you have a tarball, unzip and untar it with the following +command: + +tar -xzvf lammps*.tar.gz :pre + +This will create a LAMMPS directory with the version date +in its name, e.g. lammps-23Jun18. + +:line + +You can also download a zip file via the "Clone or download" button on +the "LAMMPS GitHub site"_git. The file name will be lammps-master.zip +which can be unzipped with the following command, to create +a lammps-master dir: + +unzip lammps*.zip :pre + +This version is the most up-to-date LAMMPS development version. It +will have the date of the most recent patch release (see the file +src/version.h). But it will also include any new bug-fixes or +features added since the last patch release. They will be included in +the next patch release tarball. + +:link(git,https://github.com/lammps/lammps) + +:line + +If you download a current LAMMPS tarball, one way to stay current as +new patch tarballs are released, is to download a patch file which you +can apply to your local directory to update it for each new patch +release. (Or of course you could just download the newest tarball +periodically.) + +The patch files are posted on the "bug and feature page"_bug of the +website, along with a list of changed files and details about what is +in the new patch release. Instructions for applying a patch file are +on the "Install patch"_Install_patch.html doc page. diff --git a/doc/src/Install_windows.txt b/doc/src/Install_windows.txt new file mode 100644 index 0000000000..df87754c5f --- /dev/null +++ b/doc/src/Install_windows.txt @@ -0,0 +1,52 @@ +"Higher level section"_Install.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Download an executable for Windows :h3 + +Pre-compiled Windows installers which install LAMMPS executables on a +Windows system can be downloaded from this site: + +"http://rpm.lammps.org/windows.html"_http://rpm.lammps.org/windows.html + +Note that each installer package has a date in its name, which +corresponds to the LAMMPS version of the same date. Installers for +current and older versions of LAMMPS are available. 32-bit and 64-bit +installers are available, and each installer contains both a serial +and parallel executable. The installer site also explains how to +install the Windows MPI package (MPICH2 from Argonne National Labs), +needed to run in parallel. + +The LAMMPS binaries contain all optional packages included in the +source distribution except: KIM, REAX, KOKKOS, USER-INTEL, +and USER-QMMM. The serial version also does not include the MPIIO and +USER-LB packages. GPU support is provided for OpenCL. + +The installer site also has instructions on how to run LAMMPS under +Windows, once it is installed, in both serial and parallel. + +When you download the installer package, you run it on your Windows +machine. It will then prompt you with a dialog, where you can choose +the installation directory, unpack and copy several executables, +potential files, documentation pdfs, selected example files, etc. It +will then update a few system settings (e.g. PATH, LAMMPS_POTENTIALS) +and add an entry into the Start Menu (with references to the +documentation, LAMMPS homepage and more). From that menu, there is +also a link to an uninstaller that removes the files and undoes the +environment manipulations. + +Note that to update to a newer version of LAMMPS, you should typically +uninstall the version you currently have, download a new installer, +and go thru the install procedure described above. I.e. the same +procedure for installing/updating most Windows programs. You can +install multiple versions of LAMMPS (in different directories), but +only the executable for the last-installed package will be found +automatically, so this should only be done for debugging purposes. + +Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting +up this Windows capability. diff --git a/doc/src/Run.txt b/doc/src/Run.txt new file mode 100644 index 0000000000..68c3f1e295 --- /dev/null +++ b/doc/src/Run.txt @@ -0,0 +1,37 @@ +"Previous Section"_Build.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Commands.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Run LAMMPS :h2 + +These pages explain how to run LAMMPS once you have "installed an +executable"_Install.html or "downloaded the source code"_Install.html +and "built an executable"_Build.html. The "Commands"_Commands.html +doc page describes how input scripts are structured and the commands +they can contain. + + + + + +"Basics of running LAMMPS"_Run_basics.html +"Command-line options"_Run_options.html +"Screen and logfile output"_Run_output.html +"Running LAMMPS on Windows"_Run_windows.html :all(b) + + diff --git a/doc/src/Run_basics.txt b/doc/src/Run_basics.txt new file mode 100644 index 0000000000..1d4b570f21 --- /dev/null +++ b/doc/src/Run_basics.txt @@ -0,0 +1,87 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Basics of running LAMMPS :h3 + +LAMMPS is run from the command line, reading commands from standard +input, which are typically listed in an input script: + +lmp_serial < in.file +lmp_serial -in in.file +~/lammps/src/lmp_serial < in.file +mpirun -np 4 lmp_mpi -in in.file +mpirun -np 8 ~/lammps/src/lmp_mpi -in in.file +mpirun -np 6 /usr/local/bin/lmp_mpi -in in.file :pre + +You normally run from the directory your input script is in. That is +also where output files are produced, unless you specify otherwise in +your input script. As in some of the examples above, the LAMMPS +executable can be elsewhere. + +NOTE: The redirection operator "<" can often be used with mpirun, but +some systems require the -in form. + +As LAMMPS runs it prints info to the screen and a logfile named +log.lammps. More info about output is given on the "Run +output"_Run_output.html doc page. + +If LAMMPS encounters errors in the input script or while running a +simulation it will print an ERROR message and stop or a WARNING +message and continue. See the "Errors"_Errors.html doc page for a +discussion of the various kinds of errors LAMMPS can or can't detect, +a list of all ERROR and WARNING messages, and what to do about them. + +:line + +LAMMPS can run the same problem on any number of processors, including +a single processor. In theory you should get identical answers on any +number of processors and on any machine. In practice, numerical +round-off can cause slight differences and eventual divergence of +molecular dynamics phase space trajectories. See the "Errors +common"_Errors_common.html doc page for discussion of this. + +LAMMPS can run as large a problem as will fit in the physical memory +of one or more processors. If you run out of memory, you must run on +more processors or define a smaller problem. + +If you run LAMMPS in parallel via mpirun, you should be aware of the +"processors"_processors.html command which controls how MPI tasks are +mapped to the simulation box, as well as mpirun options that control +how MPI tasks are assigned to physical cores of the node(s) of the +machine you are running on. These settings can improve performance, +though the defaults are often adequate. + +For example, it is often important to bind MPI tasks (processes) to +physical cores (processor affinity), so that the operating system does +not migrate them during a simulation. If this is not the default +behavior on your machine, the mpirun option "--bind-to core" (OpenMPI) +or "-bind-to core" (MPICH) can be used. + +If the LAMMPS command(s) you are using support multi-threading, you +can set the number of threads per MPI task via the environment +variable OMP_NUM_THREADS, before you launch LAMMPS: + +export OMP_NUM_THREADS=2 # bash +setenv OMP_NUM_THREADS 2 # csh or tcsh :pre + +This can also be done via the "package"_package.html command or via +the "-pk command-line switch"_Run_options.html which invokes the +package command. See the "package"_package.html command or +"Speed"_Speed.html doc pages for more details about which accerlarator +packages and which commands support multi-threading. + +:line + +You can experiment with running LAMMPS using any of the input scripts +provided in the examples or bench directory. Input scripts are named +in.* and sample outputs are named log.*.P where P is the number of +processors it was run on. + +Some of the examples or benchmarks require LAMMPS to be built with +optional packages. diff --git a/doc/src/Run_options.txt b/doc/src/Run_options.txt new file mode 100644 index 0000000000..b1c1e376da --- /dev/null +++ b/doc/src/Run_options.txt @@ -0,0 +1,470 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Command-line options :h3 + +At run time, LAMMPS recognizes several optional command-line switches +which may be used in any order. Either the full word or a one-or-two +letter abbreviation can be used: + +"-e or -echo"_#echo +"-h or -help"_#help +"-i or -in"_#in +"-k or -kokkos"_#kokkos +"-l or -log"_#log +"-nc or -nocite"_#nocite +"-pk or -package"_#package +"-p or -partition"_#partition +"-pl or -plog"_#plot +"-ps or -pscreen"_#pscreen +"-r or -restart"_#restart +"-ro or -reorder"_#reorder +"-sc or -screen"_#screen +"-sf or -suffix"_#suffix +"-v or -var"_#var :ul + +For example, the lmp_mpi executable might be launched as follows: + +mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy +mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy :pre + +:line +:line + +[-echo style] :link(echo) + +Set the style of command echoing. The style can be {none} or {screen} +or {log} or {both}. Depending on the style, each command read from +the input script will be echoed to the screen and/or logfile. This +can be useful to figure out which line of your script is causing an +input error. The default value is {log}. The echo style can also be +set by using the "echo"_echo.html command in the input script itself. + +:line + +[-help] :link(help) + +Print a brief help summary and a list of options compiled into this +executable for each LAMMPS style (atom_style, fix, compute, +pair_style, bond_style, etc). This can tell you if the command you +want to use was included via the appropriate package at compile time. +LAMMPS will print the info and immediately exit if this switch is +used. + +:line + +[-in file] :link(file) + +Specify a file to use as an input script. This is an optional switch +when running LAMMPS in one-partition mode. If it is not specified, +LAMMPS reads its script from standard input, typically from a script +via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should +also work in parallel, but if it does not (in the unlikely case that +an MPI implementation does not support it), then use the -in flag. +Note that this is a required switch when running LAMMPS in +multi-partition mode, since multiple processors cannot all read from +stdin. + +:line + +[-kokkos on/off keyword/value ...] :link(kokkos) + +Explicitly enable or disable KOKKOS support, as provided by the KOKKOS +package. Even if LAMMPS is built with this package, as described +above in "Section 2.3"_#start_3, this switch must be set to enable +running with the KOKKOS-enabled styles the package provides. If the +switch is not set (the default), LAMMPS will operate as if the KOKKOS +package were not installed; i.e. you can run standard LAMMPS or with +the GPU or USER-OMP packages, for testing or benchmarking purposes. + +Additional optional keyword/value pairs can be specified which +determine how Kokkos will use the underlying hardware on your +platform. These settings apply to each MPI task you launch via the +"mpirun" or "mpiexec" command. You may choose to run one or more MPI +tasks per physical node. Note that if you are running on a desktop +machine, you typically have one physical node. On a cluster or +supercomputer there may be dozens or 1000s of physical nodes. + +Either the full word or an abbreviation can be used for the keywords. +Note that the keywords do not use a leading minus sign. I.e. the +keyword is "t", not "-t". Also note that each of the keywords has a +default setting. Examples of when to use these options and what +settings to use on different platforms is given on the "Speed +kokkos"_Speed_kokkos.html doc page. + +d or device +g or gpus +t or threads +n or numa :ul + +device Nd :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and if you are running with only one +MPI task per node. The Nd setting is the ID of the GPU on the node to +run on. By default Nd = 0. If you have multiple GPUs per node, they +have consecutive IDs numbered as 0,1,2,etc. This setting allows you +to launch multiple independent jobs on the node, each with a single +MPI task per node, and assign each job to run on a different GPU. + +gpus Ng Ns :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and you are running with multiple MPI +tasks per node (up to one per GPU). The Ng setting is how many GPUs +you will use. The Ns setting is optional. If set, it is the ID of a +GPU to skip when assigning MPI tasks to GPUs. This may be useful if +your desktop system reserves one GPU to drive the screen and the rest +are intended for computational work like running LAMMPS. By default +Ng = 1 and Ns is not set. + +Depending on which flavor of MPI you are running, LAMMPS will look for +one of these 3 environment variables + +SLURM_LOCALID (various MPI variants compiled with SLURM support) +MV2_COMM_WORLD_LOCAL_RANK (Mvapich) +OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre + +which are initialized by the "srun", "mpirun" or "mpiexec" commands. +The environment variable setting for each MPI rank is used to assign a +unique GPU ID to the MPI task. + +threads Nt :pre + +This option assigns Nt number of threads to each MPI task for +performing work when Kokkos is executing in OpenMP or pthreads mode. +The default is Nt = 1, which essentially runs in MPI-only mode. If +there are Np MPI tasks per physical node, you generally want Np*Nt = +the number of physical cores per node, to use your available hardware +optimally. This also sets the number of threads used by the host when +LAMMPS is compiled with CUDA=yes. + +numa Nm :pre + +This option is only relevant when using pthreads with hwloc support. +In this case Nm defines the number of NUMA regions (typically sockets) +on a node which will be utilized by a single MPI rank. By default Nm += 1. If this option is used the total number of worker-threads per +MPI rank is threads*numa. Currently it is always almost better to +assign at least one MPI rank per NUMA region, and leave numa set to +its default value of 1. This is because letting a single process span +multiple NUMA regions induces a significant amount of cross NUMA data +traffic which is slow. + +:line + +[-log file] :link(log) + +Specify a log file for LAMMPS to write status information to. In +one-partition mode, if the switch is not used, LAMMPS writes to the +file log.lammps. If this switch is used, LAMMPS writes to the +specified file. In multi-partition mode, if the switch is not used, a +log.lammps file is created with hi-level status information. Each +partition also writes to a log.lammps.N file where N is the partition +ID. If the switch is specified in multi-partition mode, the hi-level +logfile is named "file" and each partition also logs information to a +file.N. For both one-partition and multi-partition mode, if the +specified file is "none", then no log files are created. Using a +"log"_log.html command in the input script will override this setting. +Option -plog will override the name of the partition log files file.N. + +:line + +[-nocite] :link(nocite) + +Disable writing the log.cite file which is normally written to list +references for specific cite-able features used during a LAMMPS run. +See the "citation page"_http://lammps.sandia.gov/cite.html for more +details. + +:line + +[-package style args ....] :link(package) + +Invoke the "package"_package.html command with style and args. The +syntax is the same as if the command appeared at the top of the input +script. For example "-package gpu 2" or "-pk gpu 2" is the same as +"package gpu 2"_package.html in the input script. The possible styles +and args are documented on the "package"_package.html doc page. This +switch can be used multiple times, e.g. to set options for the +USER-INTEL and USER-OMP packages which can be used together. + +Along with the "-suffix" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +:line + +[-partition 8x2 4 5 ...] :link(partition) + +Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P +processors and this switch is not used, LAMMPS runs in one partition, +i.e. all P processors run a single simulation. If this switch is +used, the P processors are split into separate partitions and each +partition runs its own simulation. The arguments to the switch +specify the number of processors in each partition. Arguments of the +form MxN mean M partitions, each with N processors. Arguments of the +form N mean a single partition with N processors. The sum of +processors in all partitions must equal P. Thus the command +"-partition 8x2 4 5" has 10 partitions and runs on a total of 25 +processors. + +Running with multiple partitions can be useful for running +"multi-replica simulations"_Howto_replica.html, where each replica +runs on on one or a few processors. Note that with MPI installed on a +machine (e.g. your desktop), you can run on more (virtual) processors +than you have physical processors. + +To run multiple independent simulations from one input script, using +multiple partitions, see the "Howto multiple"_Howto_multiple.html doc +page. World- and universe-style "variables"_variable.html are useful +in this context. + +:line + +[-plog file] :link(plog) + +Specify the base name for the partition log files, so partition N +writes log information to file.N. If file is none, then no partition +log files are created. This overrides the filename specified in the +-log command-line option. This option is useful when working with +large numbers of partitions, allowing the partition log files to be +suppressed (-plog none) or placed in a sub-directory (-plog +replica_files/log.lammps) If this option is not used the log file for +partition N is log.lammps.N or whatever is specified by the -log +command-line option. + +:line + +[-pscreen file] :link(pscreen) + +Specify the base name for the partition screen file, so partition N +writes screen information to file.N. If file is none, then no +partition screen files are created. This overrides the filename +specified in the -screen command-line option. This option is useful +when working with large numbers of partitions, allowing the partition +screen files to be suppressed (-pscreen none) or placed in a +sub-directory (-pscreen replica_files/screen). If this option is not +used the screen file for partition N is screen.N or whatever is +specified by the -screen command-line option. + +:line + +[-restart restartfile {remap} datafile keyword value ...] :link(restart) + +Convert the restart file into a data file and immediately exit. This +is the same operation as if the following 2-line input script were +run: + +read_restart restartfile {remap} +write_data datafile keyword value ... :pre + +Note that the specified restartfile and datafile can have wild-card +characters ("*",%") as described by the +"read_restart"_read_restart.html and "write_data"_write_data.html +commands. But a filename such as file.* will need to be enclosed in +quotes to avoid shell expansion of the "*" character. + +Note that following restartfile, the optional flag {remap} can be +used. This has the same effect as adding it to the +"read_restart"_read_restart.html command, as explained on its doc +page. This is only useful if the reading of the restart file triggers +an error that atoms have been lost. In that case, use of the remap +flag should allow the data file to still be produced. + +Also note that following datafile, the same optional keyword/value +pairs can be listed as used by the "write_data"_write_data.html +command. + +:line + +[-reorder] :link(reorder) + +This option has 2 forms: + +-reorder nth N +-reorder custom filename :pre + +Reorder the processors in the MPI communicator used to instantiate +LAMMPS, in one of several ways. The original MPI communicator ranks +all P processors from 0 to P-1. The mapping of these ranks to +physical processors is done by MPI before LAMMPS begins. It may be +useful in some cases to alter the rank order. E.g. to insure that +cores within each node are ranked in a desired order. Or when using +the "run_style verlet/split"_run_style.html command with 2 partitions +to insure that a specific Kspace processor (in the 2nd partition) is +matched up with a specific set of processors in the 1st partition. +See the "Speed tips"_Speed_tips.html doc page for more details. + +If the keyword {nth} is used with a setting {N}, then it means every +Nth processor will be moved to the end of the ranking. This is useful +when using the "run_style verlet/split"_run_style.html command with 2 +partitions via the -partition command-line switch. The first set of +processors will be in the first partition, the 2nd set in the 2nd +partition. The -reorder command-line switch can alter this so that +the 1st N procs in the 1st partition and one proc in the 2nd partition +will be ordered consecutively, e.g. as the cores on one physical node. +This can boost performance. For example, if you use "-reorder nth 4" +and "-partition 9 3" and you are running on 12 processors, the +processors will be reordered from + +0 1 2 3 4 5 6 7 8 9 10 11 :pre + +to + +0 1 2 4 5 6 8 9 10 3 7 11 :pre + +so that the processors in each partition will be + +0 1 2 4 5 6 8 9 10 +3 7 11 :pre + +See the "processors" command for how to insure processors from each +partition could then be grouped optimally for quad-core nodes. + +If the keyword is {custom}, then a file that specifies a permutation +of the processor ranks is also specified. The format of the reorder +file is as follows. Any number of initial blank or comment lines +(starting with a "#" character) can be present. These should be +followed by P lines of the form: + +I J :pre + +where P is the number of processors LAMMPS was launched with. Note +that if running in multi-partition mode (see the -partition switch +above) P is the total number of processors in all partitions. The I +and J values describe a permutation of the P processors. Every I and +J should be values from 0 to P-1 inclusive. In the set of P I values, +every proc ID should appear exactly once. Ditto for the set of P J +values. A single I,J pairing means that the physical processor with +rank I in the original MPI communicator will have rank J in the +reordered communicator. + +Note that rank ordering can also be specified by many MPI +implementations, either by environment variables that specify how to +order physical processors, or by config files that specify what +physical processors to assign to each MPI rank. The -reorder switch +simply gives you a portable way to do this without relying on MPI +itself. See the "processors out"_processors.html command for how +to output info on the final assignment of physical processors to +the LAMMPS simulation domain. + +:line + +[-screen file] :link(screen) + +Specify a file for LAMMPS to write its screen information to. In +one-partition mode, if the switch is not used, LAMMPS writes to the +screen. If this switch is used, LAMMPS writes to the specified file +instead and you will see no screen output. In multi-partition mode, +if the switch is not used, hi-level status information is written to +the screen. Each partition also writes to a screen.N file where N is +the partition ID. If the switch is specified in multi-partition mode, +the hi-level screen dump is named "file" and each partition also +writes screen information to a file.N. For both one-partition and +multi-partition mode, if the specified file is "none", then no screen +output is performed. Option -pscreen will override the name of the +partition screen files file.N. + +:line + +[-suffix style args] :link(suffix) + +Use variants of various styles if they exist. The specified style can +be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These +refer to optional packages that LAMMPS can be built with, as described +above in "Section 2.3"_#start_3. The "gpu" style corresponds to the +GPU package, the "intel" style to the USER-INTEL package, the "kk" +style to the KOKKOS package, the "opt" style to the OPT package, and +the "omp" style to the USER-OMP package. The hybrid style is the only +style that accepts arguments. It allows for two packages to be +specified. The first package specified is the default and will be used +if it is available. If no style is available for the first package, +the style for the second package will be used if available. For +example, "-suffix hybrid intel omp" will use styles from the +USER-INTEL package if they are installed and available, but styles for +the USER-OMP package otherwise. + +Along with the "-package" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +As an example, all of the packages provide a "pair_style +lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, +lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style +can be specified explicitly in your input script, e.g. pair_style +lj/cut/gpu. If the -suffix switch is used the specified suffix +(gpu,intel,kk,omp,opt) is automatically appended whenever your input +script command creates a new "atom"_atom_style.html, +"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or +"run"_run_style.html style. If the variant version does not exist, +the standard version is created. + +For the GPU package, using this command-line switch also invokes the +default GPU settings, as if the command "package gpu 1" were used at +the top of your input script. These settings can be changed by using +the "-package gpu" command-line switch or the "package +gpu"_package.html command in your script. + +For the USER-INTEL package, using this command-line switch also +invokes the default USER-INTEL settings, as if the command "package +intel 1" were used at the top of your input script. These settings +can be changed by using the "-package intel" command-line switch or +the "package intel"_package.html command in your script. If the +USER-OMP package is also installed, the hybrid style with "intel omp" +arguments can be used to make the omp suffix a second choice, if a +requested style is not available in the USER-INTEL package. It will +also invoke the default USER-OMP settings, as if the command "package +omp 0" were used at the top of your input script. These settings can +be changed by using the "-package omp" command-line switch or the +"package omp"_package.html command in your script. + +For the KOKKOS package, using this command-line switch also invokes +the default KOKKOS settings, as if the command "package kokkos" were +used at the top of your input script. These settings can be changed +by using the "-package kokkos" command-line switch or the "package +kokkos"_package.html command in your script. + +For the OMP package, using this command-line switch also invokes the +default OMP settings, as if the command "package omp 0" were used at +the top of your input script. These settings can be changed by using +the "-package omp" command-line switch or the "package +omp"_package.html command in your script. + +The "suffix"_suffix.html command can also be used within an input +script to set a suffix, or to turn off or back on any suffix setting +made via the command line. + +:line + +[-var name value1 value2 ...] :link(var) + +Specify a variable that will be defined for substitution purposes when +the input script is read. This switch can be used multiple times to +define multiple variables. "Name" is the variable name which can be a +single character (referenced as $x in the input script) or a full +string (referenced as $\{abc\}). An "index-style +variable"_variable.html will be created and populated with the +subsequent values, e.g. a set of filenames. Using this command-line +option is equivalent to putting the line "variable name index value1 +value2 ..." at the beginning of the input script. Defining an index +variable as a command-line argument overrides any setting for the same +index variable in the input script, since index variables cannot be +re-defined. + +See the "variable"_variable.html command for more info on defining +index and other kinds of variables and the "Commands +parse"_Commands_parse.html page for more info on using variables in +input scripts. + +NOTE: Currently, the command-line parser looks for arguments that +start with "-" to indicate new switches. Thus you cannot specify +multiple variable values if any of them start with a "-", e.g. a +negative numeric value. It is OK if the first value1 starts with a +"-", since it is automatically skipped. diff --git a/doc/src/Run_output.txt b/doc/src/Run_output.txt new file mode 100644 index 0000000000..a534ae7c7b --- /dev/null +++ b/doc/src/Run_output.txt @@ -0,0 +1,176 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Screen and logfile output :h3 + +As LAMMPS reads an input script, it prints information to both the +screen and a log file about significant actions it takes to setup a +simulation. When the simulation is ready to begin, LAMMPS performs +various initializations, and prints info about the run it is about to +perform, including the amount of memory (in MBytes per processor) that +the simulation requires. It also prints details of the initial +thermodynamic state of the system. During the run itself, +thermodynamic information is printed periodically, every few +timesteps. When the run concludes, LAMMPS prints the final +thermodynamic state and a total run time for the simulation. It also +appends statistics about the CPU time and storage requirements for the +simulation. An example set of statistics is shown here: + +Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre + +Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s +97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre + +MPI task timings breakdown: +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 +Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 +Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 +Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 +Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 +Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 +Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 +Other | | 0.007178 | | | 0.26 :pre + +Nlocal: 501 ave 508 max 490 min +Histogram: 1 0 0 0 0 0 1 1 0 1 +Nghost: 6586.25 ave 6628 max 6548 min +Histogram: 1 0 1 0 0 0 1 0 0 1 +Neighs: 177007 ave 180562 max 170212 min +Histogram: 1 0 0 0 0 0 0 1 1 1 :pre + +Total # of neighbors = 708028 +Ave neighs/atom = 353.307 +Ave special neighs/atom = 2.34032 +Neighbor list builds = 26 +Dangerous builds = 0 :pre + +:line + +The first section provides a global loop timing summary. The {loop +time} is the total wall-clock time for the simulation to run. The +{Performance} line is provided for convenience to help predict how +long it will take to run a desired physical simulation. The {CPU use} +line provides the CPU utilization per MPI task; it should be close to +100% times the number of OpenMP threads (or 1 of not using OpenMP). +Lower numbers correspond to delays due to file I/O or insufficient +thread utilization. + +:line + +The {MPI task} section gives the breakdown of the CPU run time (in +seconds) into major categories: + +{Pair} = non-bonded force computations +{Bond} = bonded interactions: bonds, angles, dihedrals, impropers +{Kspace} = long-range interactions: Ewald, PPPM, MSM +{Neigh} = neighbor list construction +{Comm} = inter-processor communication of atoms and their properties +{Output} = output of thermodynamic info and dump files +{Modify} = fixes and computes invoked by fixes +{Other} = all the remaining time :ul + +For each category, there is a breakdown of the least, average and most +amount of wall time any processor spent on this category of +computation. The "%varavg" is the percentage by which the max or min +varies from the average. This is an indication of load imbalance. A +percentage close to 0 is perfect load balance. A large percentage is +imbalance. The final "%total" column is the percentage of the total +loop time is spent in this category. + +When using the "timer full"_timer.html setting, an additional column +is added that also prints the CPU utilization in percent. In addition, +when using {timer full} and the "package omp"_package.html command are +active, a similar timing summary of time spent in threaded regions to +monitor thread utilization and load balance is provided. A new {Thread +timings} section is also added, which lists the time spent in reducing +the per-thread data elements to the storage for non-threaded +computation. These thread timings are measured for the first MPI rank +only and and thus, because the breakdown for MPI tasks can change from +MPI rank to MPI rank, this breakdown can be very different for +individual ranks. Here is an example output for this section: + +Thread timings breakdown (MPI rank 0): +Total threaded time 0.6846 / 90.6% +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 +Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 +Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 +Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 +Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre + +:line + +The third section above lists the number of owned atoms (Nlocal), +ghost atoms (Nghost), and pair-wise neighbors stored per processor. +The max and min values give the spread of these values across +processors with a 10-bin histogram showing the distribution. The total +number of histogram counts is equal to the number of processors. + +:line + +The last section gives aggregate statistics (across all processors) +for pair-wise neighbors and special neighbors that LAMMPS keeps track +of (see the "special_bonds"_special_bonds.html command). The number +of times neighbor lists were rebuilt is tallied, as is the number of +potentially {dangerous} rebuilds. If atom movement triggered neighbor +list rebuilding (see the "neigh_modify"_neigh_modify.html command), +then dangerous reneighborings are those that were triggered on the +first timestep atom movement was checked for. If this count is +non-zero you may wish to reduce the delay factor to insure no force +interactions are missed by atoms moving beyond the neighbor skin +distance before a rebuild takes place. + +:line + +If an energy minimization was performed via the +"minimize"_minimize.html command, additional information is printed, +e.g. + +Minimization stats: + Stopping criterion = linesearch alpha is zero + Energy initial, next-to-last, final = + -6372.3765206 -8328.46998942 -8328.46998942 + Force two-norm initial, final = 1059.36 5.36874 + Force max component initial, final = 58.6026 1.46872 + Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 + Iterations, force evaluations = 701 1516 :pre + +The first line prints the criterion that determined minimization was +converged. The next line lists the initial and final energy, as well +as the energy on the next-to-last iteration. The next 2 lines give a +measure of the gradient of the energy (force on all atoms). The +2-norm is the "length" of this 3N-component force vector; the largest +component (x, y, or z) of force (infinity-norm) is also given. Then +information is provided about the line search and statistics on how +many iterations and force-evaluations the minimizer required. +Multiple force evaluations are typically done at each iteration to +perform a 1d line minimization in the search direction. See the +"minimize"_minimize.html doc page for more details. + +:line + +If a "kspace_style"_kspace_style.html long-range Coulombics solver +that performs FFTs was used during the run (PPPM, Ewald), then +additional information is printed, e.g. + +FFT time (% of Kspce) = 0.200313 (8.34477) +FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre + +The first line is the time spent doing 3d FFTs (several per timestep) +and the fraction it represents of the total KSpace time (listed +above). Each 3d FFT requires computation (3 sets of 1d FFTs) and +communication (transposes). The total flops performed is 5Nlog_2(N), +where N is the number of points in the 3d grid. The FFTs are timed +with and without the communication and a Gflop rate is computed. The +3d rate is with communication; the 1d rate is without (just the 1d +FFTs). Thus you can estimate what fraction of your FFT time was spent +in communication, roughly 75% in the example above. diff --git a/doc/src/Run_windows.txt b/doc/src/Run_windows.txt new file mode 100644 index 0000000000..1151a4a2bb --- /dev/null +++ b/doc/src/Run_windows.txt @@ -0,0 +1,73 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Running LAMMPS on Windows :h3 + +To run a serial (non-MPI) executable, follow these steps: + +Get a command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input script, +(e.g. by typing: cd "Documents"). :l + +At the command prompt, type "lmp_serial -in in.file", where +in.file is the name of your LAMMPS input script. :l,ule + +Note that the serial executable includes support for multi-threading +parallelization from the styles in the USER-OMP packages. To run with +4 threads, you can type this: + +lmp_serial -in in.lj -pk omp 4 -sf omp :pre + +:line + +For the MPI executable, which allows you to run LAMMPS under Windows +in parallel, follow these steps. + +Download and install a compatible MPI library binary package: + +for 32-bit Windows: "mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi +for 64-bit Windows: "mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi :ul + +The LAMMPS Windows installer packages will automatically adjust your +path for the default location of this MPI package. After the +installation of the MPICH2 software, it needs to be integrated into +the system. For this you need to start a Command Prompt in +{Administrator Mode} (right click on the icon and select it). Change +into the MPICH2 installation directory, then into the subdirectory +[bin] and execute [smpd.exe -install]. Exit the command window. + +Get a new, regular command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input file +(e.g. by typing: cd "Documents"). :l,ule + +Then type something like this: + +mpiexec -localonly 4 lmp_mpi -in in.file +mpiexec -np 4 lmp_mpi -in in.file :pre + +where in.file is the name of your LAMMPS input script. For the latter +case, you may be prompted to enter your password. + +In this mode, output may not immediately show up on the screen, so if +your input script takes a long time to execute, you may need to be +patient before the output shows up. + +The parallel executable can also run on a single processor by typing +something like this: + +lmp_mpi -in in.lj :pre + +Note that the parallel executable also includes OpenMP +multi-threading, which can be combined with MPI using something like: + +mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt deleted file mode 100644 index 19a798d5df..0000000000 --- a/doc/src/Section_start.txt +++ /dev/null @@ -1,1823 +0,0 @@ -"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - -"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Commands.html :c - -:link(lws,http://lammps.sandia.gov) -:link(ld,Manual.html) -:link(lc,Commands_all.html) - -:line - -2. Getting Started :h2 - -This section describes how to build and run LAMMPS, for both new and -experienced users. - -2.1 "What's in the LAMMPS distribution"_#start_1 -2.2 "Making LAMMPS"_#start_2 -2.3 "Making LAMMPS with optional packages"_#start_3 -2.4 "Building LAMMPS as a library"_#start_4 -2.5 "Running LAMMPS"_#start_5 -2.6 "Command-line options"_#start_6 -2.7 "Screen output"_#start_7 -2.8 "Tips for users of previous versions"_#start_8 :all(b) - -:line - -2.1 What's in the LAMMPS distribution :h3,link(start_1) - -When you download a LAMMPS tarball you will need to unzip and untar -the downloaded file with the following commands, after placing the -tarball in an appropriate directory. - -tar -xzvf lammps*.tar.gz :pre - -This will create a LAMMPS directory containing two files and several -sub-directories: - -README: text file -LICENSE: the GNU General Public License (GPL) -bench: benchmark problems -doc: documentation -examples: simple test problems -potentials: embedded atom method (EAM) potential files -src: source files -tools: pre- and post-processing tools :tb(s=:) - -Note that the "download page"_download also has links to download -pre-build Windows installers, as well as pre-built packages for -several widely used Linux distributions. It also has instructions -for how to download/install LAMMPS for Macs (via Homebrew), and to -download and update LAMMPS from SVN and Git repositories, which gives -you access to the up-to-date sources that are used by the LAMMPS -core developers. - -:link(download,http://lammps.sandia.gov/download.html) - -The Windows and Linux packages for serial or parallel include -only selected packages and bug-fixes/upgrades listed on "this -page"_http://lammps.sandia.gov/bug.html up to a certain date, as -stated on the download page. If you want an executable with -non-included packages or that is more current, then you'll need to -build LAMMPS yourself, as discussed in the next section. - -Skip to the "Running LAMMPS"_#start_6 sections for info on how to -launch a LAMMPS Windows executable on a Windows box. - -:line - -2.2 Making LAMMPS :h3,link(start_2) - -This section has the following sub-sections: - -2.2.1 "Read this first"_#start_2_1 -2.2.1 "Steps to build a LAMMPS executable"_#start_2_2 -2.2.3 "Common errors that can occur when making LAMMPS"_#start_2_3 -2.2.4 "Additional build tips"_#start_2_4 -2.2.5 "Building for a Mac"_#start_2_5 -2.2.6 "Building for Windows"_#start_2_6 :all(b) - -:line - -Read this first :h4,link(start_2_1) - -If you want to avoid building LAMMPS yourself, read the preceding -section about options available for downloading and installing -executables. Details are discussed on the "download"_download page. - -Building LAMMPS can be simple or not-so-simple. If all you need are -the default packages installed in LAMMPS, and MPI is already installed -on your machine, or you just want to run LAMMPS in serial, then you -can typically use the Makefile.mpi or Makefile.serial files in -src/MAKE by typing one of these lines (from the src dir): - -make mpi -make serial :pre - -Note that on a facility supercomputer, there are often "modules" -loaded in your environment that provide the compilers and MPI you -should use. In this case, the "mpicxx" compile/link command in -Makefile.mpi should simply work by accessing those modules. - -It may be the case that one of the other Makefile.machine files in the -src/MAKE sub-directories is a better match to your system (type "make" -to see a list), you can use it as-is by typing (for example): - -make stampede :pre - -If any of these builds (with an existing Makefile.machine) works on -your system, then you're done! - -If you need to install an optional package with a LAMMPS command you -want to use, and the package does not depend on an extra library, you -can simply type - -make name :pre - -before invoking (or re-invoking) the above steps. "Name" is the -lower-case name of the package, e.g. replica or user-misc. - -If you want to do one of the following: - -use a LAMMPS command that requires an extra library (e.g. "dump -image"_dump_image.html) build with a package that requires an extra -library build with an accelerator package that requires special -compiler/linker settings run on a machine that has its own compilers, -settings, or libraries :ul - -then building LAMMPS is more complicated. You may need to find where -extra libraries exist on your machine or install them if they don't. -You may need to build extra libraries that are included in the LAMMPS -distribution, before building LAMMPS itself. You may need to edit a -Makefile.machine file to make it compatible with your system. - -Please read the following sections carefully. If you are not -comfortable with makefiles, or building codes on a Unix platform, or -running an MPI job on your machine, please find a local expert to help -you. Many compilation, linking, and run problems users experience are -often not LAMMPS issues - they are peculiar to the user's system, -compilers, libraries, etc. Such questions are better answered by a -local expert. - -If you have a build problem that you are convinced is a LAMMPS issue -(e.g. the compiler complains about a line of LAMMPS source code), then -please post the issue to the "LAMMPS mail -list"_http://lammps.sandia.gov/mail.html. - -If you succeed in building LAMMPS on a new kind of machine, for which -there isn't a similar machine Makefile included in the -src/MAKE/MACHINES directory, then send it to the developers and we can -include it in the LAMMPS distribution. - -:line - -Steps to build a LAMMPS executable :h4,link(start_2_2) - -Step 0 :h5 - -The src directory contains the C++ source and header files for LAMMPS. -It also contains a top-level Makefile and a MAKE sub-directory with -low-level Makefile.* files for many systems and machines. See the -src/MAKE/README file for a quick overview of what files are available -and what sub-directories they are in. - -The src/MAKE dir has a few files that should work as-is on many -platforms. The src/MAKE/OPTIONS dir has more that invoke additional -compiler, MPI, and other setting options commonly used by LAMMPS, to -illustrate their syntax. The src/MAKE/MACHINES dir has many more that -have been tweaked or optimized for specific machines. These files are -all good starting points if you find you need to change them for your -machine. Put any file you edit into the src/MAKE/MINE directory and -it will be never be touched by any LAMMPS updates. - ->From within the src directory, type "make" or "gmake". You should see -a list of available choices from src/MAKE and all of its -sub-directories. If one of those has the options you want or is the -machine you want, you can type a command like: - -make mpi :pre -or - -make serial :pre -or - -gmake mac :pre - -Note that the corresponding Makefile.machine can exist in src/MAKE or -any of its sub-directories. If a file with the same name appears in -multiple places (not a good idea), the order they are used is as -follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. -This gives preference to a file you have created/edited and put in -src/MAKE/MINE. - -Note that on a multi-processor or multi-core platform you can launch a -parallel make, by using the "-j" switch with the make command, which -will build LAMMPS more quickly. - -If you get no errors and an executable like [lmp_mpi] or [lmp_serial] -or [lmp_mac] is produced, then you're done; it's your lucky day. - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below. - -Step 1 :h5 - -If Step 0 did not work, you will need to create a low-level Makefile -for your machine, like Makefile.foo. You should make a copy of an -existing Makefile.* in src/MAKE or one of its sub-directories as a -starting point. The only portions of the file you need to edit are -the first line, the "compiler/linker settings" section, and the -"LAMMPS-specific settings" section. When it works, put the edited -file in src/MAKE/MINE and it will not be altered by any future LAMMPS -updates. - -Step 2 :h5 - -Change the first line of Makefile.foo to list the word "foo" after the -"#", and whatever other options it will set. This is the line you -will see if you just type "make". - -Step 3 :h5 - -The "compiler/linker settings" section lists compiler and linker -settings for your C++ compiler, including optimization flags. You can -use g++, the open-source GNU compiler, which is available on all Unix -systems. You can also use mpicxx which will typically be available if -MPI is installed on your system, though you should check which actual -compiler it wraps. Vendor compilers often produce faster code. On -boxes with Intel CPUs, we suggest using the Intel icc compiler, which -can be downloaded from "Intel's compiler site"_intel. - -:link(intel,http://www.intel.com/software/products/noncom) - -If building a C++ code on your machine requires additional libraries, -then you should list them as part of the LIB variable. You should -not need to do this if you use mpicxx. - -The DEPFLAGS setting is what triggers the C++ compiler to create a -dependency list for a source file. This speeds re-compilation when -source (*.cpp) or header (*.h) files are edited. Some compilers do -not support dependency file creation, or may use a different switch -than -D. GNU g++ and Intel icc works with -D. If your compiler can't -create dependency files, then you'll need to create a Makefile.foo -patterned after Makefile.storm, which uses different rules that do not -involve dependency files. Note that when you build LAMMPS for the -first time on a new platform, 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. - -Step 4 :h5 - -The "system-specific settings" section has several parts. Note that -if you change any -D setting in this section, you should do a full -re-compile, after typing "make clean" (which will describe different -clean options). - -The LMP_INC variable is used to include options that turn on ifdefs -within the LAMMPS code. The options that are currently recognized are: - --DLAMMPS_GZIP --DLAMMPS_JPEG --DLAMMPS_PNG --DLAMMPS_FFMPEG --DLAMMPS_MEMALIGN --DLAMMPS_SMALLBIG --DLAMMPS_BIGBIG --DLAMMPS_SMALLSMALL --DLAMMPS_LONGLONG_TO_LONG --DLAMMPS_EXCEPTIONS --DPACK_ARRAY --DPACK_POINTER --DPACK_MEMCPY :ul - -The read_data and dump commands will read/write gzipped files if you -compile with -DLAMMPS_GZIP. It 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 are -provided in the COMPRESS package. From more details about compiling -LAMMPS with packages, please see below. - -If you use -DLAMMPS_JPEG, the "dump image"_dump_image.html command -will be able to write out JPEG image files. For JPEG files, you must -also link LAMMPS with a JPEG library, as described below. If you use --DLAMMPS_PNG, the "dump image"_dump.html command will be able to write -out PNG image files. For PNG files, you must also link LAMMPS with a -PNG library, as described below. If neither of those two defines are -used, LAMMPS will only be able to write out uncompressed PPM image -files. - -If you use -DLAMMPS_FFMPEG, the "dump movie"_dump_image.html command -will be available to support on-the-fly generation of rendered movies -the need to store intermediate image files. It requires that your -machines supports the "popen" function in the standard runtime library -and that an FFmpeg executable can be found by LAMMPS during the run. - -NOTE: Similar to the note above, this option can conflict with -high-speed networks, because it uses popen(). - -Using -DLAMMPS_MEMALIGN= enables the use of the -posix_memalign() call instead of malloc() when large chunks or memory -are allocated by LAMMPS. This can help to make more efficient use of -vector instructions of modern CPUS, since dynamically allocated memory -has to be aligned on larger than default byte boundaries (e.g. 16 -bytes instead of 8 bytes on x86 type platforms) for optimal -performance. - -Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, --DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These -settings refer to use of 4-byte (small) vs 8-byte (big) integers -within LAMMPS, as specified in src/lmptype.h. The only reason to use -the BIGBIG setting is to enable simulation of huge molecular systems -(which store bond topology info) with more than 2 billion atoms, or to -track the image flags of moving atoms that wrap around a periodic box -more than 512 times. Normally, the only reason to use SMALLSMALL is -if your machine does not support 64-bit integers, though you can use -SMALLSMALL setting if you are running in serial or on a desktop -machine or small cluster where you will never run large systems or for -long time (more than 2 billion atoms, more than 2 billion timesteps). -See the "Additional build tips"_#start_2_4 section below for more -details on these settings. - -Note that the USER-ATC package is not currently compatible with --DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to -be compiled with the same setting, or the link will fail. - -The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or -MPI version does not recognize "long long" data types. In this case a -"long" data type is likely already 64-bits, in which case this setting -will convert to that data type. - -The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative -versions of error handling inside of LAMMPS. This is useful when -external codes drive LAMMPS as a library. Using this option, LAMMPS -errors do not kill the caller. Instead, the call stack is unwound and -control returns to the caller. The library interface provides the -lammps_has_error() and lammps_get_last_error_message() functions to -detect and find out more about a LAMMPS error. - -Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY -options can make for faster parallel FFTs (in the PPPM solver) on some -platforms. The -DPACK_ARRAY setting is the default. See the -"kspace_style"_kspace_style.html command for info about PPPM. See -Step 6 below for info about building LAMMPS with an FFT library. - -Step 5 :h5 - -The 3 MPI variables are used to specify an MPI library to build LAMMPS -with. Note that you do not need to set these if you use the MPI -compiler mpicxx for your CC and LINK setting in the section above. -The MPI wrapper knows where to find the needed files. - -If you want LAMMPS to run in parallel, you must have an MPI library -installed on your platform. If MPI is installed on your system in the -usual place (under /usr/local), you also may not need to specify these -3 variables, assuming /usr/local is in your path. On some large -parallel machines which use "modules" for their compile/link -environments, you may simply need to include the correct module in -your build environment, before building LAMMPS. Or the parallel -machine may have a vendor-provided MPI which the compiler has no -trouble finding. - -Failing this, these 3 variables can be used to specify where the mpi.h -file (MPI_INC) and the MPI library file (MPI_PATH) are found and the -name of the library file (MPI_LIB). - -If you are installing MPI yourself, we recommend Argonne's MPICH2 -or OpenMPI. MPICH can be downloaded from the "Argonne MPI -site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can -be downloaded from the "OpenMPI site"_http://www.open-mpi.org. -Other MPI packages should also work. If you are running on a big -parallel platform, your system people 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. If you use MPICH or OpenMPI, you will have to -configure and build it for your platform. The MPI configure script -should have compiler options to enable you to use the same compiler -you are using for the LAMMPS build, which can avoid problems that can -arise when linking LAMMPS to the MPI library. - -If you just want to run LAMMPS on a single processor, you can use the -dummy MPI library provided in src/STUBS, since you don't need a true -MPI library installed on your system. See src/MAKE/Makefile.serial -for how to specify the 3 MPI variables in this case. You will also -need to build the STUBS library for your platform before making LAMMPS -itself. Note that if you are building with src/MAKE/Makefile.serial, -e.g. by typing "make serial", then the STUBS library is built for you. - -To build the STUBS library from the src directory, type "make -mpi-stubs", or from the src/STUBS dir, type "make". This should -create a libmpi_stubs.a file suitable for linking to LAMMPS. 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. - -Step 6 :h5 - -The 3 FFT variables allow you to specify an FFT library which LAMMPS -uses (for performing 1d FFTs) when running the particle-particle -particle-mesh (PPPM) option for long-range Coulombics via the -"kspace_style"_kspace_style.html command. - -LAMMPS supports common open-source or vendor-supplied FFT libraries -for this purpose. If you leave these 3 variables blank, LAMMPS will -use the open-source "KISS FFT library"_http://kissfft.sf.net, which is -included in the LAMMPS distribution. This library is portable to all -platforms and for typical LAMMPS simulations is almost as fast as FFTW -or vendor optimized libraries. If you are not including the KSPACE -package in your build, you can also leave the 3 variables blank. - -Otherwise, select which kinds of FFTs to use as part of the FFT_INC -setting by a switch of the form -DFFT_XXX. Recommended values for XXX -are: MKL or FFTW3. FFTW2 and NONE are supported as legacy options. -Selecting -DFFT_FFTW will use the FFTW3 library and -DFFT_NONE will -use the KISS library described above. - -You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, -so the compiler and linker can find the needed FFT header and library -files. Note that on some large parallel machines which use "modules" -for their compile/link environments, you may simply need to include -the correct module in your build environment. Or the parallel machine -may have a vendor-provided FFT library which the compiler has no -trouble finding. See the src/MAKE/OPTIONS/Makefile.fftw file for an -example of how to specify these variables to use the FFTW3 library. - -FFTW is fast, portable library that should also work on any platform -and typically be faster than KISS FFT. You can download it from -"www.fftw.org"_http://www.fftw.org. Both the legacy version 2.1.X and -the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3. -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. - -If you wish to have FFTW support for single-precision FFTs (see below -about -DFFT_SINGLE) in addition to the default double-precision FFTs, -you will need to build FFTW a second time for single-precision. For -FFTW3, do this via: - -make clean -./configure --enable-single; make; make install :pre - -which should produce the additional library libfftw3f.a. - -For FFTW2, do this: - -make clean -./configure --enable-float --enable-type-prefix; make; make install :pre - -which should produce the additional library libsfftw.a and additional -include file sfttw.a. Note that on some platforms FFTW2 has been -pre-installed for both single- and double-precision, and may already -have these files as well as libdfftw.a and dfftw.h for double -precision. - -The FFT_INC variable also allows for a -DFFT_SINGLE setting that will -use single-precision FFTs with PPPM, which can speed-up long-range -calculations, particularly in parallel or on GPUs. Fourier transform -and related PPPM operations are somewhat insensitive to floating point -truncation errors and thus do not always need to be performed in -double precision. Using the -DFFT_SINGLE setting trades off a little -accuracy for reduced memory use and parallel communication costs for -transposing 3d FFT data. Note that single precision FFTs have only -been tested with the FFTW3, FFTW2, MKL, and KISS FFT options. - -When using -DFFT_SINGLE with FFTW3 or FFTW2, you need to build FFTW -with support for single-precision, as explained above. For FFTW3 you -also need to include -lfftw3f with the FFT_LIB setting, in addition to --lfftw3. For FFTW2, you also need to specify -DFFT_SIZE with the -FFT_INC setting and -lsfftw with the FFT_LIB setting (in place of --lfftw). Similarly, if FFTW2 has been pre-installed with an explicit -double-precision library (libdfftw.a and not the default libfftw.a), -then you can specify -DFFT_SIZE (and not -DFFT_SINGLE), and specify --ldfftw to use double-precision FFTs. - -Step 7 :h5 - -The 3 JPG variables allow you to specify a JPEG and/or PNG library -which LAMMPS uses when writing out JPEG or PNG files via the "dump -image"_dump_image.html command. These can be left blank if you do not -use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step -4, since in that case JPEG/PNG output will be disabled. - -A standard JPEG library usually goes by the name libjpeg.a or -libjpeg.so and has an associated header file jpeglib.h. Whichever -JPEG library you have on your platform, you'll need to set the -appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the -compiler and linker can find it. - -A standard PNG library usually goes by the name libpng.a or libpng.so -and has an associated header file png.h. Whichever PNG library you -have on your platform, you'll need to set the appropriate JPG_INC, -JPG_PATH, and JPG_LIB variables, so that the compiler and linker can -find it. - -As before, if these header and library files are in the usual place on -your machine, you may not need to set these variables. - -Step 8 :h5 - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below, before proceeding to Step 9. - -Step 9 :h5 - -That's it. Once you have a correct Makefile.foo, and you have -pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need -to do from the src directory is type something like this: - -make foo -make -j N foo -gmake foo -gmake -j N foo :pre - -The -j or -j N switches perform a parallel build which can be much -faster, depending on how many cores your compilation machine has. N -is the number of cores the build runs on. - -You should get the executable lmp_foo when the build is complete. - -:line - -Errors that can occur when making LAMMPS :h4 :link(start_2_3) - -If an error occurs when building LAMMPS, the compiler or linker will -state very explicitly what the problem is. The error message should -give you a hint as to which of the steps above has failed, and what -you need to do in order to fix it. Building a code with a Makefile is -a very logical process. The compiler and linker need to find the -appropriate files and those files need to be compatible with LAMMPS -settings and source files. When a make fails, there is usually a very -simple reason, which you or a local expert will need to fix. - -Here are two non-obvious errors that can occur: - -(1) If the make command breaks immediately with errors that indicate -it can't find files with a "*" in their names, this can be because -your machine's native make doesn't support wildcard expansion in a -makefile. Try gmake instead of make. If that doesn't work, try using -a -f switch with your make command to use a pre-generated -Makefile.list which explicitly lists all the needed files, e.g. - -make makelist -make -f Makefile.list linux -gmake -f Makefile.list mac :pre - -The first "make" command will create a current Makefile.list with all -the file names in your src dir. The 2nd "make" command (make or -gmake) will use it to build LAMMPS. Note that you should -include/exclude any desired optional packages before using the "make -makelist" command. - -(2) If you get an error that says something like 'identifier "atoll" -is undefined', then your machine does not support "long long" -integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described -above in Step 4. - -:line - -Additional build tips :h4,link(start_2_4) - -Building LAMMPS for multiple platforms. :h5 - -You can make LAMMPS for multiple platforms from the same src -directory. Each target creates its own object sub-directory called -Obj_target where it stores the system-specific *.o files. - -Cleaning up. :h5 - -Typing "make clean-all" or "make clean-machine" will delete *.o object -files created when LAMMPS is built, for either all builds or for a -particular machine. - -Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :h5 - -As explained above, any of these 3 settings can be specified on the -LMP_INC line in your low-level src/MAKE/Makefile.foo. - -The default is -DLAMMPS_SMALLBIG which allows for systems with up to -2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for -atomic systems which do not store bond topology info and thus do not -require atom IDs. If you use atom IDs for atomic systems (which is -the default) or if you use a molecular model, which stores bond -topology info and thus requires atom IDs, the limit is 2^31 atoms -(about 2 billion). This is because the IDs are stored in 32-bit -integers. - -Likewise, with this setting, the 3 image flags for each atom (see the -"dump"_dump.html doc page for a discussion) are stored in a 32-bit -integer, which means the atoms can only wrap around a periodic box (in -each dimension) at most 512 times. If atoms move through the periodic -box more than this many times, the image flags will "roll over", -e.g. from 511 to -512, which can cause diagnostics like the -mean-squared displacement, as calculated by the "compute -msd"_compute_msd.html command, to be faulty. - -To allow for larger atomic systems with atom IDs or larger molecular -systems or larger image flags, compile with -DLAMMPS_BIGBIG. This -stores atom IDs and image flags in 64-bit integers. This enables -atomic or molecular systems with atom IDS of up to 2^63 atoms (about -9e18). And image flags will not "roll over" until they reach 2^20 = -1048576. - -If your system does not support 8-byte integers, you will need to -compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the -total number of atoms (for atomic or molecular systems) and timesteps -to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512. - -Note that in src/lmptype.h there are definitions of all these data -types as well as the MPI data types associated with them. The MPI -types need to be consistent with the associated C data types, or else -LAMMPS will generate a run-time error. As far as we know, the -settings defined in src/lmptype.h are portable and work on every -current system. - -In all cases, the size of problem that can be run on a per-processor -basis is limited by 4-byte integer storage to 2^31 atoms per processor -(about 2 billion). This should not normally be a limitation since such -a problem would have a huge per-processor memory footprint due to -neighbor lists and would run very slowly in terms of CPU secs/timestep. - -:line - -Building for a Mac :h4,link(start_2_5) - -OS X is a derivative of BSD Unix, so it should just work. See the -src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files. - -:line - -Building for Windows :h4,link(start_2_6) - -If you want to build a Windows version of LAMMPS, you can build it -yourself, but it may require some effort. LAMMPS expects a Unix-like -build environment for the default build procedure. This can be done -using either Cygwin or MinGW; the latter also exists as a ready-to-use -Linux-to-Windows cross-compiler in several Linux distributions. In -these cases, you can do the installation after installing several -unix-style commands like make, grep, sed and bash with some shell -utilities. - -For Cygwin and the MinGW cross-compilers, suitable makefiles are -provided in src/MAKE/MACHINES. When using other compilers, like -Visual C++ or Intel compilers for Windows, you may have to implement -your own build system. Due to differences between the Windows OS -and Windows system libraries to Unix-like environments like Linux -or MacOS, when compiling for Windows a few adjustments may be needed: - -Do [not] set the -DLAMMPS_MEMALIGN define (see LMP_INC makefile variable) -Add -lwsock32 -lpsapi to the linker flags (see LIB makefile variable) -Try adding -static-libgcc or -static or both to the linker flags when your LAMMPS executable complains about missing .dll files :ul - -Since none of the current LAMMPS core developers has significant -experience building executables on Windows, we are happy to distribute -contributed instructions and modifications to improve the situation, -but we cannot provide support for those. - -With the so-called "Anniversary Update" to Windows 10, there is a -Ubuntu Linux subsystem available for Windows, that can be installed -and then used to compile/install LAMMPS as if you are running on a -Ubuntu Linux system instead of Windows. - -As an alternative, you can download pre-compiled installer packages from -"packages.lammps.org/windows.html"_http://packages.lammps.org/windows.html. -These executables are built with most optional packages included and the -download includes documentation, potential files, some tools and many -examples, but no source code. - -:line - -2.3 Making LAMMPS with optional packages :h3,link(start_3) - -This section has the following sub-sections: - -2.3.1 "Package basics"_#start_3_1 -2.3.2 "Including/excluding packages"_#start_3_2 -2.3.3 "Packages that require extra libraries"_#start_3_3 :all(b) - -:line - -Package basics: :h4,link(start_3_1) - -The source code for LAMMPS is structured as a set of core files which -are always included, plus optional packages. Packages are groups of -files that enable a specific set of features. For example, force -fields for molecular systems or granular systems are in packages. - -The "Packages"_Packages.html doc pages has details about all the -packages, which come in two flavors: [standard] and [user] -packages. It also has specific instructions for building LAMMPS with -any package which requires an extra library. General instructions are -below. - -You can see the list of all packages by typing "make package" from -within the src directory of the LAMMPS distribution. It will also -list various make commands that can be used to manage packages. - -If you use a command in a LAMMPS input script that is part of a -package, you must have built LAMMPS with that package, else you will -get an error that the style is invalid or the command is unknown. -Every command's doc page specifies if it is part of a package. You can -type - -lmp_machine -h :pre - -to run your executable with the optional "-h command-line -switch"_#start_6 for "help", which will list the styles and commands -known to your executable, and immediately exit. - -:line - -Including/excluding packages :h4,link(start_3_2) - -To use (or not use) a package you must install it (or un-install it) -before building LAMMPS. From the src directory, this is as simple as: - -make yes-colloid -make mpi :pre - -or - -make no-user-omp -make mpi :pre - -NOTE: You should NOT install/un-install packages and build LAMMPS in a -single make command using 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. - -Any package can be installed or not 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. I.e. individual files are only included if their dependencies -are already included. Likewise, if a package is excluded, other files -dependent on that package are also excluded. - -NOTE: The one exception is that we do not recommend building with both -the KOKKOS package installed and any of the other acceleration -packages (GPU, OPT, USER-INTEL, USER-OMP) also installed. This is -because of how Kokkos sometimes builds using a wrapper compiler which -can make it difficult to invoke all the compile/link flags correctly -for both Kokkos and non-Kokkos files. - -If you will never run simulations that use the features in a -particular packages, there is no reason to include it in your build. -For some packages, this will keep you from having to build extra -libraries, and will also produce a smaller executable which may run a -bit faster. - -When you download a LAMMPS tarball, three packages are pre-installed -in the src directory -- KSPACE, MANYBODY, MOLECULE -- because they are -so commonly used. When you download LAMMPS source files from the SVN -or Git repositories, no packages are pre-installed. - -Packages are installed or un-installed by typing - -make yes-name -make no-name :pre - -where "name" is the name of the package in lower-case, e.g. name = -kspace for the KSPACE package or name = user-atc for the USER-ATC -package. You can also type any of these commands: - -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 :tb(s=|) - -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 moving -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. -After you have installed or un-installed a package, you must re-build -LAMMPS for the action to take effect. - -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 have -downloaded a patch from the LAMMPS web site. - -Typing "make package-status" or "make ps" will 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. - -Typing "make package-installed" or "make pi" will list which packages are -currently installed, without listing the status of packages that are not -installed. - -Typing "make package-update" or "make pu" will overwrite src files -with files from the package sub-directories if the package is -installed. It should be used after a patch has been applied, since -patches only update the files in the package sub-directory, but not -the src files. - -Typing "make package-overwrite" will overwrite files in the package -sub-directories with src files. - -Typing "make package-diff" lists all differences between these files. - -Again, just type "make package" to see all of the package-related make -options. - -:line - -Packages that require extra libraries :h4,link(start_3_3) - -A few of the standard and user packages require extra libraries. See -the "Packages"_Packages.html doc pages for two tables of packages -which indicate which ones require libraries. For each such package, -the Section 4 doc page gives details on how to build the extra -library, including how to download it if necessary. The basic ideas -are summarized here. - -[System libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with a "sys" in the last column -link to system libraries that typically already exist on your machine. -E.g. the python package links to a system Python library. If your -machine does not have the required library, you will have to download -and install it on your machine, in either the system or user space. - -[Internal libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "int" in the last column -link to internal libraries whose source code is included with LAMMPS, -in the lib/name directory where name is the package name. You must -first build the library in that directory before building LAMMPS with -that package installed. E.g. the gpu package links to a library you -build in the lib/gpu dir. You can often do the build in one step by -typing "make lib-name args=..." from the src dir, with appropriate -arguments. You can leave off the args to see a help message. See the -"Packages details"_Packages_details.html doc page for details for each -package. - -[External libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "ext" in the last column -link to external libraries whose source code is not included with -LAMMPS. You must first download and install the library before -building LAMMPS with that package installed. E.g. the voronoi package -links to the freely available "Voro++ library"_voro_home2. You can -often do the download/build in one step by typing "make lib-name -args=..." from the src dir, with appropriate arguments. You can leave -off the args to see a help message. See the "Packages -details"_Packages_details.html doc page for details for each package. - -:link(voro_home2,http://math.lbl.gov/voro++) - -[Possible errors:] - -There are various common errors which can occur when building extra -libraries or when building LAMMPS with packages that require the extra -libraries. - -If you cannot build the extra library itself successfully, you may -need to edit or create an appropriate Makefile for your machine, e.g. -with appropriate compiler or system settings. Provided makefiles are -typically in the lib/name directory. E.g. see the Makefile.* files in -lib/gpu. - -The LAMMPS build often uses settings in a lib/name/Makefile.lammps -file which either exists in the LAMMPS distribution or is created or -copied from a lib/name/Makefile.lammps.* file when the library is -built. If those settings are not correct for your machine you will -need to edit or create an appropriate Makefile.lammps file. - -Package-specific details for these steps are given on the "Packages -details"_Packages_details.html doc page and in README files in the -lib/name directories. - -[Compiler options needed for accelerator packages:] - -Several packages contain code that is optimized for specific hardware, -e.g. CPU, KNL, or GPU. These are the OPT, GPU, KOKKOS, USER-INTEL, -and USER-OMP packages. Compiling and linking the source files in -these accelerator packages for optimal performance requires specific -settings in the Makefile.machine file you use. - -A summary of the Makefile.machine settings needed for each of these -packages is given on the "Packages"_Packages.html doc pages. More -info is given on the doc pages that describe each package in detail: - -"USER-INTEL package"_Speed_intel.html -"GPU package"_Speed_gpu.html -"KOKKOS package"_Speed_kokkos.html -"USER-OMP package"_Speed_omp.html -"OPT package"_Speed_opt.html :all(b) - -You can also use or examine the following machine Makefiles in -src/MAKE/OPTIONS, which include the settings. Note that the -USER-INTEL and KOKKOS packages can use settings that build LAMMPS for -different hardware. The USER-INTEL package can be compiled for Intel -CPUs and KNLs; the KOKKOS package builds for CPUs (OpenMP), GPUs -(CUDA), and Intel KNLs. - -Makefile.intel_cpu -Makefile.intel_phi -Makefile.kokkos_omp -Makefile.kokkos_cuda_mpi -Makefile.kokkos_phi -Makefile.omp -Makefile.opt :ul - -:line - -2.4 Building LAMMPS as a library :h3,link(start_4) - -LAMMPS can be built as either a static or shared library, which can -then be called from another application or a scripting language. See -the "Howto couple"_Howto_couple.html doc page for more info on -coupling LAMMPS to other codes. See the "Python"_Python.html doc page -for more info on wrapping and running LAMMPS from Python. - -Static library :h4 - -To build LAMMPS as a static library (*.a file on Linux), type - -make foo mode=lib :pre - -where foo is the machine name. This kind of library is typically used -to statically link a driver application to LAMMPS, so that you can -insure all dependencies are satisfied at compile time. This will use -the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build -will create the file liblammps_foo.a which another application can -link to. It will also create a soft link liblammps.a, which will -point to the most recently built static library. - -Shared library :h4 - -To build LAMMPS as a shared library (*.so file on Linux), which can be -dynamically loaded, e.g. from Python, type - -make foo mode=shlib :pre - -where foo is the machine name. This kind of library is required when -wrapping LAMMPS with Python; see the "Python"_Python.html doc page for -details. This will use the SHFLAGS and SHLIBFLAGS settings in -src/MAKE/Makefile.foo and perform the build in the directory -Obj_shared_foo. This is so that each file can be compiled with the --fPIC flag which is required for inclusion in a shared library. The -build will create the file liblammps_foo.so which another application -can link to dynamically. It will also create a soft link -liblammps.so, which will point to the most recently built shared -library. This is the file the Python wrapper loads by default. - -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 -lib/packages, 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. - -Here is an example of such errors when the system FFTW or provided -lib/colvars library have not been built as shared libraries: - -/usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation -R_X86_64_32 against '.rodata' can not be used when making a shared -object; recompile with -fPIC -/usr/local/lib/libfftw3.a: could not read symbols: Bad value :pre - -/usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o): -relocation R_X86_64_32 against '__pthread_key_create' can not be used -when making a shared object; recompile with -fPIC -../../lib/colvars/libcolvars.a: error adding symbols: Bad value :pre - -As an example, here is how to build and install the "MPICH -library"_mpich, a popular open-source version of MPI, distributed by -Argonne National Labs, as a shared library in the default -/usr/local/lib location: - -:link(mpich,http://www-unix.mcs.anl.gov/mpi) - -./configure --enable-shared -make -make install :pre - -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. - -[Additional requirement for using a shared library:] :h4 - -The operating system finds shared libraries to load at run-time using -the environment variable LD_LIBRARY_PATH. So you may wish to copy the -file src/liblammps.so or src/liblammps_g++.so (for example) to a place -the system can find it by default, such as /usr/local/lib, or you may -wish to add the LAMMPS src directory to 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: - -setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre - -Calling the LAMMPS library :h4 - -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 or a scripting language like -Python, the library has a simple function-style interface, provided in -src/library.cpp and src/library.h. - -See the sample codes in examples/COUPLE/simple for examples of C++ and -C and Fortran codes that invoke LAMMPS thru its library interface. -There are other examples as well in the COUPLE directory which use -coupling ideas discussed on the "Howto couple"_Howto_couple.html doc -page. See the "Python"_Python.html doc page for a description of the -Python wrapper provided with LAMMPS that operates through the LAMMPS -library interface. - -The files src/library.cpp and library.h define the C-style API for -using LAMMPS as a library. See the "Howto library"_Howto_library.html -doc page for a description of the interface and how to extend it for -your needs. - -:line - -2.5 Running LAMMPS :h3,link(start_5) - -By default, LAMMPS runs by reading commands from standard input. Thus -if you run the LAMMPS executable by itself, e.g. - -lmp_linux :pre - -it will simply wait, expecting commands from the keyboard. Typically -you should put commands in an input script and use I/O redirection, -e.g. - -lmp_linux < in.file :pre - -For parallel environments this should also work. If it does not, use -the '-in' command-line switch, e.g. - -lmp_linux -in in.file :pre - -The "Commands"_Commands.html doc page describes how input scripts are -structured and what commands they contain. - -You can test LAMMPS on any of the sample inputs provided in the -examples or bench directory. Input scripts are named in.* and sample -outputs are named log.*.name.P where name is a machine and P is the -number of processors it was run on. - -Here is how you might run a standard Lennard-Jones benchmark on a -Linux box, using mpirun to launch a parallel job: - -cd src -make linux -cp lmp_linux ../bench -cd ../bench -mpirun -np 4 lmp_linux -in in.lj :pre - -See "this page"_bench for timings for this and the other benchmarks on -various platforms. Note that some of the example scripts require -LAMMPS to be built with one or more of its optional packages. - -:link(bench,http://lammps.sandia.gov/bench.html) - -:line - -On a Windows box, you can skip making LAMMPS and simply download an -installer package from "here"_http://packages.lammps.org/windows.html - -For running the non-MPI executable, follow these steps: - -Get a command prompt by going to Start->Run... , -then typing "cmd". :ulb,l - -Move to the directory where you have your input, e.g. a copy of -the [in.lj] input from the bench folder. (e.g. by typing: cd "Documents"). :l - -At the command prompt, type "lmp_serial -in in.lj", replacing [in.lj] -with the name of your LAMMPS input script. :l - -The serial executable includes support for multi-threading -parallelization from the styles in the USER-OMP packages. - -To run with, e.g. 4 threads, type "lmp_serial -in in.lj -pk omp 4 -sf omp" -:ule - -For the MPI version, which allows you to run LAMMPS under Windows with -the more general message passing parallel library (LAMMPS has been -designed from ground up to use MPI efficiently), follow these steps: - -Download and install a compatible MPI library binary package: -for 32-bit Windows -"mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi -and for 64-bit Windows -"mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi -:ulb,l - -The LAMMPS Windows installer packages will automatically adjust your -path for the default location of this MPI package. After the installation -of the MPICH2 software, it needs to be integrated into the system. -For this you need to start a Command Prompt in {Administrator Mode} -(right click on the icon and select it). Change into the MPICH2 -installation directory, then into the subdirectory [bin] and execute -[smpd.exe -install]. Exit the command window. - -Get a new, regular command prompt by going to Start->Run... , -then typing "cmd". :l - -Move to the directory where you have your input file -(e.g. by typing: cd "Documents"). :l - -Then type something like this: - -mpiexec -localonly 4 lmp_mpi -in in.lj :pre -or - -mpiexec -np 4 lmp_mpi -in in.lj :pre - -replacing [in.lj] with the name of your LAMMPS input script. For the latter -case, you may be prompted to enter your password. :l - -In this mode, output may not immediately show up on the screen, so if -your input script takes a long time to execute, you may need to be -patient before the output shows up. :l - -The parallel executable can also run on a single processor by typing -something like: - -lmp_mpi -in in.lj :pre - -And the parallel executable also includes OpenMP multi-threading, which -can be combined with MPI using something like: - -mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre - -:ule - -:line - -The screen output from LAMMPS is described in a section below. As it -runs, LAMMPS also writes a log.lammps file with the same information. - -Note that this sequence of commands copies the LAMMPS executable -(lmp_linux) to the directory with the input files. This may not be -necessary, but some versions of MPI reset the working directory to -where the executable is, rather than leave it as the directory where -you launch mpirun from (if you launch lmp_linux on its own and not -under mpirun). If that happens, LAMMPS will look for additional input -files and write its output files to the executable directory, rather -than your working directory, which is probably not what you want. - -If LAMMPS encounters errors in the input script or while running a -simulation it will print an ERROR message and stop or a WARNING -message and continue. See the "Errors"_Errors.html doc page for a -discussion of the various kinds of errors LAMMPS can or can't detect, -a list of all ERROR and WARNING messages, and what to do about them. - -LAMMPS can run a problem on any number of processors, including a -single processor. In theory you should get identical answers on any -number of processors and on any machine. In practice, numerical -round-off can cause slight differences and eventual divergence of -molecular dynamics phase space trajectories. - -LAMMPS can run as large a problem as will fit in the physical memory -of one or more processors. If you run out of memory, you must run on -more processors or setup a smaller problem. - -:line - -2.6 Command-line options :h3,link(start_6) - -At run time, LAMMPS recognizes several optional command-line switches -which may be used in any order. Either the full word or a one-or-two -letter abbreviation can be used: - --e or -echo --h or -help --i or -in --k or -kokkos --l or -log --nc or -nocite --pk or -package --p or -partition --pl or -plog --ps or -pscreen --r or -restart --ro or -reorder --sc or -screen --sf or -suffix --v or -var :ul - -For example, lmp_ibm might be launched as follows: - -mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy -mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy :pre - -Here are the details on the options: - --echo style :pre - -Set the style of command echoing. The style can be {none} or {screen} -or {log} or {both}. Depending on the style, each command read from -the input script will be echoed to the screen and/or logfile. This -can be useful to figure out which line of your script is causing an -input error. The default value is {log}. The echo style can also be -set by using the "echo"_echo.html command in the input script itself. - --help :pre - -Print a brief help summary and a list of options compiled into this -executable for each LAMMPS style (atom_style, fix, compute, -pair_style, bond_style, etc). This can tell you if the command you -want to use was included via the appropriate package at compile time. -LAMMPS will print the info and immediately exit if this switch is -used. - --in file :pre - -Specify a file to use as an input script. This is an optional switch -when running LAMMPS in one-partition mode. If it is not specified, -LAMMPS reads its script from standard input, typically from a script -via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should -also work in parallel, but if it does not (in the unlikely case that -an MPI implementation does not support it), then use the -in flag. -Note that this is a required switch when running LAMMPS in -multi-partition mode, since multiple processors cannot all read from -stdin. - --kokkos on/off keyword/value ... :pre - -Explicitly enable or disable KOKKOS support, as provided by the KOKKOS -package. Even if LAMMPS is built with this package, as described -above in "Section 2.3"_#start_3, this switch must be set to enable -running with the KOKKOS-enabled styles the package provides. If the -switch is not set (the default), LAMMPS will operate as if the KOKKOS -package were not installed; i.e. you can run standard LAMMPS or with -the GPU or USER-OMP packages, for testing or benchmarking purposes. - -Additional optional keyword/value pairs can be specified which -determine how Kokkos will use the underlying hardware on your -platform. These settings apply to each MPI task you launch via the -"mpirun" or "mpiexec" command. You may choose to run one or more MPI -tasks per physical node. Note that if you are running on a desktop -machine, you typically have one physical node. On a cluster or -supercomputer there may be dozens or 1000s of physical nodes. - -Either the full word or an abbreviation can be used for the keywords. -Note that the keywords do not use a leading minus sign. I.e. the -keyword is "t", not "-t". Also note that each of the keywords has a -default setting. Example of when to use these options and what -settings to use on different platforms is given on the "Speed -kokkos"_Speed_kokkos.html doc page. - -d or device -g or gpus -t or threads -n or numa :ul - -device Nd :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and if you are running with only one -MPI task per node. The Nd setting is the ID of the GPU on the node to -run on. By default Nd = 0. If you have multiple GPUs per node, they -have consecutive IDs numbered as 0,1,2,etc. This setting allows you -to launch multiple independent jobs on the node, each with a single -MPI task per node, and assign each job to run on a different GPU. - -gpus Ng Ns :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and you are running with multiple MPI -tasks per node (up to one per GPU). The Ng setting is how many GPUs -you will use. The Ns setting is optional. If set, it is the ID of a -GPU to skip when assigning MPI tasks to GPUs. This may be useful if -your desktop system reserves one GPU to drive the screen and the rest -are intended for computational work like running LAMMPS. By default -Ng = 1 and Ns is not set. - -Depending on which flavor of MPI you are running, LAMMPS will look for -one of these 3 environment variables - -SLURM_LOCALID (various MPI variants compiled with SLURM support) -MV2_COMM_WORLD_LOCAL_RANK (Mvapich) -OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre - -which are initialized by the "srun", "mpirun" or "mpiexec" commands. -The environment variable setting for each MPI rank is used to assign a -unique GPU ID to the MPI task. - -threads Nt :pre - -This option assigns Nt number of threads to each MPI task for -performing work when Kokkos is executing in OpenMP or pthreads mode. -The default is Nt = 1, which essentially runs in MPI-only mode. If -there are Np MPI tasks per physical node, you generally want Np*Nt = -the number of physical cores per node, to use your available hardware -optimally. This also sets the number of threads used by the host when -LAMMPS is compiled with CUDA=yes. - -numa Nm :pre - -This option is only relevant when using pthreads with hwloc support. -In this case Nm defines the number of NUMA regions (typically sockets) -on a node which will be utilized by a single MPI rank. By default Nm -= 1. If this option is used the total number of worker-threads per -MPI rank is threads*numa. Currently it is always almost better to -assign at least one MPI rank per NUMA region, and leave numa set to -its default value of 1. This is because letting a single process span -multiple NUMA regions induces a significant amount of cross NUMA data -traffic which is slow. - --log file :pre - -Specify a log file for LAMMPS to write status information to. In -one-partition mode, if the switch is not used, LAMMPS writes to the -file log.lammps. If this switch is used, LAMMPS writes to the -specified file. In multi-partition mode, if the switch is not used, a -log.lammps file is created with hi-level status information. Each -partition also writes to a log.lammps.N file where N is the partition -ID. If the switch is specified in multi-partition mode, the hi-level -logfile is named "file" and each partition also logs information to a -file.N. For both one-partition and multi-partition mode, if the -specified file is "none", then no log files are created. Using a -"log"_log.html command in the input script will override this setting. -Option -plog will override the name of the partition log files file.N. - --nocite :pre - -Disable writing the log.cite file which is normally written to list -references for specific cite-able features used during a LAMMPS run. -See the "citation page"_http://lammps.sandia.gov/cite.html for more -details. - --package style args .... :pre - -Invoke the "package"_package.html command with style and args. The -syntax is the same as if the command appeared at the top of the input -script. For example "-package gpu 2" or "-pk gpu 2" is the same as -"package gpu 2"_package.html in the input script. The possible styles -and args are documented on the "package"_package.html doc page. This -switch can be used multiple times, e.g. to set options for the -USER-INTEL and USER-OMP packages which can be used together. - -Along with the "-suffix" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - --partition 8x2 4 5 ... :pre - -Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P -processors and this switch is not used, LAMMPS runs in one partition, -i.e. all P processors run a single simulation. If this switch is -used, the P processors are split into separate partitions and each -partition runs its own simulation. The arguments to the switch -specify the number of processors in each partition. Arguments of the -form MxN mean M partitions, each with N processors. Arguments of the -form N mean a single partition with N processors. The sum of -processors in all partitions must equal P. Thus the command -"-partition 8x2 4 5" has 10 partitions and runs on a total of 25 -processors. - -Running with multiple partitions can be useful for running -"multi-replica simulations"_Howto_replica.html, where each replica -runs on on one or a few processors. Note that with MPI installed on a -machine (e.g. your desktop), you can run on more (virtual) processors -than you have physical processors. - -To run multiple independent simulations from one input script, using -multiple partitions, see the "Howto multiple"_Howto_multiple.html doc -page. World- and universe-style "variables"_variable.html are useful -in this context. - --plog file :pre - -Specify the base name for the partition log files, so partition N -writes log information to file.N. If file is none, then no partition -log files are created. This overrides the filename specified in the --log command-line option. This option is useful when working with -large numbers of partitions, allowing the partition log files to be -suppressed (-plog none) or placed in a sub-directory (-plog -replica_files/log.lammps) If this option is not used the log file for -partition N is log.lammps.N or whatever is specified by the -log -command-line option. - --pscreen file :pre - -Specify the base name for the partition screen file, so partition N -writes screen information to file.N. If file is none, then no -partition screen files are created. This overrides the filename -specified in the -screen command-line option. This option is useful -when working with large numbers of partitions, allowing the partition -screen files to be suppressed (-pscreen none) or placed in a -sub-directory (-pscreen replica_files/screen). If this option is not -used the screen file for partition N is screen.N or whatever is -specified by the -screen command-line option. - --restart restartfile {remap} datafile keyword value ... :pre - -Convert the restart file into a data file and immediately exit. This -is the same operation as if the following 2-line input script were -run: - -read_restart restartfile {remap} -write_data datafile keyword value ... :pre - -Note that the specified restartfile and datafile can have wild-card -characters ("*",%") as described by the -"read_restart"_read_restart.html and "write_data"_write_data.html -commands. But a filename such as file.* will need to be enclosed in -quotes to avoid shell expansion of the "*" character. - -Note that following restartfile, the optional flag {remap} can be -used. This has the same effect as adding it to the -"read_restart"_read_restart.html command, as explained on its doc -page. This is only useful if the reading of the restart file triggers -an error that atoms have been lost. In that case, use of the remap -flag should allow the data file to still be produced. - -Also note that following datafile, the same optional keyword/value -pairs can be listed as used by the "write_data"_write_data.html -command. - --reorder nth N --reorder custom filename :pre - -Reorder the processors in the MPI communicator used to instantiate -LAMMPS, in one of several ways. The original MPI communicator ranks -all P processors from 0 to P-1. The mapping of these ranks to -physical processors is done by MPI before LAMMPS begins. It may be -useful in some cases to alter the rank order. E.g. to insure that -cores within each node are ranked in a desired order. Or when using -the "run_style verlet/split"_run_style.html command with 2 partitions -to insure that a specific Kspace processor (in the 2nd partition) is -matched up with a specific set of processors in the 1st partition. -See the "Speed tips"_Speed_tips.html doc page for more details. - -If the keyword {nth} is used with a setting {N}, then it means every -Nth processor will be moved to the end of the ranking. This is useful -when using the "run_style verlet/split"_run_style.html command with 2 -partitions via the -partition command-line switch. The first set of -processors will be in the first partition, the 2nd set in the 2nd -partition. The -reorder command-line switch can alter this so that -the 1st N procs in the 1st partition and one proc in the 2nd partition -will be ordered consecutively, e.g. as the cores on one physical node. -This can boost performance. For example, if you use "-reorder nth 4" -and "-partition 9 3" and you are running on 12 processors, the -processors will be reordered from - -0 1 2 3 4 5 6 7 8 9 10 11 :pre - -to - -0 1 2 4 5 6 8 9 10 3 7 11 :pre - -so that the processors in each partition will be - -0 1 2 4 5 6 8 9 10 -3 7 11 :pre - -See the "processors" command for how to insure processors from each -partition could then be grouped optimally for quad-core nodes. - -If the keyword is {custom}, then a file that specifies a permutation -of the processor ranks is also specified. The format of the reorder -file is as follows. Any number of initial blank or comment lines -(starting with a "#" character) can be present. These should be -followed by P lines of the form: - -I J :pre - -where P is the number of processors LAMMPS was launched with. Note -that if running in multi-partition mode (see the -partition switch -above) P is the total number of processors in all partitions. The I -and J values describe a permutation of the P processors. Every I and -J should be values from 0 to P-1 inclusive. In the set of P I values, -every proc ID should appear exactly once. Ditto for the set of P J -values. A single I,J pairing means that the physical processor with -rank I in the original MPI communicator will have rank J in the -reordered communicator. - -Note that rank ordering can also be specified by many MPI -implementations, either by environment variables that specify how to -order physical processors, or by config files that specify what -physical processors to assign to each MPI rank. The -reorder switch -simply gives you a portable way to do this without relying on MPI -itself. See the "processors out"_processors.html command for how -to output info on the final assignment of physical processors to -the LAMMPS simulation domain. - --screen file :pre - -Specify a file for LAMMPS to write its screen information to. In -one-partition mode, if the switch is not used, LAMMPS writes to the -screen. If this switch is used, LAMMPS writes to the specified file -instead and you will see no screen output. In multi-partition mode, -if the switch is not used, hi-level status information is written to -the screen. Each partition also writes to a screen.N file where N is -the partition ID. If the switch is specified in multi-partition mode, -the hi-level screen dump is named "file" and each partition also -writes screen information to a file.N. For both one-partition and -multi-partition mode, if the specified file is "none", then no screen -output is performed. Option -pscreen will override the name of the -partition screen files file.N. - --suffix style args :pre - -Use variants of various styles if they exist. The specified style can -be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These -refer to optional packages that LAMMPS can be built with, as described -above in "Section 2.3"_#start_3. The "gpu" style corresponds to the -GPU package, the "intel" style to the USER-INTEL package, the "kk" -style to the KOKKOS package, the "opt" style to the OPT package, and -the "omp" style to the USER-OMP package. The hybrid style is the only -style that accepts arguments. It allows for two packages to be -specified. The first package specified is the default and will be used -if it is available. If no style is available for the first package, -the style for the second package will be used if available. For -example, "-suffix hybrid intel omp" will use styles from the -USER-INTEL package if they are installed and available, but styles for -the USER-OMP package otherwise. - -Along with the "-package" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - -As an example, all of the packages provide a "pair_style -lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, -lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style -can be specified explicitly in your input script, e.g. pair_style -lj/cut/gpu. If the -suffix switch is used the specified suffix -(gpu,intel,kk,omp,opt) is automatically appended whenever your input -script command creates a new "atom"_atom_style.html, -"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or -"run"_run_style.html style. If the variant version does not exist, -the standard version is created. - -For the GPU package, using this command-line switch also invokes the -default GPU settings, as if the command "package gpu 1" were used at -the top of your input script. These settings can be changed by using -the "-package gpu" command-line switch or the "package -gpu"_package.html command in your script. - -For the USER-INTEL package, using this command-line switch also -invokes the default USER-INTEL settings, as if the command "package -intel 1" were used at the top of your input script. These settings -can be changed by using the "-package intel" command-line switch or -the "package intel"_package.html command in your script. If the -USER-OMP package is also installed, the hybrid style with "intel omp" -arguments can be used to make the omp suffix a second choice, if a -requested style is not available in the USER-INTEL package. It will -also invoke the default USER-OMP settings, as if the command "package -omp 0" were used at the top of your input script. These settings can -be changed by using the "-package omp" command-line switch or the -"package omp"_package.html command in your script. - -For the KOKKOS package, using this command-line switch also invokes -the default KOKKOS settings, as if the command "package kokkos" were -used at the top of your input script. These settings can be changed -by using the "-package kokkos" command-line switch or the "package -kokkos"_package.html command in your script. - -For the OMP package, using this command-line switch also invokes the -default OMP settings, as if the command "package omp 0" were used at -the top of your input script. These settings can be changed by using -the "-package omp" command-line switch or the "package -omp"_package.html command in your script. - -The "suffix"_suffix.html command can also be used within an input -script to set a suffix, or to turn off or back on any suffix setting -made via the command line. - --var name value1 value2 ... :pre - -Specify a variable that will be defined for substitution purposes when -the input script is read. This switch can be used multiple times to -define multiple variables. "Name" is the variable name which can be a -single character (referenced as $x in the input script) or a full -string (referenced as $\{abc\}). An "index-style -variable"_variable.html will be created and populated with the -subsequent values, e.g. a set of filenames. Using this command-line -option is equivalent to putting the line "variable name index value1 -value2 ..." at the beginning of the input script. Defining an index -variable as a command-line argument overrides any setting for the same -index variable in the input script, since index variables cannot be -re-defined. See the "variable"_variable.html command for more info on -defining index and other kinds of variables and the "Commands -parse"_Commands_parse.html page for more info on using variables in -input scripts. - -NOTE: Currently, the command-line parser looks for arguments that -start with "-" to indicate new switches. Thus you cannot specify -multiple variable values if any of they start with a "-", e.g. a -negative numeric value. It is OK if the first value1 starts with a -"-", since it is automatically skipped. - -:line - -2.7 LAMMPS screen output :h3,link(start_7) - -As LAMMPS reads an input script, it prints information to both the -screen and a log file about significant actions it takes to setup a -simulation. When the simulation is ready to begin, LAMMPS performs -various initializations and prints the amount of memory (in MBytes per -processor) that the simulation requires. It also prints details of -the initial thermodynamic state of the system. During the run itself, -thermodynamic information is printed periodically, every few -timesteps. When the run concludes, LAMMPS prints the final -thermodynamic state and a total run time for the simulation. It then -appends statistics about the CPU time and storage requirements for the -simulation. An example set of statistics is shown here: - -Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre - -Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s -97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre - -MPI task timings breakdown: -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 -Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 -Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 -Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 -Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 -Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 -Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 -Other | | 0.007178 | | | 0.26 :pre - -Nlocal: 501 ave 508 max 490 min -Histogram: 1 0 0 0 0 0 1 1 0 1 -Nghost: 6586.25 ave 6628 max 6548 min -Histogram: 1 0 1 0 0 0 1 0 0 1 -Neighs: 177007 ave 180562 max 170212 min -Histogram: 1 0 0 0 0 0 0 1 1 1 :pre - -Total # of neighbors = 708028 -Ave neighs/atom = 353.307 -Ave special neighs/atom = 2.34032 -Neighbor list builds = 26 -Dangerous builds = 0 :pre - -The first section provides a global loop timing summary. The {loop time} -is the total wall time for the section. The {Performance} line is -provided for convenience to help predicting the number of loop -continuations required and for comparing performance with other, -similar MD codes. The {CPU use} line provides the CPU utilization per -MPI task; it should be close to 100% times the number of OpenMP -threads (or 1 of no OpenMP). Lower numbers correspond to delays due -to file I/O or insufficient thread utilization. - -The MPI task section gives the breakdown of the CPU run time (in -seconds) into major categories: - -{Pair} stands for all non-bonded force computation -{Bond} stands for bonded interactions: bonds, angles, dihedrals, impropers -{Kspace} stands for reciprocal space interactions: Ewald, PPPM, MSM -{Neigh} stands for neighbor list construction -{Comm} stands for communicating atoms and their properties -{Output} stands for writing dumps and thermo output -{Modify} stands for fixes and computes called by them -{Other} is the remaining time :ul - -For each category, there is a breakdown of the least, average and most -amount of wall time a processor spent on this section. Also you have the -variation from the average time. Together these numbers allow to gauge -the amount of load imbalance in this segment of the calculation. Ideally -the difference between minimum, maximum and average is small and thus -the variation from the average close to zero. The final column shows -the percentage of the total loop time is spent in this section. - -When using the "timer full"_timer.html setting, an additional column -is present that also prints the CPU utilization in percent. In -addition, when using {timer full} and the "package omp"_package.html -command are active, a similar timing summary of time spent in threaded -regions to monitor thread utilization and load balance is provided. A -new entry is the {Reduce} section, which lists the time spent in -reducing the per-thread data elements to the storage for non-threaded -computation. These thread timings are taking from the first MPI rank -only and and thus, as the breakdown for MPI tasks can change from MPI -rank to MPI rank, this breakdown can be very different for individual -ranks. Here is an example output for this section: - -Thread timings breakdown (MPI rank 0): -Total threaded time 0.6846 / 90.6% -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 -Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 -Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 -Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 -Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre - -The third section lists the number of owned atoms (Nlocal), ghost atoms -(Nghost), and pair-wise neighbors stored per processor. The max and min -values give the spread of these values across processors with a 10-bin -histogram showing the distribution. The total number of histogram counts -is equal to the number of processors. - -The last section gives aggregate statistics for pair-wise neighbors -and special neighbors that LAMMPS keeps track of (see the -"special_bonds"_special_bonds.html command). The number of times -neighbor lists were rebuilt during the run is given as well as the -number of potentially "dangerous" rebuilds. If atom movement -triggered neighbor list rebuilding (see the -"neigh_modify"_neigh_modify.html command), then dangerous -reneighborings are those that were triggered on the first timestep -atom movement was checked for. If this count is non-zero you may wish -to reduce the delay factor to insure no force interactions are missed -by atoms moving beyond the neighbor skin distance before a rebuild -takes place. - -If an energy minimization was performed via the -"minimize"_minimize.html command, additional information is printed, -e.g. - -Minimization stats: - Stopping criterion = linesearch alpha is zero - Energy initial, next-to-last, final = - -6372.3765206 -8328.46998942 -8328.46998942 - Force two-norm initial, final = 1059.36 5.36874 - Force max component initial, final = 58.6026 1.46872 - Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 - Iterations, force evaluations = 701 1516 :pre - -The first line prints the criterion that determined the minimization -to be completed. The third line lists the initial and final energy, -as well as the energy on the next-to-last iteration. The next 2 lines -give a measure of the gradient of the energy (force on all atoms). -The 2-norm is the "length" of this force vector; the inf-norm is the -largest component. Then some information about the line search and -statistics on how many iterations and force-evaluations the minimizer -required. Multiple force evaluations are typically done at each -iteration to perform a 1d line minimization in the search direction. - -If a "kspace_style"_kspace_style.html long-range Coulombics solve was -performed during the run (PPPM, Ewald), then additional information is -printed, e.g. - -FFT time (% of Kspce) = 0.200313 (8.34477) -FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre - -The first line gives the time spent doing 3d FFTs (4 per timestep) and -the fraction it represents of the total KSpace time (listed above). -Each 3d FFT requires computation (3 sets of 1d FFTs) and communication -(transposes). The total flops performed is 5Nlog_2(N), where N is the -number of points in the 3d grid. The FFTs are timed with and without -the communication and a Gflop rate is computed. The 3d rate is with -communication; the 1d rate is without (just the 1d FFTs). Thus you -can estimate what fraction of your FFT time was spent in -communication, roughly 75% in the example above. - -:line - -2.8 Tips for users of previous LAMMPS versions :h3,link(start_8) - -The current C++ began with a complete rewrite of LAMMPS 2001, which -was written in F90. Features of earlier versions of LAMMPS are listed -on the "History page"_http://lammps.sandia.gov/history.html of the -LAMMPS website. The F90 and F77 versions (2001 and 99) are also -freely distributed as open-source codes; check the "History -page"_http://lammps.sandia.gov/history.html of the LAMMPS website for -info about those versions. The 99 and 2001 versions are no longer -under active development; they do not have all the features of C++ -LAMMPS. - -If you are a previous user of LAMMPS 2001, these are the most -significant changes you will notice in C++ LAMMPS: - -(1) The names and arguments of many input script commands have -changed. All commands are now a single word (e.g. read_data instead -of read data). - -(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, -but you may need to specify the relevant commands in different ways. - -(3) The format of the data file can be streamlined for some problems. -See the "read_data"_read_data.html command for details. The data file -section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS. - -(4) Binary restart files written by LAMMPS 2001 cannot be read by C++ -LAMMPS with a "read_restart"_read_restart.html command. This is -because they were output by F90 which writes in a different binary -format than C or C++ writes or reads. Use the {restart2data} tool -provided with LAMMPS 2001 to convert the 2001 restart file to a text -data file. Then edit the data file as necessary before using the C++ -LAMMPS "read_data"_read_data.html command to read it in. - -(5) There are numerous small numerical changes in C++ LAMMPS that mean -you will not get identical answers when comparing to a 2001 run. -However, your initial thermodynamic energy and MD trajectory should be -close if you have setup the problem for both codes the same.