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

Merge branch 'develop' into Iximiel/develop

Browse Source
This commit is contained in:
Axel Kohlmeyer
2022-04-27 14:15:10 -04:00
parent 47f3f9d44a 691ba89b6f
commit 75d42a87e5
4535 changed files with 343096 additions and 522642 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/src/Bibliography.rst
View File

@ -1123,9 +1123,12 @@ Bibliography
**(Sun)**
Sun, J. Phys. Chem. B, 102, 7338-7364 (1998).
**(Surblys)**
**(Surblys2019)**
Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
**(Surblys2021)**
Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).
**(Sutmann)**
Sutmann, Arnold, Fahrenberger, et. al., Physical review / E 88(6), 063308 (2013)

20
doc/src/Build_development.rst
View File

@ -185,6 +185,10 @@ The ``ctest`` command has many options, the most important ones are:
- run subset of tests matching the regular expression <regex>
* - -E <regex>
- exclude subset of tests matching the regular expression <regex>
* - -L <regex>
- run subset of tests with a label matching the regular expression <regex>
* - -LE <regex>
- exclude subset of tests with a label matching the regular expression <regex>
* - -N
- dry-run: display list of tests without running them
* - -T memcheck
@ -299,6 +303,12 @@ will destroy the original file, if the generation run does not complete,
so using *-g* is recommended unless the YAML file is fully tested
and working.
Some of the force style tests are rather slow to run and some are very
sensitive to small differences like CPU architecture, compiler
toolchain, compiler optimization. Those tests are flagged with a "slow"
and/or "unstable" label, and thus those tests can be selectively
excluded with the ``-LE`` flag or selected with the ``-L`` flag.
.. admonition:: Recommendations and notes for YAML files
:class: note
@ -476,14 +486,14 @@ The following options are available.
make fix-whitespace # correct whitespace issues in files
make check-homepage # search for files with old LAMMPS homepage URLs
make fix-homepage # correct LAMMPS homepage URLs in files
make check-errordocs # search for deprecated error docs in header files
make fix-errordocs # remove error docs in header files
make check-permissions # search for files with permissions issues
make fix-permissions # correct permissions issues in files
make check # run all check targets from above
These should help to replace all TAB characters with blanks and remove
any trailing whitespace. Also all LAMMPS homepage URL references can be
updated to the location change from Sandia to the lammps.org domain.
And the permission check can remove executable permissions from non-executable
files (like source code).
These should help to make source and documentation files conforming
to some the coding style preferences of the LAMMPS developers.
Clang-format support
--------------------

96
doc/src/Build_extras.rst
View File

@ -45,7 +45,6 @@ This is the list of packages that may require additional steps.
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
* :ref:`MESSAGE <message>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-IAP <mliap>`
* :ref:`ML-PACE <ml-pace>`
@ -142,8 +141,6 @@ CMake build
:code:`GPU_ARCH` settings for different GPU hardware is as follows:
* sm_12 or sm_13 for GT200 (supported by CUDA 3.2 until CUDA 6.5)
* sm_20 or sm_21 for Fermi (supported by CUDA 3.2 until CUDA 7.5)
* sm_30 for Kepler (supported since CUDA 5 and until CUDA 10.x)
* sm_35 or sm_37 for Kepler (supported since CUDA 5 and until CUDA 11.x)
* sm_50 or sm_52 for Maxwell (supported since CUDA 6)
@ -161,6 +158,12 @@ Thus the GPU_ARCH setting is merely an optimization, to have code for
the preferred GPU architecture directly included rather than having to wait
for the JIT compiler of the CUDA driver to translate it.
When compiling for CUDA or HIP with CUDA, version 8.0 or later of the CUDA toolkit
is required and a GPU architecture of Kepler or later, which must *also* be
supported by the CUDA toolkit in use **and** the CUDA driver in use.
When compiling for OpenCL, OpenCL version 1.2 or later is required and the
GPU must be supported by the GPU driver and OpenCL runtime bundled with the driver.
When building with CMake, you **must NOT** build the GPU library in ``lib/gpu``
using the traditional build procedure. CMake will detect files generated by that
process and will terminate with an error and a suggestion for how to remove them.
@ -341,6 +344,18 @@ minutes to hours) to build. Of course you only need to do that once.)
$ make lib-kim args="-p /usr/local" # use an existing KIM API installation at the provided location
$ make lib-kim args="-p /usr/local -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # ditto but add one model or driver
When using the "-b " option, the KIM library is built using its native
cmake build system. The ``lib/kim/Install.py`` script supports a
``CMAKE`` environment variable if the cmake executable is named other
than ``cmake`` on your system. Additional environment variables may be
provided on the command line for use by cmake. For example, to use the
``cmake3`` executable and tell it to use the gnu version 11 compilers
to build KIM, one could use the following command line.
.. code-block:: bash
$ CMAKE=cmake3 CXX=g++-11 CC=gcc-11 FC=gfortran-11 make lib-kim args="-b " # (re-)install KIM API lib using cmake3 and gnu v11 compilers with only example models
Settings for debugging OpenKIM web queries discussed below need to
be applied by adding them to the ``LMP_INC`` variable through
editing the ``Makefile.machine`` you are using. For example:
@ -560,11 +575,26 @@ They must be specified in uppercase.
* - VEGA908
- GPU
- AMD GPU MI100 GFX908
* - INTEL_GEN
* - VEGA90A
- GPU
- Intel GPUs Gen9+
- AMD GPU
* - INTEL_DG1
- GPU
- Intel Iris XeMAX GPU
* - INTEL_GEN9
- GPU
- Intel GPU Gen9
* - INTEL_GEN11
- GPU
- Intel GPU Gen11
* - INTEL_GEN12LP
- GPU
- Intel GPU Gen12LP
* - INTEL_XEHP
- GPU
- Intel GPUs Xe-HP
This list was last updated for version 3.4.1 of the Kokkos library.
This list was last updated for version 3.5.0 of the Kokkos library.
.. tabs::
@ -611,13 +641,14 @@ This list was last updated for version 3.4.1 of the Kokkos library.
-D CMAKE_CXX_COMPILER=${HOME}/lammps/lib/kokkos/bin/nvcc_wrapper
To simplify compilation, three preset files are included in the
To simplify compilation, four preset files are included in the
``cmake/presets`` folder, ``kokkos-serial.cmake``,
``kokkos-openmp.cmake``, and ``kokkos-cuda.cmake``. They will
enable the KOKKOS package and enable some hardware choice. So to
compile with OpenMP host parallelization, CUDA device
parallelization (for GPUs with CC 5.0 and up) with some common
packages enabled, you can do the following:
``kokkos-openmp.cmake``, ``kokkos-cuda.cmake``, and
``kokkos-sycl.cmake``. They will enable the KOKKOS package and
enable some hardware choice. So to compile with OpenMP host
parallelization, CUDA device parallelization (for GPUs with CC 5.0
and up) with some common packages enabled, you can do the
following:
.. code-block:: bash
@ -769,47 +800,6 @@ library.
----------
.. _message:
MESSAGE package
-----------------------------
This package can optionally include support for messaging via sockets,
using the open-source `ZeroMQ library <http://zeromq.org>`_, which must
be installed on your system.
.. tabs::
.. tab:: CMake build
.. code-block:: bash
-D MESSAGE_ZMQ=value # build with ZeroMQ support, value = no (default) or yes
-D ZMQ_LIBRARY=path # ZMQ library file (only needed if a custom location)
-D ZMQ_INCLUDE_DIR=path # ZMQ include directory (only needed if a custom location)
.. tab:: Traditional make
Before building LAMMPS, you must build the CSlib library in
``lib/message``\ . You can build the CSlib library manually if
you prefer; follow the instructions in ``lib/message/README``\ .
You can also do it in one step from the ``lammps/src`` dir, using
a command like these, which simply invoke the
``lib/message/Install.py`` script with the specified args:
.. code-block:: bash
$ make lib-message # print help message
$ make lib-message args="-m -z" # build with MPI and socket (ZMQ) support
$ make lib-message args="-s" # build as serial lib with no ZMQ support
The build should produce two files: ``lib/message/cslib/src/libmessage.a``
and ``lib/message/Makefile.lammps``. The latter is copied from an
existing ``Makefile.lammps.*`` and has settings to link with the ZeroMQ
library if requested in the build.
----------
.. _mliap:
ML-IAP package

14
doc/src/Build_manual.rst
View File

@ -78,11 +78,12 @@ folder. The following ``make`` commands are available:
make html # generate HTML in html dir using Sphinx
make pdf # generate PDF as Manual.pdf using Sphinx and PDFLaTeX
make fetch # fetch HTML pages and PDF files from LAMMPS website
# and unpack into the html_www folder and Manual_www.pdf
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 clean # remove intermediate RST files created by HTML build
make clean-all # remove entire build folder and any cached data
@ -193,8 +194,13 @@ folder need to be updated or new files added. These files are written in
`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
Before contributing any documentation, please check that both the HTML
and the PDF format documentation can translate without errors. Please also
check the output to the console for any warnings or problems. There will
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.
Please also check the output to the console for any warnings or problems. There will
be multiple tests run automatically:
- A test for correctness of all anchor labels and their references

1
doc/src/Build_package.rst
View File

@ -45,7 +45,6 @@ packages:
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MESSAGE <message>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-PACE <ml-pace>`
* :ref:`ML-QUIP <ml-quip>`

18
doc/src/Build_settings.rst
View File

@ -4,15 +4,15 @@ Optional build settings
LAMMPS can be built with several optional settings. Each sub-section
explain how to do this for building both with CMake and make.
* :ref:`C++11 standard compliance <cxx11>` when building all of LAMMPS
* :ref:`FFT library <fft>` for use with the :doc:`kspace_style pppm <kspace_style>` command
* :ref:`Size of LAMMPS integer types <size>`
* :ref:`Read or write compressed files <gzip>`
* :ref:`Output of JPG and PNG files <graphics>` via the :doc:`dump image <dump_image>` command
* :ref:`Output of movie files <graphics>` via the :doc:`dump_movie <dump_image>` command
* :ref:`Memory allocation alignment <align>`
* :ref:`Workaround for long long integers <longlong>`
* :ref:`Error handling exceptions <exceptions>` when using LAMMPS as a library
* `C++11 standard compliance`_ when building all of LAMMPS
* `FFT library`_ for use with the :doc:`kspace_style pppm <kspace_style>` command
* `Size of LAMMPS integer types and size limits`_
* `Read or write compressed files`_
* `Output of JPG, PNG, and move files` via the :doc:`dump image <dump_image>` or :doc:`dump movie <dump_image>` commands
* `Memory allocation alignment`_
* `Workaround for long long integers`_
* `Exception handling when using LAMMPS as a library`_ to capture errors
* `Trigger selected floating-point exceptions`_
----------

97
doc/src/Build_windows.rst
View File

@ -16,44 +16,52 @@ General remarks
LAMMPS is developed and tested primarily on Linux machines. The vast
majority of HPC clusters and supercomputers today run on Linux as well.
While portability to other platforms is desired, it is not always achieved.
The LAMMPS developers are dependent on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This is particularly
true for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality.
While portability to other platforms is desired, it is not always
achieved. That is sometimes due to non-portable code in LAMMPS itself,
but more often due to portability limitations of external libraries and
tools required to build a specific feature or package. The LAMMPS
developers are dependent on LAMMPS users giving feedback and providing
assistance in resolving portability issues. This is particularly true
for compiling LAMMPS on Windows, since this platform has significant
differences in some low-level functionality. As of LAMMPS version 14
December 2021, large parts of LAMMPS can be compiled natively with the
Microsoft Visual C++ Compilers. This is largely facilitated by using
the :doc:`Developer_platform` in the ``platform`` namespace.
Before trying to build LAMMPS on Windows yourself, please consider the
`pre-compiled Windows installer packages <https://packages.lammps.org/windows.html>`_
and see if they are sufficient for your needs.
.. _linux:
Running Linux on Windows
^^^^^^^^^^^^^^^^^^^^^^^^
Before trying to build LAMMPS on Windows, please consider if the
pre-compiled Windows binary packages are sufficient for your needs. If
it is necessary for you to compile LAMMPS on a Windows machine
If it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10 or
Windows 11 installation - consider using the Windows subsystem for
Linux. This optional Windows feature allows you to run the bash shell
from Ubuntu from within Windows and from there on, you can pretty much
use that shell like you are running on an Ubuntu Linux machine
(e.g. installing software via apt-get and more). For more details on
that, please see :doc:`this tutorial <Howto_wsl>`.
of a Linux system (Ubuntu by default) from within Windows and from there
on, you can pretty much use that shell like you are running on a regular
Ubuntu Linux machine (e.g. installing software via apt-get and more).
For more details on that, please see :doc:`this tutorial <Howto_wsl>`.
.. _gnu:
Using a GNU GCC ported to Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One option for compiling LAMMPS on Windows natively that has been known
to work in the past is to install a bash shell, unix shell utilities,
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin
package provides a unix/linux interface to low-level Windows functions,
so LAMMPS can be compiled on Windows. The necessary (minor)
modifications to LAMMPS are included, but may not always up-to-date for
recently added functionality and the corresponding new code. A machine
makefile for using cygwin for the old build system is provided. Using
CMake for this mode of compilation is untested and not likely to work.
One option for compiling LAMMPS on Windows natively is to install a Bash
shell, Unix shell utilities, Perl, Python, GNU make, and a GNU compiler
ported to Windows. The Cygwin package provides a unix/linux interface
to low-level Windows functions, so LAMMPS can be compiled on Windows.
The necessary (minor) modifications to LAMMPS are included, but may not
always up-to-date for recently added functionality and the corresponding
new code. A machine makefile for using cygwin for the old build system
is provided. Using CMake for this mode of compilation is untested and
not likely to work.
When compiling for Windows do **not** set the ``-DLAMMPS_MEMALIGN``
define in the LMP_INC makefile variable and add ``-lwsock32 -lpsapi`` to
@ -65,8 +73,9 @@ configuration should set this up automatically, but is untested.
In case of problems, you are recommended to contact somebody with
experience in using Cygwin. If you do come across portability problems
requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
yourself, please report them on the
`LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
or file them as an issue or pull request on the LAMMPS GitHub project.
.. _msvc:
@ -75,19 +84,27 @@ Using Microsoft Visual Studio
Following the integration of the :doc:`platform namespace
<Developer_platform>` into the LAMMPS code base, portability of LAMMPS
to be compiled on Windows using Visual Studio has been significantly
improved. This has been tested with Visual Studio 2019 (aka version
16). Not all features and packages in LAMMPS are currently supported
out of the box, but a preset ``cmake/presets/windows.cmake`` is provided
that contains the packages that have been compiled successfully. You
must use the CMake based build procedure, and either use the integrated
CMake support of Visual Studio or use an external CMake installation to
create build files for the Visual Studio build system. Please note that
on launching Visual Studio it will scan the directory tree and likely
miss the correct master ``CMakeLists.txt``. Try to open the
``cmake/CMakeSettings.json`` and use those CMake configurations as a
starting point. It is also possible to configure and compile LAMMPS
from the command line with a CMake binary from `cmake.org <https://cmake.org>`_.
for native compilation on Windows using Visual Studio has been
significantly improved. This has been tested with Visual Studio 2019
(aka version 16) and Visual Studio 2022 (aka version 17). We strongly
recommend using Visual Studio 2022 version 17.1 or later. Not all
features and packages in LAMMPS are currently supported out of the box,
but a preset ``cmake/presets/windows.cmake`` is provided that contains
the packages that have been compiled successfully so far. You **must**
use the CMake based build procedure, since there is no support for GNU
make or the Unix shell utilities required for the GNU make build
procedure.
It is possible to use both the integrated CMake support of the Visual
Studio IDE or use an external CMake installation (e.g. downloaded from
cmake.org) to create build files and compile LAMMPS from the command line.
.. note::
Versions of Visual Studio before version 17.1 may scan the entire
LAMMPS source tree and likely miss the correct master
``CMakeLists.txt`` and get confused since there are multiple files
of that name in different folders but none in top level folder.
Please note, that for either approach CMake will create a so-called
:ref:`"multi-configuration" build environment <cmake_multiconfig>`, and
@ -98,9 +115,11 @@ To support running in parallel you can compile with OpenMP enabled using
the OPENMP package or install Microsoft MPI (including the SDK) and compile
LAMMPS with MPI enabled.
This is work in progress and you should contact the LAMMPS developers
via GitHub, the forum, or the mailing list, if you have questions or
LAMMPS specific problems.
.. note::
This is work in progress and you should contact the LAMMPS developers
via GitHub or the `LAMMPS forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_,
if you have questions or LAMMPS specific problems.
.. _cross:

8
doc/src/Commands_all.rst
View File

@ -47,7 +47,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`
* :doc:`dump_modify <dump_modify>`
* :doc:`dynamical_matrix <dynamical_matrix>`
* :doc:`dynamical_matrix (k) <dynamical_matrix>`
* :doc:`echo <echo>`
* :doc:`fix <fix>`
* :doc:`fix_modify <fix_modify>`
@ -67,8 +67,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`lattice <lattice>`
* :doc:`log <log>`
* :doc:`mass <mass>`
* :doc:`mdi/engine <mdi_engine>`
* :doc:`message <message>`
* :doc:`mdi <mdi>`
* :doc:`minimize <minimize>`
* :doc:`min_modify <min_modify>`
* :doc:`min_style <min_style>`
@ -105,7 +104,6 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`restart <restart>`
* :doc:`run <run>`
* :doc:`run_style <run_style>`
* :doc:`server <server>`
* :doc:`set <set>`
* :doc:`shell <shell>`
* :doc:`special_bonds <special_bonds>`
@ -117,7 +115,7 @@ An alphabetic list of all general LAMMPS commands.
* :doc:`thermo <thermo>`
* :doc:`thermo_modify <thermo_modify>`
* :doc:`thermo_style <thermo_style>`
* :doc:`third_order <third_order>`
* :doc:`third_order (k) <third_order>`
* :doc:`timer <timer>`
* :doc:`timestep <timestep>`
* :doc:`uncompute <uncompute>`

3
doc/src/Commands_bond.rst
View File

@ -32,9 +32,12 @@ OPT.
*
*
*
* :doc:`bpm/rotational <bond_bpm_rotational>`
* :doc:`bpm/spring <bond_bpm_spring>`
* :doc:`class2 (ko) <bond_class2>`
* :doc:`fene (iko) <bond_fene>`
* :doc:`fene/expand (o) <bond_fene_expand>`
* :doc:`fene/nm <bond_fene>`
* :doc:`gaussian <bond_gaussian>`
* :doc:`gromos (o) <bond_gromos>`
* :doc:`harmonic (iko) <bond_harmonic>`

8
doc/src/Commands_compute.rst
View File

@ -28,10 +28,12 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`angle <compute_angle>`
* :doc:`angle/local <compute_angle_local>`
* :doc:`angmom/chunk <compute_angmom_chunk>`
* :doc:`ave/sphere/atom (k) <compute_ave_sphere_atom>`
* :doc:`basal/atom <compute_basal_atom>`
* :doc:`body/local <compute_body_local>`
* :doc:`bond <compute_bond>`
* :doc:`bond/local <compute_bond_local>`
* :doc:`born/matrix <compute_born_matrix>`
* :doc:`centro/atom <compute_centro_atom>`
* :doc:`centroid/stress/atom <compute_stress_atom>`
* :doc:`chunk/atom <compute_chunk_atom>`
@ -62,6 +64,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`event/displace <compute_event_displace>`
* :doc:`fabric <compute_fabric>`
* :doc:`fep <compute_fep>`
* :doc:`fep/ta <compute_fep_ta>`
* :doc:`force/tally <compute_tally>`
* :doc:`fragment/atom <compute_cluster_atom>`
* :doc:`global/atom <compute_global_atom>`
@ -89,6 +92,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`msd <compute_msd>`
* :doc:`msd/chunk <compute_msd_chunk>`
* :doc:`msd/nongauss <compute_msd_nongauss>`
* :doc:`nbond/atom <compute_nbond_atom>`
* :doc:`omega/chunk <compute_omega_chunk>`
* :doc:`orientorder/atom (k) <compute_orientorder_atom>`
* :doc:`pair <compute_pair>`
@ -99,7 +103,6 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`pe/tally <compute_tally>`
* :doc:`plasticity/atom <compute_plasticity_atom>`
* :doc:`pressure <compute_pressure>`
* :doc:`pressure/cylinder <compute_pressure_cylinder>`
* :doc:`pressure/uef <compute_pressure_uef>`
* :doc:`property/atom <compute_property_atom>`
* :doc:`property/chunk <compute_property_chunk>`
@ -142,8 +145,11 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`sph/t/atom <compute_sph_t_atom>`
* :doc:`spin <compute_spin>`
* :doc:`stress/atom <compute_stress_atom>`
* :doc:`stress/cartesian <compute_stress_profile>`
* :doc:`stress/cylinder <compute_stress_profile>`
* :doc:`stress/mop <compute_stress_mop>`
* :doc:`stress/mop/profile <compute_stress_mop>`
* :doc:`stress/spherical <compute_stress_profile>`
* :doc:`stress/tally <compute_tally>`
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>`
* :doc:`temp (k) <compute_temp>`

10
doc/src/Commands_fix.rst
View File

@ -51,10 +51,10 @@ OPT.
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
* :doc:`charge/regulation <fix_charge_regulation>`
* :doc:`client/md <fix_client_md>`
* :doc:`cmap <fix_cmap>`
* :doc:`colvars <fix_colvars>`
* :doc:`controller <fix_controller>`
* :doc:`damping/cundall <fix_damping_cundall>`
* :doc:`deform (k) <fix_deform>`
* :doc:`deposit <fix_deposit>`
* :doc:`dpd/energy (k) <fix_dpd_energy>`
@ -97,12 +97,10 @@ OPT.
* :doc:`latte <fix_latte>`
* :doc:`lb/fluid <fix_lb_fluid>`
* :doc:`lb/momentum <fix_lb_momentum>`
* :doc:`lb/pc <fix_lb_pc>`
* :doc:`lb/rigid/pc/sphere <fix_lb_rigid_pc_sphere>`
* :doc:`lb/viscous <fix_lb_viscous>`
* :doc:`lineforce <fix_lineforce>`
* :doc:`manifoldforce <fix_manifoldforce>`
* :doc:`mdi/engine <fix_mdi_engine>`
* :doc:`mdi/aimd <fix_mdi_aimd>`
* :doc:`meso/move <fix_meso_move>`
* :doc:`mol/swap <fix_mol_swap>`
* :doc:`momentum (k) <fix_momentum>`
@ -129,6 +127,7 @@ OPT.
* :doc:`npt/sphere (o) <fix_npt_sphere>`
* :doc:`npt/uef <fix_nh_uef>`
* :doc:`numdiff <fix_numdiff>`
* :doc:`numdiff/virial <fix_numdiff_virial>`
* :doc:`nve (giko) <fix_nve>`
* :doc:`nve/asphere (gi) <fix_nve_asphere>`
* :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>`
@ -142,6 +141,7 @@ OPT.
* :doc:`nve/manifold/rattle <fix_nve_manifold_rattle>`
* :doc:`nve/noforce <fix_nve_noforce>`
* :doc:`nve/sphere (ko) <fix_nve_sphere>`
* :doc:`nve/bpm/sphere <fix_nve_bpm_sphere>`
* :doc:`nve/spin <fix_nve_spin>`
* :doc:`nve/tri <fix_nve_tri>`
* :doc:`nvk <fix_nvk>`
@ -159,7 +159,6 @@ OPT.
* :doc:`orient/fcc <fix_orient>`
* :doc:`orient/eco <fix_orient_eco>`
* :doc:`pafi <fix_pafi>`
* :doc:`pair/tracker <fix_pair_tracker>`
* :doc:`phonon <fix_phonon>`
* :doc:`pimd <fix_pimd>`
* :doc:`planeforce <fix_planeforce>`
@ -244,6 +243,7 @@ OPT.
* :doc:`vector <fix_vector>`
* :doc:`viscosity <fix_viscosity>`
* :doc:`viscous <fix_viscous>`
* :doc:`viscous/sphere <fix_viscous_sphere>`
* :doc:`wall/body/polygon <fix_wall_body_polygon>`
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`
* :doc:`wall/colloid <fix_wall>`

18
doc/src/Commands_pair.rst
View File

@ -53,6 +53,7 @@ OPT.
* :doc:`born/coul/msm (o) <pair_born>`
* :doc:`born/coul/wolf (go) <pair_born>`
* :doc:`born/coul/wolf/cs (g) <pair_cs>`
* :doc:`bpm/spring <pair_bpm_spring>`
* :doc:`brownian (o) <pair_brownian>`
* :doc:`brownian/poly (o) <pair_brownian>`
* :doc:`buck (giko) <pair_buck>`
@ -88,12 +89,12 @@ OPT.
* :doc:`coul/tt <pair_coul_tt>`
* :doc:`coul/wolf (ko) <pair_coul>`
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (gio) <pair_dpd>`
* :doc:`dpd (giko) <pair_dpd>`
* :doc:`dpd/fdt <pair_dpd_fdt>`
* :doc:`dpd/ext <pair_dpd_ext>`
* :doc:`dpd/ext/tstat <pair_dpd_ext>`
* :doc:`dpd/ext (k) <pair_dpd_ext>`
* :doc:`dpd/ext/tstat (k) <pair_dpd_ext>`
* :doc:`dpd/fdt/energy (k) <pair_dpd_fdt>`
* :doc:`dpd/tstat (go) <pair_dpd>`
* :doc:`dpd/tstat (gko) <pair_dpd>`
* :doc:`dsmc <pair_dsmc>`
* :doc:`e3b <pair_e3b>`
* :doc:`drip <pair_drip>`
@ -119,10 +120,12 @@ OPT.
* :doc:`granular <pair_granular>`
* :doc:`gw <pair_gw>`
* :doc:`gw/zbl <pair_gw>`
* :doc:`harmonic/cut (o) <pair_harmonic_cut>`
* :doc:`hbond/dreiding/lj (o) <pair_hbond_dreiding>`
* :doc:`hbond/dreiding/morse (o) <pair_hbond_dreiding>`
* :doc:`hdnnp <pair_hdnnp>`
* :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>`
* :doc:`ilp/graphene/hbn (t) <pair_ilp_graphene_hbn>`
* :doc:`ilp/tmd <pair_ilp_tmd>`
* :doc:`kolmogorov/crespi/full <pair_kolmogorov_crespi_full>`
* :doc:`kolmogorov/crespi/z <pair_kolmogorov_crespi_z>`
* :doc:`lcbop <pair_lcbop>`
@ -149,7 +152,7 @@ OPT.
* :doc:`lj/cut/coul/cut/dielectric (o) <pair_dielectric>`
* :doc:`lj/cut/coul/cut/soft (o) <pair_fep_soft>`
* :doc:`lj/cut/coul/debye (gko) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/debye/dielectric <pair_dielectric>`
* :doc:`lj/cut/coul/debye/dielectric (o) <pair_dielectric>`
* :doc:`lj/cut/coul/dsf (gko) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/long (gikot) <pair_lj_cut_coul>`
* :doc:`lj/cut/coul/long/cs <pair_cs>`
@ -210,6 +213,7 @@ OPT.
* :doc:`nm/cut (o) <pair_nm>`
* :doc:`nm/cut/coul/cut (o) <pair_nm>`
* :doc:`nm/cut/coul/long (o) <pair_nm>`
* :doc:`nm/cut/split <pair_nm>`
* :doc:`oxdna/coaxstk <pair_oxdna>`
* :doc:`oxdna/excv <pair_oxdna>`
* :doc:`oxdna/hbond <pair_oxdna>`
@ -239,6 +243,7 @@ OPT.
* :doc:`reaxff (ko) <pair_reaxff>`
* :doc:`rebo (io) <pair_airebo>`
* :doc:`resquared (go) <pair_resquared>`
* :doc:`saip/metal <pair_saip_metal>`
* :doc:`sdpd/taitwater/isothermal <pair_sdpd_taitwater_isothermal>`
* :doc:`smatb <pair_smatb>`
* :doc:`smatb/single <pair_smatb>`
@ -264,6 +269,7 @@ OPT.
* :doc:`spin/neel <pair_spin_neel>`
* :doc:`srp <pair_srp>`
* :doc:`sw (giko) <pair_sw>`
* :doc:`sw/mod (o) <pair_sw>`
* :doc:`table (gko) <pair_table>`
* :doc:`table/rx (k) <pair_table_rx>`
* :doc:`tdpd <pair_mesodpd>`

2
doc/src/Developer.rst
View File

@ -11,7 +11,9 @@ of time and requests from the LAMMPS user community.
:maxdepth: 1
Developer_org
Developer_code_design
Developer_parallel
Developer_comm_ops
Developer_flow
Developer_write
Developer_notes

433
doc/src/Developer_code_design.rst Normal file
View File

@ -0,0 +1,433 @@
Code design
-----------
This section explains some of the code design choices in LAMMPS with
the goal of helping developers write new code similar to the existing
code. Please see the section on :doc:`Requirements for contributed
code <Modify_style>` for more specific recommendations and guidelines.
While that section is organized more in the form of a checklist for
code contributors, the focus here is on overall code design strategy,
choices made between possible alternatives, and discussing some
relevant C++ programming language constructs.
Historically, the basic design philosophy of the LAMMPS C++ code was a
"C with classes" style. The motivation was to make it easy to modify
LAMMPS for people without significant training in C++ programming.
Data structures and code constructs were used that resemble the
previous implementation(s) in Fortran. A contributing factor to this
choice also was that at the time, C++ compilers were often not mature
and some of the advanced features contained bugs or did not function
as the standard required. There were also disagreements between
compiler vendors as to how to interpret the C++ standard documents.
However, C++ compilers have now advanced significantly. In 2020 we
decided to to require the C++11 standard as the minimum C++ language
standard for LAMMPS. Since then we have begun to also replace some of
the C-style constructs with equivalent C++ functionality, either from
the C++ standard library or as custom classes or functions, in order
to improve readability of the code and to increase code reuse through
abstraction of commonly used functionality.
.. note::
Please note that as of spring 2022 there is still a sizable chunk
of legacy code in LAMMPS that has not yet been refactored to
reflect these style conventions in full. LAMMPS has a large code
base and many different contributors and there also is a hierarchy
of precedence in which the code is adapted. Highest priority has
been the code in the ``src`` folder, followed by code in packages
in order of their popularity and complexity (simpler code is
adapted sooner), followed by code in the ``lib`` folder. Source
code that is downloaded from external packages or libraries during
compilation is not subject to the conventions discussed here.
Object oriented code
^^^^^^^^^^^^^^^^^^^^
LAMMPS is designed to be an object oriented code. Each simulation is
represented by an instance of the LAMMPS class. When running in
parallel each MPI process creates such an instance. This can be seen
in the ``main.cpp`` file where the core steps of running a LAMMPS
simulation are the following 3 lines of code:
.. code-block:: C++
LAMMPS *lammps = new LAMMPS(argc, argv, lammps_comm);
lammps->input->file();
delete lammps;
The first line creates a LAMMPS class instance and passes the command
line arguments and the global communicator to its constructor. The
second line triggers the LAMMPS instance to process the input (either
from standard input or a provided input file) until the simulation
ends. The third line deletes the LAMMPS instance. The remainder of
the main.cpp file has code for error handling, MPI configuration, and
other special features.
The basic LAMMPS class hierarchy which is created by the LAMMPS class
constructor is shown in :ref:`class-topology`. When input commands
are processed, additional class instances are created, or deleted, or
replaced. Likewise specific member functions of specific classes are
called to trigger actions such creating atoms, computing forces,
computing properties, time-propagating the system, or writing output.
Compositing and Inheritance
===========================
LAMMPS makes extensive use of the object oriented programming (OOP)
principles of *compositing* and *inheritance*. Classes like the
``LAMMPS`` class are a **composite** containing pointers to instances
of other classes like ``Atom``, ``Comm``, ``Force``, ``Neighbor``,
``Modify``, and so on. Each of these classes implement certain
functionality by storing and manipulating data related to the
simulation and providing member functions that trigger certain
actions. Some of those classes like ``Force`` are themselves
composites, containing instances of classes describing different force
interactions. Similarly the ``Modify`` class contains a list of
``Fix`` and ``Compute`` classes. If the input commands that
correspond to these classes include the word *style*, then LAMMPS
stores only a single instance of that class. E.g. *atom_style*,
*comm_style*, *pair_style*, *bond_style*. It the input command does
not include the word *style*, there can be many instances of that
class defined. E.g. *region*, *fix*, *compute*, *dump*.
**Inheritance** enables creation of *derived* classes that can share
common functionality in their base class while providing a consistent
interface. The derived classes replace (dummy or pure) functions in
the base class. The higher level classes can then call those methods
of the instantiated classes without having to know which specific
derived class variant was instantiated. In LAMMPS these derived
classes are often referred to as "styles", e.g. pair styles, fix
styles, atom styles and so on.
This is the origin of the flexibility of LAMMPS. For example pair
styles implement a variety of different non-bonded interatomic
potentials functions. All details for the implementation of a
potential are stored and executed in a single class.
As mentioned above, there can be multiple instances of classes derived
from the ``Fix`` or ``Compute`` base classes. They represent a
different facet of LAMMPS flexibility as they provide methods which
can be called at different points in time within a timestep, as
explained in `Developer_flow`. This allows the input script to tailor
how a specific simulation is run, what diagnostic computations are
performed, and how the output of those computations is further
processed or output.
Additional code sharing is possible by creating derived classes from the
derived classes (e.g., to implement an accelerated version of a pair
style) where only a subset of the derived class methods are replaced
with accelerated versions.
Polymorphism
============
Polymorphism and dynamic dispatch are another OOP feature that play an
important role in how LAMMPS selects what code to execute. In a
nutshell, this is a mechanism where the decision of which member
function to call from a class is determined at runtime and not when
the code is compiled. To enable it, the function has to be declared
as ``virtual`` and all corresponding functions in derived classes
should use the ``override`` property. Below is a brief example.
.. code-block:: c++
class Base {
public:
virtual ~Base() = default;
void call();
void normal();
virtual void poly();
};
void Base::call() {
normal();
poly();
}
class Derived : public Base {
public:
~Derived() override = default;
void normal();
void poly() override;
};
// [....]
Base *base1 = new Base();
Base *base2 = new Derived();
base1->call();
base2->call();
The difference in behavior of the ``normal()`` and the ``poly()`` member
functions is which of the two member functions is called when executing
`base1->call()` versus `base2->call()`. Without polymorphism, a
function within the base class can only call member functions within the
same scope, that is ``Base::call()`` will always call
``Base::normal()``. But for the `base2->call()` case the call of the
virtual member function will be dispatched to ``Derived::poly()``
instead. This mechanism means that functions are called within the
scope of the class type that was used to *create* the class instance are
invoked; even if they are assigned to a pointer using the type of a base
class. This is the desired behavior and this way LAMMPS can even use
styles that are loaded at runtime from a shared object file with the
:doc:`plugin command <plugin>`.
A special case of virtual functions are so-called pure functions. These
are virtual functions that are initialized to 0 in the class declaration
(see example below).
.. code-block:: c++
class Base {
public:
virtual void pure() = 0;
};
This has the effect that an instance of the base class cannot be
created and that derived classes **must** implement these functions.
Many of the functions listed with the various class styles in the
section :doc:`Modify` are pure functions. The motivation for this is
to define the interface or API of the functions but defer their
implementation to the derived classes.
However, there are downsides to this. For example, calls to virtual
functions from within a constructor, will not be in the scope of the
derived class and thus it is good practice to either avoid calling them
or to provide an explicit scope such as ``Base::poly()`` or
``Derived::poly()``. Furthermore, any destructors in classes containing
virtual functions should be declared virtual too, so they will be
processed in the expected order before types are removed from dynamic
dispatch.
.. admonition:: Important Notes
In order to be able to detect incompatibilities at compile time and
to avoid unexpected behavior, it is crucial that all member functions
that are intended to replace a virtual or pure function use the
``override`` property keyword. For the same reason, the use of
overloads or default arguments for virtual functions should be
avoided as they lead to confusion over which function is supposed to
override which and which arguments need to be declared.
Style Factories
===============
In order to create class instances for different styles, LAMMPS often
uses a programming pattern called `Factory`. Those are functions that
create an instance of a specific derived class, say ``PairLJCut`` and
return a pointer to the type of the common base class of that style,
``Pair`` in this case. To associate the factory function with the
style keyword, an ``std::map`` class is used with function pointers
indexed by their keyword (for example "lj/cut" for ``PairLJCut`` and
"morse" for ``PairMorse``). A couple of typedefs help keep the code
readable and a template function is used to implement the actual
factory functions for the individual classes. Below is an example
of such a factory function from the ``Force`` class as declared in
``force.h`` and implemented in ``force.cpp``. The file ``style_pair.h``
is generated during compilation and includes all main header files
(i.e. those starting with ``pair_``) of pair styles and then the
macro ``PairStyle()`` will associate the style name "lj/cut"
with a factory function creating an instance of the ``PairLJCut``
class.
.. code-block:: C++
// from force.h
typedef Pair *(*PairCreator)(LAMMPS *);
typedef std::map<std::string, PairCreator> PairCreatorMap;
PairCreatorMap *pair_map;
// from force.cpp
template <typename S, typename T> static S *style_creator(LAMMPS *lmp)
{
return new T(lmp);
}
// [...]
pair_map = new PairCreatorMap();
#define PAIR_CLASS
#define PairStyle(key, Class) (*pair_map)[#key] = &style_creator<Pair, Class>;
#include "style_pair.h"
#undef PairStyle
#undef PAIR_CLASS
// from pair_lj_cut.h
#ifdef PAIR_CLASS
PairStyle(lj/cut,PairLJCut);
#else
// [...]
Similar code constructs are present in other files like ``modify.cpp`` and
``modify.h`` or ``neighbor.cpp`` and ``neighbor.h``. Those contain
similar macros and include ``style_*.h`` files for creating class instances
of styles they manage.
I/O and output formatting
^^^^^^^^^^^^^^^^^^^^^^^^^
C-style stdio versus C++ style iostreams
========================================
LAMMPS uses the "stdio" library of the standard C library for reading
from and writing to files and console instead of C++ "iostreams".
This is mainly motivated by better performance, better control over
formatting, and less effort to achieve specific formatting.
Since mixing "stdio" and "iostreams" can lead to unexpected
behavior. use of the latter is strongly discouraged. Also output to
the screen should not use the predefined ``stdout`` FILE pointer, but
rather the ``screen`` and ``logfile`` FILE pointers managed by the
LAMMPS class. Furthermore, output should generally only be done by
MPI rank 0 (``comm->me == 0``). Output that is sent to both
``screen`` and ``logfile`` should use the :cpp:func:`utils::logmesg()
convenience function <LAMMPS_NS::utils::logmesg>`.
We also discourage the use of stringstreams because the bundled {fmt}
library and the customized tokenizer classes can provide the same
functionality in a cleaner way with better performance. This also
helps maintain a consistent programming syntax with code from many
different contributors.
Formatting with the {fmt} library
===================================
The LAMMPS source code includes a copy of the `{fmt} library
<https://fmt.dev>`_ which is preferred over formatting with the
"printf()" family of functions. The primary reason is that it allows
a typesafe default format for any type of supported data. This is
particularly useful for formatting integers of a given size (32-bit or
64-bit) which may require different format strings depending on
compile time settings or compilers/operating systems. Furthermore,
{fmt} gives better performance, has more functionality, a familiar
formatting syntax that has similarities to ``format()`` in Python, and
provides a facility that can be used to integrate format strings and a
variable number of arguments into custom functions in a much simpler
way than the varargs mechanism of the C library. Finally, {fmt} has
been included into the C++20 language standard, so changes to adopt it
are future-proof.
Formatted strings are frequently created by calling the
``fmt::format()`` function which will return a string as a
``std::string`` class instance. In contrast to the ``%`` placeholder
in ``printf()``, the {fmt} library uses ``{}`` to embed format
descriptors. In the simplest case, no additional characters are
needed as {fmt} will choose the default format based on the data type
of the argument. Otherwise the ``fmt::print()`` function may be
used instead of ``printf()`` or ``fprintf()``. In addition, several
LAMMPS output functions, that originally accepted a single string as
argument have been overloaded to accept a format string with optional
arguments as well (e.g., ``Error::all()``, ``Error::one()``,
``utils::logmesg()``).
Summary of the {fmt} format syntax
==================================
The syntax of the format string is "{[<argument id>][:<format spec>]}",
where either the argument id or the format spec (separated by a colon
':') is optional. The argument id is usually a number starting from 0
that is the index to the arguments following the format string. By
default these are assigned in order (i.e. 0, 1, 2, 3, 4 etc.). The most
common case for using argument id would be to use the same argument in
multiple places in the format string without having to provide it as an
argument multiple times. In LAMMPS the argument id is rarely used.
More common is the use of a format specifier, which starts with a colon.
This may optionally be followed by a fill character (default is ' '). If
provided, the fill character **must** be followed by an alignment
character ('<', '^', '>' for left, centered, or right alignment
(default)). The alignment character may be used without a fill
character. The next important format parameter would be the minimum
width, which may be followed by a dot '.' and a precision for floating
point numbers. The final character in the format string would be an
indicator for the "presentation", i.e. 'd' for decimal presentation of
integers, 'x' for hexadecimal, 'o' for octal, 'c' for character etc.
This mostly follows the "printf()" scheme but without requiring an
additional length parameter to distinguish between different integer
widths. The {fmt} library will detect those and adapt the formatting
accordingly. For floating point numbers there are correspondingly, 'g'
for generic presentation, 'e' for exponential presentation, and 'f' for
fixed point presentation.
Thus "{:8}" would represent *any* type argument using at least 8
characters; "{:<8}" would do this as left aligned, "{:^8}" as centered,
"{:>8}" as right aligned. If a specific presentation is selected, the
argument type must be compatible or else the {fmt} formatting code will
throw an exception. Some format string examples are given below:
.. code-block:: C
auto mesg = fmt::format(" CPU time: {:4d}:{:02d}:{:02d}\n", cpuh, cpum, cpus);
mesg = fmt::format("{:<8s}| {:<10.5g} | {:<10.5g} | {:<10.5g} |{:6.1f} |{:6.2f}\n",
label, time_min, time, time_max, time_sq, tmp);
utils::logmesg(lmp,"{:>6} = max # of 1-2 neighbors\n",maxall);
utils::logmesg(lmp,"Lattice spacing in x,y,z = {:.8} {:.8} {:.8}\n",
xlattice,ylattice,zlattice);
which will create the following output lines:
.. parsed-literal::
CPU time: 0:02:16
Pair | 2.0133 | 2.0133 | 2.0133 | 0.0 | 84.21
4 = max # of 1-2 neighbors
Lattice spacing in x,y,z = 1.6795962 1.6795962 1.6795962
Finally, a special feature of the {fmt} library is that format
parameters like the width or the precision may be also provided as
arguments. In that case a nested format is used where a pair of curly
braces (with an optional argument id) "{}" are used instead of the
value, for example "{:{}d}" will consume two integer arguments, the
first will be the value shown and the second the minimum width.
For more details and examples, please consult the `{fmt} syntax
documentation <https://fmt.dev/latest/syntax.html>`_ website.
Memory management
^^^^^^^^^^^^^^^^^
Dynamical allocation of small data and objects can be done with the
the C++ commands "new" and "delete/delete[]. Large data should use
the member functions of the ``Memory`` class, most commonly,
``Memory::create()``, ``Memory::grow()``, and ``Memory::destroy()``,
which provide variants for vectors, 2d arrays, 3d arrays, etc.
These can also be used for small data.
The use of ``malloc()``, ``calloc()``, ``realloc()`` and ``free()``
directly is strongly discouraged. To simplify adapting legacy code
into the LAMMPS code base the member functions ``Memory::smalloc()``,
``Memory::srealloc()``, and ``Memory::sfree()`` are available, which
perform additional error checks for safety.
Use of these custom memory allocation functions is motivated by the
following considerations:
- memory allocation failures on *any* MPI rank during a parallel run
will trigger an immediate abort of the entire parallel calculation
instead of stalling it
- a failing "new" will trigger an exception which is also captured by
LAMMPS and triggers a global abort
- allocation of multi-dimensional arrays will be done in a C compatible
fashion but so that the storage of the actual data is stored in one
large contiguous block. Thus when MPI communication is needed,
the data can be communicated directly (similar to Fortran arrays).
- the "destroy()" and "sfree()" functions may safely be called on NULL
pointers
- the "destroy()" functions will nullify the pointer variables making
"use after free" errors easy to detect
- it is possible to use a larger than default memory alignment (not on
all operating systems, since the allocated storage pointers must be
compatible with ``free()`` for technical reasons)
In the practical implementation of code this means that any pointer
variables that are class members should be initialized to a
``nullptr`` value in their respective constructors. That way it is
safe to call ``Memory::destroy()`` or ``delete[]`` on them before
*any* allocation outside the constructor. This helps prevent memory
leaks.

