comphy-lab · pull · Jan 28, 2026 · Jan 20, 2026 · Jan 20, 2026 · Jan 20, 2026
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -174,6 +174,10 @@
 
 # docs
 /doc/*                  @akohlmey
+/doc/src/Howto_viz.rst  @akohlmey
+/doc/src/Howto_spc.rst  @akohlmey
+/doc/src/Howto_tip*.rst @akohlmey
+/examples/GRAPHICS/     @akohlmey
 /examples/plugin/       @akohlmey
 /examples/PACKAGES/pace/plugin/  @akohlmey
 

diff --git a/.github/release_steps.md b/.github/release_steps.md
@@ -212,6 +212,26 @@ gh release upload patch_4Feb2025 LAMMPS-Win10-64bit-GUI-4Feb2025.exe
 The symbolic link is used to have a consistent naming scheme for the packages
 attached to the GitHub release page.
 
+#### LAMMPS Online Manual
+
+Creating the online docs requires setting some environment variables to have
+the extra box at the bottom of the navigation bar included that allows to
+switch between release, stable, and develop branch versions of the manual.
+Also the search box should use Google search instead of the javascript search.
+
+``` sh
+cd lammps-release
+make -C doc clean
+make -C doc upgrade
+env LAMMPS_WEBSITE_BUILD=1 LAMMPS_WEBSITE_BUILD_VERSION=release LAMMPS_WEBSITE_BASEURL="https://docs.lammps.org/" \
+    make -C doc html WEB_SEARCH=YES
+make -C doc pdf
+mv doc/Manual.pdf doc/html
+rsync -arpv doc/html/ www.lammps.org:/var/www/lammps/docs/release-new
+
+Then log into www.lammps.org and move the current folder away and
+the new folder in its place and update permissions.
+
 #### Clean up:
 
 ``` sh
@@ -243,6 +263,7 @@ and installed (e.g. to `$HOME/.local`) as static libraries only:
 - jpeg
 - zlib
 - png
+- voro++ (for VORONOI package)
 - Qt (for LAMMPS-GUI)
 
 When configuring LAMMPS the `cmake/presets/clang.cmake` should be used
@@ -298,8 +319,8 @@ Check out the LAMMPS website repo
 https://github.com/lammps/lammps-website.git and edit the file
 `src/download.txt` for the new release.  Test translation with `make
 html` and review `html/download.html` Then add and commit to git and
-push the changes to GitHub.  The Temple Jenkis cluster will
-automatically update https://www.lammps.org/download.html accordingly.
+push the changes to GitHub.  A cron job will automatically update
+https://www.lammps.org/ accordingly if there are changes.
 
 Also notify Steve of the release so he can update `src/bug.txt` on the
 website from the available release notes.
@@ -373,11 +394,10 @@ git tag -s -m 'Update 2 for Stable LAMMPS version 29 August 2024' stable_29Aug20
 git push [email protected]:lammps/lammps.git --tags maintenance stable
 ```
 
-Associate draft release notes with new tag and publish as "latest release".
-
-On https://ci.lammps.org/ go to "dev", "stable" and manually execute
-the "update\_release" task. This will update https://docs.lammps.org/stable
-and prepare a stable tarball.
+Associate draft release notes with new tag and prepare and upload
+various source and binary packages. Publish as "latest release"
+only when all uploads are complete as they cannot be changed after
+they are published since we are creating "immutable" releases now.
 
 ### Build and upload binary packages and source tarball to GitHub
 

diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -193,7 +193,10 @@ endif()
 
 # do not include the (obsolete) MPI C++ bindings which makes for leaner object files
 # and avoids namespace conflicts. Put this early to increase its visbility.
-set(MPI_CXX_SKIP_MPICXX TRUE CACHE BOOL "Skip MPI C++ Bindings" FORCE)
+# do not apply when compiling SCAFACOS since it uses the obsolete bindings
+if (NOT PKG_SCAFACOS)
+  set(MPI_CXX_SKIP_MPICXX TRUE CACHE BOOL "Skip MPI C++ Bindings" FORCE)
+endif()
 
 ########################################################################
 # User input options                                                   #

diff --git a/cmake/Modules/Packages/SCAFACOS.cmake b/cmake/Modules/Packages/SCAFACOS.cmake
@@ -3,7 +3,7 @@ enable_language(C)
 
 find_package(GSL REQUIRED)
 find_package(PkgConfig QUIET)
-find_package(MPI REQUIRED)
+find_package(MPI REQUIRED COMPONENTS C MPICXX CXX Fortran)
 set(DOWNLOAD_SCAFACOS_DEFAULT ON)
 if(PKG_CONFIG_FOUND)
   pkg_check_modules(SCAFACOS QUIET scafacos)
@@ -19,6 +19,8 @@ if(DOWNLOAD_SCAFACOS)
   mark_as_advanced(SCAFACOS_URL)
   mark_as_advanced(SCAFACOS_MD5)
   GetFallbackURL(SCAFACOS_URL SCAFACOS_FALLBACK)
+  set(SCAFACOS_CXX_FLAGS "${CMAKE_CXX_FLAGS_${CMAKE_BUILD_TYPE}} ${CMAKE_CXX_FLAGS}")
+  set(SCAFACOS_C_FLAGS "${CMAKE_C_FLAGS_${CMAKE_BUILD_TYPE}} ${CMAKE_C_FLAGS}")
 
   include(ExternalProject)
   ExternalProject_Add(scafacos_build
@@ -32,6 +34,8 @@ if(DOWNLOAD_SCAFACOS)
                                              CXX=${CMAKE_MPI_CXX_COMPILER}
                                              CC=${CMAKE_MPI_C_COMPILER}
                                              F77=
+                                             CFLAGS=${SCAFACOS_C_FLAGS}
+                                             CXXFLAGS=${SCAFACOS_CXX_FLAGS}
     BUILD_BYPRODUCTS
       <INSTALL_DIR>/lib/libfcs.a
       <INSTALL_DIR>/lib/libfcs_direct.a
@@ -55,7 +59,7 @@ if(DOWNLOAD_SCAFACOS)
   set_target_properties(LAMMPS::SCAFACOS PROPERTIES
     IMPORTED_LOCATION "${INSTALL_DIR}/lib/libfcs.a"
     INTERFACE_INCLUDE_DIRECTORIES "${INSTALL_DIR}/include"
-    INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/libfcs.a;${INSTALL_DIR}/lib/libfcs_direct.a;${INSTALL_DIR}/lib/libfcs_ewald.a;${INSTALL_DIR}/lib/libfcs_fmm.a;${INSTALL_DIR}/lib/libfcs_p2nfft.a;${INSTALL_DIR}/lib/libfcs_p3m.a;GSL::gsl;${INSTALL_DIR}/lib/libfcs_near.a;${INSTALL_DIR}/lib/libfcs_gridsort.a;${INSTALL_DIR}/lib/libfcs_resort.a;${INSTALL_DIR}/lib/libfcs_redist.a;${INSTALL_DIR}/lib/libfcs_common.a;${INSTALL_DIR}/lib/libfcs_pnfft.a;${INSTALL_DIR}/lib/libfcs_pfft.a;${INSTALL_DIR}/lib/libfcs_fftw3_mpi.a;${INSTALL_DIR}/lib/libfcs_fftw3.a;MPI::MPI_Fortran;MPI::MPI_C")
+    INTERFACE_LINK_LIBRARIES "${INSTALL_DIR}/lib/libfcs.a;${INSTALL_DIR}/lib/libfcs_direct.a;${INSTALL_DIR}/lib/libfcs_ewald.a;${INSTALL_DIR}/lib/libfcs_fmm.a;${INSTALL_DIR}/lib/libfcs_p2nfft.a;${INSTALL_DIR}/lib/libfcs_p3m.a;GSL::gsl;${INSTALL_DIR}/lib/libfcs_near.a;${INSTALL_DIR}/lib/libfcs_gridsort.a;${INSTALL_DIR}/lib/libfcs_resort.a;${INSTALL_DIR}/lib/libfcs_redist.a;${INSTALL_DIR}/lib/libfcs_common.a;${INSTALL_DIR}/lib/libfcs_pnfft.a;${INSTALL_DIR}/lib/libfcs_pfft.a;${INSTALL_DIR}/lib/libfcs_fftw3_mpi.a;${INSTALL_DIR}/lib/libfcs_fftw3.a;MPI::MPI_CXX;MPI::MPI_Fortran;MPI::MPI_C;${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES}")
   target_link_libraries(lammps PRIVATE LAMMPS::SCAFACOS)
   add_dependencies(LAMMPS::SCAFACOS scafacos_build)
 else()

diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
@@ -431,6 +431,8 @@ INPUT                  = @LAMMPS_SOURCE_DIR@/utils.cpp                 \
                          @LAMMPS_SOURCE_DIR@/text_file_reader.h        \
                          @LAMMPS_SOURCE_DIR@/potential_file_reader.cpp \
                          @LAMMPS_SOURCE_DIR@/potential_file_reader.h   \
+                         @LAMMPS_SOURCE_DIR@/label_map.cpp             \
+                         @LAMMPS_SOURCE_DIR@/label_map.h               \
                          @LAMMPS_SOURCE_DIR@/my_page.cpp               \
                          @LAMMPS_SOURCE_DIR@/my_page.h                 \
                          @LAMMPS_SOURCE_DIR@/my_pool_chunk.cpp         \

diff --git a/doc/src/Developer_utils.rst b/doc/src/Developer_utils.rst
@@ -558,6 +558,142 @@ A file that would be parsed by the reader code fragment looks like this:
 
 ----------
 
+Type label support
+------------------
+
+Overview
+^^^^^^^^
+
+The :cpp:class:`LabelMap <LAMMPS_NS::LabelMap>` class provides a two way
+mapping between symbolic type labels in input and output files and
+numeric types as they are used by LAMMPS internally.  Instead of
+changing the numeric types in files to satisfy the requirements from
+LAMMPS for a given application, the symbolic types can remain and only
+the label map needs to be adjusted.  When following the convention that
+the labels for bonded interactions are created by joining the
+constituent atom types with hyphens, this can significantly improve
+readability, maintainability, and re-usability of inputs and reduces the
+chance of errors.
+
+The LabelMap class also provides automatic type inference for bonded
+interactions based on their constituent atom types.  For instance, based
+on the atom type labels, the corresponding bond, angle, dihedral, or
+improper types can be inferred provided the corresponding type labels
+follow the convention that they are composed of the symbolic atom types
+connected by hyphens.
+
+Integration with utils namespace
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Several utility functions in the ``utils`` namespace work with type labels and
+interact with the LabelMap class:
+
+* :cpp:func:`utils::is_type() <LAMMPS_NS::utils::is_type>` - Validates whether
+  a string is a valid type label.
+
+* :cpp:func:`utils::expand_type() <LAMMPS_NS::utils::expand_type>` - Converts
+  a type label string to its numeric equivalent using the LabelMap.
+
+* :cpp:func:`utils::bounds_typelabel() <LAMMPS_NS::utils::bounds_typelabel>` -
+  Extended version of ``utils::bounds()`` that accepts type labels in addition
+  to numeric ranges. Uses ``expand_type()`` internally to convert labels to
+  numeric bounds before processing.
+
+These functions enable seamless integration of type labels throughout LAMMPS,
+allowing commands that accept type specifications to work with both numeric
+indices and symbolic labels. Below are some code examples.
+
+Finding types from labels and vice versa
+""""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: c++
+
+   #include "label_map.h"
+   #include "atom.h"
+
+   // assuming this code is used inside a class that is derived from LAMMPS_NS::Pointers
+   LabelMap *lmap = atom->lmap;
+
+   // Forward lookup: Get numeric type from label
+   int ctype = lmap->find_type("C", Atom::ATOM);    // Returns atom type for "C"
+   int htype = lmap->find_type("H", Atom::ATOM);    // Returns atom type for "H"
+   int missing = lmap->find_type("X", Atom::ATOM);  // Returns -1 (not found)
+
+   // Reverse lookup: Get label from numeric type
+   const std::string &label1 = lmap->find_label(1, Atom::ATOM);  // Returns label for type 1
+   const std::string &label2 = lmap->find_label(2, Atom::BOND);  // Returns bond label for type 2
+
+   // Check if all types have labels
+   bool complete = lmap->is_complete(Atom::ATOM);  // Returns true if all atom types labeled
+
+Inferring bonded types from atom types
+""""""""""""""""""""""""""""""""""""""
+
+.. code-block:: c++
+
+   #include "label_map.h"
+   #include "atom.h"
+
+   LabelMap *lmap = atom->lmap;
+
+   // Assume we have: labelmap atom 1 C 2 H 3 N
+   // And: labelmap bond 1 C-H 2 C-C 3 C-N
+
+   // Infer bond type from numeric atom types
+   int bt1 = lmap->infer_bondtype(1, 2);  // Returns 1 (C-H bond)
+   int bt2 = lmap->infer_bondtype(1, 1);  // Returns 2 (C-C bond)
+   int bt3 = lmap->infer_bondtype(3, 1);  // Returns 3 (C-N bond, symmetric match)
+
+   // Infer bond type from atom type labels (handles symmetry automatically)
+   int bt4 = lmap->infer_bondtype({"C", "H"});  // Returns 1 (C-H)
+   int bt5 = lmap->infer_bondtype({"H", "C"});  // Returns 1 (symmetric match)
+   int bt6 = lmap->infer_bondtype({"C", "N"});  // Returns 3 (C-N)
+
+Validating and expanding type labels
+""""""""""""""""""""""""""""""""""""
+
+.. code-block:: c++
+
+   #include "utils.h"
+   #include "lammps.h"
+
+   using namespace LAMMPS_NS;
+
+   LAMMPS *lmp = /* ... */;
+
+   // Validate type label strings
+   int result1 = utils::is_type("C");     // Returns 1 (valid label)
+   int result2 = utils::is_type("123");   // Returns 0 (numeric type)
+   int result3 = utils::is_type("*");     // Returns -1 (invalid - starts with *)
+   int result4 = utils::is_type("C H");   // Returns -1 (invalid - contains whitespace)
+
+   // Convert type label to numeric string
+   char *numstr = utils::expand_type(FLERR, "C", Atom::ATOM, lmp);
+   if (numstr) {
+       // Use the numeric type string
+       delete[] numstr;  // Must delete after use
+   }
+
+   // Convert type label to integer
+   int type = utils::expand_type_int(FLERR, "C", Atom::ATOM, lmp, true);
+   // The 'true' argument enables range verification
+
+   // Use bounds_typelabel for ranges with label support
+   int lo, hi;
+   utils::bounds_typelabel(FLERR, "C:H", 1, 10, lo, hi, lmp, Atom::ATOM);
+   // Expands "C:H" to numeric range, e.g., "1:2" -> lo=1, hi=2
+
+----------
+
+LabelMap class reference
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenclass:: LAMMPS_NS::LabelMap
+   :project: progguide
+   :members:
+
+----------
+
 Memory pool classes
 -------------------
 

