ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'lammps:develop' into develop_ap

Browse Source
This commit is contained in:
Immel
2025-04-08 16:03:25 +02:00
committed by GitHub
parent 535d08895a 6372178caa
commit 139ecd0e90
1259 changed files with 36872 additions and 28597 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.github/CODEOWNERS vendored
View File

@ -71,6 +71,7 @@ src/EXTRA-COMMAND/group_ndx.* @akohlmey
src/EXTRA-COMMAND/ndx_group.* @akohlmey
src/EXTRA-COMPUTE/compute_stress_mop*.* @RomainVermorel
src/EXTRA-COMPUTE/compute_born_matrix.* @Bibobu @athomps
src/EXTRA-DUMP/dump_extxyz.* @fxcoudert
src/EXTRA-FIX/fix_deform_pressure.* @jtclemm
src/EXTRA-PAIR/pair_dispersion_d3.* @soniasolomoni @arthurfl
src/EXTRA-PAIR/d3_parameters.h @soniasolomoni @arthurfl

47
.github/release_steps.md vendored
View File

@ -216,7 +216,7 @@ and using the CMake settings:
``` sh
-D CMAKE_OSX_ARCHITECTURES=arm64;x86_64
-D CMAKE_OSX_DEPLOYMENT_TARGER=11.0
-D CMAKE_OSX_DEPLOYMENT_TARGET=11.0
```
This will add the compiler flags `-arch arm64 -arch x86_64
@ -324,6 +324,47 @@ At this point it should be possible to do a fast-forward merge of
### Push branches and tags
## LAMMPS Stable Update Release
After making a stable release, bugfixes from the 'develop' branch
are selectively backported to the 'maintenance' branch. This is
done with "git cherry-pick \<commit hash\>' wherever possible.
The LAMMPS\_UPDATE define in "src/version.h" is set to "Maintenance".
### Prerequesites
When a sufficient number of bugfixes has accumulated or an urgent
or important bugfix needs to be distributed a new stable update
release is made. To make this publicly visible a pull request
is submitted that will merge 'maintenance' into 'stable'. Before
merging, set LAMMPS\_UPDATE in "src/version.h" to "Update #" with
"#" indicating the update count (1, 2, and so on).
Also draft suitable release notes under https://github.com/lammps/lammps/releases
### Fast-forward merge of 'maintenance' into 'stable', apply tag, and publish
Do a fast-forward merge of 'maintenance' to 'stable' and then
apply the stable\_DMmmYYYY\_update# tag and push branch and tag
to GitHub. The corresponding pull request will be automatically
closed. Example:
```
git checkout maintenance
git pull
git checkout stable
git pull
git merge --ff-only maintenance
git tag -s -m 'Update 2 for Stable LAMMPS version 29 August 2024' stable_29Aug2024_update2
git push git@github.com:lammps/lammps.git --tags maintenance stable
```
Associate draft release notes with new tag and publish as "latest release".
On https://ci.lammps.org/ go to "dev", "stable" and manually execute
the "update\_release" task. This will update https://docs.lammps.org/stable
and prepare a stable tarball.
### Build and upload binary packages and source tarball to GitHub
The build procedure is the same as for the feature releases, only
that packages are built from the 'stable' branch.

4
cmake/CMakeLists.txt
View File

@ -432,8 +432,8 @@ else()
target_link_libraries(lammps PUBLIC mpi_stubs)
endif()
set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall)
set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
set(LAMMPS_SIZES_VALUES smallbig bigbig)
set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES})
validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES)
string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES)

4
cmake/Modules/LAMMPSInterfacePlugin.cmake
View File

@ -260,8 +260,8 @@ endif()
################
# integer size selection
set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallsmall: all 32-bit, smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
set(LAMMPS_SIZES_VALUES smallbig bigbig smallsmall)
set(LAMMPS_SIZES "smallbig" CACHE STRING "LAMMPS integer sizes (smallbig: 64-bit #atoms #timesteps, bigbig: also 64-bit imageint, 64-bit atom ids)")
set(LAMMPS_SIZES_VALUES smallbig bigbig)
set_property(CACHE LAMMPS_SIZES PROPERTY STRINGS ${LAMMPS_SIZES_VALUES})
validate_option(LAMMPS_SIZES LAMMPS_SIZES_VALUES)
string(TOUPPER ${LAMMPS_SIZES} LAMMPS_SIZES)

14
cmake/Modules/Packages/EXTRA-COMMAND.cmake
View File

@ -1,10 +1,18 @@
# the geturl command needs libcurl
find_package(CURL QUIET COMPONENTS HTTP HTTPS)
find_package(CURL QUIET)
option(WITH_CURL "Enable libcurl support" ${CURL_FOUND})
if(WITH_CURL)
find_package(CURL REQUIRED COMPONENTS HTTP HTTPS)
target_compile_definitions(lammps PRIVATE -DLAMMPS_CURL)
target_link_libraries(lammps PRIVATE CURL::libcurl)
# need to use pkgconfig for fully static bins to find custom static libs
if (CMAKE_SYSTEM_NAME STREQUAL "LinuxMUSL")
include(FindPkgConfig)
pkg_check_modules(CURL IMPORTED_TARGET libcurl libssl libcrypto)
target_link_libraries(lammps PUBLIC PkgConfig::CURL)
else()
find_package(CURL REQUIRED)
target_link_libraries(lammps PRIVATE CURL::libcurl)
endif()
endif()

6
cmake/Modules/Packages/KOKKOS.cmake
View File

@ -57,8 +57,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/4.5.01.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "4d832aa0284169d9e3fbae3165286bc6" CACHE STRING "MD5 checksum of KOKKOS tarball")
set(KOKKOS_URL "https://github.com/kokkos/kokkos/archive/4.6.00.tar.gz" CACHE STRING "URL for KOKKOS tarball")
set(KOKKOS_MD5 "61b2b69ae50d83eedcc7d47a3fa3d6cb" CACHE STRING "MD5 checksum of KOKKOS tarball")
mark_as_advanced(KOKKOS_URL)
mark_as_advanced(KOKKOS_MD5)
GetFallbackURL(KOKKOS_URL KOKKOS_FALLBACK)
@ -83,7 +83,7 @@ if(DOWNLOAD_KOKKOS)
add_dependencies(LAMMPS::KOKKOSCORE kokkos_build)
add_dependencies(LAMMPS::KOKKOSCONTAINERS kokkos_build)
elseif(EXTERNAL_KOKKOS)
find_package(Kokkos 4.5.01 REQUIRED CONFIG)
find_package(Kokkos 4.6.00 REQUIRED CONFIG)
target_link_libraries(lammps PRIVATE Kokkos::kokkos)
else()
set(LAMMPS_LIB_KOKKOS_SRC_DIR ${LAMMPS_LIB_SOURCE_DIR}/kokkos)

3
cmake/presets/kokkos-cuda.cmake
View File

@ -1,6 +1,5 @@
# preset that enables KOKKOS and selects CUDA compilation with OpenMP
# enabled as well. This preselects CC 5.0 as default GPU arch, since
# that is compatible with all higher CC, but not the default CC 3.5
# enabled as well. The GPU architecture *must* match your hardware
set(PKG_KOKKOS ON CACHE BOOL "" FORCE)
set(Kokkos_ENABLE_SERIAL ON CACHE BOOL "" FORCE)
set(Kokkos_ENABLE_CUDA ON CACHE BOOL "" FORCE)

49
doc/Makefile
View File

@ -17,9 +17,11 @@ MATHJAXTAG = 3.2.2
PYTHON = $(word 3,$(shell type python3))
DOXYGEN = $(word 3,$(shell type doxygen))
PANDOC = $(word 3,$(shell type pandoc))
HAS_PYTHON3 = NO
HAS_DOXYGEN = NO
HAS_PDFLATEX = NO
HAS_PANDOC = NO
ifeq ($(shell type python3 >/dev/null 2>&1; echo $$?), 0)
HAS_PYTHON3 = YES
@ -31,10 +33,14 @@ endif
ifeq ($(shell type pdflatex >/dev/null 2>&1; echo $$?), 0)
ifeq ($(shell type latexmk >/dev/null 2>&1; echo $$?), 0)
HAS_PDFLATEX = YES
HAS_PDFLATEX = YES
endif
endif
ifeq ($(shell type pandoc >/dev/null 2>&1; echo $$?), 0)
HAS_PANDOC = YES
endif
# override settings for PIP commands
# PIP_OPTIONS = --cert /etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt --proxy http://proxy.mydomain.org
@ -45,8 +51,9 @@ SPHINXEXTRA = -j $(shell $(PYTHON) -c 'import multiprocessing;print(multiprocess
# we only want to use explicitly listed files.
DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+=/p' doxygen/Doxyfile.in | sed -e 's/@LAMMPS_SOURCE_DIR@/..\/src/g' -e 's/\\//g' -e 's/ \+/ /' -e 's/[A-Z_]\+ \+= *\(YES\|NO\|\)//')
.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml
.PHONY: help clean-all clean clean-spelling epub mobi html pdf spelling anchor_check style_check char_check role_check xmlgen fasthtml fasthtml-init
FASTHTMLFILES = $(patsubst $(RSTDIR)/%.rst,fasthtml/%.html,$(wildcard $(RSTDIR)/*rst))
# ------------------------------------------
help:
@ -105,6 +112,8 @@ html: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJ
env LC_ALL=C grep -n ':\(ref\|doc\):[^`]' $(RSTDIR)/*.rst ;\
env LC_ALL=C grep -n '\(ref\|doc\)`[^`]' $(RSTDIR)/*.rst ;\
$(PYTHON) $(BUILDDIR)/utils/check-styles.py -s ../src -d src ;\
env LC_ALL=C grep -n -E '^ *\.\. [a-z0-9]+:(\s+.*|)$$' \
$(RSTDIR)/*.rst ../src/*.{cpp,h} ../src/*/*.{cpp,h} ;\
echo "############################################" ;\
deactivate ;\
)
@ -116,25 +125,23 @@ html: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJ
@rm -rf html/PDF/.[sg]*
@echo "Build finished. The HTML pages are in doc/html."
fasthtml: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK) $(MATHJAX)
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
@$(MAKE) $(MFLAGS) -C graphviz all
@mkdir -p fasthtml
@(\
. $(VENV)/bin/activate ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
touch $(RSTDIR)/Fortran.rst ; env PYTHONWARNINGS= PYTHONDONTWRITEBYTECODE=1 \
sphinx-build $(SPHINXEXTRA) -b html -c $(SPHINXCONFIG) -d $(BUILDDIR)/fasthtml/doctrees $(RSTDIR) fasthtml ;\
deactivate ;\
)
@rm -rf fasthtml/_sources
@rm -rf fasthtml/PDF
@rm -rf fasthtml/USER
@rm -rf fasthtml/JPG
@cp -r src/PDF fasthtml/PDF
@rm -rf fasthtml/PDF/.[sg]*
fasthtml: fasthtml-init $(FASTHTMLFILES)
@echo "Fast HTML build finished. The HTML pages are in doc/fasthtml."
fasthtml-init:
@mkdir -p fasthtml/JPG
@cp src/JPG/*.* fasthtml/JPG
@cp $(RSTDIR)/accel_styles.rst $(RSTDIR)/lepton_expression.rst fasthtml/
@cp $(BUILDDIR)/utils/pandoc.css fasthtml/
fasthtml/%.html: $(RSTDIR)/%.rst
@if [ "$(HAS_PANDOC)" == "NO" ] ; then echo "Make 'fasthtml' requires the 'pandoc' software" 1>&2; exit 1; fi
@mkdir -p fasthtml
@echo converting $< to $@
@sed -e 's/\\AA/\\mathring{\\mathrm{A}}/g' $< > fasthtml/$*.temp.rst
@pandoc -s --mathml --css="pandoc.css" --template=$(BUILDDIR)/utils/pandoc.html --metadata title="$@" -o $@ fasthtml/$*.temp.rst
@rm -f fasthtml/$*.temp.rst
spelling: xmlgen globbed-tocs $(SPHINXCONFIG)/conf.py $(VENV) $(SPHINXCONFIG)/false_positives.txt
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
@(\
@ -188,6 +195,8 @@ pdf: xmlgen globbed-tocs $(VENV) $(SPHINXCONFIG)/conf.py $(ANCHORCHECK)
env LC_ALL=C grep -n ':\(ref\|doc\):[^`]' $(RSTDIR)/*.rst ;\
env LC_ALL=C grep -n '\(ref\|doc\)`[^`]' $(RSTDIR)/*.rst ;\
$(PYTHON) utils/check-styles.py -s ../src -d src ;\
env LC_ALL=C grep -n -E '^ *\.\. [a-z0-9]+:(\s+.*|)$$' \
$(RSTDIR)/*.rst ../src/*.{cpp,h} ../src/*/*.{cpp,h} ;\
echo "############################################" ;\
deactivate ;\
)
@ -237,6 +246,8 @@ role_check :
@( env LC_ALL=C grep -n ' `[^`]\+<[a-z][^`]\+`[^_]' $(RSTDIR)/*.rst && exit 1 || : )
@( env LC_ALL=C grep -n ':\(ref\|doc\):[^`]' $(RSTDIR)/*.rst && exit 1 || : )
@( env LC_ALL=C grep -n '\(ref\|doc\)`[^`]' $(RSTDIR)/*.rst && exit 1 || : )
@( env LC_ALL=C grep -n -E '^ *\.\. [a-z0-9]+:(\s+.*|)$$' \
$(RSTDIR)/*.rst ../src/*.{cpp,h} ../src/*/*.{cpp,h} && exit 1 || : )
link_check : $(VENV) html
@(\

4
doc/lammps.1
View File

@ -1,7 +1,7 @@
.TH LAMMPS "1" "4 February 2025" "2025-02-04"
.TH LAMMPS "1" "2 April 2025" "2025-04-02"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator. Version 4 February 2025
\- Molecular Dynamics Simulator. Version 2 April 2025
.SH SYNOPSIS
.B lmp

7
doc/src/Build_cmake.rst
View File

@ -119,6 +119,13 @@ configured) and additional files like LAMMPS API headers, manpages,
potential and force field files. The location of the installation tree
defaults to ``${HOME}/.local``.
.. note::
If you have set `-D CMAKE_INSTALL_PREFIX` to install LAMMPS into a
system location on a Linux machine , you may also have to run (as
root) the `ldconfig` program to update the cache file for fast lookup
of system shared libraries.
.. _cmake_options:
Configuration and build options

14
doc/src/Build_extras.rst
View File

@ -255,11 +255,10 @@ Traditional make
Before building LAMMPS, you must build the GPU library in ``lib/gpu``\ .
You can do this manually if you prefer; follow the instructions in
``lib/gpu/README``. Note that the GPU library uses MPI calls, so you must
use the same MPI library (or the STUBS library) settings as the main
LAMMPS code. This also applies to the ``-DLAMMPS_BIGBIG``\ ,
``-DLAMMPS_SMALLBIG``\ , or ``-DLAMMPS_SMALLSMALL`` settings in whichever
Makefile you use.
``lib/gpu/README``. Note that the GPU library uses MPI calls, so you
must use the same MPI library (or the STUBS library) settings as the
main LAMMPS code. This also applies to the ``-DLAMMPS_BIGBIG`` or
``-DLAMMPS_SMALLBIG`` settings in whichever Makefile you use.
You can also build the library in one step from the ``lammps/src`` dir,
using a command like these, which simply invokes the ``lib/gpu/Install.py``
@ -612,6 +611,9 @@ They must be specified in uppercase.
* - ZEN3
- HOST
- AMD Zen3 architecture
* - ZEN4
- HOST
- AMD Zen4 architecture
* - RISCV_SG2042
- HOST
- SG2042 (RISC-V) CPUs
@ -715,7 +717,7 @@ They must be specified in uppercase.
- GPU
- Intel GPU Ponte Vecchio
This list was last updated for version 4.5.1 of the Kokkos library.
This list was last updated for version 4.6.0 of the Kokkos library.
.. tabs::

43
doc/src/Build_manual.rst
View File

@ -78,8 +78,7 @@ folder. The following ``make`` commands are available:
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
make fasthtml # generate approximate HTML in fasthtml dir using Sphinx
# some Sphinx extensions do not work correctly with this
make fasthtml # generate approximate HTML in fasthtml dir using pandoc
make clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data
@ -205,12 +204,42 @@ documentation is required and either existing files in the ``src``
folder need to be updated or new files added. These files are written in
`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
Testing your contribution
^^^^^^^^^^^^^^^^^^^^^^^^^
Before contributing any documentation, please check that both the HTML
and the PDF format documentation can translate without errors. During
testing the html translation, you may use the ``make fasthtml`` command
which does an approximate translation (i.e. not all Sphinx features and
extensions will work), but runs very fast because it will only translate
files that have been changed since the last ``make fasthtml`` command.
and the PDF format documentation can translate without errors and that
there are no spelling issues. This is done with ``make html``, ``make pdf``,
and ``make spelling``, respectively.
Fast and approximate translation to HTML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Translating the full manual to HTML or PDF can take a long time. Thus
there is a fast and approximate way to translate the reStructuredText to
HTML as a quick-n-dirty way of checking your manual page.
This translation uses `Pandoc <https://pandoc.org>`_ instead of Sphinx
and thus all special Sphinx features (cross-references, advanced tables,
embedding of Python docstrings or doxygen documentation, and so on) will
not render correctly. Most embedded math should render correctly. This
is a **very fast** way to check the syntax and layout of a documentation
file translated to HTML while writing or updating it.
To translate **all** manual pages, you can type ``make fasthtml`` at the
command line. The translated HTML files are then in the ``fasthtml``
folder. All subsequent ``make fasthtml`` commands will only translate
``.rst`` files that have been changed. The ``make fasthtml`` command
can be parallelized with make using the `-j` flag. You can also
directly translate only individual pages: e.g. to translate only the
``doc/src/pair_lj.rst`` page type ``make fasthtml/pair_lj.html``
After writing the documentation is completed, you will still need
to verify with ``make html`` and ``make pdf`` that it translates
correctly in both formats.
Tests for consistency, completeness, and other known issues
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Please also check the output to the console for any warnings or problems. There will
be multiple tests run automatically:

41
doc/src/Build_settings.rst
View File

