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 + + + + + + + + + + + + + + + + +
OptionDescriptionValues
INTEL_ARCHTarget 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) - diff --git a/doc/src/Manual_build.txt b/doc/src/Manual_build.txt new file mode 100644 index 0000000000..747a55a729 --- /dev/null +++ b/doc/src/Manual_build.txt @@ -0,0 +1,124 @@ +"Previous Section"_Errors.html - "LAMMPS WWW Site"_lws - +"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next +Section"_Manual.html :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Building the LAMMPS manual :h2 + +Depending on how you obtained LAMMPS, the doc directory has +2 or 3 sub-directories and optionally 2 PDF files and an ePUB file: + +src # content files for LAMMPS documentation +html # HTML version of the LAMMPS manual (see html/Manual.html) +tools # tools and settings for building the documentation +Manual.pdf # large PDF version of entire manual +Developer.pdf # small PDF with info about how LAMMPS is structured +LAMMPS.epub # Manual in ePUB format :pre + +If you downloaded LAMMPS as a tarball from the web site, all these +directories and files should be included. + +If you downloaded LAMMPS from the public SVN or Git repositories, then +the HTML and PDF files are not included. Instead you need to create +them, in one of three ways: + +(a) You can "fetch" the current HTML and PDF files from the LAMMPS web +site. Just type "make fetch". This should create a html_www dir and +Manual_www.pdf/Developer_www.pdf files. Note that if new LAMMPS +features have been added more recently than the date of your version, +the fetched documentation will include those changes (but your source +code will not, unless you update your local repository). + +(b) You can build the HTML and PDF files yourself, by typing "make +html" followed by "make pdf". Note that the PDF make requires the +HTML files already exist. This requires various tools including +Sphinx, which the build process will attempt to download and install +on your system, if not already available. See more details below. + +(c) You can genererate an older, simpler, less-fancy style of HTML +documentation by typing "make old". This will create an "old" +directory. This can be useful if (b) does not work on your box for +some reason, or you want to quickly view the HTML version of a doc +page you have created or edited yourself within the src directory. +E.g. if you are planning to submit a new feature to LAMMPS. + +:line + +The generation of all documentation is managed by the Makefile in +the doc dir. + +Documentation Build Options: :pre + +make html # generate HTML in html dir using Sphinx +make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf) + # in doc dir via htmldoc and pdflatex +make old # generate old-style HTML pages in old dir via txt2html +make fetch # fetch HTML doc pages and 2 PDF files from web site + # as a tarball and unpack into html dir and 2 PDFs +make epub # generate LAMMPS.epub in ePUB format using Sphinx +make clean # remove intermediate RST files created by HTML build +make clean-all # remove entire build folder and any cached data :pre + +:line + +Installing prerequisites for HTML build :h3 + +To run the HTML documention build toolchain, Python 3 and virtualenv +have to be installed. Here are instructions for common setups: + +Ubuntu :h4 + +sudo apt-get install python-virtualenv :pre + +Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x) :h4 + +sudo yum install python3-virtualenv :pre + +Fedora (since version 22) :h4 + +sudo dnf install python3-virtualenv pre + +MacOS X :h4 + +Python 3 :h5 + +Download the latest Python 3 MacOS X package from +"https://www.python.org"_https://www.python.org +and install it. This will install both Python 3 +and pip3. + +virtualenv :h5 + +Once Python 3 is installed, open a Terminal and type + +pip3 install virtualenv :pre + +This will install virtualenv from the Python Package Index. + +:line + +Installing prerequisites for PDF build + +[TBA] + +:line + +Installing prerequisites for epub build :h3 + +ePUB :h4 + +Same as for HTML. This uses the same tools and configuration +files as the HTML tree. + +For converting the generated ePUB file to a mobi format file +(for e-book readers like Kindle, that cannot read ePUB), you +also need to have the 'ebook-convert' tool from the "calibre" +software installed. "http://calibre-ebook.com/"_http://calibre-ebook.com/ +You first create the ePUB file with 'make epub' and then do: + +ebook-convert LAMMPS.epub LAMMPS.mobi :pre diff --git a/doc/src/Manual_version.txt b/doc/src/Manual_version.txt index 8583eabf86..436e531246 100644 --- a/doc/src/Manual_version.txt +++ b/doc/src/Manual_version.txt @@ -7,7 +7,7 @@ Documentation"_ld - "LAMMPS Commands"_lc :c :line -What does a LAMMPS version mean: :h3 +What does a LAMMPS version mean :h3 The LAMMPS "version" is the date when it was released, such as 1 May 2014. LAMMPS is updated continuously. Whenever we fix a bug or add a diff --git a/doc/src/Modify.txt b/doc/src/Modify.txt index f828bd5d74..666aaba8a7 100644 --- a/doc/src/Modify.txt +++ b/doc/src/Modify.txt @@ -1,6 +1,6 @@ "Previous Section"_Tools.html - "LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Python.html :c +Section"_Python_head.html :c :link(lws,http://lammps.sandia.gov) :link(ld,Manual.html) @@ -24,11 +24,13 @@ contribute"_Modify_contribute.html doc page. + + + +"Basics of running LAMMPS"_Run_basics.html +"Command-line options"_Run_options.html +"Screen and logfile output"_Run_output.html +"Running LAMMPS on Windows"_Run_windows.html :all(b) + + diff --git a/doc/src/Run_basics.txt b/doc/src/Run_basics.txt new file mode 100644 index 0000000000..c83d17d6a9 --- /dev/null +++ b/doc/src/Run_basics.txt @@ -0,0 +1,89 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Basics of running LAMMPS :h3 + +LAMMPS is run from the command line, reading commands from a +file via the -in command line flag, or from standard input. +Using the "-in in.file" variant is recommended: + +lmp_serial < in.file +lmp_serial -in in.file +/path/to/lammps/src/lmp_serial < in.file +mpirun -np 4 lmp_mpi -in in.file +mpirun -np 8 /path/to//lammps/src/lmp_mpi -in in.file +mpirun -np 6 /usr/local/bin/lmp -in in.file :pre + +You normally run the LAMMPS command in the directory where your +input script is located. That is also where output files are +produced by default, unless you provide specific other paths in +your input script or on the command line. As in some of the +examples above, the LAMMPS executable itself can be placed elsewhere. + +NOTE: The redirection operator "<" will not always work when running +in parallel with mpirun; for those systems the -in form is required. + +As LAMMPS runs it prints info to the screen and a logfile named +log.lammps. More info about output is given on the "Run +output"_Run_output.html doc page. + +If LAMMPS encounters errors in the input script or while running a +simulation it will print an ERROR message and stop or a WARNING +message and continue. See the "Errors"_Errors.html doc page for a +discussion of the various kinds of errors LAMMPS can or can't detect, +a list of all ERROR and WARNING messages, and what to do about them. + +:line + +LAMMPS can run the same problem on any number of processors, including +a single processor. In theory you should get identical answers on any +number of processors and on any machine. In practice, numerical +round-off can cause slight differences and eventual divergence of +molecular dynamics phase space trajectories. See the "Errors +common"_Errors_common.html doc page for discussion of this. + +LAMMPS can run as large a problem as will fit in the physical memory +of one or more processors. If you run out of memory, you must run on +more processors or define a smaller problem. + +If you run LAMMPS in parallel via mpirun, you should be aware of the +"processors"_processors.html command which controls how MPI tasks are +mapped to the simulation box, as well as mpirun options that control +how MPI tasks are assigned to physical cores of the node(s) of the +machine you are running on. These settings can improve performance, +though the defaults are often adequate. + +For example, it is often important to bind MPI tasks (processes) to +physical cores (processor affinity), so that the operating system does +not migrate them during a simulation. If this is not the default +behavior on your machine, the mpirun option "--bind-to core" (OpenMPI) +or "-bind-to core" (MPICH) can be used. + +If the LAMMPS command(s) you are using support multi-threading, you +can set the number of threads per MPI task via the environment +variable OMP_NUM_THREADS, before you launch LAMMPS: + +export OMP_NUM_THREADS=2 # bash +setenv OMP_NUM_THREADS 2 # csh or tcsh :pre + +This can also be done via the "package"_package.html command or via +the "-pk command-line switch"_Run_options.html which invokes the +package command. See the "package"_package.html command or +"Speed"_Speed.html doc pages for more details about which accerlarator +packages and which commands support multi-threading. + +:line + +You can experiment with running LAMMPS using any of the input scripts +provided in the examples or bench directory. Input scripts are named +in.* and sample outputs are named log.*.P where P is the number of +processors it was run on. + +Some of the examples or benchmarks require LAMMPS to be built with +optional packages. diff --git a/doc/src/Run_options.txt b/doc/src/Run_options.txt new file mode 100644 index 0000000000..0704e3b619 --- /dev/null +++ b/doc/src/Run_options.txt @@ -0,0 +1,469 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Command-line options :h3 + +At run time, LAMMPS recognizes several optional command-line switches +which may be used in any order. Either the full word or a one-or-two +letter abbreviation can be used: + +"-e or -echo"_#echo +"-h or -help"_#help +"-i or -in"_#file +"-k or -kokkos"_#run-kokkos +"-l or -log"_#log +"-nc or -nocite"_#nocite +"-pk or -package"_#package +"-p or -partition"_#partition +"-pl or -plog"_#plog +"-ps or -pscreen"_#pscreen +"-r or -restart"_#restart +"-ro or -reorder"_#reorder +"-sc or -screen"_#screen +"-sf or -suffix"_#suffix +"-v or -var"_#var :ul + +For example, the lmp_mpi executable might be launched as follows: + +mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy +mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy :pre + +:line + +[-echo style] :link(echo) + +Set the style of command echoing. The style can be {none} or {screen} +or {log} or {both}. Depending on the style, each command read from +the input script will be echoed to the screen and/or logfile. This +can be useful to figure out which line of your script is causing an +input error. The default value is {log}. The echo style can also be +set by using the "echo"_echo.html command in the input script itself. + +:line + +[-help] :link(help) + +Print a brief help summary and a list of options compiled into this +executable for each LAMMPS style (atom_style, fix, compute, +pair_style, bond_style, etc). This can tell you if the command you +want to use was included via the appropriate package at compile time. +LAMMPS will print the info and immediately exit if this switch is +used. + +:line + +[-in file] :link(file) + +Specify a file to use as an input script. This is an optional switch +when running LAMMPS in one-partition mode. If it is not specified, +LAMMPS reads its script from standard input, typically from a script +via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should +also work in parallel, but if it does not (in the unlikely case that +an MPI implementation does not support it), then use the -in flag. +Note that this is a required switch when running LAMMPS in +multi-partition mode, since multiple processors cannot all read from +stdin. + +:line + +[-kokkos on/off keyword/value ...] :link(run-kokkos) + +Explicitly enable or disable KOKKOS support, as provided by the KOKKOS +package. Even if LAMMPS is built with this package, as described +in "Speed kokkos"_Speed_kokkos.html, this switch must be set to enable +running with the KOKKOS-enabled styles the package provides. If the +switch is not set (the default), LAMMPS will operate as if the KOKKOS +package were not installed; i.e. you can run standard LAMMPS or with +the GPU or USER-OMP packages, for testing or benchmarking purposes. + +Additional optional keyword/value pairs can be specified which +determine how Kokkos will use the underlying hardware on your +platform. These settings apply to each MPI task you launch via the +"mpirun" or "mpiexec" command. You may choose to run one or more MPI +tasks per physical node. Note that if you are running on a desktop +machine, you typically have one physical node. On a cluster or +supercomputer there may be dozens or 1000s of physical nodes. + +Either the full word or an abbreviation can be used for the keywords. +Note that the keywords do not use a leading minus sign. I.e. the +keyword is "t", not "-t". Also note that each of the keywords has a +default setting. Examples of when to use these options and what +settings to use on different platforms is given on the "Speed +kokkos"_Speed_kokkos.html doc page. + +d or device +g or gpus +t or threads +n or numa :ul + +device Nd :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and if you are running with only one +MPI task per node. The Nd setting is the ID of the GPU on the node to +run on. By default Nd = 0. If you have multiple GPUs per node, they +have consecutive IDs numbered as 0,1,2,etc. This setting allows you +to launch multiple independent jobs on the node, each with a single +MPI task per node, and assign each job to run on a different GPU. + +gpus Ng Ns :pre + +This option is only relevant if you built LAMMPS with CUDA=yes, you +have more than one GPU per node, and you are running with multiple MPI +tasks per node (up to one per GPU). The Ng setting is how many GPUs +you will use. The Ns setting is optional. If set, it is the ID of a +GPU to skip when assigning MPI tasks to GPUs. This may be useful if +your desktop system reserves one GPU to drive the screen and the rest +are intended for computational work like running LAMMPS. By default +Ng = 1 and Ns is not set. + +Depending on which flavor of MPI you are running, LAMMPS will look for +one of these 3 environment variables + +SLURM_LOCALID (various MPI variants compiled with SLURM support) +MV2_COMM_WORLD_LOCAL_RANK (Mvapich) +OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre + +which are initialized by the "srun", "mpirun" or "mpiexec" commands. +The environment variable setting for each MPI rank is used to assign a +unique GPU ID to the MPI task. + +threads Nt :pre + +This option assigns Nt number of threads to each MPI task for +performing work when Kokkos is executing in OpenMP or pthreads mode. +The default is Nt = 1, which essentially runs in MPI-only mode. If +there are Np MPI tasks per physical node, you generally want Np*Nt = +the number of physical cores per node, to use your available hardware +optimally. This also sets the number of threads used by the host when +LAMMPS is compiled with CUDA=yes. + +numa Nm :pre + +This option is only relevant when using pthreads with hwloc support. +In this case Nm defines the number of NUMA regions (typically sockets) +on a node which will be utilized by a single MPI rank. By default Nm += 1. If this option is used the total number of worker-threads per +MPI rank is threads*numa. Currently it is always almost better to +assign at least one MPI rank per NUMA region, and leave numa set to +its default value of 1. This is because letting a single process span +multiple NUMA regions induces a significant amount of cross NUMA data +traffic which is slow. + +:line + +[-log file] :link(log) + +Specify a log file for LAMMPS to write status information to. In +one-partition mode, if the switch is not used, LAMMPS writes to the +file log.lammps. If this switch is used, LAMMPS writes to the +specified file. In multi-partition mode, if the switch is not used, a +log.lammps file is created with hi-level status information. Each +partition also writes to a log.lammps.N file where N is the partition +ID. If the switch is specified in multi-partition mode, the hi-level +logfile is named "file" and each partition also logs information to a +file.N. For both one-partition and multi-partition mode, if the +specified file is "none", then no log files are created. Using a +"log"_log.html command in the input script will override this setting. +Option -plog will override the name of the partition log files file.N. + +:line + +[-nocite] :link(nocite) + +Disable writing the log.cite file which is normally written to list +references for specific cite-able features used during a LAMMPS run. +See the "citation page"_http://lammps.sandia.gov/cite.html for more +details. + +:line + +[-package style args ....] :link(package) + +Invoke the "package"_package.html command with style and args. The +syntax is the same as if the command appeared at the top of the input +script. For example "-package gpu 2" or "-pk gpu 2" is the same as +"package gpu 2"_package.html in the input script. The possible styles +and args are documented on the "package"_package.html doc page. This +switch can be used multiple times, e.g. to set options for the +USER-INTEL and USER-OMP packages which can be used together. + +Along with the "-suffix" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +:line + +[-partition 8x2 4 5 ...] :link(partition) + +Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P +processors and this switch is not used, LAMMPS runs in one partition, +i.e. all P processors run a single simulation. If this switch is +used, the P processors are split into separate partitions and each +partition runs its own simulation. The arguments to the switch +specify the number of processors in each partition. Arguments of the +form MxN mean M partitions, each with N processors. Arguments of the +form N mean a single partition with N processors. The sum of +processors in all partitions must equal P. Thus the command +"-partition 8x2 4 5" has 10 partitions and runs on a total of 25 +processors. + +Running with multiple partitions can be useful for running +"multi-replica simulations"_Howto_replica.html, where each replica +runs on on one or a few processors. Note that with MPI installed on a +machine (e.g. your desktop), you can run on more (virtual) processors +than you have physical processors. + +To run multiple independent simulations from one input script, using +multiple partitions, see the "Howto multiple"_Howto_multiple.html doc +page. World- and universe-style "variables"_variable.html are useful +in this context. + +:line + +[-plog file] :link(plog) + +Specify the base name for the partition log files, so partition N +writes log information to file.N. If file is none, then no partition +log files are created. This overrides the filename specified in the +-log command-line option. This option is useful when working with +large numbers of partitions, allowing the partition log files to be +suppressed (-plog none) or placed in a sub-directory (-plog +replica_files/log.lammps) If this option is not used the log file for +partition N is log.lammps.N or whatever is specified by the -log +command-line option. + +:line + +[-pscreen file] :link(pscreen) + +Specify the base name for the partition screen file, so partition N +writes screen information to file.N. If file is none, then no +partition screen files are created. This overrides the filename +specified in the -screen command-line option. This option is useful +when working with large numbers of partitions, allowing the partition +screen files to be suppressed (-pscreen none) or placed in a +sub-directory (-pscreen replica_files/screen). If this option is not +used the screen file for partition N is screen.N or whatever is +specified by the -screen command-line option. + +:line + +[-restart restartfile {remap} datafile keyword value ...] :link(restart) + +Convert the restart file into a data file and immediately exit. This +is the same operation as if the following 2-line input script were +run: + +read_restart restartfile {remap} +write_data datafile keyword value ... :pre + +Note that the specified restartfile and datafile can have wild-card +characters ("*",%") as described by the +"read_restart"_read_restart.html and "write_data"_write_data.html +commands. But a filename such as file.* will need to be enclosed in +quotes to avoid shell expansion of the "*" character. + +Note that following restartfile, the optional flag {remap} can be +used. This has the same effect as adding it to the +"read_restart"_read_restart.html command, as explained on its doc +page. This is only useful if the reading of the restart file triggers +an error that atoms have been lost. In that case, use of the remap +flag should allow the data file to still be produced. + +Also note that following datafile, the same optional keyword/value +pairs can be listed as used by the "write_data"_write_data.html +command. + +:line + +[-reorder] :link(reorder) + +This option has 2 forms: + +-reorder nth N +-reorder custom filename :pre + +Reorder the processors in the MPI communicator used to instantiate +LAMMPS, in one of several ways. The original MPI communicator ranks +all P processors from 0 to P-1. The mapping of these ranks to +physical processors is done by MPI before LAMMPS begins. It may be +useful in some cases to alter the rank order. E.g. to insure that +cores within each node are ranked in a desired order. Or when using +the "run_style verlet/split"_run_style.html command with 2 partitions +to insure that a specific Kspace processor (in the 2nd partition) is +matched up with a specific set of processors in the 1st partition. +See the "Speed tips"_Speed_tips.html doc page for more details. + +If the keyword {nth} is used with a setting {N}, then it means every +Nth processor will be moved to the end of the ranking. This is useful +when using the "run_style verlet/split"_run_style.html command with 2 +partitions via the -partition command-line switch. The first set of +processors will be in the first partition, the 2nd set in the 2nd +partition. The -reorder command-line switch can alter this so that +the 1st N procs in the 1st partition and one proc in the 2nd partition +will be ordered consecutively, e.g. as the cores on one physical node. +This can boost performance. For example, if you use "-reorder nth 4" +and "-partition 9 3" and you are running on 12 processors, the +processors will be reordered from + +0 1 2 3 4 5 6 7 8 9 10 11 :pre + +to + +0 1 2 4 5 6 8 9 10 3 7 11 :pre + +so that the processors in each partition will be + +0 1 2 4 5 6 8 9 10 +3 7 11 :pre + +See the "processors" command for how to insure processors from each +partition could then be grouped optimally for quad-core nodes. + +If the keyword is {custom}, then a file that specifies a permutation +of the processor ranks is also specified. The format of the reorder +file is as follows. Any number of initial blank or comment lines +(starting with a "#" character) can be present. These should be +followed by P lines of the form: + +I J :pre + +where P is the number of processors LAMMPS was launched with. Note +that if running in multi-partition mode (see the -partition switch +above) P is the total number of processors in all partitions. The I +and J values describe a permutation of the P processors. Every I and +J should be values from 0 to P-1 inclusive. In the set of P I values, +every proc ID should appear exactly once. Ditto for the set of P J +values. A single I,J pairing means that the physical processor with +rank I in the original MPI communicator will have rank J in the +reordered communicator. + +Note that rank ordering can also be specified by many MPI +implementations, either by environment variables that specify how to +order physical processors, or by config files that specify what +physical processors to assign to each MPI rank. The -reorder switch +simply gives you a portable way to do this without relying on MPI +itself. See the "processors out"_processors.html command for how +to output info on the final assignment of physical processors to +the LAMMPS simulation domain. + +:line + +[-screen file] :link(screen) + +Specify a file for LAMMPS to write its screen information to. In +one-partition mode, if the switch is not used, LAMMPS writes to the +screen. If this switch is used, LAMMPS writes to the specified file +instead and you will see no screen output. In multi-partition mode, +if the switch is not used, hi-level status information is written to +the screen. Each partition also writes to a screen.N file where N is +the partition ID. If the switch is specified in multi-partition mode, +the hi-level screen dump is named "file" and each partition also +writes screen information to a file.N. For both one-partition and +multi-partition mode, if the specified file is "none", then no screen +output is performed. Option -pscreen will override the name of the +partition screen files file.N. + +:line + +[-suffix style args] :link(suffix) + +Use variants of various styles if they exist. The specified style can +be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These +refer to optional packages that LAMMPS can be built with, as described +in "Accelerate performance"_Speed.html. The "gpu" style corresponds to the +GPU package, the "intel" style to the USER-INTEL package, the "kk" +style to the KOKKOS package, the "opt" style to the OPT package, and +the "omp" style to the USER-OMP package. The hybrid style is the only +style that accepts arguments. It allows for two packages to be +specified. The first package specified is the default and will be used +if it is available. If no style is available for the first package, +the style for the second package will be used if available. For +example, "-suffix hybrid intel omp" will use styles from the +USER-INTEL package if they are installed and available, but styles for +the USER-OMP package otherwise. + +Along with the "-package" command-line switch, this is a convenient +mechanism for invoking accelerator packages and their options without +having to edit an input script. + +As an example, all of the packages provide a "pair_style +lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, +lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style +can be specified explicitly in your input script, e.g. pair_style +lj/cut/gpu. If the -suffix switch is used the specified suffix +(gpu,intel,kk,omp,opt) is automatically appended whenever your input +script command creates a new "atom"_atom_style.html, +"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or +"run"_run_style.html style. If the variant version does not exist, +the standard version is created. + +For the GPU package, using this command-line switch also invokes the +default GPU settings, as if the command "package gpu 1" were used at +the top of your input script. These settings can be changed by using +the "-package gpu" command-line switch or the "package +gpu"_package.html command in your script. + +For the USER-INTEL package, using this command-line switch also +invokes the default USER-INTEL settings, as if the command "package +intel 1" were used at the top of your input script. These settings +can be changed by using the "-package intel" command-line switch or +the "package intel"_package.html command in your script. If the +USER-OMP package is also installed, the hybrid style with "intel omp" +arguments can be used to make the omp suffix a second choice, if a +requested style is not available in the USER-INTEL package. It will +also invoke the default USER-OMP settings, as if the command "package +omp 0" were used at the top of your input script. These settings can +be changed by using the "-package omp" command-line switch or the +"package omp"_package.html command in your script. + +For the KOKKOS package, using this command-line switch also invokes +the default KOKKOS settings, as if the command "package kokkos" were +used at the top of your input script. These settings can be changed +by using the "-package kokkos" command-line switch or the "package +kokkos"_package.html command in your script. + +For the OMP package, using this command-line switch also invokes the +default OMP settings, as if the command "package omp 0" were used at +the top of your input script. These settings can be changed by using +the "-package omp" command-line switch or the "package +omp"_package.html command in your script. + +The "suffix"_suffix.html command can also be used within an input +script to set a suffix, or to turn off or back on any suffix setting +made via the command line. + +:line + +[-var name value1 value2 ...] :link(var) + +Specify a variable that will be defined for substitution purposes when +the input script is read. This switch can be used multiple times to +define multiple variables. "Name" is the variable name which can be a +single character (referenced as $x in the input script) or a full +string (referenced as $\{abc\}). An "index-style +variable"_variable.html will be created and populated with the +subsequent values, e.g. a set of filenames. Using this command-line +option is equivalent to putting the line "variable name index value1 +value2 ..." at the beginning of the input script. Defining an index +variable as a command-line argument overrides any setting for the same +index variable in the input script, since index variables cannot be +re-defined. + +See the "variable"_variable.html command for more info on defining +index and other kinds of variables and the "Commands +parse"_Commands_parse.html page for more info on using variables in +input scripts. + +NOTE: Currently, the command-line parser looks for arguments that +start with "-" to indicate new switches. Thus you cannot specify +multiple variable values if any of them start with a "-", e.g. a +negative numeric value. It is OK if the first value1 starts with a +"-", since it is automatically skipped. diff --git a/doc/src/Run_output.txt b/doc/src/Run_output.txt new file mode 100644 index 0000000000..a534ae7c7b --- /dev/null +++ b/doc/src/Run_output.txt @@ -0,0 +1,176 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Screen and logfile output :h3 + +As LAMMPS reads an input script, it prints information to both the +screen and a log file about significant actions it takes to setup a +simulation. When the simulation is ready to begin, LAMMPS performs +various initializations, and prints info about the run it is about to +perform, including the amount of memory (in MBytes per processor) that +the simulation requires. It also prints details of the initial +thermodynamic state of the system. During the run itself, +thermodynamic information is printed periodically, every few +timesteps. When the run concludes, LAMMPS prints the final +thermodynamic state and a total run time for the simulation. It also +appends statistics about the CPU time and storage requirements for the +simulation. An example set of statistics is shown here: + +Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre + +Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s +97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre + +MPI task timings breakdown: +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 +Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 +Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 +Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 +Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 +Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 +Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 +Other | | 0.007178 | | | 0.26 :pre + +Nlocal: 501 ave 508 max 490 min +Histogram: 1 0 0 0 0 0 1 1 0 1 +Nghost: 6586.25 ave 6628 max 6548 min +Histogram: 1 0 1 0 0 0 1 0 0 1 +Neighs: 177007 ave 180562 max 170212 min +Histogram: 1 0 0 0 0 0 0 1 1 1 :pre + +Total # of neighbors = 708028 +Ave neighs/atom = 353.307 +Ave special neighs/atom = 2.34032 +Neighbor list builds = 26 +Dangerous builds = 0 :pre + +:line + +The first section provides a global loop timing summary. The {loop +time} is the total wall-clock time for the simulation to run. The +{Performance} line is provided for convenience to help predict how +long it will take to run a desired physical simulation. The {CPU use} +line provides the CPU utilization per MPI task; it should be close to +100% times the number of OpenMP threads (or 1 of not using OpenMP). +Lower numbers correspond to delays due to file I/O or insufficient +thread utilization. + +:line + +The {MPI task} section gives the breakdown of the CPU run time (in +seconds) into major categories: + +{Pair} = non-bonded force computations +{Bond} = bonded interactions: bonds, angles, dihedrals, impropers +{Kspace} = long-range interactions: Ewald, PPPM, MSM +{Neigh} = neighbor list construction +{Comm} = inter-processor communication of atoms and their properties +{Output} = output of thermodynamic info and dump files +{Modify} = fixes and computes invoked by fixes +{Other} = all the remaining time :ul + +For each category, there is a breakdown of the least, average and most +amount of wall time any processor spent on this category of +computation. The "%varavg" is the percentage by which the max or min +varies from the average. This is an indication of load imbalance. A +percentage close to 0 is perfect load balance. A large percentage is +imbalance. The final "%total" column is the percentage of the total +loop time is spent in this category. + +When using the "timer full"_timer.html setting, an additional column +is added that also prints the CPU utilization in percent. In addition, +when using {timer full} and the "package omp"_package.html command are +active, a similar timing summary of time spent in threaded regions to +monitor thread utilization and load balance is provided. A new {Thread +timings} section is also added, which lists the time spent in reducing +the per-thread data elements to the storage for non-threaded +computation. These thread timings are measured for the first MPI rank +only and and thus, because the breakdown for MPI tasks can change from +MPI rank to MPI rank, this breakdown can be very different for +individual ranks. Here is an example output for this section: + +Thread timings breakdown (MPI rank 0): +Total threaded time 0.6846 / 90.6% +Section | min time | avg time | max time |%varavg| %total +--------------------------------------------------------------- +Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 +Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 +Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 +Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 +Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre + +:line + +The third section above lists the number of owned atoms (Nlocal), +ghost atoms (Nghost), and pair-wise neighbors stored per processor. +The max and min values give the spread of these values across +processors with a 10-bin histogram showing the distribution. The total +number of histogram counts is equal to the number of processors. + +:line + +The last section gives aggregate statistics (across all processors) +for pair-wise neighbors and special neighbors that LAMMPS keeps track +of (see the "special_bonds"_special_bonds.html command). The number +of times neighbor lists were rebuilt is tallied, as is the number of +potentially {dangerous} rebuilds. If atom movement triggered neighbor +list rebuilding (see the "neigh_modify"_neigh_modify.html command), +then dangerous reneighborings are those that were triggered on the +first timestep atom movement was checked for. If this count is +non-zero you may wish to reduce the delay factor to insure no force +interactions are missed by atoms moving beyond the neighbor skin +distance before a rebuild takes place. + +:line + +If an energy minimization was performed via the +"minimize"_minimize.html command, additional information is printed, +e.g. + +Minimization stats: + Stopping criterion = linesearch alpha is zero + Energy initial, next-to-last, final = + -6372.3765206 -8328.46998942 -8328.46998942 + Force two-norm initial, final = 1059.36 5.36874 + Force max component initial, final = 58.6026 1.46872 + Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 + Iterations, force evaluations = 701 1516 :pre + +The first line prints the criterion that determined minimization was +converged. The next line lists the initial and final energy, as well +as the energy on the next-to-last iteration. The next 2 lines give a +measure of the gradient of the energy (force on all atoms). The +2-norm is the "length" of this 3N-component force vector; the largest +component (x, y, or z) of force (infinity-norm) is also given. Then +information is provided about the line search and statistics on how +many iterations and force-evaluations the minimizer required. +Multiple force evaluations are typically done at each iteration to +perform a 1d line minimization in the search direction. See the +"minimize"_minimize.html doc page for more details. + +:line + +If a "kspace_style"_kspace_style.html long-range Coulombics solver +that performs FFTs was used during the run (PPPM, Ewald), then +additional information is printed, e.g. + +FFT time (% of Kspce) = 0.200313 (8.34477) +FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre + +The first line is the time spent doing 3d FFTs (several per timestep) +and the fraction it represents of the total KSpace time (listed +above). Each 3d FFT requires computation (3 sets of 1d FFTs) and +communication (transposes). The total flops performed is 5Nlog_2(N), +where N is the number of points in the 3d grid. The FFTs are timed +with and without the communication and a Gflop rate is computed. The +3d rate is with communication; the 1d rate is without (just the 1d +FFTs). Thus you can estimate what fraction of your FFT time was spent +in communication, roughly 75% in the example above. diff --git a/doc/src/Run_windows.txt b/doc/src/Run_windows.txt new file mode 100644 index 0000000000..1151a4a2bb --- /dev/null +++ b/doc/src/Run_windows.txt @@ -0,0 +1,73 @@ +"Higher level section"_Run.html - "LAMMPS WWW Site"_lws - "LAMMPS +Documentation"_ld - "LAMMPS Commands"_lc :c + +:link(lws,http://lammps.sandia.gov) +:link(ld,Manual.html) +:link(lc,Commands_all.html) + +:line + +Running LAMMPS on Windows :h3 + +To run a serial (non-MPI) executable, follow these steps: + +Get a command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input script, +(e.g. by typing: cd "Documents"). :l + +At the command prompt, type "lmp_serial -in in.file", where +in.file is the name of your LAMMPS input script. :l,ule + +Note that the serial executable includes support for multi-threading +parallelization from the styles in the USER-OMP packages. To run with +4 threads, you can type this: + +lmp_serial -in in.lj -pk omp 4 -sf omp :pre + +:line + +For the MPI executable, which allows you to run LAMMPS under Windows +in parallel, follow these steps. + +Download and install a compatible MPI library binary package: + +for 32-bit Windows: "mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi +for 64-bit Windows: "mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi :ul + +The LAMMPS Windows installer packages will automatically adjust your +path for the default location of this MPI package. After the +installation of the MPICH2 software, it needs to be integrated into +the system. For this you need to start a Command Prompt in +{Administrator Mode} (right click on the icon and select it). Change +into the MPICH2 installation directory, then into the subdirectory +[bin] and execute [smpd.exe -install]. Exit the command window. + +Get a new, regular command prompt by going to Start->Run... , +then typing "cmd". :ulb,l + +Move to the directory where you have your input file +(e.g. by typing: cd "Documents"). :l,ule + +Then type something like this: + +mpiexec -localonly 4 lmp_mpi -in in.file +mpiexec -np 4 lmp_mpi -in in.file :pre + +where in.file is the name of your LAMMPS input script. For the latter +case, you may be prompted to enter your password. + +In this mode, output may not immediately show up on the screen, so if +your input script takes a long time to execute, you may need to be +patient before the output shows up. + +The parallel executable can also run on a single processor by typing +something like this: + +lmp_mpi -in in.lj :pre + +Note that the parallel executable also includes OpenMP +multi-threading, which can be combined with MPI using something like: + +mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre diff --git a/doc/src/Section_start.txt b/doc/src/Section_start.txt deleted file mode 100644 index 19a798d5df..0000000000 --- a/doc/src/Section_start.txt +++ /dev/null @@ -1,1823 +0,0 @@ -"Previous Section"_Intro.html - "LAMMPS WWW Site"_lws - -"LAMMPS Documentation"_ld - "LAMMPS Commands"_lc - "Next -Section"_Commands.html :c - -:link(lws,http://lammps.sandia.gov) -:link(ld,Manual.html) -:link(lc,Commands_all.html) - -:line - -2. Getting Started :h2 - -This section describes how to build and run LAMMPS, for both new and -experienced users. - -2.1 "What's in the LAMMPS distribution"_#start_1 -2.2 "Making LAMMPS"_#start_2 -2.3 "Making LAMMPS with optional packages"_#start_3 -2.4 "Building LAMMPS as a library"_#start_4 -2.5 "Running LAMMPS"_#start_5 -2.6 "Command-line options"_#start_6 -2.7 "Screen output"_#start_7 -2.8 "Tips for users of previous versions"_#start_8 :all(b) - -:line - -2.1 What's in the LAMMPS distribution :h3,link(start_1) - -When you download a LAMMPS tarball you will need to unzip and untar -the downloaded file with the following commands, after placing the -tarball in an appropriate directory. - -tar -xzvf lammps*.tar.gz :pre - -This will create a LAMMPS directory containing two files and several -sub-directories: - -README: text file -LICENSE: the GNU General Public License (GPL) -bench: benchmark problems -doc: documentation -examples: simple test problems -potentials: embedded atom method (EAM) potential files -src: source files -tools: pre- and post-processing tools :tb(s=:) - -Note that the "download page"_download also has links to download -pre-build Windows installers, as well as pre-built packages for -several widely used Linux distributions. It also has instructions -for how to download/install LAMMPS for Macs (via Homebrew), and to -download and update LAMMPS from SVN and Git repositories, which gives -you access to the up-to-date sources that are used by the LAMMPS -core developers. - -:link(download,http://lammps.sandia.gov/download.html) - -The Windows and Linux packages for serial or parallel include -only selected packages and bug-fixes/upgrades listed on "this -page"_http://lammps.sandia.gov/bug.html up to a certain date, as -stated on the download page. If you want an executable with -non-included packages or that is more current, then you'll need to -build LAMMPS yourself, as discussed in the next section. - -Skip to the "Running LAMMPS"_#start_6 sections for info on how to -launch a LAMMPS Windows executable on a Windows box. - -:line - -2.2 Making LAMMPS :h3,link(start_2) - -This section has the following sub-sections: - -2.2.1 "Read this first"_#start_2_1 -2.2.1 "Steps to build a LAMMPS executable"_#start_2_2 -2.2.3 "Common errors that can occur when making LAMMPS"_#start_2_3 -2.2.4 "Additional build tips"_#start_2_4 -2.2.5 "Building for a Mac"_#start_2_5 -2.2.6 "Building for Windows"_#start_2_6 :all(b) - -:line - -Read this first :h4,link(start_2_1) - -If you want to avoid building LAMMPS yourself, read the preceding -section about options available for downloading and installing -executables. Details are discussed on the "download"_download page. - -Building LAMMPS can be simple or not-so-simple. If all you need are -the default packages installed in LAMMPS, and MPI is already installed -on your machine, or you just want to run LAMMPS in serial, then you -can typically use the Makefile.mpi or Makefile.serial files in -src/MAKE by typing one of these lines (from the src dir): - -make mpi -make serial :pre - -Note that on a facility supercomputer, there are often "modules" -loaded in your environment that provide the compilers and MPI you -should use. In this case, the "mpicxx" compile/link command in -Makefile.mpi should simply work by accessing those modules. - -It may be the case that one of the other Makefile.machine files in the -src/MAKE sub-directories is a better match to your system (type "make" -to see a list), you can use it as-is by typing (for example): - -make stampede :pre - -If any of these builds (with an existing Makefile.machine) works on -your system, then you're done! - -If you need to install an optional package with a LAMMPS command you -want to use, and the package does not depend on an extra library, you -can simply type - -make name :pre - -before invoking (or re-invoking) the above steps. "Name" is the -lower-case name of the package, e.g. replica or user-misc. - -If you want to do one of the following: - -use a LAMMPS command that requires an extra library (e.g. "dump -image"_dump_image.html) build with a package that requires an extra -library build with an accelerator package that requires special -compiler/linker settings run on a machine that has its own compilers, -settings, or libraries :ul - -then building LAMMPS is more complicated. You may need to find where -extra libraries exist on your machine or install them if they don't. -You may need to build extra libraries that are included in the LAMMPS -distribution, before building LAMMPS itself. You may need to edit a -Makefile.machine file to make it compatible with your system. - -Please read the following sections carefully. If you are not -comfortable with makefiles, or building codes on a Unix platform, or -running an MPI job on your machine, please find a local expert to help -you. Many compilation, linking, and run problems users experience are -often not LAMMPS issues - they are peculiar to the user's system, -compilers, libraries, etc. Such questions are better answered by a -local expert. - -If you have a build problem that you are convinced is a LAMMPS issue -(e.g. the compiler complains about a line of LAMMPS source code), then -please post the issue to the "LAMMPS mail -list"_http://lammps.sandia.gov/mail.html. - -If you succeed in building LAMMPS on a new kind of machine, for which -there isn't a similar machine Makefile included in the -src/MAKE/MACHINES directory, then send it to the developers and we can -include it in the LAMMPS distribution. - -:line - -Steps to build a LAMMPS executable :h4,link(start_2_2) - -Step 0 :h5 - -The src directory contains the C++ source and header files for LAMMPS. -It also contains a top-level Makefile and a MAKE sub-directory with -low-level Makefile.* files for many systems and machines. See the -src/MAKE/README file for a quick overview of what files are available -and what sub-directories they are in. - -The src/MAKE dir has a few files that should work as-is on many -platforms. The src/MAKE/OPTIONS dir has more that invoke additional -compiler, MPI, and other setting options commonly used by LAMMPS, to -illustrate their syntax. The src/MAKE/MACHINES dir has many more that -have been tweaked or optimized for specific machines. These files are -all good starting points if you find you need to change them for your -machine. Put any file you edit into the src/MAKE/MINE directory and -it will be never be touched by any LAMMPS updates. - ->From within the src directory, type "make" or "gmake". You should see -a list of available choices from src/MAKE and all of its -sub-directories. If one of those has the options you want or is the -machine you want, you can type a command like: - -make mpi :pre -or - -make serial :pre -or - -gmake mac :pre - -Note that the corresponding Makefile.machine can exist in src/MAKE or -any of its sub-directories. If a file with the same name appears in -multiple places (not a good idea), the order they are used is as -follows: src/MAKE/MINE, src/MAKE, src/MAKE/OPTIONS, src/MAKE/MACHINES. -This gives preference to a file you have created/edited and put in -src/MAKE/MINE. - -Note that on a multi-processor or multi-core platform you can launch a -parallel make, by using the "-j" switch with the make command, which -will build LAMMPS more quickly. - -If you get no errors and an executable like [lmp_mpi] or [lmp_serial] -or [lmp_mac] is produced, then you're done; it's your lucky day. - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below. - -Step 1 :h5 - -If Step 0 did not work, you will need to create a low-level Makefile -for your machine, like Makefile.foo. You should make a copy of an -existing Makefile.* in src/MAKE or one of its sub-directories as a -starting point. The only portions of the file you need to edit are -the first line, the "compiler/linker settings" section, and the -"LAMMPS-specific settings" section. When it works, put the edited -file in src/MAKE/MINE and it will not be altered by any future LAMMPS -updates. - -Step 2 :h5 - -Change the first line of Makefile.foo to list the word "foo" after the -"#", and whatever other options it will set. This is the line you -will see if you just type "make". - -Step 3 :h5 - -The "compiler/linker settings" section lists compiler and linker -settings for your C++ compiler, including optimization flags. You can -use g++, the open-source GNU compiler, which is available on all Unix -systems. You can also use mpicxx which will typically be available if -MPI is installed on your system, though you should check which actual -compiler it wraps. Vendor compilers often produce faster code. On -boxes with Intel CPUs, we suggest using the Intel icc compiler, which -can be downloaded from "Intel's compiler site"_intel. - -:link(intel,http://www.intel.com/software/products/noncom) - -If building a C++ code on your machine requires additional libraries, -then you should list them as part of the LIB variable. You should -not need to do this if you use mpicxx. - -The DEPFLAGS setting is what triggers the C++ compiler to create a -dependency list for a source file. This speeds re-compilation when -source (*.cpp) or header (*.h) files are edited. Some compilers do -not support dependency file creation, or may use a different switch -than -D. GNU g++ and Intel icc works with -D. If your compiler can't -create dependency files, then you'll need to create a Makefile.foo -patterned after Makefile.storm, which uses different rules that do not -involve dependency files. Note that when you build LAMMPS for the -first time on a new platform, a long list of *.d files will be printed -out rapidly. This is not an error; it is the Makefile doing its -normal creation of dependencies. - -Step 4 :h5 - -The "system-specific settings" section has several parts. Note that -if you change any -D setting in this section, you should do a full -re-compile, after typing "make clean" (which will describe different -clean options). - -The LMP_INC variable is used to include options that turn on ifdefs -within the LAMMPS code. The options that are currently recognized are: - --DLAMMPS_GZIP --DLAMMPS_JPEG --DLAMMPS_PNG --DLAMMPS_FFMPEG --DLAMMPS_MEMALIGN --DLAMMPS_SMALLBIG --DLAMMPS_BIGBIG --DLAMMPS_SMALLSMALL --DLAMMPS_LONGLONG_TO_LONG --DLAMMPS_EXCEPTIONS --DPACK_ARRAY --DPACK_POINTER --DPACK_MEMCPY :ul - -The read_data and dump commands will read/write gzipped files if you -compile with -DLAMMPS_GZIP. It requires that your machine supports -the "popen()" function in the standard runtime library and that a gzip -executable can be found by LAMMPS during a run. - -NOTE: on some clusters with high-speed networks, using the fork() -library calls (required by popen()) can interfere with the fast -communication library and lead to simulations using compressed output -or input to hang or crash. For selected operations, compressed file -I/O is also available using a compression library instead, which are -provided in the COMPRESS package. From more details about compiling -LAMMPS with packages, please see below. - -If you use -DLAMMPS_JPEG, the "dump image"_dump_image.html command -will be able to write out JPEG image files. For JPEG files, you must -also link LAMMPS with a JPEG library, as described below. If you use --DLAMMPS_PNG, the "dump image"_dump.html command will be able to write -out PNG image files. For PNG files, you must also link LAMMPS with a -PNG library, as described below. If neither of those two defines are -used, LAMMPS will only be able to write out uncompressed PPM image -files. - -If you use -DLAMMPS_FFMPEG, the "dump movie"_dump_image.html command -will be available to support on-the-fly generation of rendered movies -the need to store intermediate image files. It requires that your -machines supports the "popen" function in the standard runtime library -and that an FFmpeg executable can be found by LAMMPS during the run. - -NOTE: Similar to the note above, this option can conflict with -high-speed networks, because it uses popen(). - -Using -DLAMMPS_MEMALIGN= enables the use of the -posix_memalign() call instead of malloc() when large chunks or memory -are allocated by LAMMPS. This can help to make more efficient use of -vector instructions of modern CPUS, since dynamically allocated memory -has to be aligned on larger than default byte boundaries (e.g. 16 -bytes instead of 8 bytes on x86 type platforms) for optimal -performance. - -Use at most one of the -DLAMMPS_SMALLBIG, -DLAMMPS_BIGBIG, --DLAMMPS_SMALLSMALL settings. The default is -DLAMMPS_SMALLBIG. These -settings refer to use of 4-byte (small) vs 8-byte (big) integers -within LAMMPS, as specified in src/lmptype.h. The only reason to use -the BIGBIG setting is to enable simulation of huge molecular systems -(which store bond topology info) with more than 2 billion atoms, or to -track the image flags of moving atoms that wrap around a periodic box -more than 512 times. Normally, the only reason to use SMALLSMALL is -if your machine does not support 64-bit integers, though you can use -SMALLSMALL setting if you are running in serial or on a desktop -machine or small cluster where you will never run large systems or for -long time (more than 2 billion atoms, more than 2 billion timesteps). -See the "Additional build tips"_#start_2_4 section below for more -details on these settings. - -Note that the USER-ATC package is not currently compatible with --DLAMMPS_BIGBIG. Also the GPU package requires the lib/gpu library to -be compiled with the same setting, or the link will fail. - -The -DLAMMPS_LONGLONG_TO_LONG setting may be needed if your system or -MPI version does not recognize "long long" data types. In this case a -"long" data type is likely already 64-bits, in which case this setting -will convert to that data type. - -The -DLAMMPS_EXCEPTIONS setting can be used to activate alternative -versions of error handling inside of LAMMPS. This is useful when -external codes drive LAMMPS as a library. Using this option, LAMMPS -errors do not kill the caller. Instead, the call stack is unwound and -control returns to the caller. The library interface provides the -lammps_has_error() and lammps_get_last_error_message() functions to -detect and find out more about a LAMMPS error. - -Using one of the -DPACK_ARRAY, -DPACK_POINTER, and -DPACK_MEMCPY -options can make for faster parallel FFTs (in the PPPM solver) on some -platforms. The -DPACK_ARRAY setting is the default. See the -"kspace_style"_kspace_style.html command for info about PPPM. See -Step 6 below for info about building LAMMPS with an FFT library. - -Step 5 :h5 - -The 3 MPI variables are used to specify an MPI library to build LAMMPS -with. Note that you do not need to set these if you use the MPI -compiler mpicxx for your CC and LINK setting in the section above. -The MPI wrapper knows where to find the needed files. - -If you want LAMMPS to run in parallel, you must have an MPI library -installed on your platform. If MPI is installed on your system in the -usual place (under /usr/local), you also may not need to specify these -3 variables, assuming /usr/local is in your path. On some large -parallel machines which use "modules" for their compile/link -environments, you may simply need to include the correct module in -your build environment, before building LAMMPS. Or the parallel -machine may have a vendor-provided MPI which the compiler has no -trouble finding. - -Failing this, these 3 variables can be used to specify where the mpi.h -file (MPI_INC) and the MPI library file (MPI_PATH) are found and the -name of the library file (MPI_LIB). - -If you are installing MPI yourself, we recommend Argonne's MPICH2 -or OpenMPI. MPICH can be downloaded from the "Argonne MPI -site"_http://www.mcs.anl.gov/research/projects/mpich2/. OpenMPI can -be downloaded from the "OpenMPI site"_http://www.open-mpi.org. -Other MPI packages should also work. If you are running on a big -parallel platform, your system people or the vendor should have -already installed a version of MPI, which is likely to be faster -than a self-installed MPICH or OpenMPI, so find out how to build -and link with it. If you use MPICH or OpenMPI, you will have to -configure and build it for your platform. The MPI configure script -should have compiler options to enable you to use the same compiler -you are using for the LAMMPS build, which can avoid problems that can -arise when linking LAMMPS to the MPI library. - -If you just want to run LAMMPS on a single processor, you can use the -dummy MPI library provided in src/STUBS, since you don't need a true -MPI library installed on your system. See src/MAKE/Makefile.serial -for how to specify the 3 MPI variables in this case. You will also -need to build the STUBS library for your platform before making LAMMPS -itself. Note that if you are building with src/MAKE/Makefile.serial, -e.g. by typing "make serial", then the STUBS library is built for you. - -To build the STUBS library from the src directory, type "make -mpi-stubs", or from the src/STUBS dir, type "make". This should -create a libmpi_stubs.a file suitable for linking to LAMMPS. If the -build fails, you will need to edit the STUBS/Makefile for your -platform. - -The file STUBS/mpi.c provides a CPU timer function called MPI_Wtime() -that calls gettimeofday() . If your system doesn't support -gettimeofday() , you'll need to insert code to call another timer. -Note that the ANSI-standard function clock() rolls over after an hour -or so, and is therefore insufficient for timing long LAMMPS -simulations. - -Step 6 :h5 - -The 3 FFT variables allow you to specify an FFT library which LAMMPS -uses (for performing 1d FFTs) when running the particle-particle -particle-mesh (PPPM) option for long-range Coulombics via the -"kspace_style"_kspace_style.html command. - -LAMMPS supports common open-source or vendor-supplied FFT libraries -for this purpose. If you leave these 3 variables blank, LAMMPS will -use the open-source "KISS FFT library"_http://kissfft.sf.net, which is -included in the LAMMPS distribution. This library is portable to all -platforms and for typical LAMMPS simulations is almost as fast as FFTW -or vendor optimized libraries. If you are not including the KSPACE -package in your build, you can also leave the 3 variables blank. - -Otherwise, select which kinds of FFTs to use as part of the FFT_INC -setting by a switch of the form -DFFT_XXX. Recommended values for XXX -are: MKL or FFTW3. FFTW2 and NONE are supported as legacy options. -Selecting -DFFT_FFTW will use the FFTW3 library and -DFFT_NONE will -use the KISS library described above. - -You may also need to set the FFT_INC, FFT_PATH, and FFT_LIB variables, -so the compiler and linker can find the needed FFT header and library -files. Note that on some large parallel machines which use "modules" -for their compile/link environments, you may simply need to include -the correct module in your build environment. Or the parallel machine -may have a vendor-provided FFT library which the compiler has no -trouble finding. See the src/MAKE/OPTIONS/Makefile.fftw file for an -example of how to specify these variables to use the FFTW3 library. - -FFTW is fast, portable library that should also work on any platform -and typically be faster than KISS FFT. You can download it from -"www.fftw.org"_http://www.fftw.org. Both the legacy version 2.1.X and -the newer 3.X versions are supported as -DFFT_FFTW2 or -DFFT_FFTW3. -Building FFTW for your box should be as simple as ./configure; make; -make install. The install command typically requires root privileges -(e.g. invoke it via sudo), unless you specify a local directory with -the "--prefix" option of configure. Type "./configure --help" to see -various options. - -If you wish to have FFTW support for single-precision FFTs (see below -about -DFFT_SINGLE) in addition to the default double-precision FFTs, -you will need to build FFTW a second time for single-precision. For -FFTW3, do this via: - -make clean -./configure --enable-single; make; make install :pre - -which should produce the additional library libfftw3f.a. - -For FFTW2, do this: - -make clean -./configure --enable-float --enable-type-prefix; make; make install :pre - -which should produce the additional library libsfftw.a and additional -include file sfttw.a. Note that on some platforms FFTW2 has been -pre-installed for both single- and double-precision, and may already -have these files as well as libdfftw.a and dfftw.h for double -precision. - -The FFT_INC variable also allows for a -DFFT_SINGLE setting that will -use single-precision FFTs with PPPM, which can speed-up long-range -calculations, particularly in parallel or on GPUs. Fourier transform -and related PPPM operations are somewhat insensitive to floating point -truncation errors and thus do not always need to be performed in -double precision. Using the -DFFT_SINGLE setting trades off a little -accuracy for reduced memory use and parallel communication costs for -transposing 3d FFT data. Note that single precision FFTs have only -been tested with the FFTW3, FFTW2, MKL, and KISS FFT options. - -When using -DFFT_SINGLE with FFTW3 or FFTW2, you need to build FFTW -with support for single-precision, as explained above. For FFTW3 you -also need to include -lfftw3f with the FFT_LIB setting, in addition to --lfftw3. For FFTW2, you also need to specify -DFFT_SIZE with the -FFT_INC setting and -lsfftw with the FFT_LIB setting (in place of --lfftw). Similarly, if FFTW2 has been pre-installed with an explicit -double-precision library (libdfftw.a and not the default libfftw.a), -then you can specify -DFFT_SIZE (and not -DFFT_SINGLE), and specify --ldfftw to use double-precision FFTs. - -Step 7 :h5 - -The 3 JPG variables allow you to specify a JPEG and/or PNG library -which LAMMPS uses when writing out JPEG or PNG files via the "dump -image"_dump_image.html command. These can be left blank if you do not -use the -DLAMMPS_JPEG or -DLAMMPS_PNG switches discussed above in Step -4, since in that case JPEG/PNG output will be disabled. - -A standard JPEG library usually goes by the name libjpeg.a or -libjpeg.so and has an associated header file jpeglib.h. Whichever -JPEG library you have on your platform, you'll need to set the -appropriate JPG_INC, JPG_PATH, and JPG_LIB variables, so that the -compiler and linker can find it. - -A standard PNG library usually goes by the name libpng.a or libpng.so -and has an associated header file png.h. Whichever PNG library you -have on your platform, you'll need to set the appropriate JPG_INC, -JPG_PATH, and JPG_LIB variables, so that the compiler and linker can -find it. - -As before, if these header and library files are in the usual place on -your machine, you may not need to set these variables. - -Step 8 :h5 - -Note that by default only a few of LAMMPS optional packages are -installed. To build LAMMPS with optional packages, see "this -section"_#start_3 below, before proceeding to Step 9. - -Step 9 :h5 - -That's it. Once you have a correct Makefile.foo, and you have -pre-built any other needed libraries (e.g. MPI, FFT, etc) all you need -to do from the src directory is type something like this: - -make foo -make -j N foo -gmake foo -gmake -j N foo :pre - -The -j or -j N switches perform a parallel build which can be much -faster, depending on how many cores your compilation machine has. N -is the number of cores the build runs on. - -You should get the executable lmp_foo when the build is complete. - -:line - -Errors that can occur when making LAMMPS :h4 :link(start_2_3) - -If an error occurs when building LAMMPS, the compiler or linker will -state very explicitly what the problem is. The error message should -give you a hint as to which of the steps above has failed, and what -you need to do in order to fix it. Building a code with a Makefile is -a very logical process. The compiler and linker need to find the -appropriate files and those files need to be compatible with LAMMPS -settings and source files. When a make fails, there is usually a very -simple reason, which you or a local expert will need to fix. - -Here are two non-obvious errors that can occur: - -(1) If the make command breaks immediately with errors that indicate -it can't find files with a "*" in their names, this can be because -your machine's native make doesn't support wildcard expansion in a -makefile. Try gmake instead of make. If that doesn't work, try using -a -f switch with your make command to use a pre-generated -Makefile.list which explicitly lists all the needed files, e.g. - -make makelist -make -f Makefile.list linux -gmake -f Makefile.list mac :pre - -The first "make" command will create a current Makefile.list with all -the file names in your src dir. The 2nd "make" command (make or -gmake) will use it to build LAMMPS. Note that you should -include/exclude any desired optional packages before using the "make -makelist" command. - -(2) If you get an error that says something like 'identifier "atoll" -is undefined', then your machine does not support "long long" -integers. Try using the -DLAMMPS_LONGLONG_TO_LONG setting described -above in Step 4. - -:line - -Additional build tips :h4,link(start_2_4) - -Building LAMMPS for multiple platforms. :h5 - -You can make LAMMPS for multiple platforms from the same src -directory. Each target creates its own object sub-directory called -Obj_target where it stores the system-specific *.o files. - -Cleaning up. :h5 - -Typing "make clean-all" or "make clean-machine" will delete *.o object -files created when LAMMPS is built, for either all builds or for a -particular machine. - -Changing the LAMMPS size limits via -DLAMMPS_SMALLBIG or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL :h5 - -As explained above, any of these 3 settings can be specified on the -LMP_INC line in your low-level src/MAKE/Makefile.foo. - -The default is -DLAMMPS_SMALLBIG which allows for systems with up to -2^63 atoms and 2^63 timesteps (about 9e18). The atom limit is for -atomic systems which do not store bond topology info and thus do not -require atom IDs. If you use atom IDs for atomic systems (which is -the default) or if you use a molecular model, which stores bond -topology info and thus requires atom IDs, the limit is 2^31 atoms -(about 2 billion). This is because the IDs are stored in 32-bit -integers. - -Likewise, with this setting, the 3 image flags for each atom (see the -"dump"_dump.html doc page for a discussion) are stored in a 32-bit -integer, which means the atoms can only wrap around a periodic box (in -each dimension) at most 512 times. If atoms move through the periodic -box more than this many times, the image flags will "roll over", -e.g. from 511 to -512, which can cause diagnostics like the -mean-squared displacement, as calculated by the "compute -msd"_compute_msd.html command, to be faulty. - -To allow for larger atomic systems with atom IDs or larger molecular -systems or larger image flags, compile with -DLAMMPS_BIGBIG. This -stores atom IDs and image flags in 64-bit integers. This enables -atomic or molecular systems with atom IDS of up to 2^63 atoms (about -9e18). And image flags will not "roll over" until they reach 2^20 = -1048576. - -If your system does not support 8-byte integers, you will need to -compile with the -DLAMMPS_SMALLSMALL setting. This will restrict the -total number of atoms (for atomic or molecular systems) and timesteps -to 2^31 (about 2 billion). Image flags will roll over at 2^9 = 512. - -Note that in src/lmptype.h there are definitions of all these data -types as well as the MPI data types associated with them. The MPI -types need to be consistent with the associated C data types, or else -LAMMPS will generate a run-time error. As far as we know, the -settings defined in src/lmptype.h are portable and work on every -current system. - -In all cases, the size of problem that can be run on a per-processor -basis is limited by 4-byte integer storage to 2^31 atoms per processor -(about 2 billion). This should not normally be a limitation since such -a problem would have a huge per-processor memory footprint due to -neighbor lists and would run very slowly in terms of CPU secs/timestep. - -:line - -Building for a Mac :h4,link(start_2_5) - -OS X is a derivative of BSD Unix, so it should just work. See the -src/MAKE/MACHINES/Makefile.mac and Makefile.mac_mpi files. - -:line - -Building for Windows :h4,link(start_2_6) - -If you want to build a Windows version of LAMMPS, you can build it -yourself, but it may require some effort. LAMMPS expects a Unix-like -build environment for the default build procedure. This can be done -using either Cygwin or MinGW; the latter also exists as a ready-to-use -Linux-to-Windows cross-compiler in several Linux distributions. In -these cases, you can do the installation after installing several -unix-style commands like make, grep, sed and bash with some shell -utilities. - -For Cygwin and the MinGW cross-compilers, suitable makefiles are -provided in src/MAKE/MACHINES. When using other compilers, like -Visual C++ or Intel compilers for Windows, you may have to implement -your own build system. Due to differences between the Windows OS -and Windows system libraries to Unix-like environments like Linux -or MacOS, when compiling for Windows a few adjustments may be needed: - -Do [not] set the -DLAMMPS_MEMALIGN define (see LMP_INC makefile variable) -Add -lwsock32 -lpsapi to the linker flags (see LIB makefile variable) -Try adding -static-libgcc or -static or both to the linker flags when your LAMMPS executable complains about missing .dll files :ul - -Since none of the current LAMMPS core developers has significant -experience building executables on Windows, we are happy to distribute -contributed instructions and modifications to improve the situation, -but we cannot provide support for those. - -With the so-called "Anniversary Update" to Windows 10, there is a -Ubuntu Linux subsystem available for Windows, that can be installed -and then used to compile/install LAMMPS as if you are running on a -Ubuntu Linux system instead of Windows. - -As an alternative, you can download pre-compiled installer packages from -"packages.lammps.org/windows.html"_http://packages.lammps.org/windows.html. -These executables are built with most optional packages included and the -download includes documentation, potential files, some tools and many -examples, but no source code. - -:line - -2.3 Making LAMMPS with optional packages :h3,link(start_3) - -This section has the following sub-sections: - -2.3.1 "Package basics"_#start_3_1 -2.3.2 "Including/excluding packages"_#start_3_2 -2.3.3 "Packages that require extra libraries"_#start_3_3 :all(b) - -:line - -Package basics: :h4,link(start_3_1) - -The source code for LAMMPS is structured as a set of core files which -are always included, plus optional packages. Packages are groups of -files that enable a specific set of features. For example, force -fields for molecular systems or granular systems are in packages. - -The "Packages"_Packages.html doc pages has details about all the -packages, which come in two flavors: [standard] and [user] -packages. It also has specific instructions for building LAMMPS with -any package which requires an extra library. General instructions are -below. - -You can see the list of all packages by typing "make package" from -within the src directory of the LAMMPS distribution. It will also -list various make commands that can be used to manage packages. - -If you use a command in a LAMMPS input script that is part of a -package, you must have built LAMMPS with that package, else you will -get an error that the style is invalid or the command is unknown. -Every command's doc page specifies if it is part of a package. You can -type - -lmp_machine -h :pre - -to run your executable with the optional "-h command-line -switch"_#start_6 for "help", which will list the styles and commands -known to your executable, and immediately exit. - -:line - -Including/excluding packages :h4,link(start_3_2) - -To use (or not use) a package you must install it (or un-install it) -before building LAMMPS. From the src directory, this is as simple as: - -make yes-colloid -make mpi :pre - -or - -make no-user-omp -make mpi :pre - -NOTE: You should NOT install/un-install packages and build LAMMPS in a -single make command using multiple targets, e.g. make yes-colloid mpi. -This is because the make procedure creates a list of source files that -will be out-of-date for the build if the package configuration changes -within the same command. - -Any package can be installed or not in a LAMMPS build, independent of -all other packages. However, some packages include files derived from -files in other packages. LAMMPS checks for this and does the right -thing. I.e. individual files are only included if their dependencies -are already included. Likewise, if a package is excluded, other files -dependent on that package are also excluded. - -NOTE: The one exception is that we do not recommend building with both -the KOKKOS package installed and any of the other acceleration -packages (GPU, OPT, USER-INTEL, USER-OMP) also installed. This is -because of how Kokkos sometimes builds using a wrapper compiler which -can make it difficult to invoke all the compile/link flags correctly -for both Kokkos and non-Kokkos files. - -If you will never run simulations that use the features in a -particular packages, there is no reason to include it in your build. -For some packages, this will keep you from having to build extra -libraries, and will also produce a smaller executable which may run a -bit faster. - -When you download a LAMMPS tarball, three packages are pre-installed -in the src directory -- KSPACE, MANYBODY, MOLECULE -- because they are -so commonly used. When you download LAMMPS source files from the SVN -or Git repositories, no packages are pre-installed. - -Packages are installed or un-installed by typing - -make yes-name -make no-name :pre - -where "name" is the name of the package in lower-case, e.g. name = -kspace for the KSPACE package or name = user-atc for the USER-ATC -package. You can also type any of these commands: - -make yes-all | install all packages -make no-all | un-install all packages -make yes-standard or make yes-std | install standard packages -make no-standard or make no-std| un-install standard packages -make yes-user | install user packages -make no-user | un-install user packages -make yes-lib | install packages that require extra libraries -make no-lib | un-install packages that require extra libraries -make yes-ext | install packages that require external libraries -make no-ext | un-install packages that require external libraries :tb(s=|) - -which install/un-install various sets of packages. Typing "make -package" will list all the these commands. - -NOTE: Installing or un-installing a package works by simply moving -files back and forth between the main src directory and -sub-directories with the package name (e.g. src/KSPACE, src/USER-ATC), -so that the files are included or excluded when LAMMPS is built. -After you have installed or un-installed a package, you must re-build -LAMMPS for the action to take effect. - -The following make commands help manage files that exist in both the -src directory and in package sub-directories. You do not normally -need to use these commands unless you are editing LAMMPS files or have -downloaded a patch from the LAMMPS web site. - -Typing "make package-status" or "make ps" will show which packages are -currently installed. For those that are installed, it will list any -files that are different in the src directory and package -sub-directory. - -Typing "make package-installed" or "make pi" will list which packages are -currently installed, without listing the status of packages that are not -installed. - -Typing "make package-update" or "make pu" will overwrite src files -with files from the package sub-directories if the package is -installed. It should be used after a patch has been applied, since -patches only update the files in the package sub-directory, but not -the src files. - -Typing "make package-overwrite" will overwrite files in the package -sub-directories with src files. - -Typing "make package-diff" lists all differences between these files. - -Again, just type "make package" to see all of the package-related make -options. - -:line - -Packages that require extra libraries :h4,link(start_3_3) - -A few of the standard and user packages require extra libraries. See -the "Packages"_Packages.html doc pages for two tables of packages -which indicate which ones require libraries. For each such package, -the Section 4 doc page gives details on how to build the extra -library, including how to download it if necessary. The basic ideas -are summarized here. - -[System libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with a "sys" in the last column -link to system libraries that typically already exist on your machine. -E.g. the python package links to a system Python library. If your -machine does not have the required library, you will have to download -and install it on your machine, in either the system or user space. - -[Internal libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "int" in the last column -link to internal libraries whose source code is included with LAMMPS, -in the lib/name directory where name is the package name. You must -first build the library in that directory before building LAMMPS with -that package installed. E.g. the gpu package links to a library you -build in the lib/gpu dir. You can often do the build in one step by -typing "make lib-name args=..." from the src dir, with appropriate -arguments. You can leave off the args to see a help message. See the -"Packages details"_Packages_details.html doc page for details for each -package. - -[External libraries:] - -Packages in the standard and user tables of the -"Packages"_Packages.html doc pages with an "ext" in the last column -link to external libraries whose source code is not included with -LAMMPS. You must first download and install the library before -building LAMMPS with that package installed. E.g. the voronoi package -links to the freely available "Voro++ library"_voro_home2. You can -often do the download/build in one step by typing "make lib-name -args=..." from the src dir, with appropriate arguments. You can leave -off the args to see a help message. See the "Packages -details"_Packages_details.html doc page for details for each package. - -:link(voro_home2,http://math.lbl.gov/voro++) - -[Possible errors:] - -There are various common errors which can occur when building extra -libraries or when building LAMMPS with packages that require the extra -libraries. - -If you cannot build the extra library itself successfully, you may -need to edit or create an appropriate Makefile for your machine, e.g. -with appropriate compiler or system settings. Provided makefiles are -typically in the lib/name directory. E.g. see the Makefile.* files in -lib/gpu. - -The LAMMPS build often uses settings in a lib/name/Makefile.lammps -file which either exists in the LAMMPS distribution or is created or -copied from a lib/name/Makefile.lammps.* file when the library is -built. If those settings are not correct for your machine you will -need to edit or create an appropriate Makefile.lammps file. - -Package-specific details for these steps are given on the "Packages -details"_Packages_details.html doc page and in README files in the -lib/name directories. - -[Compiler options needed for accelerator packages:] - -Several packages contain code that is optimized for specific hardware, -e.g. CPU, KNL, or GPU. These are the OPT, GPU, KOKKOS, USER-INTEL, -and USER-OMP packages. Compiling and linking the source files in -these accelerator packages for optimal performance requires specific -settings in the Makefile.machine file you use. - -A summary of the Makefile.machine settings needed for each of these -packages is given on the "Packages"_Packages.html doc pages. More -info is given on the doc pages that describe each package in detail: - -"USER-INTEL package"_Speed_intel.html -"GPU package"_Speed_gpu.html -"KOKKOS package"_Speed_kokkos.html -"USER-OMP package"_Speed_omp.html -"OPT package"_Speed_opt.html :all(b) - -You can also use or examine the following machine Makefiles in -src/MAKE/OPTIONS, which include the settings. Note that the -USER-INTEL and KOKKOS packages can use settings that build LAMMPS for -different hardware. The USER-INTEL package can be compiled for Intel -CPUs and KNLs; the KOKKOS package builds for CPUs (OpenMP), GPUs -(CUDA), and Intel KNLs. - -Makefile.intel_cpu -Makefile.intel_phi -Makefile.kokkos_omp -Makefile.kokkos_cuda_mpi -Makefile.kokkos_phi -Makefile.omp -Makefile.opt :ul - -:line - -2.4 Building LAMMPS as a library :h3,link(start_4) - -LAMMPS can be built as either a static or shared library, which can -then be called from another application or a scripting language. See -the "Howto couple"_Howto_couple.html doc page for more info on -coupling LAMMPS to other codes. See the "Python"_Python.html doc page -for more info on wrapping and running LAMMPS from Python. - -Static library :h4 - -To build LAMMPS as a static library (*.a file on Linux), type - -make foo mode=lib :pre - -where foo is the machine name. This kind of library is typically used -to statically link a driver application to LAMMPS, so that you can -insure all dependencies are satisfied at compile time. This will use -the ARCHIVE and ARFLAGS settings in src/MAKE/Makefile.foo. The build -will create the file liblammps_foo.a which another application can -link to. It will also create a soft link liblammps.a, which will -point to the most recently built static library. - -Shared library :h4 - -To build LAMMPS as a shared library (*.so file on Linux), which can be -dynamically loaded, e.g. from Python, type - -make foo mode=shlib :pre - -where foo is the machine name. This kind of library is required when -wrapping LAMMPS with Python; see the "Python"_Python.html doc page for -details. This will use the SHFLAGS and SHLIBFLAGS settings in -src/MAKE/Makefile.foo and perform the build in the directory -Obj_shared_foo. This is so that each file can be compiled with the --fPIC flag which is required for inclusion in a shared library. The -build will create the file liblammps_foo.so which another application -can link to dynamically. It will also create a soft link -liblammps.so, which will point to the most recently built shared -library. This is the file the Python wrapper loads by default. - -Note that for a shared library to be usable by a calling program, all -the auxiliary libraries it depends on must also exist as shared -libraries. This will be the case for libraries included with LAMMPS, -such as the dummy MPI library in src/STUBS or any package libraries in -lib/packages, since they are always built as shared libraries using -the -fPIC switch. However, if a library like MPI or FFTW does not -exist as a shared library, the shared library build will generate an -error. This means you will need to install a shared library version -of the auxiliary library. The build instructions for the library -should tell you how to do this. - -Here is an example of such errors when the system FFTW or provided -lib/colvars library have not been built as shared libraries: - -/usr/bin/ld: /usr/local/lib/libfftw3.a(mapflags.o): relocation -R_X86_64_32 against '.rodata' can not be used when making a shared -object; recompile with -fPIC -/usr/local/lib/libfftw3.a: could not read symbols: Bad value :pre - -/usr/bin/ld: ../../lib/colvars/libcolvars.a(colvarmodule.o): -relocation R_X86_64_32 against '__pthread_key_create' can not be used -when making a shared object; recompile with -fPIC -../../lib/colvars/libcolvars.a: error adding symbols: Bad value :pre - -As an example, here is how to build and install the "MPICH -library"_mpich, a popular open-source version of MPI, distributed by -Argonne National Labs, as a shared library in the default -/usr/local/lib location: - -:link(mpich,http://www-unix.mcs.anl.gov/mpi) - -./configure --enable-shared -make -make install :pre - -You may need to use "sudo make install" in place of the last line if -you do not have write privileges for /usr/local/lib. The end result -should be the file /usr/local/lib/libmpich.so. - -[Additional requirement for using a shared library:] :h4 - -The operating system finds shared libraries to load at run-time using -the environment variable LD_LIBRARY_PATH. So you may wish to copy the -file src/liblammps.so or src/liblammps_g++.so (for example) to a place -the system can find it by default, such as /usr/local/lib, or you may -wish to add the LAMMPS src directory to LD_LIBRARY_PATH, so that the -current version of the shared library is always available to programs -that use it. - -For the csh or tcsh shells, you would add something like this to your -~/.cshrc file: - -setenv LD_LIBRARY_PATH $\{LD_LIBRARY_PATH\}:/home/sjplimp/lammps/src :pre - -Calling the LAMMPS library :h4 - -Either flavor of library (static or shared) allows one or more LAMMPS -objects to be instantiated from the calling program. - -When used from a C++ program, all of LAMMPS is wrapped in a LAMMPS_NS -namespace; you can safely use any of its classes and methods from -within the calling code, as needed. - -When used from a C or Fortran program or a scripting language like -Python, the library has a simple function-style interface, provided in -src/library.cpp and src/library.h. - -See the sample codes in examples/COUPLE/simple for examples of C++ and -C and Fortran codes that invoke LAMMPS thru its library interface. -There are other examples as well in the COUPLE directory which use -coupling ideas discussed on the "Howto couple"_Howto_couple.html doc -page. See the "Python"_Python.html doc page for a description of the -Python wrapper provided with LAMMPS that operates through the LAMMPS -library interface. - -The files src/library.cpp and library.h define the C-style API for -using LAMMPS as a library. See the "Howto library"_Howto_library.html -doc page for a description of the interface and how to extend it for -your needs. - -:line - -2.5 Running LAMMPS :h3,link(start_5) - -By default, LAMMPS runs by reading commands from standard input. Thus -if you run the LAMMPS executable by itself, e.g. - -lmp_linux :pre - -it will simply wait, expecting commands from the keyboard. Typically -you should put commands in an input script and use I/O redirection, -e.g. - -lmp_linux < in.file :pre - -For parallel environments this should also work. If it does not, use -the '-in' command-line switch, e.g. - -lmp_linux -in in.file :pre - -The "Commands"_Commands.html doc page describes how input scripts are -structured and what commands they contain. - -You can test LAMMPS on any of the sample inputs provided in the -examples or bench directory. Input scripts are named in.* and sample -outputs are named log.*.name.P where name is a machine and P is the -number of processors it was run on. - -Here is how you might run a standard Lennard-Jones benchmark on a -Linux box, using mpirun to launch a parallel job: - -cd src -make linux -cp lmp_linux ../bench -cd ../bench -mpirun -np 4 lmp_linux -in in.lj :pre - -See "this page"_bench for timings for this and the other benchmarks on -various platforms. Note that some of the example scripts require -LAMMPS to be built with one or more of its optional packages. - -:link(bench,http://lammps.sandia.gov/bench.html) - -:line - -On a Windows box, you can skip making LAMMPS and simply download an -installer package from "here"_http://packages.lammps.org/windows.html - -For running the non-MPI executable, follow these steps: - -Get a command prompt by going to Start->Run... , -then typing "cmd". :ulb,l - -Move to the directory where you have your input, e.g. a copy of -the [in.lj] input from the bench folder. (e.g. by typing: cd "Documents"). :l - -At the command prompt, type "lmp_serial -in in.lj", replacing [in.lj] -with the name of your LAMMPS input script. :l - -The serial executable includes support for multi-threading -parallelization from the styles in the USER-OMP packages. - -To run with, e.g. 4 threads, type "lmp_serial -in in.lj -pk omp 4 -sf omp" -:ule - -For the MPI version, which allows you to run LAMMPS under Windows with -the more general message passing parallel library (LAMMPS has been -designed from ground up to use MPI efficiently), follow these steps: - -Download and install a compatible MPI library binary package: -for 32-bit Windows -"mpich2-1.4.1p1-win-ia32.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-ia32.msi -and for 64-bit Windows -"mpich2-1.4.1p1-win-x86-64.msi"_download.lammps.org/thirdparty/mpich2-1.4.1p1-win-x86-64.msi -:ulb,l - -The LAMMPS Windows installer packages will automatically adjust your -path for the default location of this MPI package. After the installation -of the MPICH2 software, it needs to be integrated into the system. -For this you need to start a Command Prompt in {Administrator Mode} -(right click on the icon and select it). Change into the MPICH2 -installation directory, then into the subdirectory [bin] and execute -[smpd.exe -install]. Exit the command window. - -Get a new, regular command prompt by going to Start->Run... , -then typing "cmd". :l - -Move to the directory where you have your input file -(e.g. by typing: cd "Documents"). :l - -Then type something like this: - -mpiexec -localonly 4 lmp_mpi -in in.lj :pre -or - -mpiexec -np 4 lmp_mpi -in in.lj :pre - -replacing [in.lj] with the name of your LAMMPS input script. For the latter -case, you may be prompted to enter your password. :l - -In this mode, output may not immediately show up on the screen, so if -your input script takes a long time to execute, you may need to be -patient before the output shows up. :l - -The parallel executable can also run on a single processor by typing -something like: - -lmp_mpi -in in.lj :pre - -And the parallel executable also includes OpenMP multi-threading, which -can be combined with MPI using something like: - -mpiexec -localonly 2 lmp_mpi -in in.lj -pk omp 2 -sf omp :pre - -:ule - -:line - -The screen output from LAMMPS is described in a section below. As it -runs, LAMMPS also writes a log.lammps file with the same information. - -Note that this sequence of commands copies the LAMMPS executable -(lmp_linux) to the directory with the input files. This may not be -necessary, but some versions of MPI reset the working directory to -where the executable is, rather than leave it as the directory where -you launch mpirun from (if you launch lmp_linux on its own and not -under mpirun). If that happens, LAMMPS will look for additional input -files and write its output files to the executable directory, rather -than your working directory, which is probably not what you want. - -If LAMMPS encounters errors in the input script or while running a -simulation it will print an ERROR message and stop or a WARNING -message and continue. See the "Errors"_Errors.html doc page for a -discussion of the various kinds of errors LAMMPS can or can't detect, -a list of all ERROR and WARNING messages, and what to do about them. - -LAMMPS can run a problem on any number of processors, including a -single processor. In theory you should get identical answers on any -number of processors and on any machine. In practice, numerical -round-off can cause slight differences and eventual divergence of -molecular dynamics phase space trajectories. - -LAMMPS can run as large a problem as will fit in the physical memory -of one or more processors. If you run out of memory, you must run on -more processors or setup a smaller problem. - -:line - -2.6 Command-line options :h3,link(start_6) - -At run time, LAMMPS recognizes several optional command-line switches -which may be used in any order. Either the full word or a one-or-two -letter abbreviation can be used: - --e or -echo --h or -help --i or -in --k or -kokkos --l or -log --nc or -nocite --pk or -package --p or -partition --pl or -plog --ps or -pscreen --r or -restart --ro or -reorder --sc or -screen --sf or -suffix --v or -var :ul - -For example, lmp_ibm might be launched as follows: - -mpirun -np 16 lmp_ibm -v f tmp.out -l my.log -sc none -in in.alloy -mpirun -np 16 lmp_ibm -var f tmp.out -log my.log -screen none -in in.alloy :pre - -Here are the details on the options: - --echo style :pre - -Set the style of command echoing. The style can be {none} or {screen} -or {log} or {both}. Depending on the style, each command read from -the input script will be echoed to the screen and/or logfile. This -can be useful to figure out which line of your script is causing an -input error. The default value is {log}. The echo style can also be -set by using the "echo"_echo.html command in the input script itself. - --help :pre - -Print a brief help summary and a list of options compiled into this -executable for each LAMMPS style (atom_style, fix, compute, -pair_style, bond_style, etc). This can tell you if the command you -want to use was included via the appropriate package at compile time. -LAMMPS will print the info and immediately exit if this switch is -used. - --in file :pre - -Specify a file to use as an input script. This is an optional switch -when running LAMMPS in one-partition mode. If it is not specified, -LAMMPS reads its script from standard input, typically from a script -via I/O redirection; e.g. lmp_linux < in.run. I/O redirection should -also work in parallel, but if it does not (in the unlikely case that -an MPI implementation does not support it), then use the -in flag. -Note that this is a required switch when running LAMMPS in -multi-partition mode, since multiple processors cannot all read from -stdin. - --kokkos on/off keyword/value ... :pre - -Explicitly enable or disable KOKKOS support, as provided by the KOKKOS -package. Even if LAMMPS is built with this package, as described -above in "Section 2.3"_#start_3, this switch must be set to enable -running with the KOKKOS-enabled styles the package provides. If the -switch is not set (the default), LAMMPS will operate as if the KOKKOS -package were not installed; i.e. you can run standard LAMMPS or with -the GPU or USER-OMP packages, for testing or benchmarking purposes. - -Additional optional keyword/value pairs can be specified which -determine how Kokkos will use the underlying hardware on your -platform. These settings apply to each MPI task you launch via the -"mpirun" or "mpiexec" command. You may choose to run one or more MPI -tasks per physical node. Note that if you are running on a desktop -machine, you typically have one physical node. On a cluster or -supercomputer there may be dozens or 1000s of physical nodes. - -Either the full word or an abbreviation can be used for the keywords. -Note that the keywords do not use a leading minus sign. I.e. the -keyword is "t", not "-t". Also note that each of the keywords has a -default setting. Example of when to use these options and what -settings to use on different platforms is given on the "Speed -kokkos"_Speed_kokkos.html doc page. - -d or device -g or gpus -t or threads -n or numa :ul - -device Nd :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and if you are running with only one -MPI task per node. The Nd setting is the ID of the GPU on the node to -run on. By default Nd = 0. If you have multiple GPUs per node, they -have consecutive IDs numbered as 0,1,2,etc. This setting allows you -to launch multiple independent jobs on the node, each with a single -MPI task per node, and assign each job to run on a different GPU. - -gpus Ng Ns :pre - -This option is only relevant if you built LAMMPS with CUDA=yes, you -have more than one GPU per node, and you are running with multiple MPI -tasks per node (up to one per GPU). The Ng setting is how many GPUs -you will use. The Ns setting is optional. If set, it is the ID of a -GPU to skip when assigning MPI tasks to GPUs. This may be useful if -your desktop system reserves one GPU to drive the screen and the rest -are intended for computational work like running LAMMPS. By default -Ng = 1 and Ns is not set. - -Depending on which flavor of MPI you are running, LAMMPS will look for -one of these 3 environment variables - -SLURM_LOCALID (various MPI variants compiled with SLURM support) -MV2_COMM_WORLD_LOCAL_RANK (Mvapich) -OMPI_COMM_WORLD_LOCAL_RANK (OpenMPI) :pre - -which are initialized by the "srun", "mpirun" or "mpiexec" commands. -The environment variable setting for each MPI rank is used to assign a -unique GPU ID to the MPI task. - -threads Nt :pre - -This option assigns Nt number of threads to each MPI task for -performing work when Kokkos is executing in OpenMP or pthreads mode. -The default is Nt = 1, which essentially runs in MPI-only mode. If -there are Np MPI tasks per physical node, you generally want Np*Nt = -the number of physical cores per node, to use your available hardware -optimally. This also sets the number of threads used by the host when -LAMMPS is compiled with CUDA=yes. - -numa Nm :pre - -This option is only relevant when using pthreads with hwloc support. -In this case Nm defines the number of NUMA regions (typically sockets) -on a node which will be utilized by a single MPI rank. By default Nm -= 1. If this option is used the total number of worker-threads per -MPI rank is threads*numa. Currently it is always almost better to -assign at least one MPI rank per NUMA region, and leave numa set to -its default value of 1. This is because letting a single process span -multiple NUMA regions induces a significant amount of cross NUMA data -traffic which is slow. - --log file :pre - -Specify a log file for LAMMPS to write status information to. In -one-partition mode, if the switch is not used, LAMMPS writes to the -file log.lammps. If this switch is used, LAMMPS writes to the -specified file. In multi-partition mode, if the switch is not used, a -log.lammps file is created with hi-level status information. Each -partition also writes to a log.lammps.N file where N is the partition -ID. If the switch is specified in multi-partition mode, the hi-level -logfile is named "file" and each partition also logs information to a -file.N. For both one-partition and multi-partition mode, if the -specified file is "none", then no log files are created. Using a -"log"_log.html command in the input script will override this setting. -Option -plog will override the name of the partition log files file.N. - --nocite :pre - -Disable writing the log.cite file which is normally written to list -references for specific cite-able features used during a LAMMPS run. -See the "citation page"_http://lammps.sandia.gov/cite.html for more -details. - --package style args .... :pre - -Invoke the "package"_package.html command with style and args. The -syntax is the same as if the command appeared at the top of the input -script. For example "-package gpu 2" or "-pk gpu 2" is the same as -"package gpu 2"_package.html in the input script. The possible styles -and args are documented on the "package"_package.html doc page. This -switch can be used multiple times, e.g. to set options for the -USER-INTEL and USER-OMP packages which can be used together. - -Along with the "-suffix" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - --partition 8x2 4 5 ... :pre - -Invoke LAMMPS in multi-partition mode. When LAMMPS is run on P -processors and this switch is not used, LAMMPS runs in one partition, -i.e. all P processors run a single simulation. If this switch is -used, the P processors are split into separate partitions and each -partition runs its own simulation. The arguments to the switch -specify the number of processors in each partition. Arguments of the -form MxN mean M partitions, each with N processors. Arguments of the -form N mean a single partition with N processors. The sum of -processors in all partitions must equal P. Thus the command -"-partition 8x2 4 5" has 10 partitions and runs on a total of 25 -processors. - -Running with multiple partitions can be useful for running -"multi-replica simulations"_Howto_replica.html, where each replica -runs on on one or a few processors. Note that with MPI installed on a -machine (e.g. your desktop), you can run on more (virtual) processors -than you have physical processors. - -To run multiple independent simulations from one input script, using -multiple partitions, see the "Howto multiple"_Howto_multiple.html doc -page. World- and universe-style "variables"_variable.html are useful -in this context. - --plog file :pre - -Specify the base name for the partition log files, so partition N -writes log information to file.N. If file is none, then no partition -log files are created. This overrides the filename specified in the --log command-line option. This option is useful when working with -large numbers of partitions, allowing the partition log files to be -suppressed (-plog none) or placed in a sub-directory (-plog -replica_files/log.lammps) If this option is not used the log file for -partition N is log.lammps.N or whatever is specified by the -log -command-line option. - --pscreen file :pre - -Specify the base name for the partition screen file, so partition N -writes screen information to file.N. If file is none, then no -partition screen files are created. This overrides the filename -specified in the -screen command-line option. This option is useful -when working with large numbers of partitions, allowing the partition -screen files to be suppressed (-pscreen none) or placed in a -sub-directory (-pscreen replica_files/screen). If this option is not -used the screen file for partition N is screen.N or whatever is -specified by the -screen command-line option. - --restart restartfile {remap} datafile keyword value ... :pre - -Convert the restart file into a data file and immediately exit. This -is the same operation as if the following 2-line input script were -run: - -read_restart restartfile {remap} -write_data datafile keyword value ... :pre - -Note that the specified restartfile and datafile can have wild-card -characters ("*",%") as described by the -"read_restart"_read_restart.html and "write_data"_write_data.html -commands. But a filename such as file.* will need to be enclosed in -quotes to avoid shell expansion of the "*" character. - -Note that following restartfile, the optional flag {remap} can be -used. This has the same effect as adding it to the -"read_restart"_read_restart.html command, as explained on its doc -page. This is only useful if the reading of the restart file triggers -an error that atoms have been lost. In that case, use of the remap -flag should allow the data file to still be produced. - -Also note that following datafile, the same optional keyword/value -pairs can be listed as used by the "write_data"_write_data.html -command. - --reorder nth N --reorder custom filename :pre - -Reorder the processors in the MPI communicator used to instantiate -LAMMPS, in one of several ways. The original MPI communicator ranks -all P processors from 0 to P-1. The mapping of these ranks to -physical processors is done by MPI before LAMMPS begins. It may be -useful in some cases to alter the rank order. E.g. to insure that -cores within each node are ranked in a desired order. Or when using -the "run_style verlet/split"_run_style.html command with 2 partitions -to insure that a specific Kspace processor (in the 2nd partition) is -matched up with a specific set of processors in the 1st partition. -See the "Speed tips"_Speed_tips.html doc page for more details. - -If the keyword {nth} is used with a setting {N}, then it means every -Nth processor will be moved to the end of the ranking. This is useful -when using the "run_style verlet/split"_run_style.html command with 2 -partitions via the -partition command-line switch. The first set of -processors will be in the first partition, the 2nd set in the 2nd -partition. The -reorder command-line switch can alter this so that -the 1st N procs in the 1st partition and one proc in the 2nd partition -will be ordered consecutively, e.g. as the cores on one physical node. -This can boost performance. For example, if you use "-reorder nth 4" -and "-partition 9 3" and you are running on 12 processors, the -processors will be reordered from - -0 1 2 3 4 5 6 7 8 9 10 11 :pre - -to - -0 1 2 4 5 6 8 9 10 3 7 11 :pre - -so that the processors in each partition will be - -0 1 2 4 5 6 8 9 10 -3 7 11 :pre - -See the "processors" command for how to insure processors from each -partition could then be grouped optimally for quad-core nodes. - -If the keyword is {custom}, then a file that specifies a permutation -of the processor ranks is also specified. The format of the reorder -file is as follows. Any number of initial blank or comment lines -(starting with a "#" character) can be present. These should be -followed by P lines of the form: - -I J :pre - -where P is the number of processors LAMMPS was launched with. Note -that if running in multi-partition mode (see the -partition switch -above) P is the total number of processors in all partitions. The I -and J values describe a permutation of the P processors. Every I and -J should be values from 0 to P-1 inclusive. In the set of P I values, -every proc ID should appear exactly once. Ditto for the set of P J -values. A single I,J pairing means that the physical processor with -rank I in the original MPI communicator will have rank J in the -reordered communicator. - -Note that rank ordering can also be specified by many MPI -implementations, either by environment variables that specify how to -order physical processors, or by config files that specify what -physical processors to assign to each MPI rank. The -reorder switch -simply gives you a portable way to do this without relying on MPI -itself. See the "processors out"_processors.html command for how -to output info on the final assignment of physical processors to -the LAMMPS simulation domain. - --screen file :pre - -Specify a file for LAMMPS to write its screen information to. In -one-partition mode, if the switch is not used, LAMMPS writes to the -screen. If this switch is used, LAMMPS writes to the specified file -instead and you will see no screen output. In multi-partition mode, -if the switch is not used, hi-level status information is written to -the screen. Each partition also writes to a screen.N file where N is -the partition ID. If the switch is specified in multi-partition mode, -the hi-level screen dump is named "file" and each partition also -writes screen information to a file.N. For both one-partition and -multi-partition mode, if the specified file is "none", then no screen -output is performed. Option -pscreen will override the name of the -partition screen files file.N. - --suffix style args :pre - -Use variants of various styles if they exist. The specified style can -be {cuda}, {gpu}, {intel}, {kk}, {omp}, {opt}, or {hybrid}. These -refer to optional packages that LAMMPS can be built with, as described -above in "Section 2.3"_#start_3. The "gpu" style corresponds to the -GPU package, the "intel" style to the USER-INTEL package, the "kk" -style to the KOKKOS package, the "opt" style to the OPT package, and -the "omp" style to the USER-OMP package. The hybrid style is the only -style that accepts arguments. It allows for two packages to be -specified. The first package specified is the default and will be used -if it is available. If no style is available for the first package, -the style for the second package will be used if available. For -example, "-suffix hybrid intel omp" will use styles from the -USER-INTEL package if they are installed and available, but styles for -the USER-OMP package otherwise. - -Along with the "-package" command-line switch, this is a convenient -mechanism for invoking accelerator packages and their options without -having to edit an input script. - -As an example, all of the packages provide a "pair_style -lj/cut"_pair_lj.html variant, with style names lj/cut/gpu, -lj/cut/intel, lj/cut/kk, lj/cut/omp, and lj/cut/opt. A variant style -can be specified explicitly in your input script, e.g. pair_style -lj/cut/gpu. If the -suffix switch is used the specified suffix -(gpu,intel,kk,omp,opt) is automatically appended whenever your input -script command creates a new "atom"_atom_style.html, -"pair"_pair_style.html, "fix"_fix.html, "compute"_compute.html, or -"run"_run_style.html style. If the variant version does not exist, -the standard version is created. - -For the GPU package, using this command-line switch also invokes the -default GPU settings, as if the command "package gpu 1" were used at -the top of your input script. These settings can be changed by using -the "-package gpu" command-line switch or the "package -gpu"_package.html command in your script. - -For the USER-INTEL package, using this command-line switch also -invokes the default USER-INTEL settings, as if the command "package -intel 1" were used at the top of your input script. These settings -can be changed by using the "-package intel" command-line switch or -the "package intel"_package.html command in your script. If the -USER-OMP package is also installed, the hybrid style with "intel omp" -arguments can be used to make the omp suffix a second choice, if a -requested style is not available in the USER-INTEL package. It will -also invoke the default USER-OMP settings, as if the command "package -omp 0" were used at the top of your input script. These settings can -be changed by using the "-package omp" command-line switch or the -"package omp"_package.html command in your script. - -For the KOKKOS package, using this command-line switch also invokes -the default KOKKOS settings, as if the command "package kokkos" were -used at the top of your input script. These settings can be changed -by using the "-package kokkos" command-line switch or the "package -kokkos"_package.html command in your script. - -For the OMP package, using this command-line switch also invokes the -default OMP settings, as if the command "package omp 0" were used at -the top of your input script. These settings can be changed by using -the "-package omp" command-line switch or the "package -omp"_package.html command in your script. - -The "suffix"_suffix.html command can also be used within an input -script to set a suffix, or to turn off or back on any suffix setting -made via the command line. - --var name value1 value2 ... :pre - -Specify a variable that will be defined for substitution purposes when -the input script is read. This switch can be used multiple times to -define multiple variables. "Name" is the variable name which can be a -single character (referenced as $x in the input script) or a full -string (referenced as $\{abc\}). An "index-style -variable"_variable.html will be created and populated with the -subsequent values, e.g. a set of filenames. Using this command-line -option is equivalent to putting the line "variable name index value1 -value2 ..." at the beginning of the input script. Defining an index -variable as a command-line argument overrides any setting for the same -index variable in the input script, since index variables cannot be -re-defined. See the "variable"_variable.html command for more info on -defining index and other kinds of variables and the "Commands -parse"_Commands_parse.html page for more info on using variables in -input scripts. - -NOTE: Currently, the command-line parser looks for arguments that -start with "-" to indicate new switches. Thus you cannot specify -multiple variable values if any of they start with a "-", e.g. a -negative numeric value. It is OK if the first value1 starts with a -"-", since it is automatically skipped. - -:line - -2.7 LAMMPS screen output :h3,link(start_7) - -As LAMMPS reads an input script, it prints information to both the -screen and a log file about significant actions it takes to setup a -simulation. When the simulation is ready to begin, LAMMPS performs -various initializations and prints the amount of memory (in MBytes per -processor) that the simulation requires. It also prints details of -the initial thermodynamic state of the system. During the run itself, -thermodynamic information is printed periodically, every few -timesteps. When the run concludes, LAMMPS prints the final -thermodynamic state and a total run time for the simulation. It then -appends statistics about the CPU time and storage requirements for the -simulation. An example set of statistics is shown here: - -Loop time of 2.81192 on 4 procs for 300 steps with 2004 atoms :pre - -Performance: 18.436 ns/day 1.302 hours/ns 106.689 timesteps/s -97.0% CPU use with 4 MPI tasks x no OpenMP threads :pre - -MPI task timings breakdown: -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 1.9808 | 2.0134 | 2.0318 | 1.4 | 71.60 -Bond | 0.0021894 | 0.0060319 | 0.010058 | 4.7 | 0.21 -Kspace | 0.3207 | 0.3366 | 0.36616 | 3.1 | 11.97 -Neigh | 0.28411 | 0.28464 | 0.28516 | 0.1 | 10.12 -Comm | 0.075732 | 0.077018 | 0.07883 | 0.4 | 2.74 -Output | 0.00030518 | 0.00042665 | 0.00078821 | 1.0 | 0.02 -Modify | 0.086606 | 0.086631 | 0.086668 | 0.0 | 3.08 -Other | | 0.007178 | | | 0.26 :pre - -Nlocal: 501 ave 508 max 490 min -Histogram: 1 0 0 0 0 0 1 1 0 1 -Nghost: 6586.25 ave 6628 max 6548 min -Histogram: 1 0 1 0 0 0 1 0 0 1 -Neighs: 177007 ave 180562 max 170212 min -Histogram: 1 0 0 0 0 0 0 1 1 1 :pre - -Total # of neighbors = 708028 -Ave neighs/atom = 353.307 -Ave special neighs/atom = 2.34032 -Neighbor list builds = 26 -Dangerous builds = 0 :pre - -The first section provides a global loop timing summary. The {loop time} -is the total wall time for the section. The {Performance} line is -provided for convenience to help predicting the number of loop -continuations required and for comparing performance with other, -similar MD codes. The {CPU use} line provides the CPU utilization per -MPI task; it should be close to 100% times the number of OpenMP -threads (or 1 of no OpenMP). Lower numbers correspond to delays due -to file I/O or insufficient thread utilization. - -The MPI task section gives the breakdown of the CPU run time (in -seconds) into major categories: - -{Pair} stands for all non-bonded force computation -{Bond} stands for bonded interactions: bonds, angles, dihedrals, impropers -{Kspace} stands for reciprocal space interactions: Ewald, PPPM, MSM -{Neigh} stands for neighbor list construction -{Comm} stands for communicating atoms and their properties -{Output} stands for writing dumps and thermo output -{Modify} stands for fixes and computes called by them -{Other} is the remaining time :ul - -For each category, there is a breakdown of the least, average and most -amount of wall time a processor spent on this section. Also you have the -variation from the average time. Together these numbers allow to gauge -the amount of load imbalance in this segment of the calculation. Ideally -the difference between minimum, maximum and average is small and thus -the variation from the average close to zero. The final column shows -the percentage of the total loop time is spent in this section. - -When using the "timer full"_timer.html setting, an additional column -is present that also prints the CPU utilization in percent. In -addition, when using {timer full} and the "package omp"_package.html -command are active, a similar timing summary of time spent in threaded -regions to monitor thread utilization and load balance is provided. A -new entry is the {Reduce} section, which lists the time spent in -reducing the per-thread data elements to the storage for non-threaded -computation. These thread timings are taking from the first MPI rank -only and and thus, as the breakdown for MPI tasks can change from MPI -rank to MPI rank, this breakdown can be very different for individual -ranks. Here is an example output for this section: - -Thread timings breakdown (MPI rank 0): -Total threaded time 0.6846 / 90.6% -Section | min time | avg time | max time |%varavg| %total ---------------------------------------------------------------- -Pair | 0.5127 | 0.5147 | 0.5167 | 0.3 | 75.18 -Bond | 0.0043139 | 0.0046779 | 0.0050418 | 0.5 | 0.68 -Kspace | 0.070572 | 0.074541 | 0.07851 | 1.5 | 10.89 -Neigh | 0.084778 | 0.086969 | 0.089161 | 0.7 | 12.70 -Reduce | 0.0036485 | 0.003737 | 0.0038254 | 0.1 | 0.55 :pre - -The third section lists the number of owned atoms (Nlocal), ghost atoms -(Nghost), and pair-wise neighbors stored per processor. The max and min -values give the spread of these values across processors with a 10-bin -histogram showing the distribution. The total number of histogram counts -is equal to the number of processors. - -The last section gives aggregate statistics for pair-wise neighbors -and special neighbors that LAMMPS keeps track of (see the -"special_bonds"_special_bonds.html command). The number of times -neighbor lists were rebuilt during the run is given as well as the -number of potentially "dangerous" rebuilds. If atom movement -triggered neighbor list rebuilding (see the -"neigh_modify"_neigh_modify.html command), then dangerous -reneighborings are those that were triggered on the first timestep -atom movement was checked for. If this count is non-zero you may wish -to reduce the delay factor to insure no force interactions are missed -by atoms moving beyond the neighbor skin distance before a rebuild -takes place. - -If an energy minimization was performed via the -"minimize"_minimize.html command, additional information is printed, -e.g. - -Minimization stats: - Stopping criterion = linesearch alpha is zero - Energy initial, next-to-last, final = - -6372.3765206 -8328.46998942 -8328.46998942 - Force two-norm initial, final = 1059.36 5.36874 - Force max component initial, final = 58.6026 1.46872 - Final line search alpha, max atom move = 2.7842e-10 4.0892e-10 - Iterations, force evaluations = 701 1516 :pre - -The first line prints the criterion that determined the minimization -to be completed. The third line lists the initial and final energy, -as well as the energy on the next-to-last iteration. The next 2 lines -give a measure of the gradient of the energy (force on all atoms). -The 2-norm is the "length" of this force vector; the inf-norm is the -largest component. Then some information about the line search and -statistics on how many iterations and force-evaluations the minimizer -required. Multiple force evaluations are typically done at each -iteration to perform a 1d line minimization in the search direction. - -If a "kspace_style"_kspace_style.html long-range Coulombics solve was -performed during the run (PPPM, Ewald), then additional information is -printed, e.g. - -FFT time (% of Kspce) = 0.200313 (8.34477) -FFT Gflps 3d 1d-only = 2.31074 9.19989 :pre - -The first line gives the time spent doing 3d FFTs (4 per timestep) and -the fraction it represents of the total KSpace time (listed above). -Each 3d FFT requires computation (3 sets of 1d FFTs) and communication -(transposes). The total flops performed is 5Nlog_2(N), where N is the -number of points in the 3d grid. The FFTs are timed with and without -the communication and a Gflop rate is computed. The 3d rate is with -communication; the 1d rate is without (just the 1d FFTs). Thus you -can estimate what fraction of your FFT time was spent in -communication, roughly 75% in the example above. - -:line - -2.8 Tips for users of previous LAMMPS versions :h3,link(start_8) - -The current C++ began with a complete rewrite of LAMMPS 2001, which -was written in F90. Features of earlier versions of LAMMPS are listed -on the "History page"_http://lammps.sandia.gov/history.html of the -LAMMPS website. The F90 and F77 versions (2001 and 99) are also -freely distributed as open-source codes; check the "History -page"_http://lammps.sandia.gov/history.html of the LAMMPS website for -info about those versions. The 99 and 2001 versions are no longer -under active development; they do not have all the features of C++ -LAMMPS. - -If you are a previous user of LAMMPS 2001, these are the most -significant changes you will notice in C++ LAMMPS: - -(1) The names and arguments of many input script commands have -changed. All commands are now a single word (e.g. read_data instead -of read data). - -(2) All the functionality of LAMMPS 2001 is included in C++ LAMMPS, -but you may need to specify the relevant commands in different ways. - -(3) The format of the data file can be streamlined for some problems. -See the "read_data"_read_data.html command for details. The data file -section "Nonbond Coeff" has been renamed to "Pair Coeff" in C++ LAMMPS. - -(4) Binary restart files written by LAMMPS 2001 cannot be read by C++ -LAMMPS with a "read_restart"_read_restart.html command. This is -because they were output by F90 which writes in a different binary -format than C or C++ writes or reads. Use the {restart2data} tool -provided with LAMMPS 2001 to convert the 2001 restart file to a text -data file. Then edit the data file as necessary before using the C++ -LAMMPS "read_data"_read_data.html command to read it in. - -(5) There are numerous small numerical changes in C++ LAMMPS that mean -you will not get identical answers when comparing to a 2001 run. -However, your initial thermodynamic energy and MD trajectory should be -close if you have setup the problem for both codes the same. diff --git a/doc/src/Speed.txt b/doc/src/Speed.txt index 091657082a..7eac11ffa5 100644 --- a/doc/src/Speed.txt +++ b/doc/src/Speed.txt @@ -31,15 +31,18 @@ hardware platforms.