235
doc/src/Developer_comm_ops.rst Normal file
View File

@ -0,0 +1,235 @@
Communication patterns
----------------------
This page describes various inter-processor communication operations
provided by LAMMPS, mostly in the core *Comm* class. These are operations
for common tasks implemented using MPI library calls. They are used by
other classes to perform communication of different kinds. These
operations are useful to know about when writing new code for LAMMPS
that needs to communicate data between processors.
Owned and ghost atoms
^^^^^^^^^^^^^^^^^^^^^
As described on the :doc:`parallel partitioning algorithms
<Developer_par_part>` page, LAMMPS spatially decomposes the simulation
domain, either in a *brick* or *tiled* manner. Each processor (MPI
task) owns atoms within its sub-domain and additionally stores ghost
atoms within a cutoff distance of its sub-domain.
Forward and reverse communication
=================================
As described on the :doc:`parallel communication algorithms
<Developer_par_comm>` page, the most common communication operations are
first, *forward communication* which sends owned atom information from
each processor to nearby processors to store with their ghost atoms.
The need to do this communication arises when data from the owned atoms
is updated (e.g. their positions) and this updated information needs to
be **copied** to the corresponding ghost atoms.
And second, *reverse communication* which sends ghost atom information
from each processor to the owning processor to **accumulate** (sum)
the values with the corresponding owned atoms. The need for this
arises when data is computed and also stored with ghost atoms
(e.g. forces when using a "half" neighbor list) and thus those terms
need to be added to their corresponding atoms on the process where
they are "owned" atoms. Please note, that with the :doc:`newton off
<newton>` setting this does not happen and the neighbor lists are
constructed so that these interactions are computed on both MPI
processes containing one of the atoms and only the data pertaining to
the local atom is stored.
The time-integration classes in LAMMPS invoke these operations each
timestep via the *forward_comm()* and *reverse_comm()* methods in the
*Comm* class. Which per-atom data is communicated depends on the
currently used :doc:`atom style <atom_style>` and whether
:doc:`comm_modify vel <comm_modify>` setting is "no" (default) or
"yes".
Similarly, *Pair* style classes can invoke the *forward_comm(this)*
and *reverse_comm(this)* methods in the *Comm* class to perform the
same operations on per-atom data that is generated and stored within
the pair style class. Note that this function requires passing the
``this`` pointer as the first argument to enable the *Comm* class to
call the "pack" and "unpack" functions discussed below. An example of
the use of these functions are many-body pair styles like the
embedded-atom method (EAM) which compute intermediate values in the
first part of the compute() function that need to be stored by both
owned and ghost atoms for the second part of the force computation.
The *Comm* class methods perform the MPI communication for buffers of
per-atom data. They "call back" to the *Pair* class so it can *pack*
or *unpack* the buffer with data the *Pair* class owns. There are 4
such methods that the *Pair* class must define, assuming it uses both
forward and reverse communication:
* pack_forward_comm()
* unpack_forward_comm()
* pack_reverse_comm()
* unpack_reverse_comm()
The arguments to these methods include the buffer and a list of atoms
to pack or unpack. The *Pair* class also must set the *comm_forward*
and *comm_reverse* variables which store the number of values stored
in the communication buffers for each operation. This means, if
desired, it can choose to store multiple per-atom values in the
buffer, and they will be communicated together to minimize
communication overhead. The communication buffers are defined vectors
containing ``double`` values. To correctly store integers that may be
64-bit (bigint, tagint, imageint) in the buffer, you need to use the
`ubuf union <Communication buffer coding with ubuf>`_ construct.
The *Fix*, *Compute*, and *Dump* classes can also invoke the same kind
of forward and reverse communication operations using the same *Comm*
class methods. Likewise the same pack/unpack methods and
comm_forward/comm_reverse variables must be defined by the calling
*Fix*, *Compute*, or *Dump* class.
For *Fix* classes there is an optional second argument to the
*forward_comm()* and *reverse_comm()* call which can be used when the
fix performs multiple modes of communication, with different numbers
of values per atom. The fix should set the *comm_forward* and
*comm_reverse* variables to the maximum value, but can invoke the
communication for a particular mode with a smaller value. For this
to work, the *pack_forward_comm()*, etc methods typically use a class
member variable to choose which values to pack/unpack into/from the
buffer.
Finally, for reverse communications in *Fix* classes there is also the
*reverse_comm_variable()* method that allows the communication to have
a different amount of data per-atom. It invokes these corresponding
callback methods:
* pack_reverse_comm_size()
* unpack_reverse_comm_size()
which have extra arguments to specify the amount of data stored
in the buffer for each atom.
Higher level communication
^^^^^^^^^^^^^^^^^^^^^^^^^^
There are also several higher-level communication operations provided
in LAMMPS which work for either *brick* or *tiled* decompositions.
They may be useful for a new class to invoke if it requires more
sophisticated communication than the *forward* and *reverse* methods
provide. The 3 communication operations described here are
* ring
* irregular
* rendezvous
You can invoke these *grep* command in the LAMMPS src directory, to
see a list of classes that invoke the 3 operations.
* ``grep "\->ring" *.cpp */*.cpp``
* ``grep "irregular\->" *.cpp``
* ``grep "\->rendezvous" *.cpp */*.cpp``
Ring operation
==============
The *ring* operation is invoked via the *ring()* method in the *Comm*
class.
Each processor first creates a buffer with a list of values, typically
associated with a subset of the atoms it owns. Now think of the *P*
processors as connected to each other in a *ring*. Each processor *M*
sends data to the next *M+1* processor. It receives data from the
preceding *M-1* processor. The ring is periodic so that the last
processor sends to the first processor, and the first processor
receives from the last processor.
Invoking the *ring()* method passes each processor's buffer in *P*
steps around the ring. At each step a *callback* method, provided as
an argument to ring(), in the caller is invoked. This allows each
processor to examine the data buffer provided by every other
processor. It may extract values needed by its atoms from the
buffers, or it may alter placeholder values in the buffer. In the
latter case, when the *ring* operation is complete, each processor can
examine its original buffer to extract modified values.
Note that the *ring* operation is similar to an MPI_Alltoall()
operation where every processor effectively sends and receives data to
every other processor. The difference is that the *ring* operation
does it one step at a time, so the total volume of data does not need
to be stored by every processor. However, the *ring* operation is
also less efficient than MPI_Alltoall() because of the *P* stages
required. So it is typically only suitable for small data buffers and
occasional operations that are not time-critical.
Irregular operation
===================
The *irregular* operation is provided by the *Irregular* class. What
LAMMPS terms irregular communication is when each processor knows what
data it needs to send to what processor, but does not know what
processors are sending it data. An example is when load-balancing is
performed and each processor needs to send some of its atoms to new
processors.
The *Irregular* class provides 5 high-level methods useful in this
context:
* create_data()
* exchange_data()
* create_atom()
* exchange_atom()
* migrate_atoms()
For the *create_data()* method, each processor specifies a list of *N*
datums to send, each to a specified processor. Internally, the method
creates efficient data structures for performing the communication.
The *exchange_data()* method triggers the communication to be
performed. Each processor provides the vector of *N* datums to send,
and the size of each datum. All datums must be the same size.
The *create_atom()* and *exchange_atom()* methods are similar except
that the size of each datum can be different. Typically this is used
to communicate atoms, each with a variable amount of per-atom data, to
other processors.
The *migrate_atoms()* method is a convenience wrapper on the
*create_atom()* and *exchange_atom()* methods to simplify
communication of all the per-atom data associated with an atom so that
the atom can effectively migrate to a new owning processor. It is
similar to the *exchange()* method in the *Comm* class invoked when
atoms move to neighboring processors (in the regular or tiled
decomposition) during timestepping, except that it allows atoms to
have moved arbitrarily long distances and still be properly
communicated to a new owning processor.
Rendezvous operation
====================
Finally, the *rendezvous* operation is invoked via the *rendezvous()*
method in the *Comm* class. Depending on how much communication is
needed and how many processors a LAMMPS simulation is running on, it
can be a much more efficient choice than the *ring()* method. It uses
the *irregular* operation internally once or twice to do its
communication. The rendezvous algorithm is described in detail in
:ref:`(Plimpton) <Plimpton>`, including some LAMMPS use cases.
For the *rendezvous()* method, each processor specifies a list of *N*
datums to send and which processor to send each of them to.
Internally, this communication is performed as an irregular operation.
The received datums are returned to the caller via invocation of
*callback* function, provided as an argument to *rendezvous()*. The
caller can then process the received datums and (optionally) assemble
a new list of datums to communicate to a new list of specific
processors. When the callback function exits, the *rendezvous()*
method performs a second irregular communication on the new list of
datums.
Examples in LAMMPS of use of the *rendezvous* operation are the
:doc:`fix rigid/small <fix_rigid>` and :doc:`fix shake
<fix_shake>` commands (for one-time identification of the rigid body
atom clusters) and the identification of special_bond 1-2, 1-3 and 1-4
neighbors within molecules. See the :doc:`special_bonds <special_bonds>`
command for context.
----------
.. _Plimpton:
**(Plimpton)** Plimpton and Knight, JPDC, 147, 184-195 (2021).

209
doc/src/Developer_notes.rst
View File

@ -7,6 +7,215 @@ 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.
Available topics are:
- `Reading and parsing of text and text files`_
- `Requesting and accessing neighbor lists`_
- `Fix contributions to instantaneous energy, virial, and cumulative energy`_
- `KSpace PPPM FFT grids`_
----
Reading and parsing of text and text files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is frequently required for a class in LAMMPS to read in additional
data from a file, e.g. potential parameters from a potential file for
manybody potentials. LAMMPS provides several custom classes and
convenience functions to simplify the process. They offer the
following benefits:
- better code reuse and fewer lines of code needed to implement reading
and parsing data from a file
- better detection of format errors, incompatible data, and better error messages
- exit with an error message instead of silently converting only part of the
text to a number or returning a 0 on unrecognized text and thus reading incorrect values
- re-entrant code through avoiding global static variables (as used by ``strtok()``)
- transparent support for translating unsupported UTF-8 characters to their ASCII equivalents
(the text-to-value conversion functions **only** accept ASCII characters)
In most cases (e.g. potential files) the same data is needed on all MPI
ranks. Then it is best to do the reading and parsing only on MPI rank
0, and communicate the data later with one or more ``MPI_Bcast()``
calls. For reading generic text and potential parameter files the
custom classes :cpp:class:`TextFileReader <LAMMPS_NS::TextFileReader>`
and :cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>`
are available. They allow reading the file as individual lines for which
they can return a tokenizer class (see below) for parsing the line. Or
they can return blocks of numbers as a vector directly. The
documentation on :ref:`File reader classes <file-reader-classes>`
contains an example for a typical case.
When reading per-atom data, the data on each line of the file usually
needs to include an atom ID so it can be associated with a particular
atom. In that case the data can be read in multi-line chunks and
broadcast to all MPI ranks with
:cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>`. Those chunks are then
split into lines, parsed, and applied only to atoms the MPI rank
"owns".
For splitting a string (incrementally) into words and optionally
converting those to numbers, the :cpp:class:`Tokenizer
<LAMMPS_NS::Tokenizer>` and :cpp:class:`ValueTokenizer
<LAMMPS_NS::ValueTokenizer>` can be used. Those provide a superset of
the functionality of ``strtok()`` from the C-library and the latter
also includes conversion to different types. Any errors while
processing the string in those classes will result in an exception,
which can be caught and the error processed as needed. Unlike the
C-library functions ``atoi()``, ``atof()``, ``strtol()``, or
``strtod()`` the conversion will check if the converted text is a
valid integer or floating point number and will not silently return an
unexpected or incorrect value. For example, ``atoi()`` will return 12
when converting "12.5", while the ValueTokenizer class will throw an
:cpp:class:`InvalidIntegerException
<LAMMPS_NS::InvalidIntegerException>` if
:cpp:func:`ValueTokenizer::next_int()
<LAMMPS_NS::ValueTokenizer::next_int>` is called on the same string.
Requesting and accessing neighbor lists
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS uses Verlet-style neighbor lists to avoid having to loop over
*all* pairs of *all* atoms when computing pairwise properties with a
cutoff (e.g. pairwise forces or radial distribution functions). There
are three main algorithms that can be selected by the :doc:`neighbor
command <neighbor>`: `bin` (the default, uses binning to achieve linear
scaling with system size), `nsq` (without binning, quadratic scaling),
`multi` (with binning, optimized for varying cutoffs or polydisperse
granular particles). In addition to how the neighbor lists are
constructed a number of different variants of neighbor lists need to be
created (e.g. "full" or "half") for different purposes and styles and
those may be required in every time step ("perpetual") or on some steps
("occasional").
The neighbor list creation is managed by the ``Neighbor`` class.
Individual classes can obtain a neighbor list by creating an instance of
a ``NeighRequest`` class which is stored in a list inside the
``Neighbor`` class. The ``Neighbor`` class will then analyze the
various requests and apply optimizations where neighbor lists that have
the same settings will be created only once and then copied, or a list
may be constructed by processing a neighbor list from a different
request that is a superset of the requested list. The neighbor list
build is then :doc:`processed in parallel <Developer_par_neigh>`.
The most commonly required neighbor list is a so-called "half" neighbor
list, where each pair of atoms is listed only once (except when the
:doc:`newton command setting <newton>` for pair is off; in that case
pairs straddling sub-domains or periodic boundaries will be listed twice).
Thus these are the default settings when a neighbor list request is created in:
.. code-block:: C++
void Pair::init_style()
{
neighbor->add_request(this);
}
void Pair::init_list(int /*id*/, NeighList *ptr)
{
list = ptr;
}
The ``this`` pointer argument is required so the neighbor list code can
access the requesting class instance to store the assembled neighbor
list with that instance by calling its ``init_list()`` member function.
The optional second argument (omitted here) contains a bitmask of flags
that determines the kind of neighbor list requested. The default value
used here asks for a perpetual "half" neighbor list.
Non-default values of the second argument need to be used to adjust a
neighbor list request to the specific needs of a style an additional
request flag is needed. The :doc:`tersoff <pair_tersoff>` pair style,
for example, needs a "full" neighbor list:
.. code-block:: C++
void PairTersoff::init_style()
{
// [...]
neighbor->add_request(this, NeighConst::REQ_FULL);
}
When a pair style supports r-RESPA time integration with different cutoff regions,
the request flag may depend on the corresponding r-RESPA settings. Here an example
from pair style lj/cut:
.. code-block:: C++
void PairLJCut::init_style()
{
int list_style = NeighConst::REQ_DEFAULT;
if (update->whichflag == 1 && utils::strmatch(update->integrate_style, "^respa")) {
auto respa = (Respa *) update->integrate;
if (respa->level_inner >= 0) list_style = NeighConst::REQ_RESPA_INOUT;
if (respa->level_middle >= 0) list_style = NeighConst::REQ_RESPA_ALL;
}
neighbor->add_request(this, list_style);
// [...]
}
Granular pair styles need neighbor lists based on particle sizes and not cutoff
and also may require to have the list of previous neighbors available ("history").
For example with:
.. code-block:: C++
if (use_history) neighbor->add_request(this, NeighConst::REQ_SIZE | NeighConst::REQ_HISTORY);
else neighbor->add_request(this, NeighConst::REQ_SIZE);
In case a class would need to make multiple neighbor list requests with different
settings each request can set an id which is then used in the corresponding
``init_list()`` function to assign it to the suitable pointer variable. This is
done for example by the :doc:`pair style meam <pair_meam>`:
.. code-block:: C++
void PairMEAM::init_style()
{
// [...]
neighbor->add_request(this, NeighConst::REQ_FULL)->set_id(1);
neighbor->add_request(this)->set_id(2);
}
void PairMEAM::init_list(int id, NeighList *ptr)
{
if (id == 1) listfull = ptr;
else if (id == 2) listhalf = ptr;
}
Fixes may require a neighbor list that is only build occasionally (or
just once) and this can also be indicated by a flag. As an example here
is the request from the ``FixPeriNeigh`` class which is created
internally by :doc:`Peridynamics pair styles <pair_peri>`:
.. code-block:: C++
neighbor->add_request(this, NeighConst::REQ_FULL | NeighConst::REQ_OCCASIONAL);
It is also possible to request a neighbor list that uses a different cutoff
than what is usually inferred from the pair style settings (largest cutoff of
all pair styles plus neighbor list skin). The following is used in the
:doc:`compute rdf <compute_rdf>` command implementation:
.. code-block:: C++
if (cutflag)
neighbor->add_request(this, NeighConst::REQ_OCCASIONAL)->set_cutoff(mycutneigh);
else
neighbor->add_request(this, NeighConst::REQ_OCCASIONAL);
The neighbor list request function has a slightly different set of arguments
when created by a command style. In this case the neighbor list is
*always* an occasional neighbor list, so that flag is not needed. However
for printing the neighbor list summary the name of the requesting command
should be set. Below is the request from the :doc:`delete atoms <delete_atoms>`
command:
.. code-block:: C++
neighbor->add_request(this, "delete_atoms", NeighConst::REQ_FULL);
Fix contributions to instantaneous energy, virial, and cumulative energy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

8
doc/src/Developer_org.rst
View File

@ -225,7 +225,7 @@ follows:
commands in an input script.
- The Force class computes various forces between atoms. The Pair
parent class is for non-bonded or pair-wise forces, which in LAMMPS
parent class is for non-bonded or pairwise forces, which in LAMMPS
also includes many-body forces such as the Tersoff 3-body potential if
those are computed by walking pairwise neighbor lists. The Bond,
Angle, Dihedral, Improper parent classes are styles for bonded
@ -252,12 +252,6 @@ follows:
- The Timer class logs timing information, output at the end
of a run.
.. TODO section on "Spatial decomposition and parallel operations"
.. diagram of 3d processor grid, brick vs. tiled. local vs. ghost
.. atoms, 6-way communication with pack/unpack functions,
.. PBC as part of the communication, forward and reverse communication
.. rendezvous communication, ring communication.
.. TODO section on "Fixes, Computes, and Variables"
.. how and when data is computed and provided and how it is
.. referenced. flags in Fix/Compute/Variable classes tell

72
doc/src/Developer_plugins.rst
View File

