diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index d9e60a5208..12a496cc9f 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -17,6 +17,32 @@ file(GLOB LIB_SOURCES ${LAMMPS_SOURCE_DIR}/*.cpp)
file(GLOB LMP_SOURCES ${LAMMPS_SOURCE_DIR}/main.cpp)
list(REMOVE_ITEM LIB_SOURCES ${LMP_SOURCES})
+# Utility functions
+function(list_to_bulletpoints result)
+ list(REMOVE_AT ARGV 0)
+ set(temp "")
+ foreach(item ${ARGV})
+ set(temp "${temp}* ${item}\n")
+ endforeach()
+ set(${result} "${temp}" PARENT_SCOPE)
+endfunction(list_to_bulletpoints)
+
+function(validate_option name values)
+ string(TOLOWER ${${name}} needle_lower)
+ string(TOUPPER ${${name}} needle_upper)
+ list(FIND ${values} ${needle_lower} IDX_LOWER)
+ list(FIND ${values} ${needle_upper} IDX_UPPER)
+ if(${IDX_LOWER} LESS 0 AND ${IDX_UPPER} LESS 0)
+ list_to_bulletpoints(POSSIBLE_VALUE_LIST ${${values}})
+ message(FATAL_ERROR "\n########################################################################\n"
+ "Invalid value '${${name}}' for option ${name}\n"
+ "\n"
+ "Possible values are:\n"
+ "${POSSIBLE_VALUE_LIST}"
+ "########################################################################")
+ endif()
+endfunction(validate_option)
+
# Cmake modules/macros are in a subdirectory to keep this file cleaner
set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/Modules)
@@ -106,8 +132,6 @@ if(NOT BUILD_EXE AND NOT BUILD_LIB)
message(FATAL_ERROR "You need to at least enable one of two following options: BUILD_LIB or BUILD_EXE")
endif()
-option(DEVELOPER_MODE "Enable developer mode" OFF)
-mark_as_advanced(DEVELOPER_MODE)
option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)
include(GNUInstallDirs)
@@ -133,15 +157,21 @@ else()
list(APPEND LAMMPS_LINK_LIBS mpi_stubs)
endif()
-set(LAMMPS_SIZE_LIMIT "LAMMPS_SMALLBIG" CACHE STRING "Lammps size limit")
-set_property(CACHE LAMMPS_SIZE_LIMIT PROPERTY STRINGS LAMMPS_SMALLBIG LAMMPS_BIGBIG LAMMPS_SMALLSMALL)
-add_definitions(-D${LAMMPS_SIZE_LIMIT})
-set(LAMMPS_API_DEFINES "${LAMMPS_API_DEFINES} -D${LAMMPS_SIZE_LIMIT}")
+
+set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS size limit")
+set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall)
+set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES})
+validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES)
+string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES)
+add_definitions(-DLAMMPS_${LAMMPS_SIZES})
+set(LAMMPS_API_DEFINES "${LAMMPS_API_DEFINES} -DLAMMPS_${LAMMPS_SIZES}")
# posix_memalign is not available on Windows
if(NOT ${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
- set(LAMMPS_MEMALIGN "64" CACHE STRING "enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS")
- add_definitions(-DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
+ set(LAMMPS_MEMALIGN "64" CACHE STRING "enables the use of the posix_memalign() call instead of malloc() when large chunks or memory are allocated by LAMMPS. Set to 0 to disable")
+ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "0")
+ add_definitions(-DLAMMPS_MEMALIGN=${LAMMPS_MEMALIGN})
+ endif()
endif()
option(LAMMPS_EXCEPTIONS "enable the use of C++ exceptions for error messages (useful for library interface)" OFF)
@@ -216,10 +246,12 @@ if(PKG_KSPACE)
if(${FFTW}_FOUND)
set(FFT "${FFTW}" CACHE STRING "FFT library for KSPACE package")
else()
- set(FFT "KISSFFT" CACHE STRING "FFT library for KSPACE package")
+ set(FFT "KISS" CACHE STRING "FFT library for KSPACE package")
endif()
- set_property(CACHE FFT PROPERTY STRINGS KISSFFT ${FFTW} MKL)
- if(NOT FFT STREQUAL "KISSFFT")
+ set(FFT_VALUES KISS ${FFTW} MKL)
+ set_property(CACHE FFT PROPERTY STRINGS ${FFT_VALUES})
+ validate_option(FFT FFT_VALUES)
+ if(NOT FFT STREQUAL "KISS")
find_package(${FFT} REQUIRED)
if(NOT FFT STREQUAL "FFTW3F")
add_definitions(-DFFT_FFTW)
@@ -228,11 +260,16 @@ if(PKG_KSPACE)
endif()
include_directories(${${FFT}_INCLUDE_DIRS})
list(APPEND LAMMPS_LINK_LIBS ${${FFT}_LIBRARIES})
+ else()
+ add_definitions(-DFFT_KISS)
endif()
- set(PACK_OPTIMIZATION "PACK_ARRAY" CACHE STRING "Optimization for FFT")
- set_property(CACHE PACK_OPTIMIZATION PROPERTY STRINGS PACK_ARRAY PACK_POINTER PACK_MEMCPY)
- if(NOT PACK_OPTIMIZATION STREQUAL "PACK_ARRAY")
- add_definitions(-D${PACK_OPTIMIZATION})
+ set(FFT_PACK "array" CACHE STRING "Optimization for FFT")
+ set(FFT_PACK_VALUES array pointer memcpy)
+ set_property(CACHE FFT_PACK PROPERTY STRINGS ${FFT_PACK_VALUES})
+ validate_option(FFT_PACK FFT_PACK_VALUES)
+ if(NOT FFT_PACK STREQUAL "array")
+ string(TOUPPER ${FFT_PACK} FFT_PACK)
+ add_definitions(-DFFT_PACK_${FFT_PACK})
endif()
endif()
@@ -374,8 +411,8 @@ if(PKG_USER-NETCDF)
endif()
if(PKG_USER-SMD)
- option(DOWNLOAD_Eigen3 "Download Eigen3 (instead of using the system's one)" OFF)
- if(DOWNLOAD_Eigen3)
+ option(DOWNLOAD_EIGEN3 "Download Eigen3 (instead of using the system's one)" OFF)
+ if(DOWNLOAD_EIGEN3)
include(ExternalProject)
ExternalProject_Add(Eigen3_build
URL http://bitbucket.org/eigen/eigen/get/3.3.4.tar.gz
@@ -388,7 +425,7 @@ if(PKG_USER-SMD)
else()
find_package(Eigen3)
if(NOT Eigen3_FOUND)
- message(FATAL_ERROR "Eigen3 not found, help CMake to find it by setting EIGEN3_INCLUDE_DIR, or set DOWNLOAD_Eigen3=ON to download it")
+ message(FATAL_ERROR "Eigen3 not found, help CMake to find it by setting EIGEN3_INCLUDE_DIR, or set DOWNLOAD_EIGEN3=ON to download it")
endif()
endif()
include_directories(${EIGEN3_INCLUDE_DIR})
@@ -499,12 +536,13 @@ include(CheckLibraryExists)
if (CMAKE_VERSION VERSION_LESS "3.4")
enable_language(C) # check_library_exists isn't supported without a c compiler before v3.4
endif()
-foreach(FUNC sin cos)
- check_library_exists(${MATH_LIBRARIES} ${FUNC} "" FOUND_${FUNC}_${MATH_LIBRARIES})
- if(NOT FOUND_${FUNC}_${MATH_LIBRARIES})
- message(FATAL_ERROR "Could not find needed math function - ${FUNC}")
- endif(NOT FOUND_${FUNC}_${MATH_LIBRARIES})
-endforeach(FUNC)
+# RB: disabled this check because it breaks with KOKKOS CUDA enabled
+#foreach(FUNC sin cos)
+# check_library_exists(${MATH_LIBRARIES} ${FUNC} "" FOUND_${FUNC}_${MATH_LIBRARIES})
+# if(NOT FOUND_${FUNC}_${MATH_LIBRARIES})
+# message(FATAL_ERROR "Could not find needed math function - ${FUNC}")
+# endif(NOT FOUND_${FUNC}_${MATH_LIBRARIES})
+#endforeach(FUNC)
list(APPEND LAMMPS_LINK_LIBS ${MATH_LIBRARIES})
######################################
@@ -729,33 +767,54 @@ if(PKG_OPT)
endif()
if(PKG_USER-INTEL)
- if(NOT DEVELOPER_MODE)
- if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
- message(FATAL_ERROR "USER-INTEL is only useful together with intel compiler")
- endif()
- if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16)
+ find_package(TBB REQUIRED)
+ find_package(MKL REQUIRED)
+
+ if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
+ message(FATAL_ERROR "USER-INTEL is only useful together with intel compiler")
+ endif()
+
+ if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16)
message(FATAL_ERROR "USER-INTEL is needed at least 2016 intel compiler, found ${CMAKE_CXX_COMPILER_VERSION}")
- endif()
endif()
- option(INJECT_KNL_FLAG "Inject flags for KNL build" OFF)
- if(INJECT_KNL_FLAG)
- set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xMIC-AVX512")
+
+ if(NOT BUILD_OMP)
+ message(FATAL_ERROR "USER-INTEL requires OpenMP")
endif()
- option(INJECT_INTEL_FLAG "Inject OMG fast flags for USER-INTEL" ON)
- if(INJECT_INTEL_FLAG AND CMAKE_CXX_COMPILER_ID STREQUAL "Intel")
+
+ if(NOT ${LAMMPS_MEMALIGN} STREQUAL "64")
+ message(FATAL_ERROR "USER-INTEL is only useful with LAMMPS_MEMALIGN=64")
+ endif()
+
+ set(INTEL_ARCH "cpu" CACHE STRING "Architectures used by USER-INTEL (cpu or knl)")
+ set(INTEL_ARCH_VALUES cpu knl)
+ set_property(CACHE INTEL_ARCH PROPERTY STRINGS ${INTEL_ARCH_VALUES})
+ validate_option(INTEL_ARCH INTEL_ARCH_VALUES)
+
+ if(INTEL_ARCH STREQUAL "knl")
+ set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -xHost -qopenmp -qoffload")
+ set(MIC_OPTIONS "-qoffload-option,mic,compiler,\"-fp-model fast=2 -mGLOB_default_function_attrs=\\\"gather_scatter_loop_unroll=4\\\"\"")
+ add_compile_options(-xMIC-AVX512 -qoffload -fno-alias -ansi-alias -restrict -qoverride-limits ${MIC_OPTIONS})
+ add_definitions(-DLMP_INTEL_OFFLOAD)
+ else()
if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xCOMMON-AVX512")
else()
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xHost")
endif()
include(CheckCXXCompilerFlag)
- foreach(_FLAG -qopenmp -qno-offload -fno-alias -ansi-alias -restrict -DLMP_INTEL_USELRT -DLMP_USE_MKL_RNG -O2 "-fp-model fast=2" -no-prec-div -qoverride-limits -qopt-zmm-usage=high)
+ foreach(_FLAG -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high -qno-offload -fno-alias -ansi-alias -restrict)
check_cxx_compiler_flag("${__FLAG}" COMPILER_SUPPORTS${_FLAG})
if(COMPILER_SUPPORTS${_FLAG})
- set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_FLAG}")
+ add_compile_options(${_FLAG})
endif()
endforeach()
endif()
+
+ add_definitions(-DLMP_INTEL_USELRT -DLMP_USE_MKL_RNG)
+
+ list(APPEND LAMMPS_LINK_LIBS ${TBB_MALLOC_LIBRARIES} ${MKL_LIBRARIES})
+
set(USER-INTEL_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/USER-INTEL)
set(USER-INTEL_SOURCES ${USER-INTEL_SOURCES_DIR}/intel_preprocess.h
${USER-INTEL_SOURCES_DIR}/intel_buffers.h
@@ -788,11 +847,25 @@ if(PKG_GPU)
${GPU_SOURCES_DIR}/fix_gpu.h
${GPU_SOURCES_DIR}/fix_gpu.cpp)
- set(GPU_API "OpenCL" CACHE STRING "API used by GPU package")
- set_property(CACHE GPU_API PROPERTY STRINGS OpenCL CUDA)
+ set(GPU_API "opencl" CACHE STRING "API used by GPU package")
+ set(GPU_API_VALUES opencl cuda)
+ set_property(CACHE GPU_API PROPERTY STRINGS ${GPU_API_VALUES})
+ validate_option(GPU_API GPU_API_VALUES)
+ string(TOUPPER ${GPU_API} GPU_API)
- set(GPU_PREC "SINGLE_DOUBLE" CACHE STRING "LAMMPS GPU precision size")
- set_property(CACHE GPU_PREC PROPERTY STRINGS SINGLE_DOUBLE SINGLE_SINGLE DOUBLE_DOUBLE)
+ set(GPU_PREC "mixed" CACHE STRING "LAMMPS GPU precision")
+ set(GPU_PREC_VALUES double mixed single)
+ set_property(CACHE GPU_PREC PROPERTY STRINGS ${GPU_PREC_VALUES})
+ validate_option(GPU_PREC GPU_PREC_VALUES)
+ string(TOUPPER ${GPU_PREC} GPU_PREC)
+
+ if(GPU_PREC STREQUAL "DOUBLE")
+ set(GPU_PREC_SETTING "DOUBLE_DOUBLE")
+ elseif(GPU_PREC STREQUAL "MIXED")
+ set(GPU_PREC_SETTING "SINGLE_DOUBLE")
+ elseif(GPU_PREC STREQUAL "SINGLE")
+ set(GPU_PREC_SETTING "SINGLE_SINGLE")
+ endif()
file(GLOB GPU_LIB_SOURCES ${LAMMPS_LIB_SOURCE_DIR}/gpu/*.cpp)
file(MAKE_DIRECTORY ${LAMMPS_LIB_BINARY_DIR}/gpu)
@@ -805,7 +878,7 @@ if(PKG_GPU)
endif()
option(CUDPP_OPT "Enable CUDPP_OPT" ON)
- set(GPU_ARCH "sm_30" CACHE STRING "LAMMPS GPU CUDA SM architecture (e.g. sm_60)")
+ set(GPU_ARCH "sm_30" CACHE STRING "LAMMPS GPU CUDA SM architecture (e.g. sm_60)")
file(GLOB GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/*.cu ${CMAKE_CURRENT_SOURCE_DIR}/gpu/*.cu)
list(REMOVE_ITEM GPU_LIB_CU ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_pppm.cu)
@@ -819,10 +892,10 @@ if(PKG_GPU)
endif()
cuda_compile_cubin(GPU_GEN_OBJS ${GPU_LIB_CU} OPTIONS
- -DUNIX -O3 -Xptxas -v --use_fast_math -DNV_KERNEL -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC})
+ -DUNIX -O3 -Xptxas -v --use_fast_math -DNV_KERNEL -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC_SETTING})
cuda_compile(GPU_OBJS ${GPU_LIB_CUDPP_CU} OPTIONS $<$:-Xcompiler=-fPIC>
- -DUNIX -O3 -Xptxas -v --use_fast_math -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC})
+ -DUNIX -O3 -Xptxas -v --use_fast_math -DUCL_CUDADR -arch=${GPU_ARCH} -D_${GPU_PREC_SETTING})
foreach(CU_OBJ ${GPU_GEN_OBJS})
get_filename_component(CU_NAME ${CU_OBJ} NAME_WE)
@@ -839,7 +912,7 @@ if(PKG_GPU)
add_library(gpu STATIC ${GPU_LIB_SOURCES} ${GPU_LIB_CUDPP_SOURCES} ${GPU_OBJS})
target_link_libraries(gpu ${CUDA_LIBRARIES} ${CUDA_CUDA_LIBRARY})
target_include_directories(gpu PRIVATE ${LAMMPS_LIB_BINARY_DIR}/gpu ${CUDA_INCLUDE_DIRS})
- target_compile_definitions(gpu PRIVATE -D_${GPU_PREC} -DMPI_GERYON -DUCL_NO_EXIT)
+ target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -DMPI_GERYON -DUCL_NO_EXIT)
if(CUDPP_OPT)
target_include_directories(gpu PRIVATE ${LAMMPS_LIB_SOURCE_DIR}/gpu/cudpp_mini)
target_compile_definitions(gpu PRIVATE -DUSE_CUDPP)
@@ -853,10 +926,13 @@ if(PKG_GPU)
target_include_directories(nvc_get_devices PRIVATE ${CUDA_INCLUDE_DIRS})
- elseif(GPU_API STREQUAL "OpenCL")
+ elseif(GPU_API STREQUAL "OPENCL")
find_package(OpenCL REQUIRED)
- set(OCL_TUNE "GENERIC" CACHE STRING "OpenCL Device Tuning")
- set_property(CACHE OCL_TUNE PROPERTY STRINGS INTEL FERMI KEPLER CYPRESS GENERIC)
+ set(OCL_TUNE "generic" CACHE STRING "OpenCL Device Tuning")
+ set(OCL_TUNE_VALUES intel fermi kepler cypress generic)
+ set_property(CACHE OCL_TUNE PROPERTY STRINGS ${OCL_TUNE_VALUES})
+ validate_option(OCL_TUNE OCL_TUNE_VALUES)
+ string(TOUPPER ${OCL_TUNE} OCL_TUNE)
include(OpenCLUtils)
set(OCL_COMMON_HEADERS ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_preprocessor.h ${LAMMPS_LIB_SOURCE_DIR}/gpu/lal_aux_fun1.h)
@@ -878,7 +954,7 @@ if(PKG_GPU)
add_library(gpu STATIC ${GPU_LIB_SOURCES})
target_link_libraries(gpu ${OpenCL_LIBRARIES})
target_include_directories(gpu PRIVATE ${CMAKE_CURRENT_BINARY_DIR}/gpu ${OpenCL_INCLUDE_DIRS})
- target_compile_definitions(gpu PRIVATE -D_${GPU_PREC} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT)
+ target_compile_definitions(gpu PRIVATE -D_${GPU_PREC_SETTING} -D${OCL_TUNE}_OCL -DMPI_GERYON -DUCL_NO_EXIT)
target_compile_definitions(gpu PRIVATE -DUSE_OPENCL)
list(APPEND LAMMPS_LINK_LIBS gpu)
@@ -1131,7 +1207,7 @@ if(PKG_GPU)
message(STATUS "GPU Api: ${GPU_API}")
if(GPU_API STREQUAL "CUDA")
message(STATUS "GPU Arch: ${GPU_ARCH}")
- elseif(GPU_API STREQUAL "OpenCL")
+ elseif(GPU_API STREQUAL "OPENCL")
message(STATUS "OCL Tune: ${OCL_TUNE}")
endif()
message(STATUS "GPU Precision: ${GPU_PREC}")
diff --git a/cmake/Modules/FindQUIP.cmake b/cmake/Modules/FindQUIP.cmake
index 4ee1baf4f8..b6d87d11fa 100644
--- a/cmake/Modules/FindQUIP.cmake
+++ b/cmake/Modules/FindQUIP.cmake
@@ -1,8 +1,8 @@
# - Find quip
# Find the native QUIP libraries.
#
-# QUIP_LIBRARIES - List of libraries when using fftw3.
-# QUIP_FOUND - True if fftw3 found.
+# QUIP_LIBRARIES - List of libraries of the QUIP package
+# QUIP_FOUND - True if QUIP library was found.
#
find_library(QUIP_LIBRARY NAMES quip)
diff --git a/cmake/Modules/FindTBB.cmake b/cmake/Modules/FindTBB.cmake
new file mode 100644
index 0000000000..8cc050817e
--- /dev/null
+++ b/cmake/Modules/FindTBB.cmake
@@ -0,0 +1,46 @@
+# - Find parts of TBB
+# Find the native TBB headers and libraries.
+#
+# TBB_INCLUDE_DIRS - where to find tbb.h, etc.
+# TBB_LIBRARIES - List of libraries when using tbb.
+# TBB_FOUND - True if tbb found.
+#
+
+########################################################
+# TBB
+
+# TODO use more generic FindTBB
+
+find_path(TBB_INCLUDE_DIR NAMES tbb/tbb.h PATHS $ENV{TBBROOT}/include)
+find_library(TBB_LIBRARY NAMES tbb PATHS $ENV{TBBROOT}/lib/intel64/gcc4.7
+ $ENV{TBBROOT}/lib/intel64/gcc4.4
+ $ENV{TBBROOT}/lib/intel64/gcc4.1)
+set(TBB_LIBRARIES ${TBB_LIBRARY})
+set(TBB_INCLUDE_DIRS ${TBB_INCLUDE_DIR})
+
+include(FindPackageHandleStandardArgs)
+# handle the QUIETLY and REQUIRED arguments and set TBB_FOUND to TRUE
+# if all listed variables are TRUE
+
+find_package_handle_standard_args(TBB DEFAULT_MSG TBB_LIBRARY TBB_INCLUDE_DIR)
+
+mark_as_advanced(TBB_INCLUDE_DIR TBB_LIBRARY )
+
+########################################################
+# TBB Malloc
+
+find_path(TBB_MALLOC_INCLUDE_DIR NAMES tbb/tbb.h PATHS $ENV{TBBROOT}/include)
+find_library(TBB_MALLOC_LIBRARY NAMES tbbmalloc PATHS $ENV{TBBROOT}/lib/intel64/gcc4.7
+ $ENV{TBBROOT}/lib/intel64/gcc4.4
+ $ENV{TBBROOT}/lib/intel64/gcc4.1)
+
+set(TBB_MALLOC_LIBRARIES ${TBB_MALLOC_LIBRARY})
+set(TBB_MALLOC_INCLUDE_DIRS ${TBB_MALLOC_INCLUDE_DIR})
+
+include(FindPackageHandleStandardArgs)
+# handle the QUIETLY and REQUIRED arguments and set TBB_MALLOC_FOUND to TRUE
+# if all listed variables are TRUE
+
+find_package_handle_standard_args(TBB_MALLOC DEFAULT_MSG TBB_MALLOC_LIBRARY TBB_MALLOC_INCLUDE_DIR)
+
+mark_as_advanced(TBB_MALLOC_INCLUDE_DIR TBB_MALLOC_LIBRARY )
diff --git a/cmake/README.md b/cmake/README.md
index b6644ffda9..85375cd2aa 100644
--- a/cmake/README.md
+++ b/cmake/README.md
@@ -62,7 +62,7 @@ should get you started.
git clone https://github.com/lammps/lammps.git
mkdir lammps/build
cd lammps/build
-cmake ../cmake [-DOPTION_A=VALUE_A -DOPTION_B=VALUE_B ...]
+cmake [-D OPTION_A=VALUE_A -D OPTION_B=VALUE_B ...] ../cmake
make
```
@@ -174,7 +174,7 @@ presets can be found in the `cmake/presets` folder.
# build LAMMPS with all "standard" packages which don't use libraries and enable GPU package
mkdir build
cd build
-cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on
+cmake -C ../cmake/presets/std_nolib.cmake -D PKG_GPU=on ../cmake
```
# Reference
@@ -265,6 +265,16 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on
+
+ BUILD_LIB |
+ control whether to build LAMMPS as a library |
+
+
+ off (default)
+ on
+
+ |
+
BUILD_SHARED_LIBS |
control whether to build LAMMPS as a shared-library |
@@ -315,8 +325,8 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on
`mpicxx` in your path and use this MPI implementation.
- off (default)
- on
+ on (default, if found)
+ off
|
@@ -325,8 +335,8 @@ cmake -C ../cmake/presets/std_nolib.cmake ../cmake -DPKG_GPU=on
control whether to build LAMMPS with OpenMP support. |
- off (default)
- on
+ on (default, if found)
+ off
|
@@ -1271,7 +1281,7 @@ providing the identical features and USER interface.
- KISSFFT
+ KISS
FFTW3
FFTW2
MKL
@@ -1279,13 +1289,13 @@ providing the identical features and USER interface.
|
- PACK_ARRAY |
+ FFT_PACK |
Optimization for FFT |
- PACK_ARRAY
- PACK_POINTER
- PACK_MEMCPY
+ array (default)
+ pointer
+ memcpy
|
@@ -1377,6 +1387,29 @@ TODO
### PYTHON Package
+### USER-INTEL Package
+
+
+
+
+ | Option |
+ Description |
+ Values |
+
+
+
+
+ INTEL_ARCH |
+ Target architecture for USER-INTEL package |
+
+
+ cpu (default)
+ knl
+
+ |
+
+
+
### GPU Package
The GPU package builds a support library which can either use OpenCL or CUDA as
@@ -1396,8 +1429,8 @@ target API.
API used by GPU package |
- OpenCL (default)
- CUDA
+ opencl (default)
+ cuda
|
@@ -1406,9 +1439,9 @@ target API.
Precision size used by GPU package kernels |
- SINGLE_DOUBLE
- SINGLE_SINGLE
- DOUBLE_DOUBLE
+ mixed (default)
+ single
+ double
|
@@ -1417,12 +1450,12 @@ target API.
Tuning target for OpenCL driver code |
- GENERIC (default)
- INTEL (Intel CPU)
- PHI (Intel Xeon Phi)
- FERMI (NVIDIA)
- KEPLER (NVIDIA)
- CYPRESS (AMD)
+ generic (default)
+ intel (Intel CPU)
+ phi (Intel Xeon Phi)
+ fermi (NVIDIA)
+ kepler (NVIDIA)
+ cypress (AMD)
|
@@ -1517,6 +1550,16 @@ Requires a Eigen3 installation
+
+ WITH_JPEG |
+ Enables/Disable JPEG support in LAMMPS |
+
+
+ yes (default, if found)
+ no
+
+ |
+
JPEG_INCLUDE_DIR |
|
@@ -1544,6 +1587,16 @@ Requires a Eigen3 installation
+
+ WITH_PNG |
+ Enables/Disable PNG support in LAMMPS |
+
+
+ yes (default, if found)
+ no
+
+ |
+
PNG_INCLUDE_DIR |
|
@@ -1572,6 +1625,16 @@ requires `gzip` to be in your `PATH`
+
+ WITH_GZIP |
+ Enables/Disable GZIP support in LAMMPS |
+
+
+ yes (default, if found)
+ no
+
+ |
+
GZIP_EXECUTABLE |
|
@@ -1594,6 +1657,16 @@ requires `ffmpeg` to be in your `PATH`
+
+ WITH_FFMPEG |
+ Enables/Disable FFMPEG support in LAMMPS |
+
+
+ yes (default, if found)
+ no
+
+ |
+
FFMPEG_EXECUTABLE |
|
@@ -1606,8 +1679,13 @@ requires `ffmpeg` to be in your `PATH`
## Compilers
-By default, `cmake` will use your environment C/C++/Fortran compilers for a build. It uses the `CC`, `CXX` and `FC` environment variables to detect which compilers should be used. However, these values
-will be cached after the first run of `cmake`. Subsequent runs of `cmake` will ignore changes in these environment variables. To ensure the correct values are used you avoid the cache by setting the `CMAKE_C_COMPILER`, `CMAKE_CXX_COMPILER`, `CMAKE_Fortran_COMPILER` options directly.
+By default, `cmake` will use your environment C/C++/Fortran compilers for a
+build. It uses the `CC`, `CXX` and `FC` environment variables to detect which
+compilers should be used. However, these values will be cached after the first
+run of `cmake`. Subsequent runs of `cmake` will ignore changes in these
+environment variables. To ensure the correct values are used you avoid the
+cache by setting the `CMAKE_C_COMPILER`, `CMAKE_CXX_COMPILER`,
+`CMAKE_Fortran_COMPILER` options directly.
@@ -1643,20 +1721,20 @@ will be cached after the first run of `cmake`. Subsequent runs of `cmake` will i
### Building with GNU Compilers
```bash
-cmake ../cmake -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_Fortran_COMPILER=gfortran
+cmake -D CMAKE_C_COMPILER=gcc -D CMAKE_CXX_COMPILER=g++ -D CMAKE_Fortran_COMPILER=gfortran ../cmake
```
### Building with Intel Compilers
```bash
-cmake ../cmake -DCMAKE_C_COMPILER=icc -DCMAKE_CXX_COMPILER=icpc -DCMAKE_Fortran_COMPILER=ifort
+cmake -D CMAKE_C_COMPILER=icc -D CMAKE_CXX_COMPILER=icpc -D CMAKE_Fortran_COMPILER=ifort ../cmake
```
### Building with LLVM/Clang Compilers
```bash
-cmake ../cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_Fortran_COMPILER=flang
+cmake -D CMAKE_C_COMPILER=clang -D CMAKE_CXX_COMPILER=clang++ -D CMAKE_Fortran_COMPILER=flang ../cmake
```
diff --git a/doc/src/Build.txt b/doc/src/Build.txt
new file mode 100644
index 0000000000..218664897f
--- /dev/null
+++ b/doc/src/Build.txt
@@ -0,0 +1,58 @@
+"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 traditional makefiles (which may require manual editing)
+for use with GNU make or gmake, or a build environment generated by CMake
+(Unix Makefiles, Xcode, Visual Studio, KDevelop or more). As an
+alternative you can download a package with pre-built executables
+as described on the "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..425266a35f
--- /dev/null
+++ b/doc/src/Build_basics.txt
@@ -0,0 +1,315 @@
+"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
+
+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 created by CMake (after running make) is lmp_name. If
+the LAMMPS_MACHINE variable is not specified, the executable is just
+lmp. Using BUILD_MPI=no will produce a serial executable.
+
+[Traditional make]:
+
+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 to produce 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 MPICH2 from Argonne
+National Laboratory 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. The USER-INTEL package also provides OpenMP support (it is
+compatible with USER-OMP) and adds vectorization support when compiled
+with the Intel compilers on top of that. Also, the KOKKOS package can
+be compiled for using OpenMP threading.
+
+However, there are a few commands in LAMMPS that have native OpenMP
+support. These are commands in the MPIIO, SNAP, USER-DIFFRACTION, and
+USER-DPD packages. In addition some packages support OpenMP threading
+indirectly through the libraries they interface to: e.g. LATTE and
+USER-COLVARS. See the "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.
+
+For CMake, if you use BUILD_OMP=yes, you can use these packages and
+turn on their native OpenMP support and turn on their native OpenMP
+support at run time, by setting the OMP_NUM_THREADS environment
+variable before you launch LAMMPS.
+
+For building via conventional make, the CCFLAGS and LINKFLAGS
+variables in Makefile.machine need to include the compiler flag that
+enables OpenMP. For GNU compilers it is -fopenmp. For (recent) Intel
+compilers it is -qopenmp. If you are using a different compiler,
+please refer to its documentation.
+
+: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 add
+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 which compilers it is using, and what flags will be used in the
+compilation. Note that if the top-level compiler is mpicxx, it is
+simply a wrapper on a real compiler. The underlying compiler info is
+what will be listed in the CMake output. You should check to insure
+you are using the compiler and optimization flags are the ones you
+want.
+
+[Makefile.machine settings]:
+
+Parallel build (see src/MAKE/Makefile.mpi):
+
+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
+
+: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 LAMMPS 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 via its library interface.
+
+[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
+shared 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 soft links, named
+liblammps.a and liblammps.so, which point to the liblammps_machine
+files.
+
+[CMake and make info]:
+
+Note that for a shared library to be usable by a calling program, all
+the auxiliary libraries it depends on must also exist as shared
+libraries. This will be the case for libraries included with LAMMPS,
+such as the dummy MPI library in src/STUBS or any package libraries in
+the lib/packages directroy, 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 Lab, 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 directory.
+The reason to do this is if you want to "install" LAMMPS on a system
+after the CMake build via "make install", and include the doc pages in
+the install.
+
+[Traditional make]:
+
+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
+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 directory
+you want to copy files to is protected.
+
+[CMake variable]:
+
+cmake -D CMAKE_INSTALL_PREFIX=path \[options ...\] ../cmake
+make # perform make after CMake command
+make install # perform the installation into prefix :pre
+
+[Traditional make]:
+
+There is no "install" option in the src/Makefile for LAMMPS. If you
+wish to do this you will need to first build LAMMPS, then manually
+copy the desired LAMMPS files to the appropriate system directories.
diff --git a/doc/src/Build_cmake.txt b/doc/src/Build_cmake.txt
new file mode 100644
index 0000000000..c42bb21c7e
--- /dev/null
+++ b/doc/src/Build_cmake.txt
@@ -0,0 +1,197 @@
+"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.
+Details on CMake variables that enable specific 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/lammps/lammps/blob/master/cmake/README.md
+
+:line
+
+Building LAMMPS with CMake is a two-step process. First you use CMake
+to create a build environment in a new directory. On Linux systems,
+this will be based on makefiles for use with make. Then you use the
+make command to build LAMMPS, which uses the created
+Makefile(s). Example:
+
+cd lammps # change to the LAMMPS distribution directory
+mkdir build; cd build # create a new directory (folder) for build
+cmake ../cmake \[options ...\] # configuration with (command-line) cmake
+make # compilation :pre
+
+The cmake command will detect available features, enable selected
+packages and options, and will generate the build environment. The make
+command will then compile and link LAMMPS, producing (by default) an
+executable called "lmp" and a library called "liblammps.a" in the
+"build" folder.
+
+If your machine has multiple CPU cores (most do these days), using a
+command like "make -jN" (with N being the number of available local
+CPU cores) can be much faster. If you plan to do development on
+LAMMPS or need to recompile LAMMPS repeatedly, installation of the
+ccache (= Compiler Cache) software may speed up compilation even more.
+
+After compilation, you can optionally copy the LAMMPS executable and
+library into your system folders (by default under /usr/local) with:
+
+make install # optional, copy LAMMPS executable & library elsewhere :pre
+
+:line
+
+There are 3 variants of CMake: a command-line verison (cmake), a text mode
+UI version (ccmake), and a graphical GUI version (cmake-GUI). You can use
+any of them interchangeably to configure and create the LAMMPS build
+environment. On Linux all the versions produce a Makefile as their
+output. See more details on each below.
+
+You can specify a variety of options with any of the 3 versions, which
+affect how the build is performed and what is included in the LAMMPS
+executable. Links to pages explaining all the options are listed on
+the "Build"_Build.html doc page.
+
+You must perform the CMake build system generation and compilation in
+a new directory you create. It can be anywhere on your local machine.
+In these Build pages we assume that you are building in a directory
+called "lammps/build". You can perform separate builds independently
+with different options, so long as you perform each of them in a
+separate directory you create. All the auxiliary files created by one
+build process (executable, object files, log files, etc) are stored in
+this directory or sub-directories within it that CMake creates.
+
+NOTE: To perform a CMake build, no packages can be installed or a
+build been previously attempted in the LAMMPS src directory by using
+"make" commands to "perform a conventional LAMMPS
+build"_Build_make.html. CMake detects if this is the case and
+generates an error, telling you to type "make no-all purge" in the src
+directory to un-install all packages. The purge removes all the *.h
+files auto-generated by make.
+
+You must have CMake version 2.8 or later on your system to build
+LAMMPS. If you include the GPU or KOKKOS packages, CMake 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 run cmake (or
+ccmake or cmake-gui) again from the same build directory and alter
+various options; see details below. Or you can remove the entire build
+folder, recreate the directory and start over.
+
+:line
+
+[Command-line version of CMake]:
+
+cmake \[options ...\] /path/to/lammps/cmake # build from any dir
+cmake \[options ...\] ../cmake # build from lammps/build :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:
+
+-D CMAKE_INSTALL_PREFIX=path # where to install LAMMPS executable/lib if desired
+-D 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 :pre
+
+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.
+
+On Unix/Linux machines, CMake generates a Makefile by default to
+perform the LAMMPS build. Alternate forms of build info can be
+generated via the -G switch, e.g. Visual Studio on a Windows machine,
+Xcode on MacOS, or KDevelop on Linux. Type "cmake --help" to see the
+"Generator" styles of output your system supports.
+
+NOTE: When CMake runs, it prints configuration info to the screen.
+You should review this to verify all the features you requested were
+enabled, including packages. You can also see what compilers and
+compile options will be used for the build. Any errors in CMake
+variable syntax will also be flagged, e.g. mis-typed variable names or
+variable values.
+
+CMake creates a CMakeCache.txt file when it runs. This stores all the
+settings, so that when running CMake again you can use the current
+folder '.' instead of the path to the LAMMPS cmake folder as the
+required argument to the CMake command. Either way the existing
+settings will be inherited unless the CMakeCache.txt file is removed.
+
+If you later want to change a setting you can rerun cmake in the build
+directory with different setting. Please note that some automatically
+detected variables will not change their value when you rerun cmake.
+In these cases it is usually better to first remove all the
+files/directories in the build directory, or start with a fresh build
+directory.
+
+:line
+
+[Curses version (terminal-style menu) of CMake]:
+
+ccmake ../cmake :pre
+
+You initiate the configuration and build environment generation steps
+separately. For the first you have to type [c], for the second you
+have to type [g]. You may need to type [c] multiple times, and may be
+required to edit some of the entries of CMake configuration variables
+in between. Please see the "ccmake
+manual"_https://cmake.org/cmake/help/latest/manual/ccmake.1.html for
+more information.
+
+:line
+
+[GUI version of CMake]:
+
+cmake-gui ../cmake :pre
+
+You initiate the configuration and build environment generation steps
+separately. For the first you have to click on the [Configure] button,
+for the second you have to click on the [Generate] button. You may
+need to click on [Configure] multiple times, and may be required to
+edit some of the entries of CMake configuration variables in between.
+Please see the "cmake-gui
+manual"_https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html
+for more information.
+
+: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 environment modules to manage
+software packages, do this:
+
+module list # is a cmake module already loaded?
+module avail # is a cmake module available?
+module load cmake3 # load cmake module with appropriate name :pre
+
+Most Linux distributions offer precompiled cmake packages through
+their package management system. If you do not have CMake or a new
+enough version, you can download the latest version at
+"https://cmake.org/download/"_https://cmake.org/download/.
+Instructions on how to install it on various platforms can be found
+"on this page"_https://cmake.org/install/.
diff --git a/doc/src/Build_extras.txt b/doc/src/Build_extras.txt
new file mode 100644
index 0000000000..a3a05ed50e
--- /dev/null
+++ b/doc/src/Build_extras.txt
@@ -0,0 +1,923 @@
+"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,
+in addition to:
+
+-D PKG_NAME=yes # CMake
+make yes-name # make :pre
+
+as described on the "Build_package"_Build_package.html doc page.
+
+For a CMake build there may be additional optional or required
+variables to set. For a build with make, a provided library under the
+lammps/lib directory may need to be built first. Or an external
+library may need to exist on your system or be downloaded and built.
+You may need to tell LAMMPS where it is found on your system.
+
+This is the list of packages that may require additional steps.
+
+"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
+
+COMPRESS package :h4,link(compress)
+
+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 libz.a (.so) file :pre
+
+[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 :h4,link(gpu)
+
+To build with this package, you must choose options for precision and
+which GPU hardware to build for.
+
+[CMake build]:
+
+-D GPU_API=value # value = opencl (default) or cuda
+-D GPU_PREC=value # precision setting
+ # value = double or mixed (default) or single
+-D OCL_TUNE=value # hardware choice for GPU_API=opencl
+ # generic (default) or intel (Intel CPU) or fermi, kepler, cypress (NVIDIA)
+-D GPU_ARCH=value # hardware choice for GPU_API=cuda
+ # value = sm_XX, see below
+ # default is Cuda-compiler dependent, but typically sm_20
+-D CUDPP_OPT=value # optimization setting for GPU_API=cudea
+ # enables CUDA Performance Primitives Optimizations
+ # yes (default) or no :pre
+
+GPU_ARCH settings for different GPU hardware is as follows:
+
+sm_20 for Fermi (C2050/C2070, deprecated as of CUDA 8.0) or GeForce GTX 580 or similar
+sm_30 for Kepler (K10)
+sm_35 for Kepler (K40) or GeForce GTX Titan or similar
+sm_37 for Kepler (dual K80)
+sm_50 for Maxwell
+sm_60 for Pascal (P100)
+sm_70 for Volta :ul
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the GPU library in lib/gpu.
+You can do this manually if you prefer; follow the instructions in
+lib/gpu/README. Note that the GPU library uses MPI calls, so you must
+use the same MPI library (or the STUBS library) settings as the main
+LAMMPS code. This also applies to the -DLAMMPS_BIGBIG,
+-DLAMMPS_SMALLBIG, or -DLAMMPS_SMALLSMALL settings in whichever
+Makefile you use.
+
+You can also build the library in one step from the lammps/src dir,
+using a command like these, which simply invoke the lib/gpu/Install.py
+script with the specified args:
+
+make lib-gpu # print help message
+make lib-gpu args="-b" # build GPU library with default Makefile.linux
+make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
+make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi :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 corresponding -h, -a, -p, -e
+switches (as in the examples above), and also save a copy of the new
+Makefile if desired:
+
+CUDA_HOME = where NVIDIA CUDA software is installed on your system
+CUDA_ARCH = sm_XX, what GPU hardware you have, same as CMake GPU_ARCH above
+CUDA_PRECISION = precision (double, mixed, single)
+EXTRAMAKE = which Makefile.lammps.* file to copy to Makefile.lammps :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 in lammps/src, then re-install it and
+re-build LAMMPS. This is because the compilation of files in the GPU
+package uses the library settings from the lib/gpu/Makefile.machine
+used to build the GPU library.
+
+:line
+
+KIM package :h4,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]:
+
+-D DOWNLOAD_KIM=value # download OpenKIM API v1 for build, value = no (default) or yes
+-D KIM_LIBRARY=path # path to KIM shared library (only needed if a custom location)
+-D KIM_INCLUDE_DIR=path # path to KIM include directory (only needed if a custom location) :pre
+
+[Traditional make]:
+
+You can download and build the KIM library manually if you prefer;
+follow the instructions in lib/kim/README. You can also do it in one
+step from the lammps/src dir, using a command like these, which simply
+invoke the lib/kim/Install.py script with the specified args.
+
+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 :h4,link(kokkos)
+
+To build with this package, you must choose which hardware you want to
+build for, either CPUs (multi-threading via OpenMP) or KNLs (OpenMP)
+or GPUs (NVIDIA Cuda).
+
+For a CMake or make build, these are the possible choices for the
+KOKKOS_ARCH settings described below. Note that for CMake, these are
+really Kokkos variables, not LAMMPS variables. Hence you must use
+case-sensitive values, e.g. BDW, not bdw.
+
+ARMv80 = ARMv8.0 Compatible CPU
+ARMv81 = ARMv8.1 Compatible CPU
+ARMv8-ThunderX = ARMv8 Cavium ThunderX CPU
+BGQ = IBM Blue Gene/Q CPUs
+Power8 = IBM POWER8 CPUs
+Power9 = IBM POWER9 CPUs
+SNB = Intel Sandy/Ivy Bridge CPUs
+HSW = Intel Haswell CPUs
+BDW = Intel Broadwell Xeon E-class CPUs
+SKX = Intel Sky Lake Xeon E-class HPC CPUs (AVX512)
+KNC = Intel Knights Corner Xeon Phi
+KNL = Intel Knights Landing Xeon Phi
+Kepler30 = NVIDIA Kepler generation CC 3.0
+Kepler32 = NVIDIA Kepler generation CC 3.2
+Kepler35 = NVIDIA Kepler generation CC 3.5
+Kepler37 = NVIDIA Kepler generation CC 3.7
+Maxwell50 = NVIDIA Maxwell generation CC 5.0
+Maxwell52 = NVIDIA Maxwell generation CC 5.2
+Maxwell53 = NVIDIA Maxwell generation CC 5.3
+Pascal60 = NVIDIA Pascal generation CC 6.0
+Pascal61 = NVIDIA Pascal generation CC 6.1 :ul
+
+[CMake build]:
+
+For multicore CPUs using OpenMP, set these 2 variables.
+
+-D KOKKOS_ARCH=archCPU # archCPU = CPU from list above :pre
+-D KOKKOS_ENABLE_OPENMP=yes :pre
+
+For Intel KNLs using OpenMP, set these 2 variables:
+
+-D KOKKOS_ARCH=KNL
+-D KOKKOS_ENABLE_OPENMP=yes :pre
+
+For NVIDIA GPUs using CUDA, set these 4 variables:
+
+-D KOKKOS_ARCH="archCPU;archGPU" # archCPU = CPU from list above that is hosting the GPU
+ # archGPU = GPU from list above
+-D KOKKOS_ENABLE_CUDA=yes
+-D KOKKOS_ENABLE_OPENMP=yes
+-D CMAKE_CXX_COMPILER=wrapper # wrapper = full path to Cuda nvcc wrapper :pre
+
+The wrapper value is the Cuda nvcc compiler wrapper provided in the
+Kokkos library: lib/kokkos/bin/nvcc_wrapper. The setting should
+include the full path name to the wrapper, e.g.
+
+-D CMAKE_CXX_COMPILER=/home/username/lammps/lib/kokkos/bin/nvcc_wrapper :pre
+
+[Traditional make]:
+
+Choose which hardware to support in Makefile.machine via
+KOKKOS_DEVICES and KOKKOS_ARCH settings. See the
+src/MAKE/OPTIONS/Makefile.kokkos* files for examples.
+
+For multicore CPUs using OpenMP:
+
+KOKKOS_DEVICES = OpenMP
+KOKKOS_ARCH = archCPU # archCPU = CPU from list above :pre
+
+For Intel KNLs using OpenMP:
+
+KOKKOS_DEVICES = OpenMP
+KOKKOS_ARCH = KNL :pre
+
+For NVIDIA GPUs using CUDA:
+
+KOKKOS_DEVICES = Cuda
+KOKKOS_ARCH = archCPU,archGPU # archCPU = CPU from list above that is hosting the GPU
+ # archGPU = GPU from list above :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 and 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
+
+:line
+
+LATTE package :h4,link(latte)
+
+To build with this package, you must download and build the LATTE
+library.
+
+[CMake build]:
+
+-D DOWNLOAD_LATTE=value # download LATTE for build, value = no (default) or yes
+-D LATTE_LIBRARY=path # path to LATTE shared library (only needed if a custom location) :pre
+
+[Traditional make]:
+
+You can download and build the LATTE library manually if you prefer;
+follow the instructions in lib/latte/README. You can also do it in
+one step from the lammps/src dir, using a command like these, which
+simply invokes the lib/latte/Install.py script with the specified
+args:
+
+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 itself is built it will use these links. You should
+also check that the Makefile.lammps file you create is appropriate for
+the compiler you use on your system to build LATTE.
+
+:line
+
+MEAM package :h4,link(meam)
+
+NOTE: the use of the MEAM package is discouraged, as it has been
+superseded by the USER-MEAMC package, which is a direct translation of
+the Fortran code in the MEAM library to C++. The code in USER-MEAMC
+should be functionally equivalent to the MEAM package, fully supports
+use of "pair_style hybrid"_pair_hybrid.html (the MEAM packaged doesn
+not), and has optimizations that make it significantly faster than the
+MEAM package.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_MEAM=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the MEAM library in lib/meam.
+You can build the MEAM library 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 :h4,link(mscg)
+
+To build with this package, you must download and build the MS-CG
+library. Building the MS-CG library and using it from LAMMPS requires
+a C++11 compatible compiler and that the GSL (GNU Scientific Library)
+headers and libraries are installed on your machine. See the
+lib/mscg/README and MSCG/Install files for more details.
+
+[CMake build]:
+
+-D DOWNLOAD_MSCG=value # download MSCG for build, value = no (default) or yes
+-D MSCG_LIBRARY=path # path to MSCG shared library (only needed if a custom location)
+-D MSCG_INCLUDE_DIR=path # path to MSCG include directory (only needed if a custom location) :pre
+
+[Traditional make]:
+
+You can download and build the MS-CG library manually if you prefer;
+follow the instructions in lib/mscg/README. You can also do it in one
+step from the lammps/src dir, using a command like these, which simply
+invoke the lib/mscg/Install.py script with the specified args:
+
+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 :h4,link(opt)
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_OPT=yes".
+
+[Traditional make]:
+
+The compile flag "-restrict" must be used to build LAMMPS with the OPT
+package when using Intel compilers. It should be added to the CCFLAGS
+line of your Makefile.machine. See src/MAKE/OPTIONS/Makefile.opt for
+an example.
+
+:line
+
+POEMS package :h4,link(poems)
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_OPT=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the POEMS library in lib/poems.
+You can do this manually if you prefer; follow the instructions in
+lib/poems/README. You can also do it in one step from the lammps/src
+dir, using a command like these, which simply invoke the
+lib/poems/Install.py script with the specified args:
+
+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 :h4,link(python)
+
+Building with the PYTHON package requires you have a Python shared
+library available on your system, which needs to be a Python 2
+version, 2.6 or later. Python 3 is not yet supported. See
+lib/python/README for more details.
+
+[CMake build]:
+
+-D PYTHON_EXECUTABLE=path # path to Python executable to use :pre
+
+Without this setting, CMake will ues the default Python on your
+system. To use a different Python version, you can either create a
+virtualenv, activate it and then run cmake. Or you can set the
+PYTHON_EXECUTABLE variable to specify which Python interpreter should
+be used. Note note that you will also need to have the development
+headers installed for this version, e.g. python2-devel.
+
+[Traditional make]:
+
+The build uses the lib/python/Makefile.lammps file in the compile/link
+process to find Python. You should only need to create a new
+Makefile.lammps.* file (and copy it to Makefile.lammps) if the LAMMPS
+build fails.
+
+:line
+
+REAX package :h4,link(reax)
+
+NOTE: the use of the REAX package and its "pair_style
+reax"_pair_reax.html command is discouraged, as it is no longer
+maintained. Please use the USER-REAXC package and its "pair_style
+reax/c"_pair_reaxc.html command instead, and possibly its KOKKOS
+enabled variant (pair_style reax/c/kk), which has a more robust memory
+management. See the "pair_style reax/c"_pair_reaxc.html doc page for
+details.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_REAX=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must 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 :h4,link(voronoi)
+
+To build with this package, you must download and build the "Voro++
+library"_voro_home.
+
+:link(voro_home,http://math.lbl.gov/voro++)
+
+[CMake build]:
+
+-D DOWNLOAD_VORO=value # download Voro++ for build, value = no (default) or yes
+-D VORO_LIBRARY=path # (only needed if at custom location) path to VORO shared library
+-D VORO_INCLUDE_DIR=path # (only needed if at custom location) path to VORO include directory :pre
+
+[Traditional make]:
+
+You can download and build the Voro++ library manually if you prefer;
+follow the instructions in lib/voronoi/README. You can also do it in
+one step from the lammps/src dir, using a command like these, which
+simply invoke the lib/voronoi/Install.py script with the specified
+args:
+
+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
+
+USER-ATC package :h4,link(user-atc)
+
+The USER-ATC package requires the MANYBODY package also be installed.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_REAX=yes" and "-D
+PKG_MANYBODY=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the ATC library in lib/atc.
+You can do this manually if you prefer; follow the instructions in
+lib/atc/README. You can also do it in one step from the lammps/src
+dir, using a command like these, which simply invoke the
+lib/atc/Install.py script with the specified args:
+
+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 :h4,link(user-awpmd)
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-AQPMD=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the AWPMD library in lib/awpmd.
+You can do this manually if you prefer; follow the instructions in
+lib/awpmd/README. You can also do it in one step from the lammps/src
+dir, using a command like these, which simply invoke the
+lib/awpmd/Install.py script with the specified args:
+
+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 :h4,link(user-colvars)
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-COLVARS=yes".
+
+[Traditional make]:
+
+Before building LAMMPS, you must 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 :h4,link(user-h5md)
+
+To build with this package you must have the HDF5 software package
+installed on your system, which should include the h5cc compiler and
+the HDF5 library.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-H5MD=yes".
+
+This should autodetect the H5MD library on your system. Several
+advanced CMake H5MD options exist if you need to specify where it is
+installed. Use the ccmake (terminal window) or cmake-gui (graphical)
+tools to see these options and set them interactively from their user
+interfaces.
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the CH5MD library in lib/h5md.
+You can do this manually if you prefer; follow the instructions in
+lib/h5md/README. You can also do it in one step from the lammps/src
+dir, using a command like these, which simply invoke the
+lib/h5md/Install.py script with the specified args:
+
+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 :h4,link(user-intel)
+
+To build with this package, you must choose which hardware you want to
+build for, either Intel CPUs or Intel KNLs. You should also typically
+"install the USER-OMP package"_#user-omp, 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.
+
+[CMake build]:
+
+-D INTEL_ARCH=value # value = cpu (default) or knl
+-D BUILD_OMP=yes # also required to build with the USER-INTEl package :pre
+
+Requires an Intel compiler as well as the Intel TBB and MKL libraries.
+
+[Traditional make]:
+
+Choose which hardware to compile for in Makefile.machine via the
+following settings. See src/MAKE/OPTIONS/Makefile.intel_cpu* and
+Makefile.knl files for examples.
+
+For CPUs:
+
+OPTFLAGS = -xHost -O2 -fp-model fast=2 -no-prec-div -qoverride-limits -qopt-zmm-usage=high
+CCFLAGS = -g -qopenmp -DLAMMPS_MEMALIGN=64 -no-offload \
+ -fno-alias -ansi-alias -restrict $(OPTFLAGS)
+LINKFLAGS = -g -qopenmp $(OPTFLAGS)
+LIB = -ltbbmalloc :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
+
+:line
+
+USER-MOLFILE package :h4,link(user-molfile)
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-MOLFILE=yes".
+
+[Traditional make]:
+
+The lib/molfile/Makefile.lammps file has a setting for a dynamic
+loading library libdl.a that is typically present on all systems. It
+is required for LAMMPS to link with this package. If the setting is
+not valid for your system, you will need to edit the Makefile.lammps
+file. See lib/molfile/README and lib/molfile/Makefile.lammps for
+details.
+
+:line
+
+USER-NETCDF package :h4,link(user-netcdf)
+
+To build with this package you must have the NetCDF library installed
+on your system.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-NETCDF=yes".
+
+This should autodetect the NETCDF library if it is installed on your
+system at standard locations. Several advanced CMake NETCDF options
+exist if you need to specify where it was installed. Use the ccmake
+(terminal window) or cmake-gui (graphical) tools to see these options
+and set them interactively from their user interfaces.
+
+[Traditional make]:
+
+The lib/netcdf/Makefile.lammps file has settings for NetCDF include
+and library files which LAMMPS needs to build with this package. If
+the settings are not valid for your system, you will need to edit the
+Makefile.lammps file. See lib/netcdf/README for details.
+
+:line
+
+USER-OMP package :h4,link(user-omp)
+
+[CMake build]:
+
+No additional settings are required besides "-D PKG_USER-OMP=yes". If
+CMake detects OpenMP support, the USER-OMP code will be compiled with
+multi-threading support enabled, otherwise as optimized serial code.
+
+[Traditional make]:
+
+To enable multi-threading support in the USER-OMP package (and other
+styles supporting OpenMP) the following compile and link flags must
+be added to your Makefile.machine file.
+See src/MAKE/OPTIONS/Makefile.omp for an example.
+
+CCFLAGS: -fopenmp # for GNU Compilers
+CCFLAGS: -qopenmp -restrict # for Intel compilers on Linux
+LINKFLAGS: -fopenmp # for GNU Compilers
+LINKFLAGS: -qopenmp # for Intel compilers on Linux :pre
+
+For other platforms and compilers, please consult the documentation
+about OpenMP support for your compiler.
+
+:line
+
+USER-QMMM package :h4,link(user-qmmm)
+
+NOTE: The LAMMPS executable these steps produce is not yet functional
+for a QM/MM simulation. You must also build Quantum ESPRESSO and
+create a new executable (pwqmmm.x) which links LAMMPS and Quantum
+ESPRESSO together. These are steps 3 and 4 described in the
+lib/qmmm/README file. Unfortunately, the Quantum ESPRESSO developers
+have been breaking the interface that the QM/MM code in LAMMPS is using,
+so that currently (Summer 2018) using this feature requires either
+correcting the library interface feature in recent Quantum ESPRESSO
+releases, or using an outdated version of QE. The last version of
+Quantum ESPRESSO known to work with this QM/MM interface was version
+5.4.1 from 2016.
+
+[CMake build]:
+
+The CMake build system currently does not support building the full
+QM/MM-capable hybrid executable of LAMMPS and QE called pwqmmm.x.
+You must use the traditional make build for this package.
+
+[Traditional make]:
+
+Before building LAMMPS, you must build the QMMM library in lib/qmmm.
+You can do this manually if you prefer; follow the first two steps
+explained in lib/qmmm/README. You can also do it in one step from the
+lammps/src dir, using a command like these, which simply invoke the
+lib/qmmm/Install.py script with the specified args:
+
+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 QMMM package and build LAMMPS in the usual
+manner. After completing the LAMMPS build and compiling Quantum
+ESPRESSO with external library support, go back to the lib/qmmm folder
+and follow the instructions on the README file to build the combined
+LAMMPS/QE QM/MM executable (pwqmmm.x) in the lib/qmmm folder.
+
+:line
+
+USER-QUIP package :h4,link(user-quip)
+
+To build with this package, you must download and build the QUIP
+library. It can be obtained from GitHub. For support of GAP
+potentials, additional files with specific licensing conditions need
+to be downloaded and configured. See step 1 and step 1.1 in the
+lib/quip/README file for details on how to do this.
+
+[CMake build]:
+
+-D QUIP_LIBRARIES=path # path to libquip.a (only needed if a custom location)
+
+CMake will not download and build the QUIP library. But once you have
+done that, a CMake build of LAMMPS with "-D PKG_USER-QUIP=yes" should
+work. Set QUIP_LIBRARIES if CMake cannot find the QUIP library.
+
+[Traditional make]:
+
+The download/build procedure for the QUIP library, described in
+lib/quip/README file requires setting two environment variables,
+QUIP_ROOT and QUIP_ARCH. These are accessed by the
+lib/quip/Makefile.lammps file which is used when you compile and link
+LAMMPS with this package. You should only need to edit
+Makefile.lammps if the LAMMPS build can not use its settings to
+successfully build on your system.
+
+:line
+
+USER-SMD package :h4,link(user-smd)
+
+To build with this package, you must download the Eigen3 library.
+Eigen3 is a template library, so you do not need to build it.
+
+[CMake build]:
+
+-D DOWNLOAD_EIGEN3 # download Eigen3, value = no (default) or yes
+-D EIGEN3_INCLUDE_DIR=path # path to Eigen library (only needed if a custom location) :pre
+
+Set EIGEN3_INCLUDE_DIR if CMake cannot find the Eigen3 library.
+
+[Traditional make]:
+
+You can download the Eigen3 library manually if you prefer; follow the
+instructions in lib/smd/README. You can also do it in one step from
+the lammps/src dir, using a command like these, which simply invoke
+the lib/smd/Install.py script with the specified args:
+
+make lib-smd # print help message
+make lib-smd args="-b" # download to lib/smd/eigen3
+make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3 :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.
+
+:line
+
+USER-VTK package :h4,link(user-vtk)
+
+To build with this package you must have the VTK library installed on
+your system.
+
+[CMake build]:
+
+No additional settings are needed besides "-D PKG_USER-VTK=yes".
+
+This should autodetect the VTK library if it is installed on your
+system at standard locations. Several advanced VTK options exist if
+you need to specify where it was installed. Use the ccmake (terminal
+window) or cmake-gui (graphical) tools to see these options and set
+them interactively from their user interfaces.
+
+[Traditional make]:
+
+The lib/vtk/Makefile.lammps file has settings for accessing VTK files
+and its library, which LAMMPS needs to build with this package. If
+the settings are not valid for your system, check if one of the other
+lib/vtk/Makefile.lammps.* files is compatible and copy it to
+Makefile.lammps. If none of the provided files work, you will need to
+edit the Makefile.lammps file. See lib/vtk/README for details.
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..c00ce1f420
--- /dev/null
+++ b/doc/src/Build_make.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
+
+Build LAMMPS with make :h3
+
+Building LAMMPS with traditional makefiles requires that you have a
+Makefile."machine" file appropriate for your system in the src/MAKE,
+src/MAKE/MACHINES, src/MAKE/OPTIONS, or src/MAKE/MINE directory (see
+below). It can include various options for customizing your LAMMPS
+build with a number of global compilation options and features.
+
+To include LAMMPS packages (i.e. optional commands and styles) you
+must install them first, as discussed on the "Build
+package"_Build_package.html doc page. If the packages require
+provided or external libraries, you must build those libraries before
+building LAMMPS. Building "LAMMPS with CMake"_Build_cmake.html can
+automate all of this for many types of machines, especially
+workstations, desktops and laptops, so we suggest you try it first.
+
+These commands perform a default LAMMPS build, producing the LAMMPS
+executable lmp_serial or lmp_mpi in lammps/src:
+
+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
+
+This initial compilation can take a long time, since LAMMPS is a large
+project with many features. If your machine has multiple CPU cores
+(most do these days), using a command like "make -jN mpi" (with N =
+the number of available CPU cores) can be much faster. If you plan to
+do development on LAMMPS or need to recompile LAMMPS repeatedly, the
+installation of the ccache (= Compiler Cache) software may speed up
+compilation even more.
+
+After the initial build, whenever you edit LAMMPS source files, or add
+or remove new files to the source directory (e.g. by installing or
+uninstalling packages), you must recompile and relink the LAMMPS
+executable with the same "make" command. This makefiles dependencies
+should insure that only the subset of files that need to be are
+recompiled.
+
+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
+
+The lammps/src/MAKE tree contains all the Makefile.machine files
+included in the LAMMPS distribution. Typing "make machine" uses
+Makefile.machine. Thus the "make serial" or "make mpi" lines above
+use Makefile.serial and Makefile.mpi. Others are in these dirs:
+
+OPTIONS # Makefiles which enable specific options
+MACHINES # Makefiles for specific machines
+MINE # customized Makefiles you create (you may need to create this folder) :pre
+
+Typing "make" lists all the available Makefile.machine files. A file
+with the same name can appear in multiple folders (not a good idea).
+The order the dirs are searched is as follows: src/MAKE/MINE,
+src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. This gives preference
+to a customized file you put in src/MAKE/MINE.
+
+Makefiles you may wish to try include these (some require a package
+first be installed). Many of these include specific compiler flags
+for optimized performance. Please note, however, that some of these
+customized machine Makefile are contributed by users. Since both
+compilers, OS configs, and LAMMPS itself keep changing, their settings
+may become outdated:
+
+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..dc8918c884
--- /dev/null
+++ b/doc/src/Build_package.txt
@@ -0,0 +1,222 @@
+"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.
+
+An overview of packages is given on the "Packages"_Packages.html doc
+page. Brief overviews of each package 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 that package. Running LAMMPS with the
+"-h command-line switch"_Run_options.html will print all the included
+packages and commands for that executable.
+
+For the majority of packages, if you follow the single step below to
+include it, you can then build LAMMPS exactly the same as you would
+without any packages installed. A few packages may require additional
+steps, as explained on the "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)
+
+The mechanism for including packages is simple but different for CMake
+versus make.
+
+[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.
+
+See the shortcut section below for how to install many packages at
+once with CMake.
+
+NOTE: If you toggle back and forth between building with CMake vs
+make, no packages in the src directory can be installed when you
+invoke cmake. CMake will give an error if that is not the case,
+indicating how you can un-install all packages in the src dir.
+
+[Traditional make]:
+
+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.
+
+See the shortcut section below for how to install many packages at
+once with make.
+
+NOTE: You must always re-build LAMMPS (via make) after installing or
+un-installing a package, for the action to take effect.
+
+NOTE: You cannot install or un-install packages and build LAMMPS in a
+single make command with multiple targets, e.g. make yes-colloid mpi.
+This is because the make procedure creates a list of source files that
+will be out-of-date for the build if the package configuration changes
+within the same command. You can include or exclude multiple packages
+in a single make command, e.g. make yes-colloid no-manybody.
+
+[CMake and make info]:
+
+Any package can be included or excluded in a LAMMPS build, independent
+of all other packages. However, some packages include files derived
+from files in other packages. LAMMPS checks for this and does the
+right thing. Individual files are only included if their dependencies
+are already included. Likewise, if a package is excluded, other files
+dependent on that package are also excluded.
+
+When you download a LAMMPS tarball or download LAMMPS source files
+from the Git or SVN repositories, no packages are pre-installed in the
+src directory.
+
+NOTE: Prior to Aug 2018, if you downloaded a tarball, 3 packages
+(KSPACE, MANYBODY, MOLECULE) were pre-installed in the src directory.
+That is no longer the case, so that CMake will build as-is without the
+need to un-install those packages.
+
+:line
+
+[CMake shortcuts for installing many packages]:
+
+Instead of specifying all the CMake options via the command-line,
+CMake allows initializing the variable cache using script files. These
+are regular CMake files which can manipulate and set variables, and
+can also contain control flow constructs.
+
+LAMMPS includes several of these files to define configuration
+"presets", similar to the options that exist for the Make based
+system. Using these files you can enable/disable portions of the
+available packages in LAMMPS. If you need a custom preset you can take
+one of them as a starting point and customize it to your needs.
+
+cmake -C ../cmake/presets/all_on.cmake \[OPTIONS\] ../cmake | enable all packages
+cmake -C ../cmake/presets/all_off.cmake \[OPTIONS\] ../cmake | disable all packages
+cmake -C ../cmake/presets/std.cmake \[OPTIONS\] ../cmake | enable standard packages
+cmake -C ../cmake/presets/user.cmake \[OPTIONS\] ../cmake | enable user packages
+cmake -C ../cmake/presets/std_nolib.cmake \[OPTIONS\] ../cmake | enable standard packages that do not require extra libraries
+cmake -C ../cmake/presets/nolib.cmake \[OPTIONS\] ../cmake | disable all packages that do not require extra libraries
+cmake -C ../cmake/presets/manual_selection.cmake \[OPTIONS\] ../cmake | example of how to create a manual selection of packages :tb(s=|,a=l)
+
+NOTE: Running cmake this way manipulates the variable cache in your
+current build directory. You can combine presets and options with
+multiple cmake runs.
+
+[Example:]
+
+# build LAMMPS with all "standard" packages which don't
+# use libraries and enable GPU package
+mkdir build
+cd build
+cmake -C ../cmake/presets/std_nolib.cmake -D PKG_GPU=on ../cmake :pre
+
+:line
+
+[Make shortcuts for installing many packages]:
+
+The following commands are useful for managing package source files
+and their installation when building LAMMPS via traditional make.
+Just type "make" in lammps/src to see a one-line summary.
+
+These commands install/un-install sets of packages:
+
+make yes-all | install all packages
+make no-all | un-install all packages
+make yes-standard or make yes-std | install standard packages
+make no-standard or make no-std| un-install standard packages
+make yes-user | install user packages
+make no-user | un-install user packages
+make yes-lib | install packages that require extra libraries
+make no-lib | un-install packages that require extra libraries
+make yes-ext | install packages that require external libraries
+make no-ext | un-install packages that require external libraries :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..db281c0857
--- /dev/null
+++ b/doc/src/Build_settings.txt
@@ -0,0 +1,341 @@
+"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 building both with CMake and make.
+
+"FFT library"_#fft for use with the "kspace_style pppm"_kspace_style.html command
+"Size of LAMMPS data types"_#size
+"Read or write compressed files"_#gzip
+"Output of JPG and PNG files"_#graphics via the "dump image"_dump_image.html command
+"Output of movie files"_#graphics via the "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
+
+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 can be faster.
+LAMMPS can use them if they are available on your system.
+
+[CMake variables]:
+
+-D FFT=value # FFTW3 or MKL or KISS, default is FFTW3 if found, else KISS
+-D FFT_SINGLE=value # yes or no (default), no = double precision
+-D FFT_PACK=value # array (default) or pointer or memcpy :pre
+
+NOTE: The values for the FFT variable must be in upper-case. This is
+an exception to the rule that all CMake variables can be specified
+with lower-case values.
+
+Usually these settings are all that is needed. If CMake cannot find
+the FFT library, you can set these variables:
+
+-D FFTW3_INCLUDE_DIRS=path # path to FFTW3 include files
+-D FFTW3_LIBRARIES=path # path to FFTW3 libraries
+-D MKL_INCLUDE_DIRS=path # ditto for Intel MKL library
+-D MKL_LIBRARIES=path :pre
+
+[Makefile.machine settings]:
+
+FFT_INC = -DFFT_FFTW3 # -DFFT_FFTW3, -DFFT_FFTW (same as -DFFT_FFTW3), -DFFT_MKL, or -DFFT_KISS
+ # default is KISS if not specified
+FFT_INC = -DFFT_SINGLE # do not specify for double precision
+FFT_INC = -DFFT_PACK_ARRAY # or -DFFT_PACK_POINTER or -DFFT_PACK_MEMCPY :pre
+ # default is FFT_PACK_ARRAY if not specified
+
+FFT_INC = -I/usr/local/include
+FFT_PATH = -L/usr/local/lib
+FFT_LIB = -lfftw3 # FFTW3 double precision
+FFT_LIB = -lfftw3 -lfftw3f # FFTW3 single precision
+FFT_LIB = -lmkl_intel_lp64 -lmkl_sequential -lmkl_core # MKL with Intel compiler
+FFT_LIB = -lmkl_gf_lp64 -lmkl_sequential -lmkl_core # MKL with GNU compier :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. It is portable across all platforms. Depending on the
+size of the FFTs and the number of processors used, the other
+libraries listed here can be faster.
+
+However, note that long-range Coulombics are only a portion of the
+per-timestep CPU cost, FFTs are only a portion of long-range
+Coulombics, and 1d FFTs are only a portion of the FFT cost (parallel
+communication can be costly). A breakdown of these timings is printed
+to the screen at the end of a run using the "kspace_style
+pppm"_kspace_style.html command. The "Run output"_doc page gives more
+details.
+
+FFTW is a fast, portable FFT library that should also work on any
+platform and can be faster than the KISS FFT library. You can
+download it from "www.fftw.org"_http://www.fftw.org. LAMMPS requires
+version 3.X; the legacy version 2.1.X is no longer supported.
+
+Building FFTW for your box should be as simple as ./configure; make;
+make install. The install command typically requires root privileges
+(e.g. invoke it via sudo), unless you specify a local directory with
+the "--prefix" option of configure. Type "./configure --help" to see
+various options.
+
+The Intel MKL math library is part of the Intel compiler suite. It
+can be used with the Intel or GNU compiler (see FFT_LIB setting above).
+
+Performing 3d FFTs in parallel can be time consuming due to data
+access and required communication. This cost can be reduced by
+performing single-precision FFTs instead of double precision. Single
+precision means the real and imaginary parts of a complex datum are
+4-byte floats. Double precesion means they are 8-byte doubles. Note
+that Fourier transform and related PPPM operations are somewhat less
+sensitive to floating point truncation errors and thus the resulting
+error is less than the difference in precision. Using the -DFFT_SINGLE
+setting trades off a little accuracy for reduced memory use and
+parallel communication costs for transposing 3d FFT data.
+
+When using -DFFT_SINGLE with FFTW3 you may need to build the FFTW
+library a second time with support for single-precision.
+
+For FFTW3, do the following, which should produce the additional
+library libfftw3f.a
+
+make clean
+./configure --enable-single; 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
+ # default is LAMMMPS_SMALLBIG if not specified
+[CMake and make info]:
+
+The default "smallbig" setting allows for simulations with:
+
+total atom count = 2^63 atoms (about 9e18)
+total timesteps = 2^63 (about 9e18)
+atom IDs = 2^31 (about 2 billion)
+image flags = roll over at 512 :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 WITH_JPEG=value # yes or no
+ # default = yes if CMake finds JPEG files, else no
+-D WITH_PNG=value # yes or no
+ # default = yes if CMake finds PNG and ZLIB files, else no
+-D WITH_FFMPEG=value # yes or no
+ # default = yes if CMake can find ffmpeg, else no :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 libz.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, libz.a (.so) files if make cannot find them
+JPG_LIB = -ljpeg -lpng -lz # 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(gzip)
+
+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 WITH_GZIP=value # yes or no
+ # default is yes if CMake can find gzip, else no
+-D GZIP_EXECUTABLE=path # path to gzip executable if CMake cannot find it :pre
+
+[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_details.html#PKG-COMPRESS 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.
+On most current systems, the malloc() implementation returns
+pointers that are aligned to 16-byte boundaries. Using SSE vector
+instructions efficiently, however, requires memory blocks being
+aligned on 64-byte boundaries.
+
+[CMake variable]:
+
+-D LAMMPS_MEMALIGN=value # 0, 8, 16, 32, 64 (default) :pre
+
+Use a LAMMPS_MEMALIGN value of 0 to disable using posix_memalign()
+and revert to using the malloc() C-library function instead. When
+compiling LAMMPS for Windows systems, malloc() will always be used
+and this setting ignored.
+
+[Makefile.machine setting]:
+
+LMP_INC = -DLAMMPS_MEMALIGN=value # 8, 16, 32, 64 :pre
+
+Do not set -DLAMMPS_MEMALIGN, if you want to have memory allocated
+with the malloc() function call instead. -DLAMMPS_MEMALIGN [cannot]
+be used on Windows, as it does use different function calls for
+allocating aligned memory, that are not compatible with how LAMMPS
+manages its dynamical memory.
+
+: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/Commands.txt b/doc/src/Commands.txt
index 30e3343bd2..84eac285f7 100644
--- a/doc/src/Commands.txt
+++ b/doc/src/Commands.txt
@@ -16,6 +16,7 @@ commands in it are used to define a LAMMPS simulation.
"Using GitHub with LAMMPS"_Howto_github.html
"PyLAMMPS interface to LAMMPS"_Howto_pylammps.html
-"Using LAMMPS with bash on Windows"_Howto_bash.html
+"Using LAMMPS with bash on Windows"_Howto_bash.html :all(b)
"Restart a simulation"_Howto_restart.html
"Visualize LAMMPS snapshots"_Howto_viz.html
@@ -121,8 +128,8 @@ END_RST -->
"Polarizable models"_Howto_polarizable.html
"Adiabatic core/shell model"_Howto_coreshell.html
"Drude induced dipoles"_Howto_drude.html
-"Drude induced dipoles (extended)"_Howto_drude2.html :all(b)
+"Drude induced dipoles (extended)"_Howto_drude2.html
"Manifolds (surfaces)"_Howto_manifold.html
-"Magnetic spins"_Howto_spins.html
+"Magnetic spins"_Howto_spins.html :all(b)
diff --git a/doc/src/Howto_bioFF.txt b/doc/src/Howto_bioFF.txt
index afb8a84f2e..deb5b31441 100644
--- a/doc/src/Howto_bioFF.txt
+++ b/doc/src/Howto_bioFF.txt
@@ -96,6 +96,10 @@ documentation for the formula it computes.
[(MacKerell)] MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field,
Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998).
+:link(howto-Cornell)
+[(Cornell)] Cornell, Cieplak, Bayly, Gould, Merz, Ferguson,
+Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995).
+
:link(howto-Mayo)
[(Mayo)] Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909
(1990).
diff --git a/doc/src/Howto_coreshell.txt b/doc/src/Howto_coreshell.txt
index 4f1cd64384..7503fa1ebe 100644
--- a/doc/src/Howto_coreshell.txt
+++ b/doc/src/Howto_coreshell.txt
@@ -119,7 +119,7 @@ the core/shell pair, which is an imaginary degree of freedom, from the
real physical system. To do that, the "compute
temp/cs"_compute_temp_cs.html command can be used, in conjunction with
any of the thermostat fixes, such as "fix nvt"_fix_nh.html or "fix
-langevin"_fix_langevin. This compute uses the center-of-mass velocity
+langevin"_fix_langevin.html. This compute uses the center-of-mass velocity
of the core/shell pairs to calculate a temperature, and insures that
velocity is what is rescaled for thermostatting purposes. This
compute also works for a system with both core/shell pairs and
@@ -150,9 +150,9 @@ The pressure for the core/shell system is computed via the regular
LAMMPS convention by "treating the cores and shells as individual
particles"_#MitchellFincham2. For the thermo output of the pressure
as well as for the application of a barostat, it is necessary to
-use an additional "pressure"_compute_pressure compute based on the
-default "temperature"_compute_temp and specifying it as a second
-argument in "fix modify"_fix_modify.html and
+use an additional "pressure"_compute_pressure.html compute based on
+the default "temperature"_compute_temp.html and specifying it as a
+second argument in "fix modify"_fix_modify.html and
"thermo_modify"_thermo_modify.html resulting in:
(...)
diff --git a/doc/src/Howto_couple.txt b/doc/src/Howto_couple.txt
index 38595a9d16..d7b4924d8c 100644
--- a/doc/src/Howto_couple.txt
+++ b/doc/src/Howto_couple.txt
@@ -77,17 +77,16 @@ strain induced across grain boundaries :l
:link(quest,http://dft.sandia.gov/Quest)
:link(spparks,http://www.sandia.gov/~sjplimp/spparks.html)
-"This section"_Section_start.html#start_5 of the documentation
-describes how to build LAMMPS as a library. Once this is done, you
-can interface with LAMMPS either via C++, C, Fortran, or Python (or
-any other language that supports a vanilla C-like interface). For
-example, from C++ you could create one (or more) "instances" of
-LAMMPS, pass it an input script to process, or execute individual
-commands, all by invoking the correct class methods in LAMMPS. From C
-or Fortran you can make function calls to do the same things. See the
-"Python"_Python.html doc pages for a description of the Python wrapper
-provided with LAMMPS that operates through the LAMMPS library
-interface.
+The "Build basics"_Build_basics.html doc page describes how to build
+LAMMPS as a library. Once this is done, you can interface with LAMMPS
+either via C++, C, Fortran, or Python (or any other language that
+supports a vanilla C-like interface). For example, from C++ you could
+create one (or more) "instances" of LAMMPS, pass it an input script to
+process, or execute individual commands, all by invoking the correct
+class methods in LAMMPS. From C or Fortran you can make function
+calls to do the same things. See the "Python"_Python_head.html doc
+pages 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 contain the C-style interface
to LAMMPS. See the "Howto library"_Howto_library.html doc page for a
diff --git a/doc/src/Howto_granular.txt b/doc/src/Howto_granular.txt
index 8027369501..758b1cebee 100644
--- a/doc/src/Howto_granular.txt
+++ b/doc/src/Howto_granular.txt
@@ -53,5 +53,5 @@ computations between frozen atoms by using this command:
NOTE: By default, for 2d systems, granular particles are still modeled
as 3d spheres, not 2d discs (circles), meaning their moment of inertia
will be the same as in 3d. If you wish to model granular particles in
-2d as 2d discs, see the note on this topic on the "Howto 2d"_Howto_2d
+2d as 2d discs, see the note on this topic on the "Howto 2d"_Howto_2d.html
doc page, where 2d simulations are discussed.
diff --git a/doc/src/Howto_library.txt b/doc/src/Howto_library.txt
index 0d4852fbf2..741078e7eb 100644
--- a/doc/src/Howto_library.txt
+++ b/doc/src/Howto_library.txt
@@ -9,10 +9,10 @@ Documentation"_ld - "LAMMPS Commands"_lc :c
Library interface to LAMMPS :h3
-As described in "Section 2.5"_Section_start.html#start_5, LAMMPS can
-be built as a library, so that it can be called by another code, used
-in a "coupled manner"_Howto_couple.html with other codes, or driven
-through a "Python interface"_Python.html.
+As described on the "Build basics"_Build_basics.html doc page, LAMMPS
+can be built as a library, so that it can be called by another code,
+used in a "coupled manner"_Howto_couple.html with other codes, or
+driven through a "Python interface"_Python_head.html.
All of these methodologies use a C-style interface to LAMMPS that is
provided in the files src/library.cpp and src/library.h. The
@@ -35,8 +35,8 @@ details.
NOTE: You can write code for additional functions as needed to define
how your code talks to LAMMPS and add them to src/library.cpp and
-src/library.h, as well as to the "Python interface"_Python.html. The
-added functions can access or change any internal LAMMPS data you
+src/library.h, as well as to the "Python interface"_Python_head.html.
+The added functions can access or change any internal LAMMPS data you
wish.
void lammps_open(int, char **, MPI_Comm, void **)
@@ -51,12 +51,11 @@ void lammps_free(void *) :pre
The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were "command-line
-arguments"_Section_start.html#start_6 when LAMMPS is run in
-stand-alone mode from the command line, and a MPI communicator for
-LAMMPS to run under. It returns a ptr to the LAMMPS object that is
-created, and which is used in subsequent library calls. The
-lammps_open() function can be called multiple times, to create
-multiple instances of LAMMPS.
+arguments"_Run_options.html when LAMMPS is run in stand-alone mode
+from the command line, and a MPI communicator for LAMMPS to run under.
+It returns a ptr to the LAMMPS object that is created, and which is
+used in subsequent library calls. The lammps_open() function can be
+called multiple times, to create multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
diff --git a/doc/src/Howto_multiple.txt b/doc/src/Howto_multiple.txt
index edcb8196cf..9ad872fedc 100644
--- a/doc/src/Howto_multiple.txt
+++ b/doc/src/Howto_multiple.txt
@@ -80,8 +80,7 @@ jump in.polymer :pre
All of the above examples work whether you are running on 1 or
multiple processors, but assumed you are running LAMMPS on a single
partition of processors. LAMMPS can be run on multiple partitions via
-the "-partition" command-line switch as described in "this
-section"_Section_start.html#start_6 of the manual.
+the "-partition command-line switch"_Run_options.html.
In the last 2 examples, if LAMMPS were run on 3 partitions, the same
scripts could be used if the "index" and "loop" variables were
diff --git a/doc/src/Howto_replica.txt b/doc/src/Howto_replica.txt
index 1b44fe5374..2135e52e0e 100644
--- a/doc/src/Howto_replica.txt
+++ b/doc/src/Howto_replica.txt
@@ -29,29 +29,28 @@ runs different replicas at a series of temperature to facilitate
rare-event sampling.
These commands can only be used if LAMMPS was built with the REPLICA
-package. See the "Making LAMMPS"_Section_start.html#start_3 section
-for more info on packages.
+package. See the "Build package"_Build_package.html doc page for more
+info.
PIMD runs different replicas whose individual particles are coupled
together by springs to model a system or ring-polymers.
This commands can only be used if LAMMPS was built with the USER-MISC
-package. See the "Making LAMMPS"_Section_start.html#start_3 section
-for more info on packages.
+package. See the "Build package"_Build_package.html doc page for more
+info.
In all these cases, you must run with one or more processors per
replica. The processors assigned to each replica are determined at
run-time by using the "-partition command-line
-switch"_Section_start.html#start_6 to launch LAMMPS on multiple
-partitions, which in this context are the same as replicas. E.g.
-these commands:
+switch"_Run_options.html to launch LAMMPS on multiple partitions,
+which in this context are the same as replicas. E.g. these commands:
mpirun -np 16 lmp_linux -partition 8x2 -in in.temper
mpirun -np 8 lmp_linux -partition 8x1 -in in.neb :pre
would each run 8 replicas, on either 16 or 8 processors. Note the use
-of the "-in command-line switch"_Section_start.html#start_6 to specify
-the input script which is required when running in multi-replica mode.
+of the "-in command-line switch"_Run_options.html to specify the input
+script which is required when running in multi-replica mode.
Also note that with MPI installed on a machine (e.g. your desktop),
you can run on more (virtual) processors than you have physical
diff --git a/doc/src/Howto_restart.txt b/doc/src/Howto_restart.txt
index b211775479..bc67daa78e 100644
--- a/doc/src/Howto_restart.txt
+++ b/doc/src/Howto_restart.txt
@@ -16,8 +16,8 @@ restart files can be saved to disk using the "restart"_restart.html
command. At a later time, these binary files can be read via a
"read_restart"_read_restart.html command in a new script. Or they can
be converted to text data files using the "-r command-line
-switch"_Section_start.html#start_6 and read by a
-"read_data"_read_data.html command in a new script.
+switch"_Run_options.html and read by a "read_data"_read_data.html
+command in a new script.
Here we give examples of 2 scripts that read either a binary restart
file or a converted data file and then issue a new run command to
diff --git a/doc/src/Howto_temperature.txt b/doc/src/Howto_temperature.txt
index 7a318250cf..8a9e262da1 100644
--- a/doc/src/Howto_temperature.txt
+++ b/doc/src/Howto_temperature.txt
@@ -17,7 +17,10 @@ aggregate motion of particles) and its thermal velocity. The sum of
the two is the particle's total velocity, but the latter is often what
is wanted to compute a temperature.
-LAMMPS has several options for computing temperatures, any of which can be used in "thermostatting"_Howto_thermostat.html and "barostatting"_Howto_barostat.html. These "compute commands"_compute.html calculate temperature:
+LAMMPS has several options for computing temperatures, any of which
+can be used in "thermostatting"_Howto_thermostat.html and
+"barostatting"_Howto_barostat.html. These "compute
+commands"_compute.html calculate temperature:
"compute temp"_compute_temp.html
"compute temp/sphere"_compute_temp_sphere.html
@@ -35,6 +38,6 @@ velocities) that are removed when computing the thermal temperature.
temp/asphere"_compute_temp_asphere.html compute kinetic energy for
finite-size particles that includes rotational degrees of freedom.
They both allow for velocity biases indirectly, via an optional extra
-argument which is another temperature compute that subtracts a velocity bias.
-This allows the translational velocity of spherical or aspherical
-particles to be adjusted in prescribed ways.
+argument which is another temperature compute that subtracts a
+velocity bias. This allows the translational velocity of spherical or
+aspherical particles to be adjusted in prescribed ways.
diff --git a/doc/src/Howto_tip4p.txt b/doc/src/Howto_tip4p.txt
index f9e548e268..9f7f141314 100644
--- a/doc/src/Howto_tip4p.txt
+++ b/doc/src/Howto_tip4p.txt
@@ -31,7 +31,7 @@ using the "fix shake"_fix_shake.html command.
These are the additional parameters (in real units) to set for O and H
atoms and the water molecule to run a rigid TIP4P model with a cutoff
-"(Jorgensen)"_#Jorgensen1. Note that the OM distance is specified in
+"(Jorgensen)"_#Jorgensen5. Note that the OM distance is specified in
the "pair_style"_pair_style.html command, not as part of the pair
coefficients.
@@ -107,6 +107,6 @@ models"_http://en.wikipedia.org/wiki/Water_model.
:line
-:link(Jorgensen1)
+:link(Jorgensen5)
[(Jorgensen)] Jorgensen, Chandrasekhar, Madura, Impey, Klein, J Chem
Phys, 79, 926 (1983).
diff --git a/doc/src/Install.txt b/doc/src/Install.txt
new file mode 100644
index 0000000000..0a2e870a5d
--- /dev/null
+++ b/doc/src/Install.txt
@@ -0,0 +1,65 @@
+"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..538fa8aff8
--- /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"_Errors_bugs.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"_Errors_bugs.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..cc15ac0ae0
--- /dev/null
+++ b/doc/src/Install_linux.txt
@@ -0,0 +1,119 @@
+"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"_#ubuntu
+"Pre-built Gentoo Linux executable"_#gentoo :all(b)
+
+: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..7a0211ab65
--- /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"_Errors_bugs.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/Intro.txt b/doc/src/Intro.txt
index e3eaa40437..c8725e0085 100644
--- a/doc/src/Intro.txt
+++ b/doc/src/Intro.txt
@@ -15,8 +15,10 @@ These pages provide a brief introduction to LAMMPS.
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
@@ -18,8 +20,6 @@
:line
-
-
LAMMPS Documentation :c,h1
2 Aug 2018 version :c,h2
@@ -47,9 +47,9 @@ all LAMMPS development is coordinated.
"PDF file"_Manual.pdf of the entire manual, generated by
"htmldoc"_http://freecode.com/projects/htmldoc
-The content for this manual is part of the LAMMPS distribution.
-You can build a local copy of the Manual as HTML pages or a PDF file,
-by following the steps on the "this page"_Build_manual.html.
+The content for this manual is part of the LAMMPS distribution. You
+can build a local copy of the Manual as HTML pages or a PDF file, by
+following the steps on the "Manual build"_Manual_build.html doc page.
There is also a "Developer.pdf"_Developer.pdf document which gives
a brief description of the basic code structure of LAMMPS.
@@ -72,7 +72,9 @@ every LAMMPS command.
:includehidden:
Intro
- Section_start
+ Install
+ Build
+ Run
Commands
Packages
Speed
@@ -80,15 +82,16 @@ every LAMMPS command.
Examples
Tools
Modify
- Python
+ Python_head
Errors
+ Manual_build
.. toctree::
:caption: Index
:name: index
:hidden:
- commands
+ commands_list
fixes
computes
pairs
@@ -107,15 +110,9 @@ END_RST -->
"Introduction"_Intro.html :olb,l
-"Getting started"_Section_start.html :l
- 2.1 "What's in the LAMMPS distribution"_start_1 :ulb,b
- 2.2 "Making LAMMPS"_start_2 :b
- 2.3 "Making LAMMPS with optional packages"_start_3 :b
- 2.4 "Building LAMMPS as a library"_start_4 :b
- 2.5 "Running LAMMPS"_start_5 :b
- 2.6 "Command-line options"_start_6 :b
- 2.7 "Screen output"_start_7 :b
- 2.8 "Tips for users of previous versions"_start_8 :ule,b
+"Install LAMMPS"_Install.html :l
+"Build LAMMPS"_Build.html :l
+"Run LAMMPS"_Run.html :l
"Commands"_Commands.html :l
"Optional packages"_Packages.html :l
"Accelerate performance"_Speed.html :l
@@ -123,19 +120,11 @@ END_RST -->
"Example scripts"_Examples.html :l
"Auxiliary tools"_Tools.html :l
"Modify & extend LAMMPS"_Modify.html :l
-"Use Python with LAMMPS"_Python.html :l
+"Use Python with LAMMPS"_Python_head.html :l
"Errors"_Errors.html :l
+"Building the LAMMPS manual"_Manual_build.html :l
:ole
-:link(start_1,Section_start.html#start_1)
-:link(start_2,Section_start.html#start_2)
-:link(start_3,Section_start.html#start_3)
-:link(start_4,Section_start.html#start_4)
-:link(start_5,Section_start.html#start_5)
-:link(start_6,Section_start.html#start_6)
-:link(start_7,Section_start.html#start_7)
-:link(start_8,Section_start.html#start_8)
-