diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 59a937faba..d1617cbb25 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -50,6 +50,7 @@ src/PTM/* @pmla
src/QMMM/* @akohlmey
src/REACTION/* @jrgissing
src/REAXFF/* @hasanmetin @stanmoore1
+src/RHEO/* @jtclemm
src/SCAFACOS/* @rhalver
src/SNAP/* @athomps
src/SPIN/* @julient31
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index fbe56e99a1..5b29fb6047 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -164,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)
@@ -198,7 +214,6 @@ 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
@@ -495,6 +510,14 @@ if(PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR BUILD_T
endif()
endif()
+find_package(CURL QUIET COMPONENTS HTTP HTTPS)
+option(WITH_CURL "Enable libcurl support" ${CURL_FOUND})
+if(WITH_CURL)
+ find_package(CURL REQUIRED COMPONENTS HTTP HTTPS)
+ target_compile_definitions(lammps PRIVATE -DLAMMPS_CURL)
+ target_link_libraries(lammps PRIVATE CURL::libcurl)
+endif()
+
# tweak jpeg library names to avoid linker errors with MinGW cross-compilation
set(JPEG_NAMES libjpeg libjpeg-62)
find_package(JPEG QUIET)
@@ -872,7 +895,7 @@ endif()
include(Testing)
include(CodeCoverage)
include(CodingStandard)
-find_package(ClangFormat 8.0)
+find_package(ClangFormat 11.0)
if(ClangFormat_FOUND)
add_custom_target(format-src
@@ -1049,9 +1072,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/FindClangFormat.cmake b/cmake/Modules/FindClangFormat.cmake
index 3f0257f34f..24fad5b6a8 100644
--- a/cmake/Modules/FindClangFormat.cmake
+++ b/cmake/Modules/FindClangFormat.cmake
@@ -1,5 +1,8 @@
# Find clang-format
find_program(ClangFormat_EXECUTABLE NAMES clang-format
+ clang-format-20.0
+ clang-format-19.0
+ clang-format-18.0
clang-format-17.0
clang-format-16.0
clang-format-15.0
diff --git a/cmake/Modules/LAMMPSUtils.cmake b/cmake/Modules/LAMMPSUtils.cmake
index 2ec9d1b706..223577fe31 100644
--- a/cmake/Modules/LAMMPSUtils.cmake
+++ b/cmake/Modules/LAMMPSUtils.cmake
@@ -32,7 +32,13 @@ function(check_omp_h_include)
set(CMAKE_REQUIRED_INCLUDES ${OpenMP_CXX_INCLUDE_DIRS})
set(CMAKE_REQUIRED_LINK_OPTIONS ${OpenMP_CXX_FLAGS})
set(CMAKE_REQUIRED_LIBRARIES ${OpenMP_CXX_LIBRARIES})
- check_include_file_cxx(omp.h _have_omp_h)
+ # there are all kinds of problems with finding omp.h
+ # for Clang and derived compilers so we pretend it is there.
+ if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+ set(_have_omp_h TRUE)
+ else()
+ check_include_file_cxx(omp.h _have_omp_h)
+ endif()
else()
set(_have_omp_h FALSE)
endif()
diff --git a/cmake/Modules/Packages/COLVARS.cmake b/cmake/Modules/Packages/COLVARS.cmake
index 745c1de026..b943a0345e 100644
--- a/cmake/Modules/Packages/COLVARS.cmake
+++ b/cmake/Modules/Packages/COLVARS.cmake
@@ -24,6 +24,12 @@ target_include_directories(colvars PUBLIC ${LAMMPS_LIB_SOURCE_DIR}/colvars)
target_include_directories(colvars PRIVATE ${LAMMPS_SOURCE_DIR})
target_link_libraries(lammps PRIVATE colvars)
+if(BUILD_OMP)
+ # Enable OpenMP for Colvars as well
+ target_compile_options(colvars PRIVATE ${OpenMP_CXX_FLAGS})
+ target_link_libraries(colvars PRIVATE OpenMP::OpenMP_CXX)
+endif()
+
if(COLVARS_DEBUG)
# Need to export the define publicly to be valid in interface code
target_compile_definitions(colvars PUBLIC -DCOLVARS_DEBUG)
diff --git a/cmake/Modules/Packages/RHEO.cmake b/cmake/Modules/Packages/RHEO.cmake
index be8c22877b..7639acd8bc 100644
--- a/cmake/Modules/Packages/RHEO.cmake
+++ b/cmake/Modules/Packages/RHEO.cmake
@@ -1,2 +1,2 @@
-find_package(GSL 2.7 REQUIRED)
+find_package(GSL 2.6 REQUIRED)
target_link_libraries(lammps PRIVATE GSL::gsl)
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/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 8e103b089a..e95c5b97d9 100644
--- a/doc/src/Build_development.rst
+++ b/doc/src/Build_development.rst
@@ -153,7 +153,12 @@ development headers to compile (if those are not found locally a recent
version of that library will be downloaded and compiled along with
LAMMPS and the test programs) and will download and compile a specific
version of the `GoogleTest ` command
* `Size of LAMMPS integer types and size limits`_
* `Read or write compressed files`_
-* `Output of JPG, PNG, and move files` via the :doc:`dump image ` or :doc:`dump movie ` commands
+* `Output of JPEG, PNG, and movie files`_ via the :doc:`dump image ` or :doc:`dump movie ` commands
+* `Support for downloading files`_
* `Memory allocation alignment`_
* `Workaround for long long integers`_
* `Exception handling when using LAMMPS as a library`_ to capture errors
@@ -19,7 +20,7 @@ explains how to do this for building both with CMake and make.
.. _cxx11:
C++11 standard compliance
-------------------------------------------
+-------------------------
A C++11 standard compatible compiler is a requirement for compiling LAMMPS.
LAMMPS version 3 March 2020 is the last version compatible with the previous
@@ -31,12 +32,16 @@ flags to enable C++11 compliance. Example for GNU c++ 4.8.x:
CCFLAGS = -g -O3 -std=c++11
+Individual packages may require compliance with a later C++ standard
+like C++14 or C++17. These requirements will be documented with the
+:doc:`individual packages `.
+
----------
.. _fft:
FFT library
----------------------
+-----------
When the KSPACE package is included in a LAMMPS build, the
:doc:`kspace_style pppm ` command performs 3d FFTs which
@@ -341,8 +346,8 @@ in whichever ``lib/gpu/Makefile`` is used must be the same as above.
.. _graphics:
-Output of JPG, PNG, and movie files
---------------------------------------------------
+Output of JPEG, PNG, and movie files
+------------------------------------
The :doc:`dump image ` command has options to output JPEG or
PNG image files. Likewise, the :doc:`dump movie ` command
@@ -356,9 +361,9 @@ requires the following settings:
.. code-block:: bash
-D WITH_JPEG=value # yes or no
- # default = yes if CMake finds JPEG files, else no
+ # default = yes if CMake finds JPEG development files, else no
-D WITH_PNG=value # yes or no
- # default = yes if CMake finds PNG and ZLIB files, else no
+ # default = yes if CMake finds PNG and ZLIB development files, else no
-D WITH_FFMPEG=value # yes or no
# default = yes if CMake can find ffmpeg, else no
@@ -414,8 +419,8 @@ Read or write compressed files
If this option is enabled, large files can be read or written with
compression by ``gzip`` or similar tools by several LAMMPS commands,
including :doc:`read_data `, :doc:`rerun `, and
-:doc:`dump `. Supported compression tools are currently
-``gzip``, ``bzip2``, ``zstd``, and ``lzma``.
+:doc:`dump `. Supported compression tools and algorithms are currently
+``gzip``, ``bzip2``, ``zstd``, ``xz``, ``lz4``, and ``lzma`` (via xz).
.. tabs::
@@ -446,12 +451,58 @@ during a run.
available using a compression library instead, which is what the
:ref:`COMPRESS package ` enables.
+--------------------------------------------------
+
+.. _libcurl:
+
+Support for downloading files
+-----------------------------
+
+.. versionadded:: TBD
+
+The :doc:`geturl command ` command uses the `the libcurl library
+
+
+ CURL_INC = -I/usr/local/include # path to curl folder with curl.h
+ CURL_PATH = -L/usr/lib # paths to libcurl.a(.so) if make cannot find it
+ CURL_LIB = -lcurl # library names
+
+ As with CMake, you do not need to set ``CURL_INC`` or ``CURL_PATH``,
+ if make can find the libcurl header and library files in their
+ default system locations. You must specify ``CURL_LIB`` with a
+ paths or linker flags to link to libcurl.
+
----------
.. _align:
Memory allocation alignment
----------------------------------------
+---------------------------
This setting enables the use of the "posix_memalign()" call instead of
"malloc()" when LAMMPS allocates large chunks of memory. Vector
diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst
index 4a035f5b41..cb31369501 100644
--- a/doc/src/Commands_all.rst
+++ b/doc/src/Commands_all.rst
@@ -54,6 +54,7 @@ table above.
* :doc:`echo `
* :doc:`fix `
* :doc:`fix_modify `
+ * :doc:`geturl `
* :doc:`group `
* :doc:`if `
* :doc:`improper_coeff `
diff --git a/doc/src/Commands_bond.rst b/doc/src/Commands_bond.rst
index eec6f7acf1..2664b74076 100644
--- a/doc/src/Commands_bond.rst
+++ b/doc/src/Commands_bond.rst
@@ -73,7 +73,7 @@ OPT.
* :doc:`none `
* :doc:`zero `
- * :doc:`hybrid `
+ * :doc:`hybrid (k) `
*
*
*
@@ -101,7 +101,7 @@ OPT.
* :doc:`mesocnt `
* :doc:`mm3 `
* :doc:`quartic (o) `
- * :doc:`spica (o) `
+ * :doc:`spica (ko) `
* :doc:`table (o) `
.. _dihedral:
@@ -119,7 +119,7 @@ OPT.
* :doc:`none `
* :doc:`zero `
- * :doc:`hybrid `
+ * :doc:`hybrid (k) `
*
*
*
@@ -157,7 +157,7 @@ OPT.
* :doc:`none `
* :doc:`zero `
- * :doc:`hybrid `
+ * :doc:`hybrid (k) `
*
*
*
diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst
index a1b2a78fdb..9cf0495c8e 100644
--- a/doc/src/Commands_pair.rst
+++ b/doc/src/Commands_pair.rst
@@ -195,7 +195,7 @@ OPT.
* :doc:`lj/mdf `
* :doc:`lj/relres (o) `
* :doc:`lj/spica (gko) `
- * :doc:`lj/spica/coul/long (go) `
+ * :doc:`lj/spica/coul/long (gko) `
* :doc:`lj/spica/coul/msm (o) `
* :doc:`lj/sf/dipole/sf (go) `
* :doc:`lj/smooth (go) `
diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst
index 4955bc6f0b..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:: 27June2024
+.. 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.
-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/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_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 6faac96ce9..85f0210f99 100644
--- a/doc/src/Howto_lammps_gui.rst
+++ b/doc/src/Howto_lammps_gui.rst
@@ -1,11 +1,11 @@
-Using the LAMMPS GUI
-====================
+Using 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,123 @@ to the online LAMMPS documentation for known LAMMPS commands and styles.
.. note::
- 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 `.
+ Pre-compiled, ready-to-use LAMMPS-GUI executables for Linux x86\_64
+ (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. None-MPI LAMMPS executables for
+ running LAMMPS from the command line and :doc:`some LAMMPS tools `
+ are also included.
-LAMMPS GUI tries to provide an experience similar to what people
-traditionally would do to run LAMMPS using a command line window:
+ The source code for 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
+ `.
-- 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
+LAMMPS-GUI tries to provide an experience similar to what people
+traditionally would have running LAMMPS using a command line window
+and the console LAMMPS executable but just rolled into a single executable:
+
+- writing & 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
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
-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.
+The main benefit of using LAMMPS-GUI 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 where the `.lmp` filename extension can be registered with
+LAMMPS-GUI as the executable to launch when double clicking on such
+files. Also, LAMMPS-GUI has support for drag-n-drop, i.e. an input
+file can be selected and then moved and dropped on the LAMMPS-GUI
+executable, and LAMMPS-GUI will launch and read the file into its
+buffer.
-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.
+and thus time can be saved and people can focus on learning LAMMPS.
+The tutorials at https://lammpstutorials.github.io/ were specifically
+updated for use with LAMMPS-GUI.
+
+Another design goal is to keep the barrier low when replacing part of
+the functionality of LAMMPS-GUI with external tools.
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 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
------------
+Installing Pre-compiled LAMMPS-GUI Packages
+-------------------------------------------
-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:
+LAMMPS-GUI is available as pre-compiled binary packages for Linux
+x86\_64, macOS 11 and later, and Windows 10 and later. Alternately, it
+can be compiled from source.
+
+Windows 10 and later
+^^^^^^^^^^^^^^^^^^^^
+
+After downloading the ``LAMMPS-Win10-64bit-GUI-.exe`` installer
+package, you need to execute it, and start the installation process.
+Since those packages are currently unsigned, you have to enable "Developer Mode"
+in the Windows System Settings to run the installer.
+
+MacOS 11 and later
+^^^^^^^^^^^^^^^^^^
+
+After downloading the ``LAMMPS-macOS-multiarch-GUI-.dmg``
+installer package, you need to double-click it and then, in the window
+that opens, drag the app bundle as indicated into the "Applications"
+folder. The follow the instructions in the "README.txt" file to
+get access to the other included executables.
+
+Linux on x86\_64
+^^^^^^^^^^^^^^^^
+
+For Linux with x86\_64 CPU there are currently two variants. The first
+is compiled on Ubuntu 20.04LTS, is using some wrapper scripts, and
+should be compatible with more recent Linux distributions. After
+downloading and unpacking the
+``LAMMPS-Linux-x86_64-GUI-.tar.gz`` package. You can switch
+into the "LAMMPS_GUI" folder and execute "./lammps-gui" directly.
+
+The second variant uses `flatpak `_ and
+requires the flatpak management and runtime software to be installed.
+After downloading the ``LAMMPS-GUI-Linux-x86_64-GUI-.tar.gz``
+flatpak bundle, you can install it with ``flatpak install --user
+LAMMPS-GUI-Linux-x86_64-GUI-.tar.gz``. After installation,
+LAMMPS-GUI should be integrated into your desktop environment under
+"Applications > Science" but also can be launched from the console with
+``flatpak run org.lammps.lammps-gui``. The flatpak bundle also includes
+the console LAMMPS executable ``lmp`` which can be launched to run
+simulations with, for example: ``flatpak run --command=lmp
+org.lammps.lammps-gui -in in.melt``.
+
+
+Compiling from Source
+^^^^^^^^^^^^^^^^^^^^^
+
+There also are instructions for :ref:`compiling LAMMPS-GUI from source
+code ` available elsewhere in the manual.
+Compilation from source *requires* using CMake.
+
+-----
+
+Starting LAMMPS-GUI
+-------------------
+
+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 +145,41 @@ 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 can be launched without command line arguments
+and then starts with an empty buffer in the *Editor* window. If arguments
+are given LAMMPS will use first command line argument as the file name for
+the *Editor* buffer and reads its contents into the buffer, if the file
+exists. All further arguments are ignored. Files can also be opened via
+the ``File`` menu, the `Ctrl-O` (`Command-O` on macOS) keyboard shortcut
+or by drag-and-drop of a file from a graphical file manager into the editor
+window. If a file extension (e.g. ``.lmp``) has been registered with the
+graphical environment to launch LAMMPS-GUI, an existing input file can
+be launched with LAMMPS-GUI through double clicking.
+
+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 +202,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
` was incorrectly capitalized as "Label"), an error message
-dialog will be shown and the line of the input which triggered the
-error will be highlighted. The state of LAMMPS in the status bar will
-be set to "Failed." instead of "Ready."
+dialog is shown and the line of the input which triggered the error is
+highlighted. The state of LAMMPS in the status bar is set to "Failed."
+instead of "Ready."
.. image:: JPG/lammps-gui-run-error.png
:align: center
:scale: 75%
-Up to three additional windows will open during a run:
+Up to three additional windows may open during a run:
-- a log window with the captured screen output
-- a chart window with a line graph created from the thermodynamic output of the run
-- a slide show window with images created by a :doc:`dump image command `
+- an *Output* window with the captured screen output from LAMMPS
+- a *Charts* window with a line graph created from thermodynamic output of the run
+- a *Slide Show* window with images created by a :doc:`dump image command `
+ in the input
More information on those windows and how to adjust their behavior and
contents is given below.
@@ -171,77 +242,101 @@ This is equivalent to the input script command :doc:`timer timeout 0
interface. Please see the corresponding documentation pages to
understand the implications of this operation.
-Log Window
-----------
+Output Window
+-------------
-By default, when starting a run, a "Log Window" will open that displays
-the current screen output of the LAMMPS calculation, that would normally
-be seen in the command line window, as shown below.
+By default, when starting a run, an *Output* window opens that displays
+the screen output of the running LAMMPS calculation, as shown below.
+This text would normally be seen in the command line window.
.. image:: JPG/lammps-gui-log.png
:align: center
:scale: 50%
-LAMMPS GUI captures the screen output as it is generated and updates
-the log window regularly during a run.
+LAMMPS-GUI captures the screen output from LAMMPS as it is generated and
+updates the *Output* window regularly during a run.
-By default, the log window will be replaced each time a run is started.
+By default, the *Output* window is replaced each time a run is started.
The runs are counted and the run number for the current run is displayed
-in the window title. It is possible to change the behavior of LAMMPS
-GUI in the preferences dialog to create a *new* log window for every run
-or to not show the current log window. It is also possible to show or
-hide the *current* log window from the ``View`` menu.
+in the window title. It is possible to change the behavior of
+LAMMPS-GUI in the preferences dialog to create a *new* *Output* window
+for every run or to not show the current *Output* window. It is also
+possible to show or hide the *current* *Output* window from the ``View``
+menu.
-The text in the log window is read-only and cannot be modified, but
+The text in the *Output* window is read-only and cannot be modified, but
keyboard shortcuts to select and copy all or parts of the text can be
used to transfer text to another program. Also, the keyboard shortcut
-`Ctrl-S` (`Command-S` on macOS) is available to save the log buffer to a
+`Ctrl-S` (`Command-S` on macOS) is available to save the *Output* buffer to a
file. The "Select All" and "Copy" functions, as well as a "Save Log to
File" option are also available from a context menu by clicking with the
-right mouse button into the log window text area.
+right mouse button into the *Output* window text area.
-Chart Window
-------------
-
-By default, when starting a run, a "Chart Window" will open that
-displays a plot of thermodynamic output of the LAMMPS calculation as
-shown below.
-
-.. image:: JPG/lammps-gui-chart.png
+.. image:: JPG/lammps-gui-yaml.png
:align: center
:scale: 50%
+.. versionadded:: 1.6
+
+Should the *Output* window contain embedded YAML format text (see above for a
+demonstration), for example from using :doc:`thermo_style yaml
+` or :doc:`thermo_modify line yaml `, the
+keyboard shortcut `Ctrl-Y` (`Command-Y` on macOS) is available to save
+only the YAML parts to a file. This option is also available from a
+context menu by clicking with the right mouse button into the *Output* window
+text area.
+
+Charts Window
+-------------
+
+By default, when starting a run, a *Charts* window opens that displays a
+plot of thermodynamic output of the LAMMPS calculation as shown below.
+
+.. image:: JPG/lammps-gui-chart.png
+ :align: center
+ :scale: 33%
+
The drop down menu on the top right allows selection of different
properties that are computed and written to thermo output. Only one
-property can be shown at a time. The plots will be updated with new
-data as the run progresses, so they can be used to visually monitor the
-evolution of available properties. The window title will show the
-current run number that this chart window corresponds to. Same as
-explained for the log window above, by default, the chart window will
-be replaced on each new run, but the behavior can be changed in the
-preferences dialog.
+property can be shown at a time. The plots are updated with new data as
+the run progresses, so they can be used to visually monitor the
+evolution of available properties. The window title shows the current
+run number that this chart window corresponds to. Same as for the
+*Output* window, the chart window is replaced on each new run, but the
+behavior can be changed in the preferences dialog.
+
+.. versionadded:: 1.6
+
+ Support for YAML export added
From the ``File`` menu on the top left, it is possible to save an image
of the currently displayed plot or export the data in either plain text
columns (for use by plotting tools like `gnuplot
`
-or a :doc:`thermo_modify ` command, or the current time
-step is reset with :doc:`reset_timestep `, or if a
-:doc:`clear ` command is issued.
+Thermo output data from successive run commands in the input script is
+combined into a single data set unless the format, number, or names of
+output columns are changed with a :doc:`thermo_style ` or
+a :doc:`thermo_modify ` command, or the current time step
+is reset with :doc:`reset_timestep `, or if a
+:doc:`clear ` command is issued. This is where the YAML export
+from the *Charts* window differs from that of the *Output* window:
+here you get the compounded data set starting with the last change of
+output fields or timestep setting, while the export from the log will
+contain *all* YAML output but *segmented* into individual runs.
Image Slide Show
----------------
By default, if the LAMMPS input contains a :doc:`dump image
-` command, a "Slide Show" window will open which loads and
-displays the images created by LAMMPS as they are written.
+` command, a "Slide Show" window opens which loads and
+displays the images created by LAMMPS as they are written. This is a
+convenient way to visually monitor the progress of the simulation.
.. image:: JPG/lammps-gui-slideshow.png
:align: center
@@ -250,9 +345,17 @@ displays the images created by LAMMPS as they are written.
The various buttons at the bottom right of the window allow single
stepping through the sequence of images or playing an animation (as a
continuous loop or once from first to last). It is also possible to
-zoom in or zoom out of the displayed images, and to export the slide
-show animation to a movie file, if `ffmpeg ` command in a separate window as shown
+the `Ctrl-Shift-W` keyboard shortcut. This shows info similar to the
+:doc:`info variables ` command in a separate window as shown
below.
.. image:: JPG/lammps-gui-variable-info.png
:align: center
:scale: 75%
-Like the log and chart windows, its content is continuously updated
-during a run. It will show "(none)" if there are no variables
+Like for the *Output* and *Charts* windows, its content is continuously
+updated during a run. It will show "(none)" if there are no variables
defined. Note that it is also possible to *set* :doc:`index style
variables `, that would normally be set via command line
flags, via the "Set Variables..." dialog from the ``Run`` menu.
-LAMMPS GUI will automatically set the variable "gui_run" to the
-current value of the run counter. That way it would be possible
-to automatically record a log for each run attempt by using the
-command
+LAMMPS-GUI automatically defines the variable "gui_run" to the current
+value of the run counter. That way it is possible to automatically
+record a separate log for each run attempt by using the command
.. code-block:: LAMMPS
@@ -285,62 +387,93 @@ command
at the beginning of an input file. That would record logs to files
``logfile-1.txt``, ``logfile-2.txt``, and so on for successive runs.
-Viewing Snapshot Images
------------------------
+Snapshot Image Viewer
+---------------------
By selecting the ``Create Image`` entry in the ``Run`` menu, or by
hitting the `Ctrl-I` (`Command-I` on macOS) keyboard shortcut, or by
-clicking on the "palette" button in the status bar, LAMMPS GUI will send
-a custom :doc:`write_dump image ` command to LAMMPS and read
-the resulting snapshot image with the current state of the system into
-an image viewer window. This functionality is not available *during* an
-ongoing run. When LAMMPS is not yet initialized, LAMMPS GUI will try to
-identify the line with the first run or minimize command and execute all
-command up to that line from the input buffer and then add a "run 0"
-command. This will initialize the system so an image of the initial
-state of the system can be rendered. If there was an error, the
-snapshot image viewer will not appear.
+clicking on the "palette" button in the status bar of the *Editor*
+window, LAMMPS-GUI sends a custom :doc:`write_dump image `
+command to LAMMPS and reads back the resulting snapshot image with the
+current state of the system into an image viewer. This functionality is
+*not* available *during* an ongoing run. In case LAMMPS is not yet
+initialized, LAMMPS-GUI tries to identify the line with the first run or
+minimize command and execute all commands from the input buffer up to
+that line, and then executes a "run 0" command. This initializes the
+system so an image of the initial state of the system can be rendered.
+If there was an error in that process, the snapshot image viewer does
+not appear.
-When possible, LAMMPS GUI will try to detect which elements the atoms
-correspond to (via their mass) and then colorize them in the image
-accordingly. Otherwise the default predefined sequence of colors is
-assigned to the different atom types.
+When possible, LAMMPS-GUI tries to detect which elements the atoms
+correspond to (via their mass) and then colorize them in the image and
+set their atom diameters accordingly. If this is not possible, for
+instance when using reduced (= 'lj') :doc:`units `, then
+LAMMPS-GUI will check the current pair style and if it is a
+Lennard-Jones type potential, it will extract the *sigma* parameter
+for each atom type and assign atom diameters from those numbers.
-.. image:: JPG/lammps-gui-image.png
+Otherwise the default sequence of colors of the :doc:`dump image
+` command is assigned to the different atom types and the
+diameters are all the same.
+
+.. figure:: JPG/lammps-gui-image.png
:align: center
:scale: 50%
+ Visualization of LAMMPS "peptide" example
+
+.. versionchanged:: 1.6
+
+ Buttons for toggling shininess and re-centering were added.
+
The default image size, some default image quality settings, the view
style and some colors can be changed in the ``Preferences`` dialog
window. From the image viewer window further adjustments can be made:
actual image size, high-quality (SSAO) rendering, anti-aliasing, view
-style, display of box or axes, zoom factor. The view of the system
-can be rotated horizontally and vertically. It is also possible to
-only display the atoms within a group defined in the input script
-(default is "all"). After each change, the image is rendered again
-and the display updated. The small palette icon on the top left will
-be colored while LAMMPS is running to render the new image; it will be
-grayed out when it is finished. When there are many atoms to render
-and high quality images with anti-aliasing are requested, re-rendering
-may take several seconds. From the ``File`` menu of the image window,
-the current image can be saved to a file or copied into the
-cut-n-paste buffer for pasting into another application.
+style, display of box or axes, zoom factor. The view of the system can
+be rotated horizontally and vertically. It is also possible to only
+display the atoms within a group defined in the input script (default is
+"all"). The image can also be re-centered on the center of mass of the
+selected group. After each change, the image is rendered again and the
+display updated. The small palette icon on the top left is colored
+while LAMMPS is running to render the new image; it is grayed out when
+LAMMPS is finished. When there are many atoms to render and high
+quality images with anti-aliasing are requested, re-rendering may take
+several seconds. From the ``File`` menu of the image window, the
+current image can be saved to a file (keyboard shortcut `Ctrl-S`) or
+copied to the clipboard (keyboard shortcut `Ctrl-C`) for pasting the
+image into another application.
-Editor Functions
-----------------
+.. versionadded:: 1.6
-The editor has most of the usual functionality that similar programs
-have: text selection via mouse or with cursor moves while holding the
-Shift key, Cut (`Ctrl-X`), Copy (`Ctrl-C`), Paste (`Ctrl-V`), Undo
-(`Ctrl-Z`), Redo (`Ctrl-Shift-Z`), Select All (`Ctrl-A`). When trying
-to exit the editor with a modified buffer, a dialog will pop up asking
-whether to cancel the exit operation, or to save or not save the buffer
-contents to a file.
+From the ``File`` menu it is also possible to copy the current
+:doc:`dump image ` and :doc:`dump_modify `
+commands to the clipboard so they can be pasted into a LAMMPS input file
+so that the visualization settings of the snapshot image can be repeated
+for the entire simulation (and thus be repeated in the slide show
+viewer). This feature has the keyboard shortcut `Ctrl-D`.
+
+Editor Window
+-------------
+
+The *Editor* window of LAMMPS-GUI has most of the usual functionality
+that similar programs have: text selection via mouse or with cursor
+moves while holding the Shift key, Cut (`Ctrl-X`), Copy (`Ctrl-C`),
+Paste (`Ctrl-V`), Undo (`Ctrl-Z`), Redo (`Ctrl-Shift-Z`), Select All
+(`Ctrl-A`). When trying to exit the editor with a modified buffer, a
+dialog will pop up asking whether to cancel the exit operation, or to
+save or not save the buffer contents to a file.
+
+.. versionadded:: 1.6
+
+The editor has an auto-save mode that can be enabled or disabled in the
+``Preferences`` dialog. In auto-save mode, the editor buffer is
+automatically saved before running LAMMPS or before exiting LAMMPS-GUI.
Context Specific Word Completion
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-By default, LAMMPS GUI will display a small pop-up frame with possible
+By default, LAMMPS-GUI displays a small pop-up frame with possible
choices for LAMMPS input script commands or styles after 2 characters of
a word have been typed.
@@ -354,10 +487,10 @@ by clicking on the entry with the mouse. The automatic completion
pop-up can be disabled in the ``Preferences`` dialog, but the completion
can still be requested manually by either hitting the 'Shift-TAB' key or
by right-clicking with the mouse and selecting the option from the
-context menu. Most of the completion information is taken from the
-LAMMPS instance and thus it will be adjusted to only show available
-options that have been enabled while compiling LAMMPS. That, however,
-excludes accelerated styles and commands; for improved clarity, only the
+context menu. Most of the completion information is retrieved from the
+active LAMMPS instance and thus it shows only available options that
+have been enabled when compiling LAMMPS. That list, however, excludes
+accelerated styles and commands; for improved clarity, only the
non-suffix version of styles are shown.
Line Reformatting
@@ -366,11 +499,12 @@ Line Reformatting
The editor supports reformatting lines according to the syntax in order
to have consistently aligned lines. This primarily means adding
whitespace padding to commands, type specifiers, IDs and names. This
-reformatting is performed by default when hitting the 'Enter' key to
-start a new line. This feature can be turned on or off in the
-``Preferences`` dialog, but it can still be manually performed by
-hitting the 'TAB' key. The amount of padding can also be changed in the
-``Preferences`` dialog.
+reformatting is performed manually by hitting the 'Tab' key. It is
+also possible to have this done automatically when hitting the 'Enter'
+key to start a new line. This feature can be turned on or off in the
+``Preferences`` dialog for ``Editor Settings`` with the
+"Reformat with 'Enter'" checkbox. The amount of padding for multiple
+categories can be adjusted in the same dialog.
Internally this functionality is achieved by splitting the line into
"words" and then putting it back together with padding added where the
@@ -379,17 +513,32 @@ context can be detected; otherwise a single space is used between words.
Context Specific Help
^^^^^^^^^^^^^^^^^^^^^
-.. image:: JPG/lammps-gui-popup-help.png
- :align: center
- :scale: 50%
+.. |gui-popup1| image:: JPG/lammps-gui-popup-help.png
+ :width: 48%
-A unique feature of the LAMMPS GUI is the option to look up the
+.. |gui-popup2| image:: JPG/lammps-gui-popup-view.png
+ :width: 48%
+
+|gui-popup1| |gui-popup2|
+
+A unique feature of LAMMPS-GUI is the option to look up the LAMMPS
documentation for the command in the current line. This can be done by
either clicking the right mouse button or by using the `Ctrl-?` keyboard
-shortcut. When clicking the mouse there are additional entries in the
-context menu that will open the corresponding documentation page in the
-online LAMMPS documentation. When using the keyboard, the first of
-those entries will be chosen directly.
+shortcut. When using the mouse, there are additional entries in the
+context menu that open the corresponding documentation page in the
+online LAMMPS documentation in a web browser window. When using the
+keyboard, the first of those entries is chosen.
+
+.. versionadded:: 1.6
+
+If the word under the cursor is a file, then additionally the context
+menu has an entry to open the file in a read-only text viewer window.
+This is a convenient way to view the contents of files that are
+referenced in the input. The file viewer also supports on-the-fly
+decompression based on the file name suffix in a :ref:`similar fashion
+as available with LAMMPS `. If the necessary decompression
+program is missing or the file cannot be decompressed, the viewer window
+will contain a corresponding message.
Menu
----
@@ -397,9 +546,9 @@ Menu
The menu bar has entries ``File``, ``Edit``, ``Run``, ``View``, and
``About``. Instead of using the mouse to click on them, the individual
menus can also be activated by hitting the `Alt` key together with the
-corresponding underlined letter, that is `Alt-F` will activate the
+corresponding underlined letter, that is `Alt-F` activates the
``File`` menu. For the corresponding activated sub-menus, the key
-corresponding the underlined letters can again be used to select entries
+corresponding the underlined letters can be used to select entries
instead of using the mouse.
File
@@ -407,19 +556,22 @@ File
The ``File`` menu offers the usual options:
-- ``New`` will clear the current buffer and reset the file name to ``*unknown*``
-- ``Open`` will open a dialog to select a new file
-- ``Save`` will save the current file; if the file name is ``*unknown*``
+- ``New`` clears the current buffer and resets the file name to ``*unknown*``
+- ``Open`` opens a dialog to select a new file for editing in the *Editor*
+- ``View`` opens a dialog to select a file for viewing in a *separate* window (read-only) with support for on-the-fly decompression as explained above.
+- ``Save`` saves the current file; if the file name is ``*unknown*``
a dialog will open to select a new file name
-- ``Save As`` will open a dialog to select and new file name and save
- the buffer to it
-- ``Quit`` will exit LAMMPS GUI. If there are unsaved changes, a dialog
- will appear to either cancel the operation, or to save or not save the
- edited file.
+- ``Save As`` opens a dialog to select and new file name (and folder, if
+ desired) and saves the buffer to it. Writing the buffer to a
+ different folder will also switch the current working directory to
+ that folder.
+- ``Quit`` exits LAMMPS-GUI. If there are unsaved changes, a dialog will
+ appear to either cancel the operation, or to save, or to not save the
+ modified buffer.
-In addition, up to 5 recent file names will be listed after the
-``Open`` entry that allows re-opening recent files. This list is
-stored when quitting and recovered when starting again.
+In addition, up to 5 recent file names will be listed after the ``Open``
+entry that allows re-opening recently opened files. This list is stored
+when quitting and recovered when starting again.
Edit
^^^^
@@ -427,19 +579,20 @@ Edit
The ``Edit`` menu offers the usual editor functions like ``Undo``,
``Redo``, ``Cut``, ``Copy``, ``Paste``. It can also open a
``Preferences`` dialog (keyboard shortcut `Ctrl-P`) and allows deletion
-of all stored preferences so they will be reset to default values.
+of all stored preferences and settings, so they are reset to their
+default values.
Run
^^^
-The ``Run`` menu has options to start and stop a LAMMPS process.
-Rather than calling the LAMMPS executable as a separate executable,
-the LAMMPS GUI is linked to the LAMMPS library and thus can run LAMMPS
-internally through the :ref:`LAMMPS C-library interface
-`.
+The ``Run`` menu has options to start and stop a LAMMPS process. Rather
+than calling the LAMMPS executable as a separate executable, the
+LAMMPS-GUI is linked to the LAMMPS library and thus can run LAMMPS
+internally through the :ref:`LAMMPS C-library interface `
+in a separate thread.
Specifically, a LAMMPS instance will be created by calling
-:cpp:func:`lammps_open_no_mpi`. The buffer contents then executed by
+:cpp:func:`lammps_open_no_mpi`. The buffer contents are then executed by
calling :cpp:func:`lammps_commands_string`. Certain commands and
features are only available after a LAMMPS instance is created. Its
presence is indicated by a small LAMMPS ``L`` logo in the status bar
@@ -449,16 +602,16 @@ reading the file. This is mainly provided as a fallback option in
case the input uses some feature that is not available when running
from a string buffer.
-The LAMMPS calculation will be run in a concurrent thread so that the
-GUI can stay responsive and be updated during the run. This can be
-used to tell the running LAMMPS instance to stop at the next timestep.
-The ``Stop LAMMPS`` entry will do this by calling
-:cpp:func:`lammps_force_timeout`, which is equivalent to a :doc:`timer
-timeout 0 ` command.
+The LAMMPS calculations are run in a concurrent thread so that the GUI
+can stay responsive and be updated during the run. The GUI can retrieve
+data from the running LAMMPS instance and tell it to stop at the next
+timestep. The ``Stop LAMMPS`` entry will do this by calling the
+:cpp:func:`lammps_force_timeout` library function, which is equivalent
+to a :doc:`timer timeout 0 ` command.
-The ``Set Variables...`` entry will open a dialog box where
+The ``Set Variables...`` entry opens a dialog box where
:doc:`index style variables ` can be set. Those variables
-will be passed to the LAMMPS instance when it is created and are thus
+are passed to the LAMMPS instance when it is created and are thus
set *before* a run is started.
.. image:: JPG/lammps-gui-variables.png
@@ -478,12 +631,12 @@ in an ``Image Viewer`` window.
The ``View in OVITO`` entry will launch `OVITO `_
with a :doc:`data file ` containing the current state of
-the system. This option is only available if the LAMMPS GUI can find
+the system. This option is only available if LAMMPS-GUI can find
the OVITO executable in the system path.
The ``View in VMD`` entry will launch VMD with a :doc:`data file
` containing the current state of the system. This option
-is only available if the LAMMPS GUI can find the VMD executable in the
+is only available if LAMMPS-GUI can find the VMD executable in the
system path.
View
@@ -498,14 +651,17 @@ About
^^^^^
The ``About`` menu finally offers a couple of dialog windows and an
-option to launch the LAMMPS online documentation in a web browser.
-The ``About LAMMPS`` entry displays a dialog with a summary of the
+option to launch the LAMMPS online documentation in a web browser. The
+``About LAMMPS-GUI`` entry displays a dialog with a summary of the
configuration settings of the LAMMPS library in use and the version
-number of LAMMPS GUI itself. The ``Quick Help`` displays a dialog
-with a minimal description of LAMMPS GUI. The ``LAMMPS GUI Howto``
-entry will open this documentation page from the online documentation
-in a web browser window. The ``LAMMPS Manual`` entry will open the
-main page of the LAMMPS documentation in the web browser.
+number of LAMMPS-GUI itself. The ``Quick Help`` displays a dialog with
+a minimal description of LAMMPS-GUI. The ``LAMMPS-GUI Howto`` entry
+will open this documentation page from the online documentation in a web
+browser window. The ``LAMMPS Manual`` entry will open the main page of
+the LAMMPS online documentation in a web browser window.
+The ``LAMMPS Tutorial`` entry will open the main page of the set of
+LAMMPS tutorials authored and maintained by Simon Gravelle at
+https://lammpstutorials.github.io/ in a web browser window.
-----
@@ -513,8 +669,8 @@ Preferences
-----------
The ``Preferences`` dialog allows customization of the behavior and
-look of the LAMMPS GUI application. The settings are grouped and each
-group is displayed within a tab.
+look of LAMMPS-GUI. The settings are grouped and each group is
+displayed within a tab.
.. |guiprefs1| image:: JPG/lammps-gui-prefs-general.png
:width: 24%
@@ -534,9 +690,9 @@ General Settings:
^^^^^^^^^^^^^^^^^
- *Echo input to log:* when checked, all input commands, including
- variable expansions, will be echoed to the log window. This is
+ variable expansions, are echoed to the *Output* window. This is
equivalent to using `-echo screen` at the command line. There is no
- log *file* produced by default, since LAMMPS GUI uses `-log none`.
+ log *file* produced by default, since LAMMPS-GUI uses `-log none`.
- *Include citation details:* when checked full citation info will be
included to the log window. This is equivalent to using `-cite
screen` on the command line.
@@ -558,24 +714,26 @@ General Settings:
chart window will be replaced when a new snapshot image is requested,
otherwise each command will create a new image window.
- *Path to LAMMPS Shared Library File:* this option is only visible
- when LAMMPS GUI was compiled to load the LAMMPS library at run time
+ when LAMMPS-GUI was compiled to load the LAMMPS library at run time
instead of being linked to it directly. With the ``Browse..`` button
or by changing the text, a different shared library file with a
different compilation of LAMMPS with different settings or from a
different version can be loaded. After this setting was changed,
- LAMMPS GUI needs to be re-launched.
+ LAMMPS-GUI needs to be re-launched.
- *Select Default Font:* Opens a font selection dialog where the type
and size for the default font (used for everything but the editor and
log) of the application can be set.
- *Select Text Font:* Opens a font selection dialog where the type and
size for the text editor and log font of the application can be set.
-- *GUI update interval:* Allows to set the time interval between GUI
- and data updates during a LAMMPS run in milliseconds. The default is
- to update the GUI every 10 milliseconds. This is good for most cases.
- For LAMMPS runs that run *very* fast, however, data may be missed and
- through lowering this interval, this can be corrected. However, this
- will make the GUI use more resources, which may be a problem on some
- computers with slower CPUs and a small number of CPU cores. This
+- *GUI update interval:* Allows to set the time interval between GUI and
+ data updates during a LAMMPS run in milliseconds. The default is to
+ update the GUI every 10 milliseconds. This is good for many cases.
+ Set this to 100 milliseconds or more if LAMMPS-GUI consumes too many
+ resources during a run. For LAMMPS runs that run *very* fast (for
+ example in tutorial examples), however, data may be missed and through
+ lowering this interval, this can be corrected. However, this will
+ make the GUI use more resources, which may be a problem on some
+ computers with slower CPUs and a small number of CPU cores. This
setting may be changed to a value between 1 and 1000 milliseconds.
Accelerators:
@@ -592,18 +750,23 @@ Snapshot Image:
^^^^^^^^^^^^^^^
This tab allows setting defaults for the snapshot images displayed in
-the ``Image Viewer`` window, such as its dimensions and the zoom
-factor applied. The *Antialias* switch will render images with twice
-the number of pixels for width and height and then smoothly scale the
-image back to the requested size. This produces higher quality images
-with smoother edges at the expense of requiring more CPU time to
-render the image. The *HQ Image mode* option turns on screen space
-ambient occlusion (SSAO) mode when rendering images. This is also
-more time consuming, but produces a more 'spatial' representation of
-the system shading of atoms by their depth. The *VDW Style* checkbox
-selects whether atoms are represented by space filling spheres when
-checked or by smaller spheres and sticks. Finally there are a couple
-of drop down lists to select the background and box colors.
+the ``Image Viewer`` window, such as its dimensions and the zoom factor
+applied. The *Antialias* switch will render images with twice the
+number of pixels for width and height and then smoothly scale the image
+back to the requested size. This produces higher quality images with
+smoother edges at the expense of requiring more CPU time to render the
+image. The *HQ Image mode* option turns on screen space ambient
+occlusion (SSAO) mode when rendering images. This is also more time
+consuming, but produces a more 'spatial' representation of the system
+shading of atoms by their depth. The *Shiny Image mode* option will
+render objects with a shiny surface when enabled. Otherwise the
+surfaces will be matted. The *Show Box* option selects whether the
+system box is drawn as a colored set of sticks. Similarly, the *Show
+Axes* option selects whether a representation of the three system axes
+will be drawn as colored sticks. The *VDW Style* checkbox selects
+whether atoms are represented by space filling spheres when checked or
+by smaller spheres and sticks. Finally there are a couple of drop down
+lists to select the background and box colors.
Editor Settings:
^^^^^^^^^^^^^^^^
@@ -614,9 +777,11 @@ ranges, IDs (e.g. for fixes), and names (e.g. for groups). The value
set is the minimum width for the text element and it can be chosen in
the range between 1 and 32.
-The two settings which follow enable or disable the automatic
-reformatting when hitting the 'Enter' key and the automatic display of
-the completion pop-up window.
+The three settings which follow enable or disable the automatic
+reformatting when hitting the 'Enter' key, the automatic display of
+the completion pop-up window, and whether auto-save mode is enabled.
+In auto-save mode the editor buffer is saved before a run or before
+exiting LAMMPS-GUI.
-----------
@@ -649,48 +814,54 @@ available (On macOS use the Command key instead of Ctrl/Control).
- Redo edit
- Ctrl+/
- Stop Active Run
- * - Ctrl+S
- - Save File
+ * - Ctrl+Shift+F
+ - View File
- Ctrl+C
- Copy text
- Ctrl+Shift+V
- Set Variables
- * - Ctrl+Shift+S
- - Save File As
+ * - Ctrl+S
+ - Save File
- Ctrl+X
- Cut text
- Ctrl+I
- Snapshot Image
- * - Ctrl+Q
- - Quit Application
+ * - Ctrl+Shift+S
+ - Save File As
- Ctrl+V
- Paste text
- Ctrl+L
- Slide Show
- * - Ctrl+W
- - Close Window
+ * - Ctrl+Q
+ - Quit Application
- Ctrl+A
- Select All
- Ctrl+P
- Preferences
- * - Ctrl+Shift+A
- - About LAMMPS
+ * - Ctrl+W
+ - Close Window
- Ctrl+Shift+H
- Quick Help
- Ctrl+Shift+G
- - LAMMPS GUI Howto
- * - Ctrl+Shift+M
- - LAMMPS Manual
+ - LAMMPS-GUI Howto
+ * - Ctrl+Shift+A
+ - About LAMMPS
- Ctrl+?
- Context Help
- Ctrl+Shift+W
- Show Variables
- * - Ctrl+Shift+Enter
- - Run File
+ * - Ctrl+Shift+M
+ - LAMMPS Manual
- TAB
- Reformat line
- Shift+TAB
- Show Completions
+ * - Ctrl+Shift+T
+ - LAMMPS Tutorial
+ - Ctrl+Shift+Enter
+ - Run File
+ -
+ -
Further editing keybindings `are documented with the Qt documentation
`_. In
diff --git a/doc/src/Howto_pylammps.rst b/doc/src/Howto_pylammps.rst
index bce37d5ac7..5ef3248e1d 100644
--- a/doc/src/Howto_pylammps.rst
+++ b/doc/src/Howto_pylammps.rst
@@ -6,19 +6,22 @@ PyLammps Tutorial
Overview
--------
-``PyLammps`` is a Python wrapper class for LAMMPS which can be created
-on its own or use an existing lammps Python object. It creates a simpler,
+:py:class:`PyLammps ` is a Python wrapper class for
+LAMMPS which can be created on its own or use an existing
+:py:class:`lammps Python ` object. It creates a simpler,
more "pythonic" interface to common LAMMPS functionality, in contrast to
-the ``lammps`` wrapper for the C-style LAMMPS library interface which
-is written using `Python ctypes `_. The ``lammps`` wrapper
-is discussed on the :doc:`Python_head` doc page.
+the :py:class:`lammps ` wrapper for the LAMMPS :ref:`C
+language library interface API ` which is written using
+`Python ctypes `_. The :py:class:`lammps `
+wrapper is discussed on the :doc:`Python_head` doc page.
-Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable
-API. It no longer requires knowledge of the underlying C++ code
-implementation. Finally, the ``IPyLammps`` wrapper builds on top of
-``PyLammps`` and adds some additional features for
-`IPython integration `_ into `Jupyter notebooks `_,
-e.g. for embedded visualization output from :doc:`dump style image `.
+Unlike the flat `ctypes `_ interface, PyLammps exposes a
+discoverable API. It no longer requires knowledge of the underlying C++
+code implementation. Finally, the :py:class:`IPyLammps
+` wrapper builds on top of :py:class:`PyLammps
+` and adds some additional features for `IPython
+integration `_ into `Jupyter notebooks `_, e.g. for
+embedded visualization output from :doc:`dump style image `.
.. _ctypes: https://docs.python.org/3/library/ctypes.html
.. _ipython: https://ipython.org/
@@ -30,19 +33,22 @@ Comparison of lammps and PyLammps interfaces
lammps.lammps
"""""""""""""
-* uses ``ctypes``
-* direct memory access to native C++ data
+* uses `ctypes `_
+* direct memory access to native C++ data with optional support for NumPy arrays
* provides functions to send and receive data to LAMMPS
+* interface modeled after the LAMMPS :ref:`C language library interface API `
* requires knowledge of how LAMMPS internally works (C pointers, etc)
+* full support for running Python with MPI using `mpi4py `_
lammps.PyLammps
"""""""""""""""
-* higher-level abstraction built on top of original ctypes interface
+* higher-level abstraction built on *top* of original :py:class:`ctypes based interface `
* manipulation of Python objects
* communication with LAMMPS is hidden from API user
* shorter, more concise Python
* better IPython integration, designed for quick prototyping
+* designed for serial execution
Quick Start
-----------
@@ -506,14 +512,26 @@ inside of the IPython notebook.
Using PyLammps and mpi4py (Experimental)
----------------------------------------
-PyLammps can be run in parallel using mpi4py. This python package can be installed using
+PyLammps can be run in parallel using `mpi4py
+`_. This python package can be installed
+using
.. code-block:: bash
pip install mpi4py
-The following is a short example which reads in an existing LAMMPS input file and
-executes it in parallel. You can find in.melt in the examples/melt folder.
+.. warning::
+
+ Usually, any :py:class:`PyLammps ` command must be
+ executed by *all* MPI processes. However, evaluations and querying
+ the system state is only available on MPI rank 0. Using these
+ functions from other MPI ranks will raise an exception.
+
+The following is a short example which reads in an existing LAMMPS input
+file and executes it in parallel. You can find in.melt in the
+examples/melt folder. Please take note that the
+:py:meth:`PyLammps.eval() ` is called only from
+MPI rank 0.
.. code-block:: python
@@ -535,10 +553,6 @@ following mpirun command:
mpirun -np 4 python melt.py
-.. warning::
-
- Any command must be executed by all MPI processes. However, evaluations and querying the system state is only available on rank 0.
-
Feedback and Contributing
-------------------------
diff --git a/doc/src/Howto_rheo.rst b/doc/src/Howto_rheo.rst
index 332a0aadb6..0c2e15ebb4 100644
--- a/doc/src/Howto_rheo.rst
+++ b/doc/src/Howto_rheo.rst
@@ -13,7 +13,7 @@ interact and their physical behavior. The package is designed with modularity
in mind, so one can easily turn various features on/off, adjust physical
details of the system, or develop new capabilities. For instance, the numerics
associated with calculating gradients, reproducing kernels, etc. are separated
-into distinctclasses to simplify the development of new integration schemes
+into distinct classes to simplify the development of new integration schemes
which can call these calculations. Additional numerical details can be found in
:ref:`(Palermo) ` and
:ref:`(Clemmer) `. Example movies illustrating some of these
diff --git a/doc/src/Install_linux.rst b/doc/src/Install_linux.rst
index 53f4965e08..3dd97d8342 100644
--- a/doc/src/Install_linux.rst
+++ b/doc/src/Install_linux.rst
@@ -35,11 +35,11 @@ packages listed below), they do not depend on any installed software and
thus should run on *any* 64-bit x86 machine with *any* Linux version.
These executable include most of the available packages and multi-thread
-parallelization (via INTEL, KOKKOS, or OPENMP package). They are **not**
-compatible with MPI. Several of the LAMMPS tools executables (e.g. ``msi2lmp``)
-and the ``lammps-shell`` program are included as well. Because of the
-static linkage, there is no ``liblammps.so`` library file and thus also the
-LAMMPS python module, which depends on it, is not included.
+parallelization (via INTEL, KOKKOS, or OPENMP package). They are
+**not** compatible with MPI. Several of the LAMMPS tools executables
+(e.g. ``msi2lmp``) are included as well. Because of the static linkage,
+there is no ``liblammps.so`` library file and thus also the LAMMPS
+python module, which depends on it, is not included.
The compressed tar archives available for download have names following
the pattern ``lammps-linux-x86_64-.tar.gz`` and will all unpack
diff --git a/doc/src/JPG/lammps-gui-chart.png b/doc/src/JPG/lammps-gui-chart.png
index a16fcb167c..6395e4815a 100644
Binary files a/doc/src/JPG/lammps-gui-chart.png and b/doc/src/JPG/lammps-gui-chart.png differ
diff --git a/doc/src/JPG/lammps-gui-image.png b/doc/src/JPG/lammps-gui-image.png
index b383e914a5..969aadce0b 100644
Binary files a/doc/src/JPG/lammps-gui-image.png and b/doc/src/JPG/lammps-gui-image.png differ
diff --git a/doc/src/JPG/lammps-gui-log.png b/doc/src/JPG/lammps-gui-log.png
index 3dbae1e424..894af371f0 100644
Binary files a/doc/src/JPG/lammps-gui-log.png and b/doc/src/JPG/lammps-gui-log.png differ
diff --git a/doc/src/JPG/lammps-gui-main.png b/doc/src/JPG/lammps-gui-main.png
index f700b4264f..69efe3db68 100644
Binary files a/doc/src/JPG/lammps-gui-main.png and b/doc/src/JPG/lammps-gui-main.png differ
diff --git a/doc/src/JPG/lammps-gui-popup-help.png b/doc/src/JPG/lammps-gui-popup-help.png
index 395e06ff43..0a3c3563f2 100644
Binary files a/doc/src/JPG/lammps-gui-popup-help.png and b/doc/src/JPG/lammps-gui-popup-help.png differ
diff --git a/doc/src/JPG/lammps-gui-popup-view.png b/doc/src/JPG/lammps-gui-popup-view.png
new file mode 100644
index 0000000000..333c0616e5
Binary files /dev/null and b/doc/src/JPG/lammps-gui-popup-view.png differ
diff --git a/doc/src/JPG/lammps-gui-prefs-accel.png b/doc/src/JPG/lammps-gui-prefs-accel.png
index 3cab94136a..25820c8d44 100644
Binary files a/doc/src/JPG/lammps-gui-prefs-accel.png and b/doc/src/JPG/lammps-gui-prefs-accel.png differ
diff --git a/doc/src/JPG/lammps-gui-prefs-editor.png b/doc/src/JPG/lammps-gui-prefs-editor.png
index 5d2fe50380..5b5cffe209 100644
Binary files a/doc/src/JPG/lammps-gui-prefs-editor.png and b/doc/src/JPG/lammps-gui-prefs-editor.png differ
diff --git a/doc/src/JPG/lammps-gui-prefs-general.png b/doc/src/JPG/lammps-gui-prefs-general.png
index 765ba8f84d..bfc9556995 100644
Binary files a/doc/src/JPG/lammps-gui-prefs-general.png and b/doc/src/JPG/lammps-gui-prefs-general.png differ
diff --git a/doc/src/JPG/lammps-gui-prefs-image.png b/doc/src/JPG/lammps-gui-prefs-image.png
index b87e8f2d20..7dd9e06653 100644
Binary files a/doc/src/JPG/lammps-gui-prefs-image.png and b/doc/src/JPG/lammps-gui-prefs-image.png differ
diff --git a/doc/src/JPG/lammps-gui-running.png b/doc/src/JPG/lammps-gui-running.png
index 3cc1589643..5afe17e014 100644
Binary files a/doc/src/JPG/lammps-gui-running.png and b/doc/src/JPG/lammps-gui-running.png differ
diff --git a/doc/src/JPG/lammps-gui-slideshow.png b/doc/src/JPG/lammps-gui-slideshow.png
index 21ef80e210..00f95e9c5a 100644
Binary files a/doc/src/JPG/lammps-gui-slideshow.png and b/doc/src/JPG/lammps-gui-slideshow.png differ
diff --git a/doc/src/JPG/lammps-gui-yaml.png b/doc/src/JPG/lammps-gui-yaml.png
new file mode 100644
index 0000000000..fa35d550db
Binary files /dev/null and b/doc/src/JPG/lammps-gui-yaml.png differ
diff --git a/doc/src/Library_properties.rst b/doc/src/Library_properties.rst
index 73abcbbe1b..129acb1a32 100644
--- a/doc/src/Library_properties.rst
+++ b/doc/src/Library_properties.rst
@@ -13,6 +13,8 @@ This section documents the following functions:
- :cpp:func:`lammps_extract_setting`
- :cpp:func:`lammps_extract_global_datatype`
- :cpp:func:`lammps_extract_global`
+- :cpp:func:`lammps_extract_pair_dimension`
+- :cpp:func:`lammps_extract_pair`
- :cpp:func:`lammps_map_atom`
--------------------
@@ -123,6 +125,16 @@ subdomains and processors.
-----------------------
+.. doxygenfunction:: lammps_extract_pair_dimension
+ :project: progguide
+
+-----------------------
+
+.. doxygenfunction:: lammps_extract_pair
+ :project: progguide
+
+-----------------------
+
.. doxygenfunction:: lammps_map_atom
:project: progguide
diff --git a/doc/src/PDF/colvars-refman-lammps.pdf b/doc/src/PDF/colvars-refman-lammps.pdf
index 4f85537b35..b8f049ce01 100644
Binary files a/doc/src/PDF/colvars-refman-lammps.pdf and b/doc/src/PDF/colvars-refman-lammps.pdf differ
diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst
index 9bc9c935a7..1c16d370b9 100644
--- a/doc/src/Tools.rst
+++ b/doc/src/Tools.rst
@@ -92,8 +92,7 @@ Miscellaneous tools
* :ref:`emacs `
* :ref:`i-PI `
* :ref:`kate `
- * :ref:`LAMMPS shell `
- * :ref:`LAMMPS GUI `
+ * :ref:`LAMMPS-GUI `
* :ref:`LAMMPS magic patterns for file(1) `
* :ref:`Offline build tool `
* :ref:`singularity/apptainer `
@@ -444,219 +443,9 @@ The file was provided by Alessandro Luigi Sellerio
----------
-.. _lammps_shell:
-
-LAMMPS shell
-------------
-
-.. versionadded:: 9Oct2020
-
-Overview
-^^^^^^^^
-
-The LAMMPS Shell, ``lammps-shell`` is a program that functions very
-similar to the regular LAMMPS executable but has several modifications
-and additions that make it more powerful for interactive sessions,
-i.e. where you type LAMMPS commands from the prompt instead of reading
-them from a file.
-
-- It uses the readline and history libraries to provide command line
- editing and context aware TAB-expansion (details on that below).
-
-- When processing an input file with the '-in' or '-i' flag from the
- command line, it does not exit at the end of that input file but
- stops at a prompt, so that additional commands can be issued
-
-- Errors will not abort the shell but return to the prompt.
-
-- It has additional commands aimed at interactive use (details below).
-
-- Interrupting a calculation with CTRL-C will not terminate the
- session but rather enforce a timeout to cleanly stop an ongoing
- run (more info on timeouts is in the :doc:`timer command `
- documentation).
-
-These enhancements make the LAMMPS shell an attractive choice for
-interactive LAMMPS sessions in graphical desktop environments
-(e.g. Gnome, KDE, Cinnamon, XFCE, Windows).
-
-TAB-expansion
-^^^^^^^^^^^^^
-
-When writing commands interactively at the shell prompt, you can hit
-the TAB key at any time to try and complete the text. This completion
-is context aware and will expand any first word only to commands
-available in that executable.
-
-- For style commands it will expand to available styles of the
- corresponding category (e.g. pair styles after a
- :doc:`pair_style ` command).
-
-- For :doc:`compute `, :doc:`fix `, or :doc:`dump `
- it will also expand only to already defined groups for the group-ID
- keyword.
-
-- For commands like :doc:`compute_modify `,
- :doc:`fix_modify `, or :doc:`dump_modify `
- it will expand to known compute/fix/dump IDs only.
-
-- When typing references to computes, fixes, or variables with a
- "c\_", "f\_", or "v\_" prefix, respectively, then the expansion will
- be to known compute/fix IDs and variable names. Variable name
- expansion is also available for the ${name} variable syntax.
-
-- In all other cases TAB expansion will complete to names of files
- and directories.
-
-Command line editing and history
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When typing commands, command line editing similar to what BASH
-provides is available. Thus it is possible to move around the
-currently line and perform various cut and insert and edit operations.
-Previous commands can be retrieved by scrolling up (and down)
-or searching (e.g. with CTRL-r).
-
-Also history expansion through using the exclamation mark '!'
-can be performed. Examples: '!!' will be replaced with the previous
-command, '!-2' will repeat the command before that, '!30' will be
-replaced with event number 30 in the command history list, and
-'!run' with the last command line that started with "run". Adding
-a ":p" to such a history expansion will result that the expansion is
-printed and added to the history list, but NOT executed.
-On exit the LAMMPS shell will write the history list to a file
-".lammps_history" in the current working directory. If such a
-file exists when the LAMMPS shell is launched it will be read to
-populate the history list.
-
-This is realized via the readline library and can thus be customized
-with an ``.inputrc`` file in the home directory. For application
-specific customization, the LAMMPS shell uses the name "lammps-shell".
-For more information about using and customizing an application using
-readline, please see the available documentation at:
-https://www.gnu.org/software/readline/
-
-
-Additional commands
-^^^^^^^^^^^^^^^^^^^
-
-The following commands are added to the LAMMPS shell on top of the
-regular LAMMPS commands:
-
-.. parsed-literal::
-
- help (or ?) print a brief help message
- history display the current command history list
- clear_history wipe out the current command history list
- save_history
- write commands from the history to file.
- The range is given as -, where and
- may be empty. Example: save_history 100- in.recent
- source read commands from file (same as "include")
- pwd print current working directory
- cd change current working directory (same as pwd if no directory)
- mem print current and maximum memory usage
- \| execute as a shell command and return to the command prompt
- exit exit the LAMMPS shell cleanly (unlike the "quit" command)
-
-Please note that some known shell operations are implemented in the
-LAMMPS :doc:`shell command ` in a platform neutral fashion,
-while using the '\|' character will always pass the following text
-to the operating system's shell command.
-
-Compilation
-^^^^^^^^^^^
-
-Compilation of the LAMMPS shell can be enabled by setting the CMake
-variable ``BUILD_LAMMPS_SHELL`` to "on" or using the makefile in the
-``tools/lammps-shell`` folder to compile after building LAMMPS using
-the conventional make procedure. The makefile will likely need
-customization depending on the features and settings used for
-compiling LAMMPS.
-
-Limitations
-^^^^^^^^^^^
-
-The LAMMPS shell was not designed for use with MPI parallelization
-via ``mpirun`` or ``mpiexec`` or ``srun``.
-
-Readline customization
-^^^^^^^^^^^^^^^^^^^^^^
-
-The behavior of the readline functionality can be customized in the
-``${HOME}/.inputrc`` file. This can be used to alter the default
-settings or change the key-bindings. The LAMMPS Shell sets the
-application name ``lammps-shell``, so settings can be either applied
-globally or only for the LAMMPS shell by bracketing them between
-``$if lammps-shell`` and ``$endif`` like in the following example:
-
-.. code-block:: bash
-
- $if lammps-shell
- # disable "beep" or "screen flash"
- set bell-style none
- # bind the "Insert" key to toggle overwrite mode
- "\e[2~": overwrite-mode
- $endif
-
-More details about this are in the `readline documentation `_.
-
-
-LAMMPS Shell tips and tricks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Below are some suggestions for how to use and customize the LAMMPS shell.
-
-Enable tilde expansion
-""""""""""""""""""""""
-
-Adding ``set expand-tilde on`` to ``${HOME}/.inputrc`` is recommended as
-this will change the filename expansion behavior to replace any text
-starting with "~" by the full path to the corresponding user's home
-directory. While the expansion of filenames **will** happen on all
-arguments where the context is not known (e.g. ``~/compile/lamm``
-will expand to ``~/compile/lammps/``), it will not replace the tilde by
-default. But since LAMMPS does not do tilde expansion itself (unlike a
-shell), this will result in errors. Instead the tilde-expression should
-be expanded into a valid path, where the plain "~/" stands for the
-current user's home directory and "~someuser/" stands for
-"/home/someuser" or whatever the full path to that user's home directory
-is.
-
-File extension association
-""""""""""""""""""""""""""
-
-Since the LAMMPS shell (unlike the regular LAMMPS executable) does not
-exit when an input file is passed on the command line with the "-in" or
-"-i" flag (the behavior is like for ``python -i ``), it makes
-the LAMMPS shell suitable for associating it with input files based on
-their filename extension (e.g. ".lmp"). Since ``lammps-shell`` is a
-console application, you have to run it inside a terminal program with a
-command line like this:
-
-.. code-block:: bash
-
- xterm -title "LAMMPS Shell" -e /path/to/lammps-shell -i in.file.lmp
-
-
-Use history to create an input file
-"""""""""""""""""""""""""""""""""""
-
-When experimenting with commands to interactively to figure out a
-suitable choice of settings or simply the correct syntax, you may want
-to record part of your commands to a file for later use. This can be
-done with the ``save_history`` commands, which allows to selectively
-write a section of the command history to a file (Example:
-``save_history 25-30 in.run``). This file can be further edited
-(Example: ``|vim in.run``) and then the file read back in and tried out
-(Example: ``source in.run``). If the input also creates a system box,
-you first need to use the :doc:`clear` command.
-
-----------
-
.. _lammps_gui:
-LAMMPS GUI
+LAMMPS-GUI
----------
.. versionadded:: 2Aug2023
@@ -664,25 +453,28 @@ LAMMPS GUI
Overview
^^^^^^^^
-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 C-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
while it is running, display visualizations created with the :doc:`dump
image command `, and is adapted specifically for editing
-LAMMPS input files through text completion and reformatting, and linking
-to the online LAMMPS documentation for known LAMMPS commands and styles.
+LAMMPS input files through syntax highlighting, text completion, and
+reformatting, and linking to the online LAMMPS documentation for known
+LAMMPS commands and styles.
-This is similar to what people traditionally would do to run LAMMPS:
-using a regular text editor to edit the input and run the necessary
-commands, possibly including the text editor, too, from a command line
-terminal window. This similarity is a design goal. While making it easy
-for beginners to start with LAMMPS, it is also the intention to simplify
-the transition to workflows like most experienced LAMMPS users do.
+This is similar to what people traditionally would do to run LAMMPS but
+all rolled into a single application: that is, using a text editor,
+plotting program, and a visualization program to edit the input, run
+LAMMPS, process the output into graphs and visualizations from a command
+line window. This similarity is a design goal. While making it easy for
+beginners to start with LAMMPS, it is also the expectation that
+LAMMPS-GUI users will eventually transition to workflows that most
+experienced LAMMPS users employ.
All features have been extensively exposed to keyboard shortcuts, so
that there is also appeal for experienced LAMMPS users for prototyping
-and testing simulations setups.
+and testing simulation setups.
Features
^^^^^^^^
@@ -690,48 +482,49 @@ Features
A detailed discussion and explanation of all features and functionality
are in the :doc:`Howto_lammps_gui` tutorial Howto page.
-Here are a few highlights of LAMMPS GUI
+Here are a few highlights of LAMMPS-GUI
-- Text editor with syntax highlighting customized for LAMMPS
-- Text editor will switch working directory to folder of file in buffer
-- Text editor will remember up to 5 recent files
+- Text editor with line numbers and syntax highlighting customized for LAMMPS
+- Text editor features command completion and auto-indentation for known commands and styles
+- Text editor will switch its working directory to folder of file in buffer
+- Many adjustable settings and preferences that are persistent including the 5 most recent files
- Context specific LAMMPS command help via online documentation
- LAMMPS is running in a concurrent thread, so the GUI remains responsive
-- Support for most accelerator packages
- Progress bar indicates how far a run command is completed
-- LAMMPS can be started and stopped with a hotkey
-- Screen output is captured in a Log Window
-- Thermodynamic output is captured and displayed as line graph in a Chart Window
+- LAMMPS can be started and stopped with a mouse click or a hotkey
+- Screen output is captured in an *Output* Window
+- Thermodynamic output is captured and displayed as line graph in a *Chart* Window
- Indicator for currently executed command
- Indicator for line that caused an error
-- Visualization of current state in Image Viewer (via :doc:`dump image `)
-- Many adjustable settings and preferences that are persistent
-- Dialog to set variables from the LAMMPS command line
+- Visualization of current state in Image Viewer (via calling :doc:`write_dump image `)
+- Capture of images created via :doc:`dump image ` in Slide show window
+- Dialog to set variables, similar to the LAMMPS command line flag '-v' / '-var'
+- Support for GPU, INTEL, KOKKOS/OpenMP, OPENMAP, and OPT and accelerator packages
Parallelization
^^^^^^^^^^^^^^^
Due to its nature as a graphical application, it is not possible to use
-the LAMMPS GUI in parallel with MPI, but OpenMP multi-threading and GPU
+the LAMMPS-GUI in parallel with MPI, but OpenMP multi-threading and GPU
acceleration is available and enabled by default.
Prerequisites and portability
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-LAMMPS GUI is programmed in C++ based on the C++11 standard and using
+LAMMPS-GUI is programmed in C++ based on the C++11 standard and using
the `Qt GUI framework `_.
Currently, Qt version 5.12 or later is required; Qt 5.15LTS is
-recommended; support for Qt version 6.x is under active development and
-thus far only tested with Qt 6.5LTS on Linux. Building LAMMPS with
-CMake is required.
+recommended; support for Qt version 6.x is available. Building LAMMPS
+with CMake is required.
-The LAMMPS GUI has been successfully compiled and tested on:
+The LAMMPS-GUI has been successfully compiled and tested on:
- Ubuntu Linux 20.04LTS x86_64 using GCC 9, Qt version 5.12
- Fedora Linux 40 x86\_64 using GCC 14 and Clang 17, Qt version 5.15LTS
-- Fedora Linux 40 x86\_64 using GCC 14, Qt version 6.5LTS
+- Fedora Linux 40 x86\_64 using GCC 14, Qt version 6.7
- Apple macOS 12 (Monterey) and macOS 13 (Ventura) with Xcode on arm64 and x86\_64, Qt version 5.15LTS
- Windows 10 and 11 x86_64 with Visual Studio 2022 and Visual C++ 14.36, Qt version 5.15LTS
+- Windows 10 and 11 x86_64 with Visual Studio 2022 and Visual C++ 14.40, Qt version 6.7
- Windows 10 and 11 x86_64 with MinGW / GCC 10.0 cross-compiler on Fedora 38, Qt version 5.15LTS
.. _lammps_gui_install:
@@ -740,25 +533,41 @@ The LAMMPS GUI has been successfully compiled and tested on:
Pre-compiled executables
^^^^^^^^^^^^^^^^^^^^^^^^
-Pre-compiled LAMMPS executable packages that include the GUI are currently
-available from https://download.lammps.org/static or
-https://github.com/lammps/lammps/releases. You can unpack the archives
-(or mount the macOS disk image) and run the GUI directly in place. The
-folder may also be moved around and added to the ``PATH`` environment
-variable so the executables will be found automatically. The LAMMPS GUI
-executable is called ``lammps-gui`` and either takes no arguments or
-attempts to load the first argument as LAMMPS input file.
+Pre-compiled LAMMPS executable packages that include the GUI are
+currently available from https://download.lammps.org/static or
+https://github.com/lammps/lammps/releases. For Windows, you need to
+download and then run the application installer. For macOS you download
+and mount the disk image and then drag the application bundle to the
+Applications folder. For Linux (x86_64) you currently have two
+options: 1) you can download the tar.gz archive, unpack it and run the
+GUI directly in place. The ``LAMMPS_GUI`` folder may also be moved
+around and added to the ``PATH`` environment variable so the executables
+will be found automatically. 2) you can download the `Flatpak file
+.flatpak`` and run it with ``flatpak
+run org.lammps.lammps-gui``. The flatpak bundle also includes the
+command line version of LAMMPS and some LAMMPS tools like msi2lmp. The
+can be launched by using the ``--command`` flag. For example to run
+LAMMPS directly on the ``in.lj`` benchmark input you would type in the
+``bench`` folder: ``flatpak run --command=lmp -in in.lj`` The flatpak
+version should also appear in the applications menu of standard desktop
+environments. The LAMMPS-GUI executable is called ``lammps-gui`` and
+either takes no arguments or attempts to load the first argument as
+LAMMPS input file.
+
+.. _lammps_gui_compilation:
Compilation
^^^^^^^^^^^
-The source for the LAMMPS GUI is included with the LAMMPS source code
+The source for the LAMMPS-GUI is included with the LAMMPS source code
distribution in the folder ``tools/lammps-gui`` and thus it can be can
be built as part of a regular LAMMPS compilation. :doc:`Using CMake
` is required. To enable its compilation, the CMake
variable ``-D BUILD_LAMMPS_GUI=on`` must be set when creating the CMake
configuration. All other settings (compiler, flags, compile type) for
-LAMMPS GUI are then inherited from the regular LAMMPS build. If the Qt
+LAMMPS-GUI are then inherited from the regular LAMMPS build. If the Qt
library is packaged for Linux distributions, then its location is
typically auto-detected since the required CMake configuration files are
stored in a location where CMake can find them without additional help.
@@ -766,17 +575,17 @@ Otherwise, the location of the Qt library installation must be indicated
by setting ``-D Qt5_DIR=/path/to/qt5/lib/cmake/Qt5``, which is a path to
a folder inside the Qt installation that contains the file
``Qt5Config.cmake``. Similarly, for Qt6 the location of the Qt library
-installation can be indicated by setting ``-D Qt6_DIR=/path/to/qt6/lib/cmake/Qt6``,
-if necessary. When both, Qt5 and Qt6 are available, Qt6 will be preferred
-unless ``-D LAMMPS_GUI_USE_QT5=yes`` is set.
+installation can be indicated by setting ``-D
+Qt6_DIR=/path/to/qt6/lib/cmake/Qt6``, if necessary. When both, Qt5 and
+Qt6 are available, Qt6 will be preferred unless ``-D
+LAMMPS_GUI_USE_QT5=yes`` is set.
-It should be possible to build the LAMMPS GUI as a standalone
-compilation (e.g. when LAMMPS has been compiled with traditional make).
-Then the CMake configuration needs to be told where to find the LAMMPS
-headers and the LAMMPS library, via ``-D
-LAMMPS_SOURCE_DIR=/path/to/lammps/src``. CMake will try to guess a
-build folder with the LAMMPS library from that path, but it can also be
-set with ``-D LAMMPS_LIB_DIR=/path/to/lammps/lib``.
+It is possible to build the LAMMPS-GUI as a standalone compilation
+(e.g. when LAMMPS has been compiled with traditional make). Then the
+CMake configuration needs to be told where to find the LAMMPS headers
+and the LAMMPS library, via ``-D LAMMPS_SOURCE_DIR=/path/to/lammps/src``.
+CMake will try to guess a build folder with the LAMMPS library from that
+path, but it can also be set with ``-D LAMMPS_LIB_DIR=/path/to/lammps/lib``.
Rather than linking to the LAMMPS library during compilation, it is also
possible to compile the GUI with a plugin loader that will load
@@ -827,13 +636,13 @@ There is a custom `x64-GUI-MSVC` build configuration provided in the
compilation settings for project. Choosing this configuration will
activate building the `lammps-gui.exe` executable in addition to LAMMPS
through importing package selection from the ``windows.cmake`` preset
-file and enabling building the LAMMPS GUI and disabling building with MPI.
+file and enabling building the LAMMPS-GUI and disabling building with MPI.
When requesting an installation from the `Build` menu in Visual Studio,
it will create a compressed ``LAMMPS-Win10-amd64.zip`` zip file with the
executables and required dependent .dll files. This zip file can be
uncompressed and ``lammps-gui.exe`` run directly from there. The
uncompressed folder can be added to the ``PATH`` environment and LAMMPS
-and LAMMPS GUI can be launched from anywhere from the command line.
+and LAMMPS-GUI can be launched from anywhere from the command line.
**MinGW64 Cross-compiler**
@@ -1313,13 +1122,13 @@ necessary development headers and libraries are present.
.. code-block:: bash
- -D WITH_SWIG=on # to enable building any SWIG wrapper
- -D BUILD_SWIG_JAVA=on # to enable building the Java wrapper
- -D BUILD_SWIG_LUA=on # to enable building the Lua wrapper
- -D BUILD_SWIG_PERL5=on # to enable building the Perl 5.x wrapper
- -D BUILD_SWIG_PYTHON=on # to enable building the Python wrapper
- -D BUILD_SWIG_RUBY=on # to enable building the Ruby wrapper
- -D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper
+ -D WITH_SWIG=on # to enable building any SWIG wrapper
+ -D BUILD_SWIG_JAVA=on # to enable building the Java wrapper
+ -D BUILD_SWIG_LUA=on # to enable building the Lua wrapper
+ -D BUILD_SWIG_PERL5=on # to enable building the Perl 5.x wrapper
+ -D BUILD_SWIG_PYTHON=on # to enable building the Python wrapper
+ -D BUILD_SWIG_RUBY=on # to enable building the Ruby wrapper
+ -D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper
Manual building allows a little more flexibility. E.g. one can choose
diff --git a/doc/src/angle_hybrid.rst b/doc/src/angle_hybrid.rst
index cf8ea1a3fb..fc213c13e9 100644
--- a/doc/src/angle_hybrid.rst
+++ b/doc/src/angle_hybrid.rst
@@ -1,8 +1,11 @@
.. index:: angle_style hybrid
+.. index:: angle_style hybrid/kk
angle_style hybrid command
==========================
+Accelerator Variants: *hybrid/kk*
+
Syntax
""""""
@@ -79,6 +82,10 @@ for specific angle types.
----------
+.. include:: accel_styles.rst
+
+----------
+
Restrictions
""""""""""""
@@ -87,8 +94,9 @@ MOLECULE package. See the :doc:`Build package ` doc page
for more info.
Unlike other angle styles, the hybrid angle style does not store angle
-coefficient info for individual sub-styles in a :doc:`binary restart files `. Thus when restarting a simulation from a restart
-file, you need to re-specify :doc:`angle_coeff ` commands.
+coefficient info for individual sub-styles in :doc:`binary restart files
+` or :doc:`data files `. Thus when restarting a
+simulation, you need to re-specify the angle_coeff commands.
Related commands
""""""""""""""""
diff --git a/doc/src/angle_spica.rst b/doc/src/angle_spica.rst
index 4162ce5608..2659dd4fc0 100644
--- a/doc/src/angle_spica.rst
+++ b/doc/src/angle_spica.rst
@@ -1,10 +1,11 @@
.. index:: angle_style spica
.. index:: angle_style spica/omp
+.. index:: angle_style spica/kk
angle_style spica command
=========================
-Accelerator Variants: *spica/omp*
+Accelerator Variants: *spica/omp*, *spica/kk*
Syntax
""""""
diff --git a/doc/src/bond_hybrid.rst b/doc/src/bond_hybrid.rst
index ea90ed2b57..fce393008e 100644
--- a/doc/src/bond_hybrid.rst
+++ b/doc/src/bond_hybrid.rst
@@ -75,8 +75,9 @@ package. See the :doc:`Build package ` page for more
info.
Unlike other bond styles, the hybrid bond style does not store bond
-coefficient info for individual sub-styles in a :doc:`binary restart files `. Thus when restarting a simulation from a restart
-file, you need to re-specify bond_coeff commands.
+coefficient info for individual sub-styles in :doc:`binary restart files
+` or :doc:`data files `. Thus when restarting a
+simulation, you need to re-specify the bond_coeff commands.
Related commands
""""""""""""""""
diff --git a/doc/src/commands_list.rst b/doc/src/commands_list.rst
index cea237f14e..b297b6dbf5 100644
--- a/doc/src/commands_list.rst
+++ b/doc/src/commands_list.rst
@@ -45,6 +45,7 @@ Commands
fix
fix_modify
fitpod_command
+ geturl
group
group2ndx
hyper
diff --git a/doc/src/dihedral_hybrid.rst b/doc/src/dihedral_hybrid.rst
index 998a752275..460c329de9 100644
--- a/doc/src/dihedral_hybrid.rst
+++ b/doc/src/dihedral_hybrid.rst
@@ -1,8 +1,11 @@
.. index:: dihedral_style hybrid
+.. index:: dihedral_style hybrid/kk
dihedral_style hybrid command
=============================
+Accelerator Variants: *hybrid/kk*
+
Syntax
""""""
@@ -80,6 +83,10 @@ for specific dihedral types.
----------
+.. include:: accel_styles.rst
+
+----------
+
Restrictions
""""""""""""
@@ -88,8 +95,10 @@ MOLECULE package. See the :doc:`Build package ` doc page
for more info.
Unlike other dihedral styles, the hybrid dihedral style does not store
-dihedral coefficient info for individual sub-styles in a :doc:`binary restart files `. Thus when restarting a simulation from a
-restart file, you need to re-specify dihedral_coeff commands.
+dihedral coefficient info for individual sub-styles in :doc:`binary
+restart files ` or :doc:`data files `. Thus when
+restarting a simulation, you need to re-specify the dihedral_coeff
+commands.
Related commands
""""""""""""""""
diff --git a/doc/src/dump_image.rst b/doc/src/dump_image.rst
index 3102caaa97..d7350c4e9b 100644
--- a/doc/src/dump_image.rst
+++ b/doc/src/dump_image.rst
@@ -111,10 +111,10 @@ Syntax
.. parsed-literal::
*acolor* args = type color
- type = atom type or range of types (see below)
+ type = atom type (numeric or type label) or range of numeric types (see below)
color = name of color or color1/color2/...
*adiam* args = type diam
- type = atom type or range of types (see below)
+ type = atom type (numeric or type label) or range of numeric types (see below)
diam = diameter of atoms of that type (distance units)
*amap* args = lo hi style delta N entry1 entry2 ... entryN
lo = number or *min* = lower bound of range of color map
@@ -139,10 +139,10 @@ Syntax
*backcolor* arg = color
color = name of color for background
*bcolor* args = type color
- type = bond type or range of types (see below)
+ type = bond type (numeric or type label) or range of numeric types (see below)
color = name of color or color1/color2/...
*bdiam* args = type diam
- type = bond type or range of types (see below)
+ type = bond type (numeric or type label) or range of numeric types (see below)
diam = diameter of bonds of that type (distance units)
*bitrate* arg = rate
rate = target bitrate for movie in kbps
@@ -169,6 +169,9 @@ Examples
dump_modify 1 amap min max cf 0.0 3 min green 0.5 yellow max blue boxcolor red
+ labelmap atom 1 C 2 H 3 O 4 N
+ dump_modify 1 acolor C gray acolor H white acolor O red acolor N blue
+
Description
"""""""""""
@@ -739,15 +742,15 @@ The *acolor* keyword can be used with the dump image command, when its
atom color setting is *type*, to set the color that atoms of each type
will be drawn in the image.
-The specified *type* should be an integer from 1 to Ntypes = the
-number of atom types. A wildcard asterisk can be used in place of or
-in conjunction with the *type* argument to specify a range of atom
-types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N =
-the number of atom types, then an asterisk with no numeric values
-means all types from 1 to N. A leading asterisk means all types from
-1 to n (inclusive). A trailing asterisk means all types from n to N
-(inclusive). A middle asterisk means all types from m to n
-(inclusive).
+The specified *type* should be a type label or integer from 1 to Ntypes
+= the number of atom types. For numeric types, a wildcard asterisk can
+be used in place of or in conjunction with the *type* argument to
+specify a range of atom types. This takes the form "\*" or "\*n" or
+"n\*" or "m\*n". If N = the number of atom types, then an asterisk with
+no numeric values means all types from 1 to N. A leading asterisk
+means all types from 1 to n (inclusive). A trailing asterisk means all
+types from n to N (inclusive). A middle asterisk means all types from
+m to n (inclusive).
The specified *color* can be a single color which is any of the 140
pre-defined colors (see below) or a color name defined by the
@@ -761,11 +764,12 @@ fashion to each of the specified atom types.
The *adiam* keyword can be used with the dump image command, when its
atom diameter setting is *type*, to set the size that atoms of each
-type will be drawn in the image. The specified *type* should be an
-integer from 1 to Ntypes. As with the *acolor* keyword, a wildcard
-asterisk can be used as part of the *type* argument to specify a range
-of atom types. The specified *diam* is the size in whatever distance
-:doc:`units ` the input script is using, e.g. Angstroms.
+type will be drawn in the image. The specified *type* should be a type
+label or integer from 1 to Ntypes. As with the *acolor* keyword, a
+wildcard asterisk can be used as part of the *type* argument to specify
+a range of numeric atom types. The specified *diam* is the size in
+whatever distance :doc:`units ` the input script is using, e.g.
+Angstroms.
----------
@@ -908,14 +912,15 @@ The *bcolor* keyword can be used with the dump image command, with its
*bond* keyword, when its color setting is *type*, to set the color
that bonds of each type will be drawn in the image.
-The specified *type* should be an integer from 1 to :math:`N`, where :math:`N`
-is the number of bond types. A wildcard asterisk can be used in place of or
-in conjunction with the *type* argument to specify a range of bond
-types. This takes the form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N`
-is the number of bond types, then an asterisk with no numerical values
-means all types from 1 to :math:`N`. A leading asterisk means all types from
-1 to n (inclusive). A trailing asterisk means all types from m to :math:`N`
-(inclusive). A middle asterisk means all types from m to n
+The specified *type* should be a type label or integer from 1 to
+:math:`N`, where :math:`N` is the number of bond types. For numeric
+types, a wildcard asterisk can be used in place of or in conjunction
+with the *type* argument to specify a range of bond types. This takes
+the form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is the number
+of bond types, then an asterisk with no numerical values means all
+types from 1 to :math:`N`. A leading asterisk means all types from 1
+to n (inclusive). A trailing asterisk means all types from m to
+:math:`N` (inclusive). A middle asterisk means all types from m to n
(inclusive).
The specified *color* can be a single color which is any of the 140
@@ -931,11 +936,11 @@ of the specified bond types.
The *bdiam* keyword can be used with the dump image command, with its
*bond* keyword, when its *diam* setting is *type*, to set the diameter
that bonds of each type will be drawn in the image. The specified
-*type* should be an integer from 1 to Nbondtypes. As with the
-*bcolor* keyword, a wildcard asterisk can be used as part of the
-*type* argument to specify a range of bond types. The specified
-*diam* is the size in whatever distance :doc:`units ` you are
-using (e.g., Angstroms).
+*type* should be a type label or integer from 1 to Nbondtypes. As with
+the *bcolor* keyword, a wildcard asterisk can be used as part of the
+*type* argument to specify a range of numeric bond types. The
+specified *diam* is the size in whatever distance :doc:`units `
+you are using (e.g., Angstroms).
----------
diff --git a/doc/src/dump_modify.rst b/doc/src/dump_modify.rst
index 79fdf2cc3e..1f2b1c8e0e 100644
--- a/doc/src/dump_modify.rst
+++ b/doc/src/dump_modify.rst
@@ -107,6 +107,13 @@ Syntax
*checksum* args = *yes* or *no* (add checksum at end of zst file)
+* these keywords apply only to the vtk* dump style
+* keyword = *binary*
+
+ .. parsed-literal::
+
+ *binary* args = *yes* or *no* (select between binary and text mode VTK files)
+
Examples
""""""""
@@ -907,11 +914,11 @@ box size stored with the snapshot.
----------
-The COMPRESS package offers both GZ and Zstd compression variants of
-styles atom, custom, local, cfg, and xyz. When using these styles the
-compression level can be controlled by the :code:`compression_level`
-keyword. File names with these styles have to end in either
-:code:`.gz` or :code:`.zst`.
+The :ref:`COMPRESS package ` offers both GZ and Zstd
+compression variants of styles atom, custom, local, cfg, and xyz. When
+using these styles the compression level can be controlled by the
+:code:`compression_level` keyword. File names with these styles have to
+end in either :code:`.gz` or :code:`.zst`.
GZ supports compression levels from :math:`-1` (default), 0 (no compression),
and 1 to 9, 9 being the best compression. The COMPRESS :code:`/gz` styles use 9
@@ -930,6 +937,17 @@ default and it can be disabled with the :code:`checksum` keyword.
----------
+The :ref:`VTK package ` offers writing dump files in `VTK file
+formats ` the dump_modify command supports the
+keyword *binary* which selects between generating text mode and binary
+style VTK files.
+
+----------
+
Restrictions
""""""""""""
diff --git a/doc/src/fix_colvars.rst b/doc/src/fix_colvars.rst
index 5acd79ba34..936fdaa83b 100644
--- a/doc/src/fix_colvars.rst
+++ b/doc/src/fix_colvars.rst
@@ -8,151 +8,228 @@ Syntax
.. code-block:: LAMMPS
- fix ID group-ID colvars configfile keyword values ...
+ fix ID group-ID colvars *configfile* keyword value ...
-* ID, group-ID are documented in :doc:`fix ` command
-* colvars = style name of this fix command
-* configfile = the configuration file for the colvars module
-* keyword = *input* or *output* or *seed* or *unwrap* or *tstat*
+* *ID*, *group-ID* are documented in :doc:`fix ` command
+* "colvars" = style name of this fix command
+* *configfile* = configuration file for Colvars (use "*none*" to provide it inline)
+* keyword = *output* or *input* or *unwrap* or *tstat* or *seed*
.. parsed-literal::
-
- *input* arg = colvars.state file name or prefix or NULL (default: NULL)
- *output* arg = output filename prefix (default: out)
- *seed* arg = seed for random number generator (default: 1966)
- *unwrap* arg = *yes* or *no*
- use unwrapped coordinates in collective variables (default: yes)
- *tstat* arg = fix id of a thermostat or NULL (default: NULL)
+ *output* value = state filename/prefix for Colvars (default: "out")
+ *input* value = input state filename/prefix for Colvars (optional, default: "NULL")
+ *unwrap* value = "yes" or "no" (default: "yes")
+ *tstat* value = fix ID of thermostat applied to relevant atoms (default: "NULL")
+ *seed* value = seed for random number generator (default: 1966)
Examples
""""""""
.. code-block:: LAMMPS
- fix mtd all colvars peptide.colvars.inp seed 2122 input peptide.colvars.state output peptide
- fix abf all colvars colvars.inp tstat 1
+ # Create the fix using a config file, set prefix for its output files
+ fix Colvars all colvars colvars.inp output ${JOB}
+
+ # Communicate the LAMMPS target temperature to the Colvars module
+ fix_modify Colvars tstat NPT
+
+ # Add a new restraint specific to this LAMMPS run
+ fix_modify Colvars config """
+ harmonic {
+ name restraint
+ colvars distance1 distance2
+ centers ${ref1} ${ref2}
+ forceConstant ${kappa}
+ }"""
Description
"""""""""""
-This fix interfaces LAMMPS to the collective variables (Colvars)
-library, which allows to calculate potentials of mean force (PMFs) for
-any set of colvars, using sampling methods, including but not limited to
-Adaptive Biasing Force (ABF), metadynamics (MtD), Steered Molecular
-Dynamics (SMD) and Umbrella Sampling (US) via a flexible harmonic
-restraint bias.
+This fix interfaces LAMMPS to the collective variables `Colvars
+`_ library, which allows to accelerate sampling of
+rare events and the computation of free energy surfaces and potentials of
+mean force (PMFs) for any set of collective variables using a variety of
+sampling methods (e.g. umbrella-sampling, metadynamics, ABF...).
-This documentation describes only the ``fix colvars`` command itself in
-a LAMMPS script. The Colvars library is documented via the included
-`PDF manual `_ or at the webpage
+This documentation describes only the "fix colvars" command itself in
+a LAMMPS script. The Colvars library is fully documented in the included
+`PDF manual `_ or in the webpage
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html
`_.
The Colvars library is developed at `https://github.com/Colvars/colvars
-`_ A detailed discussion of its
-implementation is in :ref:`(Fiorin) `; additional references are
-printed at runtime based on specific features being used.
+`_ A detailed discussion of its
+implementation is in :ref:`(Fiorin) `; additional citations for
+specific features are printed at runtime if these features are used.
-There are some example scripts for using this package with LAMMPS in the
-``examples/PACKAGES/colvars`` directory.
+There are example scripts on the `Colvars website `_
+as well as in the ``examples/PACKAGES/colvars`` directory in the LAMMPS
+source tree.
----------
-The only required argument to ``fix colvars`` is the filename to the
-Colvars configuration file that contains the definition of the variables
-and any biasing methods applied to them. from the MD program in which
-the colvars library has been integrated.
+The only required argument to the fix is the name of the Colvars
+configuration file. The contents of this file are independent from the MD
+engine in which the Colvars library has been integrated, save for the units
+that are specific to each engine. In LAMMPS, the units used by Colvars are
+consistent with those specificed by the :doc:`units ` command.
-The *group-ID* entry is ignored. ``fix colvars`` will always apply to
+.. versionadded:: Colvars_2023-06-04 The special value "*none*"
+ (lowercase) initializes an empty Colvars module, which
+ allows loading configuration dynamically using
+ :doc:`fix_modify ` (see below).
+
+The *group-ID* entry is ignored. "fix colvars" will always apply to
the entire system, but specific atoms will be selected based on
selection keywords in the Colvars configuration file or files. There is
-no need to define multiple ``fix colvars`` instances and it is not
+no need to define multiple "fix colvars" instances and it is not
allowed.
-The *output* keyword allows to specify the prefix of output files
-generated by Colvars, for example ``output.colvars.traj`` or
-``output.pmf``.
+The "output" keyword allows to specify the prefix of output files generated
+by Colvars, for example "*output*.colvars.traj" or "output.pmf". Supplying
+an empty string suppresses any file output from Colvars to file, except for
+data saved into the LAMMPS :doc:`binary restart ` files.
-The *input* keyword allows to specify an optional state file that
-contains the restart information needed to continue a previous
-simulation state. Note, however, that ``fix colvars`` records its state
-in :doc:`binary restart ` files, so when using the
-:doc:`read_restart ` command, this is usually not needed.
+The "input" keyword allows to specify an optional state file that contains
+the restart information needed to continue a previous simulation state.
+However, because "fix colvars" records its state in LAMMPS :doc:`binary
+restart ` files, this is usually not needed when using the
+:doc:`read_restart ` command.
-The *seed* keyword contains the seed for the random number generator
-used by Colvars.
-
-The *unwrap* keyword controls whether wrapped or unwrapped coordinates
-are passed to the Colvars library for calculation of the collective
-variables and the resulting forces. The default is *yes*, i.e. to use
-the image flags to reconstruct the absolute atom positions. Setting
-this to *no* will use the current local coordinates that are wrapped
-back into the simulation cell at each re-neighboring instead. For
-information about when and how this affects results, please see
+The *unwrap* keyword controls whether wrapped or unwrapped coordinates are
+passed to the Colvars library for calculation of the collective variables and
+the resulting forces. The default is *yes*, i.e. the image flags are used to
+reconstruct the absolute atom positions. Setting this to *no* will use the
+current local coordinates that are wrapped back into the simulation cell at
+each re-neighboring step instead. For information about when and how this
+affects results, please see
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping
`_.
-The *tstat* keyword can be either NULL or the label of a thermostatting
-fix that thermostats all atoms in the fix colvars group. This will be
-used to let Colvars know what is the current thermostat target
+The *tstat* keyword can be either "NULL" or the label of a thermostatting
+fix that thermostats all atoms in the fix colvars group. This will be
+used to provide the colvars module with the current thermostat target
temperature.
-Restart, fix_modify, output, run start/stop, minimize info
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+The *seed* keyword contains the seed for the random number generator
+that will be used in the colvars module.
-This fix writes the current status of the colvars module into
-:doc:`binary restart files `. This is in addition to the text
-mode ``.colvars.state`` written by Colvars itself and the information in
-both files is identical.
-The :doc:`fix_modify ` *energy* option is supported by this
-fix to add the energy change from the biasing force added by Colvars to
-the global potential energy of the system as part of :doc:`thermodynamic
-output `. The default setting for this fix is
-:doc:`fix_modify energy no `.
+Restarting
+""""""""""
-The *fix_modify configfile * option loads Colvars
-configuration from an additional file. This option can only be used,
-after the system has been initialized with a :doc:`run ` command.
+This fix writes the current state of the Colvars module into :doc:`binary
+restart files `. This is in addition to the text-mode
+".colvars.state" state file that is written by the Colvars module itself.
+The information contained in both files is identical, and the binary LAMMPS
+restart file is also used by fix colvars when :doc:`read_restart
+` is called in a LAMMPS script. In that case, there is
+typically no need to specify the *input* keyword.
-The *fix_modify config * option allows to add settings
-from inline strings. Those have to fit on a single line when enclosed in
-a pair of double quotes ("), or can span multiple lines when bracketed
-by a pair of triple double quotes (""", like Python embedded
-documentation).
+As long as LAMMPS binary restarts will be used to continue a simulation, it
+is safe to delete the ".colvars.state" files to save space. However, when a
+LAMMPS simulation is restarted using :doc:`read_data `, the
+Colvars state file must be available and loaded via the "input" keyword or
+via a "fix_modify Colvars load" command (see below).
+
+When restarting, the fix and the Colvars module should be created and
+configured using either the original configuration file(s).
+
+
+Output
+""""""
This fix computes a global scalar which can be accessed by various
-:doc:`output commands `. The scalar is the Colvars energy
-mentioned above. The scalar value calculated by this fix is
-"extensive".
+:doc:`output commands `. The scalar is the energy due to all
+external potentials defined in the Colvars configuration. The scalar value
+calculated by this fix is "extensive".
+
+Aside from the state information in a ".colvars.state" file, other
+`output files `_
+are produced by Colvars depending on the type of simulation.
+For this reason, the "output" keyword is required for fix colvars.
+
+
+Controlling Colvars via `fix_modify`
+""""""""""""""""""""""""""""""""""""
+
+The :doc:`fix_modify ` command may be used on "fix colvars" in
+either one of two ways:
+
+(1) Provide updated values for the fix parameters, such as *output*, *input*,
+ *unwrap*, *tstat* and *seed*. Additionally, the :doc:`fix_modify
+ ` *energy* keyword is supported by this fix to add the energy
+ change from the biasing force added by Colvars to the global potential
+ energy of the system as part of :doc:`thermodynamic output `
+ (the default is :doc:`fix_modify energy no `).
+ For example, in a multi-step LAMMPS script involving multiple thermostats
+ (e.g. fix nvt followed by fix npt), Colvars can read a new thermostat's
+ target temperature like this:
+
+ .. code-block:: LAMMPS
+
+ fix NVT all nvt ...
+ fix Colvars all colvars output equil1 tstat NVT
+ run
+ unfix nvt
+ fix NPT all n ...
+ fix_modify Colvars tstat NPT
+ fix_modify Colvars output equil2
+
+
+(2) .. versionadded:: Colvars_2023-06-04 Call one of the scripting
+ functions provided by the Colvars module itself (a full list is available
+ in the Colvars doc). The arguments to these functions are provided as
+ strings and passed to Colvars.
+
+ LAMMPS variables referenced by their string representation
+ "${variable}" will be expanded immediately. Note also that this
+ variable expansion *will also happen within quotes*, similar to what the
+ :doc:`mdi ` command provides. This feature makes it possible to use
+ the values of certain LAMMPS variables in Colvars configuration strings.
+ For example, to synchronize the LAMMPS and Colvars dump frequencies:
+
+ .. code-block:: LAMMPS
+
+ variable freq index 10000
+ dump myDump all atom/zstd ${freq} dump.atom.zstd
+ fix_modify Colvars config "colvarsTrajFrequency ${freq}"
+
+.. note::
+
+ Although it is possible to use :doc:`fix_modify ` at any time,
+ its results will only reflect the state of the Colvars module at the end
+ of the most recent "run" or "minimize" command. Any new configuration
+ added via "fix_modify Colvars configfile" or "fix_modify Colvars config"
+ will only be loaded when the simulation resumes. Configuration files or
+ strings will be parsed in the same sequence as they were provided in the
+ LAMMPS script.
+
Restrictions
""""""""""""
-``fix colvars`` is provided by the COLVARS package and is only available
-if LAMMPS was built with that package. Some of the features also
-require code available from the LEPTON package. See the :doc:`Build
+This fix is provided by the COLVARS package and is only available if LAMMPS
+was built with that package (default in most builds). Some of the features
+also require code available from the LEPTON package. See the :doc:`Build
package ` page for more info.
There can only be one Colvars instance defined at a time. Since the
-interface communicates only the minimum amount of information and the
-Colvars module itself can handle an arbitrary number of collective
+interface communicates only the minimum required amount of information, and
+the Colvars module itself can handle an arbitrary number of collective
variables, this is not a limitation of functionality.
+
Related commands
""""""""""""""""
:doc:`fix smd `, :doc:`fix spring `,
:doc:`fix plumed `
-Default
-"""""""
-
-The default options are input = NULL, output = out, seed = 1966, unwrap yes,
-and tstat = NULL.
-
----------
.. _Fiorin:
+**(Fiorin)** Fiorin, Klein, Henin, Mol. Phys. 111, 3345 (2013) https://doi.org/10.1080/00268976.2013.813594
-**(Fiorin)** Fiorin, Klein, Henin, Mol. Phys., DOI:10.1080/00268976.2013.813594
+.. _Colvars_LAMMPS_doc:
+https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html
diff --git a/doc/src/fix_meso_move.rst b/doc/src/fix_meso_move.rst
index 55d54b2107..64b451b7f1 100644
--- a/doc/src/fix_meso_move.rst
+++ b/doc/src/fix_meso_move.rst
@@ -247,6 +247,11 @@ defined by the :doc:`atom_style sph ` command.
All particles in the group must be mesoscopic SPH/SDPD particles.
+.. versionchanged:: TBD
+
+This fix is incompatible with deformation controls that remap velocity,
+for instance the *remap v* option of :doc:`fix deform `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/fix_mvv_dpd.rst b/doc/src/fix_mvv_dpd.rst
index ff5b169f97..e64a162bf4 100644
--- a/doc/src/fix_mvv_dpd.rst
+++ b/doc/src/fix_mvv_dpd.rst
@@ -97,6 +97,11 @@ These fixes are part of the DPD-MESO package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package
` page for more info.
+.. versionchanged:: TBD
+
+This fix is incompatible with deformation controls that remap velocity,
+for instance the *remap v* option of :doc:`fix deform `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/fix_pimd.rst b/doc/src/fix_pimd.rst
index a2e137da25..0c7f763ced 100644
--- a/doc/src/fix_pimd.rst
+++ b/doc/src/fix_pimd.rst
@@ -236,7 +236,7 @@ The keyword *fixcom* specifies whether the center-of-mass of the extended ring-p
Once *fixcom* is set to be *yes*, the center-of-mass velocity will be distracted from the centroid-mode velocities in each step.
The keyword *lj* should be used if :doc:`lj units ` is used for *fix pimd/langevin*. Typically one may want to use
-reduced units to run the simulation, and then convert the results into some physical units (for example, :doc:`metal units `). In this case, the 5 quantities in the physical mass units are needed: epsilon (energy scale), sigma (length scale), mass, Planck's constant, mvv2e (mass * velocity^2 to energy conversion factor). Planck's constant and mvv2e can be found in src/update.cpp. If there is no need to convert reduced units to physical units, set all these five value to 1.
+reduced units to run the simulation, and then convert the results into some physical units (for example, :doc:`metal units `). In this case, the 5 quantities in the physical mass units are needed: epsilon (energy scale), sigma (length scale), mass, Planck's constant, mvv2e (mass * velocity^2 to energy conversion factor). Planck's constant and mvv2e can be found in src/update.cpp. If there is no need to convert reduced units to physical units, you can omit the keyword *lj* and these five values will be set to 1.
The PIMD algorithm in LAMMPS is implemented as a hyper-parallel scheme
as described in :ref:`Calhoun `. In LAMMPS this is done by using
diff --git a/doc/src/fix_rigid_meso.rst b/doc/src/fix_rigid_meso.rst
index c8c994fd26..3f734e3fef 100644
--- a/doc/src/fix_rigid_meso.rst
+++ b/doc/src/fix_rigid_meso.rst
@@ -353,6 +353,11 @@ defined by the :doc:`atom_style sph ` command.
All particles in the group must be mesoscopic SPH/SDPD particles.
+.. versionchanged:: TBD
+
+This fix is incompatible with deformation controls that remap velocity,
+for instance the *remap v* option of :doc:`fix deform `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/fix_shake.rst b/doc/src/fix_shake.rst
index 73caa9c668..4129dcd9af 100644
--- a/doc/src/fix_shake.rst
+++ b/doc/src/fix_shake.rst
@@ -27,9 +27,9 @@ Syntax
.. parsed-literal::
- *b* values = one or more bond types
- *a* values = one or more angle types
- *t* values = one or more atom types
+ *b* values = one or more bond types (may use type labels)
+ *a* values = one or more angle types (may use type labels)
+ *t* values = one or more atom types (may use type labels)
*m* value = one or more mass values
* zero or more keyword/value pairs may be appended
@@ -137,7 +137,17 @@ constrained (within a fudge factor of MASSDELTA specified in
both bonds in the angle are constrained then the angle will also be
constrained if its type is in the list.
-For all constraints, a particular bond is only constrained if both
+.. versionchanged:: TBD
+
+The types may be given as type labels *only* if there is no atom, bond,
+or angle type label named *b*, *a*, *t*, or *m* defined in the
+simulation. If that is the case, type labels cannot be used as
+constraint type index with these two fixes, because the type labels
+would be incorrectly treated as a new type of constraint instead.
+Thus, LAMMPS will print a warning and type label handling is disabled
+and numeric types must be used.
+
+For all constraints, a particular bond is only constrained if *both*
atoms in the bond are in the group specified with the SHAKE fix.
The degrees-of-freedom removed by SHAKE bonds and angles are accounted
diff --git a/doc/src/fix_smd_integrate_tlsph.rst b/doc/src/fix_smd_integrate_tlsph.rst
index 515b30d4ff..44d4bab3a5 100644
--- a/doc/src/fix_smd_integrate_tlsph.rst
+++ b/doc/src/fix_smd_integrate_tlsph.rst
@@ -53,6 +53,11 @@ Restrictions
This fix is part of the MACHDYN package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package ` page for more info.
+.. versionchanged:: TBD
+
+This fix is incompatible with deformation controls that remap velocity,
+for instance the *remap v* option of :doc:`fix deform `.
+
Related commands
""""""""""""""""
diff --git a/doc/src/fix_smd_integrate_ulsph.rst b/doc/src/fix_smd_integrate_ulsph.rst
index 17dfdb7b17..6b1e070763 100644
--- a/doc/src/fix_smd_integrate_ulsph.rst
+++ b/doc/src/fix_smd_integrate_ulsph.rst
@@ -61,6 +61,11 @@ Restrictions
This fix is part of the MACHDYN package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package