@ -8,11 +8,20 @@ without recompiling LAMMPS. The functionality for this and the
Plugins use the operating system's capability to load dynamic shared
object (DSO) files in a way similar shared libraries and then reference
specific functions in those DSOs. Any DSO file with plugins has to include
an initialization function with a specific name, "lammpsplugin_init", that
has to follow specific rules described below. When loading the DSO with
the "plugin" command, this function is looked up and called and will then
register the contained plugin(s) with LAMMPS.
specific functions in those DSOs. Any DSO file with plugins has to
include an initialization function with a specific name,
"lammpsplugin_init", that has to follow specific rules described below.
When loading the DSO with the "plugin" command, this function is looked
up and called and will then register the contained plugin(s) with
LAMMPS.
When the environment variable ``LAMMPS_PLUGIN_PATH`` is set, then LAMMPS
will search the directory (or directories) listed in this path for files
with names that end in ``plugin.so`` (e.g. ``helloplugin.so``) and will
try to load the contained plugins automatically at start-up. For
plugins that are loaded this way, the behavior of LAMMPS should be
identical to a binary where the corresponding code was compiled in
statically as a package.
From the programmer perspective this can work because of the object
oriented design of LAMMPS where all pair style commands are derived from
@ -59,25 +68,24 @@ Members of ``lammpsplugin_t``
* - author
- String with the name and email of the author
* - creator.v1
- Pointer to factory function for pair, bond, angle, dihedral, improper or command styles
- Pointer to factory function for pair, bond, angle, dihedral, improper, kspace, or command styles
* - creator.v2
- Pointer to factory function for compute, fix, or region styles
* - handle
- Pointer to the open DSO file handle
Only one of the three alternate creator entries can be used at a time
and which of those is determined by the style of plugin. The
"creator.v1" element is for factory functions of supported styles
computing forces (i.e. command, pair, bond, angle, dihedral, or
improper styles) and the function takes as single argument the pointer
to the LAMMPS instance. The factory function is cast to the
``lammpsplugin_factory1`` type before assignment. The "creator.v2"
element is for factory functions creating an instance of a fix, compute,
or region style and takes three arguments: a pointer to the LAMMPS
instance, an integer with the length of the argument list and a ``char
**`` pointer to the list of arguments. The factory function pointer
needs to be cast to the ``lammpsplugin_factory2`` type before
assignment.
Only one of the two alternate creator entries can be used at a time and
which of those is determined by the style of plugin. The "creator.v1"
element is for factory functions of supported styles computing forces
(i.e. pair, bond, angle, dihedral, or improper styles) or command styles
and the function takes as single argument the pointer to the LAMMPS
instance. The factory function is cast to the ``lammpsplugin_factory1``
type before assignment. The "creator.v2" element is for factory
functions creating an instance of a fix, compute, or region style and
takes three arguments: a pointer to the LAMMPS instance, an integer with
the length of the argument list and a ``char **`` pointer to the list of
arguments. The factory function pointer needs to be cast to the
``lammpsplugin_factory2`` type before assignment.
Pair style example
^^^^^^^^^^^^^^^^^^
@ -249,3 +257,29 @@ by ``#ifdef PAIR_CLASS`` is not needed, since the mapping of the class
name to the style name is done by the plugin registration function with
the information from the ``lammpsplugin_t`` struct. It may be included
in case the new code is intended to be later included in LAMMPS directly.
A plugin may be registered under an existing style name. In that case
the plugin will override the existing code. This can be used to modify
the behavior of existing styles or to debug new versions of them without
having to re-compile or re-install all of LAMMPS.
Compiling plugins
^^^^^^^^^^^^^^^^^
Plugins need to be compiled with the same compilers and libraries
(e.g. MPI) and compilation settings (MPI on/off, OpenMP, integer sizes)
as the LAMMPS executable and library. Otherwise the plugin will likely
not load due to mismatches in the function signatures (LAMMPS is C++ so
scope, type, and number of arguments are encoded into the symbol names
and thus differences in them will lead to failed plugin load commands.
Compilation of the plugin can be managed via both, CMake or traditional
GNU makefiles. Some examples that can be used as a template are in the
``examples/plugins`` folder. The CMake script code has some small
adjustments to allow building the plugins for running unit tests with
them. Another example that converts the KIM package into a plugin can be
found in the ``examples/kim/plugin`` folder. No changes to the sources
of the KIM package themselves are needed; only the plugin interface and
loader code needs to be added. This example only supports building with
CMake, but is probably a more typical example. To compile you need to
run CMake with -DLAMMPS_SOURCE_DIR=<path/to/lammps/src/folder>. Other
configuration setting are identical to those for compiling LAMMPS.

110
doc/src/Developer_utils.rst
View File

@ -21,18 +21,21 @@ In that case, the functions will stop with an error message, indicating
the name of the problematic file, if possible unless the *error* argument
is a NULL pointer.
The :cpp:func:`fgets_trunc` function will work similar for ``fgets()``
but it will read in a whole line (i.e. until the end of line or end
of file), but store only as many characters as will fit into the buffer
including a final newline character and the terminating NULL byte.
If the line in the file is longer it will thus be truncated in the buffer.
This function is used by :cpp:func:`read_lines_from_file` to read individual
lines but make certain they follow the size constraints.
The :cpp:func:`utils::fgets_trunc() <LAMMPS_NS::utils::fgets_trunc>`
function will work similar for ``fgets()`` but it will read in a whole
line (i.e. until the end of line or end of file), but store only as many
characters as will fit into the buffer including a final newline
character and the terminating NULL byte. If the line in the file is
longer it will thus be truncated in the buffer. This function is used
by :cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>` to read individual lines but
make certain they follow the size constraints.
The :cpp:func:`read_lines_from_file` function will read the requested
number of lines of a maximum length into a buffer and will return 0
if successful or 1 if not. It also guarantees that all lines are
terminated with a newline character and the entire buffer with a
The :cpp:func:`utils::read_lines_from_file()
<LAMMPS_NS::utils::read_lines_from_file>` function will read the
requested number of lines of a maximum length into a buffer and will
return 0 if successful or 1 if not. It also guarantees that all lines
are terminated with a newline character and the entire buffer with a
NULL character.
----------
@ -56,13 +59,13 @@ String to number conversions with validity check
These functions should be used to convert strings to numbers. They are
are strongly preferred over C library calls like ``atoi()`` or
``atof()`` since they check if the **entire** provided string is a valid
``atof()`` since they check if the **entire** string is a valid
(floating-point or integer) number, and will error out instead of
silently returning the result of a partial conversion or zero in cases
where the string is not a valid number. This behavior allows to more
easily detect typos or issues when processing input files.
where the string is not a valid number. This behavior improves
detecting typos or issues when processing input files.
Similarly the :cpp:func:`logical() <LAMMPS_NS::utils::logical>` function
Similarly the :cpp:func:`utils::logical() <LAMMPS_NS::utils::logical>` function
will convert a string into a boolean and will only accept certain words.
The *do_abort* flag should be set to ``true`` in case this function
@ -70,25 +73,40 @@ is called only on a single MPI rank, as that will then trigger the
a call to ``Error::one()`` for errors instead of ``Error::all()``
and avoids a "hanging" calculation when run in parallel.
Please also see :cpp:func:`is_integer() <LAMMPS_NS::utils::is_integer>`
and :cpp:func:`is_double() <LAMMPS_NS::utils::is_double>` for testing
Please also see :cpp:func:`utils::is_integer() <LAMMPS_NS::utils::is_integer>`
and :cpp:func:`utils::is_double() <LAMMPS_NS::utils::is_double>` for testing
strings for compliance without conversion.
----------
.. doxygenfunction:: numeric
.. doxygenfunction:: numeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: inumeric
.. doxygenfunction:: numeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: bnumeric
.. doxygenfunction:: inumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric
.. doxygenfunction:: inumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: logical
.. doxygenfunction:: bnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: bnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: tnumeric(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: logical(const char *file, int line, const std::string &str, bool do_abort, LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: logical(const char *file, int line, const char *str, bool do_abort, LAMMPS *lmp)
:project: progguide
@ -115,6 +133,9 @@ and parsing files or arguments.
.. doxygenfunction:: trim_comment
:project: progguide
.. doxygenfunction:: star_subst
:project: progguide
.. doxygenfunction:: has_utf8
:project: progguide
@ -190,6 +211,15 @@ Convenience functions
.. doxygenfunction:: logmesg(LAMMPS *lmp, const std::string &mesg)
:project: progguide
.. doxygenfunction:: errorurl
:project: progguide
.. doxygenfunction:: missing_cmd_args
:project: progguide
.. doxygenfunction:: flush_buffers(LAMMPS *lmp)
:project: progguide
.. doxygenfunction:: getsyserror
:project: progguide
@ -322,11 +352,11 @@ This code example should produce the following output:
.. doxygenclass:: LAMMPS_NS::InvalidIntegerException
:project: progguide
:members: what
:members:
.. doxygenclass:: LAMMPS_NS::InvalidFloatException
:project: progguide
:members: what
:members:
----------
@ -375,21 +405,26 @@ A typical code segment would look like this:
----------
.. _file-reader-classes:
File reader classes
-------------------
The purpose of the file reader classes is to simplify the recurring task
of reading and parsing files. They can use the
:cpp:class:`LAMMPS_NS::ValueTokenizer` class to process the read in
text. The :cpp:class:`LAMMPS_NS::TextFileReader` is a more general
version while :cpp:class:`LAMMPS_NS::PotentialFileReader` is specialized
to implement the behavior expected for looking up and reading/parsing
files with potential parameters in LAMMPS. The potential file reader
class requires a LAMMPS instance, requires to be run on MPI rank 0 only,
will use the :cpp:func:`LAMMPS_NS::utils::get_potential_file_path`
function to look up and open the file, and will call the
:cpp:class:`LAMMPS_NS::Error` class in case of failures to read or to
convert numbers, so that LAMMPS will be aborted.
:cpp:class:`ValueTokenizer <LAMMPS_NS::ValueTokenizer>` class to process
the read in text. The :cpp:class:`TextFileReader
<LAMMPS_NS::TextFileReader>` is a more general version while
:cpp:class:`PotentialFileReader <LAMMPS_NS::PotentialFileReader>` is
specialized to implement the behavior expected for looking up and
reading/parsing files with potential parameters in LAMMPS. The
potential file reader class requires a LAMMPS instance, requires to be
run on MPI rank 0 only, will use the
:cpp:func:`utils::get_potential_file_path
<LAMMPS_NS::utils::get_potential_file_path>` function to look up and
open the file, and will call the :cpp:class:`LAMMPS_NS::Error` class in
case of failures to read or to convert numbers, so that LAMMPS will be
aborted.
.. code-block:: C++
:caption: Use of PotentialFileReader class in pair style coul/streitz
@ -464,10 +499,10 @@ provided, as that is used to determine whether a new page of memory
must be used.
The :cpp:class:`MyPage <LAMMPS_NS::MyPage>` class offers two ways to
reserve a chunk: 1) with :cpp:func:`get() <LAMMPS_NS::MyPage::get>` the
chunk size needs to be known in advance, 2) with :cpp:func:`vget()
reserve a chunk: 1) with :cpp:func:`MyPage::get() <LAMMPS_NS::MyPage::get>` the
chunk size needs to be known in advance, 2) with :cpp:func:`MyPage::vget()
<LAMMPS_NS::MyPage::vget>` a pointer to the next chunk is returned, but
its size is registered later with :cpp:func:`vgot()
its size is registered later with :cpp:func:`MyPage::vgot()
<LAMMPS_NS::MyPage::vgot>`.
.. code-block:: C++
@ -570,4 +605,3 @@ the communication buffers.
.. doxygenunion:: LAMMPS_NS::ubuf
:project: progguide

2
doc/src/Developer_write.rst
View File

@ -55,7 +55,7 @@ of each timestep. First of all, implement a constructor:
if (narg < 4)
error->all(FLERR,"Illegal fix print/vel command");
nevery = force->inumeric(FLERR,arg[3]);
nevery = utils::inumeric(FLERR,arg[3],false,lmp);
if (nevery <= 0)
error->all(FLERR,"Illegal fix print/vel command");
}

1
doc/src/Errors.rst
View File

@ -11,6 +11,7 @@ them.
:maxdepth: 1
Errors_common
Errors_details
Errors_bugs
Errors_debug
Errors_messages

18
doc/src/Errors_bugs.rst
View File

@ -17,9 +17,8 @@ the steps outlined below:
if your issue has already been reported and if it is still open.
* Check the `GitHub Pull Requests page <https://github.com/lammps/lammps/pulls>`_
to see if there is already a fix for your bug pending.
* Check the `mailing list archives <https://www.lammps.org/mail.html>`_ or
the `LAMMPS forum <https://www.lammps.org/forum.html>`_ to see if the
issue has been discussed before.
* Check the `LAMMPS forum at MatSci <https://matsci.org/lammps/>`_
to see if the issue has been discussed before.
If none of these steps yields any useful information, please file a new
bug report on the `GitHub Issue page <https://github.com/lammps/lammps/issues>`_.
@ -38,12 +37,9 @@ generate this restart from a data file or a simple additional input.
This input deck can be used with tools like a debugger or `valgrind
<https://valgrind.org>`_ to further :doc:`debug the crash <Errors_debug>`.
You may also send an email to the LAMMPS mailing list at
"lammps-users at lists.sourceforge.net" describing the problem with the
same kind of information. The mailing list can provide a faster response,
especially if the bug reported is actually expected behavior. But because
of the high volume of the mailing list, it can happen that your e-mail
is overlooked and then forgotten. Issues on GitHub have to be explicitly
closed, so that will *guarantee* that at least one LAMMPS developer will
have looked at it.
You may also post a message in the `development category of the LAMMPS
forum at MatSci <https://matsci.org/c/lammps/lammps-development/>`_
describing the problem with the same kind of information. The forum can
provide a faster response, especially if the bug reported is actually
expected behavior or other LAMMPS users have come across it before.

27
doc/src/Errors_details.rst Normal file
View File

@ -0,0 +1,27 @@
Error and warning details
=========================
Many errors or warnings are self-explanatory and thus straightforward to
resolve. However, there are also cases, where there is no single cause
and explanation, where LAMMPS can only detect symptoms of an error but
not the exact cause, or where the explanation needs to be more detailed than
what can be fit into a message printed by the program. The following are
discussions of such cases.
.. _err0001:
Unknown identifier in data file
-------------------------------
This error happens when LAMMPS encounters a line of text in an unexpected format
while reading a data file. This is most commonly cause by inconsistent header and
section data. The header section informs LAMMPS how many entries or lines are expected in the
various sections (like Atoms, Masses, Pair Coeffs, *etc.*\ ) of the data file.
If there is a mismatch, LAMMPS will either keep reading beyond the end of a section
or stop reading before the section has ended.
Such a mismatch can happen unexpectedly when the first line of the data
is *not* a comment as required by the format. That would result in
LAMMPS expecting, for instance, 0 atoms because the "atoms" header line
is treated as a comment.

10
doc/src/Errors_messages.rst
View File

@ -1941,6 +1941,9 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Compute ID for fix numdiff does not exist*
Self-explanatory.
*Compute ID for fix numdiff/virial does not exist*
Self-explanatory.
*Compute ID for fix store/state does not exist*
Self-explanatory.
@ -3796,6 +3799,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
Self-explanatory. Efficient loop over all atoms for numerical
difference requires consecutive atom IDs.
*Fix numdiff/virial must use group all*
Virial contributions computed by this fix are
computed on all atoms.
*Fix nve/asphere requires extended particles*
This fix can only be used for particles with a shape setting.
@ -7772,9 +7779,6 @@ keyword to allow for additional bonds to be formed
The system size must fit in a 32-bit integer to use this dump
style.
*Too many atoms to dump sort*
Cannot sort when running with more than 2\^31 atoms.
*Too many elements extracted from MEAM library.*
Increase 'maxelt' in meam.h and recompile.

2
doc/src/Errors_warnings.rst
View File

@ -416,7 +416,7 @@ This will most likely cause errors in kinetic fluctuations.
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 pair-wise
This means the bonded atoms will not be excluded in pairwise
interactions.
*Molecule template for create_atoms has multiple molecules*

6
doc/src/Examples.rst
View File

@ -54,6 +54,8 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| body | body particles, 2d system |
+-------------+------------------------------------------------------------------+
| bpm | BPM simulations of pouring elastic grains and plate impact |
+-------------+------------------------------------------------------------------+
| cmap | CMAP 5-body contributions to CHARMM force field |
+-------------+------------------------------------------------------------------+
| colloid | big colloid particles in a small particle solvent, 2d system |
@ -94,12 +96,12 @@ Lowercase directories
+-------------+------------------------------------------------------------------+
| latte | examples for using fix latte for DFTB via the LATTE library |
+-------------+------------------------------------------------------------------+
| mdi | use of the MDI package and MolSSI MDI code coupling library |
+-------------+------------------------------------------------------------------+
| meam | MEAM test for SiC and shear (same as shear examples) |
+-------------+------------------------------------------------------------------+
| melt | rapid melt of 3d LJ system |
+-------------+------------------------------------------------------------------+
| message | demos for LAMMPS client/server coupling with the MESSAGE package |
+-------------+------------------------------------------------------------------+
| micelle | self-assembly of small lipid-like molecules into 2d bilayers |
+-------------+------------------------------------------------------------------+
| min | energy minimization of 2d LJ melt |

3
doc/src/Howto.rst
View File

@ -22,8 +22,9 @@ General howto
Howto_replica
Howto_library
Howto_couple
Howto_client_server
Howto_mdi
Howto_bpm
Howto_broken_bonds
Settings howto
==============

119
doc/src/Howto_bpm.rst Normal file
View File

@ -0,0 +1,119 @@
Bonded particle models
======================
The BPM package implements bonded particle models which can be used to
simulate mesoscale solids. Solids are constructed as a collection of
particles which each represent a coarse-grained region of space much
larger than the atomistic scale. Particles within a solid region are
then connected by a network of bonds to provide solid elasticity.
Unlike traditional bonds in molecular dynamics, the equilibrium bond
length can vary between bonds. Bonds store the reference state. This
includes setting the equilibrium length equal to the initial distance
between the two particles but can also include data on the bond
orientation for rotational models. This produces a stress free initial
state. Furthermore, bonds are allowed to break under large strains
producing fracture. The examples/bpm directory has sample input scripts
for simulations of the fragmentation of an impacted plate and the
pouring of extended, elastic bodies.
----------
Bonds can be created using a :doc:`read data <read_data>` or
:doc:`create bonds <create_bonds>` command. Alternatively, a
:doc:`molecule <molecule>` template with bonds can be used with
:doc:`fix deposit <fix_deposit>` or :doc:`fix pour <fix_pour>` to
create solid grains.
In this implementation, bonds store their reference state when they are
first computed in the setup of the first simulation run. Data is then
preserved across run commands and is written to :doc:`binary restart
files <restart>` such that restarting the system will not reset the
reference state of a bond. Bonds that are created midway into a run,
such as those created by pouring grains using :doc:`fix pour
<fix_pour>`, are initialized on that timestep.
As bonds can be broken between neighbor list builds, the
:doc:`special_bonds <special_bonds>` command works differently for BPM
bond styles. There are two possible settings which determine how pair
interactions work between bonded particles. First, one can turn off
all pair interactions between bonded particles. Unlike :doc:`bond
quartic <bond_quartic>`, this is not done by subtracting pair forces
during the bond computation but rather by dynamically updating the
special bond list. This is the default behavior of BPM bond styles and
is done by updating the 1-2 special bond list as bonds break. To do
this, LAMMPS requires :doc:`newton <newton>` bond off such that all
processors containing an atom know when a bond breaks. Additionally,
one must do either (A) or (B).
A) Use the following special bond settings
.. code-block:: LAMMPS
special_bonds lj 0 1 1 coul 1 1 1
These settings accomplish two goals. First, they turn off 1-3 and 1-4
special bond lists, which are not currently supported for BPMs. As
BPMs often have dense bond networks, generating 1-3 and 1-4 special
bond lists is expensive. By setting the lj weight for 1-2 bonds to
zero, this turns off pairwise interactions. Even though there are no
charges in BPM models, setting a nonzero coul weight for 1-2 bonds
ensures all bonded neighbors are still included in the neighbor list
in case bonds break between neighbor list builds.
B) Alternatively, one can simply overlay pair interactions such that all
bonded particles also feel pair interactions. This can be
accomplished by using the *overlay/pair* keyword present in all bpm
bond styles and by using the following special bond settings
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
See the :doc:`Howto <Howto_broken_bonds>` page on broken bonds for
more information.
----------
Currently there are two 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. Alternatively, the second
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 :doc:`granular package
<Howto_granular>`, :doc:`atom style sphere <atom_style>`. However,
they must also track the current orientation of particles and store bonds
and therefore use a :doc:`bpm/sphere atom style <atom_style>`.
This also requires a unique integrator :doc:`fix nve/bpm/sphere
<fix_nve_bpm_sphere>` which numerically integrates orientation similar
to :doc:`fix nve/asphere <fix_nve_asphere>`.
To monitor the fracture of bonds in the system, all BPM bond styles
have the ability to record instances of bond breakage to output using
the :doc:`dump local <dump>` command. Additionally, one can use
:doc:`compute nbond/atom <compute_nbond_atom>` to tally the current
number of bonds per atom.
In addition to bond styles, a new pair style :doc:`pair bpm/spring
<pair_bpm_spring>` was added to accompany the bpm/spring bond
style. This pair style is simply a hookean repulsion with similar
velocity damping as its sister bond style.
----------
While LAMMPS has many utilities to create and delete bonds, *only*
the following are currently compatible with BPM bond styles:
* :doc:`create_bonds <create_bonds>`
* :doc:`delete_bonds <delete_bonds>`
* :doc:`fix bond/create <fix_bond_create>`
* :doc:`fix bond/break <fix_bond_break>`
* :doc:`fix bond/swap <fix_bond_swap>`
Note :doc:`create_bonds <create_bonds>` requires certain special_bonds settings.
To subtract pair interactions, one will need to switch between different
special_bonds settings in the input script. An example is found in
examples/bpm/impact.

48
doc/src/Howto_broken_bonds.rst Normal file
View File

@ -0,0 +1,48 @@
Broken Bonds
============
Typically, bond interactions persist for the duration of a simulation
in LAMMPS. However, there are some exceptions that allow for bonds to
break including the :doc:`quartic bond style <bond_quartic>` and the
bond styles in the :doc:`BPM package <Howto_bpm>` which contains the
:doc:`bpm/spring <bond_bpm_spring>` and
:doc:`bpm/rotational <bond_bpm_rotational>` bond styles. In these cases,
a bond can be broken if it is stretched beyond a user-defined threshold.
LAMMPS accomplishes this by setting the bond type to zero such that the
bond force is no longer computed.
Users are normally able to weight the contribution of pair forces to atoms
that are bonded using the :doc:`special_bonds command <special_bonds>`.
When bonds break, this is not always the case. For the quartic bond style,
pair forces are always turned off between bonded particles. LAMMPS does
this via a computational sleight-of-hand. It subtracts the pairwise
interaction as part of the bond computation. When the bond breaks, the
subtraction stops. For this to work, the pairwise interaction must always
be computed by the :doc:`pair_style <pair_style>` command, whether the bond
is broken or not. This means that :doc:`special_bonds <special_bonds>` must
be set to 1,1,1. After the bond breaks, the pairwise interaction between the
two atoms is turned on, since they are no longer bonded.
In the BPM package, one can either turn off all pair interactions between
bonded particles or leave them on, overlaying pair forces on top of bond
forces. To remove pair forces, the special bond list is dynamically
updated. More details can be found on the :doc:`Howto BPM <Howto_bpm>`
page.
Bonds can also be broken by fixes which change bond topology, including
:doc:`fix bond/break <fix_bond_break>` and
:doc:`fix bond/react <fix_bond_react>`. These fixes will automatically
trigger a rebuild of the neighbor list and update special bond data structures
when bonds are broken.
Note that when bonds are dumped to a file via the :doc:`dump local <dump>` command, bonds with type 0 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
The compute :doc:`nbond/atom <compute_nbond_atom>` can also be used
to tally the current number of bonds per atom, excluding broken bonds.

163
doc/src/Howto_client_server.rst
View File

@ -1,163 +0,0 @@
Using LAMMPS in client/server mode
==================================
Client/server coupling of two codes is where one code is the "client"
and sends request messages to a "server" code. The server responds to
each request with a reply message. This enables the two codes to work
in tandem to perform a simulation. LAMMPS can act as either a client
or server code.
Some advantages of client/server coupling are that the two codes run
as stand-alone executables; they are not linked together. Thus
neither code needs to have a library interface. This often makes it
easier to run the two codes on different numbers of processors. If a
message protocol (format and content) is defined for a particular kind
of simulation, then in principle any code that implements the
client-side protocol can be used in tandem with any code that
implements the server-side protocol, without the two codes needing to
know anything more specific about each other.
A simple example of client/server coupling is where LAMMPS is the
client code performing MD timestepping. Each timestep it sends a
message to a server quantum code containing current coords of all the
atoms. The quantum code computes energy and forces based on the
coords. It returns them as a message to LAMMPS, which completes the
timestep.
A more complex example is where LAMMPS is the client code and
processes a series of data files, sending each configuration to a
quantum code to compute energy and forces. Or LAMMPS runs dynamics
with an atomistic force field, but pauses every N steps to ask the
quantum code to compute energy and forces.
Alternate methods for code coupling with LAMMPS are described on
the :doc:`Howto couple <Howto_couple>` doc page.
The protocol for using LAMMPS as a client is to use these 3 commands
in this order (other commands may come in between):
* :doc:`message client <message>` # initiate client/server interaction
* :doc:`fix client/md <fix_client_md>` # any client fix which makes specific requests to the server
* :doc:`message quit <message>` # terminate client/server interaction
In between the two message commands, a client fix command and
:doc:`unfix <unfix>` command can be used multiple times. Similarly,
this sequence of 3 commands can be repeated multiple times, assuming
the server program operates in a similar fashion, to initiate and
terminate client/server communication.
The protocol for using LAMMPS as a server is to use these 2 commands
in this order (other commands may come in between):
* :doc:`message server <message>` # initiate client/server interaction
* :doc:`server md <server_md>` # any server command which responds to specific requests from the client
This sequence of 2 commands can be repeated multiple times, assuming
the client program operates in a similar fashion, to initiate and
terminate client/server communication.
LAMMPS support for client/server coupling is in its :ref:`MESSAGE package <PKG-MESSAGE>` which implements several
commands that enable LAMMPS to act as a client or server, as discussed
below. The MESSAGE package also wraps a client/server library called
CSlib which enables two codes to exchange messages in different ways,
either via files, sockets, or MPI. The CSlib is provided with LAMMPS
in the lib/message dir. The CSlib has its own
`website <https://cslib.sandia.gov>`_ with documentation and test
programs.
.. note::
For client/server coupling to work between LAMMPS and another
code, the other code also has to use the CSlib. This can sometimes be
done without any modifications to the other code by simply wrapping it
with a Python script that exchanges CSlib messages with LAMMPS and
prepares input for or processes output from the other code. The other
code also has to implement a matching protocol for the format and
content of messages that LAMMPS exchanges with it.
These are the commands currently in the MESSAGE package for two
protocols, MD and MC (Monte Carlo). New protocols can easily be
defined and added to this directory, where LAMMPS acts as either the
client or server.
* :doc:`message <message>`
* :doc:`fix client md <fix_client_md>` = LAMMPS is a client for running MD
* :doc:`server md <server_md>` = LAMMPS is a server for computing MD forces
* :doc:`server mc <server_mc>` = LAMMPS is a server for computing a Monte Carlo energy
The server doc files give details of the message protocols
for data that is exchanged between the client and server.
These example directories illustrate how to use LAMMPS as either a
client or server code:
* examples/message
* examples/COUPLE/README
* examples/COUPLE/lammps_mc
* examples/COUPLE/lammps_nwchem
* examples/COUPLE/lammps_vasp
The examples/message directory couples a client instance of LAMMPS to a
server instance of LAMMPS.
The files in the *lammps_mc* folder show how to couple LAMMPS as
a server to a simple Monte Carlo client code as the driver.
The files in the *lammps_nwchem* folder show how to couple LAMMPS
as a client code running MD timestepping to NWChem acting as a
server providing quantum DFT forces, through a Python wrapper script
on NWChem.
The files in the *lammps_vasp* folder show how to couple LAMMPS as
a client code running MD timestepping to VASP acting as a server
providing quantum DFT forces, through a Python wrapper script on VASP.
Here is how to launch a client and server code together for any of the
4 modes of message exchange that the :doc:`message <message>` command
and the CSlib support. Here LAMMPS is used as both the client and
server code. Another code could be substituted for either.
The examples below show launching both codes from the same window (or
batch script), using the "&" character to launch the first code in the
background. For all modes except *mpi/one*, you could also launch the
codes in separate windows on your desktop machine. It does not
matter whether you launch the client or server first.
In these examples either code can be run on one or more processors.
If running in a non-MPI mode (file or zmq) you can launch a code on a
single processor without using mpirun.
IMPORTANT: If you run in mpi/two mode, you must launch both codes via
mpirun, even if one or both of them runs on a single processor. This
is so that MPI can figure out how to connect both MPI processes
together to exchange MPI messages between them.
For message exchange in *file*, *zmq*, or *mpi/two* modes:
.. code-block:: bash
% mpirun -np 1 lmp_mpi -log log.client < in.client &
% mpirun -np 2 lmp_mpi -log log.server < in.server
% mpirun -np 4 lmp_mpi -log log.client < in.client &
% mpirun -np 1 lmp_mpi -log log.server < in.server
% mpirun -np 2 lmp_mpi -log log.client < in.client &
% mpirun -np 4 lmp_mpi -log log.server < in.server
For message exchange in *mpi/one* mode:
Launch both codes in a single mpirun command:
.. code-block:: bash
mpirun -np 2 lmp_mpi -mpicolor 0 -in in.message.client -log log.client : -np 4 lmp_mpi -mpicolor 1 -in in.message.server -log log.server
The two -np values determine how many procs the client and the server
run on.
A LAMMPS executable run in this manner must use the -mpicolor color
command-line option as their its option, where color is an integer
label that will be used to distinguish one executable from another in
the multiple executables that the mpirun command launches. In this
example the client was colored with a 0, and the server with a 1.

28
doc/src/Howto_couple.rst
View File

@ -12,16 +12,16 @@ LAMMPS can be coupled to other codes in at least 4 ways. Each has
advantages and disadvantages, which you will have to think about in the
context of your application.
1. Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During timestepping,
1. Define a new :doc:`fix <fix>` command that calls the other code.
In this scenario, LAMMPS is the driver code. During timestepping,
the fix is invoked, and can make library calls to the other code,
which has been linked to LAMMPS as a library. This is the way how the
which has been linked to LAMMPS as a library. This is the way the
:ref:`LATTE <PKG-LATTE>` package, which performs density-functional
tight-binding calculations using the `LATTE software <https://github.com/lanl/LATTE>`_
to compute forces, is hooked to LAMMPS.
See the :doc:`fix latte <fix_latte>` command for more details.
Also see the :doc:`Modify <Modify>` doc pages for info on how to
add a new fix to LAMMPS.
tight-binding calculations using the `LATTE software
<https://github.com/lanl/LATTE>`_ to compute forces, is hooked to
LAMMPS. See the :doc:`fix latte <fix_latte>` command for more
details. Also see the :doc:`Modify <Modify>` doc pages for info on
how to add a new fix to LAMMPS.
.. spacer
@ -58,6 +58,12 @@ context of your application.
.. spacer
4. Couple LAMMPS with another code in a client/server mode. This is
described on the :doc:`Howto client/server <Howto_client_server>` doc
page.
4. Couple LAMMPS with another code in a client/server fashion, using
using the `MDI Library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_ to run LAMMPS as either an MDI driver
(client) or an MDI engine (server). The MDI driver issues commands
to the MDI server to exchange data between them. See the
:doc:`Howto mdi <Howto_mdi>` page for more information about how
LAMMPS can operate in either of these modes.

5
doc/src/Howto_drude2.rst
View File

@ -491,11 +491,6 @@ NPT ensemble using Nose-Hoover thermostat:
**(Schroeder)** Schroeder and Steinhauser, J Chem Phys, 133,
154511 (2010).
.. _Jiang2:
**(Jiang)** Jiang, Hardy, Phillips, MacKerell, Schulten, and Roux,
J Phys Chem Lett, 2, 87-92 (2011).
.. _Thole2:
**(Thole)** Chem Phys, 59, 341 (1981).

39
doc/src/Howto_elastic.rst
View File

@ -18,23 +18,52 @@ At zero temperature, it is easy to estimate these derivatives by
deforming the simulation box in one of the six directions using the
:doc:`change_box <change_box>` command and measuring the change in the
stress tensor. A general-purpose script that does this is given in the
examples/elastic directory described on the :doc:`Examples <Examples>`
examples/ELASTIC directory described on the :doc:`Examples <Examples>`
doc page.
Calculating elastic constants at finite temperature is more
challenging, because it is necessary to run a simulation that performs
time averages of differential properties. One way to do this is to
measure the change in average stress tensor in an NVT simulations when
time averages of differential properties. There are at least
3 ways to do this in LAMMPS. The most reliable way to do this is
by exploiting the relationship between elastic constants, stress
fluctuations, and the Born matrix, the second derivatives of energy
w.r.t. strain :ref:`(Ray) <Ray>`.
The Born matrix calculation has been enabled by
the :doc:`compute born/matrix <compute_born_matrix>` command,
which works for any bonded or non-bonded potential in LAMMPS.
The most expensive part of the calculation is the sampling of
the stress fluctuations. Several examples of this method are
provided in the examples/ELASTIC_T/BORN_MATRIX directory
described on the :doc:`Examples <Examples>` doc page.
A second way is to measure
the change in average stress tensor in an NVT simulations when
the cell volume undergoes a finite deformation. In order to balance
the systematic and statistical errors in this method, the magnitude of
the deformation must be chosen judiciously, and care must be taken to
fully equilibrate the deformed cell before sampling the stress
tensor. Another approach is to sample the triclinic cell fluctuations
tensor. An example of this method is provided in the
examples/ELASTIC_T/DEFORMATION directory
described on the :doc:`Examples <Examples>` doc page.
Another approach is to sample the triclinic cell fluctuations
that occur in an NPT simulation. This method can also be slow to
converge and requires careful post-processing :ref:`(Shinoda) <Shinoda1>`
converge and requires careful post-processing :ref:`(Shinoda) <Shinoda1>`.
We do not provide an example of this method.
A nice review of the advantages and disadvantages of all of these methods
is provided in the paper by Clavier et al. :ref:`(Clavier) <Clavier>`.
----------
.. _Ray:
**(Ray)** J. R. Ray and A. Rahman, J Chem Phys, 80, 4423 (1984).
.. _Shinoda1:
**(Shinoda)** Shinoda, Shiga, and Mikami, Phys Rev B, 69, 134103 (2004).
.. _Clavier:
**(Clavier)** G. Clavier, N. Desbiens, E. Bourasseau, V. Lachet, N. Brusselle-Dupend and B. Rousseau, Mol Sim, 43, 1413 (2017).

216
doc/src/Howto_mdi.rst
View File

@ -1,132 +1,144 @@
Using LAMMPS with the MDI library for code coupling
===================================================
.. note::
This Howto page will eventually replace the
:doc:`Howto client/server <Howto_client_server>` doc page.
Client/server coupling of two codes is where one code is the "client"
and sends request messages (data) to a "server" code. The server
responds to each request with a reply message. This enables the two
codes to work in tandem to perform a simulation. LAMMPS can act as
either a client or server code; it does this by using the `MolSSI
Driver Interface (MDI) library
Client/server coupling of two (or more) codes is where one code is the
"client" and sends request messages (data) to one (or more) "server"
code(s). A server responds to each request with a reply message
(data). This enables two (or more) codes to work in tandem to perform
a simulation. LAMMPS can act as either a client or server code; it
does this by using the `MolSSI Driver Interface (MDI) library
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_,
developed by the `Molecular Sciences Software Institute (MolSSI)
<https://molssi.org>`_.
<https://molssi.org>`_, which is supported by the :ref:`MDI <PKG-MDI>`
package.
Alternate methods for code coupling with LAMMPS are described on the
:doc:`Howto couple <Howto_couple>` doc page.
Some advantages of client/server coupling are that the two codes can run
Some advantages of client/server coupling are that the codes can run
as stand-alone executables; they need not be linked together. Thus
neither code needs to have a library interface. This also makes it easy
to run the two codes on different numbers of processors. If a message
protocol (format and content) is defined for a particular kind of
simulation, then in principle any code which implements the client-side
protocol can be used in tandem with any code which implements the
server-side protocol. Neither code needs to know what specific other
code it is working with.
neither code needs to have a library interface. This also makes it
easy to run the two codes on different numbers of processors. If a
message protocol (format and content) is defined for a particular kind
of simulation, then in principle any code which implements the
client-side protocol can be used in tandem with any code which
implements the server-side protocol. Neither code needs to know what
specific other code it is working with.
In MDI nomenclature, a client code is the "driver", and a server code is
an "engine". One driver code can communicate with one or more instances
of one or more engine codes. Driver and engine codes can be written in
any language: C, C++, Fortran, Python, etc.
In addition to allowing driver and engine(s) running to run as
stand-alone executables, MDI also enables a server code to be a
"plugin" to the client code. In this scenario, server code(s) are
compiled as shared libraries, and one (or more) instances of the
server are instantiated by the driver code. If the driver code runs
in parallel, it can split its MPI communicator into multiple
sub-communicators, and launch each plugin engine instance on a
sub-communicator. Driver processors in that sub-communicator exchange
messages with that engine instance, and can also send MPI messages to
other processors in the driver. The driver code can also destroy
engine instances and re-instantiate them.
In addition to allowing driver and engine(s) to run as stand-alone
executables, MDI also enables an engine to be a *plugin* to the client
code. In this scenario, server code(s) are compiled as shared
libraries, and one (or more) instances of the server are instantiated
by the driver code. If the driver code runs in parallel, it can split
its MPI communicator into multiple sub-communicators, and launch each
plugin engine instance on a sub-communicator. Driver processors
within that sub-communicator exchange messages with the corresponding
engine instance, and can also send MPI messages to other processors in
the driver. The driver code can also destroy engine instances and
re-instantiate them. LAMMPS can operate as either a stand-alone or
plugin MDI engine. When it operates as a driver, if can use either
stand-alone or plugin MDI engines.
The way that a driver communicates with an engine is by making
MDI_Send() and MDI_Recv() calls, which are conceptually similar to
MPI_Send() and MPI_Recv() calls. Each send or receive has a string
which identifies the command name, and optionally some data, which can
be a single value or vector of values of any data type. Inside the
MDI library, data is exchanged between the driver and engine via MPI
calls or sockets. This a run-time choice by the user.
The way in which an MDI driver communicates with an MDI engine is by
making MDI_Send() and MDI_Recv() calls, which are conceptually similar
to MPI_Send() and MPI_Recv() calls. Each send or receive operation
uses a string to identify the command name, and optionally some data,
which can be a single value or vector of values of any data type.
Inside the MDI library, data is exchanged between the driver and
engine via MPI calls or sockets. This a run-time choice by the user.
----------
The :ref:`MDI <PKG-MDI>` package provides a :doc:`mdi engine <mdi>`
command which enables LAMMPS to operate as an MDI engine. Its doc
page explains the variety of standard and custom MDI commands which
the LAMMPS engine recognizes and can respond to.
The package also provides a :doc:`mdi plugin <mdi>` command which
enables LAMMPS to operate as an MDI driver and load an MDI engine as a
plugin library.
The package also has a `fix mdi/aimd <fix_mdi_aimd>` command in which
LAMMPS operates as an MDI driver to perform *ab initio* MD simulations
in conjunction with a quantum mechanics code. Its post_force() method
illustrates how a driver issues MDI commands to another code. This
command can be used to couple to an MDI engine which is either a
stand-alone code or a plugin library.
----------
The examples/mdi directory contains Python scripts and LAMMPS input
script which use LAMMPS as either an MDI driver or engine or both.
Three example use cases are provided:
* Run ab initio MD (AIMD) using 2 instances of LAMMPS, one as driver
and one as an engine. As an engine, LAMMPS is a surrogate for a
quantum code.
* A Python script driver invokes a sequence of unrelated LAMMPS
calculations. Calculations can be single-point energy/force
evaluations, MD runs, or energy minimizations.
* Run AIMD with a Python driver code and 2 LAMMPS instances as
engines. The first LAMMPS instance performs MD timestepping. The
second LAMMPS instance acts as a surrogate QM code to compute
forces.
Note that in any of these example where LAMMPS is used as an engine,
an actual QM code (which supports MDI) could be used in its place,
without modifying other code or scripts, except to specify the name of
the QM code.
The examples/mdi/README file explains how to launch both driver and
engine codes so that they communicate using the MDI library via either
MPI or sockets.
-------------
As an example, LAMMPS and the ``pw.x`` command from Quantum Espresso (a
suite of quantum DFT codes), can work together via the MDI library to
perform an ab initio MD (AIMD) simulation, where LAMMPS runs an MD
simulation and sends a message each timestep to ``pw.x`` asking it to
compute quantum forces on the current configuration of atoms. Here is
how the 2 codes are launched to communicate by MPI:
Currently there are two quantum DFT codes which have direct MDI
support, `Quantum ESPRESSO (QE) <https://www.quantum-espresso.org/>`_
and `INQ <https://qsg.llnl.gov/node/101.html>`_. There are also
several QM codes which have indirect support through QCEngine or i-PI.
The former means they require a wrapper program (QCEngine) with MDI
support which writes/read files to pass data to the quantum code
itself. The list of QCEngine-supported and i-PI-supported quantum
codes is on the `MDI webpage
<https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
Here is how to build QE as a stand-alone ``pw.x`` file which can be
used in stand-alone mode:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method MPI" \
-in in.aimd : -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method MPI"
% git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
% build the executable pw.x, following the `QE build guide <https://gitlab.com/QEF/q-e/-/wikis/Developers/CMake-build-system>`_
In this case LAMMPS runs on 2 processors (MPI tasks), ``pw.x`` runs on 16
processors.
Here is how the 2 codes are launched to communicate by sockets:
Here is how to build QE as a shared library which can be used in plugin mode,
which results in a libqemdi.so file in <base_path>/q-e/MDI/src:
.. code-block:: bash
% mpirun -np 2 lmp_mpi -mdi "-role DRIVER -name d -method TCP -port 8021" -in in.aimd
% mpirun -np 16 pw.x -in qe.in -mdi "-role ENGINE -name e -method TCP -port 8021 -hostname localhost"
% git clone --branch mdi_plugin https://github.com/MolSSI-MDI/q-e.git <base_path>/q-e
% cd <base_path>/q-e
% ./configure --enable-parallel --enable-openmp --enable-shared FFLAGS="-fPIC" FCFLAGS="-fPIC" CFLAGS="-fPIC" foxflags="-fPIC" try_foxflags="-fPIC"
% make -j 4 mdi
These commands could be issued in different windows on a desktop
machine. Or in the same window, if the first command is ended with
"&" so as to run in the background. If "localhost" is replaced by an
IP address, ``pw.x`` could be run on another machine on the same network, or
even on another machine across the country.
INQ cannot be built as a stand-alone code; it is by design a library.
Here is how to build INQ as a shared library which can be used in
plugin mode, which results in a libinqmdi.so file in
<base_path>/inq/build/examples:
After both codes initialize themselves to model the same system, this is
what occurs each timestep:
.. code-block:: bash
* LAMMPS send a ">COORDS" message to ``pw.x`` with a 3*N vector of current atom coords
* ``pw.x`` receives the message/coords and computes quantum forces on all the atoms
* LAMMPS send a "<FORCES" message to ``pw.x`` and waits for the result
* ``pw.x`` receives the message (after its computation finishes) and sends a 3*N vector of forces
* LAMMPS receives the forces and time integrates to complete a single timestep
-------------
Examples scripts for using LAMMPS as an MDI engine are in the
examples/mdi directory. See the README file in that directory for
instructions on how to run the examples.
.. note::
Work is underway to add commands that allow LAMMPS to be used as an
MDI driver, e.g. for the AIMD example discussed above. Example
scripts for this usage mode will be added the same directory when
available.
If LAMMPS is used as a stand-alone engine it should set up the system
it will be modeling in its input script, then invoke the
:doc:`mdi/engine <mdi_engine>` command. This will put LAMMPS into
"engine mode" where it waits for messages and data from the driver.
When the driver sends an "EXIT" command, LAMMPS will exit engine mode
and the input script will continue.
If LAMMPS is used as a plugin engine it operates the same way, except
that the driver will pass LAMMPS an input script to initialize itself.
Upon receiving the "EXIT" command, LAMMPS will exit engine mode and the
input script will continue. After finishing execution of the input
script, the instance of LAMMPS will be destroyed.
LAMMPS supports the full set of MD-appropriate engine commands defined
by the MDI library. See the :doc:`mdi/engine <mdi_engine>` page for
a list of these.
If those commands are not sufficient for a user-developed driver to use
LAMMPS as an engine, then new commands can be easily added. See these
two files which implement the definition of MDI commands and the logic
for responding to them:
* src/MDI/mdi_engine.cpp
* src/MDI/fix_mdi_engine.cpp
% git clone --branch mdi --recurse-submodules https://gitlab.com/taylor-a-barnes/inq.git <base_path>/inq
% cd <base_path>/inq
% mkdir -p build
% cd build
% ../configure --prefix=<install_path>/install
% make -j 4
% make install