@ -13,7 +13,8 @@ explains how to do this for building both with CMake and make.
* `Size of LAMMPS integer types and size limits`_
* `Read or write compressed files`_
* `Output of JPEG, PNG, and movie files`_ via the :doc:`dump image <dump_image>` or :doc:`dump movie <dump_image>` commands
* `Support for downloading files`_
* `Support for downloading files from the input`_
* `Prevent download of large potential files`_
* `Memory allocation alignment`_
* `Workaround for long long integers`_
* `Exception handling when using LAMMPS as a library`_ to capture errors
@ -315,7 +316,7 @@ large counters can become before "rolling over". The default setting of
.. code-block:: bash
-D LAMMPS_SIZES=value # smallbig (default) or bigbig or smallsmall
-D LAMMPS_SIZES=value # smallbig (default) or bigbig
If the variable is not set explicitly, "smallbig" is used.
@ -326,7 +327,7 @@ large counters can become before "rolling over". The default setting of
.. code-block:: make
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG or -DLAMMPS_SMALLSMALL
LMP_INC = -DLAMMPS_SMALLBIG # or -DLAMMPS_BIGBIG
The default setting is ``-DLAMMPS_SMALLBIG`` if nothing is specified
@ -335,34 +336,27 @@ LAMMPS system size restrictions
.. list-table::
:header-rows: 1
:widths: 18 27 28 27
:widths: 27 36 37
:align: center
* -
- smallbig
- bigbig
- smallsmall
* - Total atom count
- :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{63}` atoms (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{31}` atoms (= :math:`2.147 \cdot 10^9`)
* - Total timesteps
- :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{63}` steps (= :math:`9.223 \cdot 10^{18}`)
- :math:`2^{31}` steps (= :math:`2.147 \cdot 10^9`)
* - Atom ID values
- :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)`
- :math:`1 \le i \le 2^{63} (= 9.223 \cdot 10^{18})`
- :math:`1 \le i \le 2^{31} (= 2.147 \cdot 10^9)`
* - Image flag values
- :math:`-512 \le i \le 511`
- :math:`- 1\,048\,576 \le i \le 1\,048\,575`
- :math:`-512 \le i \le 511`
The "bigbig" setting increases the size of image flags and atom IDs over
"smallbig" and the "smallsmall" setting is only needed if your machine
does not support 64-bit integers or incurs performance penalties when
using them.
the default "smallbig" setting.
These are limits for the core of the LAMMPS code, specific features or
some styles may impose additional limits. The :ref:`ATC
@ -516,8 +510,8 @@ during a run.
.. _libcurl:
Support for downloading files
-----------------------------
Support for downloading files from the input
--------------------------------------------
.. versionadded:: 29Aug2024
@ -560,6 +554,25 @@ LAMMPS is compiled accordingly which needs the following settings:
----------
.. _download_pot:
Prevent download of large potential files
-----------------------------------------
.. versionadded:: 8Feb2023
LAMMPS bundles a selection of potential files in the ``potentials``
folder as examples of how those kinds of potential files look like and
for use with the provided input examples in the ``examples`` tree. To
keep the size of the distributed LAMMPS source package small, very large
potential files (> 5 MBytes) are not bundled, but only downloaded on
demand when the :doc:`corresponding package <Packages_list>` is
installed. This automatic download can be prevented when :doc:`building
LAMMPS with CMake <Build_cmake>` by adding the setting `-D
DOWNLOAD_POTENTIALS=off` when configuring.
----------
.. _align:
Memory allocation alignment

3
doc/src/Commands_bond.rst
View File

@ -23,6 +23,7 @@ OPT.
*
* :doc:`bpm/rotational <bond_bpm_rotational>`
* :doc:`bpm/spring <bond_bpm_spring>`
* :doc:`bpm/spring/plastic <bond_bpm_spring_plastic>`
* :doc:`class2 (ko) <bond_class2>`
* :doc:`fene (iko) <bond_fene>`
* :doc:`fene/expand (o) <bond_fene_expand>`
@ -127,7 +128,7 @@ OPT.
* :doc:`harmonic (iko) <dihedral_harmonic>`
* :doc:`helix (o) <dihedral_helix>`
* :doc:`lepton (o) <dihedral_lepton>`
* :doc:`multi/harmonic (o) <dihedral_multi_harmonic>`
* :doc:`multi/harmonic (ko) <dihedral_multi_harmonic>`
* :doc:`nharmonic (o) <dihedral_nharmonic>`
* :doc:`opls (iko) <dihedral_opls>`
* :doc:`quadratic (o) <dihedral_quadratic>`

1
doc/src/Commands_dump.rst
View File

@ -19,6 +19,7 @@ An alphabetic list of all LAMMPS :doc:`dump <dump>` commands.
* :doc:`custom/gz <dump>`
* :doc:`custom/zstd <dump>`
* :doc:`dcd <dump>`
* :doc:`extxyz <dump>`
* :doc:`grid <dump>`
* :doc:`grid/vtk <dump>`
* :doc:`h5md <dump_h5md>`

3
doc/src/Commands_fix.rst
View File

@ -165,6 +165,8 @@ OPT.
* :doc:`phonon <fix_phonon>`
* :doc:`pimd/langevin <fix_pimd>`
* :doc:`pimd/nvt <fix_pimd>`
* :doc:`pimd/langevin/bosonic <fix_pimd>`
* :doc:`pimd/nvt/bosonic <fix_pimd>`
* :doc:`planeforce <fix_planeforce>`
* :doc:`plumed <fix_plumed>`
* :doc:`poems <fix_poems>`
@ -187,6 +189,7 @@ OPT.
* :doc:`qeq/fire <fix_qeq>`
* :doc:`qeq/point <fix_qeq>`
* :doc:`qeq/reaxff (ko) <fix_qeq_reaxff>`
* :doc:`qeq/rel/reaxff <fix_qeq_rel_reaxff>`
* :doc:`qeq/shielded <fix_qeq>`
* :doc:`qeq/slater <fix_qeq>`
* :doc:`qmmm <fix_qmmm>`

14
doc/src/Commands_removed.rst
View File

@ -1,7 +1,7 @@
Removed commands and packages
=============================
.. contents::
.. contents:: \
------
@ -170,6 +170,18 @@ performance characteristics on NVIDIA GPUs. Both, the KOKKOS
and the :ref:`GPU package <PKG-GPU>` are maintained
and allow running LAMMPS with GPU acceleration.
Compute atom/molecule
---------------------
.. deprecated:: 11 Dec2015
The atom/molecule command has been removed from LAMMPS since it was superseded
by the more general and extensible "chunk infrastructure". Here the system is
partitioned in one of many possible ways - including using molecule IDs -
through the :doc:`compute chunk/atom <compute_chunk_atom>` command and then
summing is done using :doc:`compute reduce/chunk <compute_reduce_chunk>` Please
refer to the :doc:`chunk HOWTO <Howto_chunk>` section for an overview.
Fix ave/spatial and fix ave/spatial/sphere
------------------------------------------

1
doc/src/Developer.rst
View File

@ -24,4 +24,5 @@ of time and requests from the LAMMPS user community.
Classes
Developer_platform
Developer_utils
Developer_internal
Developer_grid

120
doc/src/Developer_internal.rst Normal file
View File

@ -0,0 +1,120 @@
Internal Styles
---------------
LAMMPS has a number of styles that are not meant to be used in an input
file and thus are not documented in the :doc:`LAMMPS command
documentation <Commands_all>`. The differentiation between user
commands and internal commands is through the case of the command name:
user commands and styles are all lower case, internal styles are all
upper case. Internal styles are not called from the input file, but
their classes are instantiated by other styles. Often they are
created by other styles to store internal data or to perform actions
regularly at specific steps of the simulation.
The paragraphs below document some of those styles that have general
utility and may be used to avoid redundant implementation.
DEPRECATED Styles
^^^^^^^^^^^^^^^^^
The styles called DEPRECATED (e.g. pair, bond, fix, compute, region, etc.)
have the purpose to inform users that a specific style has been removed
or renamed. This is achieved by creating an alias for the deprecated
style to the corresponding class. For example, the fix style DEPRECATED
is aliased to fix style ave/spatial and fix style ave/spatial/sphere with
the following code:
.. code-block:: c++
FixStyle(DEPRECATED,FixDeprecated);
FixStyle(ave/spatial,FixDeprecated);
FixStyle(ave/spatial/sphere,FixDeprecated);
The individual class will then determine based on the style name
what action to perform:
- inform that the style has been removed and what style replaces it, if any, and then error out
- inform that the style has been renamed and then either execute the replacement or error out
- inform that the style is no longer required, and it is thus ignored and continue
There is also a section in the user's guide for :doc:`removed commands
and packages <Commands_removed>` with additional explanations.
Internal fix styles
^^^^^^^^^^^^^^^^^^^
These provide an implementation of features that would otherwise have
been replicated across multiple styles. The used fix ID is generally
derived from the compute or fix ID creating the fix with some string
appended. When needed, the fix can be looked up with
``Modify::get_fix_by_id()``, which returns a pointer to the fix
instance. The data managed by the fix can be accessed just as for other
fixes that can be used in input files.
fix DUMMY
"""""""""
Most fix classes cannot be instantiated before the simulation box has
been created since they access data that is only available then.
However, in some cases it is required that a fix must be at or close to
the top of the list of all fixes. In those cases an instance of the
DUMMY fix style may be created by calling ``Modify::add_fix()`` and then
later replaced by the intended fix through calling ``Modify::replace_fix()``.
fix STORE/ATOM
""""""""""""""
Fix STORE/ATOM can be used as persistent storage of per-atom data.
**Syntax**
.. code-block:: LAMMPS
fix ID group-ID STORE/ATOM N1 N2 gflag rflag
* ID, group-ID are documented in :doc:`fix <fix>` command
* STORE/ATOM = style name of this fix command
* N1 = 1, N2 = 0 : data is per-atom vector = single value per atom
* N1 > 1, N2 = 0 : data is per-atom array = N1 values per atom
* N1 > 0, N2 > 0 : data is per-atom tensor = N1xN2 values per atom
* gflag = 1 communicate per-atom values with ghost atoms, 0 do not update ghost atom data
* rflag = 1 store per-atom value in restart file, 0 do not store data in restart
Similar functionality is also available through using custom per-atom
properties with :doc:`fix property/atom <fix_property_atom>`. The
choice between the two fixes should be based on whether the user should
be able to access this per-atom data: if yes, then fix property/atom is
preferred, otherwise fix STORE/ATOM.
fix STORE/GLOBAL
""""""""""""""""
Fix STORE/GLOBAL can be used as persistent storage of global data with support for restarts
**Syntax**
.. code-block:: LAMMPS
fix ID group-ID STORE/GLOBAL N1 N2
* ID, group-ID are documented in :doc:`fix <fix>` command
* STORE/GLOBAL = style name of this fix command
* N1 >=1 : number of global items to store
* N2 = 1 : data is global vector of length N1
* N2 > 1 : data is global N1xN2 array
fix STORE/LOCAL
"""""""""""""""
Fix STORE/LOCAL can be used as persistent storage for local data
**Syntax**
.. code-block:: LAMMPS
fix ID group-ID STORE/LOCAL Nreset Nvalues
* ID, group-ID are documented in :doc:`fix <fix>` command
* STORE/LOCAL = style name of this fix command
* Nreset = frequency at which local data is available
* Nvalues = number of values per local item, that is the number of columns

2
doc/src/Developer_notes.rst
View File

@ -7,7 +7,7 @@ typically document what a variable stores, what a small section of
code does, or what a function does and its input/outputs. The topics
on this page are intended to document code functionality at a higher level.
.. contents::
.. contents:: Available notes
----

913
doc/src/Errors_details.rst
View File

File diff suppressed because it is too large Load Diff

3487
doc/src/Errors_messages.rst
View File

File diff suppressed because it is too large Load Diff

169
doc/src/Errors_warnings.rst
View File

@ -1,11 +1,15 @@
Warning messages
================
This is an alphabetic list of the WARNING messages LAMMPS prints out
and the reason why. If the explanation here is not sufficient, the
documentation for the offending command may help. Warning messages
also list the source file and line number where the warning was
generated. For example, a message like this:
This is an alphabetic list of some of the WARNING messages LAMMPS prints
out and the reason why. If the explanation here is not sufficient, the
documentation for the offending command may help. This is a historic
list and no longer updated. Instead the LAMMPS developers are trying
to provide more details right with the error message or link to a
paragraph with :doc:`detailed explanations <Errors_details>`.
Warning messages also list the source file and line number where the
warning was generated. For example, a message like this:
.. parsed-literal::
@ -14,7 +18,7 @@ generated. For example, a message like this:
means that line #187 in the file src/domain.cpp generated the error.
Looking in the source code may help you figure out what went wrong.
Doc page with :doc:`ERROR messages <Errors_messages>`
Please also see the page with :doc:`Error messages <Errors_messages>`
----------
@ -28,16 +32,10 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
cutoff is set too short or the angle has blown apart and an atom is
too far away.
*Angle style in data file differs from currently defined angle style*
Self-explanatory.
*Angles are defined but no angle style is set*
The topology contains angles, but there are no angle forces computed
since there was no angle_style command.
*Atom style in data file differs from currently defined atom style*
Self-explanatory.
*Bond atom missing in box size check*
The second atom needed to compute a particular bond is missing on this
processor. Typically this is because the pairwise cutoff is set too
@ -53,9 +51,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
processor. Typically this is because the pairwise cutoff is set too
short or the bond has blown apart and an atom is too far away.
*Bond style in data file differs from currently defined bond style*
Self-explanatory.
*Bonds are defined but no bond style is set*
The topology contains bonds, but there are no bond forces computed
since there was no bond_style command.
@ -68,9 +63,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
length, multiplying by the number of bonds in the interaction (e.g. 3
for a dihedral) and adding a small amount of stretch.
*Both groups in compute group/group have a net charge; the Kspace boundary correction to energy will be non-zero*
Self-explanatory.
*Calling write_dump before a full system init.*
The write_dump command is used before the system has been fully
initialized as part of a 'run' or 'minimize' command. Not all dump
@ -86,18 +78,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
This means the temperature associated with the rigid bodies may be
incorrect on this timestep.
*Cannot include log terms without 1/r terms; setting flagHI to 1*
Self-explanatory.
*Cannot include log terms without 1/r terms; setting flagHI to 1.*
Self-explanatory.
*Charges are set, but coulombic solver is not used*
Self-explanatory.
*Charges did not converge at step %ld: %lg*
Self-explanatory.
*Communication cutoff is 0.0. No ghost atoms will be generated. Atoms may get lost*
The communication cutoff defaults to the maximum of what is inferred from
pair and bond styles (will be zero, if none are defined) and what is specified
@ -123,9 +103,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
is not changed automatically and the warning may be ignored depending
on the specific system being simulated.
*Communication cutoff is too small for SNAP micro load balancing, increased to %lf*
Self-explanatory.
*Compute cna/atom cutoff may be too large to find ghost atom neighbors*
The neighbor cutoff used may not encompass enough ghost atoms
to perform this operation correctly.
@ -158,9 +135,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
Conformation of the 4 listed dihedral atoms is extreme; you may want
to check your simulation geometry.
*Dihedral style in data file differs from currently defined dihedral style*
Self-explanatory.
*Dihedrals are defined but no dihedral style is set*
The topology contains dihedrals, but there are no dihedral forces computed
since there was no dihedral_style command.
@ -177,9 +151,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
*Estimated error in splitting of dispersion coeffs is %g*
Error is greater than 0.0001 percent.
*Ewald/disp Newton solver failed, using old method to estimate g_ewald*
Self-explanatory. Choosing a different cutoff value may help.
*FENE bond too long*
A FENE bond has stretched dangerously far. It's interaction strength
will be truncated to attempt to prevent the bond from blowing up.
@ -192,9 +163,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
A FENE bond has stretched dangerously far. It's interaction strength
will be truncated to attempt to prevent the bond from blowing up.
*Fix halt condition for fix-id %s met on step %ld with value %g*
Self explanatory.
*Fix SRD walls overlap but fix srd overlap not set*
You likely want to set this in your input script.
@ -238,21 +206,12 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
*Fix property/atom mol or charge w/out ghost communication*
A model typically needs these properties defined for ghost atoms.
*Fix qeq CG convergence failed (%g) after %d iterations at %ld step*
Self-explanatory.
*Fix qeq has non-zero lower Taper radius cutoff*
Absolute value must be <= 0.01.
*Fix qeq has very low Taper radius cutoff*
Value should typically be >= 5.0.
*Fix qeq/dynamic tolerance may be too small for damped dynamics*
Self-explanatory.
*Fix qeq/fire tolerance may be too small for damped fires*
Self-explanatory.
*Fix rattle should come after all other integration fixes*
This fix is designed to work after all other integration fixes change
atom positions. Thus it should be the last integration fix specified.
@ -285,9 +244,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
The user-specified force accuracy cannot be achieved unless the table
feature is disabled by using 'pair_modify table 0'.
*Geometric mixing assumed for 1/r\^6 coefficients*
Self-explanatory.
*Group for fix_modify temp != fix group*
The fix_modify command is specifying a temperature computation that
computes a temperature on a different group of atoms than the fix
@ -310,46 +266,14 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
Conformation of the 4 listed improper atoms is extreme; you may want
to check your simulation geometry.
*Improper style in data file differs from currently defined improper style*
Self-explanatory.
*Impropers are defined but no improper style is set*
The topology contains impropers, but there are no improper forces computed
since there was no improper_style command.
*Inconsistent image flags*
The image flags for a pair on bonded atoms appear to be inconsistent.
Inconsistent means that when the coordinates of the two atoms are
unwrapped using the image flags, the two atoms are far apart.
Specifically they are further apart than half a periodic box length.
Or they are more than a box length apart in a non-periodic dimension.
This is usually due to the initial data file not having correct image
flags for the two atoms in a bond that straddles a periodic boundary.
They should be different by 1 in that case. This is a warning because
inconsistent image flags will not cause problems for dynamics or most
LAMMPS simulations. However they can cause problems when such atoms
are used with the fix rigid or replicate commands. Note that if you
have an infinite periodic crystal with bonds then it is impossible to
have fully consistent image flags, since some bonds will cross
periodic boundaries and connect two atoms with the same image
flag.
*Increasing communication cutoff for GPU style*
The pair style has increased the communication cutoff to be consistent with
the communication cutoff requirements for this pair style when run on the GPU.
*KIM Model does not provide 'energy'; Potential energy will be zero*
Self-explanatory.
*KIM Model does not provide 'forces'; Forces will be zero*
Self-explanatory.
*KIM Model does not provide 'particleEnergy'; energy per atom will be zero*
Self-explanatory.
*KIM Model does not provide 'particleVirial'; virial per atom will be zero*
Self-explanatory.
*Kspace_modify slab param < 2.0 may cause unphysical behavior*
The kspace_modify slab parameter should be larger to ensure periodic
grids padded with empty space do not overlap.
@ -401,20 +325,10 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
box, or moved further than one processor's subdomain away before
reneighboring.
*MSM mesh too small, increasing to 2 points in each direction*
Self-explanatory.
*Mismatch between velocity and compute groups*
The temperature computation used by the velocity command will not be
on the same group of atoms that velocities are being set for.
*Mixing forced for lj coefficients*
Self-explanatory.
*Molecule attributes do not match system attributes*
An attribute is specified (e.g. diameter, charge) that is
not defined for the specified atom style.
*Molecule has bond topology but no special bond settings*
This means the bonded atoms will not be excluded in pairwise
interactions.
@ -449,9 +363,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
*More than one compute damage/atom*
It is not efficient to use compute ke/atom more than once.
*More than one compute dilatation/atom*
Self-explanatory.
*More than one compute erotate/sphere/atom*
It is not efficient to use compute erorate/sphere/atom more than once.
@ -464,24 +375,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
*More than one compute orientorder/atom*
It is not efficient to use compute orientorder/atom more than once.
*More than one compute plasticity/atom*
Self-explanatory.
*More than one compute sna/atom*
Self-explanatory.
*More than one compute sna/grid*
Self-explanatory.
*More than one compute sna/grid/local*
Self-explanatory.
*More than one compute snad/atom*
Self-explanatory.
*More than one compute snav/atom*
Self-explanatory.
*More than one fix poems*
It is not efficient to use fix poems more than once.
@ -557,21 +450,12 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
*Pair COMB charge %.10f with force %.10f hit min barrier*
Something is possibly wrong with your model.
*Pair brownian needs newton pair on for momentum conservation*
Self-explanatory.
*Pair dpd needs newton pair on for momentum conservation*
Self-explanatory.
*Pair dsmc: num_of_collisions > number_of_A*
Collision model in DSMC is breaking down.
*Pair dsmc: num_of_collisions > number_of_B*
Collision model in DSMC is breaking down.
*Pair style in data file differs from currently defined pair style*
Self-explanatory.
*Pair style restartinfo set but has no restart support*
This pair style has a bug, where it does not support reading and
writing information to a restart file, but does not set the member
@ -681,9 +565,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
cluster specified by the fix shake command is numerically suspect. LAMMPS
will set it to 0.0 and continue.
*Shell command '%s' failed with error '%s'*
Self-explanatory.
*Shell command returned with non-zero status*
This may indicate the shell command did not operate as expected.
@ -694,15 +575,9 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
This will lead to invalid constraint forces in the SHAKE/RATTLE
computation.
*Simulations might be very slow because of large number of structure factors*
Self-explanatory.
*Slab correction not needed for MSM*
Slab correction is intended to be used with Ewald or PPPM and is not needed by MSM.
*Specifying an 'subset' value of '0' is equivalent to no 'subset' keyword*
Self-explanatory.
*System is not charge neutral, net charge = %g*
The total charge on all atoms on the system is not 0.0.
For some KSpace solvers this is only a warning.
@ -734,9 +609,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
assumed to also be for all atoms. Thus the pressure printed by thermo
could be inaccurate.
*The fix ave/spatial command has been replaced by the more flexible fix ave/chunk and compute chunk/atom commands -- fix ave/spatial will be removed in the summer of 2015*
Self-explanatory.
*The minimizer does not re-orient dipoles when using fix efield*
This means that only the atom coordinates will be minimized,
not the orientation of the dipoles.
@ -745,9 +617,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
More than the maximum # of neighbors was found multiple times. This
was unexpected.
*Too many inner timesteps in fix ttm*
Self-explanatory.
*Too many neighbors in CNA for %d atoms*
More than the maximum # of neighbors was found multiple times. This
was unexpected.
@ -775,24 +644,6 @@ Doc page with :doc:`ERROR messages <Errors_messages>`
The deformation will heat the SRD particles so this can
be dangerous.
*Using kspace solver on system with no charge*
Self-explanatory.
*Using largest cut-off for lj/long/dipole/long long long*
Self-explanatory.
*Using largest cutoff for buck/long/coul/long*
Self-explanatory.
*Using largest cutoff for lj/long/coul/long*
Self-explanatory.
*Using largest cutoff for pair_style lj/long/tip4p/long*
Self-explanatory.
*Using package gpu without any pair style defined*
Self-explanatory.
*Using pair potential shift with pair_modify compute no*
The shift effects will thus not be computed.

2
doc/src/Examples.rst
View File

@ -54,7 +54,7 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| body | body particles, 2d system |
+-------------+------------------------------------------------------------------+
| bpm | BPM simulations of pouring elastic grains and plate impact |
| bpm | simulations of solid elastic/plastic deformation and fracture |
+-------------+------------------------------------------------------------------+
| cmap | CMAP 5-body contributions to CHARMM force field |
+-------------+------------------------------------------------------------------+

3
doc/src/Fortran.rst
View File

@ -2773,8 +2773,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
END SUBROUTINE external_callback
END INTERFACE
where ``c_bigint`` is ``c_int`` if ``-DLAMMPS_SMALLSMALL`` was used and
``c_int64_t`` otherwise; and ``c_tagint`` is ``c_int64_t`` if
where ``c_bigint`` is ``c_int64_t`` and ``c_tagint`` is ``c_int64_t`` if
``-DLAMMPS_BIGBIG`` was used and ``c_int`` otherwise.
The argument *caller* to :f:subr:`set_fix_external_callback` is unlimited

1
doc/src/Howto.rst
View File

@ -40,6 +40,7 @@ Settings howto
Howto_walls
Howto_nemd
Howto_dispersion
Howto_bulk2slab
Analysis howto
==============

6
doc/src/Howto_bpm.rst
View File

@ -42,12 +42,14 @@ such as those created by pouring grains using :doc:`fix pour
----------
Currently, there are two types of bonds included in the BPM package. The
Currently, there are three types of bonds included in the BPM package. The
first bond style, :doc:`bond bpm/spring <bond_bpm_spring>`, only applies
pairwise, central body forces. Point particles must have :doc:`bond atom
style <atom_style>` and may be thought of as nodes in a spring
network. An optional multibody term can be used to adjust the network's
Poisson's ratio. Alternatively, the second bond style, :doc:`bond bpm/rotational
Poisson's ratio. The :doc:`bpm/spring/plastic <bond_bpm_spring_plastic>`
bond style is similar except it adds a plastic yield strain.
Alternatively, the third bond style, :doc:`bond bpm/rotational
<bond_bpm_rotational>`, resolves tangential forces and torques arising
with the shearing, bending, and twisting of the bond due to rotation or
displacement of particles. Particles are similar to those used in the

160
doc/src/Howto_bulk2slab.rst Normal file
View File

@ -0,0 +1,160 @@
===========================
Convert bulk system to slab
===========================
A regularly encountered simulation problem is how to convert a bulk
system that has been run for a while to equilibrate into a slab system
with some vacuum space and free surfaces. The challenge here is that
one cannot just change the box dimensions with the :doc:`change_box
command <change_box>` or edit the box boundaries in a data file because
some atoms will have non-zero image flags from diffusing around.
Changing the box dimensions results in an undesired displacement of
those atoms, since the image flags indicate how many times the box
length in x-, y-, or z-direction needs to be added or subtracted to get
the "unwrapped" coordinates. By changing the box dimension this
distance is changed and thus those atoms move unphysically relative to
their neighbors with zero image flags. Setting image flags forcibly to
zero creates problems because that could break apart molecules by having
one atom of a bond on the top of the system and the other at the bottom.
.. _bulk2slab:
.. figure:: JPG/rhodo-both.jpg
:figwidth: 80%
:figclass: align-center
Snapshots of the bulk Rhodopsin in lipid layer and water system (right)
and the generated slab geometry (left)
.. admonition:: Disclaimer
:class: note
The following workflow will work for many bulk systems, but not all.
Some systems cannot be converted (e.g. polymers with bonds to the
same molecule across periodic boundaries, sometimes called "infinite
polymers"). The amount of vacuum that needs to be added depends on
the length of the molecules where the system is split (the example
here splits where there is water with short molecules). In some
cases, the system may need to be re-centered in the box first using
the :doc:`displace_atoms command <displace_atoms>`. Also, the time
spent on strong thermalization and equilibration will depend on the
specific system and its thermodynamic conditions.
Below is a suggested workflow using the :doc:`Rhodopsin benchmark input
<Speed_bench>` for demonstration. The figure shows the state *before*
the procedure on the left (with unwrapped atoms that have diffused out
of the box) and *after* on the right (with the vacuum added above and
below). The procedure is implemented by modifying a copy of the
``in.rhodo`` input file. The first lines up to and including the
:doc:`read_data command <read_data>` remain unchanged. Then we insert
the following lines to add vacuum to the z direction above and below the
system:
.. code-block:: LAMMPS
variable delta index 10.0
reset_atoms image all
write_dump all custom rhodo-unwrap.lammpstrj id xu yu zu
change_box all z final $(zlo-2.0*v_delta) $(zhi+2.0*v_delta) &
boundary p p f
read_dump rhodo-unwrap.lammpstrj 0 x y z box no replace yes
kspace_modify slab 3.0
Specifically, the :doc:`variable delta <variable>` (set to 10.0)
represents a distance that determines the amount of vacuum added: we add
twice its value in each direction to the z-dimension; thus in total
:math:`40 \AA` get added. The :doc:`reset_atoms image all
<reset_atoms>` command shall reset any image flags to become either 0 or
:math:`\pm 1` and thus have the minimum distance from the center of the
simulation box, but the correct relative distance for bonded atoms.
The :doc:`write_dump command <write_dump>` then writes out the resulting
*unwrapped* coordinates of the system. After expanding the box,
coordinates that were outside the box should now be inside and the
unwrapped coordinates will become "wrapped", while atoms outside the
periodic boundaries will be wrapped back into the box and their image
flags in those directions restored.
The :doc:`change_box command <change_box>` adds the desired
distance to the low and high box boundary in z-direction and then changes
the :doc:`boundary to "p p f" <boundary>` which will force the image
flags in z-direction to zero and create an undesired displacement for
the atoms with non-zero image flags.
With the :doc:`read_dump command <read_dump>` we read back and replace
partially incorrect coordinates with the previously saved, unwrapped
coordinates. It is important to ignore the box dimensions stored in the
dump file. We want to preserve the expanded box. Finally, we turn on
the slab correction for the PPPM long-range solver with the
:doc:`kspace_modify command <kspace_modify>` as required when using a
long range Coulomb solver for non-periodic z-dimension.
Next we replace the :doc:`fix npt command <fix_nh>` with:
.. code-block:: LAMMPS
fix 2 nvt temp 300.0 300.0 10.0
We now have an open system and thus the adjustment of the cell in
z-direction is no longer required. Since splitting the bulk water
region where the vacuum is inserted, creates surface atoms with high
potential energy, we reduce the thermostat time constant from 100.0 to
10.0 to remove excess kinetic energy resulting from that change faster.
Also the high potential energy of the surface atoms can cause that some
of them are ejected from the slab. In order to suppress that, we add
soft harmonic walls to push back any atoms that want to leave the slab.
To determine the position of the wall, we first need to to determine the
extent of the atoms in z-direction and then place the harmonic walls
based on that information:
.. code-block:: LAMMPS
compute zmin all reduce min z
compute zmax all reduce max z
thermo_style custom zlo c_zmin zhi c_zmax
run 0 post no
fix 3 all wall/harmonic zhi $(c_zmax+v_delta) 10.0 0.0 ${delta} &
zlo $(c_zmin-v_delta) 10.0 0.0 ${delta}
The two :doc:`compute reduce <compute_reduce>` command determine the
minimum and maximum z-coordinate across all atoms. In order to trigger
the execution of the compute commands we need to "consume" them. This
is done with the :doc:`thermo_style custom <thermo_style>` command
followed by the :doc:`run 0 <run>` command. This avoids and error
accessing the min/max values determined by the compute commands to
compute the location of the wall in lower and upper direction. This
uses the previously defined *delta* variable to determine the distance
of the wall from the extent of the system and the cutoff for the wall
interaction. This way only atoms that move beyond the min/max values in
z-direction will experience a restoring force, nudging them back to the
slab. The force constant of :math:`10.0 \frac{\mathrm{kcal/mol}}{\AA}`
was determined empirically.
Adding these "restoring" soft walls assist in making the free surfaces
above and below the slab flat, instead of having rugged or ondulated
surfaces. The impact of the walls can be changed by adjusting the force
constant, cutoff, and position of the wall.
Finally, we replace the :doc:`run 100 <run>` of the original input with:
.. code-block:: LAMMPS
run 1000 post no
unfix 3
fix 2 all nvt temp 300.0 300.0 100.0
run 1000 post no
write_data data.rhodo-slab
This runs the system converted to a slab first for 1000 MD steps using
the walls and stronger Nose-Hoover thermostat. Then the walls are
removed with :doc:`unfix 3 <unfix>` and the thermostat time constant
reset to 100.0 and the system run for another 1000 steps. Finally the
resulting slab geometry is written to a new data file
``data.rhodo-slab`` with a :doc:`write_data command <write_data>`. The
number of MD steps required to reach a proper equilibrium state is very
likely larger. The number of 1000 steps (corresponding to 2
picoseconds) was chosen for demonstration purposes, so that the
procedure can be easily and quickly tested.

6
doc/src/Howto_github.rst
View File

@ -487,10 +487,10 @@ updates are back-ported from the *develop* branch to the *maintenance*
branch and occasionally merged to *stable* as an update release.
Furthermore, the naming of the release tags now follow the pattern
"patch_<Day><Month><Year>" to simplify comparisons between releases.
For stable releases additional "stable_<Day><Month><Year>" tags are
"patch\_<Day><Month><Year>" to simplify comparisons between releases.
For stable releases additional "stable\_<Day><Month><Year>" tags are
applied and update releases are tagged with
"stable_<Day><Month><Year>_update<Number>", Finally, all releases and
"stable\_<Day><Month><Year>\_update<Number>", Finally, all releases and
submissions are subject to automatic testing and code checks to make
sure they compile with a variety of compilers and popular operating
systems. Some unit and regression testing is applied as well.

38
doc/src/Howto_lammps_gui.rst
View File

@ -21,10 +21,11 @@ to the online LAMMPS documentation for known LAMMPS commands and styles.
Sur or later), and Windows (version 10 or later) :ref:`are available
<lammps_gui_install>` for download. Non-MPI LAMMPS executables (as
``lmp``) for running LAMMPS from the command-line and :doc:`some
LAMMPS tools <Tools>` compiled executables are also included.
Also, the pre-compiled LAMMPS-GUI packages include the WHAM executables
LAMMPS tools <Tools>` compiled executables are also included. Also,
the pre-compiled LAMMPS-GUI packages include the WHAM executables
from http://membrane.urmc.rochester.edu/content/wham/ for use with
LAMMPS tutorials.
LAMMPS tutorials documented in this paper (:ref:`Gravelle1
<Gravelle1>`).
The source code for LAMMPS-GUI is included in the LAMMPS source code
distribution and can be found in the ``tools/lammps-gui`` folder. It
@ -720,6 +721,19 @@ output, charts, slide show, variables, or snapshot images. The
default settings for their visibility can be changed in the
*Preferences* dialog.
Tutorials
^^^^^^^^^
The *Tutorials* menu is to support the set of LAMMPS tutorials for
beginners and intermediate LAMMPS users documented in (:ref:`Gravelle1
<Gravelle1>`). From the drop down menu you can select which of the eight
currently available tutorial sessions you want to start and then will be
taken to a 'wizard' dialog where you can choose in which folder you want
to work, whether you want that folder to be cleared, and also whether
you want to download the solutions files (can be large). The dialog
will then start downloading the files requested and load the first input
file for the selected session into LAMMPS-GUI.
About
^^^^^
@ -848,6 +862,11 @@ General Settings:
the plots in the *Charts* window in milliseconds. The default is to
redraw the plots every 500 milliseconds. This is just for the drawing,
data collection is managed with the previous setting.
- *HTTPS proxy setting:* Allows to enter a URL for an HTTPS proxy. This
may be needed when the LAMMPS input contains :doc:`geturl commands <geturl>`
or for downloading tutorial files from the *Tutorials* menu. If the
``https_proxy`` environment variable was set externally, its value is
displayed but cannot be changed.
Accelerators:
^^^^^^^^^^^^^
@ -976,10 +995,21 @@ available (On macOS use the Command key instead of Ctrl/Control).
- Ctrl+Shift+T
- LAMMPS Tutorial
Further editing keybindings `are documented with the Qt documentation
Further keybindings of the editor window `are documented with the Qt
documentation
<https://doc.qt.io/qt-5/qplaintextedit.html#editing-key-bindings>`_. In
case of conflicts the list above takes precedence.
All other windows only support a subset of keyboard shortcuts listed
above. Typically, the shortcuts `Ctrl-/` (Stop Run), `Ctrl-W` (Close
Window), and `Ctrl-Q` (Quit Application) are supported.
-------------
.. _Gravelle1:
**(Gravelle1)** Gravelle, Gissinger, Kohlmeyer, `arXiv:2503.14020 \[physics.comp-ph\] <https://doi.org/10.48550/arXiv.2503.14020>`_ (2025)
.. _Gravelle2:
**(Gravelle2)** Gravelle https://lammpstutorials.github.io/

