diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 2686011281..f99a336dbb 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -67,6 +67,7 @@ src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps
src/MISC/*_tracker.* @jtclemm
src/MC/fix_gcmc.* @athomps
src/MC/fix_sgcmc.* @athomps
+src/REPLICA/fix_pimd_langevin.* @Yi-FanLi
# core LAMMPS classes
src/lammps.* @sjplimp
diff --git a/bench/in.chain b/bench/in.chain
index 3993357140..d079f8d99f 100644
--- a/bench/in.chain
+++ b/bench/in.chain
@@ -1,25 +1,25 @@
# FENE beadspring benchmark
-units lj
-atom_style bond
+units lj
+atom_style bond
special_bonds fene
-read_data data.chain
+read_data data.chain
-neighbor 0.4 bin
-neigh_modify every 1 delay 1
+neighbor 0.4 bin
+neigh_modify every 1 delay 1
bond_style fene
-bond_coeff 1 30.0 1.5 1.0 1.0
+bond_coeff 1 30.0 1.5 1.0 1.0
-pair_style lj/cut 1.12
-pair_modify shift yes
-pair_coeff 1 1 1.0 1.0 1.12
+pair_style lj/cut 1.12
+pair_modify shift yes
+pair_coeff 1 1 1.0 1.0 1.12
-fix 1 all nve
-fix 2 all langevin 1.0 1.0 10.0 904297
+fix 1 all nve
+fix 2 all langevin 1.0 1.0 10.0 904297
thermo 100
-timestep 0.012
+timestep 0.012
-run 100
+run 100
diff --git a/bench/in.chain.scaled b/bench/in.chain.scaled
index c2648cc0e8..a56a2788ef 100644
--- a/bench/in.chain.scaled
+++ b/bench/in.chain.scaled
@@ -1,32 +1,32 @@
# FENE beadspring benchmark
-variable x index 1
-variable y index 1
-variable z index 1
+variable x index 1
+variable y index 1
+variable z index 1
-units lj
-atom_style bond
-atom_modify map hash
+units lj
+atom_style bond
+atom_modify map hash
special_bonds fene
-read_data data.chain
+read_data data.chain
-replicate $x $y $z
+replicate $x $y $z
-neighbor 0.4 bin
-neigh_modify every 1 delay 1
+neighbor 0.4 bin
+neigh_modify every 1 delay 1
bond_style fene
-bond_coeff 1 30.0 1.5 1.0 1.0
+bond_coeff 1 30.0 1.5 1.0 1.0
-pair_style lj/cut 1.12
-pair_modify shift yes
-pair_coeff 1 1 1.0 1.0 1.12
+pair_style lj/cut 1.12
+pair_modify shift yes
+pair_coeff 1 1 1.0 1.0 1.12
-fix 1 all nve
-fix 2 all langevin 1.0 1.0 10.0 904297
+fix 1 all nve
+fix 2 all langevin 1.0 1.0 10.0 904297
thermo 100
-timestep 0.012
+timestep 0.012
-run 100
+run 100
diff --git a/bench/in.chute b/bench/in.chute
index 9f7c28ada3..2478e98c96 100644
--- a/bench/in.chute
+++ b/bench/in.chute
@@ -1,33 +1,33 @@
# LAMMPS benchmark of granular flow
# chute flow of 32000 atoms with frozen base at 26 degrees
-units lj
-atom_style sphere
-boundary p p fs
-newton off
-comm_modify vel yes
+units lj
+atom_style sphere
+boundary p p fs
+newton off
+comm_modify vel yes
-read_data data.chute
+read_data data.chute
-pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
-pair_coeff * *
+pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
+pair_coeff * *
-neighbor 0.1 bin
-neigh_modify every 1 delay 0
+neighbor 0.1 bin
+neigh_modify every 1 delay 0
-timestep 0.0001
+timestep 0.0001
-group bottom type 2
-group active subtract all bottom
-neigh_modify exclude group bottom bottom
+group bottom type 2
+group active subtract all bottom
+neigh_modify exclude group bottom bottom
-fix 1 all gravity 1.0 chute 26.0
-fix 2 bottom freeze
-fix 3 active nve/sphere
+fix 1 all gravity 1.0 chute 26.0
+fix 2 bottom freeze
+fix 3 active nve/sphere
-compute 1 all erotate/sphere
-thermo_style custom step atoms ke c_1 vol
-thermo_modify norm no
-thermo 100
+compute 1 all erotate/sphere
+thermo_style custom step atoms ke c_1 vol
+thermo_modify norm no
+thermo 100
-run 100
+run 100
diff --git a/bench/in.chute.scaled b/bench/in.chute.scaled
index 7bac8fe12d..09a6921145 100644
--- a/bench/in.chute.scaled
+++ b/bench/in.chute.scaled
@@ -1,38 +1,38 @@
# LAMMPS benchmark of granular flow
# chute flow of 32000 atoms with frozen base at 26 degrees
-variable x index 1
-variable y index 1
+variable x index 1
+variable y index 1
-units lj
-atom_style sphere
-boundary p p fs
-newton off
-comm_modify vel yes
+units lj
+atom_style sphere
+boundary p p fs
+newton off
+comm_modify vel yes
-read_data data.chute
+read_data data.chute
-replicate $x $y 1
+replicate $x $y 1
-pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
-pair_coeff * *
+pair_style gran/hooke/history 200000.0 NULL 50.0 NULL 0.5 0
+pair_coeff * *
-neighbor 0.1 bin
-neigh_modify every 1 delay 0
+neighbor 0.1 bin
+neigh_modify every 1 delay 0
-timestep 0.0001
+timestep 0.0001
-group bottom type 2
-group active subtract all bottom
-neigh_modify exclude group bottom bottom
+group bottom type 2
+group active subtract all bottom
+neigh_modify exclude group bottom bottom
-fix 1 all gravity 1.0 chute 26.0
-fix 2 bottom freeze
-fix 3 active nve/sphere
+fix 1 all gravity 1.0 chute 26.0
+fix 2 bottom freeze
+fix 3 active nve/sphere
-compute 1 all erotate/sphere
-thermo_style custom step atoms ke c_1 vol
-thermo_modify norm no
-thermo 100
+compute 1 all erotate/sphere
+thermo_style custom step atoms ke c_1 vol
+thermo_modify norm no
+thermo 100
-run 100
+run 100
diff --git a/bench/in.eam b/bench/in.eam
index 1dc0e1a646..b681ab9163 100644
--- a/bench/in.eam
+++ b/bench/in.eam
@@ -1,32 +1,32 @@
# bulk Cu lattice
-variable x index 1
-variable y index 1
-variable z index 1
+variable x index 1
+variable y index 1
+variable z index 1
-variable xx equal 20*$x
-variable yy equal 20*$y
-variable zz equal 20*$z
+variable xx equal 20*$x
+variable yy equal 20*$y
+variable zz equal 20*$z
-units metal
-atom_style atomic
+units metal
+atom_style atomic
-lattice fcc 3.615
-region box block 0 ${xx} 0 ${yy} 0 ${zz}
-create_box 1 box
-create_atoms 1 box
+lattice fcc 3.615
+region box block 0 ${xx} 0 ${yy} 0 ${zz}
+create_box 1 box
+create_atoms 1 box
-pair_style eam
-pair_coeff 1 1 Cu_u3.eam
+pair_style eam
+pair_coeff 1 1 Cu_u3.eam
-velocity all create 1600.0 376847 loop geom
+velocity all create 1600.0 376847 loop geom
-neighbor 1.0 bin
+neighbor 1.0 bin
neigh_modify every 1 delay 5 check yes
-fix 1 all nve
+fix 1 all nve
-timestep 0.005
-thermo 50
+timestep 0.005
+thermo 50
-run 100
+run 100
diff --git a/bench/in.lj b/bench/in.lj
index 01e12ef8a9..7945e67fa5 100644
--- a/bench/in.lj
+++ b/bench/in.lj
@@ -1,30 +1,30 @@
# 3d Lennard-Jones melt
-variable x index 1
-variable y index 1
-variable z index 1
+variable x index 1
+variable y index 1
+variable z index 1
-variable xx equal 20*$x
-variable yy equal 20*$y
-variable zz equal 20*$z
+variable xx equal 20*$x
+variable yy equal 20*$y
+variable zz equal 20*$z
-units lj
-atom_style atomic
+units lj
+atom_style atomic
-lattice fcc 0.8442
-region box block 0 ${xx} 0 ${yy} 0 ${zz}
-create_box 1 box
-create_atoms 1 box
-mass 1 1.0
+lattice fcc 0.8442
+region box block 0 ${xx} 0 ${yy} 0 ${zz}
+create_box 1 box
+create_atoms 1 box
+mass 1 1.0
-velocity all create 1.44 87287 loop geom
+velocity all create 1.44 87287 loop geom
-pair_style lj/cut 2.5
-pair_coeff 1 1 1.0 1.0 2.5
+pair_style lj/cut 2.5
+pair_coeff 1 1 1.0 1.0 2.5
-neighbor 0.3 bin
-neigh_modify delay 0 every 20 check no
+neighbor 0.3 bin
+neigh_modify delay 0 every 20 check no
-fix 1 all nve
+fix 1 all nve
-run 100
+run 100
diff --git a/bench/in.rhodo b/bench/in.rhodo
index bd7e3df7f5..2f34b2721b 100644
--- a/bench/in.rhodo
+++ b/bench/in.rhodo
@@ -1,27 +1,27 @@
# Rhodopsin model
-units real
-neigh_modify delay 5 every 1
+units real
+neigh_modify delay 5 every 1
-atom_style full
-bond_style harmonic
-angle_style charmm
-dihedral_style charmm
-improper_style harmonic
-pair_style lj/charmm/coul/long 8.0 10.0
-pair_modify mix arithmetic
-kspace_style pppm 1e-4
+atom_style full
+bond_style harmonic
+angle_style charmm
+dihedral_style charmm
+improper_style harmonic
+pair_style lj/charmm/coul/long 8.0 10.0
+pair_modify mix arithmetic
+kspace_style pppm 1e-4
read_data data.rhodo
fix 1 all shake 0.0001 5 0 m 1.0 a 232
fix 2 all npt temp 300.0 300.0 100.0 &
- z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
+ z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
special_bonds charmm
-
+
thermo 50
-thermo_style multi
+thermo_style multi
timestep 2.0
-run 100
+run 100
diff --git a/bench/in.rhodo.scaled b/bench/in.rhodo.scaled
index 3debe44867..49a0864fb9 100644
--- a/bench/in.rhodo.scaled
+++ b/bench/in.rhodo.scaled
@@ -1,34 +1,34 @@
# Rhodopsin model
-variable x index 1
-variable y index 1
-variable z index 1
+variable x index 1
+variable y index 1
+variable z index 1
-units real
-neigh_modify delay 5 every 1
+units real
+neigh_modify delay 5 every 1
-atom_style full
-atom_modify map hash
-bond_style harmonic
-angle_style charmm
-dihedral_style charmm
-improper_style harmonic
-pair_style lj/charmm/coul/long 8.0 10.0
-pair_modify mix arithmetic
-kspace_style pppm 1e-4
+atom_style full
+atom_modify map hash
+bond_style harmonic
+angle_style charmm
+dihedral_style charmm
+improper_style harmonic
+pair_style lj/charmm/coul/long 8.0 10.0
+pair_modify mix arithmetic
+kspace_style pppm 1e-4
read_data data.rhodo
-replicate $x $y $z
+replicate $x $y $z
fix 1 all shake 0.0001 5 0 m 1.0 a 232
fix 2 all npt temp 300.0 300.0 100.0 &
- z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
+ z 0.0 0.0 1000.0 mtk no pchain 0 tchain 1
special_bonds charmm
-
+
thermo 50
-thermo_style multi
+thermo_style multi
timestep 2.0
-run 100
+run 100
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
index 1c05e32d0c..f9c5b74589 100644
--- a/cmake/CMakeLists.txt
+++ b/cmake/CMakeLists.txt
@@ -435,7 +435,7 @@ if(BUILD_OMP)
target_link_libraries(lmp PRIVATE OpenMP::OpenMP_CXX)
endif()
-if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE)
+if(PKG_MSCG OR PKG_ATC OR PKG_AWPMD OR PKG_ML-QUIP OR PKG_ML-POD OR PKG_ELECTRODE OR BUILD_TOOLS)
enable_language(C)
if (NOT USE_INTERNAL_LINALG)
find_package(LAPACK)
diff --git a/cmake/Modules/CodingStandard.cmake b/cmake/Modules/CodingStandard.cmake
index 6bb607be12..4efd373d22 100644
--- a/cmake/Modules/CodingStandard.cmake
+++ b/cmake/Modules/CodingStandard.cmake
@@ -5,6 +5,10 @@ if(CMAKE_VERSION VERSION_LESS 3.12)
set(Python3_VERSION ${PYTHON_VERSION_STRING})
endif()
else()
+ # use default (or custom) Python executable, if version is sufficient
+ if(Python_VERSION VERSION_GREATER_EQUAL 3.5)
+ set(Python3_EXECUTABLE ${Python_EXECUTABLE})
+ endif()
find_package(Python3 COMPONENTS Interpreter QUIET)
endif()
diff --git a/cmake/Modules/Documentation.cmake b/cmake/Modules/Documentation.cmake
index 46295feea3..0b01407cd9 100644
--- a/cmake/Modules/Documentation.cmake
+++ b/cmake/Modules/Documentation.cmake
@@ -4,14 +4,18 @@
option(BUILD_DOC "Build LAMMPS HTML documentation" OFF)
if(BUILD_DOC)
- # Sphinx 3.x requires at least Python 3.5
+ # Current Sphinx versions require at least Python 3.8
if(CMAKE_VERSION VERSION_LESS 3.12)
- find_package(PythonInterp 3.5 REQUIRED)
+ find_package(PythonInterp 3.8 REQUIRED)
set(VIRTUALENV ${PYTHON_EXECUTABLE} -m venv)
else()
+ # use default (or custom) Python executable, if version is sufficient
+ if(Python_VERSION VERSION_GREATER_EQUAL 3.8)
+ set(Python3_EXECUTABLE ${Python_EXECUTABLE})
+ endif()
find_package(Python3 REQUIRED COMPONENTS Interpreter)
- if(Python3_VERSION VERSION_LESS 3.5)
- message(FATAL_ERROR "Python 3.5 and up is required to build the HTML documentation")
+ if(Python3_VERSION VERSION_LESS 3.8)
+ message(FATAL_ERROR "Python 3.8 and up is required to build the HTML documentation")
endif()
set(VIRTUALENV ${Python3_EXECUTABLE} -m venv)
endif()
diff --git a/cmake/Modules/Packages/KOKKOS.cmake b/cmake/Modules/Packages/KOKKOS.cmake
index aa93e0cd7c..8b695667ae 100644
--- a/cmake/Modules/Packages/KOKKOS.cmake
+++ b/cmake/Modules/Packages/KOKKOS.cmake
@@ -49,8 +49,8 @@ if(DOWNLOAD_KOKKOS)
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_CXX_EXTENSIONS=${CMAKE_CXX_EXTENSIONS}")
list(APPEND KOKKOS_LIB_BUILD_ARGS "-DCMAKE_TOOLCHAIN_FILE=${CMAKE_TOOLCHAIN_FILE}")
include(ExternalProject)
- set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.7.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
- set(KOKKOS_MD5 "f140e02b826223b1045207d9bc10d404" CACHE STRING "MD5 checksum of KOKKOS tarball")
+ set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/3.7.02.tar.gz" CACHE STRING "URL for KOKKOS tarball")
+ set(KOKKOS_MD5 "34d7860d548c06a4040236d959c9f99a" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK)
@@ -75,7 +75,7 @@ if(DOWNLOAD_KOKKOS)
add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
elseif(EXTERNAL_KOKKOS)
- find_package(Kokkos 3.7.01 REQUIRED CONFIG)
+ find_package(Kokkos 3.7.02 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)
diff --git a/cmake/Modules/Tools.cmake b/cmake/Modules/Tools.cmake
index bc3372f2ae..81d6d66aff 100644
--- a/cmake/Modules/Tools.cmake
+++ b/cmake/Modules/Tools.cmake
@@ -33,6 +33,8 @@ if(BUILD_TOOLS)
endif()
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
+
+ add_subdirectory(${LAMMPS_TOOLS_DIR}/phonon ${CMAKE_BINARY_DIR}/phana_build)
endif()
if(BUILD_LAMMPS_SHELL)
diff --git a/doc/lammps.1 b/doc/lammps.1
index b1be867e60..9bc107624f 100644
--- a/doc/lammps.1
+++ b/doc/lammps.1
@@ -1,7 +1,7 @@
-.TH LAMMPS "1" "28 March 2023" "2023-03-28"
+.TH LAMMPS "1" "15 June 2023" "2023-06-15"
.SH NAME
.B LAMMPS
-\- Molecular Dynamics Simulator. Version 28 March 2023
+\- Molecular Dynamics Simulator. Version 15 June 2023
.SH SYNOPSIS
.B lmp
diff --git a/doc/src/Build_make.rst b/doc/src/Build_make.rst
index f1e34bbc55..f6764100e0 100644
--- a/doc/src/Build_make.rst
+++ b/doc/src/Build_make.rst
@@ -117,8 +117,8 @@ their settings may become outdated, too:
.. code-block:: bash
- make mac # build serial LAMMPS on a Mac
- make mac_mpi # build parallel LAMMPS on a Mac
+ make mac # build serial LAMMPS on macOS
+ make mac_mpi # build parallel LAMMPS on macOS
make intel_cpu # build with the INTEL package optimized for CPUs
make knl # build with the INTEL package optimized for KNLs
make opt # build with the OPT package optimized for CPUs
diff --git a/doc/src/Build_manual.rst b/doc/src/Build_manual.rst
index d86ad85827..4b4bfa5a45 100644
--- a/doc/src/Build_manual.rst
+++ b/doc/src/Build_manual.rst
@@ -53,10 +53,10 @@ incorporates programmer documentation extracted from the LAMMPS C++
sources through the `Doxygen `_ program. Currently
the translation to HTML, PDF (via LaTeX), ePUB (for many e-book readers)
and MOBI (for Amazon Kindle readers) are supported. For that to work a
-Python 3 interpreter, the ``doxygen`` tools and internet access to
-download additional files and tools are required. This download is
-usually only required once or after the documentation folder is returned
-to a pristine state with ``make clean-all``.
+Python interpreter version 3.8 or later, the ``doxygen`` tools and
+internet access to download additional files and tools are required.
+This download is usually only required once or after the documentation
+folder is returned to a pristine state with ``make clean-all``.
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into
diff --git a/doc/src/Commands_compute.rst b/doc/src/Commands_compute.rst
index 2f9c8b03fb..9066531459 100644
--- a/doc/src/Commands_compute.rst
+++ b/doc/src/Commands_compute.rst
@@ -46,6 +46,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`com/chunk `
* :doc:`contact/atom `
* :doc:`coord/atom (k) `
+ * :doc:`count/type `
* :doc:`damage/atom `
* :doc:`dihedral `
* :doc:`dihedral/local `
@@ -152,11 +153,11 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`sph/t/atom `
* :doc:`spin `
* :doc:`stress/atom `
- * :doc:`stress/cartesian `
- * :doc:`stress/cylinder `
+ * :doc:`stress/cartesian `
+ * :doc:`stress/cylinder `
* :doc:`stress/mop `
* :doc:`stress/mop/profile `
- * :doc:`stress/spherical `
+ * :doc:`stress/spherical `
* :doc:`stress/tally `
* :doc:`tdpd/cc/atom `
* :doc:`temp (k) `
diff --git a/doc/src/Commands_fix.rst b/doc/src/Commands_fix.rst
index c74b1fd037..6fe321e3c9 100644
--- a/doc/src/Commands_fix.rst
+++ b/doc/src/Commands_fix.rst
@@ -171,6 +171,7 @@ OPT.
* :doc:`pafi `
* :doc:`pair `
* :doc:`phonon `
+ * :doc:`pimd/langevin `
* :doc:`pimd/nvt `
* :doc:`planeforce `
* :doc:`plumed `
diff --git a/doc/src/Commands_pair.rst b/doc/src/Commands_pair.rst
index 5f79015aaf..c45a1d778c 100644
--- a/doc/src/Commands_pair.rst
+++ b/doc/src/Commands_pair.rst
@@ -37,6 +37,7 @@ OPT.
*
* :doc:`adp (ko) `
* :doc:`agni (o) `
+ * :doc:`aip/water/2dm (t) `
* :doc:`airebo (io) `
* :doc:`airebo/morse (io) `
* :doc:`amoeba (g) `
diff --git a/doc/src/Commands_removed.rst b/doc/src/Commands_removed.rst
index d50eab3a41..1848a28024 100644
--- a/doc/src/Commands_removed.rst
+++ b/doc/src/Commands_removed.rst
@@ -41,7 +41,7 @@ warning.
LATTE package
-------------
-.. deprecated:: TBD
+.. deprecated:: 15Jun2023
The LATTE package with the fix latte command was removed from LAMMPS.
This functionality has been superseded by :doc:`fix mdi/qm `
diff --git a/doc/src/Developer.rst b/doc/src/Developer.rst
index 406dd26f59..b0cfcc14fc 100644
--- a/doc/src/Developer.rst
+++ b/doc/src/Developer.rst
@@ -13,6 +13,7 @@ of time and requests from the LAMMPS user community.
Developer_org
Developer_code_design
Developer_parallel
+ Developer_atom
Developer_comm_ops
Developer_flow
Developer_write
diff --git a/doc/src/Developer_atom.rst b/doc/src/Developer_atom.rst
new file mode 100644
index 0000000000..8bc187ae7f
--- /dev/null
+++ b/doc/src/Developer_atom.rst
@@ -0,0 +1,88 @@
+Accessing per-atom data
+-----------------------
+
+This page discusses how per-atom data is managed in LAMMPS, how it can
+be accessed, what communication patters apply, and some of the utility
+functions that exist for a variety of purposes.
+
+
+Owned and ghost atoms
+^^^^^^^^^^^^^^^^^^^^^
+
+As described on the :doc:`parallel partitioning algorithms
+` page, LAMMPS uses a domain decomposition of the
+simulation domain, either in a *brick* or *tiled* manner. Each MPI
+process *owns* exactly one subdomain and the atoms within it. To compute
+forces for tuples of atoms that are spread across sub-domain boundaries,
+also a "halo" of *ghost* atoms are maintained within a the communication
+cutoff distance of its subdomain.
+
+The total number of atoms is stored in `Atom::natoms` (within any
+typical class this can be referred to at `atom->natoms`. The number of
+*owned* (or "local" atoms) are stored in `Atom::nlocal`; the number of
+*ghost* atoms is stored in `Atom::nghost`. The sum of `Atom::nlocal`
+over all MPI processes should be `Atom::natoms`. This is by default
+regularly checked by the Thermo class, and if the sum does not match,
+LAMMPS stops with a "lost atoms" error. For convenience also the
+property `Atom::nmax` is available, this is the maximum of
+`Atom::nlocal + Atom::nghost` across all MPI processes.
+
+Per-atom properties are either managed by the atom style, or individual
+classes. or as custom arrays by the individual classes. If only access
+to *owned* atoms is needed, they are usually allocated to be of size
+`Atom::nlocal`, otherwise of size `Atom::nmax`. Please note that not all
+per-atom properties are available or updated on *ghost* atoms. For
+example, per-atom velocities are only updated with :doc:`comm_modify vel
+yes `.
+
+
+Atom indexing
+^^^^^^^^^^^^^
+
+When referring to individual atoms, they may be indexed by their local
+*index*, their index in their `Atom::x` array. This is densely populated
+containing first all *owned* atoms (index < `Atom::nlocal`) and then all
+*ghost* atoms. The order of atoms in these arrays can change due to
+atoms migrating between between subdomains, atoms being added or
+deleted, or atoms being sorted for better cache efficiency. Atoms are
+globally uniquely identified by their *atom ID*. There may be multiple
+atoms with the same atom ID present, but only one of them may be an
+*owned* atom.
+
+To find the local *index* of an atom, when the *atom ID* is known, the
+`Atom::map()` function may be used. It will return the local atom index
+or -1. If the returned value is between 0 (inclusive) and `Atom::nlocal`
+(exclusive) it is an *owned* or "local" atom; for larger values the atom
+is present as a ghost atom; for a value of -1, the atom is not present
+on the current subdomain at all.
+
+If multiple atoms with the same tag exist in the same subdomain, they
+can be found via the `Atom::sametag` array. It points to the next atom
+index with the same tag or -1 if there are no more atoms with the same
+tag. The list will be exhaustive when starting with an index of an
+*owned* atom, since the atom IDs are unique, so there can only be one
+such atom. Example code to count atoms with same atom ID in subdomain:
+
+.. code-block:: c++
+
+ for (int i = 0; i < atom->nlocal; ++i) {
+ int count = 0;
+ while (sametag[i] >= 0) {
+ i = sametag[i];
+ ++count;
+ }
+ printf("Atom ID: %ld is present %d times\n", atom->tag[i], count);
+ }
+
+Atom class versus AtomVec classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `Atom` class contains all kinds of flags and counters about atoms in
+the system and that includes pointers to **all** per-atom properties
+available for atoms. However, only a subset of these pointers are
+non-NULL and which those are depends on the atom style. For each atom
+style there is a corresponding `AtomVecXXX` class derived from the
+`AtomVec` base class, where the XXX indicates the atom style. This
+`AtomVecXXX` class will update the counters and per-atom pointers if
+atoms are added or removed to the system or migrate between subdomains.
+
diff --git a/doc/src/Fortran.rst b/doc/src/Fortran.rst
index 42840c62ee..913c31842e 100644
--- a/doc/src/Fortran.rst
+++ b/doc/src/Fortran.rst
@@ -56,17 +56,6 @@ C++ in the ``examples/COUPLE/simple`` folder of the LAMMPS distribution.
and Ubuntu 18.04 LTS and not compatible. Either newer compilers
need to be installed or the Linux updated.
-.. versionchanged:: 8Feb2023
-
-.. note::
-
- A contributed Fortran interface is available in the
- ``examples/COUPLE/fortran2`` folder. However, since the completion
- of the :f:mod:`LIBLAMMPS` module, this interface is now deprecated,
- no longer actively maintained and will likely be removed in the
- future. Please see the ``README`` file in that folder for more
- information about it and how to contact its author and maintainer.
-
----------
Creating or deleting a LAMMPS object
@@ -203,40 +192,62 @@ Below is an example demonstrating some of the possible uses.
.. code-block:: fortran
- PROGRAM testprop
- USE LIBLAMMPS
- USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t
- USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
- TYPE(lammps) :: lmp
- INTEGER(KIND=c_int64_t), POINTER :: natoms
- REAL(KIND=c_double), POINTER :: dt
- INTEGER(KIND=c_int64_t), POINTER :: ntimestep
- REAL(KIND=c_double) :: pe, ke
+ PROGRAM testprop
+ USE LIBLAMMPS
+ USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
+ USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : OUTPUT_UNIT
+ TYPE(lammps) :: lmp
+ INTEGER(KIND=c_int64_t), POINTER :: natoms, ntimestep, bval
+ REAL(KIND=c_double), POINTER :: dt, dval
+ INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
+ INTEGER(KIND=c_int) :: i
+ CHARACTER(LEN=11) :: key
+ REAL(KIND=c_double) :: pe, ke
- lmp = lammps()
- CALL lmp%file('in.sysinit')
- natoms = lmp%extract_global('natoms')
- WRITE(OUTPUT_UNIT,'(A,I0,A)') 'Running a simulation with ', natoms, ' atoms'
- WRITE(OUTPUT_UNIT,'(I0,A,I0,A,I0,A)') lmp%extract_setting('nlocal'), &
- ' local and ', lmp%extract_setting('nghost'), ' ghost atoms. ', &
- lmp%extract_setting('ntypes'), ' atom types'
+ lmp = lammps()
+ CALL lmp%file('in.sysinit')
+ natoms = lmp%extract_global('natoms')
+ WRITE(OUTPUT_UNIT,'(A,I0,A)') 'Running a simulation with ', natoms, ' atoms'
+ WRITE(OUTPUT_UNIT,'(I0,A,I0,A,I0,A)') lmp%extract_setting('nlocal'), &
+ ' local and ', lmp%extract_setting('nghost'), ' ghost atoms. ', &
+ lmp%extract_setting('ntypes'), ' atom types'
- CALL lmp%command('run 2 post no')
- dt = lmp%extract_global('dt')
- ntimestep = lmp%extract_global('ntimestep')
- WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
- ' Changing timestep from', dt, ' to 0.5'
- dt = 0.5_c_double
- CALL lmp%command('run 2 post no')
+ CALL lmp%command('run 2 post no')
- WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
- pe = lmp%get_thermo('pe')
- ke = lmp%get_thermo('ke')
- PRINT*, 'PE = ', pe
- PRINT*, 'KE = ', ke
+ ntimestep = lmp%last_thermo('step', 0)
+ nfield = lmp%last_thermo('num', 0)
+ WRITE(OUTPUT_UNIT,'(A,I0,A,I0)') 'Last thermo output on step: ', ntimestep, &
+ ', number of fields: ', nfield
+ DO i=1, nfield
+ key = lmp%last_thermo('keyword',i)
+ typ = lmp%last_thermo('type',i)
+ IF (typ == lmp%dtype%i32) THEN
+ ival = lmp%last_thermo('data',i)
+ WRITE(OUTPUT_UNIT,*) key, ':', ival
+ ELSE IF (typ == lmp%dtype%i64) THEN
+ bval = lmp%last_thermo('data',i)
+ WRITE(OUTPUT_UNIT,*) key, ':', bval
+ ELSE IF (typ == lmp%dtype%r64) THEN
+ dval = lmp%last_thermo('data',i)
+ WRITE(OUTPUT_UNIT,*) key, ':', dval
+ END IF
+ END DO
- CALL lmp%close(.TRUE.)
- END PROGRAM testprop
+ dt = lmp%extract_global('dt')
+ ntimestep = lmp%extract_global('ntimestep')
+ WRITE(OUTPUT_UNIT,'(A,I0,A,F4.1,A)') 'At step: ', ntimestep, &
+ ' Changing timestep from', dt, ' to 0.5'
+ dt = 0.5_c_double
+ CALL lmp%command('run 2 post no')
+
+ WRITE(OUTPUT_UNIT,'(A,I0)') 'At step: ', ntimestep
+ pe = lmp%get_thermo('pe')
+ ke = lmp%get_thermo('ke')
+ WRITE(OUTPUT_UNIT,*) 'PE = ', pe
+ WRITE(OUTPUT_UNIT,*) 'KE = ', ke
+
+ CALL lmp%close(.TRUE.)
+ END PROGRAM testprop
---------------
@@ -262,6 +273,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
:ftype style: type(lammps_style)
:f type: derived type to access lammps type constants
:ftype type: type(lammps_type)
+ :f dtype: derived type to access lammps data type constants
+ :ftype dtype: type(lammps_dtype)
:f close: :f:subr:`close`
:ftype close: subroutine
:f subroutine error: :f:subr:`error`
@@ -278,6 +291,8 @@ of the contents of the :f:mod:`LIBLAMMPS` Fortran interface to LAMMPS.
:ftype get_natoms: function
:f get_thermo: :f:func:`get_thermo`
:ftype get_thermo: function
+ :f last_thermo: :f:func:`last_thermo`
+ :ftype last_thermo: function
:f extract_box: :f:subr:`extract_box`
:ftype extract_box: subroutine
:f reset_box: :f:subr:`reset_box`
@@ -587,6 +602,96 @@ Procedures Bound to the :f:type:`lammps` Derived Type
--------
+.. f:function:: last_thermo(what, index)
+
+ This function will call :cpp:func:`lammps_last_thermo` and returns
+ either a string or a pointer to a cached copy of LAMMPS last thermodynamic
+ output, depending on the data requested through *what*. Note that *index*
+ uses 1-based indexing to access thermo output columns.
+
+ .. versionadded:: 15Jun2023
+
+ Note that this function actually does not return a value, but rather
+ associates the pointer on the left side of the assignment to point to
+ internal LAMMPS data (with the exception of string data, which are
+ copied and returned as ordinary Fortran strings). Pointers must be
+ of the correct data type to point to said data (typically
+ ``INTEGER(c_int)``, ``INTEGER(c_int64_t)``, or ``REAL(c_double)``).
+ The pointer being associated with LAMMPS data is type-checked at
+ run-time via an overloaded assignment operator. The pointers
+ returned by this function point to temporary, read-only data that may
+ be overwritten at any time, so their target values need to be copied
+ to local storage if they are supposed to persist.
+
+ For example,
+
+ .. code-block:: fortran
+
+ PROGRAM thermo
+ USE LIBLAMMPS
+ USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_double, c_int64_t, c_int
+ TYPE(lammps) :: lmp
+ INTEGER(KIND=c_int64_t), POINTER :: ntimestep, bval
+ REAL(KIND=c_double), POINTER :: dval
+ INTEGER(KIND=c_int), POINTER :: nfield, typ, ival
+ INTEGER(KIND=c_int) :: i
+ CHARACTER(LEN=11) :: key
+
+ lmp = lammps()
+ CALL lmp%file('in.sysinit')
+
+ ntimestep = lmp%last_thermo('step', 0)
+ nfield = lmp%last_thermo('num', 0)
+ PRINT*, 'Last thermo output on step: ', ntimestep, ' Number of fields: ', nfield
+ DO i=1, nfield
+ key = lmp%last_thermo('keyword',i)
+ typ = lmp%last_thermo('type',i)
+ IF (typ == lmp%dtype%i32) THEN
+ ival = lmp%last_thermo('data',i)
+ PRINT*, key, ':', ival
+ ELSE IF (typ == lmp%dtype%i64) THEN
+ bval = lmp%last_thermo('data',i)
+ PRINT*, key, ':', bval
+ ELSE IF (typ == lmp%dtype%r64) THEN
+ dval = lmp%last_thermo('data',i)
+ PRINT*, key, ':', dval
+ END IF
+ END DO
+ CALL lmp%close(.TRUE.)
+ END PROGRAM thermo
+
+ would extract the last timestep where thermo output was done and the number
+ of columns it printed. Then it loops over the columns to print out column
+ header keywords and the corresponding data.
+
+ .. note::
+
+ If :f:func:`last_thermo` returns a string, the string must have a length
+ greater than or equal to the length of the string (not including the
+ terminal ``NULL`` character) that LAMMPS returns. If the variable's
+ length is too short, the string will be truncated. As usual in Fortran,
+ strings are padded with spaces at the end. If you use an allocatable
+ string, the string **must be allocated** prior to calling this function.
+
+ :p character(len=\*) what: string with the name of the thermo keyword
+ :p integer(c_int) index: 1-based column index
+ :to: :cpp:func:`lammps_last_thermo`
+ :r pointer [polymorphic]: pointer to LAMMPS data. The left-hand side of the
+ assignment should be either a string (if expecting string data) or a
+ C-compatible pointer (e.g., ``INTEGER(c_int), POINTER :: nlocal``) to the
+ extracted property.
+
+ .. warning::
+
+ Modifying the data in the location pointed to by the returned pointer
+ may lead to inconsistent internal data and thus may cause failures,
+ crashes, or bogus simulations. In general, it is much better
+ to use a LAMMPS input command that sets or changes these parameters.
+ Using an input command will take care of all side effects and necessary
+ updates of settings derived from such settings.
+
+--------
+
.. f:subroutine:: extract_box([boxlo][, boxhi][, xy][, yz][, xz][, pflags][, boxflag])
This subroutine will call :cpp:func:`lammps_extract_box`. All
@@ -764,13 +869,14 @@ Procedures Bound to the :f:type:`lammps` Derived Type
.. note::
- If :f:func:`extract_global` returns a string, the string must have length
- greater than or equal to the length of the string (not including the
- terminal ``NULL`` character) that LAMMPS returns. If the variable's
- length is too short, the string will be truncated. As usual in Fortran,
- strings are padded with spaces at the end. If you use an allocatable
- string, the string **must be allocated** prior to calling this function,
- but you can automatically reallocate it to the correct length after the
+ If :f:func:`extract_global` returns a string, the string must have
+ a length greater than or equal to the length of the string (not
+ including the terminal ``NULL`` character) that LAMMPS returns. If
+ the variable's length is too short, the string will be
+ truncated. As usual in Fortran, strings are padded with spaces at
+ the end. If you use an allocatable string, the string **must be
+ allocated** prior to calling this function, but you can
+ automatically reallocate it to the correct length after the
function returns, viz.,
.. code-block :: fortran
diff --git a/doc/src/Howto_broken_bonds.rst b/doc/src/Howto_broken_bonds.rst
index 88c8acb87f..2eb9f4bdf4 100644
--- a/doc/src/Howto_broken_bonds.rst
+++ b/doc/src/Howto_broken_bonds.rst
@@ -1,48 +1,56 @@
Broken Bonds
============
-Typically, bond interactions persist for the duration of a simulation in
-LAMMPS. However, there are some exceptions that allow for bonds to
-break, including the :doc:`quartic bond style ` and the
-bond styles in the :doc:`BPM package ` which contains the
-:doc:`bpm/spring ` and :doc:`bpm/rotational
-` bond styles. In these cases, a bond can be broken
-if it is stretched beyond a user-defined threshold. LAMMPS accomplishes
-this by setting the bond type to 0, such that the bond force is no
-longer computed.
+Typically, molecular bond interactions persist for the duration of a
+simulation in LAMMPS. However, some commands break bonds dynamically,
+including the following:
-Users are normally able to weight the contribution of pair forces to atoms
-that are bonded using the :doc:`special_bonds command `.
-When bonds break, this is not always the case. For the quartic bond style,
-pair forces are always turned off between bonded particles. LAMMPS does
-this via a computational sleight-of-hand. It subtracts the pairwise
-interaction as part of the bond computation. When the bond breaks, the
-subtraction stops. For this to work, the pairwise interaction must always
-be computed by the :doc:`pair_style ` command, whether the bond
-is broken or not. This means that :doc:`special_bonds ` must
-be set to 1,1,1. After the bond breaks, the pairwise interaction between the
-two atoms is turned on, since they are no longer bonded.
+* :doc:`bond_style quartic `
+* :doc:`fix bond/break `
+* :doc:`fix bond/react `
+* :doc:`BPM package ` bond styles
-In the BPM package, one can either turn off all pair interactions between
-bonded particles or leave them on, overlaying pair forces on top of bond
-forces. To remove pair forces, the special bond list is dynamically
-updated. More details can be found on the :doc:`Howto BPM `
-page.
+A bond can break if it is stretched beyond a user-defined threshold or
+more generally if other criteria are met.
-Bonds can also be broken by fixes which change bond topology, including
-:doc:`fix bond/break ` and
-:doc:`fix bond/react `. These fixes will automatically
-trigger a rebuild of the neighbor list and update special bond data structures
-when bonds are broken.
+For the quartic bond style, when a bond is broken its bond type is set
+to 0 to effectively break it and pairwise forces between the two atoms
+in the broken bond are "turned on". Angles, dihedrals, etc cannot be
+defined for a system when :doc:`bond_style quartic ` is
+used.
-Note that when bonds are dumped to a file via the :doc:`dump local ` command, bonds with type 0 are not included. The
-:doc:`delete_bonds ` command can also be used to query the
-status of broken bonds or permanently delete them, e.g.:
+Similarly, bond styles in the BPM package are also incompatible with
+angles, dihedrals, etc. and when a bond breaks its type is set to zero.
+However, in the BPM package one can either turn off all pair interactions
+between bonded particles or leave them on, overlaying pair forces on
+top of bond forces. To remove pair forces, the special bond list is
+dynamically updated. More details can be found on the :doc:`Howto BPM
+` page.
+
+The :doc:`fix bond/break ` and :doc:`fix bond/react
+` commands allow breaking of bonds within a molecular
+topology with may also define angles, dihedrals, etc. These commands
+update internal topology data structures to remove broken bonds, as
+well as the appropriate angle, dihedral, etc interactions which
+include the bond. They also trigger a rebuild of the neighbor list
+when this occurs, to turn on the appropriate pairwise forces.
+
+Note that when bonds are dumped to a file via the :doc:`dump local
+` command, bonds with type 0 are not included.
+
+The :doc:`delete_bonds ` command can be used to query
+the status of broken bonds with type = 0 or permanently delete them,
+e.g.:
.. code-block:: LAMMPS
delete_bonds all stats
delete_bonds all bond 0 remove
-The compute :doc:`nbond/atom ` can also be used
-to tally the current number of bonds per atom, excluding broken bonds.
+The compute :doc:`count/type ` command tallies the
+current number of bonds (or angles, etc) for each bond (angle, etc)
+type. It also tallies broken bonds with type = 0.
+
+The compute :doc:`nbond/atom ` command tallies the
+current number of bonds each atom is part of, excluding broken bonds
+with type = 0.
diff --git a/doc/src/Howto_spc.rst b/doc/src/Howto_spc.rst
index 6414d3b846..6dedfe40c4 100644
--- a/doc/src/Howto_spc.rst
+++ b/doc/src/Howto_spc.rst
@@ -69,15 +69,13 @@ SPC/E with rigid bonds.
timestep 1.0
fix rigid all shake 0.0001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
- run 0 post no
- reset_timestep 0
velocity all create 300.0 5463576
- fix integrate all nvt temp 300.0 300.0 1.0
+ fix integrate all nvt temp 300.0 300.0 100.0
thermo_style custom step temp press etotal density pe ke
thermo 1000
run 20000 upto
- write_data tip4p.data nocoeff
+ write_data spce.data nocoeff
.. _spce_molecule:
.. code-block::
diff --git a/doc/src/Howto_tip3p.rst b/doc/src/Howto_tip3p.rst
index 682c7f2640..5419b9ba1b 100644
--- a/doc/src/Howto_tip3p.rst
+++ b/doc/src/Howto_tip3p.rst
@@ -128,11 +128,11 @@ TIP3P with rigid bonds.
fix rigid all shake 0.001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
- run 0 post no
reset_timestep 0
+ timestep 1.0
velocity all create 300.0 5463576
- fix integrate all nvt temp 300 300 1.0
+ fix integrate all nvt temp 300 300 100.0
thermo_style custom step temp press etotal pe
diff --git a/doc/src/Howto_tip4p.rst b/doc/src/Howto_tip4p.rst
index 7775d43e76..4d9b514e0d 100644
--- a/doc/src/Howto_tip4p.rst
+++ b/doc/src/Howto_tip4p.rst
@@ -180,17 +180,17 @@ file changed):
fix rigid all shake 0.001 10 10000 b 1 a 1
minimize 0.0 0.0 1000 10000
- run 0 post no
reset_timestep 0
+ timestep 1.0
velocity all create 300.0 5463576
- fix integrate all nvt temp 300 300 1.0
+ fix integrate all nvt temp 300 300 100.0
thermo_style custom step temp press etotal pe
thermo 1000
run 20000
- write_data tip3p.data nocoeff
+ write_data tip4p-implicit.data nocoeff
Below is the code for a LAMMPS input file using the explicit method and
a TIP4P molecule file. Because of using :doc:`fix rigid/nvt/small
@@ -203,6 +203,7 @@ rigid/nvt/small can identify rigid bodies by their molecule ID:
units real
atom_style charge
+ atom_modify map array
region box block -5 5 -5 5 -5 5
create_box 3 box
@@ -219,14 +220,14 @@ rigid/nvt/small can identify rigid bodies by their molecule ID:
molecule water tip4p.mol
create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
- timestep 0.1
- fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
+ timestep 0.5
+ fix integrate all rigid/nvt/small molecule temp 300.0 300.0 100.0
velocity all create 300.0 5463576
thermo_style custom step temp press etotal density pe ke
thermo 1000
run 20000
- write_data tip4p.data nocoeff
+ write_data tip4p-explicit.data nocoeff
.. _tip4p_molecule:
.. code-block::
diff --git a/doc/src/Howto_tip5p.rst b/doc/src/Howto_tip5p.rst
index 21cc78a684..10674a04b6 100644
--- a/doc/src/Howto_tip5p.rst
+++ b/doc/src/Howto_tip5p.rst
@@ -91,6 +91,7 @@ ID:
units real
atom_style charge
+ atom_modify map array
region box block -5 5 -5 5 -5 5
create_box 3 box
@@ -107,8 +108,8 @@ ID:
molecule water tip5p.mol
create_atoms 0 random 33 34564 NULL mol water 25367 overlap 1.33
- timestep 0.20
- fix integrate all rigid/nvt/small molecule temp 300.0 300.0 1.0
+ timestep 0.5
+ fix integrate all rigid/nvt/small molecule temp 300.0 300.0 100.0
reset_timestep 0
velocity all create 300.0 5463576
diff --git a/doc/src/Install_conda.rst b/doc/src/Install_conda.rst
index 5140e4e17d..a1a7213609 100644
--- a/doc/src/Install_conda.rst
+++ b/doc/src/Install_conda.rst
@@ -1,13 +1,13 @@
-Download an executable for Linux or Mac via Conda
--------------------------------------------------
+Download an executable for Linux or macOS via Conda
+---------------------------------------------------
Pre-compiled LAMMPS binaries are available for macOS and Linux via the
`Conda `_ package management system.
-First, one must set up the Conda package manager on your system. Follow the
-instructions to install `Miniconda `_, then create a conda
-environment (named `my-lammps-env` or whatever you prefer) for your LAMMPS
-install:
+First, one must set up the Conda package manager on your system. Follow
+the instructions to install `Miniconda `_, then
+create a conda environment (named `my-lammps-env` or whatever you
+prefer) for your LAMMPS install:
.. code-block:: bash
diff --git a/doc/src/Install_mac.rst b/doc/src/Install_mac.rst
index 8228b5a4e5..880ddca7a2 100644
--- a/doc/src/Install_mac.rst
+++ b/doc/src/Install_mac.rst
@@ -1,12 +1,12 @@
-Download an executable for Mac
-------------------------------
+Download an executable for macOS
+--------------------------------
-LAMMPS can be downloaded, built, and configured for OS X on a Mac with
-`Homebrew `_. (Alternatively, see the installation
-instructions for :doc:`downloading an executable via Conda
-`.) The following LAMMPS packages are unavailable at
-this time because of additional requirements not yet met: GPU, KOKKOS,
-MSCG, MPIIO, POEMS, VORONOI.
+LAMMPS can be downloaded, built, and configured for macOS with `Homebrew
+`_. (Alternatively, see the installation instructions for
+:doc:`downloading an executable via Conda `.) The
+following LAMMPS packages are unavailable at this time because of
+additional requirements not yet met: GPU, KOKKOS, MSCG, MPIIO, POEMS,
+VORONOI.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:
@@ -15,8 +15,9 @@ the following commands:
brew install lammps
-This will install the executables "lammps_serial" and "lammps_mpi", as well as
-the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
+This will install the executables "lammps_serial" and "lammps_mpi", as
+well as the LAMMPS "doc", "potentials", "tools", "bench", and "examples"
+directories.
Once LAMMPS is installed, you can test the installation with the
Lennard-Jones benchmark file:
diff --git a/doc/src/Install_tarball.rst b/doc/src/Install_tarball.rst
index 64d73ee356..90dd27fa67 100644
--- a/doc/src/Install_tarball.rst
+++ b/doc/src/Install_tarball.rst
@@ -2,7 +2,7 @@ Download source and documentation as a tarball
----------------------------------------------
You can download a current LAMMPS tarball from the `download page `_
-of the `LAMMPS website `_.
+of the `LAMMPS website `_ or from GitHub (see below).
.. _download: https://www.lammps.org/download.html
.. _bug: https://www.lammps.org/bug.html
@@ -17,21 +17,21 @@ tarball occasionally updated. Feature releases occur every 4 to 8
weeks. The new contents in all feature releases are listed on the `bug
and feature page `_ of the LAMMPS homepage.
-Both tarballs include LAMMPS documentation (HTML and PDF files)
-corresponding to that version.
-
Tarballs of older LAMMPS versions can also be downloaded from `this page
`_.
-Once you have a tarball, unzip and untar it with the following
+Tarballs downloaded from the LAMMPS homepage include the pre-translated
+LAMMPS documentation (HTML and PDF files) corresponding to that version.
+
+Once you have a tarball, uncompress and untar it with the following
command:
.. code-block:: bash
tar -xzvf lammps*.tar.gz
-This will create a LAMMPS directory with the version date
-in its name, e.g. lammps-23Jun18.
+This will create a LAMMPS directory with the version date in its name,
+e.g. lammps-28Mar23.
----------
@@ -45,7 +45,8 @@ with the following command, to create a lammps- directory:
unzip lammps*.zip
This version corresponds to the selected LAMMPS feature or stable
-release.
+release (as indicated by the matching git tag) and will only contain the
+source code and no pre-built documentation.
.. _git: https://github.com/lammps/lammps/releases
diff --git a/doc/src/Library_properties.rst b/doc/src/Library_properties.rst
index 21e5609fc0..005bfaeea5 100644
--- a/doc/src/Library_properties.rst
+++ b/doc/src/Library_properties.rst
@@ -5,6 +5,7 @@ This section documents the following functions:
- :cpp:func:`lammps_get_natoms`
- :cpp:func:`lammps_get_thermo`
+- :cpp:func:`lammps_last_thermo`
- :cpp:func:`lammps_extract_box`
- :cpp:func:`lammps_reset_box`
- :cpp:func:`lammps_memory_usage`
@@ -81,6 +82,11 @@ subdomains and processors.
-----------------------
+.. doxygenfunction:: lammps_last_thermo
+ :project: progguide
+
+-----------------------
+
.. doxygenfunction:: lammps_extract_box
:project: progguide
diff --git a/doc/src/Modify.rst b/doc/src/Modify.rst
index 8ea7850fc5..0d7d4d6b97 100644
--- a/doc/src/Modify.rst
+++ b/doc/src/Modify.rst
@@ -1,23 +1,30 @@
Modifying & extending LAMMPS
****************************
-LAMMPS is designed in a modular fashion and to be easy to modify or
-extend with new functionality. In fact, about 95% of its source code
-are optional. The following pages give basic instructions on what
-is required when adding new styles of different kinds to LAMMPS.
+LAMMPS has a modular design, so that it is easy to modify or extend with
+new functionality. In fact, about 95% of its source code is optional.
+The following pages give basic instructions on adding new features to
+LAMMPS. More in-depth explanations and documentation of individual
+functions and classes are given in :doc:`Developer`.
If you add a new feature to LAMMPS and think it will be of general
interest to other users, we encourage you to submit it for inclusion in
-LAMMPS as a pull request on our `GitHub site
-`_, after reading about :doc:`how to
-prepare your code for submission ` and :doc:`the
-style requirements and recommendations `.
+LAMMPS. This process is explained in the following three pages:
+
+* :doc:`how to prepare and submit your code `
+* :doc:`requirements for submissions `
+* :doc:`style guidelines `
+
+A summary description of various types of styles in LAMMPS follows.
+A discussion of implementing specific styles from scratch is given
+in :doc:`writing new styles `.
.. toctree::
:maxdepth: 1
Modify_overview
Modify_contribute
+ Modify_requirements
Modify_style
.. toctree::
diff --git a/doc/src/Modify_contribute.rst b/doc/src/Modify_contribute.rst
index d3d270fe3b..8992e63c00 100644
--- a/doc/src/Modify_contribute.rst
+++ b/doc/src/Modify_contribute.rst
@@ -2,74 +2,59 @@ Submitting new features for inclusion in LAMMPS
===============================================
We encourage LAMMPS users to submit new features they wrote for LAMMPS
-to be included into the LAMMPS distribution and thus become easily
-accessible to all LAMMPS users. The LAMMPS source code is managed with
-git and public development is hosted on `GitHub
-`_. You can monitor the repository to
-be notified of releases, follow the ongoing development, and comment on
-topics of interest to you.
+to be included in the LAMMPS distribution and thus become easily
+accessible to all LAMMPS users. The LAMMPS source code is managed
+with git and public development is hosted on `GitHub
+`_. You can monitor the repository
+to be notified of releases, follow the ongoing development, and
+comment on topics of interest to you.
+
+This section contains general information regarding the preparation
+and submission of new features to LAMMPS. If you are new to
+development in LAMMPS, we recommend you read one of the tutorials on
+developing a new :doc:`pair style ` or :doc:`fix
+style ` which provide a friendly introduction to
+what LAMMPS development entails and common vocabulary used on this
+section.
+
Communication with the LAMMPS developers
----------------------------------------
-For any larger modifications or programming project, you are encouraged
-to contact the LAMMPS developers ahead of time in order to discuss
-implementation strategies and coding guidelines. That will make it
-easier to integrate your contribution and results in less work for
-everybody involved. You are also encouraged to search through the list
-of `open issues on GitHub `_
-and submit a new issue for a planned feature, so you would not duplicate
-the work of others (and possibly get scooped by them) or have your work
-duplicated by others.
+For any larger modifications or programming project, you are
+encouraged to contact the LAMMPS developers ahead of time to discuss
+implementation strategies. That will make it easier to integrate your
+contribution and typically results in less work for everyone involved.
+You are also encouraged to search through the list of `open issues on
+GitHub `_ and submit a new
+issue for a planned feature, to avoid duplicating work (and possibly
+being scooped).
-For informal communication with the LAMMPS developers you may ask to
-join the `LAMMPS developers on Slack `_. This
-slack work space is by invitation only. Thus for access, please send an
-e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
-working on. Only discussions related to LAMMPS development are
-tolerated in that work space, so this is **NOT** for people that look
+For informal communication with the LAMMPS developers, you may ask to
+join the `LAMMPS developers on Slack `_.
+This slack work space is by invitation only. For access, please send
+an e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you
+are working on. Only discussions related to LAMMPS development are
+tolerated in that work space, so this is **NOT** for people looking
for help with compiling, installing, or using LAMMPS. Please post a
message to the `LAMMPS forum `_ for
those purposes.
-Packages versus individual files
---------------------------------
-
-The remainder of this chapter describes how to add new "style" files of
-various kinds to LAMMPS. Packages are simply collections of one or more
-such new class files which are invoked as a new style within a LAMMPS
-input script. In some cases collections of supporting functions or
-classes are also included as separate files in a package, especially when
-they can be shared between multiple styles. If designed correctly, these
-additions typically do not require any changes to the core code of
-LAMMPS; they are simply add-on files that are compiled with the rest of
-LAMMPS. To make those styles work, you may need some trivial changes to
-the core code; an example of a trivial change is making a parent-class
-method "virtual" when you derive a new child class from it.
-
-If you think your new feature or package requires some non-trivial
-changes in core LAMMPS files, you should communicate with the LAMMPS
-developers `on Slack `_, `on GitHub
-`_, or `via email
-`_, since we may have
-recommendations about what changes to do where, or may not want to
-include certain changes for some reason and thus you would need to look
-for alternatives.
Time and effort required
------------------------
-How quickly your contribution will be integrated can vary a lot. It
-depends largely on how much effort it will cause the LAMMPS developers
-to integrate and test it, how many and what kind of changes to the core
-code are required, how quickly you can address them and of how much
-interest it is to the larger LAMMPS community. Please see the section
-on :doc:`LAMMPS programming style and requirements ` for
-instructions, recommendations, and formal requirements. A small,
-modular, well written contribution may be integrated within hours, but a
-complex change that will require a redesign of some core functionality
-in LAMMPS for a clean integration can take many months until it is
-considered ready for inclusion (though this is rare).
+How quickly your contribution will be integrated can vary widely. It
+depends largely on how much effort is required by the LAMMPS
+developers to integrate and test it, if any and what kind of changes
+to the core code are required, how quickly you can address them, and
+how much interest the contribution is to the larger LAMMPS
+community. This process can be streamlined by following the
+:doc:`requirements ` and :doc:`style
+guidelines`. A small, modular, well written
+contribution may be integrated within hours, but a complex change that
+requires a re-design of a core functionality in LAMMPS can take months
+before inclusion (though this is rare).
Submission procedure
@@ -78,36 +63,24 @@ Submission procedure
All changes to LAMMPS (including those from LAMMPS developers) are
integrated via pull requests on GitHub and cannot be merged without
passing the automated testing and an approving review by a LAMMPS core
-developer. Thus before submitting your contribution, you should first
-make certain, that your added or modified code compiles and works
-correctly with the latest development version of LAMMPS and contains all
-bug fixes from it.
+developer. Before submitting your contribution, you should therefore
+first ensure that your added or modified code compiles and works
+correctly with the latest development version of LAMMPS and contains
+all bug fixes from it.
-Once you have prepared everything, see the :doc:`LAMMPS GitHub Tutorial
-` page for instructions on how to submit your changes or
-new files through a GitHub pull request yourself. If you are unable or
-unwilling to submit via GitHub yourself, you may also submit patch files
-or full files to the LAMMPS developers and ask them to submit a pull
-request on GitHub on your behalf. If this is the case, create a gzipped
-tar file of all new or changed files or a corresponding patch file using
-'diff -u' or 'diff -c' format and compress it with gzip. Please only
-use gzip compression, as this works well and is available on all platforms.
+Once you have prepared everything, see the :doc:`LAMMPS GitHub
+Tutorial ` page for instructions on how to submit your
+changes or new files through a GitHub pull request. If you are unable
+or unwilling to submit via GitHub yourself, you may also send patch
+files or full files to the `LAMMPS developers
+`_ and ask them to submit a pull
+request on GitHub on your behalf. If this is the case, create a
+gzipped tar file of all new or changed files or a corresponding patch
+file using 'diff -u' or 'diff -c' format and compress it with gzip.
+Please only use gzip compression, as this works well and is available
+on all platforms. This mode of submission may delay the integration
+as it depends more on the LAMMPS developers.
-If the new features/files are broadly useful we may add them as core
-files to LAMMPS or as part of a :doc:`package `. All
-packages are listed and described on the :doc:`Packages details
-` doc page.
-
-Licensing
----------
-
-Note that by providing us files to release, you agree to make them
-open-source, i.e. we can release them under the terms of the GPL
-(version 2) with the rest of LAMMPS. And similarly as part of a LGPL
-(version 2.1) distribution of LAMMPS that we make available to
-developers on request only and with files that are not authorized for
-that kind of distribution removed (e.g. interface to FFTW). See the
-:doc:`LAMMPS license ` page for details.
External contributions
----------------------
@@ -115,11 +88,42 @@ External contributions
If you prefer to do so, you can also develop and support your add-on
feature **without** having it included in the LAMMPS distribution, for
example as a download from a website of your own. See the `External
-LAMMPS packages and tools `_ page
-of the LAMMPS website for examples of groups that do this. We are happy
-to advertise your package and website from that page. Simply email the
-`developers `_ with info about your
-package and we will post it there. We recommend to name external
-packages USER-\ so they can be easily distinguished from bundled
-packages that do not have the USER- prefix.
+LAMMPS packages and tools `_
+page of the LAMMPS website for examples of groups that do this. We
+are happy to advertise your package and website from that page.
+Simply email the `developers `_
+with info about your package, and we will post it there. We recommend
+naming external packages USER-\ so they can be easily
+distinguished from packages in the LAMMPS distribution which do not
+have the USER- prefix.
+
+Location of files: individual files and packages
+------------------------------------------------
+
+We rarely accept new styles in the core src folder. Thus, please
+review the list of :doc:`available Packages ` to see
+if your contribution should be added to one of them. It should fit
+into the general purpose of that package. If it does not fit well, it
+may be added to one of the EXTRA- packages or the MISC package.
+
+However, if your project includes many related features that are not
+covered by one of the existing packages or is dependent on a library
+(bundled or external), it is best to create a new package with its own
+directory (with a name like FOO). In addition to your new files, the
+directory should contain a README text file containing your name and
+contact information and a brief description of what your new package
+does.
+
+
+Changes to core LAMMPS files
+--------------------------------
+
+If designed correctly, most additions do not require any changes to
+the core code of LAMMPS; they are simply add-on files that are
+compiled with the rest of LAMMPS. To make those styles work, you may
+need some trivial changes to the core code. An example of a trivial
+change is making a parent-class method "virtual" when you derive a new
+child class from it. If your features involve more substantive
+changes to the core LAMMPS files, it is particularly encouraged that
+you communicate with the LAMMPS developers early in development.
diff --git a/doc/src/Modify_overview.rst b/doc/src/Modify_overview.rst
index ed7ff1a8ac..ab1fa43ed4 100644
--- a/doc/src/Modify_overview.rst
+++ b/doc/src/Modify_overview.rst
@@ -1,42 +1,44 @@
Overview
========
-The best way to add a new feature to LAMMPS is to find a similar feature
-and look at the corresponding source and header files to figure out what
-it does. You will need some knowledge of C++ to be able to understand
-the high-level structure of LAMMPS and its class organization, but
-functions (class methods) that do actual computations are mostly written
-in C-style code and operate on simple C-style data structures (vectors
-and arrays). A high-level overview of the programming style choices in
-LAMMPS is :doc:`given elsewhere `.
+The best way to add a new feature to LAMMPS is to find a similar
+feature and look at the corresponding source and header files to
+figure out what it does. You will need some knowledge of C++ to
+understand the high-level structure of LAMMPS and its class
+organization. Functions (class methods) that do actual computations
+are mostly written in C-style code and operate on simple C-style data
+structures (vectors and arrays). A high-level overview of the
+programming style choices in LAMMPS is :doc:`given elsewhere
+`.
Most of the new features described on the :doc:`Modify ` doc
-page require you to write a new C++ derived class (except for exceptions
-described below, where you can make small edits to existing files).
-Creating a new class requires 2 files, a source code file (\*.cpp) and a
-header file (\*.h). The derived class must provide certain methods to
-work as a new option. Depending on how different your new feature is
-compared to existing features, you can either derive from the base class
-itself, or from a derived class that already exists. Enabling LAMMPS to
-invoke the new class is as simple as putting the two source files in the
-src directory and re-building LAMMPS.
+page require you to write a new C++ derived class (except for
+exceptions described below, where you can make small edits to existing
+files). Creating a new class requires 2 files, a source code file
+(\*.cpp) and a header file (\*.h). The derived class must provide
+certain methods to work as a new option. Depending on how different
+your new feature is compared to existing features, you can either
+derive from the base class itself, or from a derived class that
+already exists. Enabling LAMMPS to invoke the new class is as simple
+as putting the two source files in the src directory and re-building
+LAMMPS.
The advantage of C++ and its object-orientation is that all the code
and variables needed to define the new feature are in the 2 files you
-write, and thus should not make the rest of LAMMPS more complex or
-cause side-effect bugs.
+write. Thus, it should not make the rest of LAMMPS more complex or
+cause bugs through unwanted side effects.
-Here is a concrete example. Suppose you write 2 files pair_foo.cpp
-and pair_foo.h that define a new class PairFoo that computes pairwise
-potentials described in the classic 1997 :ref:`paper ` by Foo, et al.
-If you wish to invoke those potentials in a LAMMPS input script with a
-command like
+Here is a concrete example. Suppose you write 2 files
+``pair_foo.cpp`` and ``pair_foo.h`` that define a new class
+``PairFoo`` which computes pairwise potentials described in the
+classic 1997 :ref:`paper ` by Foo, *et al.* If you wish to invoke
+those potentials in a LAMMPS input script with a command like:
.. code-block:: LAMMPS
pair_style foo 0.1 3.5
-then your pair_foo.h file should be structured as follows:
+then your ``pair_foo.h`` file should be structured as follows:
.. code-block:: c++
@@ -51,28 +53,27 @@ then your pair_foo.h file should be structured as follows:
#endif
where "foo" is the style keyword in the pair_style command, and
-PairFoo is the class name defined in your pair_foo.cpp and pair_foo.h
-files.
+``PairFoo`` is the class name defined in your ``pair_foo.cpp`` and
+``pair_foo.h`` files.
When you re-build LAMMPS, your new pairwise potential becomes part of
the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class.
-As illustrated by this example pair style, many kinds of options are
-referred to in the LAMMPS documentation as the "style" of a particular
-command.
+As illustrated by this example, many features referred to in the
+LAMMPS documentation are called a "style" of a particular command.
The :doc:`Modify page ` lists all the common styles in LAMMPS,
-and discusses the header file for the base class that these styles are
-derived from. Public variables in that file are ones used and set by
-the derived classes which are also used by the base class. Sometimes
-they are also used by the rest of LAMMPS. Pure functions, which means
-functions declared as virtual in the base class header file which are
-also set to 0, are functions you **must** implement in your new derived
-class to give it the functionality LAMMPS expects. Virtual functions
-that are not set to 0 are functions you may override or not. Those
-are usually defined with an empty function body.
+and discusses the header file for the base class that these styles
+derive from. Public variables in that file can be used and set by the
+derived classes, and may also be used by the base class. Sometimes
+they are also accessed by the rest of LAMMPS. Pure functions, which
+means functions declared as virtual in the base class header file and
+which are also set to 0, are functions you **must** implement in your
+new derived class to give it the functionality LAMMPS expects. Virtual
+functions that are not set to 0 are functions you may override or not.
+Those are usually defined with an empty function body.
Additionally, new output options can be added directly to the
thermo.cpp, dump_custom.cpp, and variable.cpp files. These are also
@@ -85,9 +86,9 @@ functionality:
post-processing step. Many computations are more easily and more
quickly done that way.
* Do not try to do anything within the timestepping of a run that is not
- parallel. For example do not accumulate a bunch of data on a single
- processor and analyze it. You run the risk of seriously degrading
- the parallel efficiency this way.
+ parallel. For example, do not accumulate a bunch of data on a single
+ processor and analyze it. That would run the risk of seriously degrading
+ the parallel efficiency.
* If your new feature reads arguments or writes output, make sure you
follow the unit conventions discussed by the :doc:`units `
command.
diff --git a/doc/src/Modify_requirements.rst b/doc/src/Modify_requirements.rst
new file mode 100644
index 0000000000..0637c860ab
--- /dev/null
+++ b/doc/src/Modify_requirements.rst
@@ -0,0 +1,384 @@
+Requirements for contributions to LAMMPS
+========================================
+
+The following is a summary of the current requirements and
+recommendations for including contributed source code or documentation
+into the LAMMPS software distribution.
+
+Motivation
+----------
+
+The LAMMPS developers are committed to provide a software package that
+is versatile, reliable, high-quality, efficient, portable, and easy to
+maintain and modify. Achieving all of these goals is challenging
+since a large part of LAMMPS consists of contributed code from many
+different authors who may not be professionally trained programmers or
+familiar with the idiosyncrasies of maintaining a large software
+package. In addition, changes that interfere with the parallel
+efficiency of the core code must be avoided. As LAMMPS continues to
+grow and more features and functionality are added, it is necessary to
+follow established guidelines when accepting new contributions while
+also working at the same time to improve the existing code.
+
+The following requirements and recommendations are provided as a
+guide. They indicate which individual requirements are strict, and
+which represent a preference and thus are negotiable or optional.
+Please feel free to contact the LAMMPS core developers in case you
+need additional explanations or clarifications, or you need assistance
+in implementing the (strict) requirements for your contributions.
+Requirements include:
+
+* :ref:`Licensing requirements ` (strict)
+* :ref:`Integration testing ` (strict)
+* :ref:`Documentation ` (strict)
+* :ref:`Programming language standards ` (strict)
+* :ref:`Build system ` (strict)
+* :ref:`Command or style names ` (strict)
+* :ref:`Programming style requirements ` (varied)
+* :ref:`Examples ` (preferred)
+* :ref:`Error or warning messages and explanations ` (preferred)
+* :ref:`Citation reminder ` (optional)
+* :ref:`Testing ` (optional)
+
+.. _ReqLicense:
+
+Licensing requirements (strict)
+-------------------------------
+
+Contributing authors agree when submitting a pull request that their
+contributions can be distributed under the LAMMPS license conditions.
+This is the GNU public license in version 2 (not 3 or later) for the
+publicly distributed versions, e.g. on the LAMMPS homepage or on
+GitHub. We also have a version of LAMMPS under LGPL 2.1 terms which
+is available on request; this will usually be the latest available or
+a previous stable version with a few LGPL 2.1 incompatible files
+removed. More details are found on the :doc:`LAMMPS open-source
+license page `.
+
+Your new source files should have the LAMMPS copyright and GPL notice,
+followed by your name and email address at the top, like other
+user-contributed LAMMPS source files.
+
+Contributions may be under a different license as long as that license
+does not conflict with the aforementioned terms. Contributions that
+use code with a conflicting license can be split into two parts:
+
+1. the core parts (i.e. parts that must be in the `src` tree) that are
+ licensed under compatible terms and bundled with the LAMMPS sources
+2. an external library that must be downloaded and compiled (either
+ separately or as part of the LAMMPS compilation)
+
+Please note, that this split licensing mode may complicate including
+the contribution in binary packages.
+
+.. _ReqIntegrationTesting:
+
+Integration testing (strict)
+----------------------------
+
+Where possible we use available continuous integration tools to search
+for common programming mistakes, portability limitations, incompatible
+formatting, and undesired side effects. Contributed code must pass the
+automated tests on GitHub before it can be merged with the LAMMPS
+distribution. These tests compile LAMMPS in a variety of environments
+and settings and run the bundled unit tests. At the discretion of the
+LAMMPS developer managing the pull request, additional tests may be
+activated that test for "side effects" on running a collection of
+input decks and create consistent results. The translation of the
+documentation to HTML and PDF is also tested.
+
+This means that contributed source code **must** compile with the most
+current version of LAMMPS with ``-DLAMMPS_BIGBIG`` in addition to the
+default setting of ``-DLAMMPS_SMALLBIG``. The code needs to work
+correctly in both cases, and also in serial and parallel using MPI.
+
+Some "disruptive" changes may break tests and require updates to the
+testing tools or scripts or tests themselves. This is rare. If in
+doubt, contact the LAMMPS developer that is assigned to the pull
+request.
+
+.. _ReqDocumentation:
+
+Documentation (strict)
+----------------------
+
+Contributions that add new styles or commands or augment existing ones
+must include the corresponding new or modified documentation in
+`ReStructuredText format `_ (.rst files in the ``doc/src/``
+folder). The documentation should be written in American English and the
+.rst file must only use ASCII characters, so it can be cleanly
+translated to PDF files (via `sphinx `_ and
+PDFLaTeX). Special characters may be included via embedded math
+expression typeset in a LaTeX subset.
+
+.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+
+When adding new commands, they need to be integrated into the sphinx
+documentation system, and the corresponding command tables and lists
+updated. When translating the documentation into html files there
+should be no warnings. When adding a new package, some lists
+describing packages must also be updated as well as a package specific
+description added. Likewise, if necessary, some package specific
+build instructions should be included.
+
+As appropriate, the text files with the documentation can include
+inline mathematical expressions or figures (see ``doc/JPG`` for
+examples). Additional PDF files with further details may also be
+included; see ``doc/PDF`` for examples. The page should also include
+literature citations as appropriate; see the bottom of
+``doc/fix_nh.rst`` for examples and the earlier part of the same file
+for how to format the cite itself. Citation labels must be unique
+across **all** .rst files. The "Restrictions" section of the page
+should indicate if your command is only available if LAMMPS is built
+with the appropriate package. See other command doc files for
+examples of how to do this.
+
+Please run at least "make html" and "make spelling" from within the
+doc/src directory, and carefully inspect and proofread the resulting
+HTML format doc page before submitting your code. Upon submission of
+a pull request, checks for error free completion of the HTML and PDF
+build will be performed and also a spell check, a check for correct
+anchors and labels, and a check for completeness of references to all
+styles in their corresponding tables and lists is run. In case the
+spell check reports false positives, they can be added to the file
+``doc/utils/sphinx-config/false_positives.txt``
+
+Contributions that add or modify the library interface or "public"
+APIs from the C++ code or the Fortran module must include suitable
+doxygen comments in the source and corresponding changes to the
+documentation sources for the "Programmer Guide" guide section of the
+LAMMPS manual.
+
+If your feature requires some more complex steps and explanations to
+be used correctly or some external or bundled tools or scripts, we
+recommend that you also contribute a :doc:`Howto document `
+providing some more background information and some tutorial material.
+This can also be used to provide more in-depth explanations of models
+that require use of multiple commands.
+
+As a rule-of-thumb, the more clear and self-explanatory you make your
+documentation, README files and examples, and the easier you make it
+for people to get started, the more likely it is that users will try
+out your new feature.
+
+.. _ReqProgrammingStandards:
+
+Programming language standards (strict)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The core of LAMMPS is written in C++11 in a style that can be mostly
+described as "C with classes". Advanced C++ features like operator
+overloading or excessive use of templates are avoided with the intent to
+keep the code readable to programmers that have limited C++ programming
+experience. C++ constructs are acceptable when they help improve the
+readability and reliability of the code, e.g. when using the
+`std::string` class instead of manipulating pointers and calling the
+string functions of the C library. In addition, a collection of
+convenient :doc:`utility functions and classes ` for
+recurring tasks and a collection of :doc:`platform neutral functions
+` for improved portability are provided.
+Contributions with code requiring more recent C++ standards are only
+accepted as packages with the post C++11 standard code confined to the
+package so that it is optional.
+
+Included Fortran code has to be compatible with the Fortran 2003
+standard. Since not all platforms supported by LAMMPS provide good
+support for compiling Fortran files, it should be considered to rewrite
+these parts as C++ code, if possible and thus allow for a wider adoption
+of the contribution. As of January 2023, all previously included
+Fortran code for the LAMMPS executable has been replaced by equivalent
+C++ code.
+
+Python code must be compatible with Python 3.5 and later. Large parts
+of LAMMPS (including the :ref:`PYTHON package `) are also
+compatible with Python 2.7. Compatibility with Python 2.7 is desirable,
+but compatibility with Python 3.5 is **required**.
+
+Compatibility with older programming language standards is very
+important to maintain portability and availability of LAMMPS on many
+platforms. This applies especially to HPC cluster environments, which
+tend to be running older software stacks and where LAMMPS users may be
+required to use those older tools for access to advanced hardware
+features or not have the option to install newer compilers or libraries.
+
+.. _ReqBuildSystem:
+
+Build system (strict)
+---------------------
+
+LAMMPS currently supports two build systems: one that is based on
+:doc:`traditional Makefiles ` and one that is based on
+:doc:`CMake `. Therefore, your contribution must be
+compatible with and support both build systems.
+
+For a single pair of header and implementation files that are an
+independent feature, it is usually only required to add them to
+``src/.gitignore``.
+
+For traditional make, if your contributed files or package depend on
+other LAMMPS style files or packages also being installed
+(e.g. because your file is a derived class from the other LAMMPS
+class), then an ``Install.sh`` file is also needed to check for those
+dependencies and modifications to ``src/Depend.sh`` to trigger the checks.
+See other README and Install.sh files in other directories as
+examples.
+
+Similarly, for CMake support, changes may need to be made to
+``cmake/CMakeLists.txt``, some of the files in ``cmake/presets``, and
+possibly a file with specific instructions needs to be added to
+``cmake/Modules/Packages/``. Please check out how this is handled for
+existing packages and ask the LAMMPS developers if you need assistance.
+
+.. _ReqNaming:
+
+Command or style names, file names, and keywords (strict)
+---------------------------------------------------------
+
+All user-visible command or style names should be all lower case and
+should only use letters, numbers, or forward slashes. They should be
+descriptive and initialisms should be avoided unless they are well
+established (e.g. lj for Lennard-Jones). For a compute style
+"some/name" the source files must be called ``compute_some_name.h`` and
+``compute_some_name.cpp``. The "include guard" in the header file would
+then be ``LMP_COMPUTE_SOME_NAME_H`` and the class name
+``ComputeSomeName``.
+
+.. _ReqProgrammingStyle:
+
+Programming style requirements (varied)
+---------------------------------------
+
+To maintain source code consistency across contributions from many
+people, there are various programming style requirements for
+contributions to LAMMPS. Some of these requirements are strict and
+must be followed, while others are only preferred and thus may be
+skipped. An in-depth discussion of the style guidelines is provided
+in the :doc:`programming style doc page `.
+
+.. _ReqExamples:
+
+Examples (preferred)
+--------------------
+
+For many new features, it is preferred that example scripts (simple,
+small, fast to complete on 1 CPU) are included that demonstrate the
+use of new or extended functionality. These are typically include
+under the examples or examples/PACKAGES directory and are further
+described on the :doc:`examples page `. Guidelines for
+input scripts include:
+
+- commands that generate output should be commented out (except when the
+ output is the sole purpose or the feature, e.g. for a new compute)
+
+- commands like :doc:`log `, :doc:`echo `, :doc:`package
+ `, :doc:`processors `, :doc:`suffix ` may
+ **not** be used in the input file (exception: "processors * * 1" or
+ similar is acceptable when used to avoid unwanted domain decomposition
+ of empty volumes)
+
+- outside of the log files, no generated output should be included
+
+- custom thermo_style settings may not include output measuring CPU or other
+ time as it complicates comparisons between different runs
+
+- input files should be named ``in.name``, data files should be named
+ ``data.name`` and log files should be named ``log.version.name..``
+
+- the total file size of all the inputs and outputs should be small
+
+- where possible, potential files from the "potentials" folder or data
+ file from other folders should be re-used through symbolic links
+
+.. _ReqErrorMessages:
+
+Error or warning messages and explanations (preferred)
+------------------------------------------------------
+
+.. versionchanged:: 4May2022
+
+Starting with LAMMPS version 4 May 2022, the LAMMPS developers have
+agreed on a new policy for error and warning messages.
+
+Previously, all error and warning strings were supposed to be listed in
+the class header files with an explanation. Those would then be
+regularly "harvested" and transferred to alphabetically sorted lists in
+the manual. To avoid excessively long lists and to reduce effort, this
+came with a requirement to have rather generic error messages (e.g.
+"Illegal ... command"). To identify the specific cause, the name of the
+source file and the line number of the error location would be printed,
+so that one could look up the cause by reading the source code.
+
+The new policy encourages more specific error messages that ideally
+indicate the cause directly, and requiring no further lookup. This is
+aided by the `{fmt} library `_ enabling Error class
+methods that take a variable number of arguments and an error text that
+will be treated like a {fmt} syntax format string. Error messages should
+still preferably be kept to a single line or two lines at most.
+
+For more complex explanations or errors that have multiple possible
+reasons, a paragraph should be added to the `Error_details` page with an
+error code reference (e.g. ``.. _err0001:``) then the utility function
+:cpp:func:`utils::errorurl() ` can be used
+to generate a URL that will directly lead to that paragraph. An error
+for missing arguments can be easily generated using the
+:cpp:func:`utils::missing_cmd_args()
+` convenience function.
+An example for this approach would be the
+``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
+:doc:`read_data ` and :doc:`atom_modify `
+commands and that may create :ref:`"Unknown identifier in data file" `
+errors that may have multiple possible reasons which complicates debugging,
+and thus require some additional explanation.
+
+The transformation of existing LAMMPS code to this new scheme is
+ongoing. Given the size of the LAMMPS code base, it will take a
+significant amount of time to complete. For new code, however,
+following the new approach is strongly preferred. The expectation is
+that the new scheme will make understanding errors easier for LAMMPS
+users, developers, and maintainers.
+
+.. _ReqCitation:
+
+Citation reminder (optional)
+-----------------------------
+
+If there is a paper of yours describing your feature (either the
+algorithm/science behind the feature itself, or its initial usage, or
+its implementation in LAMMPS), you can add the citation to the \*.cpp
+source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example.
+A BibTeX format citation is stored in a string variable at the top of
+the file, and a single line of code registering this variable is added
+to the constructor of the class. When your feature is used, then
+LAMMPS (by default) will print the brief info and the DOI in the first
+line to the screen and the full citation to the log file.
+
+If there is additional functionality (which may have been added later)
+described in a different publication, additional citation descriptions
+may be added so long as they are only registered when the
+corresponding keyword activating this functionality is used.
+
+With these options, it is possible to have LAMMPS output a specific
+citation reminder whenever a user invokes your feature from their
+input script. Please note that you should *only* use this for the
+*most* relevant paper for a feature and a publication that you or your
+group authored. E.g. adding a citation in the source code for a paper
+by Nose and Hoover if you write a fix that implements their integrator
+is not the intended usage. That kind of citation should just be
+included in the documentation page you provide describing your
+contribution. If you are not sure what the best option would be,
+please contact the LAMMPS developers for advice.
+
+.. _ReqUnitTesting:
+
+Testing (optional)
+------------------
+
+If your contribution contains new utility functions or a supporting
+class (i.e. anything that does not depend on a LAMMPS object), new
+unit tests should be added to a suitable folder in the ``unittest``
+tree. When adding a new LAMMPS style computing forces or selected
+fixes, a ``.yaml`` file with a test configuration and reference data
+should be added for the styles where a suitable tester program already
+exists (e.g. pair styles, bond styles, etc.). Please see :ref:`this
+section in the manual ` for more information on how to
+enable, run, and expand testing.
diff --git a/doc/src/Modify_style.rst b/doc/src/Modify_style.rst
index 2feffe56c2..c5aef71597 100644
--- a/doc/src/Modify_style.rst
+++ b/doc/src/Modify_style.rst
@@ -1,351 +1,58 @@
-LAMMPS programming style and requirements for contributions
-===========================================================
-
-The following is a summary of the current requirements and
-recommendations for including contributed source code or documentation
-into the LAMMPS software distribution.
-
-Motivation
-----------
-
-The LAMMPS developers are committed to providing a software package that
-is versatile, reliable, high-quality, efficient, portable, and easy to
-maintain and modify. Achieving all of these goals is challenging since
-a large part of LAMMPS consists of contributed code from many different
-authors and not many of them are professionally trained programmers and
-familiar with the idiosyncrasies of maintaining a large software
-package. In addition, changes that interfere with the parallel
-efficiency of the core code must be avoided. As LAMMPS continues to
-grow and more features and functionality are added, it becomes a
-necessity to be more discriminating with new contributions while also
-working at the same time to improve the existing code.
-
-The following requirements and recommendations are provided to help
-maintaining or improving that status. Where possible we utilize
-available continuous integration tools to search for common programming
-mistakes, portability limitations, incompatible formatting, and
-undesired side effects. It is indicated which requirements are strict,
-and which represent a preference and thus are negotiable or optional.
-
-Please feel free to contact the LAMMPS core developers in case you need
-additional explanations or clarifications or in case you need assistance
-in realizing the (strict) requirements for your contributions.
-
-Licensing requirements (strict)
--------------------------------
-
-Contributing authors agree when submitting a pull request that their
-contributions can be distributed under the LAMMPS license
-conditions. This is the GNU public license in version 2 (not 3 or later)
-for the publicly distributed versions, e.g. on the LAMMPS homepage or on
-GitHub. On request we also make a version of LAMMPS available under
-LGPL 2.1 terms; this will usually be the latest available or a previous
-stable version with a few LGPL 2.1 incompatible files removed. More details
-are found on the :doc:`LAMMPS open-source license page `.
-
-Your new source files should have the LAMMPS copyright, GPL notice, and
-your name and email address at the top, like other user-contributed
-LAMMPS source files.
-
-Contributions may be under a different license as long as that
-license does not conflict with the aforementioned terms. Contributions
-that use code with a conflicting license can be split into two parts:
-
-1. the core parts (i.e. parts that must be in the `src` tree) that are
- licensed under compatible terms and bundled with the LAMMPS sources
-2. an external library that must be downloaded and compiled (either
- separately or as part of the LAMMPS compilation)
-
-Please note, that this split licensed mode may complicate including the
-contribution in binary packages.
-
-Using pull requests on GitHub (preferred)
------------------------------------------
-
-All contributions to LAMMPS are processed as pull requests on GitHub
-(this also applies to the work of the core LAMMPS developers). A
-:doc:`tutorial for submitting pull requests on GitHub ` is
-provided. If this is still problematic, contributors may contact any of
-the core LAMMPS developers for help or to create a pull request on their
-behalf. This latter way of submission may delay the integration as it
-depends on the amount of time required to prepare the pull request and
-free time available by the LAMMPS developer in question to spend on this
-task.
-
-Integration testing (strict)
-----------------------------
-
-Contributed code, like all pull requests, must pass the automated
-tests on GitHub before it can be merged with the LAMMPS distribution.
-These tests compile LAMMPS in a variety of environments and settings and
-run the bundled unit tests. At the discretion of the LAMMPS developer
-managing the pull request, additional tests may be activated that test
-for "side effects" on running a collection of input decks and create
-consistent results. Also, the translation of the documentation to HTML
-and PDF is tested for.
-
-More specifically, this means that contributed source code **must**
-compile with the most current version of LAMMPS with ``-DLAMMPS_BIGBIG``
-in addition to the default setting of ``-DLAMMPS_SMALLBIG``. The code
-needs to work correctly in both cases and also in serial and parallel
-using MPI.
-
-Some "disruptive" changes may break tests and require updates to the
-testing tools or scripts or tests themselves. This is rare. If in
-doubt, contact the LAMMPS developer that is assigned to the pull request
-for further details and explanations and suggestions of what needs to be
-done.
-
-Documentation (strict)
-----------------------
-
-Contributions that add new styles or commands or augment existing ones
-must include the corresponding new or modified documentation in
-`ReStructuredText format `_ (.rst files in the ``doc/src/``
-folder). The documentation shall be written in American English and the
-.rst file must use only ASCII characters so it can be cleanly translated
-to PDF files (via `sphinx `_ and PDFLaTeX).
-Special characters may be included via embedded math expression typeset
-in a LaTeX subset.
-
-.. _rst: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
-
-When adding new commands, they need to be integrated into the sphinx
-documentation system, and the corresponding command tables and lists
-updated. When translating the documentation into html files there should
-be no warnings. When adding a new package also some lists describing
-packages must be updated as well as a package specific description added
-and, if necessary, some package specific build instructions included.
-
-As appropriate, the text files with the documentation can include inline
-mathematical expression or figures (see ``doc/JPG`` for examples).
-Additional PDF files with further details (see ``doc/PDF`` for examples) may
-also be included. The page should also include literature citations as
-appropriate; see the bottom of ``doc/fix_nh.rst`` for examples and the
-earlier part of the same file for how to format the cite itself.
-Citation labels must be unique across **all** .rst files. The
-"Restrictions" section of the page should indicate if your command is
-only available if LAMMPS is built with the appropriate FOO package. See
-other package doc files for examples of how to do this.
-
-Please run at least "make html" and "make spelling" and carefully
-inspect and proofread the resulting HTML format doc page before
-submitting your code. Upon submission of a pull request, checks for
-error free completion of the HTML and PDF build will be performed and
-also a spell check, a check for correct anchors and labels, and a check
-for completeness of references all styles in their corresponding tables
-and lists is run. In case the spell check reports false positives they
-can be added to the file ``doc/utils/sphinx-config/false_positives.txt``
-
-Contributions that add or modify the library interface or "public" APIs
-from the C++ code or the Fortran module must include suitable doxygen
-comments in the source and corresponding changes to the documentation
-sources for the "Programmer Guide" guide section of the LAMMPS manual.
-
-Examples (preferred)
---------------------
-
-In most cases, it is preferred that example scripts (simple, small, fast
-to complete on 1 CPU) are included that demonstrate the use of new or
-extended functionality. These are typically under the examples or
-examples/PACKAGES directory. A few guidelines for such example input
-decks.
-
-- commands that generate output should be commented out (except when the
- output is the sole purpose or the feature, e.g. for a new compute).
-
-- commands like :doc:`log `, :doc:`echo `, :doc:`package
- `, :doc:`processors `, :doc:`suffix ` may
- **not** be used in the input file (exception: "processors * * 1" or
- similar is acceptable when used to avoid unwanted domain decomposition
- of empty volumes).
-
-- outside of the log files, no generated output should be included
-
-- custom thermo_style settings may not include output measuring CPU or other time
- as that makes comparing the thermo output between different runs more complicated.
-
-- input files should be named ``in.name``, data files should be named
- ``data.name`` and log files should be named ``log.version.name..``
-
-- the total file size of all the inputs and outputs should be small
-
-- where possible, potential files from the "potentials" folder or data
- file from other folders should be re-used through symbolic links
-
-Howto document (optional)
--------------------------
-
-If your feature requires some more complex steps and explanations to be
-used correctly or some external or bundled tools or scripts, we
-recommend that you also contribute a :doc:`Howto document `
-providing some more background information and some tutorial material.
-This can also be used to provide more in-depth explanations for bundled
-examples.
-
-As a general rule-of-thumb, the more clear and self-explanatory you make
-your documentation, README files and examples, and the easier you make
-it for people to get started, the more likely it is that users will try
-out your new feature.
-
-Programming style requirements (varied)
----------------------------------------
-
-The LAMMPS developers aim to employ a consistent programming style and
-naming conventions across the entire code base, as this helps with
-maintenance, debugging, and understanding the code, both for developers
-and users.
-
-The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and `utils.cpp`
-may serve as representative examples.
-
-Command or Style names, file names, and keywords (mostly strict)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-All user-visible command or style names should be all lower case and
-should only use letters, numbers, or forward slashes. They should be
-descriptive and initialisms should be avoided unless they are well
-established (e.g. lj for Lennard-Jones). For a compute style
-"some/name" the source files must be called `compute_some_name.h` and
-`compute_some_name.cpp`. The "include guard" would then be
-`LMP_COMPUTE_SOME_NAME_H` and the class name `ComputeSomeName`.
-
-Whitespace and permissions (preferred)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Source files should not contain TAB characters unless required by the
-syntax (e.g. in makefiles) and no trailing whitespace. Text files
-should be added with Unix-style line endings (LF-only). Git will
-automatically convert those in both directions when running on Windows;
-use dos2unix on Linux machines to convert files. Text files should have
-a line ending on the last line.
-
-All files should have 0644 permissions, i.e writable to the user only
-and readable by all and no executable permissions. Executable
-permissions (0755) should only be on shell scripts or python or similar
-scripts for interpreted script languages.
-
-You can check for these issues with the python scripts in the
-:ref:`"tools/coding_standard" ` folder. When run
-normally with a source file or a source folder as argument, they will
-list all non-conforming lines. By adding the `-f` flag to the command
-line, they will modify the flagged files to try removing the detected
-issues.
-
-Indentation and placement of braces (strongly preferred)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-LAMMPS uses 2 characters per indentation level and lines should be
-kept within 100 characters wide.
-
-For new files added to the "src" tree, a `clang-format
-`_ configuration file is
-provided under the name `.clang-format`. This file is compatible with
-clang-format version 8 and later. With that file present, files can be
-reformatted according to the configuration with a command like:
-`clang-format -i new-file.cpp`. Ideally, this is done while writing the
-code or before a pull request is submitted. Blocks of code where the
-reformatting from clang-format yields undesirable output may be
-protected with placing a pair `// clang-format off` and `// clang-format
-on` comments around that block.
-
-Error or warning messages and explanations (preferred)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. versionchanged:: 4May2022
-
-Starting with LAMMPS version 4 May 2022 the LAMMPS developers have
-agreed on a new policy for error and warning messages.
-
-Previously, all error and warning strings were supposed to be listed in
-the class header files with an explanation. Those would then be
-regularly "harvested" and transferred to alphabetically sorted lists in
-the manual. To avoid excessively long lists and to reduce effort, this
-came with a requirement to have rather generic error messages (e.g.
-"Illegal ... command"). To identify the specific cause, the name of the
-source file and the line number of the error location would be printed,
-so that one could look up the cause by reading the source code.
-
-The new policy encourages more specific error messages that ideally
-indicate the cause directly and no further lookup would be needed.
-This is aided by using the `{fmt} library `_ to convert
-the Error class commands so that they take a variable number of arguments
-and error text will be treated like a {fmt} syntax format string.
-Error messages should still kept to a single line or two lines at the most.
-
-For more complex explanations or errors that have multiple possible
-reasons, a paragraph should be added to the `Error_details` page with an
-error code reference (e.g. ``.. _err0001:``) then the utility function
-:cpp:func:`utils::errorurl() ` can be used
-to generate an URL that will directly lead to that paragraph. An error
-for missing arguments can be easily generated using the
-:cpp:func:`utils::missing_cmd_args()
-` convenience function.
-
-The transformation of existing LAMMPS code to this new scheme is ongoing
-and - given the size of the LAMMPS source code - will take a significant
-amount of time until completion. However, for new code following the
-new approach is strongly preferred. The expectation is that the new
-scheme will make it easier for LAMMPS users, developers, and
-maintainers.
-
-An example for this approach would be the
-``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
-:doc:`read_data ` and :doc:`atom_modify `
-commands and that may create :ref:`"Unknown identifier in data file" `
-errors that seem difficult to debug for users because they may have
-one of multiple possible reasons, and thus require some additional explanations.
-
-Programming language standards (required)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The core of LAMMPS is written in C++11 in a style that can be mostly
-described as "C with classes". Advanced C++ features like operator
-overloading or excessive use of templates are avoided with the intent to
-keep the code readable to programmers that have limited C++ programming
-experience. C++ constructs are acceptable when they help improve the
-readability and reliability of the code, e.g. when using the
-`std::string` class instead of manipulating pointers and calling the
-string functions of the C library. In addition a collection of
-convenient :doc:`utility functions and classes ` for
-recurring tasks and a collection of
-:doc:`platform neutral functions ` for improved
-portability are provided.
-
-Included Fortran code has to be compatible with the Fortran 2003
-standard. Python code must be compatible with Python 3.5. Large parts
-of LAMMPS (including the :ref:`PYTHON package `) are also
-compatible with Python 2.7. Compatibility with Python 2.7 is
-desirable, but compatibility with Python 3.5 is **required**.
-
-Compatibility with these older programming language standards is very
-important to maintain portability and availability of LAMMPS on many
-platforms. This applies especially to HPC cluster environments, which
-tend to be running older software stacks and LAMMPS users may be
-required to use those older tools for access to advanced hardware
-features or not have the option to install newer compilers or libraries.
-
-Programming conventions (varied)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following is a collection of conventions that should be applied when
-writing code for LAMMPS. Following these steps will make it much easier
-to integrate your contribution. Please have a look at the existing files
-in packages in the src directory for examples. As a demonstration for
-how can be adapted to these conventions you may compare the REAXFF
-package with the what it looked like when it was called USER-REAXC. If
-you are uncertain, please ask.
-
-- system headers or from installed libraries are include with angular
- brackets (example: ``#include ``), while local include file
- use double quotes (example: ``#include "atom.h"``).
-
-- when including system header files from the C library use the
- C++-style names (```` or ````) instead of the
- C-style names (```` or ````)
-
-- the order of ``#include`` statements in a file ``some_name.cpp`` that
- implements a class ``SomeName`` defined in a header file
+LAMMPS programming style
+========================
+
+The aim of the LAMMPS developers is to use a consistent programming
+style and naming conventions across the entire code base, as this
+helps with maintenance, debugging, and understanding the code, both
+for developers and users. This page provides a list of standard style
+choices used in LAMMPS. Some of these standards are required, while
+others are just preferred. Following these conventions will make it
+much easier to integrate your contribution. If you are uncertain,
+please ask.
+
+The files `pair_lj_cut.h`, `pair_lj_cut.cpp`, `utils.h`, and
+`utils.cpp` may serve as representative examples.
+
+Include files (varied)
+^^^^^^^^^^^^^^^^^^^^^^
+
+- Header files that define a new LAMMPS style (i.e. that have a
+ ``SomeStyle(some/name,SomeName);`` macro in them) should only use
+ the include file for the base class and otherwise use forward
+ declarations and pointers; when interfacing to a library use the
+ PIMPL (pointer to implementation) approach where you have a pointer
+ to a struct that contains all library specific data (and thus
+ requires the library header) but use a forward declaration and
+ define the struct only in the implementation file. This is a
+ **strict** requirement since this is where type clashes between
+ packages and hard-to-find bugs have regularly manifested in the
+ past.
+
+- Header files, especially those defining a "style", should only use
+ the absolute minimum number of include files and **must not**
+ contain any ``using`` statements. Typically, that would only be the
+ header for the base class. Instead, any include statements should
+ be put in the corresponding implementation files and forward
+ declarations be used. For implementation files, the "include what
+ you use" principle should be employed. However, there is the
+ notable exception that when the ``pointers.h`` header is included
+ (or one of the base classes derived from it) certain headers will
+ always be included and thus do not need to be explicitly specified.
+ These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`,
+ `utils.h`, `vector`, `fmt/format.h`, `climits`, `cinttypes`. This
+ also means any such file can assume that `FILE`, `NULL`, and
+ `INT_MAX` are defined.
+
+- System headers or headers from installed libraries are included with
+ angular brackets (example: ``#include ``), while local
+ include files use double quotes (example: ``#include "atom.h"``)
+
+- When including system header files from the C library use the
+ C++-style names (```` or ````) instead of the
+ C-style names (```` or ````)
+
+- The order of ``#include`` statements in a file ``some_name.cpp``
+ that implements a class ``SomeName`` defined in a header file
``some_name.h`` should be as follows:
- ``#include "some_name.h"`` followed by an empty line
@@ -353,34 +60,70 @@ you are uncertain, please ask.
- LAMMPS include files e.g. ``#include "comm.h"`` or ``#include
"modify.h"`` in alphabetical order followed by an empty line
- - system header files from the C++ or C standard library followed by
+ - System header files from the C++ or C standard library followed by
an empty line
- ``using namespace LAMMPS_NS`` or other namespace imports.
+Whitespace (preferred)
+^^^^^^^^^^^^^^^^^^^^^^
+
+Source files should not contain TAB characters unless required by the
+syntax (e.g. in makefiles) and no trailing whitespace. Text files
+should have Unix-style line endings (LF-only). Git will automatically
+convert those in both directions when running on Windows; use dos2unix
+on Linux machines to convert files to Unix-style line endings. The
+last line of text files include a line ending.
+
+You can check for these issues with the python scripts in the
+:ref:`"tools/coding_standard" ` folder. When run
+normally with a source file or a source folder as argument, they will
+list all non-conforming lines. By adding the `-f` flag to the command
+line, they will modify the flagged files to try to remove the detected
+issues.
+
+Placement of braces (strongly preferred)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For new files added to the "src" tree, a `clang-format
+`_ configuration file is
+provided under the name `.clang-format`. This file is compatible with
+clang-format version 8 and later. With that file present, files can be
+reformatted according to the configuration with a command like:
+`clang-format -i new-file.cpp`. Ideally, this is done while writing
+the code or before a pull request is submitted. Blocks of code where
+the reformatting from clang-format yields hard-to-read or otherwise
+undesirable output may be protected with placing a pair `//
+clang-format off` and `// clang-format on` comments around that block.
+
+Miscellaneous standards (varied)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
- I/O is done via the C-style stdio library and **not** iostreams.
- Do not use so-called "alternative tokens" like ``and``, ``or``,
``not`` and similar, but rather use the corresponding operators
``&&``, ``||``, and ``!``. The alternative tokens are not available
- by default on all compilers, and also we want to maintain a consistent
- programming style.
+ by default on all compilers.
-- Output to the screen and the logfile should be using the corresponding
- FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg`
- convenience function where possible.
+- Output to the screen and the logfile should use the corresponding
+ FILE pointers and only be done on MPI rank 0. Use the
+ :cpp:func:`utils::logmesg` convenience function where possible.
-- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
- `C++ Core Guideline C.128 `_.
+- Usage of C++11 `virtual`, `override`, `final` keywords: Please
+ follow the `C++ Core Guideline C.128
+ `_.
That means, you should only use `virtual` to declare a new virtual
- function, `override` to indicate you are overriding an existing virtual
- function, and `final` to prevent any further overriding.
+ function, `override` to indicate you are overriding an existing
+ virtual function, and `final` to prevent any further overriding.
-- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
+- Trivial destructors: Do not write destructors when they are empty
+ and `default`.
.. code-block:: c++
// don't write destructors for A or B like this
+
class A : protected Pointers {
public:
A();
@@ -394,6 +137,7 @@ you are uncertain, please ask.
};
// instead, let the compiler create the implicit default destructor by not writing it
+
class A : protected Pointers {
public:
A();
@@ -404,37 +148,11 @@ you are uncertain, please ask.
B();
};
-- Header files, especially those defining a "style", should only use
- the absolute minimum number of include files and **must not** contain
- any ``using`` statements. Typically that would be only the header for
- the base class. Instead any include statements should be put into the
- corresponding implementation files and forward declarations be used.
- For implementation files, the "include what you use" principle should
- be employed. However, there is the notable exception that when the
- ``pointers.h`` header is included (or one of the base classes derived
- from it) certain headers will always be included and thus do not need
- to be explicitly specified.
- These are: `mpi.h`, `cstddef`, `cstdio`, `cstdlib`, `string`, `utils.h`,
- `vector`, `fmt/format.h`, `climits`, `cinttypes`.
- This also means any such file can assume that `FILE`, `NULL`, and
- `INT_MAX` are defined.
-
-- Header files that define a new LAMMPS style (i.e. that have a
- ``SomeStyle(some/name,SomeName);`` macro in them) should only use the
- include file for the base class and otherwise use forward declarations
- and pointers; when interfacing to a library use the PIMPL (pointer
- to implementation) approach where you have a pointer to a struct
- that contains all library specific data (and thus requires the library
- header) but use a forward declaration and define the struct only in
- the implementation file. This is a **strict** requirement since this
- is where type clashes between packages and hard to find bugs have
- regularly manifested in the past.
-
- Please use clang-format only to reformat files that you have
contributed. For header files containing a ``SomeStyle(keyword,
- ClassName)`` macros it is required to have this macro embedded with a
- pair of ``// clang-format off``, ``// clang-format on`` comments and
- the line must be terminated with a semi-colon (;). Example:
+ ClassName)`` macros it is required to have this macro embedded with
+ a pair of ``// clang-format off``, ``// clang-format on`` comments
+ and the line must be terminated with a semicolon (;). Example:
.. code-block:: c++
@@ -447,92 +165,10 @@ you are uncertain, please ask.
#ifndef LMP_RUN_H
[...]
- You may also use ``// clang-format on/off`` throughout your files
- to protect individual sections from being reformatted.
+ You may also use ``// clang-format on/off`` throughout your files to
+ protect individual sections from being reformatted.
-- We rarely accept new styles in the core src folder. Thus please
- review the list of :doc:`available Packages ` to see
- if your contribution could be added to be added to one of them. It
- should fit into the general purposed of that package. If it does not
- fit well, it may be added to one of the EXTRA- packages or the MISC
- package.
-
-
-Contributing a package
-----------------------
-
-If your contribution has several related features that are not covered
-by one of the existing packages or is dependent on a library (bundled or
-external), it is best to make it a package directory with a name like
-FOO. In addition to your new files, the directory should contain a
-README text file. The README should contain your name and contact
-information and a brief description of what your new package does.
-
-
-Build system (strongly preferred)
----------------------------------
-
-LAMMPS currently supports two build systems: one that is based on
-:doc:`traditional Makefiles ` and one that is based on
-:doc:`CMake `. Thus your contribution must be compatible
-with and support both.
-
-For a single pair of header and implementation files that are an
-independent feature, it is usually only required to add them to
-`src/.gitignore``.
-
-For traditional make, if your contributed files or package depend on
-other LAMMPS style files or packages also being installed (e.g. because
-your file is a derived class from the other LAMMPS class), then an
-Install.sh file is also needed to check for those dependencies and
-modifications to src/Depend.sh to trigger the checks. See other README
-and Install.sh files in other directories as examples.
-
-Similarly for CMake support, changes may need to be made to
-cmake/CMakeLists.txt, some of the files in cmake/presets, and possibly a
-file with specific instructions needs to be added to
-cmake/Modules/Packages/. Please check out how this is handled for
-existing packages and ask the LAMMPS developers if you need assistance.
-
-
-Citation reminder (suggested)
------------------------------
-
-If there is a paper of yours describing your feature (either the
-algorithm/science behind the feature itself, or its initial usage, or
-its implementation in LAMMPS), you can add the citation to the \*.cpp
-source file. See ``src/DIFFRACTION/compute_saed.cpp`` for an example.
-A BibTeX format citation is stored in a string variable at the top
-of the file and a single line of code registering this variable is
-added to the constructor of the class. When your feature is used,
-by default, LAMMPS will print the brief info and the DOI
-in the first line to the screen and the full citation to the log file.
-
-If there is additional functionality (which may have been added later)
-described in a different publication, additional citation descriptions
-may be added for as long as they are only registered when the
-corresponding keyword activating this functionality is used. With these
-options it is possible to have LAMMPS output a specific citation
-reminder whenever a user invokes your feature from their input script.
-Please note that you should *only* use this for the *most* relevant
-paper for a feature and a publication that you or your group authored.
-E.g. adding a citation in the code for a paper by Nose and Hoover if you
-write a fix that implements their integrator is not the intended usage.
-That latter kind of citation should just be included in the
-documentation page you provide describing your contribution. If you are
-not sure what the best option would be, please contact the LAMMPS
-developers for advice.
-
-
-Testing (optional)
-------------------
-
-If your contribution contains new utility functions or a supporting class
-(i.e. anything that does not depend on a LAMMPS object), new unit tests
-should be added to a suitable folder in the ``unittest`` tree.
-When adding a new LAMMPS style computing forces or selected fixes,
-a ``.yaml`` file with a test configuration and reference data should be
-added for the styles where a suitable tester program already exists
-(e.g. pair styles, bond styles, etc.). Please see
-:ref:`this section in the manual ` for more information on
-how to enable, run, and expand testing.
+- All files should have 0644 permissions, i.e. writable by the user
+ only and readable by all and no executable permissions. Executable
+ permissions (0755) should only be for shell scripts or python or
+ similar scripts for interpreted script languages.
diff --git a/doc/src/PDF/colvars-refman-lammps.pdf b/doc/src/PDF/colvars-refman-lammps.pdf
index 59d12f9253..4f85537b35 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/Python_properties.rst b/doc/src/Python_properties.rst
index d8e772379c..031461660a 100644
--- a/doc/src/Python_properties.rst
+++ b/doc/src/Python_properties.rst
@@ -53,6 +53,7 @@ against invalid accesses.
* :py:meth:`version() `: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
* :py:meth:`get_thermo() `: return current value of a thermo keyword
+ * :py:meth:`last_thermo() `: return a dictionary of the last thermodynamic output
* :py:meth:`get_natoms() `: total # of atoms as int
* :py:meth:`reset_box() `: reset the simulation box size
* :py:meth:`extract_setting() `: return a global setting
@@ -60,6 +61,10 @@ against invalid accesses.
* :py:meth:`extract_box() `: extract box info
* :py:meth:`create_atoms() `: create N atoms with IDs, types, x, v, and image flags
+ **Properties**:
+
+ * :py:attr:`last_thermo_step `: the last timestep thermodynamic output was computed
+
.. tab:: PyLammps/IPyLammps API
In addition to the functions provided by :py:class:`lammps `, :py:class:`PyLammps ` objects
diff --git a/doc/src/Speed_kokkos.rst b/doc/src/Speed_kokkos.rst
index 569a24f1c2..8161e69a1c 100644
--- a/doc/src/Speed_kokkos.rst
+++ b/doc/src/Speed_kokkos.rst
@@ -285,6 +285,16 @@ one or more nodes, each with two GPUs:
settings. Experimenting with its options can provide a speed-up for
specific calculations. For example:
+.. note::
+
+ The default binsize for :doc:`atom sorting ` on GPUs
+ is equal to the default CPU neighbor binsize (i.e. 2x smaller than the
+ default GPU neighbor binsize). When running simple pair-wise
+ potentials like Lennard Jones on GPUs, using a 2x larger binsize for
+ atom sorting (equal to the default GPU neighbor binsize) and a more
+ frequent sorting than default (e.g. sorting every 100 time steps
+ instead of 1000) may improve performance.
+
.. code-block:: bash
mpirun -np 2 lmp_kokkos_cuda_openmpi -k on g 2 -sf kk -pk kokkos newton on neigh half binsize 2.8 -in in.lj # Newton on, half neighbor list, set binsize = neighbor ghost cutoff
diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst
index 2eae1aabc7..bccb9abe73 100644
--- a/doc/src/Tools.rst
+++ b/doc/src/Tools.rst
@@ -883,9 +883,9 @@ dependencies and redirects the download to the local cache.
phonon tool
------------------------
-The phonon subdirectory contains a post-processing tool useful for
-analyzing the output of the :doc:`fix phonon ` command in
-the PHONON package.
+The phonon subdirectory contains a post-processing tool, *phana*, useful
+for analyzing the output of the :doc:`fix phonon ` command
+in the PHONON package.
See the README file for instruction on building the tool and what
library it needs. And see the examples/PACKAGES/phonon directory
diff --git a/doc/src/atom_modify.rst b/doc/src/atom_modify.rst
index 9049a24fde..1e5a3d49ff 100644
--- a/doc/src/atom_modify.rst
+++ b/doc/src/atom_modify.rst
@@ -153,6 +153,13 @@ cache locality will be undermined.
order of atoms in a :doc:`dump ` file will also typically change
if sorting is enabled.
+.. note::
+
+ When running simple pair-wise potentials like Lennard Jones on GPUs
+ with the KOKKOS package, using a larger binsize (e.g. 2x larger than
+ default) and a more frequent reordering than default (e.g. every 100
+ time steps) may improve performance.
+
Restrictions
""""""""""""
diff --git a/doc/src/bond_bpm_rotational.rst b/doc/src/bond_bpm_rotational.rst
index ba93d679ba..ca12d86ccc 100644
--- a/doc/src/bond_bpm_rotational.rst
+++ b/doc/src/bond_bpm_rotational.rst
@@ -24,14 +24,17 @@ Syntax
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
- *overlay/pair* value = none
+ *overlay/pair* value = *yes* or *no*
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
- *break/no*
- indicates that bonds should not break during a run
+ *normalize* value = *yes* or *no*
+ normalizes normal and shear forces by the reference length
+
+ *break* value = *yes* or *no*
+ indicates whether bonds break during a run
Examples
""""""""
@@ -136,16 +139,19 @@ or :doc:`read_restart ` commands:
* :math:`\gamma_r` (force*distance/velocity units)
* :math:`\gamma_t` (force*distance/velocity units)
+However, the *normalize* option will normalize the radial and shear forces
+by :math:`r_0` such that :math:`k_r` and :math:`k_s` are unit less.
+
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
-the *overlay/pair* keyword. These settings require specific
+the *overlay/pair* option. These settings require specific
:doc:`special_bonds ` settings described in the
restrictions. Further details can be found in the `:doc: how to
` page on BPMs.
.. versionadded:: 28Mar2023
-If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
+If the *break* option is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
@@ -251,7 +257,7 @@ Related commands
Default
"""""""
-The option defaults are *smooth* = *yes*
+The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
----------
diff --git a/doc/src/bond_bpm_spring.rst b/doc/src/bond_bpm_spring.rst
index 5762dbe208..d89035dcad 100644
--- a/doc/src/bond_bpm_spring.rst
+++ b/doc/src/bond_bpm_spring.rst
@@ -24,14 +24,17 @@ Syntax
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
- *overlay/pair* value = none
+ *overlay/pair* value = *yes* or *no*
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
- *break/no*
- indicates that bonds should not break during a run
+ *normalize* value = *yes* or *no*
+ normalizes bond forces by the reference length
+
+ *break* value = *yes* or *no*
+ indicates whether bonds break during a run
Examples
""""""""
@@ -66,7 +69,7 @@ particles based on a model described by Clemmer and Robbins
F = k (r - r_0) w
-where :math:`k_r` is a stiffness, :math:`r` is the current distance
+where :math:`k` is a stiffness, :math:`r` is the current distance
and :math:`r_0` is the initial distance between the two particles, and
:math:`w` is an optional smoothing factor discussed below. Bonds will
break at a strain of :math:`\epsilon_c`. This is done by setting by
@@ -102,16 +105,19 @@ the data file or restart files read by the :doc:`read_data
* :math:`\epsilon_c` (unit less)
* :math:`\gamma` (force/velocity units)
+However, the *normalize* option will normalize the elastic bond force by
+:math:`r_0` such that :math:`k` is unit less.
+
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
-the *overlay/pair* keyword. These settings require specific
+the *overlay/pair* option. These settings require specific
:doc:`special_bonds ` settings described in the
restrictions. Further details can be found in the `:doc: how to
` page on BPMs.
.. versionadded:: 28Mar2023
-If the *break/no* keyword is used, then LAMMPS assumes bonds should not break
+If the *break* option is used, then LAMMPS assumes bonds should not break
during a simulation run. This will prevent some unnecessary calculation.
However, if a bond does break, it will trigger an error.
@@ -206,7 +212,7 @@ Related commands
Default
"""""""
-The option defaults are *smooth* = *yes*
+The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
----------
diff --git a/doc/src/bond_style.rst b/doc/src/bond_style.rst
index b33d0a9e9a..95f463e695 100644
--- a/doc/src/bond_style.rst
+++ b/doc/src/bond_style.rst
@@ -32,13 +32,13 @@ Set the formula(s) LAMMPS uses to compute bond interactions between
pairs of atoms. In LAMMPS, a bond differs from a pairwise
interaction, which are set via the :doc:`pair_style `
command. Bonds are defined between specified pairs of atoms and
-remain in force for the duration of the simulation (unless the bond
-breaks which is possible in some bond potentials). The list of bonded
-atoms is read in by a :doc:`read_data ` or
-:doc:`read_restart ` command from a data or restart file.
-By contrast, pair potentials are typically defined between all pairs
-of atoms within a cutoff distance and the set of active interactions
-changes over time.
+remain in force for the duration of the simulation (unless new bonds
+are created or existing bonds break, which is possible in some fixes
+and bond potentials). The list of bonded atoms is read in by a
+:doc:`read_data ` or :doc:`read_restart `
+command from a data or restart file. By contrast, pair potentials are
+typically defined between all pairs of atoms within a cutoff distance
+and the set of active interactions changes over time.
Hybrid models where bonds are computed using different bond potentials
can be setup using the *hybrid* bond style.
diff --git a/doc/src/compute.rst b/doc/src/compute.rst
index 880f60a8a6..4e5d8e6cb4 100644
--- a/doc/src/compute.rst
+++ b/doc/src/compute.rst
@@ -200,6 +200,7 @@ The individual style names on the :doc:`Commands compute ` pag
* :doc:`com/chunk ` - center of mass for each chunk
* :doc:`contact/atom ` - contact count for each spherical particle
* :doc:`coord/atom ` - coordination number for each atom
+* :doc:`count/type ` - count of atoms or bonds by type
* :doc:`damage/atom ` - Peridynamic damage for each atom
* :doc:`dihedral ` - energy of each dihedral sub-style
* :doc:`dihedral/local ` - angle of each dihedral
@@ -306,11 +307,11 @@ The individual style names on the :doc:`Commands compute ` pag
* :doc:`sph/t/atom ` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`spin ` - magnetic quantities for a system of atoms having spins
* :doc:`stress/atom ` - stress tensor for each atom
-* :doc:`stress/cartesian ` - stress tensor in cartesian coordinates
-* :doc:`stress/cylinder ` - stress tensor in cylindrical coordinates
+* :doc:`stress/cartesian ` - stress tensor in cartesian coordinates
+* :doc:`stress/cylinder ` - stress tensor in cylindrical coordinates
* :doc:`stress/mop ` - normal components of the local stress tensor using the method of planes
* :doc:`stress/mop/profile ` - profile of the normal components of the local stress tensor using the method of planes
-* :doc:`stress/spherical ` - stress tensor in spherical coordinates
+* :doc:`stress/spherical ` - stress tensor in spherical coordinates
* :doc:`stress/tally ` - stress between two groups of atoms via the tally callback mechanism
* :doc:`tdpd/cc/atom ` - per-atom chemical concentration of a specified species for each tDPD particle
* :doc:`temp ` - temperature of group of atoms
diff --git a/doc/src/compute_bond_local.rst b/doc/src/compute_bond_local.rst
index f3fb752ebe..10e86bbe44 100644
--- a/doc/src/compute_bond_local.rst
+++ b/doc/src/compute_bond_local.rst
@@ -76,7 +76,10 @@ The value *force* is the magnitude of the force acting between the
pair of atoms in the bond.
The values *fx*, *fy*, and *fz* are the xyz components of
-*force* between the pair of atoms in the bond.
+*force* between the pair of atoms in the bond. For bond styles that apply
+non-central forces, such as :doc:`bond_style bpm/rotational
+`, these values only include the :math:`(x,y,z)`
+components of the normal force component.
The remaining properties are all computed for motion of the two atoms
relative to the center of mass (COM) velocity of the 2 atoms in the
diff --git a/doc/src/compute_count_type.rst b/doc/src/compute_count_type.rst
new file mode 100644
index 0000000000..ca3b02ecdb
--- /dev/null
+++ b/doc/src/compute_count_type.rst
@@ -0,0 +1,130 @@
+.. index:: compute count/type
+
+compute count/type command
+==========================
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+ compute ID group-ID count/type mode
+
+* ID, group-ID are documented in :doc:`compute ` command
+* count/type = style name of this compute command
+* mode = {atom} or {bond} or {angle} or {dihedral} or {improper}
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+ compute 1 all count/type atom
+ compute 1 flowmols count/type bond
+
+Description
+"""""""""""
+
+.. versionadded:: 15Jun2023
+
+Define a computation that counts the current number of atoms for each
+atom type. Or the number of bonds (angles, dihedrals, impropers) for
+each bond (angle, dihedral, improper) type.
+
+The former can be useful if atoms are added to or deleted from the
+system in random ways, e.g. via the :doc:`fix deposit `,
+:doc:`fix pour `, or :doc:`fix evaporate `
+commands. The latter can be useful in reactive simulations where
+molecular bonds are broken or created, as well as angles, dihedrals,
+impropers.
+
+Note that for this command, bonds (angles, etc) are the topological
+kind enumerated in a data file, initially read by the :doc:`read_data
+` command or defined by the :doc:`molecule `
+command. They do not refer to implicit bonds defined on-the-fly by
+bond-order or reactive pair styles based on the current conformation
+of small clusters of atoms.
+
+These commands can turn off topological bonds (angles, etc) by setting
+their bond (angle, etc) types to negative values. This command
+includes the turned-off bonds (angles, etc) in the count for each
+type:
+
+* :doc:`fix shake `
+* :doc:`delete_bonds `
+
+These commands can create and/or break topological bonds (angles,
+etc). In the case of breaking, they remove the bond (angle, etc) from
+the system, so that they no longer exist (:doc:`bond_style quartic
+` and :doc:`BPM bond styles ` are exceptions,
+see the discussion below). Thus they are not included in the counts
+for each type:
+
+* :doc:`delete_bonds remove `
+* :doc:`bond_style quartic