2
doc/src/Howto_pylammps.rst
View File

@ -545,6 +545,6 @@ Feedback and Contributing
-------------------------
If you find this Python interface useful, please feel free to provide feedback
and ideas on how to improve it to Richard Berger (richard.berger@temple.edu). We also
and ideas on how to improve it to Richard Berger (richard.berger@outlook.com). We also
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
and maybe their latest research results.

59
doc/src/Howto_structured_data.rst
View File

@ -21,7 +21,8 @@ YAML
print """---
timestep: $(step)
pe: $(pe)
ke: $(ke)""" file current_state.yaml screen no
ke: $(ke)
...""" file current_state.yaml screen no
.. code-block:: yaml
:caption: current_state.yaml
@ -51,6 +52,62 @@ JSON
"ke": 2.4962152903997174569
}
YAML format thermo_style output
===============================
.. versionadded:: 24Mar2022
LAMMPS supports the thermo style "yaml" and for "custom" style
thermodynamic output the format can be changed to YAML with
:doc:`thermo_modify line yaml <thermo_modify>`. This will produce a
block of output in a compact YAML format - one "document" per run - of
the following style:
.. code-block:: yaml
---
keywords: [Step, Temp, E_pair, E_mol, TotEng, Press, ]
data:
- [100, 0.757453103239935, -5.7585054860159, 0, -4.62236133677021, 0.207261053624721, ]
- [110, 0.759322359337036, -5.7614668389562, 0, -4.62251889318624, 0.194314975399602, ]
- [120, 0.759372342462676, -5.76149365656489, 0, -4.62247073844943, 0.191600048851267, ]
- [130, 0.756833027516501, -5.75777334823494, 0, -4.62255928350835, 0.208792327853067, ]
...
This data can be extracted and parsed from a log file using python with:
.. code-block:: python
import re, yaml
try:
from yaml import CSafeLoader as Loader, CSafeDumper as Dumper
except ImportError:
from yaml import SafeLoader as Loader, SafeDumper as Dumper
docs = ""
with open("log.lammps") as f:
for line in f:
m = re.search(r"^(keywords:.*$|data:$|---$|\.\.\.$| - \[.*\]$)", line)
if m: docs += m.group(0) + '\n'
thermo = list(yaml.load_all(docs, Loader=Loader))
print("Number of runs: ", len(thermo))
print(thermo[1]['keywords'][4], ' = ', thermo[1]['data'][2][4])
After loading the YAML data, `thermo` is a list containing a dictionary
for each "run" where the tag "keywords" maps to the list of thermo
header strings and the tag "data" has a list of lists where the outer
list represents the lines of output and the inner list the values of the
columns matching the header keywords for that step. The second print()
command for example will print the header string for the fifth keyword
of the second run and the corresponding value for the third output line
of that run:
.. parsed-literal::
Number of runs: 2
TotEng = -4.62140097780047
Writing continuous data during a simulation
===========================================

3
doc/src/Install_git.rst
View File

@ -165,5 +165,4 @@ changed. How to do this depends on the build system you are using.
URL "git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer
(Temple U, akohlmey at gmail.com) and Richard Berger (Temple U,
richard.berger at temple.edu).
(Temple U, akohlmey at gmail.com).

2
doc/src/Install_mac.rst
View File

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

2
doc/src/Install_tarball.rst
View File

@ -6,7 +6,7 @@ of the `LAMMPS website <lws_>`_.
.. _download: https://www.lammps.org/download.html
.. _bug: https://www.lammps.org/bug.html
.. _older: https://www.lammps.org/tars
.. _older: https://download.lammps.org/tars/
.. _lws: https://www.lammps.org
You have two choices of tarballs, either the most recent stable

2
doc/src/Intro_authors.rst
View File

@ -8,7 +8,7 @@ University:
* Aidan Thompson, athomps at sandia.gov
* Stan Moore, stamoor at sandia.gov
* Axel Kohlmeyer, akohlmey at gmail.com
* Richard Berger, richard.berger at temple.edu
* Richard Berger, richard.berger at outlook.com
.. _sjp: http://www.cs.sandia.gov/~sjplimp
.. _lws: https://www.lammps.org

2
doc/src/Intro_citing.rst
View File

@ -46,7 +46,7 @@ In addition there are DOIs for individual stable releases. Currently there are:
- 3 March 2020 version: `DOI:10.5281/zenodo.3726417 <https://dx.doi.org/10.5281/zenodo.3726417>`_
- 29 October 2020 version: `DOI:10.5281/zenodo.4157471 <https://dx.doi.org/10.5281/zenodo.4157471>`_
- 29 September 2021 version: `DOI:10.5281/zenodo.6386596 <https//dx.doi.org/10.5281/zenodo.6386596>`_
Home page
^^^^^^^^^

1
doc/src/Intro_website.rst
View File

@ -20,7 +20,6 @@ available online are listed below.
* `Glossary of terms relevant to LAMMPS <https://www.lammps.org/glossary.html>`_
* `LAMMPS highlights with images <https://www.lammps.org/pictures.html>`_
* `LAMMPS highlights with movies <https://www.lammps.org/movies.html>`_
* `Mailing list <https://www.lammps.org/mail.html>`_
* `LAMMPS forum <https://www.lammps.org/forum.html>`_
* `Workshops <https://www.lammps.org/workshops.html>`_
* `Tutorials <https://www.lammps.org/tutorials.html>`_

6
doc/src/Library_utility.rst
View File

@ -13,6 +13,7 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_fix_external_set_virial_peratom`
- :cpp:func:`lammps_fix_external_set_vector_length`
- :cpp:func:`lammps_fix_external_set_vector`
- :cpp:func:`lammps_flush_buffers`
- :cpp:func:`lammps_free`
- :cpp:func:`lammps_is_running`
- :cpp:func:`lammps_force_timeout`
@ -72,6 +73,11 @@ where such memory buffers were allocated that require the use of
-----------------------
.. doxygenfunction:: lammps_flush_buffers
:project: progguide
-----------------------
.. doxygenfunction:: lammps_free
:project: progguide

10
doc/src/Manual.rst
View File

@ -14,11 +14,11 @@ LAMMPS is an open-source code, distributed freely under the terms of
the GNU Public License Version 2 (GPLv2).
The `LAMMPS website <lws_>`_ has a variety of information about the
code. It includes links to an on-line version of this manual, a
`mailing list <https://www.lammps.org/mail.html>`_ and
`online forum <https://www.lammps.org/forum.html>`_ where users can
post questions, and a `GitHub site <https://github.com/lammps/lammps>`_
where all LAMMPS development is coordinated.
code. It includes links to an on-line version of this manual, an
`online forum <https://www.lammps.org/forum.html>`_ where users can post
questions and discuss LAMMPS, and a `GitHub site
<https://github.com/lammps/lammps>`_ where all LAMMPS development is
coordinated.
----------

17
doc/src/Modify.rst
View File

@ -1,16 +1,17 @@
Modifying & extending LAMMPS
****************************
LAMMPS is designed in a modular fashion so as to be easy to modify and
LAMMPS is designed in a modular fashion and to be easy to modify or
extend with new functionality. In fact, about 95% of its source code
is add-on files. These doc pages give basic instructions on how to do
this.
are optional. The following pages give basic instructions on what
is required when adding new styles of different kinds to LAMMPS.
If you add a new feature to LAMMPS and think it will be of interest to
general users, we encourage you to submit it for inclusion in LAMMPS
as a pull request on our `GitHub site <https://github.com/lammps/lammps>`_,
after reading about :doc:`how to prepare your code for submission <Modify_contribute>`
and :doc:`the style requirements and recommendations <Modify_style>`.
If you add a new feature to LAMMPS and think it will be of general
interest to other users, we encourage you to submit it for inclusion in
LAMMPS as a pull request on our `GitHub site
<https://github.com/lammps/lammps>`_, after reading about :doc:`how to
prepare your code for submission <Modify_contribute>` and :doc:`the
style requirements and recommendations <Modify_style>`.
.. toctree::
:maxdepth: 1

81
doc/src/Modify_atom.rst
View File

@ -9,34 +9,34 @@ A new atom style can be created if one of the existing atom styles
does not define all the attributes you need to store and communicate
with atoms.
Atom_vec_atomic.cpp is the simplest example of an atom style.
The file ``atom_vec_atomic.cpp`` is the simplest example of an atom style.
Examining the code for others will make these instructions more clear.
Note that the :doc:`atom style hybrid <atom_style>` command can be
used to define atoms or particles which have the union of properties
of individual styles. Also the :doc:`fix property/atom <fix_property_atom>`
command can be used to add a single property (e.g. charge
or a molecule ID) to a style that does not have it. It can also be
used to add custom properties to an atom, with options to communicate
them with ghost atoms or read them from a data file. Other LAMMPS
commands can access these custom properties, as can new pair, fix,
compute styles that are written to work with these properties. For
Note that the :doc:`atom style hybrid <atom_style>` command can be used
to define atoms or particles which have the union of properties of
individual styles. Also the :doc:`fix property/atom
<fix_property_atom>` command can be used to add a single property
(e.g. charge or a molecule ID) to a style that does not have it. It can
also be used to add custom properties to an atom, with options to
communicate them with ghost atoms or read them from a data file. Other
LAMMPS commands can access these custom properties, as can new pair,
fix, compute styles that are written to work with these properties. For
example, the :doc:`set <set>` command can be used to set the values of
custom per-atom properties from an input script. All of these methods
are less work than writing code for a new atom style.
are less work than writing and testing(!) code for a new atom style.
If you follow these directions your new style will automatically work
in tandem with others via the :doc:`atom_style hybrid <atom_style>`
command.
The first step is to define a set of strings in the constructor of the
new derived class. Each string will have zero or more space-separated
variable names which are identical to those used in the atom.h header
file for per-atom properties. Note that some represent per-atom
The first step is to define a set of string lists in the constructor of
the new derived class. Each list will have zero or more comma-separated
strings that correspond to the variable names used in the ``atom.h``
header file for per-atom properties. Note that some represent per-atom
vectors (q, molecule) while other are per-atom arrays (x,v). For all
but the last 2 strings you do not need to specify any of
but the last two lists you do not need to specify any of
(id,type,x,v,f). Those are included automatically as needed in the
other strings.
other lists.
.. list-table::
@ -65,16 +65,16 @@ other strings.
* - fields_data_vel
- list of properties (in order) in the Velocities section of a data file, as read by :doc:`read_data <read_data>`
In these strings you can list variable names which LAMMPS already
defines (in some other atom style), or you can create new variable
names. You should not re-use a LAMMPS variable for something with
different meaning in your atom style. If the meaning is related, but
interpreted differently by your atom style, then using the same
variable name means a user should not use your style and the other
style together in a :doc:`atom_style hybrid <atom_style>` command.
Because there will only be one value of the variable and different
parts of LAMMPS will then likely use it differently. LAMMPS has
no way of checking for this.
In these lists you can list variable names which LAMMPS already defines
(in some other atom style), or you can create new variable names. You
should not re-use a LAMMPS variable in your atom style that is used for
something with a different meaning in another atom style. If the
meaning is related, but interpreted differently by your atom style, then
using the same variable name means a user must not use your style and
the other style together in a :doc:`atom_style hybrid <atom_style>`
command. Because there will only be one value of the variable and
different parts of LAMMPS will then likely use it differently. LAMMPS
has no way of checking for this.
If you are defining new variable names then make them descriptive and
unique to your new atom style. For example choosing "e" for energy is
@ -85,32 +85,31 @@ If any of the variable names in your new atom style do not exist in
LAMMPS, you need to add them to the src/atom.h and atom.cpp files.
Search for the word "customize" or "customization" in these 2 files to
see where to add your variable. Adding a flag to the 2nd
customization section in atom.h is only necessary if your code (e.g. a
pair style) needs to check that a per-atom property is defined. These
flags should also be set in the constructor of the atom style child
class.
see where to add your variable. Adding a flag to the 2nd customization
section in ``atom.h`` is only necessary if your code (e.g. a pair style)
needs to check that a per-atom property is defined. These flags should
also be set in the constructor of the atom style child class.
In atom.cpp, aside from the constructor and destructor, there are 3
In ``atom.cpp``, aside from the constructor and destructor, there are 3
methods that a new variable name or flag needs to be added to.
In Atom::peratom_create() when using the add_peratom() method, a
final length argument of 0 is for per-atom vectors, a length > 1 is
for per-atom arrays. Note the use of an extra per-thread flag and the
add_peratom_vary() method when last dimension of the array is
In ``Atom::peratom_create()`` when using the ``Atom::add_peratom()``
method, a cols argument of 0 is for per-atom vectors, a length >
1 is for per-atom arrays. Note the use of the extra per-thread flag and
the add_peratom_vary() method when last dimension of the array is
variable-length.
Adding the variable name to Atom::extract() enable the per-atom data
Adding the variable name to Atom::extract() enables the per-atom data
to be accessed through the :doc:`LAMMPS library interface
<Howto_library>` by a calling code, including from :doc:`Python
<Python_head>`.
The constructor of the new atom style will also typically set a few
flags which are defined at the top of atom_vec.h. If these are
flags which are defined at the top of ``atom_vec.h``. If these are
unclear, see how other atom styles use them.
The grow_pointers() method is also required to make
a copy of peratom data pointers, as explained in the code.
The grow_pointers() method is also required to make a copy of peratom
data pointers, as explained in the code.
There are a number of other optional methods which your atom style can
implement. These are only needed if you need to do something

9
doc/src/Modify_contribute.rst
View File

@ -27,11 +27,10 @@ join the `LAMMPS developers on Slack <https://lammps.slack.com>`_. This
slack work space is by invitation only. Thus for access, please send an
e-mail to ``slack@lammps.org`` explaining what part of LAMMPS you are
working on. Only discussions related to LAMMPS development are
tolerated in that work space, so this is **NOT** for people that look for
help with compiling, installing, or using LAMMPS. Please post a message
to the `lammps-users mailing list <https://www.lammps.org/mail.html>`_
or the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for those
purposes.
tolerated in that work space, so this is **NOT** for people that look
for help with compiling, installing, or using LAMMPS. Please post a
message to the `LAMMPS forum <https://www.lammps.org/forum.html>`_ for
those purposes.
Packages versus individual files
--------------------------------

15
doc/src/Modify_overview.rst
View File

@ -1,13 +1,14 @@
Overview
========
The best way to add a new feature to LAMMPS is to find a similar
feature and look at the corresponding source and header files to figure
out what it does. You will need some knowledge of C++ to be able to
understand the high-level structure of LAMMPS and its class
organization, but functions (class methods) that do actual
computations are written in vanilla C-style code and operate on simple
C-style data structures (vectors and arrays).
The best way to add a new feature to LAMMPS is to find a similar feature
and look at the corresponding source and header files to figure out what
it does. You will need some knowledge of C++ to be able to understand
the high-level structure of LAMMPS and its class organization, but
functions (class methods) that do actual computations are mostly written
in C-style code and operate on simple C-style data structures (vectors
and arrays). A high-level overview of the programming style choices in
LAMMPS is :doc:`given elsewhere <Developer_code_design>`.
Most of the new features described on the :doc:`Modify <Modify>` doc
page require you to write a new C++ derived class (except for exceptions

38
doc/src/Modify_pair.rst
View File

@ -12,24 +12,24 @@ includes some optional methods to enable its use with rRESPA.
Here is a brief description of the class methods in pair.h:
+---------------------------------+-------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+-------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+---------------------------------+-------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+-------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+-------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+-------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+-------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+-------------------------------------------------------------------+
| single | force and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+-------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+-------------------------------------------------------------------+
+---------------------------------+---------------------------------------------------------------------+
| compute | workhorse routine that computes pairwise interactions |
+---------------------------------+---------------------------------------------------------------------+
| settings | reads the input script line with arguments you define |
+---------------------------------+---------------------------------------------------------------------+
| coeff | set coefficients for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_one | perform initialization for one i,j type pair |
+---------------------------------+---------------------------------------------------------------------+
| init_style | initialization specific to this pair style |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart | write/read i,j pair coeffs to restart files |
+---------------------------------+---------------------------------------------------------------------+
| write & read_restart_settings | write/read global settings to restart files |
+---------------------------------+---------------------------------------------------------------------+
| single | force/r and energy of a single pairwise interaction between 2 atoms |
+---------------------------------+---------------------------------------------------------------------+
| compute_inner/middle/outer | versions of compute used by rRESPA |
+---------------------------------+---------------------------------------------------------------------+
The inner/middle/outer routines are optional.

105
doc/src/Modify_style.rst
View File

@ -223,6 +223,13 @@ and readable by all and no executable permissions. Executable
permissions (0755) should only be on shell scripts or python or similar
scripts for interpreted script languages.
You can check for these issues with the python scripts in the
:ref:`"tools/coding_standard" <coding_standard>` folder. When run
normally with a source file or a source folder as argument, they will
list all non-conforming lines. By adding the `-f` flag to the command
line, they will modify the flagged files to try removing the detected
issues.
Indentation and Placement of Braces (strongly preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -240,6 +247,53 @@ reformatting from clang-format yields undesirable output may be
protected with placing a pair `// clang-format off` and `// clang-format
on` comments around that block.
Error or warning messages and explanations (preferred)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. versionchanged:: 27Apr2022
Starting with LAMMPS version 27 April 2022 the LAMMPS developers have
agreed on a new policy for error and warning messages.
Previously, all error and warning strings were supposed to be listed in
the class header files with an explanation. Those would then be
regularly "harvested" and transferred to alphabetically sorted lists in
the manual. To avoid excessively long lists and to reduce effort, this
came with a requirement to have rather generic error messages (e.g.
"Illegal ... command"). To identify the specific cause, the name of the
source file and the line number of the error location would be printed,
so that one could look up the cause by reading the source code.
The new policy encourages more specific error messages that ideally
indicate the cause directly and no further lookup would be needed.
This is aided by using the `{fmt} library <https://fmt.dev>`_ to convert
the Error class commands so that they take a variable number of arguments
and error text will be treated like a {fmt} syntax format string.
Error messages should still kept to a single line or two lines at the most.
For more complex explanations or errors that have multiple possible
reasons, a paragraph should be added to the `Error_details` page with an
error code reference (e.g. ``.. _err0001:``) then the utility function
:cpp:func:`utils::errorurl() <LAMMPS_NS::utils::errorurl>` can be used
to generate an URL that will directly lead to that paragraph. An error
for missing arguments can be easily generated using the
:cpp:func:`utils::missing_cmd_args()
<LAMMPS_NS::utils::missing_cmd_args>` convenience function.
The transformation of existing LAMMPS code to this new scheme is ongoing
and - given the size of the LAMMPS source code - will take a significant
amount of time until completion. However, for new code following the
new approach is strongly preferred. The expectation is that the new
scheme will make it easier for LAMMPS users, developers, and
maintainers.
An example for this approach would be the
``src/read_data.cpp`` and ``src/atom.cpp`` files that implement the
:doc:`read_data <read_data>` and :doc:`atom_modify <atom_modify>`
commands and that may create :ref:`"Unknown identifier in data file" <err0001>`
errors that seem difficult to debug for users because they may have
one of multiple possible reasons, and thus require some additional explanations.
Programming language standards (required)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -250,9 +304,11 @@ keep the code readable to programmers that have limited C++ programming
experience. C++ constructs are acceptable when they help improving the
readability and reliability of the code, e.g. when using the
`std::string` class instead of manipulating pointers and calling the
string functions of the C library. In addition and number of convenient
:doc:`utility functions and classes <Developer_utils>` for recurring
tasks are provided.
string functions of the C library. In addition a collection of
convenient :doc:`utility functions and classes <Developer_utils>` for
recurring tasks and a collection of
:doc:`platform neutral functions <Developer_platform>` for improved
portability are provided.
Included Fortran code has to be compatible with the Fortran 2003
standard. Python code must be compatible with Python 3.5. Large parts
@ -261,10 +317,11 @@ compatible with Python 2.7. Compatibility with Python 2.7 is
desirable, but compatibility with Python 3.5 is **required**.
Compatibility with these older programming language standards is very
important to maintain portability, especially with HPC cluster
environments, which tend to be running older software stacks and LAMMPS
users may be required to use those older tools or not have the option to
install newer compilers.
important to maintain portability and availability of LAMMPS on many
platforms. This applies especially to HPC cluster environments, which
tend to be running older software stacks and LAMMPS users may be
required to use those older tools for access to advanced hardware
features or not have the option to install newer compilers or libraries.
Programming conventions (varied)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -305,6 +362,40 @@ you are uncertain, please ask.
FILE pointers and only be done on MPI rank 0. Use the :cpp:func:`utils::logmesg`
convenience function where possible.
- Usage of C++11 `virtual`, `override`, `final` keywords: Please follow the
`C++ Core Guideline C.128 <https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override>`_.
That means, you should only use `virtual` to declare a new virtual
function, `override` to indicate you are overriding an existing virtual
function, and `final` to prevent any further overriding.
- Trivial destructors: Prefer not writing destructors when they are empty and `default`.
.. code-block:: c++
// don't write destructors for A or B like this
class A : protected Pointers {
public:
A();
~A() override {}
};
class B : protected Pointers {
public:
B();
~B() override = default;
};
// instead, let the compiler create the implicit default destructor by not writing it
class A : protected Pointers {
public:
A();
};
class B : protected Pointers {
public:
B();
};
- Header files, especially those defining a "style", should only use
the absolute minimum number of include files and **must not** contain
any ``using`` statements. Typically that would be only the header for

67
doc/src/Modify_thermo.rst
View File

@ -1,27 +1,54 @@
Thermodynamic output options
============================
There is one class that computes and prints thermodynamic information
to the screen and log file; see the file thermo.cpp.
The ``Thermo`` class computes and prints thermodynamic information to
the screen and log file; see the files ``thermo.cpp`` and ``thermo.h``.
There are two styles defined in thermo.cpp: "one" and "multi". There
is also a flexible "custom" style which allows the user to explicitly
list keywords for quantities to print when thermodynamic info is
output. See the :doc:`thermo_style <thermo_style>` command for a list
of defined quantities.
There are four styles defined in ``thermo.cpp``: "one", "multi", "yaml",
and "custom". The "custom" style allows the user to explicitly list
keywords for individual quantities to print when thermodynamic output is
generated. The others have a fixed list of keywords. See the
:doc:`thermo_style <thermo_style>` command for a list of available
quantities. The formatting of the "custom" style defaults to the "one"
style, but can be adapted using :doc:`thermo_modify line <thermo_modify>`.
The thermo styles (one, multi, etc) are simply lists of keywords.
Adding a new style thus only requires defining a new list of keywords.
Search for the word "customize" with references to "thermo style" in
thermo.cpp to see the two locations where code will need to be added.
The thermo styles (one, multi, etc) are defined by lists of keywords
with associated formats for integer and floating point numbers and
identified but an enumerator constant. Adding a new style thus mostly
requires defining a new list of keywords and the associated formats and
then inserting the required output processing where the enumerators are
identified. Search for the word "CUSTOMIZATION" with references to
"thermo style" in the ``thermo.cpp`` file to see the locations where
code will need to be added. The member function ``Thermo::header()``
prints output at the very beginning of a thermodynamic output block and
can be used to print column headers or other front matter. The member
function ``Thermo::footer()`` prints output at the end of a
thermodynamic output block. The formatting of the output is done by
assembling a "line" (which may span multiple lines if the style inserts
newline characters ("\n" as in the "multi" style).
New keywords can also be added to thermo.cpp to compute new quantities
for output. Search for the word "customize" with references to
"keyword" in thermo.cpp to see the several locations where code will
need to be added.
New thermodynamic keywords can also be added to ``thermo.cpp`` to
compute new quantities for output. Search for the word "CUSTOMIZATION"
with references to "keyword" in ``thermo.cpp`` to see the several
locations where code will need to be added. Effectively, you need to
define a member function that computes the property, add an if statement
in ``Thermo::parse_fields()`` where the corresponding header string for
the keyword and the function pointer is registered by calling the
``Thermo::addfield()`` method, and add an if statement in
``Thermo::evaluate_keyword()`` which is called from the ``Variable``
class when a thermo keyword is encountered.
Note that the :doc:`thermo_style custom <thermo_style>` command already allows
for thermo output of quantities calculated by :doc:`fixes <fix>`,
:doc:`computes <compute>`, and :doc:`variables <variable>`. Thus, it may
be simpler to compute what you wish via one of those constructs, than
by adding a new keyword to the thermo command.
.. note::
The third argument to ``Thermo::addfield()`` is a flag indicating
whether the function for the keyword computes a floating point
(FLOAT), regular integer (INT), or big integer (BIGINT) value. This
information is used for formatting the thermodynamic output. Inside
the function the result must then be stored either in the ``dvalue``,
``ivalue`` or ``bivalue`` member variable, respectively.
Since the :doc:`thermo_style custom <thermo_style>` command allows to
use output of quantities calculated by :doc:`fixes <fix>`,
:doc:`computes <compute>`, and :doc:`variables <variable>`, it may often
be simpler to compute what you wish via one of those constructs, rather
than by adding a new keyword to the thermo_style command.

19
doc/src/Modify_variable.rst
View File

@ -1,8 +1,8 @@
Variable options
================
There is one class that computes and stores :doc:`variable <variable>`
information in LAMMPS; see the file variable.cpp. The value
The ``Variable`` class computes and stores :doc:`variable <variable>`
information in LAMMPS; see the file ``variable.cpp``. The value
associated with a variable can be periodically printed to the screen
via the :doc:`print <print>`, :doc:`fix print <fix_print>`, or
:doc:`thermo_style custom <thermo_style>` commands. Variables of style
@ -19,21 +19,22 @@ of arguments:
compute values = c_mytemp[0], c_thermo_press[3], ...
Adding keywords for the :doc:`thermo_style custom <thermo_style>`
command (which can then be accessed by variables) is discussed on the
:doc:`Modify thermo <Modify_thermo>` doc page.
command (which can then be accessed by variables) is discussed in the
:doc:`Modify thermo <Modify_thermo>` documentation.
Adding a new math function of one or two arguments can be done by
editing one section of the Variable::evaluate() method. Search for
editing one section of the ``Variable::evaluate()`` method. Search for
the word "customize" to find the appropriate location.
Adding a new group function can be done by editing one section of the
Variable::evaluate() method. Search for the word "customize" to find
the appropriate location. You may need to add a new method to the
Group class as well (see the group.cpp file).
``Variable::evaluate()`` method. Search for the word "customize" to
find the appropriate location. You may need to add a new method to the
Group class as well (see the ``group.cpp`` file).
Accessing a new atom-based vector can be done by editing one section
of the Variable::evaluate() method. Search for the word "customize"
to find the appropriate location.
Adding new :doc:`compute styles <compute>` (whose calculated values can
then be accessed by variables) is discussed on the :doc:`Modify compute <Modify_compute>` doc page.
then be accessed by variables) is discussed in the :doc:`Modify compute
<Modify_compute>` documentation.

99
doc/src/Packages_details.rst
View File

@ -9,7 +9,7 @@ gives links to documentation, example scripts, and pictures/movies (if
available) that illustrate use of the package.
The majority of packages can be included in a LAMMPS build with a
single setting (``-D PGK_<NAME>=on`` for CMake) or command
single setting (``-D PKG_<NAME>=on`` for CMake) or command
(``make yes-<name>`` for make). See the :doc:`Build package <Build_package>`
page for more info. A few packages may require additional steps;
this is indicated in the descriptions below. The :doc:`Build extras <Build_extras>`
@ -32,6 +32,7 @@ page gives those details.
* :ref:`AWPMD <PKG-AWPMD>`
* :ref:`BOCS <PKG-BOCS>`
* :ref:`BODY <PKG-BODY>`
* :ref:`BPM <PKG-BPM>`
* :ref:`BROWNIAN <PKG-BROWNIAN>`
* :ref:`CG-DNA <PKG-CG-DNA>`
* :ref:`CG-SDK <PKG-CG-SDK>`
@ -72,7 +73,6 @@ page gives those details.
* :ref:`MDI <PKG-MDI>`
* :ref:`MEAM <PKG-MEAM>`
* :ref:`MESONT <PKG-MESONT>`
* :ref:`MESSAGE <PKG-MESSAGE>`
* :ref:`MGPT <PKG-MGPT>`
* :ref:`MISC <PKG-MISC>`
* :ref:`ML-HDNNP <PKG-ML-HDNNP>`
@ -284,6 +284,33 @@ overview.
----------
.. _PKG-BPM:
BPM package
------------
**Contents:**
Pair styles, bond styles, fixes, and computes for bonded particle
models for mesoscale simulations of solids and fracture. See the
:doc:`Howto bpm <Howto_bpm>` page for an overview.
**Authors:** Joel T. Clemmer (Sandia National Labs)
**Supporting info:**
* src/BPM filenames -> commands
* :doc:`Howto_bpm <Howto_bpm>`
* :doc:`atom_style bpm/sphere <atom_style>`
* :doc:`bond_style bpm/rotational <bond_bpm_rotational>`
* :doc:`bond_style bpm/spring <bond_bpm_spring>`
* :doc:`compute nbond/atom <compute_nbond_atom>`
* :doc:`fix nve/bpm/sphere <fix_nve_bpm_sphere>`
* :doc:`pair_style bpm/spring <pair_bpm_spring>`
* examples/bpm
----------
.. _PKG-BROWNIAN:
BROWNIAN package
@ -529,8 +556,20 @@ To use this package, also the :ref:`KSPACE <PKG-KSPACE>` and
**Supporting info:**
* src/DIELECTRIC: filenames -> commands
* :doc:`atom_style dielectric <atom_style>`
* :doc:`pair_style coul/cut/dielectric <pair_dielectric>`
* :doc:`pair_style coul/long/dielectric <pair_dielectric>`
* :doc:`pair_style lj/cut/coul/cut/dielectric <pair_dielectric>`
* :doc:`pair_style lj/cut/coul/debye/dielectric <pair_dielectric>`
* :doc:`pair_style lj/cut/coul/long/dielectric <pair_dielectric>`
* :doc:`pair_style lj/cut/coul/msm/dielectric <pair_dielectric>`
* :doc:`pair_style pppm/dielectric <kspace_style>`
* :doc:`pair_style pppm/disp/dielectric <kspace_style>`
* :doc:`pair_style msm/dielectric <kspace_style>`
* :doc:`fix_style polarize/bem/icc <fix_polarize>`
* :doc:`fix_style polarize/bem/gmres <fix_polarize>`
* :doc:`fix_style polarize/functional <fix_polarize>`
* :doc:`compute efield/atom <compute_efield_atom>`
* TODO: add all styles
* examples/PACKAGES/dielectric
----------
@ -1396,17 +1435,25 @@ MDI package
**Contents:**
A LAMMPS command and fix to allow client-server coupling of LAMMPS to
other atomic or molecular simulation codes via the `MolSSI Driver Interface
A LAMMPS command and fixes to allow client-server coupling of LAMMPS
to other atomic or molecular simulation codes or materials modeling
workflows via the `MolSSI Driver Interface
(MDI) library <https://molssi-mdi.github.io/MDI_Library/html/index.html>`_.
**Author:** Taylor Barnes - MolSSI, taylor.a.barnes at gmail.com
**Install:**
This package has :ref:`specific installation instructions <mdi>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/MDI/README
* :doc:`mdi/engine <mdi_engine>`
* :doc:`fix mdi/engine <fix_mdi_engine>`
* lib/mdi/README
* :doc:`Howto MDI <Howto_mdi>`
* :doc:`mdi <mdi>`
* :doc:`fix mdi/aimd <fix_mdi_aimd>`
* examples/PACKAGES/mdi
----------
@ -1483,32 +1530,6 @@ Philipp Kloza (U Cambridge)
----------
.. _PKG-MESSAGE:
MESSAGE package
---------------
**Contents:**
Commands to use LAMMPS as either a client or server and couple it to
another application.
**Install:**
This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/MESSAGE: filenames -> commands
* lib/message/README
* :doc:`message <message>`
* :doc:`fix client/md <fix_client_md>`
* :doc:`server md <server_md>`
* :doc:`server mc <server_mc>`
* examples/message
----------
.. _PKG-MGPT:
MGPT package
@ -1564,7 +1585,6 @@ listing, "ls src/MISC", to see the list of commands.
* :doc:`pair_style list <pair_list>`
* :doc:`pair_style srp <pair_srp>`
* :doc:`pair_style tracker <pair_tracker>`
* :doc:`fix pair/tracker <fix_pair_tracker>`
----------
@ -1880,6 +1900,12 @@ MPIIO library. It adds :doc:`dump styles <dump>` with a "mpiio" in
their style name. Restart files with an ".mpiio" suffix are also
written and read in parallel.
.. warning::
The MPIIO package is currently unmaintained and has become
unreliable. Use with caution.
**Install:**
The MPIIO package requires that LAMMPS is build in :ref:`MPI parallel mode <serial>`.
@ -2148,6 +2174,11 @@ A :doc:`plugin <plugin>` command that can load and unload several
kind of styles in LAMMPS from shared object files at runtime without
having to recompile and relink LAMMPS.
When the environment variable ``LAMMPS_PLUGIN_PATH`` is set, then LAMMPS
will search the directory (or directories) listed in this path for files
with names that end in ``plugin.so`` (e.g. ``helloplugin.so``) and will
try to load the contained plugins automatically at start-up.
**Authors:** Axel Kohlmeyer (Temple U)
**Supporting info:**

12
doc/src/Packages_list.rst
View File

@ -58,6 +58,11 @@ whether an extra library is needed to build and use the package:
- :doc:`Howto body <Howto_body>`
- body
- no
* - :ref:`BPM <PKG-BPM>`
- bonded particle models
- :doc:`Howto bpm <Howto_bpm>`
- bpm
- no
* - :ref:`BROWNIAN <PKG-BROWNIAN>`
- Brownian dynamics, self-propelled particles
- :doc:`fix brownian <fix_brownian>`, :doc:`fix propel/self <fix_propel_self>`
@ -244,7 +249,7 @@ whether an extra library is needed to build and use the package:
- n/a
- no
* - :ref:`MDI <PKG-MDI>`
- client-server coupling
- client-server code coupling
- :doc:`MDI Howto <Howto_mdi>`
- PACKAGES/mdi
- ext
@ -258,11 +263,6 @@ whether an extra library is needed to build and use the package:
- pair styles :doc:`mesont/tpm <pair_mesont_tpm>`, :doc:`mesocnt <pair_mesocnt>`
- PACKAGES/mesont
- int
* - :ref:`MESSAGE <PKG-MESSAGE>`
- client/server messaging
- :doc:`message <message>`
- message
- int
* - :ref:`MGPT <PKG-MGPT>`
- fast MGPT multi-ion potentials
- :doc:`pair_style mgpt <pair_mgpt>`

118
doc/src/Python_install.rst
View File

@ -25,11 +25,10 @@ Installing the LAMMPS Python Module and Shared Library
======================================================
Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python package (``lammps``) into a location where the
Python interpreter can find it and installing the LAMMPS shared library
into a folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve
this.
LAMMPS Python package (``lammps``) into a location where the Python
interpreter can find it and installing the LAMMPS shared library into a
folder that the dynamic loader searches or inside of the installed
``lammps`` package folder. There are multiple ways to achieve this.
#. Do a full LAMMPS installation of libraries, executables, selected
headers, documentation (if enabled), and supporting files (only
@ -159,38 +158,52 @@ this.
make install-python
This will try to install (only) the shared library and the Python
package into a system folder and if that fails (due to missing
write permissions) will instead do the installation to a user
folder under ``$HOME/.local``. For a system-wide installation you
This will try to build a so-called (binary) 'wheel', a compressed
binary python package and then install it with the python package
manager 'pip'. Installation will be attempted into a system-wide
``site-packages`` folder and if that fails into the corresponding
folder in the user's home directory. For a system-wide installation you
would have to gain superuser privilege, e.g. though ``sudo``
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+==========================================================+=============================================================+
| LAMMPS Python package | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+----------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation those folders would then become.
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=========================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+---------------------------------------------------------+-------------------------------------------------------------+
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================+=============================================================+
| LAMMPS Python package | * ``/usr/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+-------------------------------------------------+-------------------------------------------------------------+
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
package.
.. versionchanged:: 24Mar2022
.. note::
If there is an existing installation of the LAMMPS python
module, ``make install-python`` will try to update it.
However, that will fail if the older version of the module
was installed by LAMMPS versions until 17Feb2022. Those
were using the distutils package, which does not create a
"manifest" that allows a clean uninstall. The ``make
install-python`` command will always produce a
lammps-<version>-<python>-<abi>-<os>-<arch>.whl file (the
'wheel'). And this file can be later installed directly with
``python -m pip install <wheel file>.whl`` without having to
type ``make install-python`` again and repeating the build
step, too.
For the traditional make process you can override the python
version to version x.y when calling ``make`` with
``PYTHON=pythonX.Y``. For a CMake based compilation this choice
@ -201,16 +214,12 @@ this.
.. code-block:: bash
$ python install.py -p <python package> -l <shared library> -v <version.h file> [-d <pydir>]
$ python install.py -p <python package> -l <shared library> [-n]
* 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 ``version.h`` file in the LAMMPS source
* and the optional ``-d`` flag to a custom (legacy) installation folder
If you use a legacy installation folder, you will need to set your
``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
variables accordingly as explained in the description for "In place use".
* and the optional ``-n`` instructs the script to only build a wheel file
but not attempt to install it.
.. tab:: Virtual environment
@ -257,32 +266,29 @@ this.
package and the shared library file are installed into the
following locations:
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+=================================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/lammps`` (64bit) | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------------+-------------------------------------------------------------+
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps`` | ``X.Y`` depends on the installed Python version |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | Set shared loader environment variable to this path |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | (see below for more info on this) |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+--------------------------------------------------------+-------------------------------------------------------------+
In that case you need to modify the ``$HOME/myenv/bin/activate``
script in a similar fashion you need to update your

9
doc/src/Run_options.rst
View File

@ -226,15 +226,6 @@ other executable(s) perform an MPI_Comm_split() with their own colors
to shrink the MPI_COMM_WORLD communication to be the subset of
processors they are actually running on.
Currently, this is only used in LAMMPS to perform client/server
messaging with another application. LAMMPS can act as either a client
or server (or both). More details are given on the :doc:`Howto client/server <Howto_client_server>` doc page.
Specifically, this refers to the "mpi/one" mode of messaging provided
by the :doc:`message <message>` command and the CSlib library LAMMPS
links with from the lib/message directory. See the
:doc:`message <message>` command for more details.
----------
.. _cite:

4
doc/src/Run_output.rst
View File

@ -106,7 +106,7 @@ individual ranks. Here is an example output for this section:
----------
The third section above lists the number of owned atoms (Nlocal),
ghost atoms (Nghost), and pair-wise neighbors stored per processor.
ghost atoms (Nghost), and pairwise neighbors stored per processor.
The max and min values give the spread of these values across
processors with a 10-bin histogram showing the distribution. The total
number of histogram counts is equal to the number of processors.
@ -114,7 +114,7 @@ number of histogram counts is equal to the number of processors.
----------
The last section gives aggregate statistics (across all processors)
for pair-wise neighbors and special neighbors that LAMMPS keeps track
for pairwise neighbors and special neighbors that LAMMPS keeps track
of (see the :doc:`special_bonds <special_bonds>` command). The number
of times neighbor lists were rebuilt is tallied, as is the number of
potentially *dangerous* rebuilds. If atom movement triggered neighbor

2
doc/src/Speed_kokkos.rst
View File

@ -214,7 +214,7 @@ threads/task as Nt. The product of these two values should be N, i.e.
The default for the :doc:`package kokkos <package>` command when
running on KNL is to use "half" neighbor lists and set the Newton flag
to "on" for both pairwise and bonded interactions. This will typically
be best for many-body potentials. For simpler pair-wise potentials, it
be best for many-body potentials. For simpler pairwise potentials, it
may be faster to use a "full" neighbor list with Newton flag to "off".
Use the "-pk kokkos" :doc:`command-line switch <Run_options>` to change
the default :doc:`package kokkos <package>` options. See its page for

64
doc/src/Tools.rst
View File

@ -87,7 +87,7 @@ Miscellaneous tools
.. table_from_list::
:columns: 6
* :ref:`CMake <cmake>`
* :ref:`LAMMPS coding standards <coding_standard>`
* :ref:`emacs <emacs>`
* :ref:`i-pi <ipi>`
* :ref:`kate <kate>`
@ -189,27 +189,32 @@ for the :doc:`chain benchmark <Speed_bench>`.
----------
.. _cmake:
.. _coding_standard:
CMake tools
-----------
LAMMPS coding standard
----------------------
The ``cmbuild`` script is a wrapper around using ``cmake --build <dir>
--target`` and allows compiling LAMMPS in a :ref:`CMake build folder
<cmake_build>` with a make-like syntax regardless of the actual build
tool and the specific name of the program used (e.g. ``ninja-v1.10`` or
``gmake``) when using ``-D CMAKE_MAKE_PROGRAM=<name>``.
The ``coding_standard`` folder contains multiple python scripts to
check for and apply some LAMMPS coding conventions. The following
scripts are available:
.. parsed-literal::
Usage: cmbuild [-v] [-h] [-C <dir>] [-j <num>] [<target>]
permissions.py # detects if sources have executable permissions and scripts have not
whitespace.py # detects TAB characters and trailing whitespace
homepage.py # detects outdated LAMMPS homepage URLs (pointing to sandia.gov instead of lammps.org)
errordocs.py # detects deprecated error docs in header files
Options:
-h print this message
-j <NUM> allow processing of NUM concurrent tasks
-C DIRECTORY execute build in folder DIRECTORY
-v produce verbose output
The tools need to be given the main folder of the LAMMPS distribution
or individual file names as argument and will by default check them
and report any non-compliance. With the optional ``-f`` argument the
corresponding script will try to change the non-compliant file(s) to
match the conventions.
For convenience this scripts can also be invoked by the make file in
the ``src`` folder with, `make check-whitespace` or `make fix-whitespace`
to either detect or edit the files. Correspondingly for the other python
scripts. `make check` will run all checks.
----------
@ -277,17 +282,34 @@ at ens-lyon.fr, alain.dequidt at uca.fr
eam database tool
-----------------------------
The tools/eam_database directory contains a Fortran program that will
generate EAM alloy setfl potential files for any combination of 16
elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg, Co, Ti,
Zr. The files can then be used with the :doc:`pair_style eam/alloy <pair_eam>` command.
The tools/eam_database directory contains a Fortran and a Python program
that will generate EAM alloy setfl potential files for any combination
of the 17 elements: Cu, Ag, Au, Ni, Pd, Pt, Al, Pb, Fe, Mo, Ta, W, Mg,
Co, Ti, Zr, Cr. The files can then be used with the :doc:`pair_style
eam/alloy <pair_eam>` command.
The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov,
and is based on his paper:
The Fortran version of the tool was authored by Xiaowang Zhou (Sandia),
xzhou at sandia.gov, with updates from Lucas Hale (NIST) lucas.hale at
nist.gov and is based on his paper:
X. W. Zhou, R. A. Johnson, and H. N. G. Wadley, Phys. Rev. B, 69,
144113 (2004).
The parameters for Cr were taken from:
Lin Z B, Johnson R A and Zhigilei L V, Phys. Rev. B 77 214108 (2008).
The Python version of the tool was authored by Germain Clavier
(TU Eindhoven) g.m.g.c.clavier at tue.nl or germain.clavier at gmail.com
.. note::
The parameters in the database are only optimized for individual
elements. The mixed parameters for interactions between different
elements generated by this tool are derived from simple mixing rules
and are thus inferior to parameterizations that are specifically
optimized for specific mixtures and combinations of elements.
----------
.. _eamgn:

38
doc/src/angle_class2.rst
View File

@ -64,34 +64,44 @@ These are the 4 coefficients for the :math:`E_a` formula:
radians internally; hence the various :math:`K` are effectively energy
per radian\^2 or radian\^3 or radian\^4.
For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 4 coefficients, the first of which
is "bb" to indicate they are BondBond coefficients. In a data file,
these coefficients should be listed under a "BondBond Coeffs" heading
and you must leave out the "bb", i.e. only list 3 coefficients after
the angle type.
For the :math:`E_{bb}` formula, each line in a :doc:`angle_coeff
<angle_coeff>` command in the input script lists 4 coefficients, the
first of which is "bb" to indicate they are BondBond coefficients. In
a data file, these coefficients should be listed under a "BondBond
Coeffs" heading and you must leave out the "bb", i.e. only list 3
coefficients after the angle type.
* bb
* :math:`M` (energy/distance\^2)
* :math:`r_1` (distance)
* :math:`r_2` (distance)
For the :math:`E_{ba}` formula, each line in a :doc:`angle_coeff <angle_coeff>`
command in the input script lists 5 coefficients, the first of which
is "ba" to indicate they are BondAngle coefficients. In a data file,
these coefficients should be listed under a "BondAngle Coeffs" heading
and you must leave out the "ba", i.e. only list 4 coefficients after
the angle type.
For the :math:`E_{ba}` formula, each line in a :doc:`angle_coeff
<angle_coeff>` command in the input script lists 5 coefficients, the
first of which is "ba" to indicate they are BondAngle coefficients.
In a data file, these coefficients should be listed under a "BondAngle
Coeffs" heading and you must leave out the "ba", i.e. only list 4
coefficients after the angle type.
* ba
* :math:`N_1` (energy/distance\^2)
* :math:`N_2` (energy/distance\^2)
* :math:`N_1` (energy/distance)
* :math:`N_2` (energy/distance)
* :math:`r_1` (distance)
* :math:`r_2` (distance)
The :math:`\theta_0` value in the :math:`E_{ba}` formula is not specified,
since it is the same value from the :math:`E_a` formula.
.. note::
It is important that the order of the I,J,K atoms in each angle
listed in the Angles section of the data file read by the
:doc:`read_data <read_data>` command be consistent with the order
of the :math:`r_1` and :math:`r_2` BondBond and BondAngle
coefficients. This is because the terms in the formulas for
:math:`E_{bb}` and :math:`E_{ba}` will use the I,J atoms to compute
:math:`r_{ij}` and the J,K atoms to compute :math:`r_{jk}`.
----------
.. include:: accel_styles.rst

18
doc/src/atom_style.rst
View File

@ -10,7 +10,7 @@ Syntax
atom_style style args
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *oxdna* or *peri* or *smd* or *sph* or *sphere* or *spin* or *tdpd* or *tri* or *template* or *hybrid*
* style = *angle* or *atomic* or *body* or *bond* or *charge* or *dipole* or *dpd* or *edpd* or *electron* or *ellipsoid* or *full* or *line* or *mdpd* or *molecular* or *oxdna* or *peri* or *smd* or *sph* or *sphere* or *bpm/sphere* or *spin* or *tdpd* or *tri* or *template* or *hybrid*
.. parsed-literal::
@ -21,6 +21,7 @@ Syntax
see the :doc:`Howto body <Howto_body>` doc
page for details
*sphere* arg = 0/1 (optional) for static/dynamic particle radii
*bpm/sphere* arg = 0/1 (optional) for static/dynamic particle radii
*tdpd* arg = Nspecies
Nspecies = # of chemical species
*template* arg = template-ID
@ -120,6 +121,8 @@ quantities.
+--------------+-----------------------------------------------------+--------------------------------------+
| *sphere* | diameter, mass, angular velocity | granular models |
+--------------+-----------------------------------------------------+--------------------------------------+
| *bpm/sphere* | diameter, mass, angular velocity, quaternion | granular bonded particle models (BPM)|
+--------------+-----------------------------------------------------+--------------------------------------+
| *spin* | magnetic moment | system with magnetic particles |
+--------------+-----------------------------------------------------+--------------------------------------+
| *tdpd* | chemical concentration | tDPD particles |
@ -141,8 +144,9 @@ quantities.
output the custom values.
All of the above styles define point particles, except the *sphere*,
*ellipsoid*, *electron*, *peri*, *wavepacket*, *line*, *tri*, and
*body* styles, which define finite-size particles. See the :doc:`Howto spherical <Howto_spherical>` page for an overview of using
*bpm/sphere*, *ellipsoid*, *electron*, *peri*, *wavepacket*, *line*,
*tri*, and *body* styles, which define finite-size particles. See the
:doc:`Howto spherical <Howto_spherical>` page for an overview of using
finite-size particle models with LAMMPS.
All of the point-particle styles assign mass to particles on a
@ -150,15 +154,15 @@ per-type basis, using the :doc:`mass <mass>` command, The finite-size
particle styles assign mass to individual particles on a per-particle
basis.
For the *sphere* style, the particles are spheres and each stores a
For the *sphere* and *bpm/sphere* styles, the particles are spheres and each stores a
per-particle diameter and mass. If the diameter > 0.0, the particle
is a finite-size sphere. If the diameter = 0.0, it is a point
particle. Note that by use of the *disc* keyword with the :doc:`fix
nve/sphere <fix_nve_sphere>`, :doc:`fix nvt/sphere <fix_nvt_sphere>`,
:doc:`fix nph/sphere <fix_nph_sphere>`, :doc:`fix npt/sphere
<fix_npt_sphere>` commands, spheres can be effectively treated as 2d
<fix_npt_sphere>` commands for the *sphere* style, spheres can be effectively treated as 2d
discs for a 2d simulation if desired. See also the :doc:`set
density/disc <set>` command. The *sphere* style takes an optional 0
density/disc <set>` command. The *sphere* and *bpm/sphere* styles take an optional 0
or 1 argument. A value of 0 means the radius of each sphere is
constant for the duration of the simulation. A value of 1 means the
radii may vary dynamically during the simulation, e.g. due to use of
@ -195,6 +199,8 @@ position, which is represented by the eradius = electron size.
For the *peri* style, the particles are spherical and each stores a
per-particle mass and volume.
The *bpm/sphere* style is part of the BPM package.
The *oxdna* style is for coarse-grained nucleotides and stores the
3'-to-5' polarity of the nucleotide strand, which is set through
the bond topology in the data file. The first (second) atom in a

2
doc/src/balance.rst
View File

@ -383,7 +383,7 @@ multiple groups, its weight is the product of the weight factors.
This weight style is useful in combination with pair style
:doc:`hybrid <pair_hybrid>`, e.g. when combining a more costly many-body
potential with a fast pair-wise potential. It is also useful when
potential with a fast pairwise potential. It is also useful when
using :doc:`run_style respa <run_style>` where some portions of the
system have many bonded interactions and others none. It assumes that
the computational cost for each group remains constant over time.

258
doc/src/bond_bpm_rotational.rst Normal file
View File

@ -0,0 +1,258 @@
.. index:: bond_style bpm/rotational
bond_style bpm/rotational command
=================================
Syntax
""""""
.. code-block:: LAMMPS
bond_style bpm/rotational keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth*
.. 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 2 atoms in the bond
*time* = the timestep the bond broke
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
*overlay/pair* value = none
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
Examples
""""""""
.. code-block:: LAMMPS
bond_style bpm/rotational
bond_coeff 1 1.0 0.2 0.02 0.02 0.20 0.04 0.04 0.04 0.1 0.02 0.002 0.002
bond_style bpm/rotational myfix 1000 time id1 id2
fix myfix all store/local 1000 3
dump 1 all local 1000 dump.broken f_myfix[1] f_myfix[2] f_myfix[3]
dump_modify 1 write_header no
Description
"""""""""""
The *bpm/rotational* bond style computes forces and torques based on
deviations from the initial reference state of the two atoms. The
reference state is stored by each bond when it is first computed in
the setup of a run. Data is then preserved across run commands and is
written to :doc:`binary restart files <restart>` such that restarting
the system will not reset the reference state of a bond.
Forces include a normal and tangential component. The base normal force
has a magnitude of
.. math::
f_r = k_r (r - r_0)
where :math:`k_r` is a stiffness and :math:`r` is the current distance and
:math:`r_0` is the initial distance between the two particles.
A tangential force is applied perpendicular to the normal direction
which is proportional to the tangential shear displacement with a
stiffness of :math:`k_s`. This tangential force also induces a torque.
In addition, bending and twisting torques are also applied to
particles which are proportional to angular bending and twisting
displacements with stiffnesses of :math`k_b` and :math:`k_t',
respectively. Details on the calculations of shear displacements and
angular displacements can be found in :ref:`(Wang) <Wang2009>` and
:ref:`(Wang and Mora) <Wang2009b>`.
Bonds will break under sufficient stress. A breaking criteria is calculated
.. math::
B = \mathrm{max}\{0, \frac{f_r}{f_{r,c}} + \frac{|f_s|}{f_{s,c}} +
\frac{|\tau_b|}{\tau_{b,c}} + \frac{|\tau_t|}{\tau_{t,c}} \}
where :math:`|f_s|` is the magnitude of the shear force and
:math:`|\tau_b|` and :math:`|\tau_t|` are the magnitudes of the
bending and twisting forces, respectively. The corresponding variables
:math:`f_{r,c}` :math:`f_{s,c}`, :math:`\tau_{b,c}`, and
:math:`\tau_{t,c}` are critical limits to each force or torque. If
:math:`B` is ever equal to or exceeds one, the bond will break. This
is done by setting by setting its type to 0 such that forces and
torques are no longer computed.
After computing the base magnitudes of the forces and torques, they
can be optionally multiplied by an extra factor :math:`w` to smoothly
interpolate forces and torques to zero as the bond breaks. This term
is calculated as :math:`w = (1.0 - B^4)`. This smoothing factor can be
added or removed using the *smooth* keyword.
Finally, additional damping forces and torques are applied to the two
particles. A force is applied proportional to the difference in the
normal velocity of particles using a similar construction as
dissipative particle dynamics (:ref:`(Groot) <Groot3>`):
.. math::
F_D = - \gamma_n w (\hat{r} \bullet \vec{v})
where :math:`\gamma_n` is the damping strength, :math:`\hat{r}` is the
radial normal vector, and :math:`\vec{v}` is the velocity difference
between the two particles. Similarly, tangential forces are applied to
each atom proportional to the relative differences in sliding
velocities with a constant prefactor :math:`\gamma_s` (:ref:`(Wang et
al.) <Wang20152>`) along with their associated torques. The rolling and
twisting components of the relative angular velocities of the two
atoms are also damped by applying torques with prefactors of
:math:`\gamma_r` and :math:`\gamma_t`, respectively.
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_r` (force/distance units)
* :math:`k_s` (force/distance units)
* :math:`k_t` (force*distance/radians units)
* :math:`k_b` (force*distance/radians units)
* :math:`f_{r,c}` (force units)
* :math:`f_{s,c}` (force units)
* :math:`\tau_{b,c}` (force*distance units)
* :math:`\tau_{t,c}` (force*distance units)
* :math:`\gamma_n` (force/velocity units)
* :math:`\gamma_s` (force/velocity units)
* :math:`\gamma_r` (force*distance/velocity units)
* :math:`\gamma_t` (force*distance/velocity units)
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
the *overlay/pair* keyword. These settings require specific
:doc:`special_bonds <special_bonds>` settings described in the
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
If the *store/local* keyword is used, this fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
local data to be accessed by other LAMMPS commands.
Following any optional keyword/value arguments, a list of one or more
attributes is specified. These include the IDs of the two atoms in
the bond. The other attributes for the two atoms include the timestep
during which the bond broke and the current/initial center of mass
position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
data is deleted to make room for new data. Individual datum may
therefore persist anywhere between *1* to *N* timesteps depending on
when they are saved. This data can be accessed using the *fix_ID* and a
:doc:`dump local <dump>` command. To ensure all data is output,
the dump frequency should correspond to the same interval of *N*
timesteps. A dump frequency of an integer multiple of *N* can be used
to regularly output a sample of the accumulated data.
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 of each bond to
:doc:`binary restart files <restart>`. Loading a restart file will
properly resume bonds.
The single() function of these pair styles returns 0.0 for the energy
of a pairwise interaction, since energy is not conserved in these
dissipative potentials. It also returns only the normal component of
the pairwise interaction force.
The accumulated data is not written to restart files and should be
output before a restart file is written to avoid missing data.
The internal fix calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of recorded, lost interactions. If a single
input is specified, a local vector is produced. If two or more inputs
are specified, a local array is produced where the number of columns =
the number of inputs. The vector or array can be accessed by any
command that uses local values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS
output options.
The vector or array will be floating point values that correspond to
the specified attribute.
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the BPM
package. See the :doc:`Build package <Build_package>` doc page for
more info.
By default if pair interactions 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* option is used, this bond style alternatively requires
setting
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
The *bpm/rotational* style requires :doc:`atom style bpm/sphere <atom_style>`.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`fix nve/bpm/sphere <fix_nve_bpm_sphere>`
Default
"""""""
The option defaults are *smooth* = *yes*
----------
.. _Wang2009:
**(Wang)** Wang, Acta Geotechnica, 4,
p 117-127 (2009).
.. _Wang2009b:
**(Wang and Mora)** Wang, Mora, Advances in Geocomputing,
119, p 183-228 (2009).
.. _Groot3:
**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).
.. _Wang20152:
**(Wang et al, 2015)** Wang, Y., Alonso-Marroquin, F., & Guo,
W. W. (2015). Rolling and sliding in 3-D discrete element
models. Particuology, 23, 49-55.