272
doc/src/Howto_moltemplate.rst
View File

@ -2,14 +2,18 @@ Moltemplate Tutorial
====================
In this tutorial, we are going to use the tool :ref:`Moltemplate
<moltemplate>` to set up a classical molecular dynamic simulation using
the :ref:`OPLS-AA force field <OPLSAA96>`. The first
task is to describe an organic compound and create a complete input deck
for LAMMPS. The second task is to map the OPLS-AA force field to a
molecular sample created with an external tool, e.g. PACKMOL, and
exported as a PDB file. The files used in this tutorial can be found
in the ``tools/moltemplate/tutorial-files`` folder of the LAMMPS
source code distribution.
<Moltemplate1>` from https://moltemplate.org/ to set up a classical
molecular dynamic simulation using the :ref:`OPLS-AA force field
<oplsaa2024>`. The first task is to describe an organic compound and
create a complete input deck for LAMMPS. The second task is to use
moltemplate to build a polymer. The third task is to map the OPLS-AA
force field to a molecular sample created with an external tool,
e.g. PACKMOL, and exported as a PDB file. The files used in this
tutorial can be found in the ``tools/moltemplate/tutorial-files`` folder
of the LAMMPS source code distribution.
Many more examples can be found here: https://moltemplate.org/examples.html
Simulating an organic solvent
"""""""""""""""""""""""""""""
@ -17,14 +21,13 @@ Simulating an organic solvent
This example aims to create a cubic box of the organic solvent
formamide.
The first step is to create a molecular topology in the
LAMMPS-template (LT) file format representing a single molecule, which
will be stored in a Moltemplate object called ``_FAM inherits OPLSAA {}``.
The first step is to create a molecular topology in the LAMMPS-template
(LT) file format representing a single molecule, which will be
stored in a Moltemplate object called ``_FAM inherits OPLSAA {}``.
This command states that the object ``_FAM`` is based on an existing
object called ``OPLSAA``, which contains OPLS-AA parameters, atom type
definitions, partial charges, masses and bond-angle rules for many organic
and biological compounds.
The atomic structure is the starting point to populate the command
``write('Data Atoms') {}``, which will write the ``Atoms`` section in the
LAMMPS data file. The OPLS-AA force field uses the ``atom_style full``,
@ -36,21 +39,23 @@ to the ``molID``, except that the same variable is used for the whole
molecule. The atom types are assigned using ``@``-type variables. The
assignment of atom types (e.g. ``@atom:177``, ``@atom:178``) is done using
the OPLS-AA atom types defined in the "In Charges" section of the file
``oplsaa.lt``, looking for a reasonable match with the description of the atom.
``oplsaa2024.lt``, looking for a reasonable match with the description of the atom.
The resulting file (``formamide.lt``) follows:
.. code-block:: bash
import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt # defines OPLSAA
_FAM inherits OPLSAA {
# atomID molID atomType charge coordX coordY coordZ
write('Data Atoms') {
$atom:C00 $mol @atom:177 0.00 0.100 0.490 0.0
$atom:O01 $mol @atom:178 0.00 1.091 -0.250 0.0
$atom:N02 $mol @atom:179 0.00 -1.121 -0.181 0.0
$atom:H03 $mol @atom:182 0.00 -2.013 0.272 0.0
$atom:H04 $mol @atom:182 0.00 -1.056 -1.190 0.0
$atom:H05 $mol @atom:221 0.00 0.144 1.570 0.0
$atom:C00 $mol @atom:235 0.00 0.100 0.490 0.0
$atom:O01 $mol @atom:236 0.00 1.091 -0.250 0.0
$atom:N02 $mol @atom:237 0.00 -1.121 -0.181 0.0
$atom:H03 $mol @atom:240 0.00 -2.013 0.272 0.0
$atom:H04 $mol @atom:240 0.00 -1.056 -1.190 0.0
$atom:H05 $mol @atom:279 0.00 0.144 1.570 0.0
}
# A list of the bonds in the molecule:
@ -64,16 +69,17 @@ The resulting file (``formamide.lt``) follows:
}
}
You don't have to specify the charge in this example because they will
be assigned according to the atom type. Analogously, only a
"Data Bond List" section is needed as the atom type will determine the
bond type. The other bonded interactions (e.g. angles,
dihedrals, and impropers) will be automatically generated by
You don't have to specify the charge in this example because the OPLSAA
force-field assigns charge according to the atom type. (This is not true
when using other force fields.) A "Data Bond List" section is needed as
the atom type will determine the bond type. The other bonded interactions
(e.g. angles, dihedrals, and impropers) will be automatically generated by
Moltemplate.
If the simulation is non-neutral, or Moltemplate complains that you have
missing bond, angle, or dihedral types, this means at least one of your
atom types is incorrect.
If the simulation is not charge-neutral, or Moltemplate complains that
you have missing bond, angle, or dihedral types, this probably means that
at least one of your atom types is incorrect (or that perhaps there is no
suitable atom type currently defined in the ``oplsaa2024.lt`` file).
The second step is to create a master file with instructions to build a
starting structure and the LAMMPS commands to run an NPT simulation. The
@ -81,11 +87,9 @@ master file (``solv_01.lt``) follows:
.. code-block:: bash
# Import the force field.
import /usr/local/moltemplate/moltemplate/force_fields/oplsaa.lt
import formamide.lt # after oplsaa.lt, as it depends on it.
import formamide.lt # Defines "_FAM" and OPLSAA
# Create the input sample.
# Distribute the molecules on a 5x5x5 cubic grid with spacing 4.6
solv = new _FAM [5].move( 4.6, 0, 0)
[5].move( 0, 4.6, 0)
[5].move( 0, 0, 4.6)
@ -98,8 +102,11 @@ master file (``solv_01.lt``) follows:
-11.5 11.5 zlo zhi
}
# Create an input deck for LAMMPS.
write_once("In Init"){
# Note: The lines below in the "In Run" section are often omitted.
write_once("In Run"){
# Create an input deck for LAMMPS.
# Run an NPT simulation.
# Input variables.
variable run string solv_01 # output name
variable ts equal 1 # timestep
@ -109,12 +116,6 @@ master file (``solv_01.lt``) follows:
variable equi equal 5000 # Equilibration steps
variable prod equal 30000 # Production steps
# PBC (set them before the creation of the box).
boundary p p p
}
# Run an NPT simulation.
write_once("In Run"){
# Derived variables.
variable tcouple equal \$\{ts\}*100
variable pcouple equal \$\{ts\}*1000
@ -143,7 +144,7 @@ master file (``solv_01.lt``) follows:
unfix NPT
}
The first two commands insert the content of files ``oplsaa.lt`` and
The first two commands insert the content of files ``oplsaa2024.lt`` and
``formamide.lt`` into the master file. At this point, we can use the
command ``solv = new _FAM [N]`` to create N copies of a molecule of type
``_FAM``. In this case, we create an array of 5*5*5 molecules on a cubic
@ -153,21 +154,37 @@ the sample was created from scratch, we also specify the simulation box
size in the "Data Boundary" section.
The LAMMPS setting for the force field are specified in the file
``oplsaa.lt`` and are written automatically in the input deck. We also
``oplsaa2024.lt`` and are written automatically in the input deck. We also
specify the boundary conditions and a set of variables in
the "In Init" section. The remaining commands to run an NPT simulation
the "In Init" section.
The remaining commands to run an NPT simulation
are written in the "In Run" section. Note that in this script, LAMMPS
variables are protected with the escape character ``\`` to distinguish
them from Moltemplate variables, e.g. ``\$\{run\}`` is a LAMMPS
variable that is written in the input deck as ``${run}``.
(Note: Moltemplate can be slow to run, so you need to change you run
settings frequently, I recommended moving those commands (from "In Run")
out of your .lt files and into a separate file. Moltemplate creates a
file named ``run.in.EXAMPLE`` for this purpose. You can put your run
settings and fixes that file and then invoke LAMMPS using
``mpirun -np 4 lmp -in run.in.EXAMPLE`` instead.)
Compile the master file with:
.. code-block:: bash
moltemplate.sh -overlay-all solv_01.lt
moltemplate.sh solv_01.lt
cleanup_moltemplate.sh # <-- optional: see below
And execute the simulation with the following:
(Note: The optional "cleanup_moltemplate.sh" command deletes
unused atom types, which sometimes makes LAMMPS run faster.
But it does not work with many-body pair styles or dreiding-style h-bonds.
Fortunately most force fields, including OPLSAA, don't use those features.)
Then execute the simulation with the following:
.. code-block:: bash
@ -180,15 +197,116 @@ And execute the simulation with the following:
Snapshot of the sample at the beginning and end of the simulation.
Rendered with Ovito.
Building a simple polymer
"""""""""""""""""""""""""
Moltemplate is particularly useful for building polymers (and other molecules
with sub-units). As an simple example, consider butane:
.. figure:: JPG/butane.jpg
The ``butane.lt`` file below defines Butane as a polymer containing
4 monomers (of type ``CH3``, ``CH2``, ``CH2``, ``CH3``).
.. code-block:: bash
import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt # defines OPLSAA
CH3 inherits OPLSAA {
# atomID molID atomType charge coordX coordY coordZ
write("Data Atoms") {
$atom:c $mol:... @atom:54 0.0 0.000000 0.4431163 0.000000
$atom:h1 $mol:... @atom:60 0.0 0.000000 1.0741603 0.892431
$atom:h2 $mol:... @atom:60 0.0 0.000000 1.0741603 -0.892431
$atom:h3 $mol:... @atom:60 0.0 -0.892431 -0.1879277 0.000000
}
# (Using "$mol:..." indicates this object ("CH3") is part of a larger
# molecule. Moltemplate will share the molecule-ID with that molecule.)
# A list of the bonds within the "CH3" molecular sub-unit:
# BondID AtomID1 AtomID2
write('Data Bond List') {
$bond:ch1 $atom:c $atom:h1
$bond:ch2 $atom:c $atom:h2
$bond:ch3 $atom:c $atom:h3
}
}
CH2 inherits OPLSAA {
# atomID molID atomType charge coordX coordY coordZ
write("Data Atoms") {
$atom:c $mol:... @atom:57 0.0 0.000000 0.4431163 0.000000
$atom:h1 $mol:... @atom:60 0.0 0.000000 1.0741603 0.892431
$atom:h2 $mol:... @atom:60 0.0 0.000000 1.0741603 -0.892431
}
# A list of the bonds within the "CH2" molecular sub-unit:
# BondID AtomID1 AtomID2
write('Data Bond List') {
$bond:ch1 $atom:c $atom:h1
$bond:ch2 $atom:c $atom:h2
}
}
Butane inherits OPLSAA {
create_var {$mol} # optional:force all monomers to share the same molecule-ID
# - Create 4 monomers
# - Move them along the X axis using ".move()",
# - Rotate them 180 degrees with respect to the previous monomer
monomer1 = new CH3
monomer2 = new CH2.rot(180,1,0,0).move(1.2533223,0,0)
monomer3 = new CH2.move(2.5066446,0,0)
monomer4 = new CH3.rot(180,0,0,1).move(3.7599669,0,0)
# A list of the bonds connecting different monomers together:
write('Data Bond List') {
$bond:b1 $atom:monomer1/c $atom:monomer2/c
$bond:b2 $atom:monomer2/c $atom:monomer3/c
$bond:b3 $atom:monomer3/c $atom:monomer4/c
}
}
Again, you don't have to specify the charge in this example because OPLSAA
assigns charges according to the atom type.
This ``Butane`` object is a molecule which can be used anywhere other molecules
can be used. (You can arrange ``Butane`` molecules on a lattice, as we did previously.
You can also modify individual butane molecules by adding or deleting atoms or bonds.
You can add bonds between specific butane molecules or use ``Butane`` as a
sub-unit to define even larger molecules. See the moltemplate manual for details.)
How to build a complex polymer
""""""""""""""""""""""""""""""""""""""""""
A similar procedure can be used to create more complicated polymers,
such as the NIPAM polymer example shown below. For details, see:
https://github.com/jewettaij/moltemplate/tree/master/examples/all_atom/force_field_OPLSAA/NIPAM_polymer+water+ions
Mapping an existing structure
"""""""""""""""""""""""""""""
Another helpful way to use Moltemplate is mapping an existing molecular
sample to a force field. This is useful when a complex sample is
assembled from different simulations or created with specialized
software (e.g. PACKMOL). As in the previous example, all molecular
species in the sample must be defined using single-molecule Moltemplate
objects. For this example, we use a short polymer in a box containing
sample to a force field. This is useful when a complex sample is assembled
from different simulations or created with specialized software (e.g. PACKMOL).
(Note: The previous link shows how to build this entire system from scratch
using only moltemplate. However here we will assume instead that we obtained
a PDB file for this system using PACKMOL.)
As in the previous examples, all molecular species in the sample
are defined using single-molecule Moltemplate objects.
For this example, we use a short polymer in a box containing
water molecules and ions in the PDB file ``model.pdb``.
It is essential to understand that the order of atoms in the PDB file
@ -246,25 +364,25 @@ The resulting master LT file defining short annealing at a fixed volume
.. code-block:: bash
# Use the OPLS-AA force field for all species.
import /usr/local/moltemplate/moltemplate/force_fields/oplsaa.lt
import /usr/local/moltemplate/moltemplate/force_fields/oplsaa2024.lt
import PolyNIPAM.lt
# Define the SPC water and ions as in the OPLS-AA
Ca inherits OPLSAA {
write("Data Atoms"){
$atom:a1 $mol:. @atom:354 0.0 0.00000 0.00000 0.000000
$atom:a1 $mol:. @atom:412 0.0 0.00000 0.00000 0.000000
}
}
Cl inherits OPLSAA {
write("Data Atoms"){
$atom:a1 $mol:. @atom:344 0.0 0.00000 0.00000 0.000000
$atom:a1 $mol:. @atom:401 0.0 0.00000 0.00000 0.000000
}
}
SPC inherits OPLSAA {
write("Data Atoms"){
$atom:O $mol:. @atom:76 0. 0.0000000 0.00000 0.000000
$atom:H1 $mol:. @atom:77 0. 0.8164904 0.00000 0.5773590
$atom:H2 $mol:. @atom:77 0. -0.8164904 0.00000 0.5773590
$atom:O $mol:. @atom:9991 0. 0.0000000 0.00000 0.0000000
$atom:H1 $mol:. @atom:9990 0. 0.8164904 0.00000 0.5773590
$atom:H2 $mol:. @atom:9990 0. -0.8164904 0.00000 0.5773590
}
write("Data Bond List") {
$bond:OH1 $atom:O $atom:H1
@ -285,8 +403,15 @@ The resulting master LT file defining short annealing at a fixed volume
0 26 zlo zhi
}
# Define the input variables.
write_once("In Init"){
boundary p p p # "p p p" is the default. This line is optional.
neighbor 3 bin # (This line is also optional in this example.)
}
# Note: The lines below in the "In Run" section are often omitted.
# Run an NVT simulation.
write_once("In Run"){
# Input variables.
variable run string sample01 # output name
variable ts equal 2 # timestep
@ -294,13 +419,6 @@ The resulting master LT file defining short annealing at a fixed volume
variable p equal 1. # equilibrium pressure
variable equi equal 30000 # equilibration steps
# PBC (set them before the creation of the box).
boundary p p p
neighbor 3 bin
}
# Run an NVT simulation.
write_once("In Run"){
# Set the output.
thermo 1000
thermo_style custom step etotal evdwl ecoul elong ebond eangle &
@ -314,8 +432,8 @@ The resulting master LT file defining short annealing at a fixed volume
write_data \$\{run\}.min
# Set the constrains.
group watergroup type @atom:76 @atom:77
fix 0 watergroup shake 0.0001 10 0 b @bond:042_043 a @angle:043_042_043
group watergroup type @atom:9991 @atom:9990
fix 0 watergroup shake 0.0001 10 0 b @bond:spcO_spcH a @angle:spcH_spcO_spcH
# Short annealing.
timestep \$\{ts\}
@ -327,7 +445,7 @@ The resulting master LT file defining short annealing at a fixed volume
In this example, the water model is SPC and it is defined in the
``oplsaa.lt`` file with atom types ``@atom:76`` and ``@atom:77``. For
``oplsaa2024.lt`` file with atom types ``@atom:9991`` and ``@atom:9990``. For
water we also use the ``group`` and ``fix shake`` commands with
Moltemplate ``@``-type variables, to ensure consistency with the
numerical values assigned during compilation. To identify the bond and
@ -336,19 +454,20 @@ are:
.. code-block:: bash
replace{ @atom:76 @atom:76_b042_a042_d042_i042 }
replace{ @atom:77 @atom:77_b043_a043_d043_i043 }
replace{ @atom:9991 @atom:9991_bspcO_aspcO_dspcO_ispcO }
replace{ @atom:9990 @atom:9990_bspcH_aspcH_dspcH_ispcH }
From which we can identify the following "Data Bonds By Type":
``@bond:042_043 @atom:*_b042*_a*_d*_i* @atom:*_b043*_a*_d*_i*`` and
"Data Angles By Type": ``@angle:043_042_043 @atom:*_b*_a043*_d*_i*
@atom:*_b*_a042*_d*_i* @atom:*_b*_a043*_d*_i*``
``@bond:spcO_spcH @atom:*_bspcO*_a*_d*_i* @atom:*_bspcH*_a*_d*_i*``
and "Data Angles By Type":
``@angle:spcH_spcO_spcH @atom:*_b*_aspcH*_d*_i* @atom:*_b*_aspcO*_d*_i* @atom:*_b*_aspcH*_d*_i*``
Compile the master file with:
.. code-block:: bash
moltemplate.sh -overlay-all -pdb model.pdb sample01.lt
moltemplate.sh -pdb model.pdb sample01.lt
cleanup_moltemplate.sh
And execute the simulation with the following:
@ -363,8 +482,13 @@ And execute the simulation with the following:
Sample visualized with Ovito loading the trajectory into the DATA
file written after minimization.
------------
.. _OPLSAA96:
.. _oplsaa2024:
**(OPLS-AA)** Jorgensen, Maxwell, Tirado-Rives, J Am Chem Soc, 118(45), 11225-11236 (1996).
**(OPLS-AA)** Jorgensen, W.L., Ghahremanpour, M.M., Saar, A., Tirado-Rives, J., J. Phys. Chem. B, 128(1), 250-262 (2024).
.. _Moltemplate1:
**(Moltemplate)** Jewett et al., J. Mol. Biol., 433(11), 166841 (2021)

8
doc/src/Howto_peri.rst
View File

@ -197,7 +197,7 @@ The LPS model has a force scalar state
.. math::
\underline{t} = \frac{3K\theta}{m}\underline{\omega}\,\underline{x} +
\alpha \underline{\omega}\,\underline{e}^{\rm d}, \qquad\qquad\textrm{(3)}
\alpha \underline{\omega}\,\underline{e}^\mathrm{d}, \qquad\qquad\textrm{(3)}
with :math:`K` the bulk modulus and :math:`\alpha` related to the shear
modulus :math:`G` as
@ -242,14 +242,14 @@ scalar state are defined, respectively, as
.. math::
\underline{e}^{\rm i}=\frac{\theta \underline{x}}{3}, \qquad
\underline{e}^{\rm d} = \underline{e}- \underline{e}^{\rm i},
\underline{e}^\mathrm{i}=\frac{\theta \underline{x}}{3}, \qquad
\underline{e}^\mathrm{d} = \underline{e}- \underline{e}^\mathrm{i},
where the arguments of the state functions and the vectors on which they
operate are omitted for simplicity. We note that the LPS model is linear
in the dilatation :math:`\theta`, and in the deviatoric part of the
extension :math:`\underline{e}^{\rm d}`.
extension :math:`\underline{e}^\mathrm{d}`.
.. note::

31
doc/src/Howto_python.rst
View File

@ -62,17 +62,17 @@ with :ref:`PNG, JPEG and FFMPEG output support <graphics>` enabled.
cd $LAMMPS_DIR/src
# add packages if necessary
# add LAMMPS packages if necessary
make yes-MOLECULE
make yes-PYTHON
# compile shared library using Makefile
make mpi mode=shlib LMP_INC="-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG" JPG_LIB="-lpng -ljpeg"
Step 2: Installing the LAMMPS Python package
""""""""""""""""""""""""""""""""""""""""""""
Step 2: Installing the LAMMPS Python module
"""""""""""""""""""""""""""""""""""""""""""
Next install the LAMMPS Python package into your current Python installation with:
Next install the LAMMPS Python module into your current Python installation with:
.. code-block:: bash
@ -89,6 +89,29 @@ privileges) or into your personal Python module folder.
Recompiling the shared library requires re-installing the Python
package.
.. _externally_managed:
.. admonition:: Handling an "externally-managed-environment" Error
:class: Hint
Some Python installations made through Linux distributions
(e.g. Ubuntu 24.04LTS or later) will prevent installing the LAMMPS
Python module into a system folder or a corresponding folder of the
individual user as attempted by ``make install-python`` with an error
stating that an *externally managed* python installation must be only
managed by the same package package management tool. This is an
optional setting, so not all Linux distributions follow it currently
(Spring 2025). The reasoning and explanations for this error can be
found in the `Python Packaging User Guide
<https://packaging.python.org/en/latest/specifications/externally-managed-environments/>`_
These guidelines suggest to create a virtual environment and install
the LAMMPS Python module there (see below). This is generally a good
idea and the LAMMPS developers recommend this, too. If, however, you
want to proceed and install the LAMMPS Python module regardless, you
can install the "wheel" file (see above) manually with the ``pip``
command by adding the ``--break-system-packages`` flag.
Installation inside of a virtual environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

24
doc/src/Howto_triclinic.rst
View File

@ -249,23 +249,23 @@ as follows:
.. math::
a = & {\rm lx} \\
b^2 = & {\rm ly}^2 + {\rm xy}^2 \\
c^2 = & {\rm lz}^2 + {\rm xz}^2 + {\rm yz}^2 \\
\cos{\alpha} = & \frac{{\rm xy}*{\rm xz} + {\rm ly}*{\rm yz}}{b*c} \\
\cos{\beta} = & \frac{\rm xz}{c} \\
\cos{\gamma} = & \frac{\rm xy}{b} \\
a = & \mathrm{lx} \\
b^2 = & \mathrm{ly}^2 + \mathrm{xy}^2 \\
c^2 = & \mathrm{lz}^2 + \mathrm{xz}^2 + \mathrm{yz}^2 \\
\cos{\alpha} = & \frac{\mathrm{xy}*\mathrm{xz} + \mathrm{ly}*\mathrm{yz}}{b*c} \\
\cos{\beta} = & \frac{\mathrm{xz}}{c} \\
\cos{\gamma} = & \frac{\mathrm{xy}}{b} \\
The inverse relationship can be written as follows:
.. math::
{\rm lx} = & a \\
{\rm xy} = & b \cos{\gamma} \\
{\rm xz} = & c \cos{\beta}\\
{\rm ly}^2 = & b^2 - {\rm xy}^2 \\
{\rm yz} = & \frac{b*c \cos{\alpha} - {\rm xy}*{\rm xz}}{\rm ly} \\
{\rm lz}^2 = & c^2 - {\rm xz}^2 - {\rm yz}^2 \\
\mathrm{lx} = & a \\
\mathrm{xy} = & b \cos{\gamma} \\
\mathrm{xz} = & c \cos{\beta}\\
\mathrm{ly}^2 = & b^2 - \mathrm{xy}^2 \\
\mathrm{yz} = & \frac{b*c \cos{\alpha} - \mathrm{xy}*\mathrm{xz}}{\mathrm{ly}} \\
\mathrm{lz}^2 = & c^2 - \mathrm{xz}^2 - \mathrm{yz}^2 \\
The values of *a*, *b*, *c*, :math:`\alpha` , :math:`\beta`, and
:math:`\gamma` can be printed out or accessed by computes using the

3
doc/src/Install_mac.rst
View File

@ -5,8 +5,7 @@ LAMMPS can be downloaded, built, and configured for macOS with `Homebrew
<homebrew_>`_. (Alternatively, see the installation instructions for
:doc:`downloading an executable via Conda <Install_conda>`.) The
following LAMMPS packages are unavailable at this time because of
additional requirements not yet met: GPU, KOKKOS, MSCG, POEMS,
VORONOI.
additional requirements not yet met: GPU, KOKKOS.
After installing Homebrew, you can install LAMMPS on your system with
the following commands:

14
doc/src/Intro_overview.rst
View File

@ -20,13 +20,21 @@ acceleration.
.. _lws: https://www.lammps.org
.. _omp: https://www.openmp.org
LAMMPS is written in C++ and requires a compiler that is at least
compatible with the C++-11 standard. Earlier versions were written in
F77, F90, and C++-98. See the `History page
LAMMPS is written in C++ and currently requires a compiler that is at
least compatible with the C++-11 standard. Earlier versions were
written in F77, F90, and C++-98. See the `History page
<https://www.lammps.org/history.html>`_ of the website for details. All
versions can be downloaded as source code from the `LAMMPS website
<lws_>`_.
Through a :ref:`C language API <lammps_c_api>` LAMMPS functionality can
be accessed and managed from other programming languages rather than
running the LAMMPS executable. Ready to use modules for :ref:`Python
<lammps_python_api>` and :ref:`Fortran <lammps_fortran_api>` exist, and
an example :ref:`SWIG interface file <swig>` as well as example C files
for dynamically loading LAMMPS as a shared library into other
executables are provided.
LAMMPS is designed to be easy to modify or extend with new capabilities,
such as new force fields, atom types, boundary conditions, or
diagnostics. See the :doc:`Modify` section of for more details.

2
doc/src/Intro_portability.rst
View File

@ -15,7 +15,7 @@ Most of the C++ code currently requires a compiler compatible with the
C++11 standard, the KOKKOS package currently requires C++17. Most of
the Python code is written to be compatible with Python 3.6 or later.
.. deprecated:: TBD
.. deprecated:: 2Apr2025
Python 2.x is no longer supported and trying to use it, e.g. for the
LAMMPS Python module should result in an error. If you come across

BIN
doc/src/JPG/PolyNIPAM.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 94 KiB

BIN
doc/src/JPG/butane.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
doc/src/JPG/rhodo-both.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 568 KiB

6
doc/src/Library_add.rst
View File

@ -19,9 +19,9 @@ there are now a few requirements for including new changes or extensions.
be added.
- New features should also be implemented and documented not just
for the C interface, but also the Python and Fortran interfaces.
- All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,
``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` as well as when
compiling with and without MPI support.
- All additions should work and be compatible with
``-DLAMMPS_BIGBIG``, ``-DLAMMPS_SMALLBIG`` as well as when compiling
with and without MPI support.
- The ``library.h`` file should be kept compatible to C code at
a level similar to C89. Its interfaces may not reference any
custom data types (e.g. ``bigint``, ``tagint``, and so on) that

6
doc/src/Library_utility.rst
View File

@ -20,6 +20,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_force_timeout`
- :cpp:func:`lammps_has_error`
- :cpp:func:`lammps_get_last_error_message`
- :cpp:func:`lammps_set_show_error`
- :cpp:func:`lammps_python_api_version`
The :cpp:func:`lammps_free` function is a clean-up function to free
@ -110,6 +111,11 @@ where such memory buffers were allocated that require the use of
-----------------------
.. doxygenfunction:: lammps_set_show_error
:project: progguide
-----------------------
.. doxygenfunction:: lammps_python_api_version
:project: progguide

51
doc/src/Manual_version.rst
View File

@ -2,9 +2,15 @@ What does a LAMMPS version mean
-------------------------------
The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously, and we aim to keep it working
correctly and reliably at all times. Also, several variants of static
code analysis are run regularly to maintain or improve the overall code
2014. LAMMPS is updated continuously, and with the help of extensive
automated testing (mostly applied *before* changes are included) we aim
to keep it working correctly and reliably at all times, but there also
are regular *feature releases* with new and expanded functionality, and
there are designated *stable releases* that receive updates with bug
fixes back-ported from the development branch.
In addition to automated testing, several variants of static code
analysis are run regularly to maintain or improve the overall code
quality, consistency, and compliance with programming standards, best
practices and style conventions. You can follow its development in a
public `git repository on GitHub <https://github.com/lammps/lammps>`_.
@ -19,17 +25,18 @@ Identifying the Version
The version date is printed to the screen and log file every time you
run LAMMPS. There also is an indication, if a LAMMPS binary was
compiled from version with modifications **after** a release.
It is also visible in the file src/version.h and in the LAMMPS directory
name created when you unpack a downloaded tarball. And it is on the
first page of the :doc:`manual <Manual>`.
compiled from version with modifications **after** a release, either
from the development version or the maintenance version of the last
stable release. It is also visible in the file src/version.h and in the
LAMMPS directory name created when you unpack a downloaded tarball. And
it is on the first page of the :doc:`manual <Manual>`.
* If you browse the HTML pages of the online version of the LAMMPS
manual, they will by default describe the most current feature release
version of LAMMPS. In the navigation bar on the bottom left, there is
the option to view instead the documentation for the most recent
*stable* version or the documentation corresponding to the state of
the development branch.
the development branch *develop*.
* If you browse the HTML pages included in your downloaded tarball, they
describe the version you have, which may be older than the online
version.
@ -48,8 +55,9 @@ Development
Modifications of the LAMMPS source code (like bug fixes, code
refactoring, updates to existing features, or addition of new features)
are organized into pull requests. Pull requests will be merged into the
*develop* branch of the git repository after they pass automated testing
and code review by the LAMMPS developers.
*develop* branch of the LAMMPS git repository on GitHub after they pass
automated testing and code review by :doc:`core LAMMPS developers
<Intro_authors>`.
Feature Releases
""""""""""""""""
@ -62,8 +70,7 @@ repository is updated with every such *feature release* and a tag in the
format ``patch_1May2014`` is added. A summary of the most important
changes of these releases for the current year are posted on `this
website page <https://www.lammps.org/bug.html>`_. More detailed release
notes are `available on GitHub
<https://github.com/lammps/lammps/releases/>`_.
notes are `available on GitHub <https://github.com/lammps/lammps/releases/>`_.
Stable Releases
"""""""""""""""
@ -71,18 +78,18 @@ Stable Releases
About once a year, we release a *stable release* version of LAMMPS.
This is done after a "stabilization period" where we apply only bug
fixes and small, non-intrusive changes to the *develop* branch but no
new features. At the same time, the code is subjected to more detailed
and thorough manual testing than the default automated testing.
After such a *stable release*, both the *release* and the *stable*
branches are updated and two tags are applied, a ``patch_1May2014`` format
and a ``stable_1May2014`` format tag.
new features to the core code. At the same time, the code is subjected
to more detailed and thorough manual testing than the default automated
testing. After such a *stable release*, both the *release* and the
*stable* branches are updated and two tags are applied, a
``patch_1May2014`` format and a ``stable_1May2014`` format tag.
Stable Release Updates
""""""""""""""""""""""
Between *stable releases*, we collect bug fixes and updates back-ported
from the *develop* branch in a branch called *maintenance*. From the
*maintenance* branch we make occasional *stable update releases* and
update the *stable* branch accordingly. The first update to the
``stable_1May2014`` release would be tagged as
Between *stable releases*, we collect bug fixes and updates that are
back-ported from the *develop* branch in a branch called *maintenance*.
From the *maintenance* branch we make occasional *stable update
releases* and update the *stable* branch accordingly. The first update
to the ``stable_1May2014`` release would be tagged as
``stable_1May2014_update1``. These updates contain no new features.

35
doc/src/Modify_compute.rst
View File

@ -1,19 +1,21 @@
Compute styles
==============
Classes that compute scalar and vector quantities like temperature
and the pressure tensor, as well as classes that compute per-atom
quantities like kinetic energy and the centro-symmetry parameter
are derived from the Compute class. New styles can be created
to add new calculations to LAMMPS.
Classes that compute scalar and vector quantities like temperature and
the pressure tensor, as well as classes that compute per-atom quantities
like kinetic energy and the centro-symmetry parameter are derived from
the Compute class. New styles can be created to add new calculations to
LAMMPS.
Compute_temp.cpp is a simple example of computing a scalar
temperature. Compute_ke_atom.cpp is a simple example of computing
per-atom kinetic energy.
The ``src/compute_temp.cpp`` file is a simple example of computing a
scalar temperature. The ``src/compute_ke_atom.cpp`` file is a simple
example of computing per-atom kinetic energy.
Here is a brief description of methods you define in your new derived
class. See compute.h for details.
class. See ``src/compute.h`` for additional details.
+-----------------------+------------------------------------------------------------------+
| post_constructor | perform tasks that cannot be run in the constructor (optional) |
+-----------------------+------------------------------------------------------------------+
| init | perform one time setup (required) |
+-----------------------+------------------------------------------------------------------+
@ -50,10 +52,11 @@ class. See compute.h for details.
| memory_usage | tally memory usage (optional) |
+-----------------------+------------------------------------------------------------------+
Tally-style computes are a special case, as their computation is done
in two stages: the callback function is registered with the pair style
and then called from the Pair::ev_tally() function, which is called for
each pair after force and energy has been computed for this pair. Then
the tallied values are retrieved with the standard compute_scalar or
compute_vector or compute_peratom methods. The :doc:`compute styles in the TALLY package <compute_tally>`
provide *examples* for utilizing this mechanism.
Tally-style computes are a special case, as their computation is done in
two stages: the callback function is registered with the pair style and
then called from the Pair::ev_tally() function, which is called for each
pair after force and energy has been computed for this pair. Then the
tallied values are retrieved with the standard compute_scalar or
compute_vector or compute_peratom methods. The :doc:`compute styles in
the TALLY package <compute_tally>` provide *examples* for utilizing this
mechanism.

57
doc/src/Modify_fix.rst
View File

@ -1,23 +1,25 @@
Fix styles
==========
In LAMMPS, a "fix" is any operation that is computed during
timestepping that alters some property of the system. Essentially
everything that happens during a simulation besides force computation,
neighbor list construction, and output, is a "fix". This includes
time integration (update of coordinates and velocities), force
constraints or boundary conditions (SHAKE or walls), and diagnostics
(compute a diffusion coefficient). New styles can be created to add
new options to LAMMPS.
In LAMMPS, a "fix" is any operation that is computed during timestepping
that alters some property of the system. Essentially everything that
happens during a simulation besides force computation, neighbor list
construction, and output, is a "fix". This includes time integration
(update of coordinates and velocities), force constraints or boundary
conditions (SHAKE or walls), and diagnostics (compute a diffusion
coefficient). New styles can be created to add new options to LAMMPS.
Fix_setforce.cpp is a simple example of setting forces on atoms to
prescribed values. There are dozens of fix options already in LAMMPS;
choose one as a template that is similar to what you want to
implement.
The file ``src/fix_setforce.cpp`` is a simple example of setting forces
on atoms to prescribed values. There are dozens of fix options already
in LAMMPS; choose one as a template that is similar to what you want to
implement. There also is a detailed discussion of :doc:`how to write
new fix styles <Developer_write_fix>` in LAMMPS.
Here is a brief description of methods you can define in your new
derived class. See fix.h for details.
derived class. See ``src/fix.h`` for additional details.
+---------------------------+--------------------------------------------------------------------------------------------+
| post_constructor | perform tasks that cannot be run in the constructor (optional) |
+---------------------------+--------------------------------------------------------------------------------------------+
| setmask | determines when the fix is called during the timestep (required) |
+---------------------------+--------------------------------------------------------------------------------------------+
@ -130,10 +132,11 @@ derived class. See fix.h for details.
Typically, only a small fraction of these methods are defined for a
particular fix. Setmask is mandatory, as it determines when the fix
will be invoked during the timestep. Fixes that perform time
integration (\ *nve*, *nvt*, *npt*\ ) implement initial_integrate() and
final_integrate() to perform velocity Verlet updates. Fixes that
constrain forces implement post_force().
will be invoked during :doc:`the evolution of a timestep
<Developer_flow>`. Fixes that perform time integration (\ *nve*, *nvt*,
*npt*\ ) implement initial_integrate() and final_integrate() to perform
velocity Verlet updates. Fixes that constrain forces implement
post_force().
Fixes that perform diagnostics typically implement end_of_step(). For
an end_of_step fix, one of your fix arguments must be the variable
@ -143,13 +146,13 @@ is the first argument the fix defines (after the ID, group-ID, style).
If the fix needs to store information for each atom that persists from
timestep to timestep, it can manage that memory and migrate the info
with the atoms as they move from processors to processor by
implementing the grow_arrays, copy_arrays, pack_exchange, and
unpack_exchange methods. Similarly, the pack_restart and
unpack_restart methods can be implemented to store information about
the fix in restart files. If you wish an integrator or force
constraint fix to work with rRESPA (see the :doc:`run_style <run_style>`
command), the initial_integrate, post_force_integrate, and
final_integrate_respa methods can be implemented. The thermo method
enables a fix to contribute values to thermodynamic output, as printed
quantities and/or to be summed to the potential energy of the system.
with the atoms as they move from processors to processor by implementing
the grow_arrays, copy_arrays, pack_exchange, and unpack_exchange
methods. Similarly, the pack_restart and unpack_restart methods can be
implemented to store information about the fix in restart files. If you
wish an integrator or force constraint fix to work with rRESPA (see the
:doc:`run_style <run_style>` command), the initial_integrate,
post_force_integrate, and final_integrate_respa methods can be
implemented. The thermo method enables a fix to contribute values to
thermodynamic output, as printed quantities and/or to be summed to the
potential energy of the system.

15
doc/src/Python_install.rst
View File

@ -7,7 +7,7 @@ LAMMPS shared library through the Python `ctypes <ctypes_>`_
module. Because of the dynamic loading, it is required that LAMMPS is
compiled in :ref:`"shared" mode <exe>`.
.. versionchanged:: TBD
.. versionchanged:: 2Apr2025
LAMMPS currently only supports Python version 3.6 or later.
@ -110,13 +110,16 @@ folder that the dynamic loader searches or inside of the installed
.. code-block:: bash
python install.py -p <python package> -l <shared library> -v <version.h file> [-n]
python install.py -p <python package> -l <shared library> -v <version.h file> [-n] [-f]
* The ``-p`` flag points to the ``lammps`` Python package folder to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
* the ``-v`` flag points to the LAMMPS version header file to extract the version date,
* and the optional ``-n`` instructs the script to only build a wheel file
but not attempt to install it.
* the optional ``-n`` instructs the script to only build a wheel file but not attempt
to install it,
* and the optional ``-f`` argument instructs the script to force installation even if
pip would otherwise refuse installation with an
:ref:`error about externally managed environments <externally_managed>`.
.. tab:: Virtual environment
@ -198,6 +201,10 @@ folder that the dynamic loader searches or inside of the installed
The ``PYTHONPATH`` needs to point to the parent folder that contains the ``lammps`` package!
In case you run into an "externally-managed-environment" error when
trying to install the LAMMPS Python module, please refer to
:ref:`corresponding paragraph <externally_managed>` in the Python HOWTO
page to learn about options for handling this error.
To verify if LAMMPS can be successfully started from Python, start the
Python interpreter, load the ``lammps`` Python module and create a

23
doc/src/Python_scatter.rst
View File

@ -3,17 +3,16 @@ Scatter/gather operations
.. code-block:: python
data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered)
data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs
data = lmp.gather_atoms(name,dtype,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "q", "type", etc
data = lmp.gather_atoms_concat(name,dtype,count) # ditto, but concatenated atom values from each proc (unordered)
data = lmp.gather_atoms_subset(name,dtype,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs
lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs
lmp.scatter_atoms(name,dtype,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID
# name = "x", "q", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms_subset(name,dtype,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs
The gather methods collect peratom info of the requested type (atom
coords, atom types, forces, etc) from all processors, and returns the
@ -22,6 +21,12 @@ functions do the inverse. They distribute a vector of peratom values,
passed by all calling processors, to individual atoms, which may be
owned by different processors.
The *dtype* parameter is 0 for ``int`` values and 1 for ``double``
values. The *count* parameter is 1 for per-atom vectors like "type"
or "q" and 3 for per-atom arrays like "x", "v", "f". Use *count* = 3
with name = "image" if you want the single integer storing the image
flags unpacked into 3 components ("x", "y", and "z").
Note that the data returned by the gather methods,
e.g. :py:meth:`gather_atoms("x") <lammps.lammps.gather_atoms()>`, is
different from the data structure returned by

416
doc/src/Run_formats.rst Normal file
View File

@ -0,0 +1,416 @@
File formats used by LAMMPS
===========================
This page provides a general overview of the kinds of files and file
formats that LAMMPS is reading and writing.
.. contents:: On this page
:depth: 2
:backlinks: top
-------------------
Character Encoding
^^^^^^^^^^^^^^^^^^
For processing text files, the LAMMPS source code assumes `ASCII
character encoding <https://en.wikipedia.org/wiki/ASCII>`_ which
represents the digits 0 to 9, the lower and upper case letters a to z,
some common punctuation and other symbols and a few whitespace
characters including a regular "space character", "line feed", "carriage
return", "tabulator". These characters are all represented by single
bytes with a value smaller than 128 and only 95 of those 128 values
represent printable characters. This list is sufficient to represent
most English text, but misses accented characters or umlauts or Greek
symbols and more.
Modern text often uses `UTF-8 character encoding
<https://en.wikipedia.org/wiki/UTF-8>`_ instead. This encoding is a way
to represent many more different characters as defined by the Unicode
standard. UFT-8 is compatible with ASCII, since the first 128 values
are identical with the ASCII encoding. It is important to note,
however, that there are Unicode characters that *look* similar to ASCII
characters, but have a different binary representation. As a general
rule, these characters may not be correctly recognized by LAMMPS. For
some parts of LAMMPS' text processing, translation tables with known
"lookalike" characters are used. The tables are used to substitute
non-ASCII characters with their ASCII equivalents. Non-ASCII lookalike
characters are often used by web browsers or PDF viewers to improve the
readability of text. Thus, when using copy and paste to transfer text
from such an application to your input file, you may unintentionally
create text that is not exclusively using ASCII encoding and may cause
errors when LAMMPS is trying to read it.
Lines with non-printable and non-ASCII characters in text files can be
detected for example with a (Linux) command like the following:
.. code-block:: bash
env LC_ALL=C grep -n '[^ -~]' some_file.txt
Number Formatting
^^^^^^^^^^^^^^^^^
Different countries and languages have different conventions to format
numbers. While in some regions commas are used for fractions and points
to indicate thousand, million and so on, this is reversed in other
regions. Modern operating systems have facilities to adjust input and
output accordingly that are collectively referred to as "native language
support" (NLS). The exact rules are often applied according to the
value of the ``$LANG`` environment variable (e.g. "en_US.utf8" for
English text in UTF-8 encoding).
For the sake of simplicity of the implementation and transferability of
results, LAMMPS does not support this and instead expects numbers being
formatted in the generic or "C" locale. The "C" locale has no
punctuation for thousand, million and so on and uses a decimal point for
fractions. One thousand would be represented as "1000.0" and not as
"1,000.0" nor as "1.000,0". Having native language support enabled for
a locale other than "C" will result in different behavior when
converting or formatting numbers that can trigger unexpected errors.
LAMMPS also only accepts integer numbers when an integer is required, so
using floating point equivalents like "1.0" are not accepted; you *must*
use "1" instead.
For floating point numbers in scientific notation, the Fortran double
precision notation "1.1d3" is not accepted; you have to use "1100",
"1100.0" or "1.1e3".
Input file
^^^^^^^^^^
A LAMMPS input file is a text file with commands. It is read
line-by-line and each line is processed *immediately*. Before looking
for commands and executing them, there is a pre-processing step where
comments (non-quoted text starting with a pound sign '#') are removed,
``${variable}`` and ``$(expression)`` constructs are expanded or
evaluated, and lines that end in the ampersand character '&' are
combined with the next line (similar to Fortran 90 free-format source
code). After the pre-processing, lines are split into "words" and
evaluated. The first word must be a :doc:`command <Commands_all>` and
all following words are arguments. Below are some example lines:
.. code-block:: LAMMPS
# full line comment
# some global settings
units lj
atom_style atomic
# ^^ command ^^ argument(s)
variable x index 1 # may be overridden from command line with -var x <value>
variable xx equal 20*$x # variable "xx" is always 20 times "x"
lattice fcc 0.8442
# example of a command written across multiple lines
# the "region" command uses spacing from "lattice" command, unless "units box" is specified
region box block 0.0 ${xx} &
0.0 40.0 &
0.0 30.0
# create simulation box and fill with atoms according to lattice setting
create_box 1 box
create_atoms 1 box
# set force field and parameters
mass 1 1.0
pair_style lj/cut 2.5
pair_coeff 1 1 1.0 1.0 2.5
# run simulation
fix 1 all nve
run 1000
The pivotal command in this example input is the :doc:`create_box
command <create_box>`. It defines the simulation system and many
parameters that go with it: units, atom style, number of atom types (and
other types) and more. Those settings are *locked in* after the box is
created. Commands that change these kind of settings are only allowed
**before** a simulation box is created and many other commands are only
allowed **after** the simulation box is defined (e.g. :doc:`pair_coeff
<pair_coeff>`). Very few commands (e.g. :doc:`pair_style <pair_style>`)
may be used in either part of the input. The :doc:`read_data
<read_data>` and :doc:`read_restart <read_restart>` commands also create
the system box and thus have a similar pivotal function.
The LAMMPS input syntax has minimal support for conditionals and loops,
but if more complex operations are required, it is recommended to use
the library interface, e.g. :doc:`from Python using the LAMMPS Python
module <Python_run>`.
There is a frequent misconception about the :doc:`if command <if>`:
this is a command for conditional execution **outside** a run or
minimization. To trigger actions on specific conditions **during**
a run is a non-trivial operation that usually requires adopting one
of the available "fix" commands or creating a new "fix" command.
LAMMPS commands change the internal state and thus the order of commands
matters and reordering them can produce different results. For example,
the region defined by the :doc:`region command <region>` in the example
above depends on the :doc:`lattice setting <lattice>` and thus its
dimensions will be different depending on the order of the two commands.
Each line must have an "end-of-line" character (line feed or carriage
return plus line feed). Some text editors do not automatically insert
one which may cause LAMMPS to ignore the last command. It is thus
recommended to always have an empty line at the end of an input file.
The specific details describing how LAMMPS input is processed and parsed
are explained in :doc:`Commands_parse`.
Data file
^^^^^^^^^
A LAMMPS data file contains a description of a system suitable for
reading with the :doc:`read_data command <read_data>`. Data files are
commonly used for setting up complex molecular systems that can be
difficult to achieve with the commands :doc:`create_box <create_box>`
and :doc:`create_atoms <create_atoms>` alone. Also, data files can be
used as a portable alternatives to a :doc:`binary restart file
<restart>`. A restart file can be converted into a data file from the
:doc:`command line <Run_options>`.
Data files have a header section at the very beginning of the file and
multiple titled sections such as "Atoms", Masses", "Pair Coeffs", and so
on. Header keywords can only be used *before* the first title section.
The data file **always** starts with a "title" line, which will be
**ignored** by LAMMPS. Omitting the title line can lead to unexpected
behavior because a line of the header with an actual setting may be
ignored. In this case, the mistakenly ignored line often contains the
"atoms" keyword, which results in LAMMPS assuming that there are no
atoms in the data file and thus throwing an error on the contents of the
"Atoms" section. The title line may contain some keywords that can be
used by external programs to convey information about the system
(included as comments), that is not required and not read by LAMMPS.
The line following a section title is also **ignored**. An error will
occur if an empty line is not placed after a section title. The number
of lines in titled sections depends on header keywords, like the number
of atom types, the number of atoms, the number of bond types, the number
of bonds, and so on. The data in those sections has to be complete. A
special case are the "Pair Coeffs" and "PairIJ Coeffs" sections; the
former is for force fields and pair styles that use mixing of non-bonded
potential parameters, the latter for pair styles and force fields
requiring explicit coefficients. Thus with *N* being the number of atom
types, the "Pair Coeffs" section has *N* entries while "PairIJ Coeffs"
has :math:`N \cdot (N-1)` entries. Internally, these sections will be
converted to :doc:`pair_coeff <pair_coeff>` commands. Thus the
corresponding :doc:`pair style <pair_style>` must have been set *before*
the :doc:`read_data command <read_data>` reads the data file.
Data files may contain comments, which start with the pound sign '#'.
There must be at least one blank between a valid keyword and the pound
sign. Below is a simple example case of a data file for :doc:`atom style
full <atom_style>`.
.. code-block:: bash
LAMMPS Title line (ignored)
# full line comment
10 atoms # comment
4 atom types
-36.840194 64.211560 xlo xhi
-41.013691 68.385058 ylo yhi
-29.768095 57.139462 zlo zhi
Masses
1 12.0110
2 12.0110
3 15.9990
4 1.0080
Pair Coeffs # this section is optional
1 0.110000 3.563595 0.110000 3.563595
2 0.080000 3.670503 0.010000 3.385415
3 0.120000 3.029056 0.120000 2.494516
4 0.022000 2.351973 0.022000 2.351973
Atoms # full
1 1 1 0.560 43.99993 58.52678 36.78550 0 0 0
2 1 2 -0.270 45.10395 58.23499 35.86693 0 0 0
3 1 3 -0.510 43.81519 59.54928 37.43995 0 0 0
4 1 4 0.090 45.71714 57.34797 36.13434 0 0 0
5 1 4 0.090 45.72261 59.13657 35.67007 0 0 0
6 1 4 0.090 44.66624 58.09539 34.85538 0 0 0
7 1 3 -0.470 43.28193 57.47427 36.91953 0 0 0
8 1 4 0.070 42.07157 57.45486 37.62418 0 0 0
9 1 1 0.510 42.19985 57.57789 39.12163 0 0 0
10 1 1 0.510 41.88641 58.62251 39.70398 0 0 0
# ^^atomID ^^molID ^^type ^^charge ^^xcoord ^^ycoord ^^ycoord ^^image^^flags (optional)
Velocities # this section is optional
1 0.0050731 -0.00398928 0.00391473
2 -0.0175184 0.0173484 -0.00489207
3 0.00597225 -0.00202006 0.00166454
4 -0.010395 -0.0082582 0.00316419
5 -0.00390877 0.00470331 -0.00226911
6 -0.00111157 -0.00374545 -0.0169374
7 0.00209054 -0.00594936 -0.000124563
8 0.00635002 -0.0120093 -0.0110999
9 -0.004955 -0.0123375 0.000403422
10 0.00265028 -0.00189329 -0.00293198
The common problem is processing the "Atoms" section, since its format
depends on the :doc:`atom style <atom_style>` used, and that setting
must be done in the input file *before* reading the data file. To
assist with detecting incompatible data files, a comment is appended to
the "Atoms" title indicating the atom style used (or intended) when
*writing* the data file. For example, below is an "Atoms" section for
:doc:`atom style charge <atom_style>`, which omits the molecule ID
column.
.. code-block:: bash
Atoms # charge
1 1 0.560 43.99993 58.52678 36.78550
2 2 -0.270 45.10395 58.23499 35.86693
3 3 -0.510 43.81519 59.54928 37.43995
4 4 0.090 45.71714 57.34797 36.13434
5 4 0.090 45.72261 59.13657 35.67007
6 4 0.090 44.66624 58.09539 34.85538
7 3 -0.470 43.28193 57.47427 36.91953
8 4 0.070 42.07157 57.45486 37.62418
9 1 0.510 42.19985 57.57789 39.12163
10 1 0.510 41.88641 58.62251 39.70398
# ^^atomID ^^type ^^charge ^^xcoord ^^ycoord ^^ycoord
Another source of confusion about the "Atoms" section format is the
ordering of columns. The three atom style variants `atom_style full`,
`atom_style hybrid charge molecular`, and `atom_style hybrid molecular
charge` all carry the same per-atom information. However, in data files,
the Atoms section has the columns 'Atom-ID Molecule-ID Atom-type Charge
X Y Z' for atom style full, but for hybrid atom styles the first columns
are always 'Atom-ID Atom-type X Y Z' followed by any *additional* data
added by the hybrid styles, for example, 'Charge Molecule-ID' for the
first hybrid style and 'Molecule-ID Charge' in the second hybrid style
variant. Finally, an alternative to a hybrid atom style is to use fix
property/atom, e.g. to add molecule IDs to atom style charge. In this
case the "Atoms" section is formatted according to atom style charge and
a new section, "Molecules" is added that contains lines with 'Atom-ID
Molecule-ID', one for each atom in the system. For adding charges to
atom style molecular with fix property/atom, the "Atoms" section is now
formatted according to the atom style and a "Charges" section is added.
Molecule file
^^^^^^^^^^^^^
Molecule files for use with the :doc:`molecule command <molecule>` look
quite similar to data files but they do not have a compatible format,
i.e., one cannot use a data file as molecule file and vice versa. Below
is a simple example for a water molecule (SPC/E model). Same as a data
file, there is an ignored title line and you can use comments. However,
there is no information about the number of types or the box dimensions.
These parameters are set when the simulation box is created. Thus the
header only has the count of atoms, bonds, and so on.
Molecule files have a header followed by sections (just as in data
files), but the section names are different than those of a data file.
There is no "Atoms" section and the section formats in molecule files is
independent of the atom style. Its information is split across multiple
sections, like "Coords", "Types", and "Charges". Note that no "Masses"
section is needed here. The atom masses are by default tied to the atom
type and set with a data file or the :doc:`mass command <mass>`. A
"Masses" section would only be required for atom styles with per-atom
masses, e.g. atom style sphere, where in data files you would provide
the density and the diameter instead of the mass.
Since the entire file is a 'molecule', LAMMPS will assign a new
molecule-ID (if supported by the atom style) when atoms are instantiated
from a molecule file, e.g. with the :doc:`create_atoms command
<create_atoms>`. It is possible to include a "Molecules" section to
indicate that the atoms belong to multiple 'molecules'. Atom-IDs and
molecule-IDs in the molecule file are relative for the file
(i.e. starting from 1) and will be translated into actual atom-IDs also
when the atoms from the molecule are created.
.. code-block:: bash
# Water molecule. SPC/E model.
3 atoms
2 bonds
1 angles
Coords
1 1.12456 0.09298 1.27452
2 1.53683 0.75606 1.89928
3 0.49482 0.56390 0.65678
Types
1 1
2 2
3 2
Charges
1 -0.8472
2 0.4236
3 0.4236
Bonds
1 1 1 2
2 1 1 3
Angles
1 1 2 1 3
There are also optional sections, e.g. about :doc:`SHAKE <fix_shake>`
and :doc:`special bonds <special_bonds>`. Those sections are only needed
if the molecule command is issued *before* the simulation box is
defined. Otherwise, the molecule command can derive the required
settings internally.
Restart file
^^^^^^^^^^^^
LAMMPS restart files are binary files and not available in text format.
They can be identified by the first few bytes that contain the (C-style)
string ``LammpS RestartT`` as `magic string
<https://en.wikipedia.org/wiki/Magic_string>`_. This string is followed
by a 16-bit integer of the number 1 used for detecting whether the
computer writing the restart has the same `endianness
<https://en.wikipedia.org/wiki/Endianness>`_ as the computer reading it.
If not, the file cannot be read correctly. This integer is followed by
a 32-bit integer indicating the file format revision (currently 3),
which can be used to implement backward compatibility for reading older
revisions.
This information has been added to the `Unix "file" command's
<https://www.darwinsys.com/file/>` "magic" file so that restart files
can be identified without opening them. If you have a fairly recent
version, it should already be included. If you have an older version,
the LAMMPS source package :ref:`contains a file with the necessary
additions <magic>`.
The rest of the file is organized in sections of a 32-bit signed integer
constant indicating the kind of content and the corresponding value (or
values). If those values are arrays (including C-style strings), then
the integer constant is followed by a 32-bit integer indicating the
length of the array. This mechanism will read the data regardless of
the ordering of the sections. Symbolic names of the section constants
are in the ``lmprestart.h`` header file.
LAMMPS restart files are not expected to be portable between platforms
or LAMMPS versions, but changes to the file format are rare.
.. Native Dump file
.. ^^^^^^^^^^^^^^^^
..
.. Potential files
.. ^^^^^^^^^^^^^^^

10
doc/src/Run_head.rst
View File

@ -1,10 +1,11 @@
Run LAMMPS
**********
These pages explain how to run LAMMPS once you have :doc:`installed an executable <Install>` or :doc:`downloaded the source code <Install>`
and :doc:`built an executable <Build>`. The :doc:`Commands <Commands>`
doc page describes how input scripts are structured and the commands
they can contain.
These pages explain how to run LAMMPS once you have :doc:`installed an
executable <Install>` or :doc:`downloaded the source code <Install>` and
:doc:`built an executable <Build>`. The :doc:`Commands <Commands>` doc
page describes how input scripts are structured and the commands they
can contain.
.. toctree::
:maxdepth: 1
@ -12,4 +13,5 @@ they can contain.
Run_basics
Run_options
Run_output
Run_formats
Run_windows

13
doc/src/Speed_compare.rst
View File

@ -44,11 +44,6 @@ section below for examples where this has been done.
system the crossover (in single precision) is often about 50K-100K
atoms per GPU. When performing double precision calculations the
crossover point can be significantly smaller.
* Both KOKKOS and GPU package compute bonded interactions (bonds, angles,
etc) on the CPU. If the GPU package is running with several MPI processes
assigned to one GPU, the cost of computing the bonded interactions is
spread across more CPUs and hence the GPU package can run faster in these
cases.
* When using LAMMPS with multiple MPI ranks assigned to the same GPU, its
performance depends to some extent on the available bandwidth between
the CPUs and the GPU. This can differ significantly based on the
@ -85,10 +80,10 @@ section below for examples where this has been done.
code (with a performance penalty due to having data transfers between
host and GPU).
* The GPU package requires neighbor lists to be built on the CPU when using
exclusion lists, or a triclinic simulation box.
* The GPU package can be compiled for CUDA or OpenCL and thus supports
both, NVIDIA and AMD GPUs well. On NVIDIA hardware, using CUDA is typically
resulting in equal or better performance over OpenCL.
hybrid pair styles, exclusion lists, or a triclinic simulation box.
* The GPU package can be compiled for CUDA, HIP, or OpenCL and thus supports
NVIDIA, AMD, and Intel GPUs well. On NVIDIA hardware, using CUDA is
typically resulting in equal or better performance over OpenCL.
* OpenCL in the GPU package does theoretically also support Intel CPUs or
Intel Xeon Phi, but the native support for those in KOKKOS (or INTEL)
is superior.

14
doc/src/Tools.rst
View File

@ -930,7 +930,7 @@ dependencies and redirects the download to the local cache.
mkdir build
cd build
cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake ../cmake
cmake -D LAMMPS_DOWNLOADS_URL=${HTTP_CACHE_URL} -C "${LAMMPS_HTTP_CACHE_CONFIG}" -C ../cmake/presets/most.cmake -D DOWNLOAD_POTENTIALS=off ../cmake
make -j 8
deactivate_caches
@ -1276,11 +1276,13 @@ Those scripts were written by Steve Plimpton sjplimp at gmail.com
valgrind tool
-------------
The ``valgrind`` folder contains additional suppressions fur LAMMPS when using
valgrind's memcheck tool to search for memory access violation and memory
leaks. These suppressions are automatically invoked when running tests through
CMake "ctest -T memcheck". See the provided README file to add these
suppressions when running LAMMPS.
The ``valgrind`` folder contains additional suppressions fur LAMMPS when
using `valgrind's <https://valgrind.org/>`_ ` `memcheck tool
<https://valgrind.org/info/tools.html#memcheck>`_ to search for memory
access violation and memory leaks. These suppressions are automatically
invoked when running tests through CMake "ctest -T memcheck". See the
instruction in the ``README`` file to add these suppressions when using
valgrind with LAMMPS or other programs.
----------

17
doc/src/bond_bpm_spring.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style bpm/spring keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *break* or *volume/factor*
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *normalize* or *break* or *volume/factor*
.. parsed-literal::
@ -141,7 +141,8 @@ calculated using bond lengths squared and the cube root in the above equation
is accordingly replaced with a square root. This approximation assumes bonds
are evenly distributed on a spherical surface and neglects constant prefactors
which are irrelevant since only the ratio of volumes matters. This term may be
used to adjust the Poisson's ratio.
used to adjust the Poisson's ratio. See the simulation in the
``examples/bpm/poissons_ratio`` directory for a demonstration of this effect.
If a bond is broken (or created), :math:`V_{0,i}` is updated by subtracting
(or adding) that bond's contribution.
@ -152,7 +153,7 @@ the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* :math:`k` (force/distance units)
* :math:`\epsilon_c` (unit less)
* :math:`\epsilon_c` (unitless)
* :math:`\gamma` (force/velocity units)
Additionally, if *volume/factor* is set to *yes*, a fourth coefficient
@ -214,11 +215,11 @@ for an overview of LAMMPS output options.
The vector or array will be floating point values that correspond to
the specified attribute.
The single() function of this bond style returns 0.0 for the energy
of a bonded interaction, since energy is not conserved in these
dissipative potentials. The single() function also calculates an
extra bond quantity, the initial distance :math:`r_0`. This
extra quantity can be accessed by the
The potential energy and the single() function of this bond style return
:math:`k (r - r_0)^2 / 2` as a proxy of the energy of a bonded interaction,
ignoring any volumetric/smoothing factors or dissipative forces. The single()
function also calculates an extra bond quantity, the initial distance
:math:`r_0`. This extra quantity can be accessed by the
:doc:`compute bond/local <compute_bond_local>` command as *b1*\ .
Restrictions

184
doc/src/bond_bpm_spring_plastic.rst Normal file
View File

@ -0,0 +1,184 @@
.. index:: bond_style bpm/spring/plastic
bond_style bpm/spring/plastic command
=====================================
Syntax
""""""
.. code-block:: LAMMPS
bond_style bpm/spring/plastic keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth* or *normalize* or *break*
.. parsed-literal::
*store/local* values = fix_ID N attributes ...
* fix_ID = ID of associated internal fix to store data
* N = prepare data for output every this many timesteps
* attributes = zero or more of the below attributes may be appended
*id1, id2* = IDs of two atoms in the bond
*time* = the timestep the bond broke
*x, y, z* = the center of mass position of the two atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the two atoms (distance units)
*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
*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
""""""""
.. code-block:: LAMMPS
bond_style bpm/spring/plastic
bond_coeff 1 1.0 0.05 0.1 0.02
bond_style bpm/spring/plastic myfix 1000 time id1 id2
dump 1 all local 1000 dump.broken f_myfix[1] f_myfix[2] f_myfix[3]
dump_modify 1 write_header no
Description
"""""""""""
.. versionadded:: 2Apr2025
The *bpm/spring/plastic* bond style computes forces based on
deviations from the initial reference state of the two atoms and the
strain history. The reference length of the bond :math:`r_0` is stored
by each bond when it is first computed in the setup of a run. Initially,
the equilibrium length of each bond :math:`r_\mathrm{eq}` is set equal
to :math:`r_0` but can evolve. data is then preserved across run commands
and is written to :doc:`binary restart files <restart>` such that restarting
the system will not modify either of these quantities.
This bond style only applies central-body forces which conserve the
translational and rotational degrees of freedom of a bonded set of
particles. The force has a magnitude of
.. math::
F = -k (r_\mathrm{eq} - r) w
where :math:`k` is a stiffness, :math:`r` is the current distance between
the two particles, and :math:`w` is an optional smoothing factor discussed
below. If the bond stretches beyond a strain of :math:`\epsilon_p` in compression
or extension, it will plastically activate and :math:`r_\mathrm{eq}` will evolve
to ensure :math:`|(r-r_\mathrm{eq})/r_\mathrm{eq}|` never exceeds :math:`\epsilon_p`.
Therefore, if a bond is continually loaded in either tension or compression, the
force will initially grow elastically before plateauing. See
:ref:`(Clemmer) <plastic-Clemmer>` for more details on these mechanics.
Bonds will break at a strain of :math:`\epsilon_c`. This is done by setting
the bond type to 0 such that forces are no longer computed.
An additional damping force is applied to the bonded
particles. This forces is proportional to the difference in the
normal velocity of particles:
.. math::
F_D = - \gamma w (\hat{r} \bullet \vec{v})
where :math:`\gamma` is the damping strength, :math:`\hat{r}` is the
radial normal vector, and :math:`\vec{v}` is the velocity difference
between the two particles.
The smoothing factor :math:`w` is constructed such that forces smoothly
go to zero, avoiding discontinuities, as bonds approach the critical
breaking strain
.. math::
w = 1.0 - \left( \frac{r - r_0}{r_0 \epsilon_c} \right)^8 .
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* :math:`k` (force/distance units)
* :math:`\epsilon_c` (unitless)
* :math:`\gamma` (force/velocity units)
* :math:`\epsilon_p` (unitless)
See the :doc:`bpm/spring doc page <bond_bpm_spring>` for information on
the *smooth*, *normalize*, *break*, *overlay/pair*, and *store/local*
keywords.
Note that when unbroken bonds are dumped to a file via the
:doc:`dump local <dump>` command, bonds with type 0 (broken bonds)
are not included.
The :doc:`delete_bonds <delete_bonds>` command can also be used to
query the status of broken bonds or permanently delete them, e.g.:
.. code-block:: LAMMPS
delete_bonds all stats
delete_bonds all bond 0 remove
----------
Restart and other info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This bond style writes the reference state and plastic history of each
bond to :doc:`binary restart files <restart>`. Loading a restart file
will properly restore bonds. However, the reference state is NOT written
to data files. Therefore reading a data file will not restore bonds and
will cause their reference states to be redefined.
The potential energy and the single() function of this bond style
returns zero. The single() function also calculates two extra bond
quantities, the initial distance :math:`r_0` and the current equilibrium
length :math:`r_eq`. These extra quantities can be accessed by the
:doc:`compute bond/local <compute_bond_local>` command as *b1* and *b2*,
respectively.
Restrictions
""""""""""""
This bond style is part of the BPM package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
By default if pair interactions between bonded atoms are to be disabled,
this bond style requires setting
.. code-block:: LAMMPS
special_bonds lj 0 1 1 coul 1 1 1
and :doc:`newton <newton>` must be set to bond off. If the *overlay/pair*
keyword is set to *yes*, this bond style alternatively requires setting
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`bond bpm/spring <bond_bpm_spring>`
Default
"""""""
The option defaults are *overlay/pair* = *no*, *smooth* = *yes*, *normalize* = *no*, and *break* = *yes*
----------
.. _plastic-Clemmer:
**(Clemmer)** Clemmer and Lechman, Powder Technology (2025).

2
doc/src/bond_harmonic.rst
View File

@ -60,6 +60,8 @@ Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
:doc:`bond style harmonic/shift <bond_harmonic_shift>`,
:doc:`bond style harmonic/shift/cut <bond_harmonic_shift_cut>`
Default
"""""""

17
doc/src/bond_harmonic_shift.rst
View File

@ -31,9 +31,15 @@ the potential
E = \frac{U_{\text{min}}}{(r_0-r_c)^2} \left[ (r-r_0)^2-(r_c-r_0)^2 \right]
where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the critical distance.
The potential is :math:`-U_{\text{min}}` at :math:`r0` and zero at :math:`r_c`. The spring constant is
:math:`k = U_{\text{min}} / [ 2 (r_0-r_c)^2]`.
where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the
critical distance. The potential energy has the value
:math:`-U_{\text{min}}` at :math:`r_0` and zero at :math:`r_c`. This
bond style differs from :doc:`bond_style harmonic <bond_harmonic>`
by the value of the potential energy.
The equivalent spring constant value *K* for use with :doc:`bond_style
harmonic <bond_harmonic>` can be computed using :math:`K =
U_{\text{min}} / [(r_0-r_c)^2]`.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in
@ -41,9 +47,7 @@ the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* :math:`U_{\text{min}}` (energy)
* :math:`r_0` (distance)
* :math:`r_c` (distance)
----------
@ -63,7 +67,8 @@ Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`bond_harmonic <bond_harmonic>`
:doc:`bond style harmonic <bond_harmonic>`,
:doc:`bond style harmonic/shift/cut <bond_harmonic_shift_cut>`
Default
"""""""

11
doc/src/bond_harmonic_shift_cut.rst
View File

@ -31,9 +31,14 @@ uses the potential
E = \frac{U_{\text{min}}}{(r_0-r_c)^2} \left[ (r-r_0)^2-(r_c-r_0)^2 \right]
where :math:`r_0` is the equilibrium bond distance, and rc the critical distance.
The bond potential is zero for distances :math:`r > r_c`. The potential is :math:`-U_{\text{min}}`
at :math:`r_0` and zero at :math:`r_c`. The spring constant is :math:`k = U_{\text{min}} / [ 2 (r_0-r_c)^2]`.
where :math:`r_0` is the equilibrium bond distance, and :math:`r_c` the
critical distance. The bond potential is zero and thus its force also
zero for distances :math:`r > r_c`. The potential energy has the value
:math:`-U_{\text{min}}` at :math:`r_0` and zero at :math:`r_c`.
The equivalent spring constant value *K* for use with :doc:`bond_style
harmonic <bond_harmonic>` for :math:`r <= r_c`, can be computed using
:math:`K = U_{\text{min}} / [(r_0-r_c)^2]`
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the example above, or in

2
doc/src/bond_rheo_shell.rst
View File

@ -94,7 +94,7 @@ the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* :math:`k` (force/distance units)
* :math:`\epsilon_c` (unit less)
* :math:`\epsilon_c` (unitless)
* :math:`\gamma` (force/velocity units)
Unlike other BPM-style bonds, this bond style does not update special

3
doc/src/bond_style.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style style args
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *bpm/spring/plastic* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/restrain* *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* args = none for any style except *hybrid*
@ -86,6 +86,7 @@ accelerated styles exist.
* :doc:`bpm/rotational <bond_bpm_rotational>` - breakable bond with forces and torques based on deviation from reference state
* :doc:`bpm/spring <bond_bpm_spring>` - breakable bond with forces based on deviation from reference length
* :doc:`bpm/spring/plastic <bond_bpm_spring_plastic>` - a similar breakable bond with plastic yield
* :doc:`class2 <bond_class2>` - COMPASS (class 2) bond
* :doc:`fene <bond_fene>` - FENE (finite-extensible non-linear elastic) bond
* :doc:`fene/expand <bond_fene_expand>` - FENE bonds with variable size particles

17
doc/src/compute_chunk_atom.rst
View File

@ -217,13 +217,16 @@ scaled differently in the two different dimensions to transform them
into ellipses).
The created bins (and hence the chunk IDs) are numbered consecutively
from 1 to the number of bins = *Nchunk*\ . For *bin2d* and *bin3d*, the
numbering varies most rapidly in the first dimension (which could be
*x*, *y*, or *z*), next rapidly in the second dimension, and most slowly in the
third dimension. For *bin/sphere*, the bin with smallest radii is chunk
1 and the bin with largest radii is chunk Nchunk = *ncbin*\ . For
*bin/cylinder*, the numbering varies most rapidly in the dimension
along the cylinder axis and most slowly in the radial direction.
from 1 to the number of bins = *Nchunk*\ . For *bin2d* and *bin3d*, the
numbering varies fastest in the last dimension (which could be
*x*, *y*, or *z*), slower in the second dimension, and slowest in the
first dimension. For *bin/sphere*, the bin with smallest radius is chunk
1 and the bin with largest radius is chunk Nchunk = *ncbin*\ . For
*bin/cylinder*, the numbering varies faster in the dimension
along the cylinder axis and slower in the radial direction.
In all cases, for a given dimension, the numbering increases
with increasing value of the coordinate (Cartesian coordinate,
sphere or cylinder radius, axial position).
Each time this compute is invoked, each atom is mapped to a bin based
on its current position. Note that between reneighboring timesteps,

2
doc/src/compute_cna_atom.rst
View File

@ -67,7 +67,7 @@ following relation should also be satisfied:
.. math::
r_c + r_s > 2*{\rm cutoff}
r_c + r_s > 2*\mathrm{cutoff}
where :math:`r_c` is the cutoff distance of the potential, :math:`r_s`
is the skin

2
doc/src/compute_cnp_atom.rst
View File

@ -74,7 +74,7 @@ following relation should also be satisfied:
.. math::
r_c + r_s > 2*{\rm cutoff}
r_c + r_s > 2*\mathrm{cutoff}
where :math:`r_c` is the cutoff distance of the potential, :math:`r_s` is
the skin

4
doc/src/compute_efield_wolf_atom.rst
View File

@ -50,9 +50,9 @@ the potential energy using the Wolf summation method, described in
.. math::
E_i = \frac{1}{2} \sum_{j \neq i}
\frac{q_i q_j {\rm erfc}(\alpha r_{ij})}{r_{ij}} +
\frac{q_i q_j \mathrm{erfc}(\alpha r_{ij})}{r_{ij}} +
\frac{1}{2} \sum_{j \neq i}
\frac{q_i q_j {\rm erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c
\frac{q_i q_j \mathrm{erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c
where :math:`\alpha` is the damping parameter, and *erf()* and *erfc()*
are error-function and complementary error-function terms. This

2
doc/src/compute_hexorder_atom.rst
View File

@ -40,7 +40,7 @@ is a complex number (stored as two real numbers) defined as follows:
.. math::
q_n = \frac{1}{nnn}\sum_{j = 1}^{nnn} e^{n i \theta({\bf r}_{ij})}
q_n = \frac{1}{nnn}\sum_{j = 1}^{nnn} e^{n i \theta({\textbf{r}}_{ij})}
where the sum is over the *nnn* nearest neighbors
of the central atom. The angle :math:`\theta`

2
doc/src/compute_orientorder_atom.rst
View File

@ -49,7 +49,7 @@ For each atom, :math:`Q_\ell` is a real number defined as follows:
.. math::
\bar{Y}_{\ell m} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{\ell m}\bigl( \theta( {\bf r}_{ij} ), \phi( {\bf r}_{ij} ) \bigr) \\
\bar{Y}_{\ell m} = & \frac{1}{nnn}\sum_{j = 1}^{nnn} Y_{\ell m}\bigl( \theta( \mathbf{r}_{ij} ), \phi( \mathbf{r}_{ij} ) \bigr) \\
Q_\ell = & \sqrt{\frac{4 \pi}{2 \ell + 1} \sum_{m = -\ell }^{m = \ell } \bar{Y}_{\ell m} \bar{Y}^*_{\ell m}}
The first equation defines the local order parameters as averages

4
doc/src/compute_slcsa_atom.rst
View File

@ -19,7 +19,7 @@ Syntax
* lr_decision_file = file name of file containing the scaling matrix for logistic regression classification
* lr_bias_file = file name of file containing the bias vector for logistic regression classification
* maha_file = file name of file containing for each crystal structure: the Mahalanobis distance threshold for sanity check purposes, the average reduced descriptor and the inverse of the corresponding covariance matrix
* c_ID[*] = compute ID of previously required *compute sna/atom* command
* c_ID[1] = compute ID and output data column of previously defined *compute sna/atom* command
Examples
""""""""
@ -27,7 +27,7 @@ Examples
.. code-block:: LAMMPS
compute b1 all sna/atom 9.0 0.99363 8 0.5 1.0 rmin0 0.0 nnn 24 wmode 1 delta 0.3
compute b2 all slcsa/atom 8 4 mean_descriptors.dat lda_scalings.dat lr_decision.dat lr_bias.dat maha_thresholds.dat c_b1[*]
compute b2 all slcsa/atom 8 4 mean_descriptors.dat lda_scalings.dat lr_decision.dat lr_bias.dat maha_thresholds.dat c_b1[1]
Description
"""""""""""

10
doc/src/compute_sna_atom.rst
View File

@ -139,11 +139,11 @@ mapped on to a third polar angle :math:`\theta_0` defined by,
.. math::
\theta_0 = {\sf rfac0} \frac{r-r_{min0}}{R_{ii'}-r_{min0}} \pi
\theta_0 = \mathsf{rfac0} \frac{r-r_{min0}}{R_{ii'}-r_{min0}} \pi
In this way, all possible neighbor positions are mapped on to a subset
of the 3-sphere. Points south of the latitude :math:`\theta_0` =
*rfac0* :math:`\pi` are excluded.
of the 3-sphere. Points south of the latitude
:math:`\theta_0 = \mathsf{rfac0} \pi` are excluded.
The natural basis for functions on the 3-sphere is formed by the
representatives of *SU(2)*, the matrices :math:`U^j_{m,m'}(\theta, \phi,
@ -204,7 +204,7 @@ components summed separately for each LAMMPS atom type:
.. math::
-\sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j} }}{\partial {\bf r}_i}
-\sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j} }}{\partial \mathbf{r}_i}
The sum is over all atoms *i'* of atom type *I*\ . For each atom *i*,
this compute evaluates the above expression for each direction, each
@ -216,7 +216,7 @@ derivatives:
.. math::
-{\bf r}_i \otimes \sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j}}}{\partial {\bf r}_i}
-\mathbf{r}_i \otimes \sum_{i' \in I} \frac{\partial {B^{i'}_{j_1,j_2,j}}}{\partial \mathbf{r}_i}
Again, the sum is over all atoms *i'* of atom type *I*\ . For each atom
*i*, this compute evaluates the above expression for each of the six

4
doc/src/compute_stress_atom.rst
View File

@ -65,7 +65,7 @@ In case of compute *stress/atom*, the virial contribution is:
W_{ab} & = \frac{1}{2} \sum_{n = 1}^{N_p} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b}) + \frac{1}{2} \sum_{n = 1}^{N_b} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b}) \\
& + \frac{1}{3} \sum_{n = 1}^{N_a} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b}) + \frac{1}{4} \sum_{n = 1}^{N_d} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) \\
& + \frac{1}{4} \sum_{n = 1}^{N_i} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
& + \frac{1}{4} \sum_{n = 1}^{N_i} (r_{1_a} F_{1_b} + r_{2_a} F_{2_b} + r_{3_a} F_{3_b} + r_{4_a} F_{4_b}) + \mathrm{Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
The first term is a pairwise energy contribution where :math:`n` loops
over the :math:`N_p` neighbors of atom :math:`I`, :math:`\mathbf{r}_1`
@ -97,7 +97,7 @@ In case of compute *centroid/stress/atom*, the virial contribution is:
.. math::
W_{ab} & = \sum_{n = 1}^{N_p} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_b} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_a} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_d} r_{I0_a} F_{I_b} + \sum_{n = 1}^{N_i} r_{I0_a} F_{I_b} \\
& + {\rm Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
& + \mathrm{Kspace}(r_{i_a},F_{i_b}) + \sum_{n = 1}^{N_f} r_{i_a} F_{i_b}
As with compute *stress/atom*, the first, second, third, fourth and
fifth terms are pairwise, bond, angle, dihedral and improper

2
doc/src/compute_vacf_chunk.rst
View File

@ -24,7 +24,7 @@ Examples
Description
"""""""""""
.. versionadded:: TBD
.. versionadded:: 2Apr2025
Define a computation that calculates the velocity auto-correlation
function (VACF) for multiple chunks of atoms.

3
doc/src/dihedral_multi_harmonic.rst
View File

@ -1,10 +1,11 @@
.. index:: dihedral_style multi/harmonic
.. index:: dihedral_style multi/harmonic/kk
.. index:: dihedral_style multi/harmonic/omp
dihedral_style multi/harmonic command
=====================================
Accelerator Variants: *multi/harmonic/omp*
Accelerator Variants: *multi/harmonic/kk*, *multi/harmonic/omp*
Syntax
""""""

59
doc/src/dump.rst
View File

@ -3,6 +3,7 @@
.. index:: dump cfg
.. index:: dump custom
.. index:: dump dcd
.. index:: dump extxyz
.. index:: dump grid
.. index:: dump grid/vtk
.. index:: dump local
@ -59,7 +60,7 @@ Syntax
* ID = user-assigned name for the dump
* group-ID = ID of the group of atoms to be dumped
* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/adios* or *dcd* or *grid* or *grid/vtk* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *yaml*
* style = *atom* or *atom/adios* or *atom/gz* or *atom/zstd* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/uef* or *custom* or *custom/gz* or *custom/zstd* or *custom/adios* or *dcd* or *extxyz* or *grid* or *grid/vtk* or *h5md* or *image* or *local* or *local/gz* or *local/zstd* or *molfile* or *movie* or *netcdf* or *netcdf/mpiio* or *vtk* or *xtc* or *xyz* or *xyz/gz* or *xyz/zstd* or *yaml*
* N = dump on timesteps which are multiples of N
* file = name of file to write dump info to
* attribute1,attribute2,... = list of attributes for a particular style
@ -77,6 +78,7 @@ Syntax
*custom*, *custom/gz*, *custom/zstd* attributes = see below
*custom/adios* attributes = same as *custom* attributes, discussed on :doc:`dump custom/adios <dump_adios>` page
*dcd* attributes = none
*extxyz* attributes = none
*h5md* attributes = discussed on :doc:`dump h5md <dump_h5md>` page
*grid* attributes = see below
*grid/vtk* attributes = see below
@ -242,28 +244,29 @@ all the processors or multiple smaller files.
frames consistently to the same atom. This can lead to incorrect
visualizations or results. LAMMPS will print a warning in such cases.
For the *atom*, *custom*, *cfg*, *grid*, and *local* styles, sorting
is off by default. For the *dcd*, *grid/vtk*, *xtc*, *xyz*, and
For the *atom*, *custom*, *cfg*, *grid*, and *local* styles, sorting is
off by default. For the *dcd*, *extxyz*, *grid/vtk*, *xtc*, *xyz*, and
*molfile* styles, sorting by atom ID or grid ID is on by default. See
the :doc:`dump_modify <dump_modify>` page for details.
The *style* keyword determines what kind of data is written to the
dump file(s) and in what format.
Note that *atom*, *custom*, *dcd*, *xtc*, *xyz*, and *yaml* style dump
files can be read directly by `VMD <https://www.ks.uiuc.edu/Research/vmd>`_,
a popular tool for visualizing and analyzing trajectories from atomic
and molecular systems. For reading *netcdf* style dump files, the
netcdf plugin needs to be recompiled from source using a NetCDF version
compatible with the one used by LAMMPS. The bundled plugin binary
uses a very old version of NetCDF that is not compatible with LAMMPS.
Note that *atom*, *custom*, *dcd*, *extxyz*, *xtc*, *xyz*, and *yaml*
style dump files can be read directly by `VMD
<https://www.ks.uiuc.edu/Research/vmd>`_, a popular tool for visualizing
and analyzing trajectories from atomic and molecular systems. For
reading *netcdf* style dump files, the netcdf plugin needs to be
recompiled from source using a NetCDF version compatible with the one
used by LAMMPS. The bundled plugin binary uses a very old version of
NetCDF that is not compatible with LAMMPS.
Likewise the `OVITO visualization package <https://www.ovito.org>`_,
popular for materials modeling, can read the *atom*, *custom*,
popular for materials modeling, can read the *atom*, *custom*, *extxyz*,
*local*, *xtc*, *cfg*, *netcdf*, and *xyz* style atom dump files
directly. With version 3.8 and above, OVITO can also read and
visualize *grid* style dump files with grid cell data, including
iso-surface images of the grid cell values.
directly. With version 3.8 and above, OVITO can also read and visualize
*grid* style dump files with grid cell data, including iso-surface
images of the grid cell values.
Note that settings made via the :doc:`dump_modify <dump_modify>`
command can also alter the format of individual values and content of
@ -475,6 +478,24 @@ label). This option will help many visualization programs to guess bonds
and colors. You can use the :doc:`dump_modify types labels <dump_modify>`
option to replace numeric atom types with :doc:`type labels <Howto_type_labels>`.
.. versionadded:: 2Apr2025
The *extxyz* style writes XYZ files compatible with the Extended XYZ (or
ExtXYZ) format as defined as defined in `the libAtoms specification
<https://github.com/libAtoms/extxyz>`_. Specifically, the following
information will be dumped:
* timestep
* time, which can be disabled with :doc:`dump_modify time no <dump_modify>`
* simulation box lattice and pbc conditions
* atomic forces, which can be disabled with :doc:`dump_modify forces no <dump_modify>`
* atomic velocities, which can be disabled with :doc:`dump_modify vel no <dump_modify>`
* atomic masses, if enabled with :doc:`dump_modify mass yes <dump_modify>`
Dump style *extxyz* requires either that a :doc:`type label map for atoms types
<labelmap>` is defined or :doc:`dump_modify element <dump_modify>` is used to
set up an atom type number to atom name mapping.
.. versionadded:: 22Dec2022
The *grid/vtk* style writes VTK files for grid data on a regular
@ -607,8 +628,8 @@ with the processor ID from :math:`0` to :math:`P-1`. For example,
tmp.dump.% becomes tmp.dump.0, tmp.dump.1, ... tmp.dump.:math:`P-1`,
etc. This creates smaller files and can be a fast mode of output on
parallel machines that support parallel I/O for output. This option is
**not** available for the *dcd*, *xtc*, *xyz*, *grid/vtk*, and *yaml*
styles.
**not** available for the *dcd*, *extxyz*, *xtc*, *xyz*, *grid/vtk*, and
*yaml* styles.
By default, :math:`P` is the the number of processors, meaning one file per
processor, but :math:`P` can be set to a smaller value via the *nfile* or
@ -1017,9 +1038,9 @@ the COMPRESS package. They are only enabled if LAMMPS was built with
that package. See the :doc:`Build package <Build_package>` page for
more info.
The *xtc*, *dcd*, and *yaml* styles are part of the EXTRA-DUMP package.
They are only enabled if LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
The *dcd*, *extxyz*, *xtc*, and *yaml* styles are part of the EXTRA-DUMP
package. They are only enabled if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` page for more info.
Related commands
""""""""""""""""

12
doc/src/dump_modify.rst
View File

@ -92,6 +92,15 @@ Syntax
see the :doc:`dump image <dump_image>` doc page for details
* these keywords apply only to the extxyz dump style
* keyword = *forces* or *mass* or *vel*
.. parsed-literal::
*forces* arg = *yes* or *no*
*mass* arg = *yes* or *no*
*vel* arg = *yes* or *no*
* these keywords apply only to the */gz* and */zstd* dump styles
* keyword = *compression_level*
@ -972,9 +981,11 @@ The option defaults are
* fileper = # of processors
* first = no
* flush = yes
* forces = yes
* format = %d and %g for each integer or floating point value
* image = no
* label = ENTRIES
* mass = no
* maxfiles = -1
* nfile = 1
* pad = 0
@ -990,6 +1001,7 @@ The option defaults are
* types = numeric
* units = no
* unwrap = no
* vel = yes
* compression_level = 9 (gz variants)
* compression_level = 0 (zstd variants)

4
doc/src/fitpod_command.rst
View File

@ -263,10 +263,10 @@ then the globally defined weights from the ``fitting_weight_energy`` and
POD Potential
"""""""""""""
We consider a multi-element system of *N* atoms with :math:`N_{\rm e}`
We consider a multi-element system of *N* atoms with :math:`N_\mathrm{e}`
unique elements. We denote by :math:`\boldsymbol r_n` and :math:`Z_n`
position vector and type of an atom *n* in the system,
respectively. Note that we have :math:`Z_n \in \{1, \ldots, N_{\rm e}
respectively. Note that we have :math:`Z_n \in \{1, \ldots, N_\mathrm{e}
\}`, :math:`\boldsymbol R = (\boldsymbol r_1, \boldsymbol r_2, \ldots,
\boldsymbol r_N) \in \mathbb{R}^{3N}`, and :math:`\boldsymbol Z = (Z_1,
Z_2, \ldots, Z_N) \in \mathbb{N}^{N}`. The total energy of the

3
doc/src/fix.rst
View File

@ -344,6 +344,8 @@ accelerated styles exist.
* :doc:`phonon <fix_phonon>` - calculate dynamical matrix from MD simulations
* :doc:`pimd/langevin <fix_pimd>` - Feynman path-integral molecular dynamics with stochastic thermostat
* :doc:`pimd/nvt <fix_pimd>` - Feynman path-integral molecular dynamics with Nose-Hoover thermostat
* :doc:`pimd/langevin/bosonic <fix_pimd>` - Bosonic Feynman path-integral molecular dynamics for with stochastic thermostat
* :doc:`pimd/nvt/bosonic <fix_pimd>` - Bosonic Feynman path-integral molecular dynamics with Nose-Hoover thermostat
* :doc:`planeforce <fix_planeforce>` - constrain atoms to move in a plane
* :doc:`plumed <fix_plumed>` - wrapper on PLUMED free energy library
* :doc:`poems <fix_poems>` - constrain clusters of atoms to move as coupled rigid bodies
@ -366,6 +368,7 @@ accelerated styles exist.
* :doc:`qeq/fire <fix_qeq>` - charge equilibration via FIRE minimizer
* :doc:`qeq/point <fix_qeq>` - charge equilibration via point method
* :doc:`qeq/reaxff <fix_qeq_reaxff>` - charge equilibration for ReaxFF potential
* :doc:`qeq/rel/reaxff <fix_qeq_rel_reaxff>` - charge equilibration for ReaxFF potential with alternate efield implementation
* :doc:`qeq/shielded <fix_qeq>` - charge equilibration via shielded method
* :doc:`qeq/slater <fix_qeq>` - charge equilibration via Slater method
* :doc:`qmmm <fix_qmmm>` - functionality to enable a quantum mechanics/molecular mechanics coupling

6
doc/src/fix_acks2_reaxff.rst
View File

@ -123,8 +123,10 @@ components in non-periodic directions.
Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`,
:doc:`fix qtpi/reaxff <fix_qtpie_reaxff>`
:doc:`pair_style reaxff <pair_reaxff>`,
:doc:`fix qeq/reaxff <fix_qeq_reaxff>`,
:doc:`fix qtpie/reaxff <fix_qtpie_reaxff>`,
:doc:`fix qeq/rel/reaxff <fix_qeq_rel_reaxff>`
Default
"""""""

67
doc/src/fix_adapt.rst
View File

@ -14,7 +14,7 @@ Syntax
* adapt = style name of this fix command
* N = adapt simulation settings every this many timesteps
* one or more attribute/arg pairs may be appended
* attribute = *pair* or *bond* or *angle* or *kspace* or *atom*
* attribute = *pair* or *bond* or *angle* or *improper* or *kspace* or *atom*
.. parsed-literal::
@ -33,6 +33,11 @@ Syntax
aparam = parameter to adapt over time
I = type angle to set parameter for (integer or type label)
v_name = variable with name that calculates value of aparam
*improper* args = istyle iparam I v_name
istyle = improper style name (e.g., cvff)
iparam = parameter to adapt over time
I = type improper to set parameter for (integer or type label)
v_name = variable with name that calculates value of iparam
*kspace* arg = v_name
v_name = variable with name that calculates scale factor on :math:`k`-space terms
*atom* args = atomparam v_name
@ -178,10 +183,14 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lennard/mdf <pair_mdf>` | A,B | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj96/cut <pair_lj96>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/class2 <pair_class2>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/class2/coul/cut, lj/class2/coul/long <pair_class2>` | epsilon,sigma,coulombic_cutoff | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/cubic <pair_lj_cubic>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/cut <pair_lj>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/cut/coul/cut, lj/cut/coul/long, lj/cut/coul/msm <pair_lj_cut_coul>` | epsilon,sigma,coulombic_cutoff | type pairs |
@ -196,6 +205,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/expand <pair_lj_expand>` | epsilon,sigma,delta | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/lj/gromacs <pair_gromacs>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/mdf <pair_mdf>` | epsilon,sigma | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`lj/sf/dipole/sf <pair_dipole>` | epsilon,sigma,scale | type pairs |
@ -216,6 +227,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`pace, pace/extrapolation <pair_pace>` | scale | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`pedone <pair_pedone>` | c0,d0,r0,alpha | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`quip <pair_quip>` | scale | type global |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`snap <pair_snap>` | scale | type pairs |
@ -236,6 +249,8 @@ formulas for the meaning of these parameters:
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`wf/cut <pair_wf_cut>` | epsilon,sigma,nu,mu | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
| :doc:`yukawa <pair_yukawa>` | alpha | type pairs |
+------------------------------------------------------------------------------+--------------------------------------------------+-------------+
.. note::
@ -418,6 +433,56 @@ this fix uses to reset theta0 needs to generate values in radians.
----------
.. versionadded:: 2Apr2025
The *improper* keyword uses the specified variable to change the value of
an improper coefficient over time, very similar to how the *angle* keyword
operates. The only difference is that now an improper coefficient for a
given improper type is adapted.
A wild-card asterisk can be used in place of or in conjunction with the
improper type argument to set the coefficients for multiple improper types.
This takes the form "\*" or "\*n" or "m\*" or "m\*n". If :math:`N` is
the number of improper types, then an asterisk with no numeric values means
all types from 1 to :math:`N`. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from m to
:math:`N` (inclusive). A middle asterisk means all types from m to n
(inclusive).
If :doc:`improper_style hybrid <improper_hybrid>` is used, *istyle* should be a
sub-style name. The improper styles that currently work with fix adapt are:
+---------------------------------------------------------+----------------+----------------+
| :doc:`amoeba <improper_amoeba>` | k | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`class2 <improper_class2>` | k,chi0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`cossq <improper_cossq>` | k,chi0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`cvff <improper_cvff>` | k,d,n | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`distance <improper_distance>` | k2,k4 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`distharm <improper_distharm>` | k,d0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`fourier <improper_fourier>` | k,C0,C1,C2 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`harmonic <improper_harmonic>` | k,chi0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`inversion/harmonic <improper_inversion_harmonic>` | k,w0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`ring <improper_ring>` | k,theta0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`umbrella <improper_umbrella>` | k,w0 | type impropers |
+---------------------------------------------------------+----------------+----------------+
| :doc:`sqdistharm <improper_sqdistharm>` | k | type impropers |
+---------------------------------------------------------+----------------+----------------+
Note that internally, chi0 and theta0 are stored in radians, so the variable
this fix use to reset chi0 or theta0 needs to generate values in radians.
----------
The *kspace* keyword used the specified variable as a scale factor on
the energy, forces, virial calculated by whatever :math:`k`-space solver is
defined by the :doc:`kspace_style <kspace_style>` command. If the

4
doc/src/fix_ave_chunk.rst
View File

@ -459,8 +459,8 @@ output. This option can only be used with the *ave running* setting.
The *format* keyword sets the numeric format of each value when it is
printed to a file via the *file* keyword. Note that all values are
floating point quantities. The default format is %g. You can specify
a higher precision if desired (e.g., %20.16g).
floating point quantities. The default format is " %g". You can specify
a higher precision if desired (e.g., " %20.16g").
The *title1* and *title2* and *title3* keywords allow specification of
the strings that will be printed as the first three lines of the output

8
doc/src/fix_ave_correlate.rst
View File

@ -32,13 +32,14 @@ Syntax
.. parsed-literal::
*type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full*
*type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* or *first*
auto = correlate each value with itself
upper = correlate each value with each succeeding value
lower = correlate each value with each preceding value
auto/upper = auto + upper
auto/lower = auto + lower
full = correlate each value with every other value, including itself = auto + upper + lower
first = correlate each value with the first value
*ave* args = *one* or *running*
one = zero the correlation accumulation every Nfreq steps
running = accumulate correlations continuously
@ -257,6 +258,9 @@ time.
* If *type* is set to *full* then each input value is correlated with
itself and every other value (i.e., :math:`C_{ij} = V_i V_j` for
:math:`\{i,j\} = \{1,N\}`, so :math:`N_\text{pair} = N^2`).
* If *type* is set to *first* then each input value is correlated with
the first input value (i.e., :math:`C_{ij} = V_1 V_j` for
:math:`\{j\} = \{1,N\}`, so :math:`N_\text{pair} = N`).
The *ave* keyword determines what happens to the accumulation of correlation
samples every :math:`N_\text{freq}` timesteps. If the *ave* setting is *one*,
@ -369,6 +373,8 @@ above.
* For *type* = *full*, the :math:`N_\text{pair} = N^2` columns are ordered:
:math:`C_{11}, C_{12}, \dotsc, C_{1N}, C_{21}, C_{22}, \dotsc, C_{2N},
C_{31}, \dotsc, C_{3N}, \dotsc, C_{N1}, \dotsc, C_{N,N-1}, C_{NN}`
* For *type* = *first*, the :math:`N_\text{pair} = N` columns are ordered:
:math:`C_{11}, C_{12}, \dotsc, C_{1N}`
The array values calculated by this fix are treated as extensive. If
you need to divide them by the number of atoms, you must do this in a

3
doc/src/fix_ave_correlate_long.rst
View File

@ -31,13 +31,14 @@ Syntax
.. parsed-literal::
*type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full*
*type* arg = *auto* or *upper* or *lower* or *auto/upper* or *auto/lower* or *full* or *first*
auto = correlate each value with itself
upper = correlate each value with each succeeding value
lower = correlate each value with each preceding value
auto/upper = auto + upper
auto/lower = auto + lower
full = correlate each value with every other value, including itself = auto + upper + lower
first = correlate each value with the first value
*start* args = Nstart
Nstart = start accumulating correlations on this time step
*file* arg = filename

4
doc/src/fix_ave_time.rst
View File

@ -304,8 +304,8 @@ output. This option can only be used with the *ave running* setting.
The *format* keyword sets the numeric format of each value when it is
printed to a file via the *file* keyword. Note that all values are
floating point quantities. The default format is %g. You can specify
a higher precision if desired (e.g., %20.16g).
floating point quantities. The default format is " %g". You can specify
a higher precision if desired (e.g., " %20.16g").
The *title1* and *title2* and *title3* keywords allow specification of
the strings that will be printed as the first 2 or 3 lines of the

40
doc/src/fix_bond_react.rst
View File

@ -28,9 +28,10 @@ Syntax
*no* = no reaction site stabilization (default)
group_prefix = user-assigned prefix for the dynamic group of atoms not currently involved in a reaction
xmax = value that is used by an internally-created :doc:`nve/limit <fix_nve_limit>` integrator
*reset_mol_ids* values = *yes* or *no*
*reset_mol_ids* values = *yes* or *no* or *molmap*
*yes* = update molecule IDs based on new global topology (default)
*no* = do not update molecule IDs
*molmap* = customize how molecule IDs are updated
* react = mandatory argument indicating new reaction specification
* react-ID = user-assigned name for the reaction
@ -188,12 +189,30 @@ due to the internal dynamic grouping performed by fix bond/react.
If the group-ID is an existing static group, react-group-IDs
should also be specified as this static group or a subset.
The *reset_mol_ids* keyword invokes the :doc:`reset_atoms mol
<reset_atoms>` command after a reaction occurs, to ensure that
molecule IDs are consistent with the new bond topology. The group-ID
used for :doc:`reset_atoms mol <reset_atoms>` is the group-ID for this
fix. Resetting molecule IDs is necessarily a global operation, so it
can be slow for very large systems.
.. versionadded:: 2Apr2025
New *molmap* option
If the *reset_mol_ids* keyword is set to *yes* (default), the
:doc:`reset_atoms mol <reset_atoms>` command is invoked after a reaction
occurs, to ensure that molecule IDs are consistent with the new bond
topology. The group-ID used for :doc:`reset_atoms mol <reset_atoms>` is
the group-ID for this fix. Resetting molecule IDs is necessarily a
global operation, so it can be slow for very large systems. If the
*reset_mol_ids* keyword is set to *no*, molecule IDs are not updated.
If the *reset_mol_ids* keyword is set to *molmap*, molecule IDs are
updated consistently with the molecule IDs listed in the *Molecules*
section of the pre- and post-reaction templates. If a post-reaction
atom has the same molecule ID as one or more pre-reaction atoms in the
templates, then the post-reaction simulation atom will be assigned the
same simulation molecule ID that those corresponding pre-reaction
simulation atoms had before the reaction. The *molmap* option is only
guaranteed to work correctly if all the pre-reaction atoms that have
equivalent template molecule IDs also have equivalent molecule IDs in
the simulation. No check is performed to test for this consistency.
For post-reaction atoms that have a template molecule ID that does not
exist in pre-reaction template, they are assigned a new molecule ID that
does not currently exist in the simulation.
The following comments pertain to each *react* argument (in other
words, they can be customized for each reaction, or reaction step):
@ -420,9 +439,10 @@ within a distance :math:`R` of any created atom, including the effect of
periodic boundary conditions if applicable. :math:`R` is defined by the
*overlap* sub-keyword. Note that the default value for :math:`R` is 0.0, which
will allow atoms to strongly overlap if you are inserting where other
atoms are present. The velocity of each created atom is initialized in
a random direction with a magnitude calculated from the instantaneous
temperature of the reaction site.
atoms are present. The molecule ID of a created atom is zero, unless the
*reset_mol_ids molmap* option is used. The velocity of each created atom is
initialized in a random direction with a magnitude calculated from the
instantaneous temperature of the reaction site.
.. note::

2
doc/src/fix_eos_table_rx.rst
View File

@ -49,7 +49,7 @@ computed according to the following relation:
where *m* is the number of species, :math:`c_{i,j}` is the
concentration of species *j* in particle *i*, :math:`u_j` is the
internal energy of species j, :math:`\Delta H_{f,j} is the heat of
internal energy of species j, :math:`\Delta H_{f,j}` is the heat of
formation of species *j*, N is the number of molecules represented
by the coarse-grained particle, :math:`k_B` is the Boltzmann constant,
and :math:`T` is the temperature of the system. Additionally, it is

4
doc/src/fix_gld.rst
View File

@ -60,9 +60,9 @@ With this fix active, the force on the *j*\ th atom is given as
.. math::
{\bf F}_{j}(t) = & {\bf F}^C_j(t)-\int \limits_{0}^{t} \Gamma_j(t-s) {\bf v}_j(s)~\text{d}s + {\bf F}^R_j(t) \\
\mathbf{F}_{j}(t) = & \mathbf{F}^C_j(t)-\int \limits_{0}^{t} \Gamma_j(t-s) \mathbf{v}_j(s)~\text{d}s + \mathbf{F}^R_j(t) \\
\Gamma_j(t-s) = & \sum \limits_{k=1}^{N_k} \frac{c_k}{\tau_k} e^{-(t-s)/\tau_k} \\
\langle{\bf F}^R_j(t),{\bf F}^R_j(s)\rangle = & \text{k$_\text{B}$T} ~\Gamma_j(t-s)
\langle\mathbf{F}^R_j(t),\mathbf{F}^R_j(s)\rangle = & \text{k$_\text{B}$T} ~\Gamma_j(t-s)
Here, the first term is representative of all conservative (pairwise,
bonded, etc) forces external to this fix, the second is the temporally

54
doc/src/fix_halt.rst
View File

@ -25,13 +25,14 @@ Syntax
* operator = "<" or "<=" or ">" or ">=" or "==" or "!=" or "\|\^"
* avalue = numeric value to compare attribute to
* zero or more keyword/value pairs may be appended
* keyword = *error* or *message* or *path*
* keyword = *error* or *message* or *path* or *universe*
.. parsed-literal::
*error* value = *hard* or *soft* or *continue*
*message* value = *yes* or *no*
*path* value = path to check for free space (may be in quotes)
*universe* value = *yes* or *no*
Examples
@ -40,8 +41,10 @@ Examples
.. code-block:: LAMMPS
fix 10 all halt 1 bondmax > 1.5
fix 10 all halt 10 v_myCheck != 0 error soft
fix 10 all halt 10 v_myCheck != 0 error soft message no
fix 10 all halt 100 diskfree < 100000.0 path "dump storage/."
fix 2 all halt 100 v_curtime > ${maxtime} universe yes
Description
"""""""""""
@ -141,33 +144,52 @@ The optional *error* keyword determines how the current run is halted.
If its value is *hard*, then LAMMPS will stop with an error message.
If its value is *soft*, LAMMPS will exit the current run, but continue
to execute subsequent commands in the input script. However,
additional :doc:`run <run>` or :doc:`minimize <minimize>` commands will be
skipped. For example, this allows a script to output the current
state of the system, e.g. via a :doc:`write_dump <write_dump>` or
:doc:`write_restart <write_restart>` command.
to execute subsequent commands in the input script. However, additional
:doc:`run <run>` or :doc:`minimize <minimize>` commands will be skipped.
For example, this allows a script to output the current state of the
system, e.g. via a :doc:`write_dump <write_dump>` or :doc:`write_restart
<write_restart>` command. To re-enable regular runs after *fix halt*
stopped a run, you need to issue a :doc:`timer timeout unlimited
<timer>` command.
If its value is *continue*, the behavior is the same as for *soft*,
except subsequent :doc:`run <run>` or :doc:`minimize <minimize>` commands
are executed. This allows your script to remedy the condition that
triggered the halt, if necessary. Note that you may wish use the
:doc:`unfix <unfix>` command on the fix halt ID, so that the same
condition is not immediately triggered in a subsequent run.
triggered the halt, if necessary. This is the equivalent of stopping
with *error soft* and followed by :doc:`timer timeout unlimited
<timer>` command. This can have undesired consequences, when a
:doc:`run command <run>` uses the *every* keyword, so using *error soft*
and resetting the timer manually may be the preferred option.
You may wish use the :doc:`unfix <unfix>` command on the *fix halt* ID
before starting a subsequent run, so that the same condition is not
immediately triggered again.
The optional *message* keyword determines whether a message is printed
to the screen and logfile when the halt condition is triggered. If
*message* is set to yes, a one line message with the values that
triggered the halt is printed. If *message* is set to no, no message
is printed; the run simply exits. The latter may be desirable for
triggered the halt is printed. If *message* is set to no, no message is
printed; the run simply exits. The latter may be desirable for
post-processing tools that extract thermodynamic information from log
files.
.. versionadded:: 2Apr2025
The optional *universe* keyword determines whether the halt request
should be synchronized across the partitions of a :doc:`multi-partition
run <Run_options>`. If *universe* is set to yes, fix halt will check if
there is a specific message received from any of the other partitions
requesting to stop the run on this partition as well. Consequently, if
fix halt determines to halt the simulation, the fix will send messages
to all other partitions so they stop their runs, too.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various :doc:`output commands <Howto_output>`.
No information about this fix is written to :doc:`binary restart files
<restart>`. None of the :doc:`fix_modify <fix_modify>` options are
relevant to this fix. No global or per-atom quantities are stored by
this fix for access by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
@ -183,4 +205,4 @@ Related commands
Default
"""""""
The option defaults are error = soft, message = yes, and path = ".".
The option defaults are error = soft, message = yes, path = ".", and universe = no.

17
doc/src/fix_hyper_global.rst
View File

@ -131,14 +131,15 @@ timesteps is simply
t_{hyper} = \sum_{i=1,N} B-i \cdot dt
where *dt* is the timestep size defined by the :doc:`timestep <timestep>`
command. The effective time acceleration due to GHD is thus t_hyper /
N\*dt, where N\*dt is elapsed time for a normal MD run of N timesteps.
command. The effective time acceleration due to GHD is thus
:math:`t_{hyper} / N * dt`, where N\*dt is elapsed time for a normal MD run
of N timesteps.
Note that in GHD, the boost factor varies from timestep to timestep.
Likewise, which bond has :math:`E^{max}` strain and thus which pair of
atoms the bias potential is added to, will also vary from timestep to timestep.
This is in contrast to local hyperdynamics (LHD) where the boost
factor is an input parameter; see the :doc:`fix hyper/local <fix_hyper_local>` page for details.
Note that in GHD, the boost factor varies from timestep to timestep. Likewise,
which bond has :math:`E^{max}` strain and thus which pair of atoms the bias
potential is added to, will also vary from timestep to timestep. This is in
contrast to local hyperdynamics (LHD) where the boost factor is an input
parameter; see the :doc:`fix hyper/local <fix_hyper_local>` page for details.
----------
@ -178,7 +179,7 @@ time-accurate trajectory of the system.
Note that if *Vmax* is set too small, the GHD simulation will run
correctly. There will just be fewer events because the hyper time
(t_hyper equation above) will be shorter.
(:math:`t_{hyper}` equation above) will be shorter.
.. note::

6
doc/src/fix_hyper_local.rst
View File

@ -111,7 +111,7 @@ requirement, and thus a bias potential :math:`V^{max}_{ij}` will be
applied to many bonds on the same timestep.
In LHD, all bonds store a :math:`C_{ij}` prefactor which appears in
the :math:`V^{max}_{ij}` and :math:`F^{max}_{ij}equations above. Note
the :math:`V^{max}_{ij}` and :math:`F^{max}_{ij}` equations above. Note
that the :math:`C_{ij}` factor scales the strength of the bias energy
and forces whenever bond *ij* is the maximum strain bond in its neighborhood.
@ -269,7 +269,7 @@ inverse of the alpha parameter discussed in
The *Btarget* argument is the desired time boost factor (a value > 1)
that all the atoms in the system will experience. The elapsed time
t_hyper for an LHD simulation running for *N* timesteps is simply
:math:`t_{hyper}` for an LHD simulation running for *N* timesteps is simply
.. math::
@ -294,7 +294,7 @@ is the specified temperature of the system
Note that if *Btarget* is set smaller than this, the LHD simulation
will run correctly. There will just be fewer events because the hyper
time (t_hyper equation above) will be shorter.
time (:math:`t_{hyper}` equation above) will be shorter.
.. note::

2
doc/src/fix_lb_fluid.rst
View File

@ -130,7 +130,7 @@ calculated as:
.. math::
{\bf F}_{j \alpha} = \gamma \left({\bf v}_n - {\bf u}_f \right) \zeta_{j\alpha}
\mathbf{F}_{j \alpha} = \gamma \left(\mathbf{v}_n - \mathbf{u}_f \right) \zeta_{j\alpha}
where :math:`\mathbf{v}_n` is the velocity of the MD particle,
:math:`\mathbf{u}_f` is the fluid velocity interpolated to the particle

15
doc/src/fix_modify.rst
View File

@ -12,7 +12,7 @@ Syntax
* fix-ID = ID of the fix to modify
* one or more keyword/value pairs may be appended
* keyword = *bodyforces* or *colname* or *dynamic/dof* or *energy* or *press* or *respa* or *temp* or *virial*
* keyword = *bodyforces* or *colname* or *dynamic/dof* or *energy* or *pad* or *press* or *respa* or *temp* or *virial*
.. parsed-literal::
@ -25,6 +25,7 @@ Syntax
*dynamic/dof* value = *yes* or *no*
yes/no = do or do not re-compute the number of degrees of freedom (DOF) contributing to the temperature
*energy* value = *yes* or *no*
*pad* arg = Nchar = # of characters to convert timestep to
*press* value = compute ID that calculates a pressure
*respa* value = *1* to *max respa level* or *0* (for outermost level)
*temp* value = compute ID that calculates a temperature
@ -184,6 +185,18 @@ replaces the string for that specific keyword. The *colname* keyword can
be used multiple times. If multiple *colname* settings refer to the same
keyword, the last setting has precedence.
.. versionadded:: 2Apr2025
The *pad* keyword only applies when a fix produces a file and the output
filename is specified with a wildcard "\*" character which becomes the
timestep. If *pad* is 0, which is the default, the timestep is
converted into a string of unpadded length (e.g., 100 or 12000 or
2000000). When *pad* is specified with *Nchar* :math:`>` 0, the string
is padded with leading zeroes so they are all the same length = *Nchar*\
. For example, pad 7 would yield 0000100, 0012000, 2000000. This can
be useful so that post-processing programs can easily read the files in
ascending timestep order. Please see the documentation of the individual
fix styles if this keyword is supported.
Restrictions
""""""""""""

14
doc/src/fix_move.rst
View File

@ -35,11 +35,12 @@ Syntax
v_vx,v_vy,v_vz = 3 variable names that calculate x,y,z velocity as function of time, any component can be specified as NULL
* zero or more keyword/value pairs may be appended
* keyword = *units*
* keyword = *units* or *update*
.. parsed-literal::
*units* value = *box* or *lattice*
*update* value = *dipole*
Examples
""""""""
@ -49,7 +50,7 @@ Examples
fix 1 boundary move wiggle 3.0 0.0 0.0 1.0 units box
fix 2 boundary move rotate 0.0 0.0 0.0 0.0 0.0 1.0 5.0
fix 2 boundary move variable v_myx v_myy NULL v_VX v_VY NULL
fix 3 boundary move transrot 0.1 0.1 0.0 0.0 0.0 0.0 0.0 0.0 1.0 5.0 units box
fix 3 boundary move transrot 0.1 0.1 0.0 0.0 0.0 0.0 0.0 0.0 1.0 5.0 units box update dipole
Description
"""""""""""
@ -217,6 +218,15 @@ been previously used to define the lattice spacing. Each of these 3
quantities may be dependent on the x,y,z dimension, since the lattice
spacings can be different in x,y,z.
.. versionadded:: 2Apr2025
If the *update dipole* keyword/value pair is used together with the
*rotate* or *transrot* style, then the orientation of the dipole moment
of each particle is also updated appropriately to correspond with the rotation.
This option should be used for models where a dipole moment is assigned to
finite-size particles, e.g. spheroids via use of the :doc:`atom_style hybrid
sphere dipole <atom_style>` command.
----------
Restart, fix_modify, output, run start/stop, minimize info

2
doc/src/fix_neb.rst
View File

@ -180,7 +180,7 @@ force is added.
By default, no additional forces act on the first and last replicas
during the NEB relaxation, so these replicas simply relax toward their
respective local minima. By using the key word *end*, additional forces
respective local minima. By using the keyword *end*, additional forces
can be applied to the first and/or last replicas, to enable them to
relax toward a MEP while constraining their energy E to the target
energy ETarget.

20
doc/src/fix_nh.rst
View File

@ -208,19 +208,19 @@ The relaxation rate of the barostat is set by its inertia :math:`W`:
.. math::
W = (N + 1) k_B T_{\rm target} P_{\rm damp}^2
W = (N + 1) k_B T_\mathrm{target} P_\mathrm{damp}^2
where :math:`N` is the number of atoms, :math:`k_B` is the Boltzmann constant,
and :math:`T_{\rm target}` is the target temperature of the barostat :ref:`(Martyna) <nh-Martyna>`.
If a thermostat is defined, :math:`T_{\rm target}` is the target temperature
of the thermostat. If a thermostat is not defined, :math:`T_{\rm target}`
and :math:`T_\mathrm{target}` is the target temperature of the barostat :ref:`(Martyna) <nh-Martyna>`.
If a thermostat is defined, :math:`T_\mathrm{target}` is the target temperature
of the thermostat. If a thermostat is not defined, :math:`T_\mathrm{target}`
is set to the current temperature of the system when the barostat is initialized.
If this temperature is too low the simulation will quit with an error.
Note: in previous versions of LAMMPS, :math:`T_{\rm target}` would default to
Note: in previous versions of LAMMPS, :math:`T_\mathrm{target}` would default to
a value of 1.0 for *lj* units and 300.0 otherwise if the system had a temperature
of exactly zero.
If a thermostat is not specified by this fix, :math:`T_{\rm target}` can be
If a thermostat is not specified by this fix, :math:`T_\mathrm{target}` can be
manually specified using the *Ptemp* parameter. This may be useful if the
barostat is initialized when the current temperature does not reflect the
steady state temperature of the system. This keyword may also be useful in
@ -512,8 +512,8 @@ according to the following factorization of the Liouville propagator
.. math::
\exp \left(\mathrm{i} L \Delta t \right) = & \hat{E}
\exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \\
&\times \left[
@ -526,8 +526,8 @@ according to the following factorization of the Liouville propagator
&\times
\exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) \\
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) \\
&+ \mathcal{O} \left(\Delta t^3 \right)
This factorization differs somewhat from that of Tuckerman et al, in

8
doc/src/fix_npt_cauchy.rst
View File

@ -426,8 +426,8 @@ according to the following factorization of the Liouville propagator
.. math::
\exp \left(\mathrm{i} L \Delta t \right) = & \hat{E}
\exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right) \\
&\times \left[
@ -440,8 +440,8 @@ according to the following factorization of the Liouville propagator
&\times
\exp \left(\mathrm{i} L_{2}^{(2)} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\epsilon , 2} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_{\rm T\textrm{-}baro} \frac{\Delta t}{2} \right) \\
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}part} \frac{\Delta t}{2} \right)
\exp \left(\mathrm{i} L_\mathrm{T\textrm{-}baro} \frac{\Delta t}{2} \right) \\
&+ \mathcal{O} \left(\Delta t^3 \right)
This factorization differs somewhat from that of Tuckerman et al, in

18
doc/src/fix_orient.rst
View File

@ -62,19 +62,19 @@ The potential energy added to atom I is given by these formulas
.. math::
\xi_{i} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j} - \mathbf{r}_{j}^{\rm I} \right| \qquad\qquad\left(1\right) \\
\xi_{i} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j} - \mathbf{r}_{j}^\mathrm{I} \right| \qquad\qquad\left(1\right) \\
\\
\xi_{\rm IJ} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j}^{\rm J} - \mathbf{r}_{j}^{\rm I} \right| \qquad\qquad\left(2\right)\\
\xi_\mathrm{IJ} = & \sum_{j=1}^{12} \left| \mathbf{r}_{j}^\mathrm{J} - \mathbf{r}_{j}^\mathrm{I} \right| \qquad\qquad\left(2\right)\\
\\
\xi_{\rm low} = & {\rm cutlo} \, \xi_{\rm IJ} \qquad\qquad\qquad\left(3\right)\\
\xi_{\rm high} = & {\rm cuthi} \, \xi_{\rm IJ} \qquad\qquad\qquad\left(4\right) \\
\xi_\mathrm{low} = & \mathrm{cutlo} \, \xi_\mathrm{IJ} \qquad\qquad\qquad\left(3\right)\\
\xi_\mathrm{high} = & \mathrm{cuthi} \, \xi_\mathrm{IJ} \qquad\qquad\qquad\left(4\right) \\
\\
\omega_{i} = & \frac{\pi}{2} \frac{\xi_{i} - \xi_{\rm low}}{\xi_{\rm high} - \xi_{\rm low}} \qquad\qquad\left(5\right)\\
\omega_{i} = & \frac{\pi}{2} \frac{\xi_{i} - \xi_\mathrm{low}}{\xi_\mathrm{high} - \xi_\mathrm{low}} \qquad\qquad\left(5\right)\\
\\
u_{i} = & 0 \quad\quad\qquad\qquad\qquad \textrm{ for } \qquad \xi_{i} < \xi_{\rm low}\\
= & {\rm dE}\,\frac{1 - \cos(2 \omega_{i})}{2}
\qquad \mathrm{ for }\qquad \xi_{\rm low} < \xi_{i} < \xi_{\rm high} \quad \left(6\right) \\
= & {\rm dE} \quad\qquad\qquad\qquad\textrm{ for } \qquad \xi_{\rm high} < \xi_{i}
u_{i} = & 0 \quad\quad\qquad\qquad\qquad \textrm{ for } \qquad \xi_{i} < \xi_\mathrm{low}\\
= & \mathrm{dE}\,\frac{1 - \cos(2 \omega_{i})}{2}
\qquad \mathrm{for }\qquad \xi_\mathrm{low} < \xi_{i} < \xi_\mathrm{high} \quad \left(6\right) \\
= & \mathrm{dE} \quad\qquad\qquad\qquad\textrm{ for } \qquad \xi_\mathrm{high} < \xi_{i}
which are fully explained in :ref:`(Janssens) <Janssens>`. For fcc crystals
this order parameter Xi for atom I in equation (1) is a sum over the

110
doc/src/fix_pimd.rst
View File

@ -1,5 +1,7 @@
.. index:: fix pimd/langevin
.. index:: fix pimd/nvt
.. index:: fix pimd/langevin/bosonic
.. index:: fix pimd/nvt/bosonic
fix pimd/langevin command
=========================
@ -7,6 +9,12 @@ fix pimd/langevin command
fix pimd/nvt command
====================
fix pimd/langevin/bosonic command
=================================
fix pimd/nvt/bosonic command
============================
Syntax
""""""
@ -15,39 +23,42 @@ Syntax
fix ID group-ID style keyword value ...
* ID, group-ID are documented in :doc:`fix <fix>` command
* style = *pimd/langevin* or *pimd/nvt* = style name of this fix command
* style = *pimd/langevin* or *pimd/nvt* or *pimd/langevin/bosonic* or *pimd/nvt/bosonic* = style name of this fix command
* zero or more keyword/value pairs may be appended
* keywords for style *pimd/nvt*
.. parsed-literal::
*keywords* = *method* or *fmass* or *sp* or *temp* or *nhc*
*method* value = *pimd* or *nmpimd* or *cmd*
*fmass* value = scaling factor on mass
*sp* value = scaling factor on Planck constant
*temp* value = temperature (temperature units)
*nhc* value = Nc = number of chains in Nose-Hoover thermostat
*keywords* = *method* or *fmass* or *sp* or *temp* or *nhc*
*method* value = *pimd* or *nmpimd* or *cmd*
*fmass* value = scaling factor on mass
*sp* value = scaling factor on Planck constant
*temp* value = temperature (temperature units)
*nhc* value = Nc = number of chains in Nose-Hoover thermostat
* keywords for style *pimd/langevin*
.. parsed-literal::
*keywords* = *method* or *integrator* or *ensemble* or *fmmode* or *fmass* or *scale* or *temp* or *thermostat* or *tau* or *iso* or *aniso* or *barostat* or *taup* or *fixcom* or *lj*
*method* value = *nmpimd* (default) or *pimd*
*integrator* value = *obabo* or *baoab*
*fmmode* value = *physical* or *normal*
*fmass* value = scaling factor on mass
*temp* value = temperature (temperature unit)
*keywords* = *method* or *integrator* or *ensemble* or *fmmode* or *fmass* or *scale* or *temp* or *thermostat* or *tau* or *iso* or *aniso* or *barostat* or *taup* or *fixcom* or *lj*
*method* value = *nmpimd* (default) or *pimd*
*integrator* value = *obabo* or *baoab*
*ensemble* value = *nvt* or *nve* or *nph* or *npt*
*fmmode* value = *physical* or *normal*
*fmass* value = scaling factor on mass
*temp* value = temperature (temperature unit)
temperature = target temperature of the thermostat
*thermostat* values = style seed
*thermostat* values = style seed
style value = *PILE_L*
seed = random number generator seed
*tau* value = thermostat damping parameter (time unit)
*scale* value = scaling factor of the damping times of non-centroid modes of PILE_L thermostat
*iso* or *aniso* values = pressure (pressure unit)
*tau* value = thermostat damping parameter (time unit)
*scale* value = scaling factor of the damping times of non-centroid modes of PILE_L thermostat
*iso* or *aniso* values = pressure (pressure unit)
pressure = scalar external pressure of the barostat
*barostat* value = *BZP* or *MTTK*
*taup* value = barostat damping parameter (time unit)
*fixcom* value = *yes* or *no*
*lj* values = epsilon sigma mass planck mvv2e
*barostat* value = *BZP* or *MTTK*
*taup* value = barostat damping parameter (time unit)
*fixcom* value = *yes* or *no*
*lj* values = epsilon sigma mass planck mvv2e
epsilon = energy scale for reduced units (energy units)
sigma = length scale for reduced units (length units)
mass = mass scale for reduced units (mass units)
@ -62,6 +73,8 @@ Examples
fix 1 all pimd/nvt method nmpimd fmass 1.0 sp 2.0 temp 300.0 nhc 4
fix 1 all pimd/langevin ensemble npt integrator obabo temp 113.15 thermostat PILE_L 1234 tau 1.0 iso 1.0 barostat BZP taup 1.0
Example input files are provided in the examples/PACKAGES/pimd directory.
Description
"""""""""""
@ -76,12 +89,20 @@ partition function for the original system to a classical partition
function for a ring-polymer system is exploited, to efficiently sample
configurations from the canonical ensemble :ref:`(Feynman) <Feynman>`.
The classical partition function and its components are given
.. versionadded:: 2Apr2025
Fix *pimd/langevin/bosonic* and *pimd/nvt/bosonic* were added.
Fix *pimd/nvt* and fix *pimd/langevin* simulate *distinguishable* quantum particles.
Simulations of bosons, including exchange effects, are supported with the
fix *pimd/langevin/bosonic* and the *pimd/nvt/bosonic* commands.
For distinguishable particles, the isomorphic classical partition function and its components are given
by the following equations:
.. math::
Z = & \int d{\bf q} d{\bf p} \cdot \textrm{exp} [ -\beta H_{eff} ] \\
Z = & \int d\mathbf{q} d\mathbf{p} \cdot \textrm{exp} [ -\beta H_{eff} ] \\
H_{eff} = & \bigg(\sum_{i=1}^P \frac{p_i^2}{2M_i}\bigg) + V_{eff} \\
V_{eff} = & \sum_{i=1}^P \bigg[ \frac{mP}{2\beta^2 \hbar^2} (q_i - q_{i+1})^2 + \frac{1}{P} V(q_i)\bigg]
@ -153,15 +174,17 @@ normal-mode PIMD. A value of *cmd* is for centroid molecular dynamics
Mode *pimd* added to fix pimd/langevin.
Fix pimd/langevin supports the *method* values *nmpimd* and *pimd*. The default value is *nmpimd*.
If *method* is *nmpimd*, the normal mode representation is used to integrate the equations of motion.
The exact solution of harmonic oscillator is used to propagate the free ring polymer part of the Hamiltonian.
If *method* is *pimd*, the Cartesian representation is used to integrate the equations of motion.
The harmonic force is added to the total force of the system, and the numerical integrator is used to propagate the Hamiltonian.
Fix pimd/langevin supports the *method* values *nmpimd* and *pimd*. The default
value is *nmpimd*. If *method* is *nmpimd*, the normal mode representation is
used to integrate the equations of motion. The exact solution of harmonic
oscillator is used to propagate the free ring polymer part of the Hamiltonian.
If *method* is *pimd*, the Cartesian representation is used to integrate the
equations of motion. The harmonic force is added to the total force of the
system, and the numerical integrator is used to propagate the Hamiltonian.
The keyword *integrator* specifies the Trotter splitting method used by *fix pimd/langevin*.
See :ref:`(Liu) <Liu>` for a discussion on the OBABO and BAOAB splitting schemes. Typically
either of the two should work fine.
The keyword *integrator* specifies the Trotter splitting method used by *fix
pimd/langevin*. See :ref:`(Liu) <Liu>` for a discussion on the OBABO and BAOAB
splitting schemes. Typically either of the two should work fine.
The keyword *fmass* sets a further scaling factor for the fictitious
masses of beads, which can be used for the Partial Adiabatic CMD
@ -211,8 +234,8 @@ a positive floating-point number.
For pimd simulations, a temperature values should be specified even for nve ensemble. Temperature will make a difference
for nve pimd, since the spring elastic frequency between the beads will be affected by the temperature.
The keyword *thermostat* reads *style* and *seed* of thermostat for fix style *pimd/langevin*. *style* can only
be *PILE_L* (path integral Langevin equation local thermostat, as described in :ref:`Ceriotti <Ceriotti2>`), and *seed* should a positive integer number, which serves as the seed of the pseudo random number generator.
The keyword *thermostat* reads *style* and *seed* of thermostat for fix style *pimd/langevin*.
*style* can only be *PILE_L* (path integral Langevin equation local thermostat, as described in :ref:`Ceriotti <Ceriotti2>`), and *seed* should a positive integer number, which serves as the seed of the pseudo random number generator.
.. note::
@ -222,7 +245,7 @@ be *PILE_L* (path integral Langevin equation local thermostat, as described in :
The keyword *tau* specifies the thermostat damping time parameter for fix style *pimd/langevin*. It is in time unit. It only works on the centroid mode.
The keyword *scale* specifies a scaling parameter for the damping times of the non-centroid modes for fix style *pimd/langevin*. The default
damping time of the non-centroid mode :math:`i` is :math:`\frac{P}{\beta\hbar}\sqrt{\lambda_i\times\mathrm{fmass}}` (*fmmode* is *physical*) or :math:`\frac{P}{\beta\hbar}\sqrt{\mathrm{fmass}}` (*fmmode* is *normal*). The damping times of all non-centroid modes are the default values divided by *scale*.
damping time of the non-centroid mode :math:`i` is :math:`\frac{P}{\beta\hbar}\sqrt{\lambda_i\times\mathrm{fmass}}` (*fmmode* is *physical*) or :math:`\frac{P}{\beta\hbar}\sqrt{\mathrm{fmass}}` (*fmmode* is *normal*). The damping times of all non-centroid modes are the default values divided by *scale*. This keyword should be used only with *method*=*nmpimd*.
The barostat parameters for fix style *pimd/langevin* with *npt* or *nph* ensemble is specified using one of *iso* and *aniso*
keywords. A *pressure* value should be given with pressure unit. The keyword *iso* means couple all 3 diagonal components together when pressure is computed (hydrostatic pressure), and dilate/contract the dimensions together. The keyword *aniso* means x, y, and z dimensions are controlled independently using the Pxx, Pyy, and Pzz components of the stress tensor as the driving forces, and the specified scalar external pressure.
@ -334,8 +357,8 @@ it outputs multiple log files, and different log files contain information
about different beads or modes (see detailed explanations below). If *ensemble*
is *nve* or *nvt*, the vector has 10 values:
#. kinetic energy of the normal mode
#. spring elastic energy of the normal mode
#. kinetic energy of the bead (if *method*=*pimd*) or normal mode (if *method*=*nmpimd*)
#. spring elastic energy of the bead (if *method*=*pimd*) or normal mode (if *method*=*nmpimd*)
#. potential energy of the bead
#. total energy of all beads (conserved if *ensemble* is *nve*)
#. primitive kinetic energy estimator
@ -398,7 +421,12 @@ LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Fix *pimd/nvt* cannot be used with :doc:`lj units <units>`.
Fix *pimd/langevin* can be used with :doc:`lj units <units>`. See the above part for how to use it.
Fix *pimd/langevin* can be used with :doc:`lj units <units>`.
See the documentation above for how to use it.
Only some combinations of fix styles and their options support
partitions with multiple processors. LAMMPS will stop with an
error if multi-processor partitions are not supported.
A PIMD simulation can be initialized with a single data file read via
the :doc:`read_data <read_data>` command. However, this means all
@ -412,12 +440,20 @@ variable, e.g.
velocity all create 300.0 1234${ibead} rot yes dist gaussian
Related commands
""""""""""""""""
:doc:`fix ipi <fix_ipi>`
Default
"""""""
The keyword defaults for fix *pimd/nvt* are method = pimd, fmass = 1.0, sp
= 1.0, temp = 300.0, and nhc = 2.
The keyword defaults for fix *pimd/langevin* are integrator = obabo, method = nmpimd, ensemble = nvt, fmmode = physical, fmass = 1.0,
scale = 1, temp = 298.15, thermostat = PILE_L, tau = 1.0, iso = 1.0, taup = 1.0, barostat = BZP, fixcom = yes, and lj = 1 for all its arguments.
----------
.. _Feynman:

2
doc/src/fix_qeq.rst
View File

@ -304,7 +304,7 @@ Chemistry, 95, 3358-3363 (1991).
.. _CTIP1:
**(CTIP)** G. Plummer, J. P. Tavenner, M. I. Mendelev, Z. Wu, J. W. Lawson,
in preparation
J Chemical Physics, 162, 054709 (2025)
.. _vanDuin:

5
doc/src/fix_qeq_reaxff.rst
View File

@ -59,7 +59,7 @@ extracted from the :doc:`pair_style reaxff <pair_reaxff>` command and
the ReaxFF force field file it reads in. If a file name is specified
for *params*, then the parameters are taken from the specified file
and the file must contain one line for each atom type. The latter
form must be used when performing QeQ with a non-ReaxFF potential.
form must be used when performing QEq with a non-ReaxFF potential.
Each line should be formatted as follows:
.. parsed-literal::
@ -140,7 +140,8 @@ Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/shielded <fix_qeq>`,
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`, :doc:`fix qtpie/reaxff <fix_qtpie_reaxff>`
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`, :doc:`fix qtpie/reaxff <fix_qtpie_reaxff>`,
:doc:`fix qeq/rel/reaxff <fix_qeq_rel_reaxff>`
Default
"""""""

195
doc/src/fix_qeq_rel_reaxff.rst Normal file
View File

@ -0,0 +1,195 @@
.. index:: fix qeq/rel/reaxff
fix qeq/rel/reaxff command
==========================
Syntax
""""""
.. code-block:: LAMMPS
fix ID group-ID qeq/rel/reaxff Nevery cutlo cuthi tolerance params gfile args
* ID, group-ID are documented in :doc:`fix <fix>` command
* qeq/rel/reaxff = style name of this fix command
* Nevery = perform QEqR every this many steps
* cutlo,cuthi = lo and hi cutoff for Taper radius
* tolerance = precision to which charges will be equilibrated
* params = reaxff or a filename
* gfile = the name of a file containing Gaussian orbital exponents
* one or more keywords or keyword/value pairs may be appended
.. parsed-literal::
keyword = *scale* or *maxiter* or *nowarn*
*scale* beta = set value of scaling factor *beta* (determines strength of electric polarization)
*maxiter* N = limit the number of iterations to *N*
*nowarn* = do not print a warning message if the maximum number of iterations is reached
Examples
""""""""
.. code-block:: LAMMPS
fix 1 all qeq/rel/reaxff 1 0.0 10.0 1.0e-6 reaxff exp.qeqr
fix 1 all qeq/rel/reaxff 1 0.0 10.0 1.0e-6 params.qeqr exp.qeqr scale 1.5 maxiter 500 nowarn
Description
"""""""""""
.. versionadded:: 19Nov2024
This fix implements the QEqR method for charge equilibration, which
differs from the QEq charge equilibration method :ref:`(Rappe and
Goddard) <Rappe4>` only in how external electric fields are accounted
for. This fix therefore raises a warning when used without :doc:`fix
efield <fix_efield>` since :doc:`fix qeq/reaxff <fix_qeq_reaxff>` should
be used without an external electric field. Charges are computed with
the QEqR method by minimizing the electrostatic energy of the system in
the same way as the QEq method but where the absolute electronegativity,
:math:`\chi_i`, of each atom in the QEq method is replaced with an
effective electronegativity given by
.. math::
\chi_{\mathrm{r}i} = \chi_i + \frac{\sum_{j=1}^{N} \beta(\phi_i - \phi_j) S_{ij}}
{\sum_{m=1}^{N}S_{im}},
where :math:`N` is the number of atoms in the system, :math:`\beta` is a
scaling factor, :math:`\phi_i` and :math:`\phi_j` are the electric
potentials at the positions of atoms :math:`i` and :math:`j` due to the
external electric field and :math:`S_{ij}` is the overlap integral
between atoms :math:`i` and :math:`j`. This formulation is advantageous
over the method used by :doc:`fix qeq/reaxff <fix_qeq_reaxff>` to
account for an external electric field in that it permits periodic
boundaries in the direction of an external electric field and in that it
does not worsen long-range charge transfer seen with QEq.
This fix is typically used in conjunction with the ReaxFF force field
model as implemented in the :doc:`pair_style reaxff <pair_reaxff>`
command, but it can be used with any potential in LAMMPS, so long as it
defines and uses charges on each atom. For more technical details about
the charge equilibration performed by *fix qeq/rel/reaxff*, which is the
same as in :doc:`fix qeq/reaxff <fix_qeq_reaxff>` except for the use of
:math:`\chi_{\mathrm{r}i}`, please refer to :ref:`(Aktulga)
<qeq-Aktulga3>`. To be explicit, *fix qeq/rel/reaxff* replaces
:math:`\chi_k` of eq. 3 in :ref:`(Aktulga) <qeq-Aktulga3>` with
:math:`\chi_{\mathrm{r}k}` when an external electric field is applied.
This fix requires the absolute electronegativity, :math:`\chi`, in eV,
the self-Coulomb potential, :math:`\eta`, in eV, and the shielded
Coulomb constant, :math:`\gamma`, in :math:`\AA^{-1}`. If the *params*
setting above is the word "reaxff", then these are extracted from the
:doc:`pair_style reaxff <pair_reaxff>` command and the ReaxFF force
field file it reads in. If a file name is specified for *params*, then
the parameters are taken from the specified file and the file must
contain one line for each atom type. The latter form must be used when
using this fix with a non-ReaxFF potential. Each line should be
formatted as follows, ensuring that the parameters are given in units of
eV, eV, and :math:`\AA^{-1}`, respectively:
.. parsed-literal::
itype chi eta gamma
where *itype* is the atom type from 1 to Ntypes. Note that eta is
defined here as twice the eta value in the ReaxFF file.
The overlap integrals :math:`S_{ij}` are computed by using normalized 1s
Gaussian type orbitals. The Gaussian orbital exponents, :math:`\alpha`,
that are needed to compute the overlap integrals are taken from the file
given by *gfile*. This file must contain one line for each atom type
and provide the Gaussian orbital exponent for each atom type in units of
inverse square Bohr radius. Each line should be formatted as follows:
.. parsed-literal::
itype alpha
Empty lines or any text following the pound sign (#) are ignored. An
example *gfile* for a system with two atom types is
.. parsed-literal::
# An example gfile. Exponents are taken from Table 2.2 of Chen, J. (2009).
# Theory and applications of fluctuating-charge models.
# The units of the exponents are 1 / (Bohr radius)^2 .
1 0.2240 # O
2 0.5434 # H
The optional *scale* keyword sets the value of :math:`\beta` in the
equation for :math:`\chi_{\mathrm{r}i}`. The default value is 1.0.
The optional *maxiter* keyword allows changing the max number of
iterations in the linear solver. The default value is 200.
The optional *nowarn* keyword silences the warning message printed when
the maximum number of iterations is reached. This can be useful for
comparing serial and parallel results where having the same fixed number
of iterations is desired, which can be achieved by using a very small
tolerance and setting *maxiter* to the desired number of iterations.
.. note::
In order to solve the self-consistent equations for electronegativity
equalization, LAMMPS imposes the additional constraint that all the
charges in the fix group must add up to zero. The initial charge
assignments should also satisfy this constraint. LAMMPS will print a
warning if that is not the case.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files
<restart>`. This fix computes a global scalar (the number of
iterations) and a per-atom vector (the effective electronegativity),
which can be accessed by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
This fix is invoked during :doc:`energy minimization <minimize>`.
Restrictions
""""""""""""
This fix is part of the REAXFF package. It is only enabled if LAMMPS
was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
This fix does not correctly handle interactions involving multiple
periodic images of the same atom. Hence, it should not be used for
periodic cell dimensions smaller than the non-bonded cutoff radius,
which is typically :math:`10~\AA` for ReaxFF simulations.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
and will apply the external electric field during charge equilibration,
but there may be only one fix efield instance used and the electric
field must be applied to all atoms in the system. Consequently, `fix
efield` must be used with *group-ID* all and must not be used with the
keyword *region*. Equal-style variables can be used for electric field
vector components without any further settings. Atom-style variables can
be used for spatially-varying electric field vector components, but the
resulting electric potential must be specified as an atom-style variable
using the *potential* keyword for `fix efield`.
Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`,
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`, :doc:`fix qtpie/reaxff <fix_qtpie_reaxff>`
Default
"""""""
scale = 1.0 and maxiter = 200
----------
.. _Rappe4:
**(Rappe)** Rappe and Goddard III, Journal of Physical Chemistry, 95,
3358-3363 (1991).
.. _qeq-Aktulga3:
**(Aktulga)** Aktulga, Fogarty, Pandit, Grama, Parallel Computing, 38,
245-259 (2012).

43
doc/src/fix_qtpie_reaxff.rst
View File

@ -21,8 +21,10 @@ Syntax
.. parsed-literal::
keyword = *maxiter*
keyword = *scale* or *maxiter* or *nowarn*
*scale* beta = set value of scaling factor *beta* (determines strength of electric polarization)
*maxiter* N = limit the number of iterations to *N*
*nowarn* = do not print a warning message if the maximum number of iterations is reached
Examples
""""""""
@ -30,7 +32,7 @@ Examples
.. code-block:: LAMMPS
fix 1 all qtpie/reaxff 1 0.0 10.0 1.0e-6 reaxff exp.qtpie
fix 1 all qtpie/reaxff 1 0.0 10.0 1.0e-6 params.qtpie exp.qtpie maxiter 500
fix 1 all qtpie/reaxff 1 0.0 10.0 1.0e-6 params.qtpie exp.qtpie scale 1.5 maxiter 500 nowarn
Description
"""""""""""
@ -46,7 +48,7 @@ same way as the QEq method but where the absolute electronegativity,
electronegativity given by :ref:`(Chen) <qtpie-Chen>`
.. math::
\chi_{\mathrm{eff},i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j) S_{ij}}
\tilde{\chi}_{i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j) S_{ij}}
{\sum_{m=1}^{N}S_{im}},
which acts to penalize long-range charge transfer seen with the QEq charge
@ -61,11 +63,11 @@ electric field by using the effective electronegativity given in
:ref:`(Gergs) <Gergs>`:
.. math::
\chi_{\mathrm{eff},i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j + \phi_i - \phi_j) S_{ij}}
\tilde{\chi}_{\mathrm{r}i} = \frac{\sum_{j=1}^{N} (\chi_i - \chi_j + \beta(\phi_i - \phi_j)) S_{ij}}
{\sum_{m=1}^{N}S_{im}},
where :math:`\phi_i` and :math:`\phi_j` are the electric
potentials at the positions of atom :math:`i` and :math:`j`
where :math:`\beta` is a scaling factor and :math:`\phi_i` and :math:`\phi_j`
are the electric potentials at the positions of atoms :math:`i` and :math:`j`
due to the external electric field.
This fix is typically used in conjunction with the ReaxFF force
@ -74,9 +76,12 @@ command, but it can be used with any potential in LAMMPS, so long as it
defines and uses charges on each atom. For more technical details about the
charge equilibration performed by `fix qtpie/reaxff`, which is the same as in
:doc:`fix qeq/reaxff <fix_qeq_reaxff>` except for the use of
:math:`\chi_{\mathrm{eff},i}`, please refer to :ref:`(Aktulga) <qeq-Aktulga2>`.
:math:`\tilde{\chi}_{i}` or :math:`\tilde{\chi}_{\mathrm{r}i}`,
please refer to :ref:`(Aktulga) <qeq-Aktulga2>`.
To be explicit, this fix replaces :math:`\chi_k` of eq. 3 in
:ref:`(Aktulga) <qeq-Aktulga2>` with :math:`\chi_{\mathrm{eff},k}`.
:ref:`(Aktulga) <qeq-Aktulga2>` with :math:`\tilde{\chi}_{k}` when no external
electric field is applied and with :math:`\tilde{\chi}_{\mathrm{r}k}` when an
external electric field is applied.
This fix requires the absolute electronegativity, :math:`\chi`, in eV, the
self-Coulomb potential, :math:`\eta`, in eV, and the shielded Coulomb
@ -97,7 +102,7 @@ respectively:
where *itype* is the atom type from 1 to Ntypes. Note that eta is
defined here as twice the eta value in the ReaxFF file.
The overlap integrals in the equation for :math:`\chi_{\mathrm{eff},i}`
The overlap integrals :math:`S_{ij}`
are computed by using normalized 1s Gaussian type orbitals. The Gaussian
orbital exponents, :math:`\alpha`, that are needed to compute the overlap
integrals are taken from the file given by *gfile*.
@ -120,15 +125,26 @@ Empty lines or any text following the pound sign (#) are ignored. An example
1 0.2240 # O
2 0.5434 # H
The optional *scale* keyword sets the value of :math:`\beta` in the equation for
:math:`\tilde{\chi}_{\mathrm{r}i}`. This keyword only affects the computed charges
when :doc:`fix efield <fix_efield>` is used. The default value is 1.0.
The optional *maxiter* keyword allows changing the max number
of iterations in the linear solver. The default value is 200.
The optional *nowarn* keyword silences the warning message printed
when the maximum number of iterations is reached. This can be
useful for comparing serial and parallel results where having the
same fixed number of iterations is desired, which can be achieved
by using a very small tolerance and setting *maxiter* to the desired
number of iterations.
.. note::
In order to solve the self-consistent equations for electronegativity
equalization, LAMMPS imposes the additional constraint that all the
charges in the fix group must add up to zero. The initial charge
assignments should also satisfy this constraint. LAMMPS will print a
charges in the fix group must add up to zero. The initial charge
assignments should also satisfy this constraint. LAMMPS will print a
warning if that is not the case.
Restart, fix_modify, output, run start/stop, minimize info
@ -170,12 +186,13 @@ Related commands
""""""""""""""""
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`,
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`
:doc:`fix acks2/reaxff <fix_acks2_reaxff>`,
:doc:`fix qeq/rel/reaxff <fix_qeq_rel_reaxff>`
Default
"""""""
maxiter 200
scale = 1.0 and maxiter = 200
----------

32
doc/src/fix_reaxff_bonds.rst
View File

@ -56,16 +56,28 @@ If the filename ends with ".gz", the output file is written in gzipped
format. A gzipped dump file will be about 3x smaller than the text
version, but will also take longer to write.
.. versionadded:: 2Apr2025
If the filename contains the wildcard character "\*", a new file is
created on every timestep there bond information is written. The "\*"
character is replaced with the timestep value. Note that the
:doc:`fix_modify pad <fix_modify>` command can be used so that all
timestep numbers have the same length by adding leading zeroes
(e.g. 00010 for a pad value of 5). The default pad value is 0, i.e. no
leading zeroes.
----------
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
No information about this fix is written to :doc:`binary restart files <restart>`. None of the :doc:`fix_modify <fix_modify>` options
are relevant to this fix. No global or per-atom quantities are stored
by this fix for access by various :doc:`output commands <Howto_output>`.
No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minimization <minimize>`.
No information about this fix is written to :doc:`binary restart files
<restart>`. This fix supports the :doc:`fix_modify pad <fix_modify>`
option. No global or per-atom quantities are stored by this fix for
access by various :doc:`output commands <Howto_output>`. No parameter
of this fix can be used with the *start/stop* keywords of the :doc:`run
<run>` command. This fix is not invoked during :doc:`energy
minimization <minimize>`.
----------
@ -76,10 +88,10 @@ the :doc:`run <run>` command. This fix is not invoked during :doc:`energy minim
Restrictions
""""""""""""
The fix reaxff/bonds command requires that the :doc:`pair_style reaxff <pair_reaxff>` is invoked. This fix is part of the
REAXFF package. It is only enabled if LAMMPS was built with that
package. See the :doc:`Build package <Build_package>` page for more
info.
The fix reaxff/bonds command requires that the :doc:`pair_style reaxff
<pair_reaxff>` is invoked. This fix is part of the REAXFF package. It
is only enabled if LAMMPS was built with that package. See the
:doc:`Build package <Build_package>` page for more info.
To write gzipped bond files, you must compile LAMMPS with the
-DLAMMPS_GZIP option.
@ -92,4 +104,4 @@ Related commands
Default
"""""""
none
pad = 0

3
doc/src/fix_reaxff_species.rst
View File

@ -207,6 +207,9 @@ No parameter of this fix can be used with the *start/stop* keywords of
the :doc:`run <run>` command.
This fix is not invoked during :doc:`energy minimization <minimize>`.
This fix supports dynamic groups only if the *Nrepeat* setting is 1,
i.e. there is no averaging.
----------
.. include:: accel_styles.rst

2
doc/src/fix_wall_piston.rst
View File

@ -33,7 +33,7 @@ Syntax
*box* = the wall position is defined in simulation box units
..
FIXME: There are several "undocumented" key words for this fix: *rough*,
FIXME: There are several "undocumented" keywords for this fix: *rough*,
*rampNL1*, *rampNL2*, *rampNL3*, *rampNL4*, and *rampNL5*.
Examples

Some files were not shown because too many files have changed in this diff Show More