diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 007ac2ca3c..59a937faba 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -59,7 +59,8 @@ src/VTK/* @rbberger # individual files in packages src/GPU/pair_vashishta_gpu.* @andeplane -src/KOKKOS/pair_vashishta_kokkos.* @andeplane +src/KOKKOS/pair_vashishta_kokkos.* @andeplane @stanmoore1 +src/KOSSOS/pair_pod_kokkos.* @exapde @stanmoore1 src/MANYBODY/pair_vashishta_table.* @andeplane src/MANYBODY/pair_atm.* @sergeylishchuk src/MANYBODY/pair_nb3b_screened.* @flodesani diff --git a/.gitignore b/.gitignore index 4faef4b8db..d96f0b4b5f 100644 --- a/.gitignore +++ b/.gitignore @@ -43,12 +43,12 @@ Thumbs.db #cmake /build* -/CMakeCache.txt -/CMakeFiles/ -/Testing +CMakeCache.txt +CMakeFiles /Makefile -/Testing -/cmake_install.cmake +Testing +Temporary +cmake_install.cmake /lmp out/Debug out/RelWithDebInfo @@ -60,3 +60,4 @@ src/Makefile.package.settings-e /cmake/build/x64-Debug-Clang /install/x64-GUI-MSVC /install +.Rhistory diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt index ada38138f6..224dc5cf9d 100644 --- a/cmake/CMakeLists.txt +++ b/cmake/CMakeLists.txt @@ -23,6 +23,7 @@ project(lammps CXX) set(SOVERSION 0) get_property(BUILD_IS_MULTI_CONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG) +include(GNUInstallDirs) get_filename_component(LAMMPS_DIR ${CMAKE_CURRENT_SOURCE_DIR}/.. ABSOLUTE) get_filename_component(LAMMPS_LIB_BINARY_DIR ${CMAKE_BINARY_DIR}/lib ABSOLUTE) # collect all executables and shared libs in the top level build folder @@ -163,6 +164,22 @@ if(MSVC) add_compile_definitions(_CRT_SECURE_NO_WARNINGS) endif() +# warn about potentially problematic GCC compiler versions +if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU") + if (CMAKE_CXX_STANDARD GREATER_EQUAL 17) + if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 9.0) + message(WARNING "Using ${CMAKE_CXX_COMPILER_ID} compiler version ${CMAKE_CXX_COMPILER_VERSION} " + "with C++17 is not recommended. Please use ${CMAKE_CXX_COMPILER_ID} compiler version 9.x or later") + endif() + endif() + if (CMAKE_CXX_STANDARD GREATER_EQUAL 11) + if (CMAKE_CXX_COMPILER_VERSION VERSION_LESS 5.0) + message(WARNING "Using ${CMAKE_CXX_COMPILER_ID} compiler version ${CMAKE_CXX_COMPILER_VERSION} " + "with C++11 is not recommended. Please use ${CMAKE_CXX_COMPILER_ID} compiler version 5.x or later") + endif() + endif() +endif() + # export all symbols when building a .dll file on windows if((CMAKE_SYSTEM_NAME STREQUAL "Windows") AND BUILD_SHARED_LIBS) set(CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS ON) @@ -197,18 +214,17 @@ set(LAMMPS_BINARY lmp${LAMMPS_MACHINE}) option(BUILD_SHARED_LIBS "Build shared library" OFF) option(CMAKE_POSITION_INDEPENDENT_CODE "Create object compatible with shared libraries" ON) option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF) -option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF) option(BUILD_LAMMPS_GUI "Build and install the LAMMPS GUI" OFF) # Support using clang-tidy for C++ files with selected options set(ENABLE_CLANG_TIDY OFF CACHE BOOL "Include clang-tidy processing when compiling") if(ENABLE_CLANG_TIDY) - set(CMAKE_CXX_CLANG_TIDY "clang-tidy;-checks=-*,performance-trivially-destructible,performance-unnecessary-copy-initialization,performance-unnecessary-value-param,readability-redundant-control-flow,readability-redundant-declaration,readability-redundant-function-ptr-dereference,readability-redundant-member-init,readability-redundant-string-cstr,readability-redundant-string-init,readability-simplify-boolean-expr,readability-static-accessed-through-instance,readability-static-definition-in-anonymous-namespace,modernize-use-override,modernize-use-bool-literals,modernize-use-emplace,modernize-return-braced-init-list,modernize-use-equals-default,modernize-use-equals-delete,modernize-replace-random-shuffle,modernize-deprecated-headers,modernize-use-nullptr,modernize-use-noexcept,modernize-redundant-void-arg;-fix;-header-filter=.*,header-filter=library.h,header-filter=fmt/*.h" CACHE STRING "clang-tidy settings") + set(CMAKE_CXX_CLANG_TIDY "clang-tidy;-checks=-*,performance-trivially-destructible,performance-unnecessary-copy-initialization,performance-unnecessary-value-param,readability-redundant-control-flow,readability-redundant-declaration,readability-redundant-function-ptr-dereference,readability-redundant-member-init,readability-redundant-string-cstr,readability-redundant-string-init,readability-simplify-boolean-expr,readability-static-accessed-through-instance,readability-static-definition-in-anonymous-namespace,readability-qualified-auto,misc-unused-parameters,modernize-deprecated-ios-base-aliases,modernize-loop-convert,modernize-shrink-to-fit,modernize-use-auto,modernize-use-using,modernize-use-override,modernize-use-bool-literals,modernize-use-emplace,modernize-return-braced-init-list,modernize-use-equals-default,modernize-use-equals-delete,modernize-replace-random-shuffle,modernize-deprecated-headers,modernize-use-nullptr,modernize-use-noexcept,modernize-redundant-void-arg;-fix;-header-filter=.*,header-filter=library.h,header-filter=fmt/*.h" CACHE STRING "clang-tidy settings") else() unset(CMAKE_CXX_CLANG_TIDY CACHE) endif() -include(GNUInstallDirs) + file(GLOB ALL_SOURCES CONFIGURE_DEPENDS ${LAMMPS_SOURCE_DIR}/[^.]*.cpp) file(GLOB MAIN_SOURCES CONFIGURE_DEPENDS ${LAMMPS_SOURCE_DIR}/main.cpp) list(REMOVE_ITEM ALL_SOURCES ${MAIN_SOURCES}) @@ -282,10 +298,10 @@ set(STANDARD_PACKAGES ML-HDNNP ML-IAP ML-PACE + ML-POD ML-QUIP ML-RANN ML-SNAP - ML-POD ML-UF3 MOFFF MOLECULE @@ -305,6 +321,7 @@ set(STANDARD_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SCAFACOS SHOCK @@ -409,6 +426,7 @@ pkg_depends(CG-DNA ASPHERE) pkg_depends(ELECTRODE KSPACE) pkg_depends(EXTRA-MOLECULE MOLECULE) pkg_depends(MESONT MOLECULE) +pkg_depends(RHEO BPM) # detect if we may enable OpenMP support by default set(BUILD_OMP_DEFAULT OFF) @@ -549,7 +567,7 @@ else() endif() foreach(PKG_WITH_INCL KSPACE PYTHON ML-IAP VORONOI COLVARS ML-HDNNP MDI MOLFILE NETCDF - PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM COMPRESS ML-PACE LEPTON) + PLUMED QMMM ML-QUIP SCAFACOS MACHDYN VTK KIM COMPRESS ML-PACE LEPTON RHEO) if(PKG_${PKG_WITH_INCL}) include(Packages/${PKG_WITH_INCL}) endif() @@ -939,6 +957,7 @@ message(STATUS "<<< Compilers and Flags: >>> -- C++ Compiler: ${CMAKE_CXX_COMPILER} Type: ${CMAKE_CXX_COMPILER_ID} Version: ${CMAKE_CXX_COMPILER_VERSION} + C++ Standard: ${CMAKE_CXX_STANDARD} C++ Flags: ${CMAKE_CXX_FLAGS} ${CMAKE_CXX_FLAGS_${BTYPE}} Defines: ${DEFINES}") get_target_property(OPTIONS lammps COMPILE_OPTIONS) @@ -1045,9 +1064,6 @@ endif() if(BUILD_TOOLS) message(STATUS "<<< Building Tools >>>") endif() -if(BUILD_LAMMPS_SHELL) - message(STATUS "<<< Building LAMMPS Shell >>>") -endif() if(BUILD_LAMMPS_GUI) message(STATUS "<<< Building LAMMPS GUI >>>") if(LAMMPS_GUI_USE_PLUGIN) diff --git a/cmake/Modules/Packages/ML-QUIP.cmake b/cmake/Modules/Packages/ML-QUIP.cmake index 5cb5a0967e..9106ff54ef 100644 --- a/cmake/Modules/Packages/ML-QUIP.cmake +++ b/cmake/Modules/Packages/ML-QUIP.cmake @@ -27,7 +27,7 @@ if(DOWNLOAD_QUIP) else() message(FATAL_ERROR "The ${CMAKE_Fortran_COMPILER_ID} Fortran compiler is not (yet) supported for building QUIP") endif() - set(temp "${temp}CFLAGS += -fPIC \nCPLUSPLUSFLAGS += -fPIC\nAR_ADD=src\n") + set(temp "${temp}CFLAGS += -fPIC -Wno-return-mismatch \nCPLUSPLUSFLAGS += -fPIC -Wno-return-mismatch\nAR_ADD=src\n") set(temp "${temp}MATH_LINKOPTS=") foreach(flag ${BLAS_LIBRARIES}) set(temp "${temp} ${flag}") diff --git a/cmake/Modules/Packages/RHEO.cmake b/cmake/Modules/Packages/RHEO.cmake new file mode 100644 index 0000000000..be8c22877b --- /dev/null +++ b/cmake/Modules/Packages/RHEO.cmake @@ -0,0 +1,2 @@ +find_package(GSL 2.7 REQUIRED) +target_link_libraries(lammps PRIVATE GSL::gsl) diff --git a/cmake/Modules/Testing.cmake b/cmake/Modules/Testing.cmake index ff595d3c8f..a72ce17e1b 100644 --- a/cmake/Modules/Testing.cmake +++ b/cmake/Modules/Testing.cmake @@ -102,9 +102,9 @@ endif() ####################################### # select code sanitizer options ####################################### -set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, leak, thread, undefined)") +set(ENABLE_SANITIZER "none" CACHE STRING "Select a code sanitizer option (none (default), address, hwaddress, leak, thread, undefined)") mark_as_advanced(ENABLE_SANITIZER) -set(ENABLE_SANITIZER_VALUES none address leak thread undefined) +set(ENABLE_SANITIZER_VALUES none address hwaddress leak thread undefined) set_property(CACHE ENABLE_SANITIZER PROPERTY STRINGS ${ENABLE_SANITIZER_VALUES}) validate_option(ENABLE_SANITIZER ENABLE_SANITIZER_VALUES) string(TOLOWER ${ENABLE_SANITIZER} ENABLE_SANITIZER) diff --git a/cmake/Modules/Tools.cmake b/cmake/Modules/Tools.cmake index 133301c3d4..94e077d51e 100644 --- a/cmake/Modules/Tools.cmake +++ b/cmake/Modules/Tools.cmake @@ -37,37 +37,6 @@ if(BUILD_TOOLS) add_subdirectory(${LAMMPS_TOOLS_DIR}/phonon ${CMAKE_BINARY_DIR}/phana_build) endif() -find_package(PkgConfig QUIET) -if(BUILD_LAMMPS_SHELL) - if(NOT PkgConfig_FOUND) - message(FATAL_ERROR "Must have pkg-config installed for building LAMMPS shell") - endif() - find_package(PkgConfig REQUIRED) - pkg_check_modules(READLINE IMPORTED_TARGET REQUIRED readline) - - # include resource compiler to embed icons into the executable on Windows - if(CMAKE_SYSTEM_NAME STREQUAL "Windows") - enable_language(RC) - set(ICON_RC_FILE ${LAMMPS_TOOLS_DIR}/lammps-shell/lmpicons.rc) - endif() - - add_executable(lammps-shell ${LAMMPS_TOOLS_DIR}/lammps-shell/lammps-shell.cpp ${ICON_RC_FILE}) - target_include_directories(lammps-shell PRIVATE ${LAMMPS_TOOLS_DIR}/lammps-shell) - target_link_libraries(lammps-shell PRIVATE lammps PkgConfig::READLINE) - - # workaround for broken readline pkg-config file on FreeBSD - if(CMAKE_SYSTEM_NAME STREQUAL "FreeBSD") - target_include_directories(lammps-shell PRIVATE /usr/local/include) - endif() - if(CMAKE_SYSTEM_NAME STREQUAL "LinuxMUSL") - pkg_check_modules(TERMCAP IMPORTED_TARGET REQUIRED termcap) - target_link_libraries(lammps-shell PRIVATE lammps PkgConfig::TERMCAP) - endif() - install(TARGETS lammps-shell EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR}) - install(DIRECTORY ${LAMMPS_TOOLS_DIR}/lammps-shell/icons DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/) - install(FILES ${LAMMPS_TOOLS_DIR}/lammps-shell/lammps-shell.desktop DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/applications/) -endif() - if(BUILD_LAMMPS_GUI) get_filename_component(LAMMPS_GUI_DIR ${LAMMPS_SOURCE_DIR}/../tools/lammps-gui ABSOLUTE) get_filename_component(LAMMPS_GUI_BIN ${CMAKE_BINARY_DIR}/lammps-gui-build ABSOLUTE) diff --git a/cmake/presets/all_off.cmake b/cmake/presets/all_off.cmake index 59ac760f6a..f2f5782480 100644 --- a/cmake/presets/all_off.cmake +++ b/cmake/presets/all_off.cmake @@ -26,8 +26,8 @@ set(ALL_PACKAGES DPD-REACT DPD-SMOOTH DRUDE - ELECTRODE EFF + ELECTRODE EXTRA-COMMAND EXTRA-COMPUTE EXTRA-DUMP @@ -82,6 +82,7 @@ set(ALL_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SCAFACOS SHOCK diff --git a/cmake/presets/all_on.cmake b/cmake/presets/all_on.cmake index a75ab0d9b2..8dc4632138 100644 --- a/cmake/presets/all_on.cmake +++ b/cmake/presets/all_on.cmake @@ -28,8 +28,8 @@ set(ALL_PACKAGES DPD-REACT DPD-SMOOTH DRUDE - ELECTRODE EFF + ELECTRODE EXTRA-COMMAND EXTRA-COMPUTE EXTRA-DUMP @@ -84,6 +84,7 @@ set(ALL_PACKAGES REACTION REAXFF REPLICA + RHEO RIGID SCAFACOS SHOCK diff --git a/cmake/presets/mingw-cross.cmake b/cmake/presets/mingw-cross.cmake index 8ca9b97e35..100ce13632 100644 --- a/cmake/presets/mingw-cross.cmake +++ b/cmake/presets/mingw-cross.cmake @@ -22,8 +22,8 @@ set(WIN_PACKAGES DPD-REACT DPD-SMOOTH DRUDE - ELECTRODE EFF + ELECTRODE EXTRA-COMMAND EXTRA-COMPUTE EXTRA-DUMP @@ -33,7 +33,6 @@ set(WIN_PACKAGES FEP GPU GRANULAR - INTEL INTERLAYER KSPACE LEPTON diff --git a/cmake/presets/windows.cmake b/cmake/presets/windows.cmake index 5e400e9de9..403d40efa4 100644 --- a/cmake/presets/windows.cmake +++ b/cmake/presets/windows.cmake @@ -52,8 +52,8 @@ set(WIN_PACKAGES ORIENT PERI PHONON - POEMS PLUGIN + POEMS PTM QEQ QTB diff --git a/doc/lammps.1 b/doc/lammps.1 index 27ec20b1d3..a66083ed07 100644 --- a/doc/lammps.1 +++ b/doc/lammps.1 @@ -1,7 +1,7 @@ -.TH LAMMPS "1" "17 April 2024" "2024-04-17" +.TH LAMMPS "1" "27 June 2024" "2024-06-27" .SH NAME .B LAMMPS -\- Molecular Dynamics Simulator. Version 17 April 2024 +\- Molecular Dynamics Simulator. Version 27 June 2024 .SH SYNOPSIS .B lmp diff --git a/doc/src/Build_basics.rst b/doc/src/Build_basics.rst index 233b825d01..45678938ef 100644 --- a/doc/src/Build_basics.rst +++ b/doc/src/Build_basics.rst @@ -489,8 +489,7 @@ using CMake or Make. .. code-block:: bash -D BUILD_TOOLS=value # yes or no (default). Build binary2txt, chain.x, micelle2d.x, msi2lmp, phana, stl_bin2txt - -D BUILD_LAMMPS_SHELL=value # yes or no (default). Build lammps-shell - -D BUILD_LAMMPS_GUI=value # yes or no (default). Build lammps-gui + -D BUILD_LAMMPS_GUI=value # yes or no (default). Build LAMMPS-GUI The generated binaries will also become part of the LAMMPS installation (see below). @@ -505,8 +504,9 @@ using CMake or Make. make chain # build only chain tool make micelle2d # build only micelle2d tool - cd lammps/tools/lammps-shell - make # build LAMMPS shell + .. note:: + + Building the LAMMPS-GUI *requires* building LAMMPS with CMake. ---------- diff --git a/doc/src/Build_development.rst b/doc/src/Build_development.rst index 4d8bf0d07f..8e103b089a 100644 --- a/doc/src/Build_development.rst +++ b/doc/src/Build_development.rst @@ -88,8 +88,8 @@ on recording all commands required to do the compilation. .. _sanitizer: -Address, Undefined Behavior, and Thread Sanitizer Support (CMake only) ----------------------------------------------------------------------- +Address, Leak, Undefined Behavior, and Thread Sanitizer Support (CMake only) +---------------------------------------------------------------------------- Compilers such as GCC and Clang support generating instrumented binaries which use different sanitizer libraries to detect problems in the code @@ -110,6 +110,7 @@ compilation and linking stages. This is done through setting the -D ENABLE_SANITIZER=none # no sanitizer active (default) -D ENABLE_SANITIZER=address # enable address sanitizer / memory leak checker + -D ENABLE_SANITIZER=hwaddress # enable hardware assisted address sanitizer / memory leak checker -D ENABLE_SANITIZER=leak # enable memory leak checker (only) -D ENABLE_SANITIZER=undefined # enable undefined behavior sanitizer -D ENABLE_SANITIZER=thread # enable thread sanitizer diff --git a/doc/src/Build_extras.rst b/doc/src/Build_extras.rst index f66238c3c9..4802c67420 100644 --- a/doc/src/Build_extras.rst +++ b/doc/src/Build_extras.rst @@ -59,6 +59,7 @@ This is the list of packages that may require additional steps. * :ref:`POEMS ` * :ref:`PYTHON ` * :ref:`QMMM ` + * :ref:`RHEO ` * :ref:`SCAFACOS ` * :ref:`VORONOI ` * :ref:`VTK ` @@ -1566,10 +1567,11 @@ LAMMPS build. .. tab:: CMake build When the ``-D PKG_PLUMED=yes`` flag is included in the cmake - command you must ensure that GSL is installed in locations that - are specified in your environment. There are then two additional - variables that control the manner in which PLUMED is obtained and - linked into LAMMPS. + command you must ensure that `the GNU Scientific Library (GSL) + ` is installed in locations + that are accessible in your environment. There are then two + additional variables that control the manner in which PLUMED is + obtained and linked into LAMMPS. .. code-block:: bash @@ -2040,6 +2042,36 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to ---------- +.. _rheo: + +RHEO package +------------ + +To build with this package you must have the `GNU Scientific Library +(GSL) ` installed in locations that +are accessible in your environment. The GSL library should be at least +version 2.7. + +.. tabs:: + + .. tab:: CMake build + + If CMake cannot find the GSL library or include files, you can set: + + .. code-block:: bash + + -D GSL_ROOT_DIR=path # path to root of GSL installation + + .. tab:: Traditional make + + LAMMPS will try to auto-detect the GSL compiler and linker flags + from the corresponding ``pkg-config`` file (``gsl.pc``), otherwise + you can edit the file ``lib/rheo/Makefile.lammps`` + to specify the paths and library names where indicated by comments. + This must be done **before** the package is installed. + +---------- + .. _scafacos: SCAFACOS package diff --git a/doc/src/Build_link.rst b/doc/src/Build_link.rst index 3800e41e21..efd6691d30 100644 --- a/doc/src/Build_link.rst +++ b/doc/src/Build_link.rst @@ -45,8 +45,8 @@ executable code from the library is copied into the calling executable. .. code-block:: bash - mpicc -c -O $(pkgconf liblammps --cflags) caller.c - mpicxx -o caller caller.o -$(pkgconf liblammps --libs) + mpicc -c -O $(pkg-config --cflags liblammps) caller.c + mpicxx -o caller caller.o -$(pkg-config --libs liblammps) .. tab:: Traditional make @@ -155,8 +155,8 @@ POEMS package installed becomes: .. code-block:: bash - mpicc -c -O $(pkgconf liblammps --cflags) caller.c - mpicxx -o caller caller.o -$(pkgconf --libs) + mpicc -c -O $(pkg-config --cflags liblammps) caller.c + mpicxx -o caller caller.o -$(pkg-config --libs liblammps) .. tab:: Traditional make diff --git a/doc/src/Build_package.rst b/doc/src/Build_package.rst index 63ccac534d..b70a1ca4d1 100644 --- a/doc/src/Build_package.rst +++ b/doc/src/Build_package.rst @@ -62,6 +62,7 @@ packages: * :ref:`POEMS ` * :ref:`PYTHON ` * :ref:`QMMM ` + * :ref:`RHEO ` * :ref:`SCAFACOS ` * :ref:`VORONOI ` * :ref:`VTK ` diff --git a/doc/src/Commands_bond.rst b/doc/src/Commands_bond.rst index 73235cf3c6..eec6f7acf1 100644 --- a/doc/src/Commands_bond.rst +++ b/doc/src/Commands_bond.rst @@ -54,6 +54,7 @@ OPT. * :doc:`oxdna2/fene ` * :doc:`oxrna2/fene ` * :doc:`quartic (o) ` + * :doc:`rheo/shell ` * :doc:`special ` * :doc:`table (o) ` diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst index 0352ad5374..e5ec34fc22 100644 --- a/doc/src/Commands_compute.rst +++ b/doc/src/Commands_compute.rst @@ -108,6 +108,10 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`pe/mol/tally ` * :doc:`pe/tally ` * :doc:`plasticity/atom ` + * :doc:`pod/atom ` + * :doc:`podd/atom ` + * :doc:`pod/local ` + * :doc:`pod/global ` * :doc:`pressure ` * :doc:`pressure/alchemy ` * :doc:`pressure/uef ` @@ -122,6 +126,7 @@ KOKKOS, o = OPENMP, t = OPT. * :doc:`reduce ` * :doc:`reduce/chunk ` * :doc:`reduce/region ` + * :doc:`rheo/property/atom ` * :doc:`rigid/local ` * :doc:`saed ` * :doc:`slcsa/atom ` diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst index a7648218fa..4350a98b31 100644 --- a/doc/src/Commands_fix.rst +++ b/doc/src/Commands_fix.rst @@ -28,6 +28,7 @@ OPT. * :doc:`adapt ` * :doc:`adapt/fep ` * :doc:`addforce ` + * :doc:`add/heat ` * :doc:`addtorque ` * :doc:`alchemy ` * :doc:`amoeba/bitorsion ` @@ -204,6 +205,11 @@ OPT. * :doc:`reaxff/species (k) ` * :doc:`recenter ` * :doc:`restrain ` + * :doc:`rheo ` + * :doc:`rheo/oxidation ` + * :doc:`rheo/pressure ` + * :doc:`rheo/thermal ` + * :doc:`rheo/viscosity ` * :doc:`rhok ` * :doc:`rigid (o) ` * :doc:`rigid/meso ` diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst index d357595d64..a1b2a78fdb 100644 --- a/doc/src/Commands_pair.rst +++ b/doc/src/Commands_pair.rst @@ -35,6 +35,10 @@ OPT. * * * + * + * + * + * * :doc:`adp (ko) ` * :doc:`agni (o) ` * :doc:`aip/water/2dm (t) ` @@ -247,7 +251,7 @@ OPT. * :doc:`pace (k) ` * :doc:`pace/extrapolation (k) ` * :doc:`pedone (o) ` - * :doc:`pod ` + * :doc:`pod (k) ` * :doc:`peri/eps ` * :doc:`peri/lps (o) ` * :doc:`peri/pmb (o) ` @@ -260,6 +264,8 @@ OPT. * :doc:`rebo (io) ` * :doc:`rebomos (o) ` * :doc:`resquared (go) ` + * :doc:`rheo ` + * :doc:`rheo/solid ` * :doc:`saip/metal (t) ` * :doc:`sdpd/taitwater/isothermal ` * :doc:`smatb ` diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst index e37f8755d7..f902a61515 100644 --- a/doc/src/Commands_removed.rst +++ b/doc/src/Commands_removed.rst @@ -8,6 +8,18 @@ stop LAMMPS and print a suitable error message in most cases, when a style/command is used that has been removed or will replace the command with the direct alternative (if available) and print a warning. +restart2data tool +----------------- + +.. versionchanged:: 23Nov2013 + +The functionality of the restart2data tool has been folded into the +LAMMPS executable directly instead of having a separate tool. A +combination of the commands :doc:`read_restart ` and +:doc:`write_data ` can be used to the same effect. For +added convenience this conversion can also be triggered by +:doc:`command line flags ` + Fix ave/spatial and fix ave/spatial/sphere ------------------------------------------ @@ -151,17 +163,16 @@ and allow running LAMMPS with GPU acceleration. i-PI tool --------- -.. versionchanged:: TBD +.. versionchanged:: 27Jun2024 The i-PI tool has been removed from the LAMMPS distribution. Instead, -instructions to install i-PI from PyPi via pip are provided. +instructions to install i-PI from PyPI via pip are provided. -restart2data tool ------------------ +LAMMPS shell +------------ + +.. versionchanged:: TBD + +The LAMMPS shell has been removed from the LAMMPS distribution. Users +are encouraged to use the :ref:`LAMMPS-GUI ` tool instead. -The functionality of the restart2data tool has been folded into the -LAMMPS executable directly instead of having a separate tool. A -combination of the commands :doc:`read_restart ` and -:doc:`write_data ` can be used to the same effect. For -added convenience this conversion can also be triggered by -:doc:`command line flags ` diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst index 76e90e17ba..2923e5b29c 100644 --- a/doc/src/Developer_utils.rst +++ b/doc/src/Developer_utils.rst @@ -211,6 +211,9 @@ Argument processing .. doxygenfunction:: bounds :project: progguide +.. doxygenfunction:: bounds_typelabel + :project: progguide + .. doxygenfunction:: expand_args :project: progguide diff --git a/doc/src/Developer_write_pair.rst b/doc/src/Developer_write_pair.rst index d70f8ec50b..c286b9e1dd 100644 --- a/doc/src/Developer_write_pair.rst +++ b/doc/src/Developer_write_pair.rst @@ -50,6 +50,30 @@ We are looking at the following cases: - `Case 3: a potential requiring communication`_ - `Case 4: potentials without a compute() function`_ +Package and build system considerations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, new pair styles should be added to the :ref:`EXTRA-PAIR +package ` unless they are an accelerated pair style and +then they should be added to the corresponding accelerator package +(:ref:`GPU `, :ref:`INTEL `, :ref:`KOKKOS +`, :ref:`OPENMP `, :ref:`OPT `). If +you feel that your contribution should be added to a different package, +please consult with the LAMMPS developers first. + +The contributed code needs to support the :doc:`traditional GNU make +build process ` **and** the :doc:`CMake build process +`. For the GNU make process and if the package has an +``Install.sh`` file, most likely that file needs to be updated to +correctly copy the sources when installing the package and properly +delete them when uninstalling. This is particularly important when +added a new pair style that is a derived class from an existing pair +style in a package, so that its installation depends on the the +installation status of the package of the derived class. For the CMake +process, it is sometimes necessary to make changes to the package +specific CMake scripting in ``cmake/Modules/Packages``. + + ---- Case 1: a pairwise additive model diff --git a/doc/src/Examples.rst b/doc/src/Examples.rst index c5da4a498b..3d2103fd6f 100644 --- a/doc/src/Examples.rst +++ b/doc/src/Examples.rst @@ -134,6 +134,8 @@ Lowercase directories +-------------+------------------------------------------------------------------+ | rerun | use of rerun and read_dump commands | +-------------+------------------------------------------------------------------+ +| rheo | RHEO simulations of fluid flows and phase transitions | ++-------------+------------------------------------------------------------------+ | rigid | rigid bodies modeled as independent or coupled | +-------------+------------------------------------------------------------------+ | shear | sideways shear applied to 2d solid, with and without a void | diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst index cea70dd3af..3b12ff2117 100644 --- a/doc/src/Fortran.rst +++ b/doc/src/Fortran.rst @@ -2327,7 +2327,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type retrieved via :f:func:`get_last_error_message`. This allows to restart a calculation or delete and recreate the LAMMPS instance when a C++ exception occurs. One application of using exceptions this way - is the :ref:`lammps_shell`. + is the :ref:`lammps_gui`. :to: :cpp:func:`lammps_config_has_exceptions` :r has_exceptions: diff --git a/doc/src/Howto.rst b/doc/src/Howto.rst index 85c98bd6de..5a63e2b1c4 100644 --- a/doc/src/Howto.rst +++ b/doc/src/Howto.rst @@ -89,6 +89,7 @@ Packages howto Howto_drude2 Howto_peri Howto_manifold + Howto_rheo Howto_spins Tutorials howto diff --git a/doc/src/Howto_bioFF.rst b/doc/src/Howto_bioFF.rst index 8899f7520c..7418a43861 100644 --- a/doc/src/Howto_bioFF.rst +++ b/doc/src/Howto_bioFF.rst @@ -1,6 +1,10 @@ CHARMM, AMBER, COMPASS, and DREIDING force fields ================================================= +A compact summary of the concepts, definitions, and properties of +force fields with explicit bonded interactions (like the ones discussed +in this HowTo) is given in :ref:`(Gissinger) `. + A force field has 2 parts: the formulas that define it and the coefficients used for a particular system. Here we only discuss formulas implemented in LAMMPS that correspond to formulas commonly used @@ -11,12 +15,42 @@ commands like :doc:`pair_coeff ` or :doc:`bond_coeff ` and so on. See the :doc:`Tools ` doc page for additional tools that can use CHARMM, AMBER, or Materials Studio generated files to assign force field coefficients and convert their -output into LAMMPS input. +output into LAMMPS input. LAMMPS input scripts can also be generated by +`charmm-gui.org `_. -See :ref:`(MacKerell) ` for a description of the CHARMM -force field. See :ref:`(Cornell) ` for a description of -the AMBER force field. See :ref:`(Sun) ` for a description -of the COMPASS force field. +CHARMM and AMBER +---------------- + +The `CHARMM force field +`_ :ref:`(MacKerell) +` and `AMBER force field +`_ :ref:`(Cornell) ` +have potential energy function of the form + +.. math:: + + V & = \sum_{bonds} E_b + \sum_{angles} \!E_a + \!\overbrace{\sum_{dihedral} \!\!E_d}^{\substack{ + \text{charmm} \\ + \text{charmmfsw} + }} +\!\!\! \sum_{impropers} \!\!\!E_i \\[.6em] + & \quad + \!\!\!\!\!\!\!\!\!\!\underbrace{~\sum_{pairs} \left(E_{LJ}+E_{coul}\right)}_{\substack{ + \text{lj/charmm/coul/charmm} \\ + \text{lj/charmm/coul/charmm/implicit} \\ + \text{lj/charmm/coul/long} \\ + \text{lj/charmm/coul/msm} \\ + \text{lj/charmmfsw/coul/charmmfsh} \\ + \text{lj/charmmfsw/coul/long} + }} \!\!\!\!\!\!\!\!+ \!\!\sum_{special}\! E_s + \!\!\!\!\sum_{residues} \!\!\!{\scriptstyle\mathrm{CMAP}(\phi,\psi)} + + +The terms are computed by bond styles (relationship between 2 atoms), +angle styles (between 3 atoms) , dihedral/improper styles (between 4 +atoms), pair styles (non-covalently bonded pair interactions) and +special bonds. The CMAP term (see :doc:`fix cmap ` command for +details) corrects for pairs of dihedral angles ("Correction MAP") to +significantly improve the structural and dynamic properties of proteins +in crystalline and solution environments :ref:`(Brooks) +`. The AMBER force field does not include the CMAP term. The interaction styles listed below compute force field formulas that are consistent with common options in CHARMM or AMBER. See each @@ -31,10 +65,81 @@ command's documentation for the formula it computes. * :doc:`pair_style ` lj/charmm/coul/charmm * :doc:`pair_style ` lj/charmm/coul/charmm/implicit * :doc:`pair_style ` lj/charmm/coul/long - * :doc:`special_bonds ` charmm * :doc:`special_bonds ` amber +The pair styles compute Lennard Jones (LJ) and Coulombic interactions +with additional switching or shifting functions that ramp the energy +and/or force smoothly to zero between an inner :math:`(a)` and outer +:math:`(b)` cutoff. The older styles with *charmm* (not *charmmfsw* or +*charmmfsh*\ ) in their name compute the LJ and Coulombic interactions +with an energy switching function (esw) S(r) which ramps the energy +smoothly to zero between the inner and outer cutoff. This can cause +irregularities in pairwise forces (due to the discontinuous second +derivative of energy at the boundaries of the switching region), which +in some cases can result in complications in energy minimization and +detectable artifacts in MD simulations. + +.. grid:: 1 1 2 2 + + .. grid-item:: + + .. math:: + + LJ(r) &= 4 \epsilon \left[ \left(\frac{\sigma}{r}\right)^{12} - + \left(\frac{\sigma}{r}\right)^6 \right]\\[.6em] + C(r) &= \frac{C q_i q_j}{ \epsilon r}\\[.6em] + S(r) &= \frac{ \left(b^2 - r^2\right)^2 \left(b^2 + 2r^2 - 3{a^2}\right)} + { \left(b^2 - a^2\right)^3 }\\[.6em] + E_{LJ}(r) &= \begin{cases} + LJ(r), & r \leq a \\ + LJ(r) S(r), & a < r \leq b \\ + 0, &r > b + \end{cases} \\[.6em] + E_{coul}(r) &= \begin{cases} + C(r), & r \leq a \\ + C(r) S(r), & a < r \leq b \\ + 0, & r > b + \end{cases} + + .. grid-item:: + + .. image:: img/howto_charmm_ELJ.png + :align: center + +The newer styles with *charmmfsw* or *charmmfsh* in their name replace +energy switching with force switching (fsw) for LJ interactions and +force shifting (fsh) functions for Coulombic interactions +:ref:`(Steinbach) ` + +.. grid:: 1 1 2 2 + + .. grid-item:: + + .. math:: + + E_{LJ}(r) = & \begin{cases} + 4 \epsilon \sigma^6 \left(\frac{\displaystyle\sigma + ^6-r^6}{\displaystyle r^{12}}-\frac{\displaystyle\sigma ^6}{\displaystyle a^6 + b^6}+\frac{\displaystyle 1}{\displaystyle a^3 b^3}\right) & r\leq a \\ + \frac{\displaystyle 4 \epsilon \sigma^6 \left(\sigma ^6 + \left(b^6-r^6\right)^2-b^3 r^6 \left(a^3+b^3\right) + \left(b^3-r^3\right)^2\right)}{\displaystyle b^6 r^{12} + \left(b^6-a^6\right)} & ab + \end{cases}\\[.6em] + E_{coul}(r) & = \begin{cases} + C(r) \frac{\displaystyle (b-r)^2}{\displaystyle r b^2}, & r \leq b \\ + 0, & r > b + \end{cases} + + .. grid-item:: + .. image:: img/howto_charmmfsw_ELJ.png + :align: center + +These styles are used by LAMMPS input scripts generated by +https://charmm-gui.org/ :ref:`(Brooks) `. + .. note:: For CHARMM, newer *charmmfsw* or *charmmfsh* styles were released in @@ -43,17 +148,33 @@ command's documentation for the formula it computes. ` and :doc:`dihedral charmm ` doc pages. +.. note:: + + The TIP3P water model is strongly recommended for use with the CHARMM + force field. In fact, `"using the SPC model with CHARMM parameters is + a bad idea" + `_ and `"to + enable TIP4P style water in CHARMM, you would have to write a new pair + style" + `_ + . LAMMPS input scripts generated by Solution Builder on https://charmm-gui.org + use TIP3P molecules for solvation. Any other water model can and + probably will lead to false conclusions. + +COMPASS +------- + COMPASS is a general force field for atomistic simulation of common organic molecules, inorganic small molecules, and polymers which was -developed using ab initio and empirical parameterization techniques. -See the :doc:`Tools ` page for the msi2lmp tool for creating -LAMMPS template input and data files from BIOVIA's Materials Studio -files. Please note that the msi2lmp tool is very old and largely -unmaintained, so it does not support all features of Materials Studio -provided force field files, especially additions during the last decade. -You should watch the output carefully and compare results, where -possible. See :ref:`(Sun) ` for a description of the COMPASS force -field. +developed using ab initio and empirical parameterization techniques +:ref:`(Sun) `. See the :doc:`Tools ` page for the +msi2lmp tool for creating LAMMPS template input and data files from +BIOVIA's Materials Studio files. Please note that the msi2lmp tool is +very old and largely unmaintained, so it does not support all features +of Materials Studio provided force field files, especially additions +during the last decade. You should watch the output carefully and +compare results, where possible. See :ref:`(Sun) ` for a +description of the COMPASS force field. These interaction styles listed below compute force field formulas that are consistent with the COMPASS force field. See each command's @@ -70,14 +191,21 @@ documentation for the formula it computes. * :doc:`special_bonds ` lj/coul 0 0 1 -DREIDING is a generic force field developed by the `Goddard group `_ at Caltech and is useful for -predicting structures and dynamics of organic, biological and main-group -inorganic molecules. The philosophy in DREIDING is to use general force -constants and geometry parameters based on simple hybridization -considerations, rather than individual force constants and geometric -parameters that depend on the particular combinations of atoms involved -in the bond, angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond term ` to describe interactions involving a -hydrogen atom on very electronegative atoms (N, O, F). +DREIDING +-------- + +DREIDING is a generic force field developed by the `Goddard group +`_ at Caltech and is useful for predicting +structures and dynamics of organic, biological and main-group inorganic +molecules. The philosophy in DREIDING is to use general force constants +and geometry parameters based on simple hybridization considerations, +rather than individual force constants and geometric parameters that +depend on the particular combinations of atoms involved in the bond, +angle, or torsion terms. DREIDING has an :doc:`explicit hydrogen bond +term ` to describe interactions involving a +hydrogen atom on very electronegative atoms (N, O, F). Unlike CHARMM +or AMBER, the DREIDING force field has not been parameterized for +considering solvents (like water). See :ref:`(Mayo) ` for a description of the DREIDING force field @@ -110,21 +238,31 @@ documentation for the formula it computes. ---------- +.. _Typelabel2: + +**(Gissinger)** J. R. Gissinger, I. Nikiforov, Y. Afshar, B. Waters, M. Choi, D. S. Karls, A. Stukowski, W. Im, H. Heinz, A. Kohlmeyer, and E. B. Tadmor, J Phys Chem B, 128, 3282-3297 (2024). + .. _howto-MacKerell: -**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, -Fischer, Gao, Guo, Ha, et al, J Phys Chem, 102, 3586 (1998). +**(MacKerell)** MacKerell, Bashford, Bellott, Dunbrack, Evanseck, Field, Fischer, Gao, Guo, Ha, et al (1998). J Phys Chem, 102, 3586 . https://doi.org/10.1021/jp973084f .. _howto-Cornell: -**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, -Spellmeyer, Fox, Caldwell, Kollman, JACS 117, 5179-5197 (1995). +**(Cornell)** Cornell, Cieplak, Bayly, Gould, Merz, Ferguson, Spellmeyer, Fox, Caldwell, Kollman (1995). JACS 117, 5179-5197. https://doi.org/10.1021/ja00124a002 + +.. _howto-Steinbach: + +**(Steinbach)** Steinbach, Brooks (1994). J Comput Chem, 15, 667. https://doi.org/10.1002/jcc.540150702 + +.. _howto-Brooks: + +**(Brooks)** Brooks, et al (2009). J Comput Chem, 30, 1545. https://onlinelibrary.wiley.com/doi/10.1002/jcc.21287 .. _howto-Sun: -**(Sun)** Sun, J. Phys. Chem. B, 102, 7338-7364 (1998). +**(Sun)** Sun (1998). J. Phys. Chem. B, 102, 7338-7364. https://doi.org/10.1021/jp980939v .. _howto-Mayo: -**(Mayo)** Mayo, Olfason, Goddard III, J Phys Chem, 94, 8897-8909 -(1990). +**(Mayo)** Mayo, Olfason, Goddard III (1990). J Phys Chem, 94, 8897-8909. https://doi.org/10.1021/j100389a010 + diff --git a/doc/src/Howto_chunk.rst b/doc/src/Howto_chunk.rst index 858e8241d1..f8655b745d 100644 --- a/doc/src/Howto_chunk.rst +++ b/doc/src/Howto_chunk.rst @@ -1,7 +1,7 @@ Use chunks to calculate system properties ========================================= -In LAMMS, "chunks" are collections of atoms, as defined by the +In LAMMPS, "chunks" are collections of atoms, as defined by the :doc:`compute chunk/atom ` command, which assigns each atom to a chunk ID (or to no chunk at all). The number of chunks and the assignment of chunk IDs to atoms can be static or change over @@ -148,14 +148,14 @@ Example calculations with chunks Here are examples using chunk commands to calculate various properties: -(1) Average velocity in each of 1000 2d spatial bins: +1. Average velocity in each of 1000 2d spatial bins: .. code-block:: LAMMPS compute cc1 all chunk/atom bin/2d x 0.0 0.1 y lower 0.01 units reduced fix 1 all ave/chunk 100 10 1000 cc1 vx vy file tmp.out -(2) Temperature in each spatial bin, after subtracting a flow +2. Temperature in each spatial bin, after subtracting a flow velocity: .. code-block:: LAMMPS @@ -164,7 +164,7 @@ velocity: compute vbias all temp/profile 1 0 0 y 10 fix 1 all ave/chunk 100 10 1000 cc1 temp bias vbias file tmp.out -(3) Center of mass of each molecule: +3. Center of mass of each molecule: .. code-block:: LAMMPS @@ -172,7 +172,7 @@ velocity: compute myChunk all com/chunk cc1 fix 1 all ave/time 100 1 100 c_myChunk[*] file tmp.out mode vector -(4) Total force on each molecule and ave/max across all molecules: +4. Total force on each molecule and ave/max across all molecules: .. code-block:: LAMMPS @@ -183,7 +183,7 @@ velocity: thermo 1000 thermo_style custom step temp v_xave v_xmax -(5) Histogram of cluster sizes: +5. Histogram of cluster sizes: .. code-block:: LAMMPS @@ -192,16 +192,16 @@ velocity: compute size all property/chunk cc1 count fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file tmp.histo -(6) An example for using a per-chunk value to apply per-atom forces to +6. An example for using a per-chunk value to apply per-atom forces to compress individual polymer chains (molecules) in a mixture, is explained on the :doc:`compute chunk/spread/atom ` command doc page. -(7) An example for using one set of per-chunk values for molecule +7. An example for using one set of per-chunk values for molecule chunks, to create a second set of micelle-scale chunks (clustered molecules, due to hydrophobicity), is explained on the :doc:`compute reduce/chunk ` command doc page. -(8) An example for using one set of per-chunk values (dipole moment +8. An example for using one set of per-chunk values (dipole moment vectors) for molecule chunks, spreading the values to each atom in each chunk, then defining a second set of chunks as spatial bins, and using the :doc:`fix ave/chunk ` command to calculate an diff --git a/doc/src/Howto_cmake.rst b/doc/src/Howto_cmake.rst index 8b710d1065..55e5b171a6 100644 --- a/doc/src/Howto_cmake.rst +++ b/doc/src/Howto_cmake.rst @@ -339,8 +339,6 @@ Some common LAMMPS specific variables - build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``) * - ``BUILD_TOOLS`` - compile some additional executables from the ``tools`` folder (default: ``off``) - * - ``BUILD_LAMMPS_SHELL`` - - compile the LAMMPS shell from the ``tools/lammps-shell`` folder (default: ``off``) * - ``BUILD_DOC`` - include building the HTML format documentation for packaging/installing (default: ``off``) * - ``CMAKE_TUNE_FLAGS`` diff --git a/doc/src/Howto_lammps_gui.rst b/doc/src/Howto_lammps_gui.rst index 165ed84d95..a91a46ad3c 100644 --- a/doc/src/Howto_lammps_gui.rst +++ b/doc/src/Howto_lammps_gui.rst @@ -1,11 +1,11 @@ -Using the LAMMPS GUI +Using the LAMMPS-GUI ==================== -This document describes **LAMMPS GUI version 1.5**. +This document describes **LAMMPS-GUI version 1.6**. ----- -LAMMPS GUI is a graphical text editor customized for editing LAMMPS +LAMMPS-GUI is a graphical text editor customized for editing LAMMPS input files that is linked to the :ref:`LAMMPS library ` and thus can run LAMMPS directly using the contents of the editor's text buffer as input. It can retrieve and display information from LAMMPS @@ -16,58 +16,60 @@ to the online LAMMPS documentation for known LAMMPS commands and styles. .. note:: - Pre-compiled, ready-to-use LAMMPS GUI executables for Linux (Ubuntu + Pre-compiled, ready-to-use LAMMPS-GUI executables for Linux (Ubuntu 20.04LTS or later and compatible), macOS (version 11 aka Big Sur or later), and Windows (version 10 or later) :ref:`are available - ` for download. They may be linked to a - development version of LAMMPS in case they need features not yet - available in a released version. Serial LAMMPS executables of the - same LAMMPS version are included as well. The source code for the - LAMMPS GUI is included in the LAMMPS source code and can be found in - the ``tools/lammps-gui`` folder. It can be compiled alongside LAMMPS - when :doc:`compiling with CMake `. + ` for download. None-MPI LAMMPS executables of + the same LAMMPS version are included in these packages as well. The + source code for the LAMMPS-GUI is included in the LAMMPS source code + distribution and can be found in the ``tools/lammps-gui`` folder. It + can be compiled alongside LAMMPS when :doc:`compiling with CMake + `. -LAMMPS GUI tries to provide an experience similar to what people -traditionally would do to run LAMMPS using a command line window: +LAMMPS-GUI tries to provide an experience similar to what people +traditionally would do to run LAMMPS using a command line window +but just rolled into a single executable: + +- editing LAMMPS input files with a text editor +- run LAMMPS on those input file with selected command line flags +- use or extract data from the created files and visualize it with + either a molecular visualization program or a plotting program -- editing inputs with a text editor -- run LAMMPS on the input with selected command line flags -- and then use or extract data from the created files and visualize it That procedure is quite effective for people proficient in using the command line, as that allows them to use tools for the individual steps -which they are most comfortable with. It is often required when running -LAMMPS on high-performance computing facilities. +that they are most comfortable with. It is often *required* to adopt +this workflow when running LAMMPS simulations on high-performance +computing facilities. -The main benefit of using the LAMMPS GUI application instead is that +The main benefit of using the LAMMPS-GUI application instead is that many basic tasks can be done directly from the GUI without switching to a text console window or using external programs, let alone writing scripts to extract data from the generated output. It also integrates well with graphical desktop environments. -LAMMPS GUI thus makes it easier for beginners to get started running +LAMMPS-GUI thus makes it easier for beginners to get started running simple LAMMPS simulations. It is very suitable for tutorials on LAMMPS since you only need to learn how to use a single program for most tasks and thus time can be saved and people can focus on learning LAMMPS. It is also designed to keep the barrier low when you decide to switch to a full featured, standalone programming editor and more sophisticated -visualization and analysis tools and run LAMMPS from a command line. +visualization and analysis tools, and run LAMMPS from the command line +or a batch script. The following text provides a detailed tour of the features and -functionality of the LAMMPS GUI. - -Suggestions for new features and reports of bugs are always welcome. -You can use the :doc:`the same channels as for LAMMPS itself -` for that purpose. +functionality of the LAMMPS-GUI. Suggestions for new features and +reports of bugs are always welcome. You can use the :doc:`the same +channels as for LAMMPS itself ` for that purpose. ----- -Main window ------------ +Starting LAMMPS-GUI +------------------- -When LAMMPS GUI starts, it will show a main window with either an -empty buffer or the contents of a loaded file. In the latter case it -may look like the following: +When LAMMPS-GUI starts, it shows the main window, labeled *Editor*, with +either an empty buffer or the contents of the file used as argument. In +the latter case it may look like the following: .. image:: JPG/lammps-gui-main.png :align: center @@ -80,32 +82,34 @@ the LAMMPS input file syntax. The status bar shows the status of LAMMPS execution on the left (e.g. "Ready." when idle) and the current working directory on the right. The name of the current file in the buffer is shown in the window title; the word `*modified*` is added if -the buffer edits have not yet saved to a file. The size of the main -window will be stored when exiting and restored when starting again. +the buffer edits have not yet saved to a file. The geometry of the main +window is stored when exiting and restored when starting again. Opening Files ^^^^^^^^^^^^^ -The LAMMPS GUI application will try to open the first command line -argument as a LAMMPS input script, further arguments are ignored. -When no argument is given, LAMMPS GUI will start with an empty buffer. -Files can also be opened via the ``File`` menu or by drag-and-drop of -a file from a graphical file manager into the editor window. Only one -file can be open at a time, so opening a new file with a filled buffer -will close the buffer. If the buffer has unsaved modifications, you -will be asked to either cancel the operation, discard the changes, or -save them. +The LAMMPS-GUI application tries to open the first command line argument +as a LAMMPS input script, further arguments are ignored. When no +argument is given, LAMMPS-GUI starts with an empty buffer. Files can +also be opened via the ``File`` menu or by drag-and-drop of a file from +a graphical file manager into the editor window. Only one file can be +edited at a time, so opening a new file with a filled buffer closes that +buffer. If the buffer has unsaved modifications, you are asked to +either cancel the operation, discard the changes, or save them. A +buffer with modifications can be saved any time from the "File" menu, by +the keyboard shortcut `Ctrl-S` (`Command-S` on macOS), or by clicking on +the "Save" button at the very left in the status bar. Running LAMMPS ^^^^^^^^^^^^^^ -From within the LAMMPS GUI main window LAMMPS can be started either from +From within the LAMMPS-GUI main window LAMMPS can be started either from the ``Run`` menu using the ``Run LAMMPS from Editor Buffer`` entry, by the keyboard shortcut `Ctrl-Enter` (`Command-Enter` on macOS), or by clicking on the green "Run" button in the status bar. All of these -operations will cause LAMMPS to process the entire input script, which -may contain multiple :doc:`run ` or :doc:`minimize ` -commands. +operations causes LAMMPS to process the entire input script in the +editor buffer, which may contain multiple :doc:`run ` or +:doc:`minimize ` commands. LAMMPS runs in a separate thread, so the GUI stays responsive and is able to interact with the running calculation and access data it @@ -128,33 +132,30 @@ before LAMMPS can be run from a file. While LAMMPS is running, the contents of the status bar change. On the left side there is a text indicating that LAMMPS is running, which -will also show the number of active threads, if thread-parallel +also indicates the number of active threads, when thread-parallel acceleration was selected in the ``Preferences`` dialog. On the right side, a progress bar is shown that displays the estimated progress for -the current :doc:`run command `. +the current :doc:`run ` or :doc:`minimize ` command. -Also, the line number of the currently executed command will be -highlighted in green. - -.. image:: JPG/lammps-gui-run-highlight.png - :align: center - :scale: 75% +Also, the line number of the currently executed command is highlighted +in green. If an error occurs (in the example below the command :doc:`label