202
doc/src/bond_bpm_spring.rst Normal file
View File

@ -0,0 +1,202 @@
.. index:: bond_style bpm/spring
bond_style bpm/spring command
=============================
Syntax
""""""
.. code-block:: LAMMPS
bond_style bpm/spring keyword value attribute1 attribute2 ...
* optional keyword = *overlay/pair* or *store/local* or *smooth*
.. 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 2 atoms in the bond
*time* = the timestep the bond broke
*x, y, z* = the center of mass position of the 2 atoms when the bond broke (distance units)
*x/ref, y/ref, z/ref* = the initial center of mass position of the 2 atoms (distance units)
*overlay/pair* value = none
bonded particles will still interact with pair forces
*smooth* value = *yes* or *no*
smooths bond forces near the breaking point
Examples
""""""""
.. code-block:: LAMMPS
bond_style bpm/spring
bond_coeff 1 1.0 0.05 0.1
bond_style bpm/spring 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
"""""""""""
The *bpm/spring* bond style computes forces and torques based on
deviations from the initial reference state of the two atoms. The
reference state is stored by each bond when it is first computed in
the setup of a run. Data is then preserved across run commands and is
written to :doc:`binary restart files <restart>` such that restarting
the system will not reset the reference state of a bond.
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 - r_0) w
where :math:`k_r` is a stiffness, :math:`r` is the current distance
and :math:`r_0` is the initial distance between the two particles, and
:math:`w` is an optional smoothing factor discussed below. Bonds will
break at a strain of :math:`\epsilon_c`. This is done by setting by
setting its 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 using a similar construction as
dissipative particle dynamics (:ref:`(Groot) <Groot4>`):
.. 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` can be added or removed using the
*smooth* keyword. It is constructed such that forces smoothly go
to zero, avoiding discontinuities, as bonds approach the critical 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` (unit less)
* :math:`\gamma` (force/velocity units)
By default, pair forces are not calculated between bonded particles.
Pair forces can alternatively be overlaid on top of bond forces using
the *overlay/pair* keyword. These settings require specific
:doc:`special_bonds <special_bonds>` settings described in the
restrictions. Further details can be found in the `:doc: how to
<Howto_BPM>` page on BPMs.
If the *store/local* keyword is used, this fix will track bonds that
break during the simulation. Whenever a bond breaks, data is processed
and transferred to an internal fix labeled *fix_ID*. This allows the
local data to be accessed by other LAMMPS commands.
Following any optional keyword/value arguments, a list of one or more
attributes is specified. These include the IDs of the two atoms in
the bond. The other attributes for the two atoms include the timestep
during which the bond broke and the current/initial center of mass
position of the two atoms.
Data is continuously accumulated over intervals of *N*
timesteps. At the end of each interval, all of the saved accumulated
data is deleted to make room for new data. Individual datum may
therefore persist anywhere between *1* to *N* timesteps depending on
when they are saved. This data can be accessed using the *fix_ID* and a
:doc:`dump local <dump>` command. To ensure all data is output,
the dump frequency should correspond to the same interval of *N*
timesteps. A dump frequency of an integer multiple of *N* can be used
to regularly output a sample of the accumulated data.
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 of each bond to
:doc:`binary restart files <restart>`. Loading a restart
file will properly resume bonds.
The single() function of these pair styles returns 0.0 for the energy
of a pairwise interaction, since energy is not conserved in these
dissipative potentials.
The accumulated data is not written to restart files and should be
output before a restart file is written to avoid missing data.
The internal fix calculates a local vector or local array depending on the
number of input values. The length of the vector or number of rows in
the array is the number of recorded, lost interactions. If a single
input is specified, a local vector is produced. If two or more inputs
are specified, a local array is produced where the number of columns =
the number of inputs. The vector or array can be accessed by any
command that uses local values from a compute as input. See the
:doc:`Howto output <Howto_output>` page for an overview of LAMMPS
output options.
The vector or array will be floating point values that correspond to
the specified attribute.
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the BPM
package. See the :doc:`Build package <Build_package>` doc page for
more info.
By default if pair interactions 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* option is used, this bond style alternatively requires
setting
.. code-block:: LAMMPS
special_bonds lj/coul 1 1 1
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`pair bpm/spring <pair_bpm_spring>`
Default
"""""""
The option defaults are *smooth* = *yes*
----------
.. _Groot4:
**(Groot)** Groot and Warren, J Chem Phys, 107, 4423-35 (1997).

46
doc/src/bond_fene.rst
View File

@ -1,4 +1,5 @@
.. index:: bond_style fene
.. index:: bond_style fene/nm
.. index:: bond_style fene/intel
.. index:: bond_style fene/kk
.. index:: bond_style fene/omp
@ -8,12 +9,16 @@ bond_style fene command
Accelerator Variants: *fene/intel*, *fene/kk*, *fene/omp*
bond_style fene/nm command
==========================
Syntax
""""""
.. code-block:: LAMMPS
bond_style fene
bond_style fene/nm
Examples
""""""""
@ -23,6 +28,9 @@ Examples
bond_style fene
bond_coeff 1 30.0 1.5 1.0 1.0
bond_style fene/nm
bond_coeff 1 2.25344 1.5 1.0 1.12246 2 6
Description
"""""""""""
@ -38,16 +46,36 @@ term is attractive, the second Lennard-Jones term is repulsive. The
first term extends to :math:`R_0`, the maximum extent of the bond. The second
term is cutoff at :math:`2^\frac{1}{6} \sigma`, the minimum of the LJ potential.
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:
The *fene/nm* bond style substitutes the standard LJ potential with the generalized LJ potential
in the same form as in pair style :doc:`nm/cut <pair_nm>`. The bond energy is then given by
.. math::
E = -0.5 K r_0^2 \ln \left[ 1 - \left(\frac{r}{R_0}\right)^2\right] + \frac{E_0}{(n-m)} \left[ m \left(\frac{r_0}{r}\right)^n - n \left(\frac{r_0}{r}\right)^m \right]
Similar to the *fene* style, the generalized Lennard-Jones is cut off at
the potential minimum, :math:`r_0`, to be repulsive only. 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` (energy/distance\^2)
* :math:`R_0` (distance)
* :math:`\epsilon` (energy)
* :math:`\sigma` (distance)
For the *fene/nm* style, the following coefficients are used. Please
note, that the standard LJ potential and thus the regular FENE potential
is recovered for (n=12 m=6) and :math:`r_0 = 2^\frac{1}{6} \sigma`.
* :math:`K` (energy/distance\^2)
* :math:`R_0` (distance)
* :math:`E_0` (energy)
* :math:`r_0` (distance)
* :math:`n` (unitless)
* :math:`m` (unitless)
----------
.. include:: accel_styles.rst
@ -57,9 +85,10 @@ or :doc:`read_restart <read_restart>` commands:
Restrictions
""""""""""""
This bond style can only be used if LAMMPS was built with the MOLECULE
package. See the :doc:`Build package <Build_package>` page for more
info.
The *fene* bond style can only be used if LAMMPS was built with the MOLECULE
package; the *fene/nm* bond style can only be used if LAMMPS was built
with the EXTRA-MOLECULE package. See the :doc:`Build package <Build_package>`
page for more info.
You typically should specify :doc:`special_bonds fene <special_bonds>`
or :doc:`special_bonds lj/coul 0 1 1 <special_bonds>` to use this bond
@ -68,7 +97,8 @@ style. LAMMPS will issue a warning it that's not the case.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`
:doc:`bond_coeff <bond_coeff>`, :doc:`delete_bonds <delete_bonds>`,
:doc:`pair style lj/cut <pair_lj>`, :doc:`pair style nm/cut <pair_nm>`.
Default
"""""""