diff --git a/doc/src/Howto_viz.rst b/doc/src/Howto_viz.rst
@@ -34,6 +34,83 @@ rarely needed these days.
 
 ------------------------
 
+Basic workflow for loading LAMMPS trajectories in VMD
+=====================================================
+
+VMD can read native LAMMPS dump files (in text format not binary) and
+several other dump styles.  The native LAMMPS format is preferred since
+it contains simulation box information.  VMD does not support reading
+data files directly, but `the TopoTools plugin
+<https://www.ks.uiuc.edu/Research/vmd/plugins/topotools/>`_ does.  This
+step is usually necessary, since the LAMMPS dump files do not contain
+information about the molecular topology and elements and that
+information can be obtained from the data file.  There also is the
+`pbctools plugin
+<https://www.ks.uiuc.edu/Research/vmd/plugins/pbctools/>`_ that can be
+used for "repairing" bonds that are broken because one of its atom
+passed through a periodic boundary.  Because of using the plugins, the
+following commands need to be typed into the VMD console to read a
+trajectory.  The following commands are based on the ``peptide`` example
+to which the command ``dump 1 all atom 10 dump.peptide`` was added.
+Note the use of the group "all" in contrast to the commented out dump
+commands that use the group "peptide".  This is to match the number of
+atoms in the data file.  VMD does not support cases where the number of
+atoms change or you are trying to read in a subset of a system unless
+*all* files contain the same subset.
+
+.. code-block:: Tcl
+
+   # load data file including its coordinates
+   topo readlammpsdata data.peptide full
+   # atom style full is the default ^^^^ and can be omitted
+
+   # try to infer missing atom properties from available information
+   topo guessatom lammps data
+
+   # now add one of more dump files
+   mol addfile dump.peptide type lammpstrj waitfor all
+   # we tell VMD which file type ^^^^^^^^^ if the filename does not end in .lammpstrj
+
+   # jump to the first frame with the data file coordinates
+   animate goto 0
+   # if needed  use the following command to try and repair broken bonds
+   # pbc join fragment -now
+
+   # unwrap the entire trajectory to repair all broken bonds
+   # this is faster and more accurate than running `pbc join` for all frames
+   pbc unwrap -all
+   pbc wrap -all -compound fragment -orthorhombic
+   #       remove for triclinic box ^^^^^^^^^^^^^
+
+   # delete the coordinate frame from the data file
+   animate delete beg 0 end 0 top
+   # write out the topology information without coordinates to a PSF file
+   animate write psf peptide.psf top
+   # and the processed trajectory data to a DCD file for future use
+   animate write dcd peptide.dcd top waitfor all
+
+   ###############################################################
+   # the steps up to this line only need to be run once
+   ###############################################################
+   # set visualization defaults
+   display perspective orthographic
+   mol default style Licorice
+   mol default material Diffuse
+   display backgroundgradient on
+
+   # delete molecule and load psf and dcd file
+   mol delete top
+   mol new peptide.psf
+   mol addfile peptide.dcd waitfor all
+   pbc box
+
+To automate this process, you can also save these commands to a file,
+e.g. ``peptide.vmd`` and then load this file from the VMD "File" menu
+with "Load Visualization State..."  or type in the command console
+``play peptide.vmd``.
+
+------------------------
+
 Advanced graphics features in the *dump image* command
 ======================================================
 

diff --git a/doc/src/Manual.rst b/doc/src/Manual.rst
@@ -81,9 +81,9 @@ The manual is organized into three parts:
 
 .. _user_documentation:
 
-************
+**********
 User Guide
-************
+**********
 
 .. toctree::
    :maxdepth: 2
@@ -106,9 +106,9 @@ User Guide
 
 .. _programmer_documentation:
 
-******************
+****************
 Programmer Guide
-******************
+****************
 
 .. toctree::
    :maxdepth: 2