3
doc/src/bond_quartic.rst
View File

@ -67,7 +67,8 @@ local maximum. If a bond length ever becomes :math:`> R_c`, LAMMPS "breaks"
the bond, which means two things. First, the bond potential is turned
off by setting its type to 0, and is no longer computed. Second, a
pairwise interaction between the two atoms is turned on, since they
are no longer bonded.
are no longer bonded. See the :doc:`Howto <Howto_broken_bonds>` page
on broken bonds for more information.
LAMMPS does the second task via a computational sleight-of-hand. It
subtracts the pairwise interaction as part of the bond computation.

3
doc/src/bond_style.rst
View File

@ -84,9 +84,12 @@ accelerated styles exist.
* :doc:`zero <bond_zero>` - topology but no interactions
* :doc:`hybrid <bond_hybrid>` - define multiple styles of bond interactions
* :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:`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
* :doc:`fene/nm <bond_fene>` - FENE bonds with a generalized Lennard-Jones potential
* :doc:`gaussian <bond_gaussian>` - multicentered Gaussian-based bond potential
* :doc:`gromos <bond_gromos>` - GROMOS force field bond
* :doc:`harmonic <bond_harmonic>` - harmonic bond

6
doc/src/commands_list.rst
View File

@ -59,8 +59,7 @@ Commands
lattice
log
mass
mdi_engine
message
mdi
min_modify
min_spin
min_style
@ -96,9 +95,6 @@ Commands
restart
run
run_style
server
server_mc
server_md
set
shell
special_bonds

10
doc/src/compute.rst
View File

@ -174,10 +174,12 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`angle <compute_angle>` - energy of each angle sub-style
* :doc:`angle/local <compute_angle_local>` - theta and energy of each angle
* :doc:`angmom/chunk <compute_angmom_chunk>` - angular momentum for each chunk
* :doc:`ave/sphere/atom <compute_ave_sphere_atom>` - compute local density and temperature around each atom
* :doc:`basal/atom <compute_basal_atom>` - calculates the hexagonal close-packed "c" lattice vector of each atom
* :doc:`body/local <compute_body_local>` - attributes of body sub-particles
* :doc:`bond <compute_bond>` - energy of each bond sub-style
* :doc:`bond/local <compute_bond_local>` - distance and energy of each bond
* :doc:`born/matrix <compute_born_matrix>` - second derivative or potential with respect to strain
* :doc:`centro/atom <compute_centro_atom>` - centro-symmetry parameter for each atom
* :doc:`centroid/stress/atom <compute_stress_atom>` - centroid based stress tensor for each atom
* :doc:`chunk/atom <compute_chunk_atom>` - assign chunk IDs to each atom
@ -207,7 +209,8 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>` - rotational energy for each spherical particle
* :doc:`event/displace <compute_event_displace>` - detect event on atom displacement
* :doc:`fabric <compute_fabric>` - calculates fabric tensors from pair interactions
* :doc:`fep <compute_fep>` -
* :doc:`fep <compute_fep>` - compute free energies for alchemical transformation from perturbation theory
* :doc:`fep/ta <compute_fep_ta>` - compute free energies for a test area perturbation
* :doc:`force/tally <compute_tally>` - force between two groups of atoms via the tally callback mechanism
* :doc:`fragment/atom <compute_cluster_atom>` - fragment ID for each atom
* :doc:`global/atom <compute_global_atom>` -
@ -234,6 +237,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`msd <compute_msd>` - mean-squared displacement of group of atoms
* :doc:`msd/chunk <compute_msd_chunk>` - mean-squared displacement for each chunk
* :doc:`msd/nongauss <compute_msd_nongauss>` - MSD and non-Gaussian parameter of group of atoms
* :doc:`nbond/atom <compute_nbond_atom>` - calculates number of bonds per atom
* :doc:`omega/chunk <compute_omega_chunk>` - angular velocity for each chunk
* :doc:`orientorder/atom <compute_orientorder_atom>` - Steinhardt bond orientational order parameters Ql
* :doc:`pair <compute_pair>` - values computed by a pair style
@ -245,7 +249,6 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`pe/tally <compute_tally>` - potential energy between two groups of atoms via the tally callback mechanism
* :doc:`plasticity/atom <compute_plasticity_atom>` - Peridynamic plasticity for each atom
* :doc:`pressure <compute_pressure>` - total pressure and pressure tensor
* :doc:`pressure/cylinder <compute_pressure_cylinder>` - pressure tensor in cylindrical coordinates
* :doc:`pressure/uef <compute_pressure_uef>` - pressure tensor in the reference frame of an applied flow field
* :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
* :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes
@ -288,8 +291,11 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`sph/t/atom <compute_sph_t_atom>` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`spin <compute_spin>` - magnetic quantities for a system of atoms having spins
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`stress/cartesian <compute_stress_profile>` - stress tensor in cartesian coordinates
* :doc:`stress/cylinder <compute_stress_profile>` - stress tensor in cylindrical coordinates
* :doc:`stress/mop <compute_stress_mop>` - normal components of the local stress tensor using the method of planes
* :doc:`stress/mop/profile <compute_stress_mop>` - profile of the normal components of the local stress tensor using the method of planes
* :doc:`stress/spherical <compute_stress_profile>` - stress tensor in spherical coordinates
* :doc:`stress/tally <compute_tally>` - stress between two groups of atoms via the tally callback mechanism
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>` - per-atom chemical concentration of a specified species for each tDPD particle
* :doc:`temp <compute_temp>` - temperature of group of atoms

101
doc/src/compute_ave_sphere_atom.rst Normal file
View File

@ -0,0 +1,101 @@
.. index:: compute ave/sphere/atom
.. index:: compute ave/sphere/atom/kk
compute ave/sphere/atom command
================================
Accelerator Variants: *ave/sphere/atom/kk*
Syntax
""""""
.. parsed-literal::
compute ID group-ID ave/sphere/atom keyword values ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* ave/sphere/atom = style name of this compute command
* one or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *cutoff*
*cutoff* value = distance cutoff
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all ave/sphere/atom
compute 1 all ave/sphere/atom cutoff 5.0
comm_modify cutoff 5.0
Description
"""""""""""
Define a computation that calculates the local density and temperature
for each atom and neighbors inside a spherical cutoff.
The optional keyword *cutoff* defines the distance cutoff
used when searching for neighbors. The default value is the cutoff
specified by the pair style. If no pair style is defined, then a cutoff
must be defined using this keyword. If the specified cutoff is larger than
that of the pair_style plus neighbor skin (or no pair style is defined),
the *comm_modify cutoff* option must also be set to match that of the
*cutoff* keyword.
The neighbor list needed to compute this quantity is constructed each
time the calculation is performed (i.e. each time a snapshot of atoms
is dumped). Thus it can be inefficient to compute/dump this quantity
too frequently.
.. note::
If you have a bonded system, then the settings of
:doc:`special_bonds <special_bonds>` command can remove pairwise
interactions between atoms in the same bond, angle, or dihedral. This
is the default setting for the :doc:`special_bonds <special_bonds>`
command, and means those pairwise interactions do not appear in the
neighbor list. Because this fix uses the neighbor list, it also means
those pairs will not be included in the order parameter. This
difficulty can be circumvented by writing a dump file, and using the
:doc:`rerun <rerun>` command to compute the order parameter for
snapshots in the dump file. The rerun script can use a
:doc:`special_bonds <special_bonds>` command that includes all pairs in
the neighbor list.
----------
.. include:: accel_styles.rst
----------
Output info
"""""""""""
This compute calculates a per-atom array with two columns: density and temperature.
These values can be accessed by any command that uses per-atom values
from a compute as input. See the :doc:`Howto output <Howto_output>` doc
page for an overview of LAMMPS output options.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`comm_modify <comm_modify>`
Default
"""""""
The option defaults are *cutoff* = pair style cutoff

6
doc/src/compute_bond_local.rst
View File

@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`compute <compute>` command
* bond/local = style name of this compute command
* one or more values may be appended
* value = *dist* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
* value = *dist* or *dx* or *dy* or *dz* or *engpot* or *force* or *fx* or *fy* or *fz* or *engvib* or *engrot* or *engtrans* or *omega* or *velvib* or *v_name*
.. parsed-literal::
@ -21,6 +21,7 @@ Syntax
*engpot* = bond potential energy
*force* = bond force
*dx*,\ *dy*,\ *dz* = components of pairwise distance
*fx*,\ *fy*,\ *fz* = components of bond force
*engvib* = bond kinetic energy of vibration
*engrot* = bond kinetic energy of rotation
@ -63,6 +64,9 @@ whether the 2 atoms represent a simple diatomic molecule, or are part
of some larger molecule.
The value *dist* is the current length of the bond.
The values *dx*, *dy*, and *dz* are the xyz components of the
*distance* between the pair of atoms. This value is always the
distance from the atom of lower to the one with the higher id.
The value *engpot* is the potential energy for the bond,
based on the current separation of the pair of atoms in the bond.

213
doc/src/compute_born_matrix.rst Normal file
View File

@ -0,0 +1,213 @@
.. index:: compute born/matrix
compute born/matrix command
===========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID born/matrix keyword value ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* born/matrix = style name of this compute command
* zero or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *numdiff*
*numdiff* values = delta virial-ID
delta = magnitude of strain (dimensionless)
virial-ID = ID of pressure compute for virial (string)
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all born/matrix
compute 1 all born/matrix bond angle
compute 1 all born/matrix numdiff 1.0e-4 myvirial
Description
"""""""""""
Define a compute that calculates
:math:`\frac{\partial{}^2U}{\partial\varepsilon_{i}\partial\varepsilon_{j}}` the
second derivatives of the potential energy :math:`U` w.r.t. strain
tensor :math:`\varepsilon` elements. These values are related to:
.. math::
C^{B}_{i,j}=\frac{1}{V}\frac{\partial{}^2U}{\partial{}\varepsilon_{i}\partial\varepsilon_{j}}
also called the Born term of elastic constants in the stress-stress fluctuation
formalism. This quantity can be used to compute the elastic constant tensor.
Using the symmetric Voigt notation, the elastic constant tensor can be written
as a 6x6 symmetric matrix:
.. math::
C_{i,j} = \langle{}C^{B}_{i,j}\rangle
+ \frac{V}{k_{B}T}\left(\langle\sigma_{i}\sigma_{j}\rangle\right.
\left.- \langle\sigma_{i}\rangle\langle\sigma_{j}\rangle\right)
+ \frac{Nk_{B}T}{V}
\left(\delta_{i,j}+(\delta_{1,i}+\delta_{2,i}+\delta_{3,i})\right.
\left.*(\delta_{1,j}+\delta_{2,j}+\delta_{3,j})\right)
In the above expression, :math:`\sigma` stands for the virial stress
tensor, :math:`\delta` is the Kronecker delta and the usual notation apply for
the number of particle, the temperature and volume respectively :math:`N`,
:math:`T` and :math:`V`. :math:`k_{B}` is the Boltzmann constant.
The Born term is a symmetric 6x6 matrix, as is the matrix of second derivatives
of potential energy w.r.t strain,
whose 21 independent elements are output in this order:
.. math::
\begin{matrix}
C_{1} & C_{7} & C_{8} & C_{9} & C_{10} & C_{11} \\
C_{7} & C_{2} & C_{12} & C_{13} & C_{14} & C_{15} \\
\vdots & C_{12} & C_{3} & C_{16} & C_{17} & C_{18} \\
\vdots & C_{13} & C_{16} & C_{4} & C_{19} & C_{20} \\
\vdots & \vdots & \vdots & C_{19} & C_{5} & C_{21} \\
\vdots & \vdots & \vdots & \vdots & C_{21} & C_{6}
\end{matrix}
in this matrix the indices of :math:`C_{k}` value are the corresponding element
:math:`k` in the global vector output by this compute. Each term comes from the sum
of the derivatives of every contribution to the potential energy
in the system as explained in :ref:`(VanWorkum)
<VanWorkum>`.
The output can be accessed using usual Lammps routines:
.. code-block:: LAMMPS
compute 1 all born/matrix
compute 2 all pressure NULL virial
variable S1 equal -c_2[1]
variable S2 equal -c_2[2]
variable S3 equal -c_2[3]
variable S4 equal -c_2[4]
variable S5 equal -c_2[5]
variable S6 equal -c_2[6]
fix 1 all ave/time 1 1 1 v_S1 v_S2 v_S3 v_S4 v_S5 v_S6 c_1[*] file born.out
In this example, the file *born.out* will contain the information needed to
compute the first and second terms of the elastic constant matrix in a post
processing procedure. The other required quantities can be accessed using any
other *LAMMPS* usual method. Several examples of this method are
provided in the examples/ELASTIC_T/BORN_MATRIX directory
described on the :doc:`Examples <Examples>` doc page.
NOTE: In the above :math:`C_{i,j}` computation, the fluctuation
term involving the virial stress tensor :math:`\sigma` is the
covariance between each elements. In a
solid the stress fluctuations can vary rapidly, while average
fluctuations can be slow to converge.
A detailed analysis of the convergence rate of all the terms in
the elastic tensor
is provided in the paper by Clavier et al. :ref:`(Clavier) <Clavier2>`.
Two different computation methods for the Born matrix are implemented in this
compute and are mutually exclusive.
The first one is a direct computation from the analytical formula from the
different terms of the potential used for the simulations :ref:`(VanWorkum)
<VanWorkum>`. However, the implementation of such derivations must be done
for every potential form. This has not been done yet and can be very
complicated for complex potentials. At the moment a warning message is
displayed for every term that is not supporting the compute at the moment.
This method is the default for now.
The second method uses finite differences of energy to numerically approximate
the second derivatives :ref:`(Zhen) <Zhen>`. This is useful when using
interaction styles for which the analytical second derivatives have not been
implemented. In this cases, the compute applies linear strain fields of
magnitude *delta* to all the atoms relative to a point at the center of the
box. The strain fields are in six different directions, corresponding to the
six Cartesian components of the stress tensor defined by LAMMPS. For each
direction it applies the strain field in both the positive and negative senses,
and the new stress virial tensor of the entire system is calculated after each.
The difference in these two virials divided by two times *delta*, approximates
the corresponding components of the second derivative, after applying a
suitable unit conversion.
.. note::
It is important to choose a suitable value for delta, the magnitude of
strains that are used to generate finite difference
approximations to the exact virial stress. For typical systems, a value in
the range of 1 part in 1e5 to 1e6 will be sufficient.
However, the best value will depend on a multitude of factors
including the stiffness of the interatomic potential, the thermodynamic
state of the material being probed, and so on. The only way to be sure
that you have made a good choice is to do a sensitivity study on a
representative atomic configuration, sweeping over a wide range of
values of delta. If delta is too small, the output values will vary
erratically due to truncation effects. If delta is increased beyond a
certain point, the output values will start to vary smoothly with
delta, due to growing contributions from higher order derivatives. In
between these two limits, the numerical virial values should be largely
independent of delta.
The keyword requires the additional arguments *delta* and *virial-ID*.
*delta* gives the size of the applied strains. *virial-ID* gives
the ID string of the pressure compute that provides the virial stress tensor,
requiring that it use the virial keyword e.g.
.. code-block:: LAMMPS
compute myvirial all pressure NULL virial
compute 1 all born/matrix numdiff 1.0e-4 myvirial
**Output info:**
This compute calculates a global vector with 21 values that are
the second derivatives of the potential energy w.r.t. strain.
The values are in energy units.
The values are ordered as explained above. These values can be used
by any command that uses global values from a compute as input. See
the :doc:`Howto output <Howto_output>` doc page for an overview of
LAMMPS output options.
The array values calculated by this compute are all "extensive".
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info. LAMMPS was built with that package. See
the :doc:`Build package <Build_package>` page for more info.
The Born term can be decomposed as a product of two terms. The first one is a
general term which depends on the configuration. The second one is specific to
every interaction composing your force field (non-bonded, bonds, angle...).
Currently not all LAMMPS interaction styles implement the *born_matrix* method
giving first and second order derivatives and LAMMPS will exit with an error if
this compute is used with such interactions unless the *numdiff* option is
also used. The *numdiff* option cannot be used with any other keyword. In this
situation, LAMMPS will also exit with an error.
Default
"""""""
none
----------
.. _VanWorkum:
**(Van Workum)** K. Van Workum et al., J. Chem. Phys. 125 144506 (2006)
.. _Clavier2:
**(Clavier)** G. Clavier, N. Desbiens, E. Bourasseau, V. Lachet, N. Brusselle-Dupend and B. Rousseau, Mol Sim, 43, 1413 (2017).
.. _Zhen:
**(Zhen)** Y. Zhen, C. Chu, Computer Physics Communications 183(2012)261-265

99
doc/src/compute_fep_ta.rst Normal file
View File

@ -0,0 +1,99 @@
.. index:: compute fep/ta
compute fep/ta command
======================
Syntax
""""""
.. parsed-literal::
compute ID group-ID fep/ta temp plane scale_factor keyword value ...
* ID, group-ID are documented in the :doc:`compute <compute>` command
* fep/ta = name of this compute command
* temp = external temperature (as specified for constant-temperature run)
* plane = *xy* or *xz* or *yz*
* scale_factor = multiplicative factor for change in plane area
* zero or more keyword/value pairs may be appended
* keyword = *tail*
.. parsed-literal::
*tail* value = *no* or *yes*
*no* = ignore tail correction to pair energies (usually small in fep)
*yes* = include tail correction to pair energies
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all fep/ta 298 xy 1.0005
Description
"""""""""""
Define a computation that calculates the change in the free energy due
to a test-area (TA) perturbation :ref:`(Gloor) <Gloor>`. The test-area
approach can be used to determine the interfacial tension of the system
in a single simulation:
.. math::
\gamma = \lim_{\Delta \mathcal{A} \to 0} \left( \frac{\Delta A_{0 \to 1 }}{\Delta \mathcal{A}}\right)_{N,V,T}
= - \frac{kT}{\Delta \mathcal{A}} \ln \left< \exp(-(U_1 - U_0)/kT) \right>_0
During the perturbation, both axes of *plane* are scaled by multiplying
:math:`\sqrt{scale\_factor}`, while the other axis divided by
*scale_factor* such that the overall volume of the system is maintained.
The *tail* keyword controls the calculation of the tail correction to
"van der Waals" pair energies beyond the cutoff, if this has been
activated via the :doc:`pair_modify <pair_modify>` command. If the
perturbation is small, the tail contribution to the energy difference
between the reference and perturbed systems should be negligible.
----------
Output info
"""""""""""
This compute calculates a global vector of length 3 which contains the
energy difference ( :math:`U_1-U_0` ) as c_ID[1], the Boltzmann factor
:math:`\exp(-(U_1-U_0)/kT)`, as c_ID[2] and the change in the *plane*
area :math:`\Delta \mathcal{A}` as c_ID[3]. :math:`U_1` is the potential
energy of the perturbed state and :math:`U_0` is the potential energy of
the reference state. The energies include kspace terms if these are
used in the simulation.
These output results can be used by any command that uses a global
scalar or vector from a compute as input. See the :doc:`Howto output
<Howto_output>` page for an overview of LAMMPS output options. For
example, the computed values can be averaged using :doc:`fix ave/time
<fix_ave_time>`.
Restrictions
""""""""""""
Constraints, like fix shake, may lead to incorrect values for energy difference.
This compute is distributed as the FEP package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`compute fep <compute_fep>`
Default
"""""""
The option defaults are *tail* = *no*\ .
----------
.. _Gloor:
**(Gloor)** Gloor, J Chem Phys, 123, 134703 (2005)

21
doc/src/compute_heat_flux.rst
View File

@ -89,13 +89,20 @@ included in the calculation.
.. warning::
The compute *heat/flux* has been reported to produce unphysical
values for angle, dihedral and improper contributions
values for angle, dihedral, improper and constraint force contributions
when used with :doc:`compute stress/atom <compute_stress_atom>`,
as discussed in :ref:`(Surblys) <Surblys2>` and :ref:`(Boone) <Boone>`.
You are strongly advised to
as discussed in :ref:`(Surblys2019) <Surblys3>`, :ref:`(Boone) <Boone>`
and :ref:`(Surblys2021) <Surblys4>`. You are strongly advised to
use :doc:`compute centroid/stress/atom <compute_stress_atom>`,
which has been implemented specifically for such cases.
.. warning::
Due to an implementation detail, the :math:`y` and :math:`z`
components of heat flux from :doc:`fix rigid <fix_rigid>`
contribution when computed via :doc:`compute stress/atom <compute_stress_atom>`
are highly unphysical and should not be used.
The Green-Kubo formulas relate the ensemble average of the
auto-correlation of the heat flux :math:`\mathbf{J}`
to the thermal conductivity :math:`\kappa`:
@ -232,10 +239,14 @@ none
----------
.. _Surblys2:
.. _Surblys3:
**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
.. _Boone:
**(Boone)** Boone, Babaei, Wilmer, J Chem Theory Comput, 15, 5579--5587 (2019).
.. _Surblys4:
**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).

9
doc/src/compute_momentum.rst
View File

@ -23,11 +23,10 @@ Examples
Description
"""""""""""
Define a computation that calculates the translational momentum
of a group of particles.
The momentum of each particles is computed as m v, where m and v are
the mass and velocity of the particle.
Define a computation that calculates the translational momentum *p*
of a group of particles. It is computed as the sum :math:`\vec{p} = \sum_i m_i \cdot \vec{v}_i`
over all particles in the compute group, where *m* and *v* are
the mass and velocity vector of the particle, respectively.
Output info
"""""""""""

12
doc/src/compute_msd.rst
View File

@ -75,10 +75,11 @@ solids undergoing thermal motion.
.. note::
Initial coordinates are stored in "unwrapped" form, by using the
image flags associated with each atom. See the :doc:`dump custom <dump>` command for a discussion of "unwrapped" coordinates.
See the Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You can
reset the image flags (e.g. to 0) before invoking this compute by
image flags associated with each atom. See the :doc:`dump custom
<dump>` command for a discussion of "unwrapped" coordinates. See the
Atoms section of the :doc:`read_data <read_data>` command for a
discussion of image flags and how they are set for each atom. You
can reset the image flags (e.g. to 0) before invoking this compute by
using the :doc:`set image <set>` command.
.. note::
@ -108,7 +109,8 @@ distance\^2 :doc:`units <units>`.
Restrictions
""""""""""""
none
Compute *msd* cannot be used with a dynamic group.
Related commands
""""""""""""""""

7
doc/src/compute_msd_nongauss.rst
View File

@ -74,8 +74,11 @@ the third is dimensionless.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
Compute *msd/nongauss* cannot be used with a dynamic group.
This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""

52
doc/src/compute_nbond_atom.rst Normal file
View File

@ -0,0 +1,52 @@
.. index:: compute nbond/atom
compute nbond/atom command
==========================
Syntax
""""""
.. parsed-literal::
compute ID group-ID nbond/atom
* ID, group-ID are documented in :doc:`compute <compute>` command
* nbond/atom = style name of this compute command
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all nbond/atom
Description
"""""""""""
Define a computation that computes the number of bonds each atom is
part of. Bonds which are broken are not counted in the tally. See
the :doc:`Howto broken bonds <Howto_bpm>` page for more information.
The number of bonds will be zero for atoms not in the specified
compute group. This compute does not depend on Newton bond settings.
Output info
"""""""""""
This compute calculates a per-atom vector, which can be accessed by
any command that uses per-atom values from a compute as input. See
the :doc:`Howto output <Howto_output>` doc page for an overview of
LAMMPS output options.
Restrictions
""""""""""""
This fix can only be used if LAMMPS was built with the BPM package.
See the :doc:`Build package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
Default
"""""""
none

14
doc/src/compute_pair_local.rst
View File

@ -13,11 +13,12 @@ Syntax
* ID, group-ID are documented in :doc:`compute <compute>` command
* pair/local = style name of this compute command
* one or more values may be appended
* value = *dist* or *eng* or *force* or *fx* or *fy* or *fz* or *pN*
* value = *dist* or *dx* or *dy* or *dz* or *eng* or *force* or *fx* or *fy* or *fz* or *pN*
.. parsed-literal::
*dist* = pairwise distance
*dx*,\ *dy*,\ *dz* = components of pairwise distance
*eng* = pairwise energy
*force* = pairwise force
*fx*,\ *fy*,\ *fz* = components of pairwise force
@ -56,6 +57,9 @@ force cutoff distance for that interaction, as defined by the
commands.
The value *dist* is the distance between the pair of atoms.
The values *dx*, *dy*, and *dz* are the xyz components of the
*distance* between the pair of atoms. This value is always the
distance from the atom of lower to the one with the higher id.
The value *eng* is the interaction energy for the pair of atoms.
@ -89,10 +93,10 @@ from the second of the two sub-styles. If the referenced *pN*
is not computed for the specific pairwise interaction (based on
atom types), then the output will be 0.0.
The value *dist* will be in distance :doc:`units <units>`. The value
*eng* will be in energy :doc:`units <units>`. The values *force*, *fx*,
*fy*, and *fz* will be in force :doc:`units <units>`. The values *pN*
will be in whatever units the pair style defines.
The value *dist*, *dx*, *dy* and *dz* will be in distance :doc:`units <units>`.
The value *eng* will be in energy :doc:`units <units>`.
The values *force*, *fx*, *fy*, and *fz* will be in force :doc:`units <units>`.
The values *pN* will be in whatever units the pair style defines.
The optional *cutoff* keyword determines how the force cutoff distance
for an interaction is determined. For the default setting of *type*,

2
doc/src/compute_pressure.rst
View File

@ -141,7 +141,7 @@ Related commands
""""""""""""""""
:doc:`compute temp <compute_temp>`, :doc:`compute stress/atom <compute_stress_atom>`,
:doc:`thermo_style <thermo_style>`,
:doc:`thermo_style <thermo_style>`, :doc:`fix numdiff/virial <fix_numdiff_virial>`,
Default
"""""""

88
doc/src/compute_pressure_cylinder.rst
View File

@ -1,88 +0,0 @@
.. index:: compute pressure/cylinder
compute pressure/cylinder command
=================================
Syntax
""""""
.. parsed-literal::
compute ID group-ID pressure/cylinder zlo zhi Rmax bin_width
* ID, group-ID are documented in :doc:`compute <compute>` command
* pressure/cylinder = style name of this compute command
* zlo = minimum z-boundary for cylinder
* zhi = maximum z-boundary for cylinder
* Rmax = maximum radius to perform calculation to
* bin_width = width of radial bins to use for calculation
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all pressure/cylinder -10.0 10.0 15.0 0.25
Description
"""""""""""
Define a computation that calculates the pressure tensor of a system in
cylindrical coordinates, as discussed in :ref:`(Addington) <Addington1>`.
This is useful for systems with a single axis of rotational symmetry,
such as cylindrical micelles or carbon nanotubes. The compute splits the
system into radial, cylindrical-shell-type bins of width bin_width,
centered at x=0,y=0, and calculates the radial (P_rhorho), azimuthal
(P_phiphi), and axial (P_zz) components of the configurational pressure
tensor. The local density is also calculated for each bin, so that the
true pressure can be recovered as P_kin+P_conf=density\*k\*T+P_conf. The
output is a global array with 5 columns; one each for bin radius, local
number density, P_rhorho, P_phiphi, and P_zz. The number of rows is
governed by the values of Rmax and bin_width. Pressure tensor values are
output in pressure units.
Output info
"""""""""""
This compute calculates a global array with 5 columns and Rmax/bin_width
rows. The output columns are: R (distance units), number density (inverse
volume units), configurational radial pressure (pressure units),
configurational azimuthal pressure (pressure units), and configurational
axial pressure (pressure units).
The values calculated by this compute are
"intensive". The pressure values will be in pressure
:doc:`units <units>`. The number density values will be in
inverse volume :doc:`units <units>`.
Restrictions
""""""""""""
This compute currently calculates the pressure tensor contributions
for pair styles only (i.e. no bond, angle, dihedral, etc. contributions
and in the presence of bonded interactions, the result will be incorrect
due to exclusions for special bonds) and requires pair-wise force
calculations not available for most many-body pair styles. K-space
calculations are also excluded. Note that this pressure compute outputs
the configurational terms only; the kinetic contribution is not included
and may be calculated from the number density output by P_kin=density\*k\*T.
This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`compute temp <compute_temp>`, :doc:`compute stress/atom <compute_stress_atom>`,
:doc:`thermo_style <thermo_style>`,
Default
"""""""
none
----------
.. _Addington1:
**(Addington)** Addington, Long, Gubbins, J Chem Phys, 149, 084109 (2018).

7
doc/src/compute_rigid_local.rst
View File

@ -127,19 +127,16 @@ The *vx*, *vy*, *vz*, *fx*, *fy*, *fz* attributes are components of
the COM velocity and force on the COM of the body.
The *omegax*, *omegay*, and *omegaz* attributes are the angular
velocity components of the body around its COM.
velocity components of the body in the system frame around its COM.
The *angmomx*, *angmomy*, and *angmomz* attributes are the angular
momentum components of the body around its COM.
momentum components of the body in the system frame around its COM.
The *quatw*, *quati*, *quatj*, and *quatk* attributes are the
components of the 4-vector quaternion representing the orientation of
the rigid body. See the :doc:`set <set>` command for an explanation of
the quaternion vector.
The *angmomx*, *angmomy*, and *angmomz* attributes are the angular
momentum components of the body around its COM.
The *tqx*, *tqy*, *tqz* attributes are components of the torque acting
on the body around its COM.

38
doc/src/compute_sna_atom.rst
View File

@ -33,7 +33,7 @@ Syntax
* R_1, R_2,... = list of cutoff radii, one for each type (distance units)
* w_1, w_2,... = list of neighbor weights, one for each type
* zero or more keyword/value pairs may be appended
* keyword = *rmin0* or *switchflag* or *bzeroflag* or *quadraticflag* or *chem* or *bnormflag* or *wselfallflag*
* keyword = *rmin0* or *switchflag* or *bzeroflag* or *quadraticflag* or *chem* or *bnormflag* or *wselfallflag* or *bikflag* or *switchinnerflag*
.. parsed-literal::
@ -56,6 +56,12 @@ Syntax
*wselfallflag* value = *0* or *1*
*0* = self-contribution only for element of central atom
*1* = self-contribution for all elements
*bikflag* value = *0* or *1* (only implemented for compute snap)
*0* = per-atom bispectrum descriptors are summed over atoms
*1* = per-atom bispectrum descriptors are not summed over atoms
*switchinnerflag* values = *rinnerlist* *drinnerlist*
*rinnerlist* = *ntypes* values of rinner (distance units)
*drinnerlist* = *ntypes* values of drinner (distance units)
Examples
""""""""
@ -67,6 +73,7 @@ Examples
compute vb all sna/atom 1.4 0.95 6 2.0 1.0
compute snap all snap 1.4 0.95 6 2.0 1.0
compute snap all snap 1.0 0.99363 6 3.81 3.83 1.0 0.93 chem 2 0 1
compute snap all snap 1.0 0.99363 6 3.81 3.83 1.0 0.93 switchinnerflag 1.1 1.3 0.5 0.6
Description
"""""""""""
@ -296,6 +303,35 @@ This option is typically used in conjunction with the *chem* keyword,
and LAMMPS will generate a warning if both *chem* and *bnormflag*
are not both set or not both unset.
The keyword *bikflag* determines whether or not to expand the bispectrum
rows of the global array returned by compute snap. If *bikflag* is set
to *1* then the bispectrum row, which is typically the per-atom bispectrum
descriptors :math:`B_{i,k}` summed over all atoms *i* to produce
:math:`B_k`, becomes bispectrum rows equal to the number of atoms. Thus,
the resulting bispectrum rows are :math:`B_{i,k}` instead of just
:math:`B_k`. In this case, the entries in the final column for these rows
are set to zero.
The keyword *switchinnerflag* activates an additional radial switching
function similar to :math:`f_c(r)` above, but acting to switch off
smoothly contributions from neighbor atoms at short separation distances.
This is useful when SNAP is used in combination with a simple
repulsive potential. The keyword is followed by the *ntypes*
values for :math:`r_{inner}` and the *ntypes*
values for :math:`\Delta r_{inner}`. For a neighbor atom at
distance :math:`r`, its contribution is scaled by a multiplicative
factor :math:`f_{inner}(r)` defined as follows:
.. math::
= & 0, r \leq r_{inner} \\
f_{inner}(r) = & \frac{1}{2}(1 - \cos(\pi \frac{r-r_{inner}}{\Delta r_{inner}})), r_{inner} < r \leq r_{inner} + \Delta r_{inner} \\
= & 1, r > r_{inner} + \Delta r_{inner}
The values of :math:`r_{inner}` and :math:`\Delta r_{inner}` are
the arithmetic means of the values for the central atom of type I
and the neighbor atom of type J.
.. note::
If you have a bonded system, then the settings of :doc:`special_bonds

45
doc/src/compute_stress_atom.rst
View File

@ -87,6 +87,10 @@ Tersoff 3-body interaction) is assigned in equal portions to each atom
in the set. E.g. 1/4 of the dihedral virial to each of the 4 atoms,
or 1/3 of the fix virial due to SHAKE constraints applied to atoms in
a water molecule via the :doc:`fix shake <fix_shake>` command.
As an exception, the virial contribution from
constraint forces in :doc:`fix rigid <fix_rigid>` on each atom
is computed from the constraint force acting on the corresponding atom
and its position, i.e. the total virial is not equally distributed.
In case of compute *centroid/stress/atom*, the virial contribution is:
@ -103,13 +107,25 @@ atom :math:`I` due to the interaction and the relative position
:math:`\mathbf{r}_{I0}` of the atom :math:`I` to the geometric center
of the interacting atoms, i.e. centroid, is used. As the geometric
center is different for each interaction, the :math:`\mathbf{r}_{I0}`
also differs. The sixth and seventh terms, Kspace and :doc:`fix
<fix>` contribution respectively, are computed identical to compute
*stress/atom*. Although the total system virial is the same as
also differs. The sixth term, Kspace contribution,
is computed identically to compute *stress/atom*.
The seventh term is handed differently depending on
if the constraint forces are due to :doc:`fix shake <fix_shake>`
or :doc:`fix rigid <fix_rigid>`.
In case of SHAKE constraints, each distance constraint is
handed as a pairwise interaction.
E.g. in case of a water molecule, two OH and one HH distance
constraints are treated as three pairwise interactions.
In case of :doc:`fix rigid <fix_rigid>`,
all constraint forces in the molecule are treated
as a single many-body interaction with a single centroid position.
In case of water molecule, the formula expression would become
identical to that of the three-body angle interaction.
Although the total system virial is the same as
compute *stress/atom*, compute *centroid/stress/atom* is know to
result in more consistent heat flux values for angle, dihedrals and
improper contributions when computed via :doc:`compute heat/flux
<compute_heat_flux>`.
result in more consistent heat flux values for angle, dihedrals,
improper and constraint force contributions
when computed via :doc:`compute heat/flux <compute_heat_flux>`.
If no extra keywords are listed, the kinetic contribution all of the
virial contribution terms are included in the per-atom stress tensor.
@ -134,7 +150,8 @@ contribution for the cluster interaction is divided evenly among those
atoms.
Details of how compute *centroid/stress/atom* obtains the virial for
individual atoms is given in :ref:`(Surblys) <Surblys1>`, where the
individual atoms are given in :ref:`(Surblys2019) <Surblys1>` and
:ref:`(Surblys2021) <Surblys2>`, where the
idea is that the virial of the atom :math:`I` is the result of only
the force :math:`\mathbf{F}_I` on the atom due to the interaction and
its positional vector :math:`\mathbf{r}_{I0}`, relative to the
@ -235,10 +252,10 @@ between the pair of particles. All bond styles are supported. All
angle, dihedral, improper styles are supported with the exception of
INTEL and KOKKOS variants of specific styles. It also does not
support models with long-range Coulombic or dispersion forces,
i.e. the kspace_style command in LAMMPS. It also does not support the
following fixes which add rigid-body constraints: :doc:`fix shake
<fix_shake>`, :doc:`fix rattle <fix_shake>`, :doc:`fix rigid
<fix_rigid>`, :doc:`fix rigid/small <fix_rigid>`.
i.e. the kspace_style command in LAMMPS. It also does not implement the
following fixes which add rigid-body constraints:
:doc:`fix rigid/* <fix_rigid>` and the OpenMP accelerated version of :doc:`fix rigid/small <fix_rigid>`,
while all other :doc:`fix rigid/*/small <fix_rigid>` are implemented.
LAMMPS will generate an error if one of these options is included in
your model. Extension of centroid stress calculations to these force
@ -270,4 +287,8 @@ none
.. _Surblys1:
**(Surblys)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
**(Surblys2019)** Surblys, Matsubara, Kikugawa, Ohara, Phys Rev E, 99, 051301(R) (2019).
.. _Surblys2:
**(Surblys2021)** Surblys, Matsubara, Kikugawa, Ohara, J Appl Phys 130, 215104 (2021).

25
doc/src/compute_stress_mop.rst
View File

@ -68,7 +68,19 @@ configurational stress (conf), and/or total stress (total).
NOTE 1: The configurational stress is computed considering all pairs of atoms where at least one atom belongs to group group-ID.
NOTE 2: The local stress does not include any Lennard-Jones tail
corrections to the pressure added by the :doc:`pair_modify tail yes <pair_modify>` command, since those are contributions to the global system pressure.
corrections to the stress added by the :doc:`pair_modify tail yes <pair_modify>`
command, since those are contributions to the global system pressure.
NOTE 3: The local stress profile generated by compute *stress/mop/profile*
is similar to that obtained by compute
:doc:`stress/cartesian <compute_stress_profile>`.
A key difference
is that compute *stress/mop/profile* considers particles
crossing a set of planes,
while compute *stress/cartesian* computes averages for a set of
small volumes. More information
on the similarities and differences can be found in
:ref:`(Ikeshoji)<Ikeshoji2>`.
Output info
"""""""""""
@ -87,7 +99,10 @@ and stress_dir,z.
The values are in pressure :doc:`units <units>`.
The values produced by this compute can be accessed by various :doc:`output commands <Howto_output>`. For instance, the results can be written to a file using the :doc:`fix ave/time <fix_ave_time>` command. Please see the example in the examples/PACKAGES/mop folder.
The values produced by this compute can be accessed by various :doc:`output commands <Howto_output>`.
For instance, the results can be written to a file using the
:doc:`fix ave/time <fix_ave_time>` command. Please see the example
in the examples/PACKAGES/mop folder.
Restrictions
""""""""""""
@ -107,7 +122,7 @@ intra-molecular interactions, and long range (kspace) interactions.
Related commands
""""""""""""""""
:doc:`compute stress/atom <compute_stress_atom>`
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`, :doc:`compute stress/cartesian <compute_stress_profile>`, :doc:`compute stress/cylinder <compute_stress_profile>`, :doc:`compute stress/spherical <compute_stress_profile>`
Default
"""""""
@ -120,3 +135,7 @@ none
**(Todd)** B. D. Todd, Denis J. Evans, and Peter J. Daivis: "Pressure tensor for inhomogeneous fluids",
Phys. Rev. E 52, 1627 (1995).
.. _Ikeshoji3:
**(Ikeshoji)** Ikeshoji, Hafskjold, Furuholt, Mol Sim, 29, 101-109, (2003).

165
doc/src/compute_stress_profile.rst Normal file
View File

@ -0,0 +1,165 @@
.. index:: compute stress/cartesian
.. index:: compute stress/cylinder
.. index:: compute stress/spherical
compute stress/cartesian command
==================================
compute stress/cylinder command
=================================
compute stress/spherical command
==================================
Syntax
""""""
.. parsed-literal::
compute ID group-ID style args
* ID, group-ID are documented in :doc:`compute <compute>` command
* style = stress/cartesian or stress/spherical or stress/cylinder
* args = argument specific to the compute style
.. parsed-literal::
*stress/cartesian* args = dim bin_width
dim = x, y, or z. One or two dim/bin_width pairs may be appended
bin_width = width of the bin
*stress/cylinder* args = zlo zh Rmax bin_width keyword
zlo = minimum z-boundary for cylinder
zhi = maximum z-boundary for cylinder
Rmax = maximum radius to perform calculation to
bin_width = width of radial bins to use for calculation
keyword = ke (zero or one can be specified)
ke = yes or no
*stress/spherical*
x0, y0, z0 = origin of the spherical coordinate system
bin_width = width of spherical shells
Rmax = maximum radius of spherical shells
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all stress/cartesian x 0.1
compute 1 all stress/cartesian y 0.25 z 0.1
compute 1 all stress/cylinder -10.0 10.0 15.0 0.25
compute 1 all stress/cylinder -10.0 10.0 15.0 0.25 ke no
compute 1 all stress/spherical 0 0 0 0.1 10
Description
"""""""""""
Compute *stress/cartesian*, compute *stress/cylinder*, and compute
*stress/spherical* define computations that calculate profiles of the
diagonal components of the local stress tensor in the specified
coordinate system. The stress tensor is split into a kinetic
contribution :math:`P^k` and a virial contribution :math:`P^v`. The sum
gives the total stress tensor :math:`P = P^k+P^v`. These computes can
for example be used to calculate the diagonal components of the local
stress tensor of interfaces with flat, cylindrical, or spherical
symmetry. These computes obeys momentum balance through fluid
interfaces. They use the Irving-Kirkwood contour, which is the straight
line between particle pairs.
The *stress/cartesian* computes the stress profile along one or two
Cartesian coordinates, as described in :ref:`(Ikeshoji)<Ikeshoji2>`. The
compute *stress/cylinder* computes the stress profile along the
radial direction in cylindrical coordinates, as described in
:ref:`(Addington)<Addington1>`. The compute *stress/spherical*
computes the stress profile along the radial direction in spherical
coordinates, as described in :ref:`(Ikeshoji)<Ikeshoji2>`.
Output info
"""""""""""
The output columns for *stress/cartesian* are the position of the
center of the local volume in the first and second dimensions, number
density, :math:`P^k_{xx}`, :math:`P^k_{yy}`, :math:`P^k_{zz}`,
:math:`P^v_{xx}`, :math:`P^v_{yy}`, and :math:`P^v_{zz}`. There are 8
columns when one dimension is specified and 9 columns when two
dimensions are specified. The number of bins/rows are
(L1/bin_width1)*(L2/bin_width2), L1 and L2 are the sizes of the
simulation box in the specified dimensions, and bin_width1 and
bin_width2 are the specified bin widths. When only one dimension is
specified the number of bins/rows are L1/bin_width.
The default output columns for *stress/cylinder* are the radius to the
center of the cylindrical shell, number density, :math:`P^k_{rr}`,
:math:`P^k_{\phi\phi}`, :math:`P^k_{zz}`, :math:`P^v_{rr}`,
:math:`P^v_{\phi\phi}`, and :math:`P^v_{zz}`. When the keyword *ke* is
set to no, the kinetic contributions are not calculated, and
consequently there are only 5 columns the radius to the center of the
cylindrical shell, number density, :math:`P^v_{rr}`,
:math:`P^v_{\phi\phi}`, :math:`P^v_{zz}`. The number of bins/rows are
Rmax/bin_width.
The output columns for *stress/spherical* are the radius to the center
of the spherical shell, number density, :math:`P^k_{rr}`,
:math:`P^k_{\theta\theta}`, :math:`P^k_{\phi\phi}`, :math:`P^v_{rr}`,
:math:`P^v_{\theta\theta}`, and :math:`P^v_{\phi\phi}`. There are 8
columns and the number of bins/rows are Rmax/bin_width.
This array can be output with :doc:`fix ave/time <fix_ave_time>`,
.. code-block:: LAMMPS
compute p all stress/cartesian x 0.1
fix 2 all ave/time 100 1 100 c_p[*] file dump_p.out mode vector
The values calculated by this compute are "intensive". The stress
values will be in pressure :doc:`units <units>`. The number density
values are in inverse volume :doc:`units <units>`.
NOTE 1: The local stress does not include any Lennard-Jones tail
corrections to the stress added by the :doc:`pair_modify tail yes <pair_modify>`
command, since those are contributions to the global system pressure.
NOTE 2: The local stress profiles generated by these computes are
similar to those obtained by the
:doc:`method-of-planes (MOP) <compute_stress_mop>`.
A key difference
is that compute `stress/mop/profile <compute_stress_mop>`
considers particles crossing a set of planes, while
*stress/cartesian* computes averages for a set of small volumes.
More information on the similarities and differences can be found in
:ref:`(Ikeshoji)<Ikeshoji2>`.
Restrictions
""""""""""""
These computes calculate the stress tensor contributions for pair
styles only (i.e. no bond, angle, dihedral, etc. contributions, and in
the presence of bonded interactions, the result will be incorrect due to
exclusions for special bonds) and requires pairwise force calculations
not available for most many-body pair styles. K-space calculations are
also excluded.
These computes are part of the EXTRA-COMPUTE package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build
package <Build_package>` doc page for more info.
Related commands
""""""""""""""""
:doc:`compute stress/atom <compute_stress_atom>`, :doc:`compute pressure <compute_pressure>`, :doc:`compute stress/mop/profile <compute_stress_mop>`
Default
"""""""
The keyword default for ke in style *stress/cylinder* is yes.
----------
.. _Ikeshoji2:
**(Ikeshoji)** Ikeshoji, Hafskjold, Furuholt, Mol Sim, 29, 101-109, (2003).
.. _Addington1:
**(Addington)** Addington, Long, Gubbins, J Chem Phys, 149, 084109 (2018).

60
doc/src/compute_tally.rst
View File

@ -31,7 +31,7 @@ Syntax
compute ID group-ID style group2-ID
* ID, group-ID are documented in :doc:`compute <compute>` command
* style = *force/tally* or *heat/flux/tally* or *heat/flux/virial/tally* or * or *pe/tally* or *pe/mol/tally* or *stress/tally*
* style = *force/tally* or *heat/flux/tally* or *heat/flux/virial/tally* or *pe/tally* or *pe/mol/tally* or *stress/tally*
* group2-ID = group ID of second (or same) group
Examples
@ -61,7 +61,7 @@ mechanism. Compute *pe/mol/tally* is one such style, that can
- through using this mechanism - separately tally intermolecular
and intramolecular energies. Something that would otherwise be
impossible without integrating this as a core functionality into
the based classes of LAMMPS.
the base classes of LAMMPS.
----------
@ -148,30 +148,38 @@ pairwise property computations.
Output info
"""""""""""
Compute *pe/tally* calculates a global scalar (the energy) and a per
atom scalar (the contributions of the single atom to the global
scalar). Compute *pe/mol/tally* calculates a global 4-element vector
containing (in this order): *evdwl* and *ecoul* for intramolecular pairs
and *evdwl* and *ecoul* for intermolecular pairs. Since molecules are
identified by their molecule IDs, the partitioning does not have to be
related to molecules, but the energies are tallied into the respective
slots depending on whether the molecule IDs of a pair are the same or
different. Compute *force/tally* calculates a global scalar (the force
magnitude) and a per atom 3-element vector (force contribution from
each atom). Compute *stress/tally* calculates a global scalar
(average of the diagonal elements of the stress tensor) and a per atom
vector (the 6 elements of stress tensor contributions from the
individual atom). As in :doc:`compute heat/flux <compute_heat_flux>`,
compute *heat/flux/tally* calculates a global vector of length 6,
where the first 3 components are the :math:`x`, :math:`y`, :math:`z`
components of the full heat flow vector,
and the next 3 components are the corresponding components
of just the convective portion of the flow, i.e. the
first term in the equation for :math:`\mathbf{Q}`.
Compute *heat/flux/virial/tally* calculates a global scalar (heat flow)
and a per atom 3-element vector
(contribution to the force acting over atoms in the first group
from individual atoms in both groups).
- Compute *pe/tally* calculates a global scalar (the energy) and a per
atom scalar (the contributions of the single atom to the global
scalar).
- Compute *pe/mol/tally* calculates a global 4-element vector containing
(in this order): *evdwl* and *ecoul* for intramolecular pairs and
*evdwl* and *ecoul* for intermolecular pairs. Since molecules are
identified by their molecule IDs, the partitioning does not have to be
related to molecules, but the energies are tallied into the respective
slots depending on whether the molecule IDs of a pair are the same or
different.
- Compute *force/tally* calculates a global scalar (the force magnitude)
and a per atom 3-element vector (force contribution from each atom).
- Compute *stress/tally* calculates a global scalar
(average of the diagonal elements of the stress tensor) and a per atom
vector (the 6 elements of stress tensor contributions from the
individual atom).
- As in :doc:`compute heat/flux <compute_heat_flux>`,
compute *heat/flux/tally* calculates a global vector of length 6,
where the first 3 components are the :math:`x`, :math:`y`, :math:`z`
components of the full heat flow vector,
and the next 3 components are the corresponding components
of just the convective portion of the flow, i.e. the
first term in the equation for :math:`\mathbf{Q}`.
- Compute *heat/flux/virial/tally* calculates a global scalar (heat flow)
and a per atom 3-element vector
(contribution to the force acting over atoms in the first group
from individual atoms in both groups).
Both the scalar and vector values calculated by this compute are
"extensive".

45
doc/src/compute_temp_profile.rst
View File

@ -76,21 +76,28 @@ velocity for each atom. Note that if there is only one atom in the
bin, its thermal velocity will thus be 0.0.
After the spatially-averaged velocity field has been subtracted from
each atom, the temperature is calculated by the formula KE = (dim\*N
- dim\*Nx\*Ny\*Nz) k T/2, where KE = total kinetic energy of the group of
atoms (sum of 1/2 m v\^2), dim = 2 or 3 = dimensionality of the
simulation, N = number of atoms in the group, k = Boltzmann constant,
and T = temperature. The dim\*Nx\*Ny\*Nz term are degrees of freedom
subtracted to adjust for the removal of the center-of-mass velocity in
each of Nx\*Ny\*Nz bins, as discussed in the :ref:`(Evans) <Evans1>` paper.
each atom, the temperature is calculated by the formula
*KE* = (*dim\*N* - *Ns\*Nx\*Ny\*Nz* - *extra* ) *k* *T*/2, where *KE* = total
kinetic energy of the group of atoms (sum of 1/2 *m* *v*\^2), *dim* = 2
or 3 = dimensionality of the simulation, *Ns* = 0, 1, 2 or 3 for
streaming velocity subtracted in 0, 1, 2 or 3 dimensions, *extra* = extra
degrees-of-freedom, *N* = number of atoms in the group, *k* = Boltzmann
constant, and *T* = temperature. The *Ns\*Nx\*Ny\*Nz* term is degrees
of freedom subtracted to adjust for the removal of the center-of-mass
velocity in each direction of the *Nx\*Ny\*Nz* bins, as discussed in the
:ref:`(Evans) <Evans1>` paper. The extra term defaults to (*dim* - *Ns*)
and accounts for overall conservation of center-of-mass velocity across
the group in directions where streaming velocity is *not* subtracted. This
can be altered using the *extra* option of the
:doc:`compute_modify <compute_modify>` command.
If the *out* keyword is used with a *tensor* value, which is the
default, a kinetic energy tensor, stored as a 6-element vector, is
also calculated by this compute for use in the computation of a
pressure tensor. The formula for the components of the tensor is the
same as the above formula, except that v\^2 is replaced by vx\*vy for
the xy component, etc. The 6 components of the vector are ordered xx,
yy, zz, xy, xz, yz.
same as the above formula, except that *v*\^2 is replaced by *vx\*vy* for
the xy component, etc. The 6 components of the vector are ordered *xx,
yy, zz, xy, xz, yz.*
If the *out* keyword is used with a *bin* value, the count of atoms
and computed temperature for each bin are stored for output, as an
@ -123,10 +130,20 @@ needed, the subtracted degrees-of-freedom can be altered using the
.. note::
When using the *out* keyword with a value of *bin*, the
calculated temperature for each bin does not include the
degrees-of-freedom adjustment described in the preceding paragraph,
for fixes that constrain molecular motion. It does include the
adjustment due to the *extra* option, which is applied to each bin.
calculated temperature for each bin includes the degrees-of-freedom
adjustment described in the preceding paragraph for fixes that
constrain molecular motion, as well as the adjustment due to
the *extra* option (which defaults to *dim* - *Ns* as described above),
by fractionally applying them based on the fraction of atoms in each
bin. As a result, the bin degrees-of-freedom summed over all bins exactly
equals the degrees-of-freedom used in the scalar temperature calculation,
:math:`\Sigma N_{DOF_i} = N_{DOF}` and the corresponding relation for temperature
is also satisfied :math:`\Sigma N_{DOF_i} T_i = N_{DOF} T`.
These relations will breakdown in cases where the adjustment
exceeds the actual number of degrees-of-freedom in a bin. This could happen
if a bin is empty or in situations where rigid molecules
are non-uniformly distributed, in which case the reported
temperature within a bin may not be accurate.
See the :doc:`Howto thermostat <Howto_thermostat>` page for a
discussion of different ways to compute temperature and perform

5
doc/src/compute_viscosity_cos.rst
View File

@ -21,12 +21,13 @@ Examples
.. code-block:: LAMMPS
units real
compute cos all viscosity/cos
variable V equal c_cos[7]
variable A equal 0.02E-5
variable A equal 0.02E-5 # A/fs^2
variable density equal density
variable lz equal lz
variable reciprocalViscosity equal v_V/${A}/v_density*39.4784/v_lz/v_lz*100
variable reciprocalViscosity equal v_V/${A}/v_density*39.4784/v_lz/v_lz*100 # 1/(Pa*s)
Description
"""""""""""

46
doc/src/delete_atoms.rst
View File

@ -20,8 +20,10 @@ Syntax
cutoff = delete one atom from pairs of atoms within the cutoff (distance units)
group1-ID = one atom in pair must be in this group
group2-ID = other atom in pair must be in this group
*porosity* args = region-ID fraction seed
*porosity* args = group-ID region-ID fraction seed
group-ID = group within which to perform deletions
region-ID = region within which to perform deletions
or NULL to only impose the group criterion
fraction = delete this fraction of atoms
seed = random number seed (positive integer)
@ -43,7 +45,8 @@ Examples
delete_atoms region sphere compress no
delete_atoms overlap 0.3 all all
delete_atoms overlap 0.5 solvent colloid
delete_atoms porosity cube 0.1 482793 bond yes
delete_atoms porosity all cube 0.1 482793 bond yes
delete_atoms porosity polymer cube 0.1 482793 bond yes
Description
"""""""""""
@ -76,12 +79,17 @@ have occurred that no atom pairs within the cutoff will remain
minimum number of atoms will be deleted, or that the same atoms will
be deleted when running on different numbers of processors.
For style *porosity* a specified *fraction* of atoms are deleted
within the specified region. For example, if fraction is 0.1, then
10% of the atoms will be deleted. The atoms to delete are chosen
randomly. There is no guarantee that the exact fraction of atoms will
be deleted, or that the same atoms will be deleted when running on
different numbers of processors.
For style *porosity* a specified *fraction* of atoms are deleted which
are both in the specified group and within the specified region. The
region-ID can be specified as NULL to only impose the group criterion.
Likewise, specifying the group-ID as *all* will only impose the region
criterion.
For example, if fraction is 0.1, then 10% of the eligible atoms will
be deleted. The atoms to delete are chosen randomly. There is no
guarantee that the exact fraction of atoms will be deleted, or that
the same atoms will be deleted when running on different numbers of
processors.
If the *compress* keyword is set to *yes*, then after atoms are
deleted, then atom IDs are re-assigned so that they run from 1 to the
@ -89,8 +97,8 @@ number of atoms in the system. Note that this is not done for
molecular systems (see the :doc:`atom_style <atom_style>` command),
regardless of the *compress* setting, since it would foul up the bond
connectivity that has already been assigned. However, the
:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this command to
accomplish the same thing.
:doc:`reset_atom_ids <reset_atom_ids>` command can be used after this
command to accomplish the same thing.
Note that the re-assignment of IDs is not really a compression, where
gaps in atom IDs are removed by decrementing atom IDs that are larger.
@ -100,15 +108,15 @@ the :doc:`create_atoms <create_atoms>` command explains.
A molecular system with fixed bonds, angles, dihedrals, or improper
interactions, is one where the topology of the interactions is
typically defined in the data file read by the
:doc:`read_data <read_data>` command, and where the interactions
themselves are defined with the :doc:`bond_style <bond_style>`,
:doc:`angle_style <angle_style>`, etc commands. If you delete atoms
from such a system, you must be careful not to end up with bonded
interactions that are stored by remaining atoms but which include
deleted atoms. This will cause LAMMPS to generate a "missing atoms"
error when the bonded interaction is computed. The *bond* and *mol*
keywords offer two ways to do that.
typically defined in the data file read by the :doc:`read_data
<read_data>` command, and where the interactions themselves are
defined with the :doc:`bond_style <bond_style>`, :doc:`angle_style
<angle_style>`, etc commands. If you delete atoms from such a system,
you must be careful not to end up with bonded interactions that are
stored by remaining atoms but which include deleted atoms. This will
cause LAMMPS to generate a "missing atoms" error when the bonded
interaction is computed. The *bond* and *mol* keywords offer two ways
to do that.
It the *bond* keyword is set to *yes* then any bond or angle or
dihedral or improper interaction that includes a deleted atom is also

170
doc/src/dump.rst
View File

@ -36,7 +36,7 @@ Syntax
* ID = user-assigned name for the dump
* group-ID = ID of the group of atoms to be dumped
* style = *atom* or *atom/gz* or *atom/zstd or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *dcd* 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 *xyz/mpiio*
* style = *atom* or *atom/gz* or *atom/zstd or *atom/mpiio* or *cfg* or *cfg/gz* or *cfg/zstd* or *cfg/mpiio* or *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *dcd* 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 *xyz/mpiio* or *yaml*
* N = dump every this many timesteps
* file = name of file to write dump info to
* args = list of arguments for a particular style
@ -68,8 +68,9 @@ Syntax
*xyz/gz* args = none
*xyz/zstd* args = none
*xyz/mpiio* args = none
*yaml* args = same as *custom* args, see below
* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* args = list of atom attributes
* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* or *yaml* args = list of atom attributes
.. parsed-literal::
@ -137,7 +138,7 @@ Examples
dump myDump all atom/gz 100 dump.atom.gz
dump myDump all atom/zstd 100 dump.atom.zst
dump 2 subgroup atom 50 dump.run.bin
dump 2 subgroup atom 50 dump.run.mpiio.bin
dump 2 subgroup atom/mpiio 50 dump.run.mpiio.bin
dump 4a all custom 100 dump.myforce.* id type x y vx fx
dump 4b flow custom 100 dump.%.myforce id type c_myF[3] v_ke
dump 4b flow custom 100 dump.%.myforce id type c_myF[*] v_ke
@ -169,11 +170,12 @@ or multiple smaller files).
.. note::
Because periodic boundary conditions are enforced only on
timesteps when neighbor lists are rebuilt, the coordinates of an atom
written to a dump file may be slightly outside the simulation box.
Re-neighbor timesteps will not typically coincide with the timesteps
dump snapshots are written. See the :doc:`dump_modify pbc <dump_modify>` command if you with to force coordinates to be
Because periodic boundary conditions are enforced only on timesteps
when neighbor lists are rebuilt, the coordinates of an atom written
to a dump file may be slightly outside the simulation box.
Re-neighbor timesteps will not typically coincide with the
timesteps dump snapshots are written. See the :doc:`dump_modify
pbc <dump_modify>` command if you with to force coordinates to be
strictly inside the simulation box.
.. note::
@ -189,20 +191,21 @@ or multiple smaller files).
multiple processors, each of which owns a subset of the atoms.
For the *atom*, *custom*, *cfg*, and *local* styles, sorting is off by
default. For the *dcd*, *xtc*, *xyz*, and *molfile* styles, sorting by
atom ID is on by default. See the :doc:`dump_modify <dump_modify>` doc
page for details.
default. For the *dcd*, *xtc*, *xyz*, and *molfile* styles, sorting
by atom ID is on by default. See the :doc:`dump_modify <dump_modify>`
doc page for details.
The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles are identical
in command syntax to the corresponding styles without "gz", however,
they generate compressed files using the zlib library. Thus the filename
suffix ".gz" is mandatory. This is an alternative approach to writing
compressed files via a pipe, as done by the regular dump styles, which
may be required on clusters where the interface to the high-speed network
disallows using the fork() library call (which is needed for a pipe).
For the remainder of this doc page, you should thus consider the *atom*
and *atom/gz* styles (etc) to be inter-changeable, with the exception
of the required filename suffix.
The *atom/gz*, *cfg/gz*, *custom/gz*, *local/gz*, and *xyz/gz* styles
are identical in command syntax to the corresponding styles without
"gz", however, they generate compressed files using the zlib
library. Thus the filename suffix ".gz" is mandatory. This is an
alternative approach to writing compressed files via a pipe, as done
by the regular dump styles, which may be required on clusters where
the interface to the high-speed network disallows using the fork()
library call (which is needed for a pipe). For the remainder of this
doc page, you should thus consider the *atom* and *atom/gz* styles
(etc) to be inter-changeable, with the exception of the required
filename suffix.
Similarly, the *atom/zstd*, *cfg/zstd*, *custom/zstd*, *local/zstd*,
and *xyz/zstd* styles are identical to the gz styles, but use the Zstd
@ -219,6 +222,11 @@ you should thus consider the *atom* and *atom/mpiio* styles (etc) to
be inter-changeable. The one exception is how the filename is
specified for the MPI-IO styles, as explained below.
.. warning::
The MPIIO package is currently unmaintained and has become
unreliable. Use with caution.
The precision of values output to text-based dump files can be
controlled by the :doc:`dump_modify format <dump_modify>` command and
its options.
@ -275,10 +283,11 @@ This bounding box is convenient for many visualization programs. The
meaning of the 6 character flags for "xx yy zz" is the same as above.
Note that the first two numbers on each line are now xlo_bound instead
of xlo, etc, since they represent a bounding box. See the :doc:`Howto triclinic <Howto_triclinic>` page for a geometric description
of triclinic boxes, as defined by LAMMPS, simple formulas for how the
6 bounding box extents (xlo_bound,xhi_bound,etc) are calculated from
the triclinic parameters, and how to transform those parameters to and
of xlo, etc, since they represent a bounding box. See the :doc:`Howto
triclinic <Howto_triclinic>` page for a geometric description of
triclinic boxes, as defined by LAMMPS, simple formulas for how the 6
bounding box extents (xlo_bound,xhi_bound,etc) are calculated from the
triclinic parameters, and how to transform those parameters to and
from other commonly used triclinic representations.
The "ITEM: ATOMS" line in each snapshot lists column descriptors for
@ -310,23 +319,24 @@ written to the dump file. This local data is typically calculated by
each processor based on the atoms it owns, but there may be zero or
more entities per atom, e.g. a list of bond distances. An explanation
of the possible dump local attributes is given below. Note that by
using input from the :doc:`compute property/local <compute_property_local>` command with dump local,
it is possible to generate information on bonds, angles, etc that can
be cut and pasted directly into a data file read by the
:doc:`read_data <read_data>` command.
using input from the :doc:`compute property/local
<compute_property_local>` command with dump local, it is possible to
generate information on bonds, angles, etc that can be cut and pasted
directly into a data file read by the :doc:`read_data <read_data>`
command.
Style *cfg* has the same command syntax as style *custom* and writes
extended CFG format files, as used by the
`AtomEye <http://li.mit.edu/Archive/Graphics/A/>`_ visualization
package. Since the extended CFG format uses a single snapshot of the
system per file, a wildcard "\*" must be included in the filename, as
discussed below. The list of atom attributes for style *cfg* must
begin with either "mass type xs ys zs" or "mass type xsu ysu zsu"
since these quantities are needed to write the CFG files in the
appropriate format (though the "mass" and "type" fields do not appear
explicitly in the file). Any remaining attributes will be stored as
"auxiliary properties" in the CFG files. Note that you will typically
want to use the :doc:`dump_modify element <dump_modify>` command with
extended CFG format files, as used by the `AtomEye
<http://li.mit.edu/Archive/Graphics/A/>`_ visualization package.
Since the extended CFG format uses a single snapshot of the system per
file, a wildcard "\*" must be included in the filename, as discussed
below. The list of atom attributes for style *cfg* must begin with
either "mass type xs ys zs" or "mass type xsu ysu zsu" since these
quantities are needed to write the CFG files in the appropriate format
(though the "mass" and "type" fields do not appear explicitly in the
file). Any remaining attributes will be stored as "auxiliary
properties" in the CFG files. Note that you will typically want to
use the :doc:`dump_modify element <dump_modify>` command with
CFG-formatted files, to associate element names with atom types, so
that AtomEye can render atoms appropriately. When unwrapped
coordinates *xsu*, *ysu*, and *zsu* are requested, the nominal AtomEye
@ -377,6 +387,70 @@ from using the (numerical) atom type to an element name (or some
other label). This will help many visualization programs to guess
bonds and colors.
Dump style *yaml* has the same command syntax as style *custom* and
writes YAML format files that can be easily parsed by a variety of data
processing tools and programming languages. Each timestep will be
written as a YAML "document" (i.e. starts with "---" and ends with
"..."). The style supports writing one file per timestep through the
"\*" wildcard but not multi-processor outputs with the "%" token in the
filename. In addition to per-atom data, :doc:`thermo <thermo>` data can
be included in the *yaml* style dump file using the :doc:`dump_modify
thermo yes <dump_modify>`. The data included in the dump file uses the
"thermo" tag and is otherwise identical to data specified by the
:doc:`thermo_style <thermo_style>` command.
Below is an example for a YAML format dump created by the following commands.
.. code-block:: LAMMPS
dump out all yaml 100 dump.yaml id type x y z vx vy vz ix iy iz
dump_modify out time yes units yes thermo yes format 1 %5d format "% 10.6e"
The tags "time", "units", and "thermo" are optional and enabled by the
dump_modify command. The list under the "box" tag has 3 lines for
orthogonal boxes and 4 lines with triclinic boxes, where the first 3 are
the box boundaries and the 4th the three tilt factors (xy, xz, yz). The
"thermo" data follows the format of the *yaml* thermo style. The
"keywords" tag lists the per-atom properties contained in the "data"
columns, which contain a list with one line per atom. The keywords may
be renamed using the dump_modify command same as for the *custom* dump
style.
.. code-block:: yaml
---
timestep: 0
units: lj
time: 0
natoms: 4000
boundary: [ p, p, p, p, p, p, ]
thermo:
- keywords: [ Step, Temp, E_pair, E_mol, TotEng, Press, ]
- data: [ 0, 0, -27093.472213010766, 0, 0, 0, ]
box:
- [ 0, 16.795961913825074 ]
- [ 0, 16.795961913825074 ]
- [ 0, 16.795961913825074 ]
- [ 0, 0, 0 ]
keywords: [ id, type, x, y, z, vx, vy, vz, ix, iy, iz, ]
data:
- [ 1 , 1 , 0.000000e+00 , 0.000000e+00 , 0.000000e+00 , -1.841579e-01 , -9.710036e-01 , -2.934617e+00 , 0 , 0 , 0, ]
- [ 2 , 1 , 8.397981e-01 , 8.397981e-01 , 0.000000e+00 , -1.799591e+00 , 2.127197e+00 , 2.298572e+00 , 0 , 0 , 0, ]
- [ 3 , 1 , 8.397981e-01 , 0.000000e+00 , 8.397981e-01 , -1.807682e+00 , -9.585130e-01 , 1.605884e+00 , 0 , 0 , 0, ]
[...]
...
---
timestep: 100
units: lj
time: 0.5
[...]
...
----------
Note that *atom*, *custom*, *dcd*, *xtc*, and *xyz* style dump files
can be read directly by `VMD <http://www.ks.uiuc.edu/Research/vmd>`_, a
popular molecular viewing program.
@ -418,9 +492,9 @@ If a "%" character appears in the filename, then each of P processors
writes a portion of the dump file, and the "%" character is replaced
with the processor ID from 0 to P-1. For example, tmp.dump.% becomes
tmp.dump.0, tmp.dump.1, ... tmp.dump.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*, and *xyz* styles.
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*, and *yaml* styles.
By default, P = the number of processors meaning one file per
processor, but P can be set to a smaller value via the *nfile* or
@ -452,6 +526,11 @@ use the :doc:`read_dump <read_dump>` command or perform other
post-processing, just as if the dump file was not written using
MPI-IO.
.. warning::
The MPIIO package is currently unmaintained and has become
unreliable. Use with caution.
Note that MPI-IO dump files are one large file which all processors
write to. You thus cannot use the "%" wildcard character described
above in the filename since that specifies generation of multiple
@ -708,8 +787,9 @@ are part of the MPIIO package. They are only enabled if LAMMPS was
built with that package. See the :doc:`Build package <Build_package>`
doc page for more info.
The *xtc* style is part of the MISC package. It is 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.
Related commands
""""""""""""""""

14
doc/src/dump_adios.rst
View File

@ -35,13 +35,21 @@ Examples
Description
"""""""""""
Dump a snapshot of atom coordinates every N timesteps in the
`ADIOS <adios_>`_ based "BP" file format, or using different I/O solutions in ADIOS,
to a stream that can be read on-line by another program.
Dump a snapshot of atom coordinates every N timesteps in the `ADIOS
<adios_>`_ based "BP" file format, or using different I/O solutions in
ADIOS, to a stream that can be read on-line by another program.
ADIOS-BP files are binary, portable and self-describing.
.. _adios: https://github.com/ornladios/ADIOS2
.. note::
To be able to use ADIOS, a file ``adios2_config.xml`` with specific
configuration settings is expected in the current working directory.
If the file is not present, LAMMPS will try to create a minimal
default file. Please refer to the ADIOS documentation for details on
how to adjust this file for optimal performance and desired features.
**Use from write_dump:**
It is possible to use these dump styles with the

202
doc/src/dump_modify.rst
View File

@ -17,14 +17,19 @@ Syntax
* one or more keyword/value pairs may be appended
* these keywords apply to various dump styles
* keyword = *append* or *at* or *buffer* or *delay* or *element* or *every* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
* keyword = *append* or *at* or *balance* or *buffer* or *delay* or *element* or *every* or *every/time* or *fileper* or *first* or *flush* or *format* or *header* or *image* or *label* or *maxfiles* or *nfile* or *pad* or *pbc* or *precision* or *region* or *refresh* or *scale* or *sfactor* or *sort* or *tfactor* or *thermo* or *thresh* or *time* or *units* or *unwrap*
.. parsed-literal::
*append* arg = *yes* or *no*
*at* arg = N
N = index of frame written upon first dump
*balance* arg = *yes* or *no*
*buffer* arg = *yes* or *no*
*colname* values = ID string, or *default*
string = new column header name
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a custom dump keyword or reference to compute, fix, property or variable.
*delay* arg = Dstep
Dstep = delay output until this timestep
*element* args = E1 E2 ... EN, where N = # of atom types
@ -32,13 +37,17 @@ Syntax
*every* arg = N
N = dump every this many timesteps
N can be a variable (see below)
*every/time* arg = Delta
Delta = dump every this interval in simulation time (time units)
Delta can be a variable (see below)
*fileper* arg = Np
Np = write one file for every this many processors
*first* arg = *yes* or *no*
*flush* arg = *yes* or *no*
*format* args = *line* string, *int* string, *float* string, M string, or *none*
*format* args = *line* string, *int* string, *float* string, ID string, or *none*
string = C-style format string
M = integer from 1 to N, where N = # of per-atom quantities being output
ID = integer from 1 to N, or integer from -1 to -N, where N = # of quantities being output
*or* a custom dump keyword or reference to compute, fix, property or variable.
*header* arg = *yes* or *no*
*yes* to write the header
*no* to not write the header
@ -197,11 +206,19 @@ will be accepted.
----------
The *every* keyword changes the dump frequency originally specified by
the :doc:`dump <dump>` command to a new value. The every keyword can be
specified in one of two ways. It can be a numeric value in which case
it must be > 0. Or it can be an :doc:`equal-style variable <variable>`,
which should be specified as v_name, where name is the variable name.
The *every* keyword can be used with any dump style except the *dcd*
and *xtc* styles. It does two things. It specifies that the interval
between dump snapshots will be set in timesteps, which is the default
if the *every* or *every/time* keywords are not used. See the
*every/time* keyword for how to specify the interval in simulation
time, i.e. in time units of the :doc:`units <units>` command. The
*every* keyword also sets the interval value, which overrides the dump
frequency originally specified by the :doc:`dump <dump>` command.
The *every* keyword can be specified in one of two ways. It can be a
numeric value in which case it must be > 0. Or it can be an
:doc:`equal-style variable <variable>`, which should be specified as
v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to
determine the next timestep at which a dump snapshot will be written
@ -210,11 +227,12 @@ determine the next timestep, etc. Thus the variable should return
timestep values. See the stagger() and logfreq() and stride() math
functions for :doc:`equal-style variables <variable>`, as examples of
useful functions to use in this context. Other similar math functions
could easily be added as options for :doc:`equal-style variables <variable>`. Also see the next() function, which allows
use of a file-style variable which reads successive values from a
file, each time the variable is evaluated. Used with the *every*
keyword, if the file contains a list of ascending timesteps, you can
output snapshots whenever you wish.
could easily be added as options for :doc:`equal-style variables
<variable>`. Also see the next() function, which allows use of a
file-style variable which reads successive values from a file, each
time the variable is evaluated. Used with the *every* keyword, if the
file contains a list of ascending timesteps, you can output snapshots
whenever you wish.
Note that when using the variable option with the *every* keyword, you
need to use the *first* option if you want an initial snapshot written
@ -255,14 +273,103 @@ in file tmp.times:
----------
The *every/time* keyword can be used with any dump style except the
*dcd* and *xtc* styles. It does two things. It specifies that the
interval between dump snapshots will be set in simulation time,
i.e. in time units of the :doc:`units <units>` command. This can be
useful when the timestep size varies during a simulation run, e.g. by
use of the :doc:`fix dt/reset <fix_dt_reset>` command. The default is
to specify the interval in timesteps; see the *every* keyword. The
*every/time* command also sets the interval value.
.. note::
If you wish dump styles *atom*, *custom*, *local*, or *xyz* to
include the simulation time as a field in the header portion of
each snapshot, you also need to use the dump_modify *time* keyword
with a setting of *yes*. See its documentation below.
Note that since snapshots are output on simulation steps, each
snapshot will be written on the first timestep whose associated
simulation time is >= the exact snapshot time value.
As with the *every* option, the *Delta* value can be specified in one
of two ways. It can be a numeric value in which case it must be >
0.0. Or it can be an :doc:`equal-style variable <variable>`, which
should be specified as v_name, where name is the variable name.
In this case, the variable is evaluated at the beginning of a run to
determine the next simulation time at which a dump snapshot will be
written out. On that timestep the variable will be evaluated again to
determine the next simulation time, etc. Thus the variable should
return values in time units. Note the current timestep or simulation
time can be used in an :doc:`equal-style variables <variable>` since
they are both thermodynamic keywords. Also see the next() function,
which allows use of a file-style variable which reads successive
values from a file, each time the variable is evaluated. Used with
the *every/time* keyword, if the file contains a list of ascending
simulation times, you can output snapshots whenever you wish.
Note that when using the variable option with the *every/time*
keyword, you need to use the *first* option if you want an initial
snapshot written to the dump file. The *every/time* keyword cannot be
used with the dump *dcd* style.
For example, the following commands will write snapshots at successive
simulation times which grow by a factor of 1.5 with each interval.
The dt value used in the variable is to avoid a zero result when the
initial simulation time is 0.0.
.. code-block:: LAMMPS
variable increase equal 1.5*(time+dt)
dump 1 all atom 100 tmp.dump
dump_modify 1 every/time v_increase first yes
The following commands would write snapshots at the times listed in
file tmp.times:
.. code-block:: LAMMPS
variable f file tmp.times
variable s equal next(f)
dump 1 all atom 100 tmp.dump
dump_modify 1 every/time v_s
.. note::
When using a file-style variable with the *every/time* keyword, the
file of timesteps must list a first time that is beyond the time
associated with the current timestep (e.g. it cannot be 0.0). And
it must list one or more times beyond the length of the run you
perform. This is because the dump command will generate an error
if the next time it reads from the file is not a value greater than
the current time. Thus if you wanted output at times 0,15,100 of a
run of length 100 in simulation time, the file should contain the
values 15,100,101 and you should also use the dump_modify first
command. Any final value > 100 could be used in place of 101.
----------
The *first* keyword determines whether a dump snapshot is written on
the very first timestep after the dump command is invoked. This will
always occur if the current timestep is a multiple of N, the frequency
specified in the :doc:`dump <dump>` command, including timestep 0. But
if this is not the case, a dump snapshot will only be written if the
setting of this keyword is *yes*\ . If it is *no*, which is the
always occur if the current timestep is a multiple of $N$, the
frequency specified in the :doc:`dump <dump>` command or
:doc:`dump_modify every <dump_modify>` command, including timestep 0.
It will also always occur if the current simulation time is a multiple
of *Delta*, the time interval specified in the doc:`dump_modify
every/time <dump_modify>` command.
But if this is not the case, a dump snapshot will only be written if
the setting of this keyword is *yes*\ . If it is *no*, which is the
default, then it will not be written.
Note that if the argument to the :doc:`dump_modify every
<dump_modify>` doc:`dump_modify every/time <dump_modify>` commands is
a variable and not a numeric value, then specifying *first yes* is the
only way to write a dump snapshot on the first timestep after the dump
command is invoked.
----------
The *flush* keyword determines whether a flush operation is invoked
@ -273,6 +380,29 @@ performed with dump style *xtc*\ .
----------
The *colname* keyword can be used to change the default header keyword
for dump styles: *atom*, *custom*, and *cfg* and their compressed, ADIOS,
and MPIIO variants. The setting for *ID string* replaces the default
text with the provided string. *ID* can be a positive integer when it
represents the column number counting from the left, a negative integer
when it represents the column number from the right (i.e. -1 is the last
column/keyword), or a custom dump keyword (or compute, fix, property, or
variable reference) and then it replaces the string for that specific
keyword. For *atom* dump styles only the keywords "id", "type", "x",
"y", "z", "ix", "iy", "iz" can be accessed via string regardless of
whether scaled or unwrapped coordinates were enabled or disabled, and
it always assumes 8 columns for indexing regardless of whether image
flags are enabled or not. For dump style *cfg* only the "auxiliary"
keywords (6th or later keyword) may be changed and the column indexing
considers only them (i.e. the 6th keyword is the the 1st column).
The *colname* keyword can be used multiple times. If multiple *colname*
settings refer to the same keyword, the last setting has precedence. A
setting of *default* clears all previous settings, reverting all values
to their default names.
----------
The *format* keyword can be used to change the default numeric format output
by the text-based dump styles: *atom*, *local*, *custom*, *cfg*, and
*xyz* styles, and their MPIIO variants. Only the *line* or *none*
@ -342,10 +472,11 @@ The *fileper* keyword is documented below with the *nfile* keyword.
----------
The *header* keyword toggles whether the dump file will include a header.
Excluding a header will reduce the size of the dump file for fixes such as
:doc:`fix pair/tracker <fix_pair_tracker>` which do not require the information
typically written to the header.
The *header* keyword toggles whether the dump file will include a
header. Excluding a header will reduce the size of the dump file for
data produced by :doc:`pair tracker <pair_tracker>` or
:doc:`bpm bond styles <Howto_bpm>` which may not require the
information typically written to the header.
----------
@ -561,9 +692,19 @@ The dump *local* style cannot be sorted by atom ID, since there are
typically multiple lines of output per atom. Some dump styles, such
as *dcd* and *xtc*, require sorting by atom ID to format the output
file correctly. If multiple processors are writing the dump file, via
the "%" wildcard in the dump filename, then sorting cannot be
the "%" wildcard in the dump filename and the *nfile* or *fileper*
keywords are set to non-default values (i.e. the number of dump file
pieces is not equal to the number of procs), then sorting cannot be
performed.
In a parallel run, the per-processor dump file pieces can have
significant imbalance in number of lines of per-atom info. The *balance*
keyword determines whether the number of lines in each processor
snapshot are balanced to be nearly the same. A balance value of *no*
means no balancing will be done, while *yes* means balancing will be
performed. This balancing preserves dump sorting order. For a serial
run, this option is ignored since the output is already balanced.
.. note::
Unless it is required by the dump style, sorting dump file
@ -572,8 +713,8 @@ performed.
----------
The *thermo* keyword only applies the dump *netcdf* style. It
triggers writing of :doc:`thermo <thermo>` information to the dump file
The *thermo* keyword only applies the dump styles *netcdf* and *yaml*.
It triggers writing of :doc:`thermo <thermo>` information to the dump file
alongside per-atom data. The values included in the dump file are
identical to the values specified by :doc:`thermo_style <thermo_style>`.
@ -639,16 +780,20 @@ threshold criterion is met. Otherwise it is not met.
----------
The *time* keyword only applies to the dump *atom*, *custom*, and
*local* styles (and their COMPRESS package versions *atom/gz*,
*custom/gz* and *local/gz*\ ). If set to *yes*, each frame will will
contain two extra lines before the "ITEM: TIMESTEP" entry:
The *time* keyword only applies to the dump *atom*, *custom*, *local*,
and *xyz* styles (and their COMPRESS package versions *atom/gz*,
*custom/gz* and *local/gz*\ ). For the first 3 styles, if set to
*yes*, each frame will will contain two extra lines before the "ITEM:
TIMESTEP" entry:
.. parsed-literal::
ITEM: TIME
\<elapsed time\>
For the *xyz* style, the simulation time is included on the same line
as the timestep value.
This will output the current elapsed simulation time in current
time units equivalent to the :doc:`thermo keyword <thermo_style>` *time*\ .
This is to simplify post-processing of trajectories using a variable time
@ -725,6 +870,7 @@ Default
The option defaults are
* append = no
* balance = no
* buffer = yes for dump styles *atom*, *custom*, *loca*, and *xyz*
* element = "C" for every atom type
* every = whatever it was set to via the :doc:`dump <dump>` command

9
doc/src/dynamical_matrix.rst
View File

@ -1,8 +1,11 @@
.. index:: dynamical_matrix
.. index:: dynamical_matrix/kk
dynamical_matrix command
========================
Accelerator Variants: dynamical_matrix/kk
Syntax
""""""
@ -56,6 +59,12 @@ If the style eskm is selected, the dynamical matrix will be in units of
inverse squared femtoseconds. These units will then conveniently leave
frequencies in THz.
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""

12
doc/src/fix.rst
View File

@ -194,10 +194,10 @@ accelerated styles exist.
* :doc:`bond/swap <fix_bond_swap>` - Monte Carlo bond swapping
* :doc:`box/relax <fix_box_relax>` - relax box size during energy minimization
* :doc:`charge/regulation <fix_charge_regulation>` - Monte Carlo sampling of charge regulation
* :doc:`client/md <fix_client_md>` - MD client for client/server simulations
* :doc:`cmap <fix_cmap>` - enables CMAP cross-terms of the CHARMM force field
* :doc:`colvars <fix_colvars>` - interface to the collective variables "Colvars" library
* :doc:`controller <fix_controller>` - apply control loop feedback mechanism
* :doc:`damping/cundall <fix_damping_cundall>` - Cundall non-viscous damping for granular simulations
* :doc:`deform <fix_deform>` - change the simulation box size/shape
* :doc:`deposit <fix_deposit>` - add new atoms above a surface
* :doc:`dpd/energy <fix_dpd_energy>` - constant energy dissipative particle dynamics
@ -240,12 +240,10 @@ accelerated styles exist.
* :doc:`latte <fix_latte>` - wrapper on LATTE density-functional tight-binding code
* :doc:`lb/fluid <fix_lb_fluid>` -
* :doc:`lb/momentum <fix_lb_momentum>` -
* :doc:`lb/pc <fix_lb_pc>` -
* :doc:`lb/rigid/pc/sphere <fix_lb_rigid_pc_sphere>` -
* :doc:`lb/viscous <fix_lb_viscous>` -
* :doc:`lineforce <fix_lineforce>` - constrain atoms to move in a line
* :doc:`manifoldforce <fix_manifoldforce>` - restrain atoms to a manifold during minimization
* :doc:`mdi/engine <fix_mdi_engine>` - connect LAMMPS to external programs via the MolSSI Driver Interface (MDI)
* :doc:`mdi/aimd <fix_mdi_aimd>` - LAMMPS operates as driver for ab initio MD (AIMD) via the MolSSI Driver Interface (MDI)
* :doc:`meso/move <fix_meso_move>` - move mesoscopic SPH/SDPD particles in a prescribed fashion
* :doc:`mol/swap <fix_mol_swap>` - Monte Carlo atom type swapping with a molecule
* :doc:`momentum <fix_momentum>` - zero the linear and/or angular momentum of a group of atoms
@ -271,7 +269,8 @@ accelerated styles exist.
* :doc:`npt/eff <fix_nh_eff>` - NPT for nuclei and electrons in the electron force field model
* :doc:`npt/sphere <fix_npt_sphere>` - NPT for spherical particles
* :doc:`npt/uef <fix_nh_uef>` - NPT style time integration with diagonal flow
* :doc:`numdiff <fix_numdiff>` - compute derivatives of per-atom data from finite differences
* :doc:`numdiff <fix_numdiff>` - numerically approximate atomic forces using finite energy differences
* :doc:`numdiff/virial <fix_numdiff_virial>` - numerically approximate virial stress tensor using finite energy differences
* :doc:`nve <fix_nve>` - constant NVE time integration
* :doc:`nve/asphere <fix_nve_asphere>` - NVE for aspherical particles
* :doc:`nve/asphere/noforce <fix_nve_asphere_noforce>` - NVE for aspherical particles without forces
@ -285,6 +284,7 @@ accelerated styles exist.
* :doc:`nve/manifold/rattle <fix_nve_manifold_rattle>` -
* :doc:`nve/noforce <fix_nve_noforce>` - NVE without forces (v only)
* :doc:`nve/sphere <fix_nve_sphere>` - NVE for spherical particles
* :doc:`nve/bpm/sphere <fix_nve_bpm_sphere>` - NVE for spherical particles used in the BPM package
* :doc:`nve/spin <fix_nve_spin>` - NVE for a spin or spin-lattice system
* :doc:`nve/tri <fix_nve_tri>` - NVE for triangles
* :doc:`nvk <fix_nvk>` - constant kinetic energy time integration
@ -302,7 +302,6 @@ accelerated styles exist.
* :doc:`orient/fcc <fix_orient>` - add grain boundary migration force for FCC
* :doc:`orient/eco <fix_orient_eco>` - add generalized grain boundary migration force
* :doc:`pafi <fix_pafi>` - constrained force averages on hyper-planes to compute free energies (PAFI)
* :doc:`pair/tracker <fix_pair_tracker>` - track properties of pairwise interactions
* :doc:`phonon <fix_phonon>` - calculate dynamical matrix from MD simulations
* :doc:`pimd <fix_pimd>` - Feynman path integral molecular dynamics
* :doc:`planeforce <fix_planeforce>` - constrain atoms to move in a plane
@ -387,6 +386,7 @@ accelerated styles exist.
* :doc:`vector <fix_vector>` - accumulate a global vector every N timesteps
* :doc:`viscosity <fix_viscosity>` - Muller-Plathe momentum exchange for viscosity calculation
* :doc:`viscous <fix_viscous>` - viscous damping for granular simulations
* :doc:`viscous/sphere <fix_viscous_sphere>` - viscous damping on angular velocity for granular simulations
* :doc:`wall/body/polygon <fix_wall_body_polygon>` -
* :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>` -
* :doc:`wall/colloid <fix_wall>` - Lennard-Jones wall interacting with finite-size particles

2
doc/src/fix_accelerate_cos.rst
View File

@ -13,7 +13,7 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* accelerate/cos = style name of this fix command
* value = amplitude of acceleration (in unit of force/mass)
* value = amplitude of acceleration (in unit of velocity/time)
Examples

53
doc/src/fix_acks2_reaxff.rst
View File

@ -19,6 +19,12 @@ Syntax
* cutlo,cuthi = lo and hi cutoff for Taper radius
* tolerance = precision to which charges will be equilibrated
* params = reaxff or a filename
* one or more keywords or keyword/value pairs may be appended
.. parsed-literal::
keyword = *maxiter*
*maxiter* N = limit the number of iterations to *N*
Examples
""""""""
@ -26,7 +32,7 @@ Examples
.. code-block:: LAMMPS
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 reaxff
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 param.acks2
fix 1 all acks2/reaxff 1 0.0 10.0 1.0e-6 param.acks2 maxiter 500
Description
"""""""""""
@ -44,14 +50,14 @@ the charge equilibration performed by fix acks2/reaxff, see the
The ACKS2 method minimizes the electrostatic energy of the system by
adjusting the partial charge on individual atoms based on interactions
with their neighbors. It requires some parameters for each atom type.
with their neighbors. It requires some parameters for each atom type.
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 performing QeQ with a non-ReaxFF potential. The lines
should be formatted as follows:
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.
The lines should be formatted as follows:
.. parsed-literal::
@ -67,13 +73,25 @@ ReaxFF potential file, except that eta is defined here as twice the eta
value in the ReaxFF file. Note that unlike the rest of LAMMPS, the units
of this fix are hard-coded to be A, eV, and electronic charge.
**Restart, fix_modify, output, run start/stop, minimize info:**
The optional *maxiter* keyword allows changing the max number
of iterations in the linear solver. The default value is 200.
.. 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>`. No global scalar or vector 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.
<restart>`. This fix computes a global scalar (the number of
iterations) 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 invoked during :doc:`energy minimization <minimize>`.
@ -86,12 +104,12 @@ 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>` doc page for more info.
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 images of the same atom. Hence, it should not be used for
periodic cell dimensions less than 10 angstroms.
This fix may be used in combination with :doc:`fix efield <fix_efield>`
@ -105,7 +123,10 @@ Related commands
:doc:`pair_style reaxff <pair_reaxff>`, :doc:`fix qeq/reaxff <fix_qeq_reaxff>`
**Default:** none
Default
"""""""
maxiter 200
----------

87
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 *kspace* or *atom*
* attribute = *pair* or *bond* or *angle* or *kspace* or *atom*
.. parsed-literal::
@ -28,11 +28,16 @@ Syntax
bparam = parameter to adapt over time
I = type bond to set parameter for
v_name = variable with name that calculates value of bparam
*angle* args = astyle aparam I v_name
astyle = angle style name, e.g. harmonic
aparam = parameter to adapt over time
I = type angle to set parameter for
v_name = variable with name that calculates value of aparam
*kspace* arg = v_name
v_name = variable with name that calculates scale factor on K-space terms
*atom* args = aparam v_name
aparam = parameter to adapt over time
v_name = variable with name that calculates value of aparam
*atom* args = atomparam v_name
atomparam = parameter to adapt over time
v_name = variable with name that calculates value of atomparam
* zero or more keyword/value pairs may be appended
* keyword = *scale* or *reset* or *mass*
@ -283,30 +288,62 @@ operates. The only difference is that now a bond coefficient for a
given bond type is adapted.
A wild-card asterisk can be used in place of or in conjunction with
the bond type argument to set the coefficients for multiple bond types.
This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N = the number of
atom types, then an asterisk with no numeric values means all types
from 1 to N. A leading asterisk means all types from 1 to n (inclusive).
A trailing asterisk means all types from n to N (inclusive). A middle
asterisk means all types from m to n (inclusive).
the bond type argument to set the coefficients for multiple bond
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N =
the number of bond types, then an asterisk with no numeric values
means all types from 1 to N. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
Currently *bond* does not support bond_style hybrid nor bond_style
hybrid/overlay as bond styles. The only bonds that currently are
working with fix_adapt are
hybrid/overlay as bond styles. The bond styles that currently work
with fix_adapt are
+------------------------------------+-------+------------+
| :doc:`class2 <bond_class2>` | r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`fene <bond_fene>` | k, r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`gromos <bond_gromos>` | k, r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`morse <bond_morse>` | r0 | type bonds |
+------------------------------------+-------+------------+
| :doc:`nonlinear <bond_nonlinear>` | r0 | type bonds |
+------------------------------------+-------+------------+
+------------------------------------+-------+-----------------+
| :doc:`class2 <bond_class2>` | r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`fene <bond_fene>` | k,r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`fene/nm <bond_fene>` | k,r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`gromos <bond_gromos>` | k,r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`harmonic <bond_harmonic>` | k,r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`morse <bond_morse>` | r0 | type bonds |
+------------------------------------+-------+-----------------+
| :doc:`nonlinear <bond_nonlinear>` | epsilon,r0 | type bonds |
+------------------------------------+-------+-----------------+
----------
The *angle* keyword uses the specified variable to change the value of
an angle coefficient over time, very similar to how the *pair* keyword
operates. The only difference is that now an angle coefficient for a
given angle type is adapted.
A wild-card asterisk can be used in place of or in conjunction with
the angle type argument to set the coefficients for multiple angle
types. This takes the form "\*" or "\*n" or "n\*" or "m\*n". If N =
the number of angle types, then an asterisk with no numeric values
means all types from 1 to N. A leading asterisk means all types from
1 to n (inclusive). A trailing asterisk means all types from n to N
(inclusive). A middle asterisk means all types from m to n
(inclusive).
Currently *angle* does not support angle_style hybrid nor angle_style
hybrid/overlay as angle styles. The angle styles that currently work
with fix_adapt are
+------------------------------------+-------+-----------------+
| :doc:`harmonic <angle_harmonic>` | k,theta0 | type angles |
+------------------------------------+-------+-----------------+
| :doc:`cosine <angle_cosine>` | k | type angles |
+------------------------------------+-------+-----------------+
Note that internally, theta0 is stored in radians, so the variable
this fix uses to reset theta0 needs to generate values in radians.
----------

2
doc/src/fix_addtorque.rst
View File

@ -99,7 +99,7 @@ invoked by the :doc:`minimize <minimize>` command.
Restrictions
""""""""""""
This fix is part of the MISC package. It is only enabled if
This fix is part of the EXTRA-FIX package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.

40
doc/src/fix_atc.rst
View File

@ -266,50 +266,50 @@ For detailed exposition of the theory and algorithms please see:
.. _Wagner:
**(Wagner)** Wagner, GJ; Jones, RE; Templeton, JA; Parks, MA, "An
atomistic-to-continuum coupling method for heat transfer in solids."
Special Issue of Computer Methods and Applied Mechanics (2008)
197:3351.
atomistic-to-continuum coupling method for heat transfer in solids."
Special Issue of Computer Methods and Applied Mechanics (2008)
197:3351.
.. _Zimmeman2004:
**(Zimmerman2004)** Zimmerman, JA; Webb, EB; Hoyt, JJ;. Jones, RE;
Klein, PA; Bammann, DJ, "Calculation of stress in atomistic
simulation." Special Issue of Modelling and Simulation in Materials
Science and Engineering (2004), 12:S319.
Klein, PA; Bammann, DJ, "Calculation of stress in atomistic
simulation." Special Issue of Modelling and Simulation in Materials
Science and Engineering (2004), 12:S319.
.. _Zimmerman2010:
**(Zimmerman2010)** Zimmerman, JA; Jones, RE; Templeton, JA, "A
material frame approach for evaluating continuum variables in
atomistic simulations." Journal of Computational Physics (2010),
229:2364.
material frame approach for evaluating continuum variables in
atomistic simulations." Journal of Computational Physics (2010),
229:2364.
.. _Templeton2010:
**(Templeton2010)** Templeton, JA; Jones, RE; Wagner, GJ, "Application
of a field-based method to spatially varying thermal transport
problems in molecular dynamics." Modelling and Simulation in
Materials Science and Engineering (2010), 18:085007.
of a field-based method to spatially varying thermal transport
problems in molecular dynamics." Modelling and Simulation in
Materials Science and Engineering (2010), 18:085007.
.. _Jones:
**(Jones)** Jones, RE; Templeton, JA; Wagner, GJ; Olmsted, D; Modine,
JA, "Electron transport enhanced molecular dynamics for metals and
semi-metals." International Journal for Numerical Methods in
Engineering (2010), 83:940.
JA, "Electron transport enhanced molecular dynamics for metals and
semi-metals." International Journal for Numerical Methods in
Engineering (2010), 83:940.
.. _Templeton2011:
**(Templeton2011)** Templeton, JA; Jones, RE; Lee, JW; Zimmerman, JA;
Wong, BM, "A long-range electric field solver for molecular dynamics
based on atomistic-to-continuum modeling." Journal of Chemical Theory
and Computation (2011), 7:1736.
Wong, BM, "A long-range electric field solver for molecular dynamics
based on atomistic-to-continuum modeling." Journal of Chemical Theory
and Computation (2011), 7:1736.
.. _Mandadapu:
**(Mandadapu)** Mandadapu, KK; Templeton, JA; Lee, JW, "Polarization
as a field variable from molecular dynamics simulations." Journal of
Chemical Physics (2013), 139:054115.
as a field variable from molecular dynamics simulations." Journal of
Chemical Physics (2013), 139:054115.
Please refer to the standard finite element (FE) texts, e.g. T.J.R
Hughes " The finite element method ", Dover 2003, for the basics of FE

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