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

Merge branch 'develop' of github.com:lammps/lammps into kk_occupancy

Browse Source
This commit is contained in:
Stan Gerald Moore
2023-01-20 07:32:46 -07:00
parent 8644a6601d 0a5f97c327
commit 13d4344999
1157 changed files with 147296 additions and 82053 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/Build_basics.rst
View File

@ -276,7 +276,7 @@ LAMMPS.
Parallel build (see ``src/MAKE/Makefile.mpi``):
.. code-block:: bash
.. code-block:: make
CC = mpicxx
CCFLAGS = -g -O3
@ -296,7 +296,7 @@ LAMMPS.
If compilation stops with a message like the following:
.. code-block::
.. code-block:: output
g++ -g -O3 -DLAMMPS_GZIP -DLAMMPS_MEMALIGN=64 -I../STUBS -c ../main.cpp
In file included from ../pointers.h:24:0,

82
doc/src/Build_development.rst
View File

@ -154,32 +154,48 @@ for implementing the tests.
framework are more strict than for the main part of LAMMPS. For
example the default GNU C++ and Fortran compilers of RHEL/CentOS 7.x
(version 4.8.x) are not sufficient. The CMake configuration will try
to detect compatible versions and either skip incompatible tests or
stop with an error.
to detect incompatible versions and either skip incompatible tests or
stop with an error. Also the number of tests will depend on
installed LAMMPS packages, development environment, operating system,
and configuration settings.
After compilation is complete, the unit testing is started in the build
folder using the ``ctest`` command, which is part of the CMake software.
The output of this command will be looking something like this::
The output of this command will be looking something like this:
[...]$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: MolPairStyle:hybrid-overlay
1/109 Test #1: MolPairStyle:hybrid-overlay ......... Passed 0.02 sec
Start 2: MolPairStyle:hybrid
2/109 Test #2: MolPairStyle:hybrid ................. Passed 0.01 sec
Start 3: MolPairStyle:lj_class2
[...]
Start 107: PotentialFileReader
107/109 Test #107: PotentialFileReader ................ Passed 0.04 sec
Start 108: EIMPotentialFileReader
108/109 Test #108: EIMPotentialFileReader ............. Passed 0.03 sec
Start 109: TestSimpleCommands
109/109 Test #109: TestSimpleCommands ................. Passed 0.02 sec
.. code-block:: console
100% tests passed, 0 tests failed out of 26
$ ctest
Test project /home/akohlmey/compile/lammps/build-testing
Start 1: RunLammps
1/563 Test #1: RunLammps .......................................... Passed 0.28 sec
Start 2: HelpMessage
2/563 Test #2: HelpMessage ........................................ Passed 0.06 sec
Start 3: InvalidFlag
3/563 Test #3: InvalidFlag ........................................ Passed 0.06 sec
Start 4: Tokenizer
4/563 Test #4: Tokenizer .......................................... Passed 0.05 sec
Start 5: MemPool
5/563 Test #5: MemPool ............................................ Passed 0.05 sec
Start 6: ArgUtils
6/563 Test #6: ArgUtils ........................................... Passed 0.05 sec
[...]
Start 561: ImproperStyle:zero
561/563 Test #561: ImproperStyle:zero ................................. Passed 0.07 sec
Start 562: TestMliapPyUnified
562/563 Test #562: TestMliapPyUnified ................................. Passed 0.16 sec
Start 563: TestPairList
563/563 Test #563: TestPairList ....................................... Passed 0.06 sec
Total Test time (real) = 25.57 sec
100% tests passed, 0 tests failed out of 563
Label Time Summary:
generated = 0.85 sec*proc (3 tests)
noWindows = 4.16 sec*proc (2 tests)
slow = 78.33 sec*proc (67 tests)
unstable = 28.23 sec*proc (34 tests)
Total Test time (real) = 132.34 sec
The ``ctest`` command has many options, the most important ones are:
@ -210,11 +226,13 @@ Fortran) and testing different aspects of the LAMMPS software and its features.
The tests will adapt to the compilation settings of LAMMPS, so that tests
will be skipped if prerequisite features are not available in LAMMPS.
.. note::
.. admonition:: Work in Progress
:class: note
The unit test framework was added in spring 2020 and is under active
development. The coverage is not complete and will be expanded over
time.
time. Preference is given to parts of the code base that are easy to
test or commonly used.
Tests for styles of the same kind of style (e.g. pair styles or bond
styles) are performed with the same test executable using different
@ -248,9 +266,9 @@ the CMake option ``-D BUILD_MPI=off`` can significantly speed up testing,
since this will skip the MPI initialization for each test run.
Below is an example command and output:
.. parsed-literal::
.. code-block:: console
[tests]$ test_pair_style mol-pair-lj_cut.yaml
$ test_pair_style mol-pair-lj_cut.yaml
[==========] Running 6 tests from 1 test suite.
[----------] Global test environment set-up.
[----------] 6 tests from PairStyle
@ -530,7 +548,7 @@ commands like the following:
.. code-block:: bash
$ clang-format -i some_file.cpp
clang-format -i some_file.cpp
The following target are available for both, GNU make and CMake:
@ -539,3 +557,19 @@ The following target are available for both, GNU make and CMake:
make format-src # apply clang-format to all files in src and the package folders
make format-tests # apply clang-format to all files in the unittest tree
----------
.. _gh-cli:
GitHub command line interface
-----------------------------
GitHub is developing a `tool for the command line
<https://cli.github.com>`_ that interacts with the GitHub website via a
command called ``gh``. This can be extremely convenient when working
with a Git repository hosted on GitHub (like LAMMPS). It is thus highly
recommended to install it when doing LAMMPS development.
The capabilities of the ``gh`` command is continually expanding, so
please see the documentation at https://cli.github.com/manual/

338
doc/src/Build_extras.rst
View File

@ -12,11 +12,11 @@ in addition to
- Traditional make
* - .. code-block:: bash
$ cmake -D PKG_NAME=yes
cmake -D PKG_NAME=yes
- .. code-block:: bash
- .. code-block:: console
$ make yes-name
make yes-name
as described on the :doc:`Build_package <Build_package>` page.
@ -28,13 +28,14 @@ You may need to tell LAMMPS where it is found on your system.
This is the list of packages that may require additional steps.
.. this list must be kept in sync with its counterpart in Build_package.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS <adios>`
* :ref:`ATC <atc>`
* :ref:`AWPMD <awpmd>`
* :ref:`COLVARS <colvars>`
* :ref:`COLVARS <colvar>`
* :ref:`COMPRESS <compress>`
* :ref:`ELECTRODE <electrode>`
* :ref:`GPU <gpu>`
@ -43,6 +44,7 @@ This is the list of packages that may require additional steps.
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
@ -150,7 +152,9 @@ CMake build
* sm_60 or sm_61 for Pascal (supported since CUDA 8)
* sm_70 for Volta (supported since CUDA 9)
* sm_75 for Turing (supported since CUDA 10)
* sm_80 for Ampere (supported since CUDA 11)
* sm_80 or sm_86 for Ampere (supported since CUDA 11, sm_86 since CUDA 11.1)
* sm_89 for Lovelace (supported since CUDA 11.8)
* sm_90 for Hopper (supported since CUDA 12.0)
A more detailed list can be found, for example,
at `Wikipedia's CUDA article <https://en.wikipedia.org/wiki/CUDA#GPUs_supported>`_
@ -241,10 +245,10 @@ script with the specified args:
.. code-block:: bash
$ make lib-gpu # print help message
$ make lib-gpu args="-b" # build GPU library with default Makefile.linux
$ make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
$ make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
make lib-gpu # print help message
make lib-gpu args="-b" # build GPU library with default Makefile.linux
make lib-gpu args="-m xk7 -p single -o xk7.single" # create new Makefile.xk7.single, altered for single-precision
make lib-gpu args="-m mpi -a sm_60 -p mixed -b" # build GPU library with mixed precision and P100 using other settings in Makefile.mpi
Note that this procedure starts with a Makefile.machine in lib/gpu, as
specified by the "-m" switch. For your convenience, machine makefiles
@ -357,13 +361,13 @@ minutes to hours) to build. Of course you only need to do that once.)
.. code-block:: bash
$ make lib-kim # print help message
$ make lib-kim args="-b " # (re-)install KIM API lib with only example models
$ make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
$ make lib-kim args="-b -a everything" # install KIM API lib with all models
$ make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
$ 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
make lib-kim # print help message
make lib-kim args="-b " # (re-)install KIM API lib with only example models
make lib-kim args="-b -a Glue_Ercolessi_Adams_Al__MO_324507536345_001" # ditto plus one model
make lib-kim args="-b -a everything" # install KIM API lib with all models
make lib-kim args="-n -a EAM_Dynamo_Ackland_W__MO_141627196590_002" # add one model or model driver
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
@ -375,7 +379,7 @@ minutes to hours) to build. Of course you only need to do that once.)
.. 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
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
@ -858,11 +862,11 @@ library.
.. code-block:: bash
$ make lib-latte # print help message
$ make lib-latte args="-b" # download and build in lib/latte/LATTE-master
$ make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
$ make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
make lib-latte # print help message
make lib-latte args="-b" # download and build in lib/latte/LATTE-master
make lib-latte args="-p $HOME/latte" # use existing LATTE installation in $HOME/latte
make lib-latte args="-b -m gfortran" # download and build in lib/latte and
# copy Makefile.lammps.gfortran to Makefile.lammps
Note that 3 symbolic (soft) links, ``includelink`` and ``liblink``
and ``filelink.o``, are created in ``lib/latte`` to point to
@ -873,6 +877,55 @@ library.
----------
.. _lepton:
LEPTON package
--------------
To build with this package, you must build the Lepton library which is
included in the LAMMPS source distribution in the ``lib/lepton`` folder.
.. tabs::
.. tab:: CMake build
This is the recommended build procedure for using Lepton in
LAMMPS. No additional settings are normally needed besides
``-D PKG_LEPTON=yes``.
On x86 hardware the Lepton library will also include a just-in-time
compiler for faster execution. This is auto detected but can
be explicitly disabled by setting ``-D LEPTON_ENABLE_JIT=no``
(or enabled by setting it to yes).
.. tab:: Traditional make
Before building LAMMPS, one must build the Lepton library in lib/lepton.
This can be done manually in the same folder by using or adapting
one of the provided Makefiles: for example, ``Makefile.serial`` for
the GNU C++ compiler, or ``Makefile.mpi`` for the MPI compiler wrapper.
The Lepton library is written in C++-11 and thus the C++ compiler
may need to be instructed to enable support for that.
In general, it is safer to use build setting consistent with the
rest of LAMMPS. This is best carried out from the LAMMPS src
directory using a command like these, which simply invokes the
``lib/lepton/Install.py`` script with the specified args:
.. code-block:: bash
make lib-lepton # print help message
make lib-lepton args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-lepton args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
The "machine" argument of the "-m" flag is used to find a
Makefile.machine to use as build recipe.
The build should produce a ``build`` folder and the library ``lib/lepton/liblmplepton.a``
----------
.. _mliap:
ML-IAP package
@ -961,12 +1014,12 @@ more details.
.. code-block:: bash
$ make lib-mscg # print help message
$ make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make serial"
$ make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make mpi"
$ make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
make lib-mscg # print help message
make lib-mscg args="-b -m serial" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make serial"
make lib-mscg args="-b -m mpi" # download and build in lib/mscg/MSCG-release-master
# with the settings compatible with "make mpi"
make lib-mscg args="-p /usr/local/mscg-release" # use the existing MS-CG installation in /usr/local/mscg-release
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``,
will be created in ``lib/mscg`` to point to the MS-CG
@ -1018,10 +1071,10 @@ POEMS package
.. code-block:: bash
$ make lib-poems # print help message
$ make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
$ make lib-poems args="-m icc" # build with Intel icc compiler
make lib-poems # print help message
make lib-poems args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-poems args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-poems args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/poems/libpoems.a`` and
``lib/poems/Makefile.lammps``. The latter is copied from an
@ -1107,10 +1160,10 @@ binary package provided by your operating system.
.. code-block:: bash
$ make lib-voronoi # print help message
$ make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
$ make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
$ make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
make lib-voronoi # print help message
make lib-voronoi args="-b" # download and build the default version in lib/voronoi/voro++-<version>
make lib-voronoi args="-p $HOME/voro++" # use existing Voro++ installation in $HOME/voro++
make lib-voronoi args="-b -v voro++0.4.6" # download and build the 0.4.6 version in lib/voronoi/voro++-0.4.6
Note that 2 symbolic (soft) links, ``includelink`` and
``liblink``, are created in lib/voronoi to point to the Voro++
@ -1151,13 +1204,13 @@ systems.
.. code-block:: bash
$ make yes-adios
make yes-adios
otherwise, set ADIOS2_DIR environment variable when turning on the package:
.. code-block:: bash
$ ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
ADIOS2_DIR=path make yes-adios # path is where ADIOS 2.x is installed
----------
@ -1186,10 +1239,10 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
$ make lib-atc # print help message
$ make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-atc args="-m icc" # build with Intel icc compiler
make lib-atc # print help message
make lib-atc args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-atc args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-atc args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/atc/libatc.a`` and
``lib/atc/Makefile.lammps``. The latter is copied from an
@ -1208,17 +1261,17 @@ The ATC package requires the MANYBODY package also be installed.
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU Fortran compiler
----------
.. _awpmd:
AWPMD package
------------------
-------------
.. tabs::
@ -1237,10 +1290,10 @@ AWPMD package
.. code-block:: bash
$ make lib-awpmd # print help message
$ make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-awpmd args="-m icc" # build with Intel icc compiler
make lib-awpmd # print help message
make lib-awpmd args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-awpmd args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-awpmd args="-m icc" # build with Intel icc compiler
The build should produce two files: ``lib/awpmd/libawpmd.a`` and
``lib/awpmd/Makefile.lammps``. The latter is copied from an
@ -1259,21 +1312,20 @@ AWPMD package
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
----------
.. _colvars:
.. _colvar:
COLVARS package
---------------------------------------
---------------
This package includes the `Colvars library
<https://colvars.github.io/>`_ into the LAMMPS distribution, which can
be built for the most part with all major versions of the C++ language.
This package enables the use of the `Colvars <https://colvars.github.io/>`_
module included in the LAMMPS source distribution.
.. tabs::
@ -1286,42 +1338,45 @@ be built for the most part with all major versions of the C++ language.
.. tab:: Traditional make
Before building LAMMPS, one must build the Colvars library in lib/colvars.
As with other libraries distributed with LAMMPS, the Colvars library
needs to be built before building the LAMMPS program with the COLVARS
package enabled.
This can be done manually in the same folder by using or adapting
one of the provided Makefiles: for example, ``Makefile.g++`` for
the GNU C++ compiler. C++11 compatibility may need to be enabled
for some older compilers (as is done in the example makefile).
In general, it is safer to use build setting consistent with the
rest of LAMMPS. This is best carried out from the LAMMPS src
directory using a command like these, which simply invokes the
``lib/colvars/Install.py`` script with the specified args:
From the LAMMPS ``src`` directory, this is most easily and safely done
via one of the following commands, which implicitly rely on the
``lib/colvars/Install.py`` script with optional arguments:
.. code-block:: bash
$ make lib-colvars # print help message
$ make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
make lib-colvars # print help message
make lib-colvars args="-m serial" # build with GNU g++ compiler (settings as with "make serial")
make lib-colvars args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-colvars args="-m g++-debug" # build with GNU g++ compiler and colvars debugging enabled
The "machine" argument of the "-m" flag is used to find a
Makefile.machine to use as build recipe. If it does not already
exist in ``lib/colvars``, it will be auto-generated by using
compiler flags consistent with those parsed from the core LAMMPS
makefiles.
``Makefile.machine`` file to use as build recipe. If such recipe does
not already exist in ``lib/colvars``, suitable settings will be
auto-generated consistent with those used in the core LAMMPS makefiles.
.. versionchanged:: TBD
Please note that Colvars uses the Lepton library, which is now
included with the LEPTON package; if you use anything other than
the ``make lib-colvars`` command, please make sure to :ref:`build
Lepton beforehand <lepton>`.
Optional flags may be specified as environment variables:
.. code-block:: bash
$ COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
$ COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
COLVARS_DEBUG=yes make lib-colvars args="-m machine" # Build with debug code (much slower)
COLVARS_LEPTON=no make lib-colvars args="-m machine" # Build without Lepton (included otherwise)
The build should produce two files: the library ``lib/colvars/libcolvars.a``
(which also includes Lepton objects if enabled) and the specification file
``lib/colvars/Makefile.lammps``. The latter is auto-generated, and normally does
not need to be edited.
The build should produce two files: the library
``lib/colvars/libcolvars.a`` and the specification file
``lib/colvars/Makefile.lammps``. The latter is auto-generated,
and normally does not need to be edited.
----------
@ -1336,8 +1391,21 @@ This package depends on the KSPACE package.
.. tab:: CMake build
No additional settings are needed besides ``-D PKG_KSPACE=yes`` and
``-D PKG_ELECTRODE=yes``.
.. code-block:: bash
-D PKG_ELECTRODE=yes # enable the package itself
-D PKG_KSPACE=yes # the ELECTRODE package requires KSPACE
-D USE_INTERNAL_LINALG=value #
Features in the ELECTRODE package are dependent on code in the
KSPACE package so the latter one *must* be enabled.
The ELECTRODE package also requires LAPACK (and BLAS) and CMake
can identify their locations and pass that info to the LATTE build
script. But on some systems this may cause problems when linking
or the dependency is not desired. Try enabling
``USE_INTERNAL_LINALG`` in those cases to use the bundled linear
algebra library and work around the limitation.
.. tab:: Traditional make
@ -1350,9 +1418,9 @@ This package depends on the KSPACE package.
.. code-block:: bash
$ make lib-electrode # print help message
$ make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-electrode # print help message
make lib-electrode args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-electrode args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
Note that the ``Makefile.lammps`` file has settings for the BLAS
@ -1363,10 +1431,10 @@ This package depends on the KSPACE package.
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
The package itself is activated with ``make yes-KSPACE`` and
``make yes-ELECTRODE``
@ -1406,8 +1474,8 @@ at: `https://github.com/ICAMS/lammps-user-pace/ <https://github.com/ICAMS/lammps
.. code-block:: bash
$ make lib-pace # print help message
$ make lib-pace args="-b" # download and build the default version in lib/pace
make lib-pace # print help message
make lib-pace args="-b" # download and build the default version in lib/pace
You should not need to edit the ``lib/pace/Makefile.lammps`` file.
@ -1434,10 +1502,10 @@ ML-POD package
.. code-block:: bash
$ make lib-mlpod # print help message
$ make lib-mlpod args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
$ make lib-mlpod args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
$ make lib-mlpod args="-m mpi -e linalg" # same as above but use the bundled linalg lib
make lib-mlpod # print help message
make lib-mlpod args="-m serial" # build with GNU g++ compiler and MPI STUBS (settings as with "make serial")
make lib-mlpod args="-m mpi" # build with default MPI compiler (settings as with "make mpi")
make lib-mlpod args="-m mpi -e linalg" # same as above but use the bundled linalg lib
Note that the ``Makefile.lammps`` file has settings to use the BLAS
and LAPACK linear algebra libraries. These can either exist on
@ -1447,10 +1515,10 @@ ML-POD package
.. code-block:: bash
$ make lib-linalg # print help message
$ make lib-linalg args="-m serial" # build with GNU Fortran compiler (settings as with "make serial")
$ make lib-linalg args="-m mpi" # build with default MPI Fortran compiler (settings as with "make mpi")
$ make lib-linalg args="-m gfortran" # build with GNU Fortran compiler
make lib-linalg # print help message
make lib-linalg args="-m serial" # build with GNU C++ compiler (settings as with "make serial")
make lib-linalg args="-m mpi" # build with default MPI C++ compiler (settings as with "make mpi")
make lib-linalg args="-m g++" # build with GNU C++ compiler
The package itself is activated with ``make yes-ML-POD``.
@ -1549,10 +1617,10 @@ LAMMPS build.
.. code-block:: bash
$ make lib-plumed # print help message
$ make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2
$ make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local
$ make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in
make lib-plumed # print help message
make lib-plumed args="-b" # download and build PLUMED in lib/plumed/plumed2
make lib-plumed args="-p $HOME/.local" # use existing PLUMED installation in $HOME/.local
make lib-plumed args="-p /usr/local -m shared" # use existing PLUMED installation in
# /usr/local and use shared linkage mode
Note that 2 symbolic (soft) links, ``includelink`` and ``liblink``
@ -1565,8 +1633,8 @@ LAMMPS build.
.. code-block:: bash
$ make yes-plumed
$ make machine
make yes-plumed
make machine
Once this compilation completes you should be able to run LAMMPS
in the usual way. For shared linkage mode, libplumed.so must be
@ -1618,8 +1686,8 @@ the HDF5 library.
.. code-block:: bash
$ make lib-h5md # print help message
$ make lib-h5md args="-m h5cc" # build with h5cc compiler
make lib-h5md # print help message
make lib-h5md args="-m h5cc" # build with h5cc compiler
The build should produce two files: ``lib/h5md/libch5md.a`` and
``lib/h5md/Makefile.lammps``. The latter is copied from an
@ -1673,10 +1741,10 @@ details please see ``lib/hdnnp/README`` and the `n2p2 build documentation
.. code-block:: bash
$ make lib-hdnnp # print help message
$ make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
$ make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
$ make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2 installation in /usr/local/n2p2
make lib-hdnnp # print help message
make lib-hdnnp args="-b" # download and build in lib/hdnnp/n2p2-...
make lib-hdnnp args="-b -v 2.1.4" # download and build specific version
make lib-hdnnp args="-p /usr/local/n2p2" # use the existing n2p2 installation in /usr/local/n2p2
Note that 3 symbolic (soft) links, ``includelink``, ``liblink`` and
``Makefile.lammps``, will be created in ``lib/hdnnp`` to point to
@ -1776,8 +1844,8 @@ MDI package
.. code-block:: bash
$ python Install.py -m gcc # build using gcc compiler
$ python Install.py -m icc # build using icc compiler
python Install.py -m gcc # build using gcc compiler
python Install.py -m icc # build using icc compiler
The build should produce two files: ``lib/mdi/includelink/mdi.h``
and ``lib/mdi/liblink/libmdi.so``\ .
@ -1811,9 +1879,9 @@ they will be downloaded the first time this package is installed.
.. code-block:: bash
$ make lib-mesont # print help message
$ make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
$ make lib-mesont args="-m ifort" # build with Intel icc compiler
make lib-mesont # print help message
make lib-mesont args="-m gfortran" # build with GNU g++ compiler (settings as with "make serial")
make lib-mesont args="-m ifort" # build with Intel icc compiler
The build should produce two files: ``lib/mesont/libmesont.a`` and
``lib/mesont/Makefile.lammps``\ . The latter is copied from an
@ -1926,6 +1994,22 @@ OPENMP package
For other platforms and compilers, please consult the
documentation about OpenMP support for your compiler.
.. admonition:: Adding OpenMP support on macOS
:class: note
Apple offers the `Xcode package and IDE
<https://developer.apple.com/xcode/>`_ for compiling software on
macOS, so you have likely installed it to compile LAMMPS. Their
compiler is based on `Clang <https://clang.llvm.org/>`, but while it
is capable of processing OpenMP directives, the necessary header
files and OpenMP runtime library are missing. The `R developers
<https://www.r-project.org/>` have figured out a way to build those
in a compatible fashion. One can download them from
`https://mac.r-project.org/openmp/
<https://mac.r-project.org/openmp/>`_. Simply adding those files as
instructed enables the Xcode C++ compiler to compile LAMMPS with ``-D
BUILD_OMP=yes``.
----------
.. _qmmm:
@ -1980,10 +2064,10 @@ verified to work in February 2020 with Quantum Espresso versions 6.3 to
.. code-block:: bash
$ make lib-qmmm # print help message
$ make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
$ make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
$ make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
make lib-qmmm # print help message
make lib-qmmm args="-m serial" # build with GNU Fortran compiler (settings as in "make serial")
make lib-qmmm args="-m mpi" # build with default MPI compiler (settings as in "make mpi")
make lib-qmmm args="-m gfortran" # build with GNU Fortran compiler
The build should produce two files: ``lib/qmmm/libqmmm.a`` and
``lib/qmmm/Makefile.lammps``. The latter is copied from an
@ -2132,9 +2216,9 @@ Eigen3 is a template library, so you do not need to build it.
.. code-block:: bash
$ make lib-smd # print help message
$ make lib-smd args="-b" # download to lib/smd/eigen3
$ make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
make lib-smd # print help message
make lib-smd args="-b" # download to lib/smd/eigen3
make lib-smd args="-p /usr/include/eigen3" # use existing Eigen installation in /usr/include/eigen3
Note that a symbolic (soft) link named ``includelink`` is created
in ``lib/smd`` to point to the Eigen dir. When LAMMPS builds it

4
doc/src/Build_link.rst
View File

@ -209,7 +209,7 @@ You can verify whether all required shared libraries are found with the
.. code-block:: bash
$ LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
LD_LIBRARY_PATH=/home/user/lammps/src ldd caller
linux-vdso.so.1 (0x00007ffe729e0000)
liblammps.so => /home/user/lammps/src/liblammps.so (0x00007fc91bb9e000)
libstdc++.so.6 => /lib64/libstdc++.so.6 (0x00007fc91b984000)
@ -222,7 +222,7 @@ If a required library is missing, you would get a 'not found' entry:
.. code-block:: bash
$ ldd caller
ldd caller
linux-vdso.so.1 (0x00007ffd672fe000)
liblammps.so => not found
libstdc++.so.6 => /usr/lib64/libstdc++.so.6 (0x00007fb7c7e86000)

21
doc/src/Build_manual.rst
View File

@ -125,38 +125,29 @@ common setups:
.. code-block:: bash
sudo apt-get install python-virtualenv git doxygen
sudo apt-get install git doxygen
.. tab:: RHEL or CentOS (Version 7.x)
.. code-block:: bash
sudo yum install python3-virtualenv git doxygen
sudo yum install git doxygen
.. tab:: Fedora or RHEL/CentOS (8.x or later)
.. code-block:: bash
sudo dnf install python3-virtualenv git doxygen
sudo dnf install git doxygen
.. tab:: MacOS X
.. tab:: macOS
*Python 3*
Download the latest Python 3 MacOS X package from
If Python 3 is not available on your macOS system, you can
download the latest Python 3 macOS package from
`https://www.python.org <https://www.python.org>`_ and install it.
This will install both Python 3 and pip3.
*virtualenv*
Once Python 3 is installed, open a Terminal and type
.. code-block:: bash
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
Prerequisites for PDF
---------------------

9
doc/src/Build_package.rst
View File

@ -30,23 +30,30 @@ steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:
.. this list must be kept in sync with its counterpart in Build_extras.rst
.. table_from_list::
:columns: 6
* :ref:`ADIOS <adios>`
* :ref:`ATC <atc>`
* :ref:`AWPMD <awpmd>`
* :ref:`COLVARS <colvars>`
* :ref:`COLVARS <colvar>`
* :ref:`COMPRESS <compress>`
* :ref:`ELECTRODE <electrode>`
* :ref:`GPU <gpu>`
* :ref:`H5MD <h5md>`
* :ref:`INTEL <intel>`
* :ref:`KIM <kim>`
* :ref:`KOKKOS <kokkos>`
* :ref:`LATTE <latte>`
* :ref:`LEPTON <lepton>`
* :ref:`MACHDYN <machdyn>`
* :ref:`MDI <mdi>`
* :ref:`MESONT <mesont>`
* :ref:`ML-HDNNP <ml-hdnnp>`
* :ref:`ML-IAP <mliap>`
* :ref:`ML-PACE <ml-pace>`
* :ref:`ML-POD <ml-pod>`
* :ref:`ML-QUIP <ml-quip>`
* :ref:`MOLFILE <molfile>`
* :ref:`MSCG <mscg>`

2
doc/src/Commands_all.rst
View File

@ -24,6 +24,7 @@ table above.
* :doc:`angle_coeff <angle_coeff>`
* :doc:`angle_style <angle_style>`
* :doc:`angle_write <angle_write>`
* :doc:`atom_modify <atom_modify>`
* :doc:`atom_style <atom_style>`
* :doc:`balance <balance>`
@ -45,6 +46,7 @@ table above.
* :doc:`dielectric <dielectric>`
* :doc:`dihedral_coeff <dihedral_coeff>`
* :doc:`dihedral_style <dihedral_style>`
* :doc:`dihedral_write <dihedral_write>`
* :doc:`dimension <dimension>`
* :doc:`displace_atoms <displace_atoms>`
* :doc:`dump <dump>`

3
doc/src/Commands_bond.rst
View File

@ -44,6 +44,7 @@ OPT.
* :doc:`harmonic (iko) <bond_harmonic>`
* :doc:`harmonic/shift (o) <bond_harmonic_shift>`
* :doc:`harmonic/shift/cut (o) <bond_harmonic_shift_cut>`
* :doc:`lepton (o) <bond_lepton>`
* :doc:`mesocnt <bond_mesocnt>`
* :doc:`mm3 <bond_mm3>`
* :doc:`morse (o) <bond_morse>`
@ -93,6 +94,7 @@ OPT.
* :doc:`fourier/simple (o) <angle_fourier_simple>`
* :doc:`gaussian <angle_gaussian>`
* :doc:`harmonic (iko) <angle_harmonic>`
* :doc:`lepton (o) <angle_lepton>`
* :doc:`mesocnt <angle_mesocnt>`
* :doc:`mm3 <angle_mm3>`
* :doc:`quartic (o) <angle_quartic>`
@ -127,6 +129,7 @@ OPT.
* :doc:`fourier (io) <dihedral_fourier>`
* :doc:`harmonic (iko) <dihedral_harmonic>`
* :doc:`helix (o) <dihedral_helix>`
* :doc:`lepton (o) <dihedral_lepton>`
* :doc:`multi/harmonic (o) <dihedral_multi_harmonic>`
* :doc:`nharmonic (o) <dihedral_nharmonic>`
* :doc:`opls (iko) <dihedral_opls>`

1
doc/src/Commands_compute.rst
View File

@ -57,6 +57,7 @@ KOKKOS, o = OPENMP, t = OPT.
* :doc:`dpd/atom <compute_dpd_atom>`
* :doc:`edpd/temp/atom <compute_edpd_temp_atom>`
* :doc:`efield/atom <compute_efield_atom>`
* :doc:`efield/wolf/atom <compute_efield_wolf_atom>`
* :doc:`entropy/atom <compute_entropy_atom>`
* :doc:`erotate/asphere <compute_erotate_asphere>`
* :doc:`erotate/rigid <compute_erotate_rigid>`

6
doc/src/Commands_fix.rst
View File

@ -44,9 +44,6 @@ OPT.
* :doc:`ave/time <fix_ave_time>`
* :doc:`aveforce <fix_aveforce>`
* :doc:`balance <fix_balance>`
* :doc:`brownian <fix_brownian>`
* :doc:`brownian/asphere <fix_brownian>`
* :doc:`brownian/sphere <fix_brownian>`
* :doc:`bocs <fix_bocs>`
* :doc:`bond/break <fix_bond_break>`
* :doc:`bond/create <fix_bond_create>`
@ -54,6 +51,9 @@ OPT.
* :doc:`bond/react <fix_bond_react>`
* :doc:`bond/swap <fix_bond_swap>`
* :doc:`box/relax <fix_box_relax>`
* :doc:`brownian <fix_brownian>`
* :doc:`brownian/asphere <fix_brownian>`
* :doc:`brownian/sphere <fix_brownian>`
* :doc:`charge/regulation <fix_charge_regulation>`
* :doc:`cmap <fix_cmap>`
* :doc:`colvars <fix_colvars>`

4
doc/src/Commands_pair.rst
View File

@ -134,6 +134,8 @@ OPT.
* :doc:`lcbop <pair_lcbop>`
* :doc:`lebedeva/z <pair_lebedeva_z>`
* :doc:`lennard/mdf <pair_mdf>`
* :doc:`lepton (o) <pair_lepton>`
* :doc:`lepton/coul (o) <pair_lepton>`
* :doc:`line/lj <pair_line_lj>`
* :doc:`lj/charmm/coul/charmm (giko) <pair_charmm>`
* :doc:`lj/charmm/coul/charmm/implicit (ko) <pair_charmm>`
@ -236,7 +238,7 @@ OPT.
* :doc:`oxrna2/xstk <pair_oxrna2>`
* :doc:`oxrna2/coaxstk <pair_oxrna2>`
* :doc:`pace (k) <pair_pace>`
* :doc:`pace/extrapolation <pair_pace>`
* :doc:`pace/extrapolation (k) <pair_pace>`
* :doc:`pod <pair_pod>`
* :doc:`peri/eps <pair_peri>`
* :doc:`peri/lps (o) <pair_peri>`

10
doc/src/Commands_removed.rst
View File

@ -50,6 +50,16 @@ for some optimizations leading to better performance. The pair style
period the C++ version of MEAM was called USER-MEAMC so it could
coexist with the Fortran version.
Minimize style fire/old
-----------------------
.. deprecated:: TBD
Minimize style *fire/old* has been removed. Its functionality can be
reproduced with *fire* with specific options. Please see the
:doc:`min_modify command <min_modify>` documentation for details.
REAX package
------------

6
doc/src/Developer_parallel.rst
View File

@ -3,9 +3,9 @@ Parallel algorithms
LAMMPS is designed to enable running simulations in parallel using the
MPI parallel communication standard with distributed data via domain
decomposition. The parallelization aims to be efficient result in good
strong scaling (= good speedup for the same system) and good weak
scaling (= the computational cost of enlarging the system is
decomposition. The parallelization aims to be efficient, and resulting
in good strong scaling (= good speedup for the same system) and good
weak scaling (= the computational cost of enlarging the system is
proportional to the system size). Additional parallelization using GPUs
or OpenMP can also be applied within the sub-domain assigned to an MPI
process. For clarity, most of the following illustrations show the 2d

6
doc/src/Developer_unittest.rst
View File

@ -489,7 +489,7 @@ to update the YAML files. Running a command like
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
test_pair_style mol-pair-lennard_mdf.yaml -g new.yaml
will read the settings from the ``mol-pair-lennard_mdf.yaml`` file and then compute
the reference data and write a new file with to ``new.yaml``. If this step fails,
@ -500,13 +500,13 @@ It is also possible to do an update in place with:
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml -u
test_pair_style mol-pair-lennard_mdf.yaml -u
And one can finally run the full set of tests with:
.. code-block:: bash
$ test_pair_style mol-pair-lennard_mdf.yaml
test_pair_style mol-pair-lennard_mdf.yaml
This will just print a summary of the groups of tests. When using the "-v" flag
the test will also keep any LAMMPS output and when using the "-s" flag, there

13
doc/src/Errors_debug.rst
View File

@ -40,7 +40,7 @@ We use it to show how to identify the origin of a segmentation fault.
After recompiling LAMMPS and running the input you should get something like this:
.. code-block::
.. code-block:: console
$ ./lmp -in in.melt
LAMMPS (19 Mar 2020)
@ -90,8 +90,9 @@ it. When it reaches the code causing the segmentation fault, it will
stop with a message why it stopped, print the current line of code, and
drop back to the GDB prompt.
.. code-block::
.. code-block:: console
(gdb) run
[...]
Setting up Verlet run ...
Unit style : lj
@ -106,7 +107,7 @@ drop back to the GDB prompt.
Now typing the command "where" will show the stack of functions starting from
the current function back to "main()".
.. code-block::
.. code-block:: console
(gdb) where
#0 0x00000000006653ab in LAMMPS_NS::PairLJCut::compute (this=0x829740, eflag=1, vflag=<optimized out>) at /home/akohlmey/compile/lammps/src/pair_lj_cut.cpp:139
@ -124,7 +125,7 @@ You can also print the value of variables and see if there is anything
unexpected. Segmentation faults, for example, commonly happen when a
pointer variable is not assigned and still initialized to NULL.
.. code-block::
.. code-block:: console
(gdb) print x
$1 = (double **) 0x7ffff7ca1010
@ -153,7 +154,7 @@ utility to the current folder. Example: ``coredumpctl -o core dump lmp``.
Now you can launch the debugger to load the executable, its debug info
and the core dump and drop you to a prompt like before.
.. code-block::
.. code-block:: console
$ gdb lmp core
Reading symbols from lmp...
@ -186,7 +187,7 @@ recommended to redirect the valgrind output to a file (e.g. with
process ID) so that the messages of the multiple valgrind instances to
the console are not mixed.
.. code-block::
.. code-block:: console
$ valgrind ./lmp -in in.melt
==1933642== Memcheck, a memory error detector

15
doc/src/Fortran.rst
View File

@ -47,11 +47,20 @@ Fortran code in order to uses the Fortran interface.
A working example can be found together with equivalent examples in C and
C++ in the ``examples/COUPLE/simple`` folder of the LAMMPS distribution.
.. admonition:: Fortran compiler compatibility
:class: note
A fully Fortran 2003 compatible Fortran compiler is required.
This means that currently only GNU Fortran 9 and later are
compatible and thus the default compilers of Red Hat or CentOS 7
and Ubuntu 18.04 LTS and not compatible. Either newer compilers
need to be installed or the Linux updated.
.. versionchanged:: TBD
.. note::
A contributed Fortran interface interface is available in the
A contributed Fortran interface is available in the
``examples/COUPLE/fortran2`` folder. However, since the completion
of the :f:mod:`LIBLAMMPS` module, this interface is now deprecated,
no longer actively maintained and will likely be removed in the
@ -2403,7 +2412,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
mode. The function should have Fortran language bindings with the following
interface, which depends on how LAMMPS was compiled:
.. code-block:: Fortran
.. code-block:: fortran
ABSTRACT INTERFACE
SUBROUTINE external_callback(caller, timestep, ids, x, fexternal)
@ -2462,7 +2471,7 @@ Procedures Bound to the :f:type:`lammps` Derived Type
with ``-DLAMMPS_SMALLBIG``) that applies something akin to Hooke's Law
(with each atom having a different *k* value) is shown below.
.. code-block:: Fortran
.. code-block:: fortran
MODULE stuff
USE, INTRINSIC :: ISO_C_BINDING, ONLY : c_int, c_double, c_int64_t

10
doc/src/Howto_amoeba.rst
View File

@ -261,11 +261,11 @@ all the options available to use with the tinker2lmp.py script:
.. code-block:: bash
% python tinker2lmp.py -xyz water_dimer.xyz -amoeba amoeba_water.prm -data data.water_dimer.amoeba # AMOEBA non-periodic system
% python tinker2lmp.py -xyz water_dimer.xyz -hippo hippo_water.prm -data data.water_dimer.hippo # HIPPO non-periodic system
% python tinker2lmp.py -xyz water_box.xyz -amoeba amoeba_water.prm -data data.water_box.amoeba -pbc 18.643 18.643 18.643 # AMOEBA periodic system
% python tinker2lmp.py -xyz water_box.xyz -hippo hippo_water.prm -data data.water_box.hippo -pbc 18.643 18.643 18.643 # HIPPO periodic system
% python tinker2lmp.py -xyz ubiquitin.xyz -amoeba amoeba_ubiquitin.prm -data data.ubiquitin.new -pbc 54.99 41.91 41.91 -bitorsion bitorsion.ubiquitin.data.new # system with bitorsions
python tinker2lmp.py -xyz water_dimer.xyz -amoeba amoeba_water.prm -data data.water_dimer.amoeba # AMOEBA non-periodic system
python tinker2lmp.py -xyz water_dimer.xyz -hippo hippo_water.prm -data data.water_dimer.hippo # HIPPO non-periodic system
python tinker2lmp.py -xyz water_box.xyz -amoeba amoeba_water.prm -data data.water_box.amoeba -pbc 18.643 18.643 18.643 # AMOEBA periodic system
python tinker2lmp.py -xyz water_box.xyz -hippo hippo_water.prm -data data.water_box.hippo -pbc 18.643 18.643 18.643 # HIPPO periodic system
python tinker2lmp.py -xyz ubiquitin.xyz -amoeba amoeba_ubiquitin.prm -data data.ubiquitin.new -pbc 54.99 41.91 41.91 -bitorsion bitorsion.ubiquitin.data.new # system with bitorsions
Switches and their arguments may be specified in any order.

6
doc/src/Howto_cmake.rst
View File

@ -46,7 +46,7 @@ This tutorial assumes that you are operating in a command-line environment
using a shell like Bash.
- Linux: any Terminal window will work
- MacOS X: launch the Terminal application.
- macOS: launch the Terminal application.
- Windows 10: install and run the :doc:`Windows Subsystem for Linux <Howto_wsl>`
We also assume that you have downloaded and unpacked a recent LAMMPS source code package
@ -56,7 +56,7 @@ You should change into the top level directory of the LAMMPS source tree all
paths mentioned in the tutorial are relative to that. Immediately after downloading
it should look like this:
.. code-block:: bash
.. code-block:: console
$ ls
bench doc lib potentials README tools
@ -104,7 +104,7 @@ the progress of the configuration printed to the screen followed by a
summary of the enabled features, options and compiler settings. A typical
summary screen will look like this:
.. code-block::
.. code-block:: console
$ cmake ../cmake/
-- The CXX compiler identification is GNU 8.2.0

61
doc/src/Howto_github.rst
View File

@ -78,13 +78,13 @@ machine via HTTPS:
.. code-block:: bash
$ git clone https://github.com/<your user name>/lammps.git <some name>
git clone https://github.com/<your user name>/lammps.git <some name>
or, if you have set up your GitHub account for using SSH keys, via SSH:
.. code-block:: bash
$ git clone git@github.com:<your user name>/lammps.git
git clone git@github.com:<your user name>/lammps.git
You can find the proper URL by clicking the "Clone or download"-button:
@ -103,21 +103,21 @@ and use git pull:
.. code-block:: bash
$ cd mylammps
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
cd mylammps
git checkout develop
git pull https://github.com/lammps/lammps develop
You can also add this URL as a remote:
.. code-block:: bash
$ git remote add upstream https://www.github.com/lammps/lammps
git remote add upstream https://www.github.com/lammps/lammps
From then on you can update your upstream branches with:
.. code-block:: bash
$ git fetch upstream
git fetch upstream
and then refer to the upstream repository branches with
`upstream/develop` or `upstream/release` and so on.
@ -129,8 +129,8 @@ workflow that updated this tutorial, and hence we will call the branch
.. code-block:: bash
$ git fetch upstream
$ git checkout -b github-tutorial-update upstream/develop
git fetch upstream
git checkout -b github-tutorial-update upstream/develop
Now that we have changed branches, we can make our changes to our local
repository. Just remember that if you want to start working on another,
@ -150,8 +150,8 @@ After everything is done, add the files to the branch and commit them:
.. code-block:: bash
$ git add doc/src/Howto_github.txt
$ git add doc/src/JPG/tutorial*.png
git add doc/src/Howto_github.txt
git add doc/src/JPG/tutorial*.png
.. warning::
@ -174,13 +174,13 @@ useful message that explains the change.
.. code-block:: bash
$ git commit -m 'Finally updated the GitHub tutorial'
git commit -m 'Finally updated the GitHub tutorial'
After the commit, the changes can be pushed to the same branch on GitHub:
.. code-block:: bash
$ git push
git push
Git will ask you for your user name and password on GitHub if you have
not configured anything. If your local branch is not present on GitHub yet,
@ -188,7 +188,7 @@ it will ask you to add it by running
.. code-block:: bash
$ git push --set-upstream origin github-tutorial-update
git push --set-upstream origin github-tutorial-update
If you correctly type your user name and
password, the feature branch should be added to your fork on GitHub.
@ -198,13 +198,13 @@ If you want to make really sure you push to the right repository
.. code-block:: bash
$ git push origin
git push origin
or using an explicit URL:
.. code-block:: bash
$ git push git@github.com:Pakketeretet2/lammps.git
git push git@github.com:Pakketeretet2/lammps.git
----------
@ -412,10 +412,10 @@ we need to pull Axel's change back into our branch, and merge them:
.. code-block:: bash
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request*.png
$ git commit -m "Updated text and images on reverse pull requests"
$ git pull
git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request*.png
git commit -m "Updated text and images on reverse pull requests"
git pull
In this case, the merge was painless because git could auto-merge:
@ -428,10 +428,10 @@ commit and push again:
.. code-block:: bash
$ git add Howto_github.txt
$ git add JPG/tutorial_reverse_pull_request6.png
$ git commit -m "Merged Axel's suggestions and updated text"
$ git push git@github.com:Pakketeretet2/lammps
git add Howto_github.txt
git add JPG/tutorial_reverse_pull_request6.png
git commit -m "Merged Axel's suggestions and updated text"
git push git@github.com:Pakketeretet2/lammps
This merge also shows up on the lammps GitHub page:
@ -456,9 +456,9 @@ branch!
.. code-block:: bash
$ git checkout develop
$ git pull https://github.com/lammps/lammps develop
$ git branch -d github-tutorial-update
git checkout develop
git pull https://github.com/lammps/lammps develop
git branch -d github-tutorial-update
If you do not pull first, it is not really a problem but git will warn
you at the next statement that you are deleting a local branch that
@ -472,7 +472,7 @@ to your remote(s) as well:
.. code-block:: bash
$ git push origin :github-tutorial-update
git push origin :github-tutorial-update
**Recent changes in the workflow**
@ -486,5 +486,6 @@ simplify comparisons between releases. Finally, all patches and
submissions are subject to automatic testing and code checks to make
sure they at the very least compile.
A discussion of the LAMMPS developer GitHub workflow can be found in the file
`doc/github-development-workflow.md <https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_
A discussion of the LAMMPS developer GitHub workflow can be found in the
file `doc/github-development-workflow.md
<https://github.com/lammps/lammps/blob/develop/doc/github-development-workflow.md>`_

26
doc/src/Howto_mdi.rst
View File

@ -134,18 +134,18 @@ used in stand-alone mode:
.. code-block:: bash
% 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>`_
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>`_
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
% 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
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
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
@ -154,10 +154,10 @@ plugin mode, which results in a libinqmdi.so file in
.. code-block:: bash
% 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
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

13
doc/src/Install_conda.rst
View File

@ -1,7 +1,8 @@
Download an executable for Linux or Mac via Conda
-------------------------------------------------
Binaries are available for MacOS or Linux via `Conda <conda_>`_.
Pre-compiled LAMMPS binaries are available for macOS or Linux via the
`Conda <conda_>`_ package management system.
First, one must setup the Conda package manager on your system. Follow the
instructions to install `Miniconda <mini_conda_install_>`_, then create a conda
@ -10,15 +11,15 @@ install:
.. code-block:: bash
% conda config --add channels conda-forge
% conda create -n my-lammps-env
conda config --add channels conda-forge
conda create -n my-lammps-env
Then, you can install LAMMPS on your system with the following command:
.. code-block:: bash
% conda activate my-lammps-env
% conda install lammps
conda activate my-lammps-env
conda install lammps
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Conda also installing the `kim-api` binaries when LAMMPS is
@ -27,7 +28,7 @@ install the `openkim-models` package
.. code-block:: bash
% conda install openkim-models
conda install openkim-models
If you have problems with the installation you can post issues to
`this link <conda_forge_lammps_>`_.

26
doc/src/Install_git.rst
View File

@ -41,7 +41,7 @@ create a local copy of the LAMMPS repository with a command like:
.. code-block:: bash
$ git clone -b release https://github.com/lammps/lammps.git mylammps
git clone -b release https://github.com/lammps/lammps.git mylammps
where "mylammps" is the name of the directory you wish to create on
your machine and "release" is one of the 3 branches listed above.
@ -78,10 +78,10 @@ from within the "mylammps" directory:
.. code-block:: bash
$ git checkout release # not needed if you always stay in this branch
$ git checkout stable # use one of these 3 checkout commands
$ git checkout develop # to choose the branch to follow
$ git pull
git checkout release # not needed if you always stay in this branch
git checkout stable # use one of these 3 checkout commands
git checkout develop # to choose the branch to follow
git pull
Doing a "pull" will not change any files you have added to the LAMMPS
directory structure. It will also not change any existing LAMMPS
@ -97,7 +97,7 @@ this is as follows.
.. code-block:: bash
$ git checkout tagID
git checkout tagID
Stable versions and what tagID to use for a particular stable version
are discussed on `this page <https://www.lammps.org/bug.html#version>`_.
@ -138,13 +138,13 @@ changed. How to do this depends on the build system you are using.
.. code-block:: bash
$ make purge # remove any deprecated src files
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
make purge # remove any deprecated src files
make package-update # sync package files with src files
make foo # re-build for your machine (mpi, serial, etc)
to enforce consistency of the source between the src folder
and package directories. This is OK to do even if you don't
use any packages. The "make purge" command removes any deprecated
use any packages. The ``make purge`` command removes any deprecated
src files if they were removed by the patch from a package
sub-directory.
@ -160,9 +160,9 @@ changed. How to do this depends on the build system you are using.
:class: note
The servers at github.com support the "https://" access protocol for
anonymous, read-only access. If you have a suitably configured GitHub
account, you may also use SSH protocol with the
URL "git@github.com:lammps/lammps.git".
anonymous, read-only access. If you have a suitably configured
GitHub account, you may also use SSH protocol with the URL
"git@github.com:lammps/lammps.git".
The LAMMPS GitHub project is currently managed by Axel Kohlmeyer
(Temple U, akohlmey at gmail.com).

38
doc/src/Install_linux.rst
View File

@ -34,7 +34,7 @@ To install LAMMPS do the following once:
.. code-block:: bash
$ sudo apt-get install lammps
sudo apt-get install lammps
This downloads an executable named ``lmp`` to your box and multiple
packages with supporting data, examples and libraries as well as any
@ -43,13 +43,13 @@ to run input scripts:
.. code-block:: bash
$ lmp -in in.lj
lmp -in in.lj
To update LAMMPS to the latest packaged version, do the following:
.. code-block:: bash
$ sudo apt-get update
sudo apt-get update
which will also update other packages on your system.
@ -61,14 +61,14 @@ package
.. code-block:: bash
$ sudo apt-get install openkim-models
sudo apt-get install openkim-models
Or use the KIM-API commands to download and install individual models.
To un-install LAMMPS, do the following:
.. code-block:: bash
$ sudo apt-get remove lammps
sudo apt-get remove lammps
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -103,9 +103,9 @@ To install LAMMPS with OpenMPI and run an input ``in.lj`` with 2 CPUs do:
.. code-block:: bash
$ dnf install lammps-openmpi
$ module load mpi/openmpi-x86_64
$ mpirun -np 2 lmp -in in.lj
dnf install lammps-openmpi
module load mpi/openmpi-x86_64
mpirun -np 2 lmp -in in.lj
The ``dnf install`` command is needed only once. In case of a new LAMMPS
stable release, ``dnf update`` will automatically update to the newer
@ -121,7 +121,7 @@ can install the `openkim-models` package
.. code-block:: bash
$ dnf install openkim-models
dnf install openkim-models
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -162,14 +162,14 @@ in OpenSuse as of Leap 15.0. You can install the package with:
.. code-block:: bash
$ zypper install lammps
zypper install lammps
This includes support for OpenMPI. The name of the LAMMPS executable
is ``lmp``. Thus to run an input in parallel on 2 CPUs you would do:
.. code-block:: bash
$ mpirun -np 2 lmp -in in.lj
mpirun -np 2 lmp -in in.lj
Please use ``lmp -help`` to see which compilation options, packages,
and styles are included in the binary.
@ -181,7 +181,7 @@ can install the `openkim-models` package
.. code-block:: bash
$ zypper install openkim-models
zypper install openkim-models
Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.
@ -197,7 +197,7 @@ typing:
.. code-block:: bash
% emerge --ask lammps
emerge --ask lammps
Note that in Gentoo the LAMMPS source is downloaded and the package is
built on the your machine.
@ -206,7 +206,7 @@ Certain LAMMPS packages can be enable via USE flags, type
.. code-block:: bash
% equery uses lammps
equery uses lammps
for details.
@ -229,10 +229,10 @@ any of the above names in-place of lammps.
.. code-block:: bash
$ git clone https://aur.archlinux.org/lammps.git
$ cd lammps
$ makepkg -s
$ makepkg -i
git clone https://aur.archlinux.org/lammps.git
cd lammps
makepkg -s
makepkg -i
To update, you may repeat the above, or change into the cloned directory,
and execute the following, after which, if there are any changes, you may
@ -240,7 +240,7 @@ use makepkg as above.
.. code-block:: bash
$ git pull
git pull
Alternatively, you may use an AUR helper to install these packages.

6
doc/src/Install_mac.rst
View File

@ -12,7 +12,7 @@ the following commands:
.. code-block:: bash
% brew install lammps
brew install lammps
This will install the executables "lammps_serial" and "lammps_mpi", as well as
the LAMMPS "doc", "potentials", "tools", "bench", and "examples" directories.
@ -22,7 +22,7 @@ Lennard-Jones benchmark file:
.. code-block:: bash
% brew test lammps -v
brew test lammps -v
The LAMMPS binary is built with the :ref:`KIM package <kim>` which
results in Homebrew also installing the `kim-api` binaries when LAMMPS is
@ -31,7 +31,7 @@ install the `openkim-models` package
.. code-block:: bash
% brew install openkim-models
brew install openkim-models
If you have problems with the installation you can post issues to
`this link <https://github.com/Homebrew/homebrew-core/issues>`_.

4
doc/src/Install_tarball.rst
View File

@ -26,7 +26,7 @@ command:
.. code-block:: bash
$ tar -xzvf lammps*.tar.gz
tar -xzvf lammps*.tar.gz
This will create a LAMMPS directory with the version date
in its name, e.g. lammps-23Jun18.
@ -40,7 +40,7 @@ with the following command, to create a lammps-<version> dir:
.. code-block:: bash
$ unzip lammps*.zip
unzip lammps*.zip
This version corresponds to the selected LAMMPS patch or stable
release.

4
doc/src/Library_properties.rst
View File

@ -16,8 +16,8 @@ This section documents the following functions:
--------------------
The library interface allows the extraction of different kinds of
information about the active simulation instance and also---in some
cases---to apply modifications to it. This enables combining of a
information about the active simulation instance and also - in some
cases - to apply modifications to it. This enables combining of a
LAMMPS simulation with other processing and simulation methods computed
by the calling code, or by another code that is coupled to LAMMPS via
the library interface. In some cases the data returned is direct

114
doc/src/Packages_details.rst
View File

@ -68,6 +68,7 @@ page gives those details.
* :ref:`KSPACE <PKG-KSPACE>`
* :ref:`LATBOLTZ <PKG-LATBOLTZ>`
* :ref:`LATTE <PKG-LATTE>`
* :ref:`LEPTON <PKG-LEPTON>`
* :ref:`MACHDYN <PKG-MACHDYN>`
* :ref:`MANIFOLD <PKG-MANIFOLD>`
* :ref:`MANYBODY <PKG-MANYBODY>`
@ -492,22 +493,21 @@ COLVARS package
**Contents:**
COLVARS stands for collective variables, which can be used to
implement various enhanced sampling methods, including Adaptive
Biasing Force, Metadynamics, Steered MD, Umbrella Sampling and
Restraints. A :doc:`fix colvars <fix_colvars>` command is implemented
which wraps a COLVARS library, which implements these methods.
simulations.
Colvars stands for collective variables, which can be used to implement
various enhanced sampling methods, including Adaptive Biasing Force,
Metadynamics, Steered MD, Umbrella Sampling and Restraints. A :doc:`fix
colvars <fix_colvars>` command is implemented which wraps a COLVARS
library, which implements these methods. simulations.
**Authors:** The COLVARS library is written and maintained by
Giacomo Fiorin (ICMS, Temple University, Philadelphia, PA, USA)
and Jerome Henin (LISM, CNRS, Marseille, France), originally for
the NAMD MD code, but with portability in mind. Axel Kohlmeyer
(Temple U) provided the interface to LAMMPS.
**Authors:** The COLVARS library is written and maintained by Giacomo
Fiorin (NIH, Bethesda, MD, USA) and Jerome Henin (CNRS, Paris, France),
originally for the NAMD MD code, but with portability in mind. Axel
Kohlmeyer (Temple U) provided the interface to LAMMPS.
**Install:**
This package has :ref:`specific installation instructions <colvars>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <colvar>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -516,6 +516,8 @@ This package has :ref:`specific installation instructions <colvars>` on the :doc
* src/COLVARS/README
* lib/colvars/README
* :doc:`fix colvars <fix_colvars>`
* :doc:`group2ndx <group2ndx>`
* :doc:`ndx2group <group2ndx>`
* examples/PACKAGES/colvars
----------
@ -560,9 +562,10 @@ CORESHELL package
Compute and pair styles that implement the adiabatic core/shell model
for polarizability. The pair styles augment Born, Buckingham, and
Lennard-Jones styles with core/shell capabilities. The :doc:`compute temp/cs <compute_temp_cs>` command calculates the temperature of a
system with core/shell particles. See the :doc:`Howto coreshell <Howto_coreshell>` page for an overview of how to use
this package.
Lennard-Jones styles with core/shell capabilities. The :doc:`compute
temp/cs <compute_temp_cs>` command calculates the temperature of a
system with core/shell particles. See the :doc:`Howto coreshell
<Howto_coreshell>` page for an overview of how to use this package.
**Author:** Hendrik Heenen (Technical U of Munich).
@ -880,6 +883,8 @@ This package has :ref:`specific installation instructions <electrode>` on the
**Supporting info:**
* :doc:`fix electrode/conp <fix_electrode>`
* :doc:`fix electrode/conq <fix_electrode>`
* :doc:`fix electrode/thermo <fix_electrode>`
----------
@ -974,10 +979,11 @@ FEP package
**Contents:**
FEP stands for free energy perturbation. This package provides
methods for performing FEP simulations by using a :doc:`fix adapt/fep <fix_adapt_fep>` command with soft-core pair potentials,
which have a "soft" in their style name. There are auxiliary tools
for using this package in tools/fep; see its README file.
FEP stands for free energy perturbation. This package provides methods
for performing FEP simulations by using a :doc:`fix adapt/fep
<fix_adapt_fep>` command with soft-core pair potentials, which have a
"soft" in their style name. There are auxiliary tools for using this
package in tools/fep; see its README file.
**Author:** Agilio Padua (ENS de Lyon)
@ -1018,7 +1024,8 @@ Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
**Install:**
This package has :ref:`specific installation instructions <gpu>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <gpu>` on the
:doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1371,7 +1378,8 @@ Cawkwell, Anders Niklasson, and Christian Negre.
**Install:**
This package has :ref:`specific installation instructions <latte>` on the :doc:`Build extras <Build_extras>` page.
This package has :ref:`specific installation instructions <latte>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1384,6 +1392,46 @@ This package has :ref:`specific installation instructions <latte>` on the :doc:`
----------
.. _PKG-LEPTON:
LEPTON package
--------------
**Contents:**
Styles for pair, bond, and angle forces that evaluate the potential
function from a string using the `Lepton mathematical expression parser
<https://simtk.org/projects/lepton>`_. Lepton is a C++ library that is
bundled with `OpenMM <https://openmm.org/>`_ and can be used for
parsing, evaluating, differentiating, and analyzing mathematical
expressions. This is a more lightweight and efficient alternative for
evaluating custom potential function to an embedded Python interpreter
as used in the :ref:`PYTHON package <PKG-PYTHON>`. On the other hand,
since the potentials are evaluated form analytical expressions, they are
more precise than what can be done with :ref:`tabulated potentials
<tabulate>`.
**Authors:** Axel Kohlmeyer (Temple U). Lepton itself is developed
by Peter Eastman at Stanford University.
.. versionadded:: TBD
**Install:**
This package has :ref:`specific installation instructions <lepton>` on
the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
* src/LEPTON: filenames -> commands
* lib/lepton/README.md
* :doc:`pair_style lepton <pair_lepton>`
* :doc:`bond_style lepton <bond_lepton>`
* :doc:`angle_style lepton <angle_lepton>`
* :doc:`dihedral_style lepton <dihedral_lepton>`
----------
.. _PKG-MACHDYN:
MACHDYN package
@ -2544,17 +2592,18 @@ REACTION package
**Contents:**
This package allows for complex bond topology changes (reactions)
during a running MD simulation, when using classical force fields.
Topology changes are defined in pre- and post-reaction molecule
templates and can include creation and deletion of bonds, angles,
dihedrals, impropers, atom types, bond types, angle types, dihedral
types, improper types, and/or atomic charges. Other options currently
available include reaction constraints (e.g. angle and Arrhenius
constraints), deletion of reaction byproducts or other small
molecules, and chiral-sensitive reactions.
This package implements the REACTER protocol, which allows for complex
bond topology changes (reactions) during a running MD simulation when
using classical force fields. Topology changes are defined in pre- and
post-reaction molecule templates and can include creation and deletion
of bonds, angles, dihedrals, impropers, atom types, bond types, angle
types, dihedral types, improper types, and/or atomic charges. Other
options currently available include reaction constraints (e.g., angle
and Arrhenius constraints), deletion of reaction byproducts or other
small molecules, creation of new atoms or molecules bonded to existing
atoms, and using LAMMPS variables for input parameters.
**Author:** Jacob R. Gissinger (CU Boulder) while at NASA Langley Research Center.
**Author:** Jacob R. Gissinger (NASA Langley Research Center).
**Supporting info:**
@ -2564,7 +2613,8 @@ molecules, and chiral-sensitive reactions.
* examples/PACKAGES/reaction
* `2017 LAMMPS Workshop <https://www.lammps.org/workshops/Aug17/pdf/gissinger.pdf>`_
* `2019 LAMMPS Workshop <https://www.lammps.org/workshops/Aug19/talk_gissinger.pdf>`_
* reacter.org
* `2021 LAMMPS Workshop <https://www.lammps.org/workshops/Aug21/talk/jacob-gissinger/>`_
* `REACTER website (reacter.org) <https://www.reacter.org/>`_
----------

23
doc/src/Packages_list.rst
View File

@ -8,10 +8,10 @@ Packages are supported by either the LAMMPS developers or the
contributing authors and written in a syntax and style consistent with
the rest of LAMMPS.
The "Example" column is a sub-directory in the examples directory of the
distribution which has an input script that uses the package.
The "Examples" column is a sub-directory in the examples directory of the
distribution which has one or more input scripts that use the package.
E.g. "peptide" refers to the examples/peptide directory; PACKAGES/atc refers
to the examples/PACKAGES/atc directory. The "Library" column indicates
to the examples/PACKAGES/atc directory. The "Lib" column indicates
whether an extra library is needed to build and use the package:
* no = no library
@ -26,8 +26,8 @@ whether an extra library is needed to build and use the package:
* - Package
- Description
- Doc page
- Example
- Library
- Examples
- Lib
* - :ref:`ADIOS <PKG-ADIOS>`
- dump output via ADIOS
- :doc:`dump adios <dump_adios>`
@ -94,7 +94,7 @@ whether an extra library is needed to build and use the package:
- colloid
- no
* - :ref:`COLVARS <PKG-COLVARS>`
- collective variables library
- `Colvars collective variables library <https://colvars.github.io/>`_
- :doc:`fix colvars <fix_colvars>`
- PACKAGES/colvars
- int
@ -125,7 +125,7 @@ whether an extra library is needed to build and use the package:
- no
* - :ref:`DPD-BASIC <PKG-DPD-BASIC>`
- basic DPD models
- :doc:`pair_styles dpd dpd/tstat <pair_dpd>` :doc:`dpd/ext dpd/ext/tstat <pair_dpd_ext>`
- :doc:`pair_styles dpd <pair_dpd>` :doc:`dpd/ext <pair_dpd_ext>`
- PACKAGES/dpd-basic
- no
* - :ref:`DPD-MESO <PKG-DPD-MESO>`
@ -238,6 +238,11 @@ whether an extra library is needed to build and use the package:
- :doc:`fix latte <fix_latte>`
- latte
- ext
* - :ref:`LEPTON <PKG-LEPTON>`
- evaluate strings as potential function
- :doc:`pair_style lepton <pair_lepton>`
- PACKAGES/lepton
- int
* - :ref:`MACHDYN <PKG-MACHDYN>`
- smoothed Mach dynamics
- `SMD User Guide <PDF/MACHDYN_LAMMPS_userguide.pdf>`_
@ -379,7 +384,7 @@ whether an extra library is needed to build and use the package:
- plugins
- no
* - :ref:`PLUMED <PKG-PLUMED>`
- :ref:`PLUMED <PLUMED>` free energy library
- `PLUMED free energy library <https://www.plumed.org>`_
- :doc:`fix plumed <fix_plumed>`
- PACKAGES/plumed
- ext
@ -445,7 +450,7 @@ whether an extra library is needed to build and use the package:
- no
* - :ref:`SMTBQ <PKG-SMTBQ>`
- second moment tight binding potentials
- :doc:`pair_style smtbq <pair_smtbq>` :doc:`pair_style smatb <pair_smatb>`
- pair styles :doc:`smtbq <pair_smtbq>`, :doc:`smatb <pair_smatb>`
- PACKAGES/smtbq
- no
* - :ref:`SPH <PKG-SPH>`

28
doc/src/Python_install.rst
View File

@ -54,7 +54,7 @@ folder that the dynamic loader searches or inside of the installed
``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
``-DPKG_PYTHON=on`` (The first option is required, the other two
are optional by recommended). The exact file name of the shared
library depends on the platform (Unix/Linux, MacOS, Windows) and
library depends on the platform (Unix/Linux, macOS, Windows) and
the build configuration being used. The installation base folder
is already set by default to the ``$HOME/.local`` directory, but
it can be changed to a custom location defined by the
@ -121,7 +121,7 @@ folder that the dynamic loader searches or inside of the installed
the folder containing the LAMMPS shared library is either included
in a path searched by the shared linker (e.g. like
``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
variable (or ``DYLD_LIBRARY_PATH`` on MacOS). Otherwise you will
variable (or ``DYLD_LIBRARY_PATH`` on macOS). Otherwise you will
get an error when trying to create a LAMMPS object through the
Python module.
@ -130,7 +130,7 @@ folder that the dynamic loader searches or inside of the installed
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# MacOS
# macOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
@ -214,7 +214,7 @@ folder that the dynamic loader searches or inside of the installed
.. code-block:: bash
$ python install.py -p <python package> -l <shared library> [-n]
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,
@ -294,7 +294,7 @@ folder that the dynamic loader searches or inside of the installed
script in a similar fashion you need to update your
``$HOME/.bashrc`` file to include the shared library and
executable locations in ``LD_LIBRARY_PATH`` (or
``DYLD_LIBRARY_PATH`` on MacOS) and ``PATH``, respectively.
``DYLD_LIBRARY_PATH`` on macOS) and ``PATH``, respectively.
For example with:
@ -303,7 +303,7 @@ folder that the dynamic loader searches or inside of the installed
# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# MacOS
# macOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$DYLD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
.. tab:: In place usage
@ -313,7 +313,7 @@ folder that the dynamic loader searches or inside of the installed
package inside the source/compilation folders. Instead of
copying the files where they can be found, you need to set the environment
variables ``PYTHONPATH`` (for the Python package) and
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on macOS
For Bourne shells (bash, ksh and similar) the commands are:
@ -329,7 +329,7 @@ folder that the dynamic loader searches or inside of the installed
setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
On MacOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
On macOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
You can make those changes permanent by editing your ``$HOME/.bashrc``
or ``$HOME/.login`` files, respectively.
@ -343,7 +343,7 @@ Python interpreter, load the ``lammps`` Python module and create a
LAMMPS instance. This should not generate an error message and produce
output similar to the following:
.. code-block:: bash
.. code-block:: console
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
@ -403,7 +403,7 @@ follows:
- Via ``pip`` into a virtual environment (see above):
.. code-block:: bash
.. code-block:: console
$ source $HOME/myenv/activate
(myenv)$ pip install mpi4py
@ -449,7 +449,7 @@ on a simple test script
.. code-block:: bash
$ mpirun -np 4 python3 test.py
mpirun -np 4 python3 test.py
where ``test.py`` contains the lines
@ -459,11 +459,11 @@ where ``test.py`` contains the lines
comm = MPI.COMM_WORLD
print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))
and see one line of output for each processor you run on.
and see one line of output for each processor you run on. Please note
that the order of the lines is not deterministic
.. code-block:: bash
.. code-block:: console
# NOTE: the line order is not deterministic
$ mpirun -np 4 python3 test.py
Proc 0 out of 4 procs
Proc 1 out of 4 procs

38
doc/src/Python_launch.rst
View File

@ -6,15 +6,15 @@ interactively from the ``bench`` directory:
.. code-block:: python
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
Or put the same lines in the file ``test.py`` and run it as
.. code-block:: bash
$ python3 test.py
python3 test.py
Either way, you should see the results of running the ``in.lj`` benchmark
on a single processor appear on the screen, the same as if you had
@ -46,13 +46,13 @@ You can run the script in parallel as:
.. code-block:: bash
$ mpirun -np 4 python3 test.py
mpirun -np 4 python3 test.py
and you should see the same output as if you had typed
.. code-block:: bash
$ mpirun -np 4 lmp_mpi -in in.lj
mpirun -np 4 lmp_mpi -in in.lj
Note that without the mpi4py specific lines from ``test.py``
@ -82,9 +82,9 @@ one of several ways:
.. code-block:: bash
$ python script.py
$ python -i script.py
$ ./script.py
python script.py
python -i script.py
./script.py
The last command requires that the first line of the script be
something like this:
@ -92,17 +92,23 @@ something like this:
.. code-block:: bash
#!/usr/bin/python
#!/usr/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
or
.. code-block:: bash
$ chmod +x script.py
#!/usr/bin/env python
where the path in the first case needs to point to where you have Python
installed (the second option is workaround for when this may change),
and that you have made the script file executable:
.. code-block:: bash
chmod +x script.py
Without the ``-i`` flag, Python will exit when the script finishes.
With the ``-i`` flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.
the script finishes, so you can type subsequent commands. As mentioned
above, you can only run Python interactively when running Python on a
single processor, not in parallel.

18
doc/src/Python_overview.rst
View File

@ -32,7 +32,7 @@ standard Python distribution since version 2.5. You can check which
version of Python you have by simply typing "python" at a shell prompt.
Below is an example output for Python version 3.8.5.
.. code-block::
.. code-block:: console
$ python
Python 3.8.5 (default, Aug 12 2020, 00:00:00)
@ -43,12 +43,16 @@ Below is an example output for Python version 3.8.5.
.. warning::
The options described in this section of the manual for using Python with
LAMMPS currently support either Python 2 or 3. Specifically version 2.7 or
later and 3.6 or later. Since the Python community no longer maintains Python
2 (see `this notice <https://www.python.org/doc/sunset-python-2/>`_), we
recommend use of Python 3 with LAMMPS. While Python 2 code should continue to
work, that is not something we can guarantee long-term.
The options described in this section of the manual for using Python
with LAMMPS currently support either Python 2 or 3. Specifically
version 2.7 or later and 3.6 or later. Since the Python community no
longer maintains Python 2 (see `this notice
<https://www.python.org/doc/sunset-python-2/>`_), we recommend use of
Python 3 with LAMMPS. While Python 2 code should continue to work,
that is not something we can guarantee long-term. If you notice
Python code in the LAMMPS distribution that is not compatible with
Python 3, please contact the LAMMPS developers or submit `and issue
on GitHub <https://github.com/lammps/lammps/issues>`_
---------

22
doc/src/Run_basics.rst
View File

@ -12,15 +12,15 @@ build LAMMPS:
.. code-block:: bash
$ lmp_serial -in in.file
$ lmp_serial < in.file
$ lmp -in in.file
$ lmp < in.file
$ /path/to/lammps/src/lmp_serial -i in.file
$ mpirun -np 4 lmp_mpi -in in.file
$ mpiexec -np 4 lmp -in in.file
$ mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
$ mpiexec -n 6 /usr/local/bin/lmp -in in.file
lmp_serial -in in.file
lmp_serial < in.file
lmp -in in.file
lmp < in.file
/path/to/lammps/src/lmp_serial -i in.file
mpirun -np 4 lmp_mpi -in in.file
mpiexec -np 4 lmp -in in.file
mpirun -np 8 /path/to/lammps/src/lmp_mpi -in in.file
mpiexec -n 6 /usr/local/bin/lmp -in in.file
You normally run the LAMMPS command in the directory where your input
script is located. That is also where output files are produced by
@ -78,8 +78,8 @@ variable OMP_NUM_THREADS, before you launch LAMMPS:
.. code-block:: bash
$ export OMP_NUM_THREADS=2 # bash
$ setenv OMP_NUM_THREADS 2 # csh or tcsh
export OMP_NUM_THREADS=2 # bash
setenv OMP_NUM_THREADS 2 # csh or tcsh
This can also be done via the :doc:`package <package>` command or via
the :doc:`-pk command-line switch <Run_options>` which invokes the

4
doc/src/Run_options.rst
View File

@ -31,8 +31,8 @@ For example, the lmp_mpi executable might be launched as follows:
.. code-block:: bash
$ mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
$ mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy
mpirun -np 16 lmp_mpi -v f tmp.out -l my.log -sc none -i in.alloy
mpirun -np 16 lmp_mpi -var f tmp.out -log my.log -screen none -in in.alloy
----------

40
doc/src/Tools.rst
View File

@ -683,7 +683,7 @@ or (as administrator) to ``/etc/magic`` (for a system-wide
installation). Afterwards the ``file`` command should be able to
detect most LAMMPS restarts, dump, data and log files. Examples:
.. code-block:: bash
.. code-block:: console
$ file *.*
dihedral-quadratic.restart: LAMMPS binary restart file (rev 2), Version 10 Mar 2021, Little Endian
@ -1100,18 +1100,18 @@ for Tcl with:
.. code-block:: bash
$ swig -tcl -module tcllammps lammps.i
$ gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
swig -tcl -module tcllammps lammps.i
gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
lammps_wrap.c -L ../src/ -llammps
$ tclsh
tclsh
Or one can build an extended Tcl shell command with the wrapped
functions included with:
.. code-block:: bash
$ swig -tcl -module tcllmps lammps_shell.i
$ gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \
swig -tcl -module tcllmps lammps_shell.i
gcc -o tcllmpsh lammps_wrap.c -Xlinker -export-dynamic \
-DHAVE_CONFIG_H $(pkgconf --cflags tcl) \
$(pkgconf --libs tcl) -L ../src -llammps
@ -1142,20 +1142,20 @@ For illustration purposes below is a part of the Tcl example script.
.. code-block:: tcl
% load ./tcllammps.so
% set lmp [lammps_open_no_mpi 0 NULL NULL]
% lammps_command $lmp "units real"
% lammps_command $lmp "lattice fcc 2.5"
% lammps_command $lmp "region box block -5 5 -5 5 -5 5"
% lammps_command $lmp "create_box 1 box"
% lammps_command $lmp "create_atoms 1 box"
%
% set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]]
% puts "LAMMPS version $ver"
% puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]]
% puts "Current size of timestep: $dt"
% puts "LAMMPS version: [lammps_version $lmp]"
% lammps_close $lmp
load ./tcllammps.so
set lmp [lammps_open_no_mpi 0 NULL NULL]
lammps_command $lmp "units real"
lammps_command $lmp "lattice fcc 2.5"
lammps_command $lmp "region box block -5 5 -5 5 -5 5"
lammps_command $lmp "create_box 1 box"
lammps_command $lmp "create_atoms 1 box"
set dt [doublep_value [voidp_to_doublep [lammps_extract_global $lmp dt]]]
puts "LAMMPS version $ver"
puts [format "Number of created atoms: %g" [lammps_get_natoms $lmp]]
puts "Current size of timestep: $dt"
puts "LAMMPS version: [lammps_version $lmp]"
lammps_close $lmp
----------

94
doc/src/angle_lepton.rst Normal file
View File

@ -0,0 +1,94 @@
.. index:: angle_style lepton
.. index:: angle_style lepton/omp
angle_style lepton command
==========================
Accelerator Variants: *lepton/omp*
Syntax
""""""
.. code-block:: LAMMPS
angle_style lepton
Examples
""""""""
.. code-block:: LAMMPS
angle_style lepton
angle_coeff 1 120.0 "k*theta^2; k=250.0"
angle_coeff 2 90.0 "k2*theta^2 + k3*theta^3 + k4*theta^4; k2=300.0; k3=-100.0; k4=50.0"
angle_coeff 3 109.47 "k*theta^2; k=350.0"
Description
"""""""""""
.. versionadded:: TBD
Angle style *lepton* computes angular interactions between three atoms
with a custom potential function. The potential function must be
provided as an expression string using "theta" as the angle variable
relative to the reference angle :math:`\theta_0` which is provided as an
angle coefficient. For example `"200.0*theta^2"` represents a
:doc:`harmonic angle <angle_harmonic>` potential with a force constant
*K* of 200.0 energy units:
.. math::
U_{angle,i} = K (\theta_i - \theta_0)^2 = K \theta^2 \qquad \theta = \theta_i - \theta_0
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* angle style interfaces with, evaluates this expression string
at run time to compute the pairwise energy. It also creates an
analytical representation of the first derivative of this expression
with respect to "theta" and then uses that to compute the force between
the angle atoms as defined by the topology data.
The following coefficients must be defined for each angle type via the
:doc:`angle_coeff <angle_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:
* Lepton expression (energy units)
* :math:`\theta_0` (degrees)
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. The :math:`\theta_0`
coefficient is the "equilibrium angle". It is entered in degrees, but
internally converted to radians. Thus the expression must assume
"theta" is in radians. The potential energy function in the Lepton
expression is shifted in such a way, that the potential energy is 0 for
a angle :math:`\theta_i == \theta_0`.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This angle style is part of the LEPTON package and only enabled if LAMMPS
was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_style table <angle_table>`,
:doc:`bond_style lepton <bond_lepton>`,:doc:`dihedral_style lepton <dihedral_lepton>`
Default
"""""""
none

3
doc/src/angle_style.rst
View File

@ -10,7 +10,7 @@ Syntax
angle_style style
* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *mm3* or *quartic* or *spica* or *table*
* style = *none* or *zero* or *hybrid* or *amoeba* or *charmm* or *class2* or *class2/p6* or *cosine* or *cosine/buck6d* or *cosine/delta* or *cosine/periodic* or *cosine/shift* or *cosine/shift/exp* or *cosine/squared* or *cross* or *dipole* or *fourier* or *fourier/simple* or *gaussian* or *harmonic* or *lepton* or *mm3* or *quartic* or *spica* or *table*
Examples
""""""""
@ -90,6 +90,7 @@ of (g,i,k,o,t) to indicate which accelerated styles exist.
* :doc:`fourier/simple <angle_fourier_simple>` - angle with a single cosine term
* :doc:`gaussian <angle_gaussian>` - multi-centered Gaussian-based angle potential
* :doc:`harmonic <angle_harmonic>` - harmonic angle
* :doc:`lepton <angle_lepton>` - angle potential from evaluating a string
* :doc:`mesocnt <angle_mesocnt>` - piecewise harmonic and linear angle for bending-buckling of nanotubes
* :doc:`mm3 <angle_mm3>` - anharmonic angle
* :doc:`quartic <angle_quartic>` - angle with cubic and quartic terms

11
doc/src/angle_table.rst
View File

@ -59,9 +59,12 @@ format of this file is described below.
----------
Suitable tables for use with this angle style can be created using the
Python code in the ``tools/tabulate`` folder of the LAMMPS source code
distribution.
Suitable tables for use with this angle style can be created by LAMMPS
itself from existing angle styles using the :doc:`angle_write
<angle_write>` command. This can be useful to have a template file for
testing the angle style settings and to build a compatible custom file.
Another option to generate tables is the Python code in the
``tools/tabulate`` folder of the LAMMPS source code distribution.
The format of a tabulated file is as follows (without the
parenthesized comments):
@ -154,7 +157,7 @@ for more info.
Related commands
""""""""""""""""
:doc:`angle_coeff <angle_coeff>`
:doc:`angle_coeff <angle_coeff>`, :doc:`angle_write <angle_write>`
Default
"""""""

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

@ -0,0 +1,99 @@
.. index:: angle_write
angle_write command
===================
Syntax
""""""
.. code-block:: LAMMPS
angle_write atype N file keyword
* atype = angle type
* N = # of values
* file = name of file to write values to
* keyword = section name in file for this set of tabulated values
Examples
""""""""
.. code-block:: LAMMPS
angle_write 1 500 table.txt Harmonic_1
angle_write 3 1000 table.txt Harmonic_3
Description
"""""""""""
.. versionadded:: TBD
Write energy and force values to a file as a function of angle for the
currently defined angle potential. Force in this context means the
force with respect to the angle, not the force on individual atoms.
This is useful for plotting the potential function or otherwise
debugging its values. The resulting file can also be used as input for
use with :doc:`angle style table <angle_table>`.
If the file already exists, the table of values is appended to the end
of the file to allow multiple tables of energy and force to be included
in one file. The individual sections may be identified by the *keyword*.
The energy and force values are computed for angles ranging from 0
degrees to 180 degrees for 3 interacting atoms forming an angle type
atype, using the appropriate :doc:`angle_coeff <angle_coeff>`
coefficients. N evenly spaced angles are used.
For example, for N = 6, values are computed at :math:`\theta = 0, 36,
72, 108, 144, 180`.
The file is written in the format used as input for the
:doc:`angle_style table <angle_table>` option with *keyword* as the
section name. Each line written to the file lists an index number
(1-N), an angle (in degrees), an energy (in energy units), and a force
(in force units per radians^2). In case a new file is created, the
first line will be a comment with a "DATE:" and "UNITS:" tag with the
current date and :doc:`units <units>` settings. For subsequent
invocations of the *angle_write* command for the same file, data will be
appended and the current units settings will be compared to the data
from the header, if present. The *angle_write* will refuse to add a
table to an existing file if the units are not the same.
Restrictions
""""""""""""
All force field coefficients for angle and other kinds of interactions
must be set before this command can be invoked.
The table of the angle energy and force data data is created by using a
separate, internally created, new LAMMPS instance with a dummy system of
3 atoms for which the angle potential energy is computed after
transferring the angle style and coefficients and arranging the 3 atoms
into the corresponding geometries. The angle force is then determined
from the potential energies through numerical differentiation. As a
consequence of this approach, not all angle styles are compatible. The
following conditions must be met:
- The angle style must be able to write its coefficients to a data file.
This condition excludes for example :doc:`angle style hybrid <angle_hybrid>` and
:doc:`angle style table <angle_table>`.
- The potential function must not have any terms that depend on geometry
properties other than the angle. This condition excludes for example
:doc:`angle style class2 <angle_class2>` all angle types for
:doc:`angle style charmm <angle_charmm>` that have non-zero
Urey-Bradley terms. Please note that the *write_angle* command has no
way of checking for this condition, so the resulting tables may be
bogus if the requirement is not met. It is thus recommended to make
careful tests for any created tables.
Related commands
""""""""""""""""
:doc:`angle_style table <angle_table>`, :doc:`bond_write <bond_write>`,
:doc:`dihedral_write <dihedral_write>`, :doc:`angle_style <angle_style>`,
:doc:`angle_coeff <angle_coeff>`
Default
"""""""
none

92
doc/src/bond_lepton.rst Normal file
View File

@ -0,0 +1,92 @@
.. index:: bond_style lepton
.. index:: bond_style lepton/omp
bond_style lepton command
=========================
Accelerator Variants: *lepton/omp*
Syntax
""""""
.. code-block:: LAMMPS
bond_style lepton
Examples
""""""""
.. code-block:: LAMMPS
bond_style lepton
bond_coeff 1 1.5 "k*r^2; k=250.0"
bond_coeff 2 1.1 "k2*r^2 + k3*r^3 + k4*r^4; k2=300.0; k3=-100.0; k4=50.0"
bond_coeff 3 1.3 "k*r^2; k=350.0"
Description
"""""""""""
.. versionadded:: TBD
Bond style *lepton* computes bonded interactions between two atoms with
a custom function. The potential function must be provided as an
expression string using "r" as the distance variable relative to the
reference distance :math:`r_0` which is provided as a bond coefficient.
For example `"200.0*r^2"` represents a harmonic potential with a force
constant *K* of 200.0 energy units:
.. math::
U_{bond,i} = K (r_i - r_0)^2 = K r^2 \qquad r = r_i - r_0
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* bond style interfaces with, evaluates this expression string at
run time to compute the pairwise energy. It also creates an analytical
representation of the first derivative of this expression with respect to
"r" and then uses that to compute the force between the atom pairs forming
bonds as defined by the topology data.
The following coefficients must be defined for each bond type via the
:doc:`bond_coeff <bond_coeff>` command as in the examples above, or in
the data file or restart files read by the :doc:`read_data <read_data>`
or :doc:`read_restart <read_restart>` commands:
* Lepton expression (energy units)
* :math:`r_0` (distance)
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. The :math:`r_0` is the
"equilibrium distance". The potential energy function in the Lepton
expression is shifted in such a way, that the potential energy is 0 for
a bond length :math:`r_i == r_0`.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This bond style is part of the LEPTON package and only enabled if LAMMPS
was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`bond_coeff <bond_coeff>`, :doc:`bond_style table <bond_table>`,
:doc:`bond_write <bond_write>`, :doc:`angle_style lepton <angle_lepton>`,
:doc:`dihedral_style lepton <dihedral_lepton>`
Default
"""""""
none

3
doc/src/bond_style.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_style style args
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* style = *none* or *zero* or *hybrid* or *bpm/rotational* or *bpm/spring* or *class2* or *fene* or *fene/expand* or *fene/nm* or *gaussian* or *gromos* or *harmonic* or *harmonic/shift* or *harmonic/shift/cut* or *lepton* or *morse* or *nonlinear* or *oxdna/fene* or *oxdena2/fene* or *oxrna2/fene* or *quartic* or *special* or *table*
* args = none for any style except *hybrid*
@ -95,6 +95,7 @@ accelerated styles exist.
* :doc:`harmonic <bond_harmonic>` - harmonic bond
* :doc:`harmonic/shift <bond_harmonic_shift>` - shifted harmonic bond
* :doc:`harmonic/shift/cut <bond_harmonic_shift_cut>` - shifted harmonic bond with a cutoff
* :doc:`lepton <bond_lepton>` - bond potential from evaluating a string
* :doc:`mesocnt <bond_mesocnt>` - Harmonic bond wrapper with parameterization presets for nanotubes
* :doc:`mm3 <bond_mm3>` - MM3 anharmonic bond
* :doc:`morse <bond_morse>` - Morse bond

47
doc/src/bond_write.rst
View File

@ -10,7 +10,7 @@ Syntax
bond_write btype N inner outer file keyword itype jtype
* btype = bond types
* btype = bond type
* N = # of values
* inner,outer = inner and outer bond length (distance units)
* file = name of file to write values to
@ -29,31 +29,34 @@ Description
"""""""""""
Write energy and force values to a file as a function of distance for
the currently defined bond potential. This is useful for plotting the
potential function or otherwise debugging its values. If the file
already exists, the table of values is appended to the end of the file
to allow multiple tables of energy and force to be included in one
file.
the currently defined :doc:`bond style <bond_style>` for a selected bond
type. This is useful for plotting the potential function or otherwise
debugging its values. The resulting file can also be used as input for
use with :doc:`bond style table <bond_table>`.
The energy and force values are computed at distances from inner to
outer for 2 interacting atoms forming a bond of type btype, using the
appropriate :doc:`bond_coeff <bond_coeff>` coefficients. N evenly spaced
distances are used.
If the file already exists, the table of values is appended to the end
of the file to allow multiple tables of energy and force to be included
in one file. The individual sections may be identified by the *keyword*.
The energy and force values are computed at distances from *inner* to
*outer* for 2 interacting atoms forming a bond of type *btype*, using
the appropriate :doc:`bond_coeff <bond_coeff>` coefficients. N evenly
spaced distances are used.
For example, for N = 7, inner = 1.0, and outer = 4.0,
values are computed at r = 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0.
The file is written in the format used as input for the
:doc:`bond_style <bond_style>` *table* option with *keyword* as the
section name. Each line written to the file lists an index number
(1-N), a distance (in distance units), an energy (in energy units),
and a force (in force units). In case a new file is created, the first
line will be a comment with a "DATE:" and "UNITS:" tag with the current
date and :doc:`units <units>` settings. For subsequent invocations of
the bond_write command for the same file, data will be appended and the
current units settings will be compared to the data from the header, if
present, and bond_write will refuse to add a table if the units are not
the same.
The file is written in the format used as input for the :doc:`bond_style
table <bond_table>` option with *keyword* as the section name. Each
line written to the file lists an index number (1-N), a distance (in
distance units), an energy (in energy units), and a force (in force
units). In case a new file is created, the first line will be a comment
with a "DATE:" and "UNITS:" tag with the current date and :doc:`units
<units>` settings. For subsequent invocations of the *bond_write*
command for the same file, data will be appended and the current units
settings will be compared to the data from the header, if present. The
*bond_write* command will refuse to add a table to an existing file if
the units are not the same.
Restrictions
""""""""""""
@ -67,7 +70,7 @@ be specified even if the potential has a finite value at r = 0.0.
Related commands
""""""""""""""""
:doc:`bond_style table <bond_table>`,
:doc:`bond_style table <bond_table>`, `angle_write <angle_write>`,
:doc:`bond_style <bond_style>`, :doc:`bond_coeff <bond_coeff>`
Default

2
doc/src/commands_list.rst
View File

@ -6,6 +6,7 @@ Commands
angle_coeff
angle_style
angle_write
atom_modify
atom_style
balance
@ -27,6 +28,7 @@ Commands
dielectric
dihedral_coeff
dihedral_style
dihedral_write
dimension
displace_atoms
dump

1
doc/src/compute.rst
View File

@ -211,6 +211,7 @@ The individual style names on the :doc:`Commands compute <Commands_compute>` pag
* :doc:`dpd/atom <compute_dpd_atom>` - per-particle values of internal conductive energy, internal mechanical energy, chemical energy, and internal temperature
* :doc:`edpd/temp/atom <compute_edpd_temp_atom>` - per-atom temperature for each eDPD particle in a group
* :doc:`efield/atom <compute_efield_atom>` - electric field at each atom
* :doc:`efield/wolf/atom <compute_efield_wolf_atom>` - electric field at each atom
* :doc:`entropy/atom <compute_entropy_atom>` - pair entropy fingerprint of each atom
* :doc:`erotate/asphere <compute_erotate_asphere>` - rotational energy of aspherical particles
* :doc:`erotate/rigid <compute_erotate_rigid>` - rotational energy of rigid bodies

126
doc/src/compute_efield_wolf_atom.rst Normal file
View File

@ -0,0 +1,126 @@
.. index:: compute efield/wolf/atom
compute efield/wolf/atom command
================================
Syntax
""""""
.. code-block:: LAMMPS
compute ID group-ID efield/wolf/atom alpha keyword val
* ID, group-ID are documented in :doc:`compute <compute>` command
* efield/atom/wolf = style name of this compute command
* alpha = damping parameter (inverse distance units)
* zero or more keyword/value pairs may be appended
* keyword = *limit* or *cutoff*
.. parsed-literal::
*limit* group2-ID = limit computing the electric field contributions to a group (default: all)
*cutoff* value = set cutoff for computing contributions to this value (default: maximum cutoff of pair style)
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all efield/wolf/atom 0.2
compute 1 mols efield/wolf/atom 0.25 limit water cutoff 10.0
Description
"""""""""""
.. versionadded:: TBD
Define a computation that approximates the electric field at each atom in a group.
.. math::
\vec{E}_i = \frac{\vec{F}coul_i}{q_i} = \sum_{j \neq i} \frac{q_j}{r_{ij}^2} \qquad r < r_c
The electric field at the position of the atom *i* is the coulomb force
on a unit charge at that point, which is equivalent to dividing the
Coulomb force by the charge of the individual atom.
In this compute the electric field is approximated as the derivative of
the potential energy using the Wolf summation method, described in
:ref:`Wolf <Wolf4>`, given by:
.. math::
E_i = \frac{1}{2} \sum_{j \neq i}
\frac{q_i q_j {\rm erfc}(\alpha r_{ij})}{r_{ij}} +
\frac{1}{2} \sum_{j \neq i}
\frac{q_i q_j {\rm erf}(\alpha r_{ij})}{r_{ij}} \qquad r < r_c
where :math:`\alpha` is the damping parameter, and *erf()* and *erfc()*
are error-function and complementary error-function terms. This
potential is essentially a short-range, spherically-truncated,
charge-neutralized, force-shifted, pairwise *1/r* summation. With a
manipulation of adding and subtracting a self term (for i = j) to the
first and second term on the right-hand-side, respectively, and a small
enough :math:`\alpha` damping parameter, the second term shrinks and the
potential becomes a rapidly-converging real-space summation. With a
long enough cutoff and small enough :math:`\alpha` parameter, the
electric field calculated by the Wolf summation method approaches that
computed using the Ewald sum.
The value of the electric field components will be 0.0 for atoms not in
the specified compute group.
When the *limit* keyword is used, only contributions from atoms in the
selected group will be considered, otherwise contributions from all
atoms within the cutoff are included.
When the *cutoff* keyword is used, the cutoff used for the electric
field approximation can be set explicitly. By default it is the largest
cutoff of any pair style force computation.
.. admonition:: Computational Efficiency
:class: note
This compute will loop over a full neighbor list just like a pair
style does when computing forces, thus it can be quite time consuming
and slow down a calculation significantly when its data is used in
every time step. The :doc:`compute efield/atom
<compute_efield_atom>` command of the DIELECTRIC package is more
efficient in comparison, since the electric field data is collected
and stored as part of the force computation at next to no extra
computational cost.
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>` page for an overview of
LAMMPS output options.
The vector contains 3 values per atom which are the x-, y-, and
z-direction electric field components in force units.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package.
Related commands
""""""""""""""""
:doc:`pair_style coul/wolf <pair_coul>`,
:doc:`compute efield/atom <compute_efield_atom>`
Default
"""""""
The option defaults are *limit* = all and *cutoff* = largest cutoff
for pair styles.
----------
.. _Wolf4:
**(Wolf)** D. Wolf, P. Keblinski, S. R. Phillpot, J. Eggebrecht, J Chem
Phys, 110, 8254 (1999).

89
doc/src/dihedral_lepton.rst Normal file
View File

@ -0,0 +1,89 @@
.. index:: dihedral_style lepton
.. index:: dihedral_style lepton/omp
dihedral_style lepton command
=============================
Accelerator Variants: *lepton/omp*
Syntax
""""""
.. code-block:: LAMMPS
dihedral_style lepton
Examples
""""""""
.. code-block:: LAMMPS
dihedral_style lepton
dihedral_coeff 1 "k*(1 + d*cos(n*phi)); k=75.0; d=1; n=2"
dihedral_coeff 2 "45*(1-cos(4*phi))"
dihedral_coeff 2 "k2*cos(phi) + k3*cos(phi)^2; k2=100.0"
dihedral_coeff 3 "k*(phi-phi0)^2; k=85.0; phi0=120.0"
Description
"""""""""""
.. versionadded:: TBD
Dihedral style *lepton* computes dihedral interactions between four
atoms forming a dihedral angle with a custom potential function. The
potential function must be provided as an expression string using "phi"
as the dihedral angle variable. For example `"200.0*(phi-120.0)^2"`
represents a :doc:`quadratic dihedral <dihedral_quadratic>` potential
around a 120 degree dihedral angle with a force constant *K* of 200.0
energy units:
.. math::
U_{dihedral,i} = K (\phi_i - \phi_0)^2
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* dihedral style interfaces with, evaluates this expression
string at run time to compute the pairwise energy. It also creates an
analytical representation of the first derivative of this expression
with respect to "phi" and then uses that to compute the force between
the dihedral atoms as defined by the topology data.
The potential function expression for each dihedral type is provided via the
:doc:`dihedral_coeff <dihedral_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 expression is in energy units.
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. Dihedral angles are internally
computed in radians and thus the expression must assume "phi" is in
radians.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Restrictions
""""""""""""
This dihedral style is part of the LEPTON package and only enabled if LAMMPS
was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`dihedral_coeff <dihedral_coeff>`, :doc:`dihedral_style table <dihedral_table>`,
:doc:`bond_style lepton <bond_lepton>`, :doc:`angle_style lepton <angle_lepton>`
Default
"""""""
none

2
doc/src/dihedral_nharmonic.rst
View File

@ -28,7 +28,7 @@ The *nharmonic* dihedral style uses the potential:
.. math::
E = \sum_{n=1,n} A_n \cos^{n-1}(\phi)
E = \sum_{i=1,n} A_i \cos^{i-1}(\phi)
The following coefficients must be defined for each dihedral type via the
:doc:`dihedral_coeff <dihedral_coeff>` command as in the example above, or in

3
doc/src/dihedral_style.rst
View File

@ -10,7 +10,7 @@ Syntax
dihedral_style style
* style = *none* or *zero* or *hybrid* or *charmm* or *charmmfsw* or *class2* or *osine/shift/exp* or *fourier* or *harmonic* or *helix* or *multi/harmonic* or *nharmonic* or *opls* or *spherical* or *table* or *table/cut*
* style = *none* or *zero* or *hybrid* or *charmm* or *charmmfsw* or *class2* or *cosine/shift/exp* or *fourier* or *harmonic* or *helix* or *lepton* or *multi/harmonic* or *nharmonic* or *opls* or *spherical* or *table* or *table/cut*
Examples
""""""""
@ -108,6 +108,7 @@ exist.
* :doc:`fourier <dihedral_fourier>` - dihedral with multiple cosine terms
* :doc:`harmonic <dihedral_harmonic>` - harmonic dihedral
* :doc:`helix <dihedral_helix>` - helix dihedral
* :doc:`lepton <dihedral_lepton>` - dihedral potential from evaluating a string
* :doc:`multi/harmonic <dihedral_multi_harmonic>` - dihedral with 5 harmonic terms
* :doc:`nharmonic <dihedral_nharmonic>` - same as multi-harmonic with N terms
* :doc:`opls <dihedral_opls>` - OPLS dihedral

14
doc/src/dihedral_table.rst
View File

@ -80,10 +80,10 @@ For dihedral style *table/cut* the following coefficients must be
defined for each dihedral type via the :doc:`dihedral_coeff
<dihedral_coeff>` command as in the example above.
* style (aat)
* cutoff prefactor
* cutoff angle1
* cutoff angle2
* style (= aat)
* cutoff prefactor (unitless)
* cutoff angle1 (degrees)
* cutoff angle2 (degrees)
* filename
* keyword
@ -95,9 +95,9 @@ cutoff function:
f(\theta) & = K \qquad\qquad\qquad\qquad\qquad\qquad \theta < \theta_1 \\
f(\theta) & = K \left(1-\frac{(\theta - \theta_1)^2}{(\theta_2 - \theta_1)^2}\right) \qquad \theta_1 < \theta < \theta_2
The cutoff specifies an prefactor to the cutoff function. While this
value would ordinarily equal 1 there may be situations where the value
should change.
The cutoff includes a prefactor *K* to the cutoff function :math:`f(\theta)`.
While this value would ordinarily be 1, there may be situations where the value
could be different.
The cutoff :math:`\theta_1` specifies the angle (in degrees) below which
the dihedral interaction is unmodified, i.e. the cutoff function is 1.

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

@ -0,0 +1,101 @@
.. index:: dihedral_write
dihedral_write command
======================
Syntax
""""""
.. code-block:: LAMMPS
dihedral_write dtype N file keyword
* dtype = dihedral type
* N = # of values
* file = name of file to write values to
* keyword = section name in file for this set of tabulated values
Examples
""""""""
.. code-block:: LAMMPS
dihedral_write 1 500 table.txt Harmonic_1
dihedral_write 3 1000 table.txt Harmonic_3
Description
"""""""""""
.. versionadded:: TBD
Write energy and force values to a file as a function of the dihedral
angle for the currently defined dihedral potential. Force in this
context means the force with respect to the dihedral angle, not the
force on individual atoms. This is useful for plotting the potential
function or otherwise debugging its values. The resulting file can also
be used as input for use with :doc:`dihedral style table
<dihedral_table>`.
If the file already exists, the table of values is appended to the end
of the file to allow multiple tables of energy and force to be included
in one file. The individual sections may be identified by the *keyword*.
The energy and force values are computed for dihedrals ranging from 0
degrees to 360 degrees for 4 interacting atoms forming an dihedral type
dtype, using the appropriate :doc:`dihedral_coeff <dihedral_coeff>`
coefficients. N evenly spaced dihedrals are used. Since 0 and 360
degrees are the same dihedral angle, the latter entry is skipped.
For example, for N = 6, values would be computed at
:math:`\phi = 0, 60, 120, 180, 240, 300`.
The file is written in the format used as input for the
:doc:`dihedral_style table <dihedral_table>` option with *keyword* as
the section name. Each line written to the file lists an index number
(1-N), an dihedral angle (in degrees), an energy (in energy units), and
a force (in force units per radians^2). In case a new file is created,
the first line will be a comment with a "DATE:" and "UNITS:" tag with
the current date and :doc:`units <units>` settings. For subsequent
invocations of the *dihedral_write* command for the same file, data will
be appended and the current units settings will be compared to the data
from the header, if present. The *dihedral_write* will refuse to add a
table to an existing file if the units are not the same.
Restrictions
""""""""""""
All force field coefficients for dihedrals and other kinds of interactions
must be set before this command can be invoked.
The table of the dihedral energy and force data data is created by using a
separate, internally created, new LAMMPS instance with a dummy system of
4 atoms for which the dihedral potential energy is computed after
transferring the dihedral style and coefficients and arranging the 4 atoms
into the corresponding geometries. The dihedral force is then determined
from the potential energies through numerical differentiation. As a
consequence of this approach, not all dihedral styles are compatible. The
following conditions must be met:
- The dihedral style must be able to write its coefficients to a data file.
This condition excludes for example :doc:`dihedral style hybrid <dihedral_hybrid>` and
:doc:`dihedral style table <dihedral_table>`.
- The potential function must not have any terms that depend on geometry
properties other than the dihedral. This condition excludes for
example :doc:`dihedral style class2 <dihedral_class2>`. Please note
that the *write_dihedral* command has no way of checking for this
condition. It will check the style name against an internal list of
known to be incompatible styles. The resulting tables may be bogus
for unlisted dihedral styles if the requirement is not met. It is
thus recommended to make careful tests for any created tables.
Related commands
""""""""""""""""
:doc:`dihedral_style table <dihedral_table>`, :doc:`bond_write <bond_write>`,
:doc:`angle_write <angle_write>`, :doc:`dihedral_style <dihedral_style>`,
:doc:`dihedral_coeff <dihedral_coeff>`
Default
"""""""
none

40
doc/src/dump.rst
View File

@ -242,6 +242,14 @@ all the processors or multiple smaller files.
data for a single snapshot is collected from multiple processors,
each of which owns a subset of the atoms.
.. warning::
Without either including atom IDs or using the :doc:`dump_modify sort
<dump_modify>` option, it is impossible for visualization programs
(e.g. OVITO or VMD) or analysis tools to assign data in different
frames consistently to the same atom. This can lead to incorrect
visualizations or results. LAMMPS will print a warning in such cases.
For the *atom*, *custom*, *cfg*, *grid*, and *local* styles, sorting
is off by default. For the *dcd*, *grid/vtk*, *xtc*, *xyz*, and
*molfile* styles, sorting by atom ID or grid ID is on by default. See
@ -355,22 +363,32 @@ attributes is given below.
.. versionadded:: 22Dec2022
For style *grid* the extent of the Nx by Ny by Nz grid that overlays
the simulation domain is output with each snapshot:
For style *grid* the dimension of the simulation domain and size of
the Nx by Ny by Nz grid that overlays the simulation domain are also
output with each snapshot:
.. parsed-literal::
ITEM: GRID EXTENT
ITEM: DIMENSION
dim
ITEM: GRID SIZE
nx ny nz
For 2d simulations, nz will be 1. There will also be an "ITEM: GRID
DATA" line which includes column descriptors for the per grid cell
data. Each subsequent line (Nx * Ny * Nz lines) will list the data
for a single grid cell. If grid cell IDs are included in the output
via the :doc:`compute property/grid <compute_property_grid>` command,
then the IDs will range from 1 to N = Nx*Ny*Nz. The ordering of IDs
is with the x index varying fastest, then the y index, and the z index
varying slowest.
The value dim will be 2 or 3 for 2d or 3d simulations. It is included
so that post-processing tools like `OVITO <https://www.ovito.org>`,
which can visualize grid-based quantities know how to draw each grid
cell. The grid size will match the input script parameters for
grid(s) created by the computes or fixes which are referenced by the
the dump command. For 2d simulations (and grids), nz will always
be 1.
There will also be an "ITEM: GRID DATA" line which includes column
descriptors for the per grid cell data. Each subsequent line (Nx *
Ny * Nz lines) will list the data for a single grid cell. If grid
cell IDs are included in the output via the :doc:`compute
property/grid <compute_property_grid>` command, then the IDs will
range from 1 to N = Nx*Ny*Nz. The ordering of IDs is with the x index
varying fastest, then the y index, and the z index varying slowest.
For style *local*, local output generated by :doc:`computes <compute>`
and :doc:`fixes <fix>` is used to generate lines of output that is

10
doc/src/dump_image.rst
View File

@ -621,8 +621,8 @@ MPEG or other movie file you can use:
.. code-block:: bash
% convert *.jpg foo.gif
% convert -loop 1 *.ppm foo.mpg
convert *.jpg foo.gif
convert -loop 1 *.ppm foo.mpg
Animated GIF files from ImageMagick are not optimized. You can use
a program like gifsicle to optimize and thus massively shrink them.
@ -668,8 +668,8 @@ Play the movie:
.. code-block:: bash
% mplayer foo.mpg
% ffplay bar.avi
mplayer foo.mpg
ffplay bar.avi
* c) Use the `Pizza.py <https://lammps.github.io/pizza>`_
`animate tool <https://lammps.github.io/pizza/doc/animate.html>`_,
@ -679,7 +679,7 @@ Play the movie:
a = animate("foo*.jpg")
* d) QuickTime and other Windows- or MacOS-based media players can
* d) QuickTime and other Windows- or macOS-based media players can
obviously play movie files directly. Similarly for corresponding tools
bundled with Linux desktop environments. However, due to licensing
issues with some file formats, the formats may require installing

2
doc/src/dump_modify.rst
View File

@ -297,6 +297,8 @@ in file tmp.times:
----------
.. versionadded:: 7Jan2022
The *every/time* keyword can be used with any dump style except the
*dcd* and *xtc* styles. It changes the frequency of dump snapshots
from being based on the current timestep to being determined by

2
doc/src/fix_adapt.rst
View File

@ -120,7 +120,7 @@ The *pstyle* argument is the name of the pair style. If
:doc:`pair_style hybrid or hybrid/overlay <pair_hybrid>` is used,
*pstyle* should be a sub-style name. If there are multiple
sub-styles using the same pair style, then *pstyle* should be specified
as "style:N", where :math:`N` is which instance of the pair style you wish to
as "style:N", where *N* is which instance of the pair style you wish to
adapt (e.g., the first or second). For example, *pstyle* could be
specified as "soft" or "lubricate" or "lj/cut:1" or "lj/cut:2". The
*pparam* argument is the name of the parameter to change. This is the

100
doc/src/fix_atom_swap.rst
View File

@ -44,56 +44,55 @@ Examples
Description
"""""""""""
This fix performs Monte Carlo swaps of atoms of one given atom type
with atoms of the other given atom types. The specified :math:`T` is used in
the Metropolis criterion dictating swap probabilities.
This fix performs Monte Carlo swaps of atoms of one given atom type with
atoms of the other given atom types. The specified scaling temperature
*T* is used in the Metropolis criterion dictating swap probabilities.
Perform :math:`X` swaps of atoms of one type with atoms of another type
Perform *X* swaps of atoms of one type with atoms of another type
according to a Monte Carlo probability. Swap candidates must be in the
fix group, must be in the region (if specified), and must be of one of
the listed types. Swaps are attempted between candidates that are
chosen randomly with equal probability among the candidate
atoms. Swaps are not attempted between atoms of the same type since
nothing would happen.
the listed types. Swaps are attempted between candidates that are chosen
randomly with equal probability among the candidate atoms. Swaps are not
attempted between atoms of the same type since nothing would happen.
All atoms in the simulation domain can be moved using regular time
integration displacements (e.g., via :doc:`fix nvt <fix_nh>`), resulting
in a hybrid MC+MD simulation. A smaller-than-usual timestep size may
be needed when running such a hybrid simulation, especially if the
swapped atoms are not well equilibrated.
in a hybrid MC+MD simulation. A smaller-than-usual timestep size may be
needed when running such a hybrid simulation, especially if the swapped
atoms are not well equilibrated.
The *types* keyword is required. At least two atom types must be
specified. If not using *semi-grand*, exactly two atom types
are required.
specified. If not using *semi-grand*, exactly two atom types are
required.
The *ke* keyword can be set to *no* to turn off kinetic energy
conservation for swaps. The default is *yes*, which means that swapped
atoms have their velocities scaled by the ratio of the masses of the
swapped atom types. This ensures that the kinetic energy of each atom
is the same after the swap as it was before the swap, even though the
atom masses have changed.
swapped atom types. This ensures that the kinetic energy of each atom is
the same after the swap as it was before the swap, even though the atom
masses have changed.
The *semi-grand* keyword can be set to *yes* to switch to the
semi-grand canonical ensemble as discussed in :ref:`(Sadigh)
<Sadigh>`. This means that the total number of each particle type does
not need to be conserved. The default is *no*, which means that the
only kind of swap allowed exchanges an atom of one type with an atom
of a different given type. In other words, the relative mole fractions
of the swapped atoms remains constant. Whereas in the semi-grand
canonical ensemble, the composition of the system can change. Note
that when using *semi-grand*, atoms in the fix group whose type is not
listed in the *types* keyword are ineligible for attempted
conversion. An attempt is made to switch the selected atom (if
eligible) to one of the other listed types with equal probability.
Acceptance of each attempt depends upon the Metropolis criterion.
The *semi-grand* keyword can be set to *yes* to switch to the semi-grand
canonical ensemble as discussed in :ref:`(Sadigh) <Sadigh>`. This means
that the total number of each particle type does not need to be
conserved. The default is *no*, which means that the only kind of swap
allowed exchanges an atom of one type with an atom of a different given
type. In other words, the relative mole fractions of the swapped atoms
remains constant. Whereas in the semi-grand canonical ensemble, the
composition of the system can change. Note that when using *semi-grand*,
atoms in the fix group whose type is not listed in the *types* keyword
are ineligible for attempted conversion. An attempt is made to switch
the selected atom (if eligible) to one of the other listed types with
equal probability. Acceptance of each attempt depends upon the
Metropolis criterion.
The *mu* keyword allows users to specify chemical potentials. This is
required and allowed only when using *semi-grand*\ . All chemical
potentials are absolute, so there is one for each swap type listed
following the *types* keyword. In semi-grand canonical ensemble
simulations the chemical composition of the system is controlled by
the difference in these values. So shifting all values by a constant
amount will have no effect on the simulation.
simulations the chemical composition of the system is controlled by the
difference in these values. So shifting all values by a constant amount
will have no effect on the simulation.
This command may optionally use the *region* keyword to define swap
volume. The specified region must have been previously defined with a
@ -108,16 +107,16 @@ have a non-zero molecule ID, but does not check for this at the time of
swapping.
If not using *semi-grand* this fix checks to ensure all atoms of the
given types have the same atomic charge. LAMMPS does not enforce this
in general, but it is needed for this fix to simplify the swapping
given types have the same atomic charge. LAMMPS does not enforce this in
general, but it is needed for this fix to simplify the swapping
procedure. Successful swaps will swap the atom type and charge of the
swapped atoms. Conversely, when using *semi-grand*, it is assumed that
all the atom types involved in switches have the same
charge. Otherwise, charge would not be conserved. As a consequence, no
checks on atomic charges are performed, and successful switches update
the atom type but not the atom charge. While it is possible to use
*semi-grand* with groups of atoms that have different charges, these
charges will not be changed when the atom types change.
all the atom types involved in switches have the same charge. Otherwise,
charge would not be conserved. As a consequence, no checks on atomic
charges are performed, and successful switches update the atom type but
not the atom charge. While it is possible to use *semi-grand* with
groups of atoms that have different charges, these charges will not be
changed when the atom types change.
Since this fix computes total potential energies before and after
proposed swaps, so even complicated potential energy calculations are
@ -145,18 +144,19 @@ Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This fix writes the state of the fix to :doc:`binary restart files
<restart>`. This includes information about the random number
generator seed, the next timestep for MC exchanges, the number of
exchange attempts and successes, etc. See the :doc:`read_restart
<read_restart>` command for info on how to re-specify a fix in an
input script that reads a restart file, so that the operation of the
fix continues in an uninterrupted fashion.
<restart>`. This includes information about the random number generator
seed, the next timestep for MC exchanges, the number of exchange
attempts and successes, etc. See the :doc:`read_restart <read_restart>`
command for info on how to re-specify a fix in an input script that
reads a restart file, so that the operation of the fix continues in an
uninterrupted fashion.
.. note::
For this to work correctly, the timestep must **not** be changed
after reading the restart with :doc:`reset_timestep <reset_timestep>`.
The fix will try to detect it and stop with an error.
after reading the restart with :doc:`reset_timestep
<reset_timestep>`. The fix will try to detect it and stop with an
error.
None of the :doc:`fix_modify <fix_modify>` options are relevant to this
fix.
@ -187,12 +187,12 @@ Related commands
:doc:`fix nvt <fix_nh>`, :doc:`neighbor <neighbor>`,
:doc:`fix deposit <fix_deposit>`, :doc:`fix evaporate <fix_evaporate>`,
:doc:`delete_atoms <delete_atoms>`, :doc:`fix gcmc <fix_gcmc>`,
:doc:`fix mol/swap <fix_mol_swap>`
:doc:`fix mol/swap <fix_mol_swap>`, :doc:`fix sgcmc <fix_sgcmc>`
Default
"""""""
The option defaults are ke = yes, semi-grand = no, mu = 0.0 for
The option defaults are *ke* = yes, *semi-grand* = no, *mu* = 0.0 for
all atom types.
----------

40
doc/src/fix_bond_react.rst
View File

@ -123,6 +123,17 @@ using this fix is
(4) create a map that relates the template-atom-IDs of each atom between pre- and post-reaction molecule templates
(5) fill a simulation box with molecules and run a simulation with fix bond/react.
.. note::
.. versionadded:: 15Sep2022
:doc:`Type labels <Howto_type_labels>` allow for molecule templates
and data files to use alphanumeric atom types that match those of
a force field. Input files that use type labels are inherently
compatible with each other and portable between different
simulations. Therefore, it is highly recommended to use type labels
to specify atom, bond, etc. types when using fix bond/react.
Only one 'fix bond/react' command can be used at a time. Multiple
reactions can be simultaneously applied by specifying multiple *react*
arguments to a single 'fix bond/react' command. This syntax is
@ -228,18 +239,18 @@ pairs are identified within the cutoff distance:
initiator partners, these two atoms are identified as the initiator atom
pair of the reaction site.
Note that it can be helpful to select
unique atom types for the initiator atoms: if an initiator atom pair
is identified, as described in the previous steps, but it does not
correspond to the same pair specified in the pre-reaction template, an
otherwise eligible reaction could be prevented from occurring. Once
this unique initiator atom pair is identified for each reaction, there
could be two or more reactions that involve the same atom on the same
time step. If this is the case, only one such reaction is permitted to
occur. This reaction is chosen randomly from all potential reactions
involving the overlapping atom. This capability allows, for example,
different reaction pathways to proceed from identical reaction sites
with user-specified probabilities.
Note that it can be helpful to select unique atom types for the
initiator atoms: if an initiator atom pair is identified, as described
in the previous steps, but it does not correspond to the same pair
specified in the pre-reaction template, an otherwise eligible reaction
could be prevented from occurring. Once this unique initiator atom
pair is identified for each reaction, there could be two or more
reactions that involve the same atom on the same time step. If this is
the case, only one such reaction is permitted to occur. This reaction
is chosen randomly from all potential reactions involving the
overlapping atom. This capability allows, for example, different
reaction pathways to proceed from identical reaction sites with
user-specified probabilities.
The pre-reacted molecule template is specified by a molecule command.
This molecule template file contains a sample reaction site and its
@ -280,7 +291,10 @@ for a given simulation. All atom types in the pre-reacted template
must be the same as those of a potential reaction site in the
simulation. A detailed discussion of matching molecule template atom
types with the simulation is provided on the :doc:`molecule <molecule>`
command page.
command page. It is highly recommended to use :doc:`Type labels <Howto_type_labels>`
(added in version 15Sep2022) in both molecule templates and data
files, which automates the process of syncing atom types between
different input files.
The post-reacted molecule template contains a sample of the reaction
site and its surrounding topology after the reaction has occurred. It

122
doc/src/fix_colvars.rst
View File

@ -37,57 +37,64 @@ Description
This fix interfaces LAMMPS to the collective variables (Colvars)
library, which allows to calculate potentials of mean force (PMFs) for
any set of colvars, using different sampling methods: currently
implemented are the Adaptive Biasing Force (ABF) method, metadynamics,
Steered Molecular Dynamics (SMD) and Umbrella Sampling (US) via a
flexible harmonic restraint bias.
any set of colvars, using sampling methods, including but not limited to
Adaptive Biasing Force (ABF), metadynamics (MtD), Steered Molecular
Dynamics (SMD) and Umbrella Sampling (US) via a flexible harmonic
restraint bias.
This documentation describes only the fix colvars command itself and
LAMMPS specific parts of the code. The full documentation of the
colvars library is available as `this supplementary PDF document <PDF/colvars-refman-lammps.pdf>`_
This documentation describes only the ``fix colvars`` command itself in
a LAMMPS script. The Colvars library is documented via the included
`PDF manual <PDF/colvars-refman-lammps.pdf>`_ or at the webpage
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html
<https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html>`_.
The Colvars library is developed at `https://github.com/colvars/colvars <https://github.com/colvars/colvars>`_
A detailed discussion of its implementation is in :ref:`(Fiorin) <Fiorin>`.
The Colvars library is developed at `https://github.com/Colvars/colvars
<https://github.com/Colvars/colvars>`_ A detailed discussion of its
implementation is in :ref:`(Fiorin) <Fiorin>`; additional references are
printed at runtime based on specific features being used.
There are some example scripts for using this package with LAMMPS in the
examples/PACKAGES/colvars directory.
``examples/PACKAGES/colvars`` directory.
----------
The only mandatory argument to the fix is the filename to the colvars
input file that contains the input that is independent from the MD
program in which the colvars library has been integrated.
The only required argument to ``fix colvars`` is the filename to the
Colvars configuration file that contains the definition of the variables
and any biasing methods applied to them. from the MD program in which
the colvars library has been integrated.
The *group-ID* entry is ignored. The collective variable module will
always apply to the entire system and there can only be one instance
of the colvars fix at a time. The colvars fix will only communicate
the minimum information necessary and the colvars library supports
multiple, completely independent collective variables, so there is
no restriction to functionality by limiting the number of colvars fixes.
The *group-ID* entry is ignored. ``fix colvars`` will always apply to
the entire system, but specific atoms will be selected based on
selection keywords in the Colvars configuration file or files. There is
no need to define multiple ``fix colvars`` instances and it is not
allowed.
The *input* keyword allows to specify a state file that would contain
the restart information required in order to continue a calculation from
a prerecorded state. Fix colvars records it state in :doc:`binary restart <restart>`
files, so when using the :doc:`read_restart <read_restart>` command,
this is usually not needed.
The *output* keyword allows to specify the prefix of output files
generated by Colvars, for example ``output.colvars.traj`` or
``output.pmf``.
The *output* keyword allows to specify the output prefix. All output
files generated will use this prefix followed by the ".colvars." and
a word like "state" or "traj".
The *input* keyword allows to specify an optional state file that
contains the restart information needed to continue a previous
simulation state. Note, however, that ``fix colvars`` records its state
in :doc:`binary restart <restart>` files, so when using the
:doc:`read_restart <read_restart>` command, this is usually not needed.
The *seed* keyword contains the seed for the random number generator
that will be used in the colvars module.
used by Colvars.
The *unwrap* keyword controls whether wrapped or unwrapped coordinates
are passed to the colvars library for calculation of the collective
are passed to the Colvars library for calculation of the collective
variables and the resulting forces. The default is *yes*, i.e. to use
the image flags to reconstruct the absolute atom positions.
Setting this to *no* will use the current local coordinates that are
wrapped back into the simulation cell at each re-neighboring instead.
the image flags to reconstruct the absolute atom positions. Setting
this to *no* will use the current local coordinates that are wrapped
back into the simulation cell at each re-neighboring instead. For
information about when and how this affects results, please see
`https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping
<https://colvars.github.io/colvars-refman-lammps/colvars-refman-lammps.html#sec:colvar_atom_groups_wrapping>`_.
The *tstat* keyword can be either NULL or the label of a thermostatting
fix that thermostats all atoms in the fix colvars group. This will be
used to provide the colvars module with the current thermostat target
fix that thermostats all atoms in the fix colvars group. This will be
used to let Colvars know what is the current thermostat target
temperature.
Restart, fix_modify, output, run start/stop, minimize info
@ -95,41 +102,42 @@ Restart, fix_modify, output, run start/stop, minimize info
This fix writes the current status of the colvars module into
:doc:`binary restart files <restart>`. This is in addition to the text
mode status file that is written by the colvars module itself and the
kind of information in both files is identical.
mode ``.colvars.state`` written by Colvars itself and the information in
both files is identical.
The :doc:`fix_modify <fix_modify>` *energy* option is supported by
this fix to add the energy change from the biasing force added by
Colvars to the global potential energy of the system as part of
:doc:`thermodynamic output <thermo_style>`. The default setting for
this fix is :doc:`fix_modify energy no <fix_modify>`.
The :doc:`fix_modify <fix_modify>` *energy* option is supported by this
fix to add the energy change from the biasing force added by Colvars to
the global potential energy of the system as part of :doc:`thermodynamic
output <thermo_style>`. The default setting for this fix is
:doc:`fix_modify energy no <fix_modify>`.
The *fix_modify configfile <config file>* option allows to add settings
from an additional config file to the colvars module. This option can
only be used, after the system has been initialized with a :doc:`run <run>`
command.
The *fix_modify configfile <config file>* option loads Colvars
configuration from an additional file. This option can only be used,
after the system has been initialized with a :doc:`run <run>` command.
The *fix_modify config <quoted string>* option allows to add settings
from inline strings. Those have to fit on a single line when enclosed
in a pair of double quotes ("), or can span multiple lines when bracketed
by a pair of triple double quotes (""", like python embedded documentation).
from inline strings. Those have to fit on a single line when enclosed in
a pair of double quotes ("), or can span multiple lines when bracketed
by a pair of triple double quotes (""", like Python embedded
documentation).
This fix computes a global scalar which can be accessed by various
:doc:`output commands <Howto_output>`. The scalar is the Colvars
energy mentioned above. The scalar value calculated by this fix is
:doc:`output commands <Howto_output>`. The scalar is the Colvars energy
mentioned above. The scalar value calculated by this fix is
"extensive".
Restrictions
""""""""""""
This fix is part of the COLVARS package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
``fix colvars`` is provided by the COLVARS package and is only available
if LAMMPS was built with that package. Some of the features also
require code available from the LEPTON package. See the :doc:`Build
package <Build_package>` page for more info.
There can only be one colvars fix active at a time. Since the interface
communicates only the minimum amount of information and colvars module
itself can handle an arbitrary number of collective variables, this is
not a limitation of functionality.
There can only be one Colvars instance defined at a time. Since the
interface communicates only the minimum amount of information and the
Colvars module itself can handle an arbitrary number of collective
variables, this is not a limitation of functionality.
Related commands
""""""""""""""""

2
doc/src/fix_halt.rst
View File

@ -173,7 +173,7 @@ the :doc:`run <run>` command.
Restrictions
""""""""""""
The *diskfree* attribute is currently only supported on Linux, MacOSX, and BSD.
The *diskfree* attribute is currently only supported on Linux, macOS, and \*BSD.
Related commands
""""""""""""""""

127
doc/src/fix_neb.rst
View File

@ -18,9 +18,10 @@ Syntax
.. parsed-literal::
*parallel* value = *neigh* or *ideal*
*parallel* value = *neigh* or *ideal* or *equal*
*neigh* = parallel nudging force based on distance to neighbor replicas (Kspring = force/distance units)
*ideal* = parallel nudging force based on interpolated ideal position (Kspring = force units)
*equal* = parallel nudging force based on interpolated ideal position before climbing, then interpolated ideal energy whilst climbing (Kspring = force units)
*perp* value = *Kspring2*
*Kspring2* = spring constant for perpendicular nudging force (force/distance units)
*end* values = estyle Kspring3
@ -59,37 +60,37 @@ replica having the highest energy relaxes toward the saddle point
relaxation is performed.
A key purpose of the nudging forces is to keep the replicas equally
spaced. During the NEB calculation, the 3N-length vector of
interatomic force Fi = -Grad(V) for each replica I is altered. For
all intermediate replicas (i.e. for 1 < I < N, except the climbing
replica) the force vector becomes:
spaced. During the NEB calculation, the :math:`3N`-length vector of
interatomic force :math:`F_i = -\nabla V` for each replica *i* is
altered. For all intermediate replicas (i.e. for :math:`1 < i < N`,
except the climbing replica) the force vector becomes:
.. parsed-literal::
.. math::
Fi = -Grad(V) + (Grad(V) dot T') T' + Fnudge_parallel + Fnudge_perp
F_i = -\nabla V + (\nabla V \cdot T') T' + F_\parallel + F_\perp
T' is the unit "tangent" vector for replica I and is a function of Ri,
Ri-1, Ri+1, and the potential energy of the 3 replicas; it points
roughly in the direction of (Ri+i - Ri-1); see the
:ref:`(Henkelman1) <Henkelman1>` paper for details. Ri are the atomic
coordinates of replica I; Ri-1 and Ri+1 are the coordinates of its
neighbor replicas. The term (Grad(V) dot T') is used to remove the
component of the gradient parallel to the path which would tend to
distribute the replica unevenly along the path. Fnudge_parallel is an
artificial nudging force which is applied only in the tangent
direction and which maintains the equal spacing between replicas (see
below for more information). Fnudge_perp is an optional artificial
spring which is applied in a direction perpendicular to the tangent
direction and which prevent the paths from forming acute kinks (see
below for more information).
T' is the unit "tangent" vector for replica *i* and is a function of
:math:`R_i, R_{i-1}, R_{i+1}`, and the potential energy of the 3
replicas; it points roughly in the direction of :math:`R_{i+i} -
R_{i-1}`; see the :ref:`(Henkelman1) <Henkelman1>` paper for details.
:math:`R_i` are the atomic coordinates of replica *i*; :math:`R_{i-1}`
and :math:`R_{i+1}` are the coordinates of its neighbor replicas. The
term :math:`\nabla V \cdot T'` is used to remove the component of the
gradient parallel to the path which would tend to distribute the replica
unevenly along the path. :math:`F_\parallel` is an artificial nudging
force which is applied only in the tangent direction and which maintains
the equal spacing between replicas (see below for more information).
:math:`F_\perp` is an optional artificial spring which is applied in a
direction perpendicular to the tangent direction and which prevent the
paths from forming acute kinks (see below for more information).
In the second stage of the NEB calculation, the interatomic force Fi
In the second stage of the NEB calculation, the interatomic force :math:`F_i`
for the climbing replica (the replica of highest energy after the
first stage) is changed to:
.. parsed-literal::
.. math::
Fi = -Grad(V) + 2 (Grad(V) dot T') T' + Fnudge_perp
F_i = -\nabla V + 2 (\nabla V \cdot T') T' + F_\perp
and the relaxation procedure is continued to a new converged MEP.
@ -100,29 +101,56 @@ computed. With a value of *neigh*, the parallel nudging force is
computed as in :ref:`(Henkelman1) <Henkelman1>` by connecting each
intermediate replica with the previous and the next image:
.. parsed-literal::
.. math::
Fnudge_parallel = *Kspring* \* (\|Ri+1 - Ri\| - \|Ri - Ri-1\|)
F_\parallel = Kspring \cdot \left(\left|R_{i+1} - R_i\right| - \left|R_i - R_{i-1}\right|\right)
Note that in this case the specified *Kspring* is in force/distance
units.
Note that in this case the specified *Kspring* is in
force/distance units.
With a value of *ideal*, the spring force is computed as suggested in
ref`(WeinanE) <WeinanE>`
.. parsed-literal::
.. math::
Fnudge_parallel = -\ *Kspring* \* (RD-RDideal) / (2 \* meanDist)
F_\parallel = -Kspring \cdot (RD - RD_{ideal}) / (2 \cdot meanDist)
where RD is the "reaction coordinate" see :doc:`neb <neb>` section, and
RDideal is the ideal RD for which all the images are equally spaced.
I.e. RDideal = (I-1)\*meanDist when the climbing replica is off, where
I is the replica number). The meanDist is the average distance
between replicas. Note that in this case the specified *Kspring* is
in force units.
where *RD* is the "reaction coordinate" see :doc:`neb <neb>` section,
and :math:`RD_{ideal}` is the ideal *RD* for which all the images are
equally spaced. I.e. :math:`RD_{ideal} = (i-1) \cdot meanDist` when the
climbing replica is off, where *i* is the replica number). The
*meanDist* is the average distance between replicas. Note that in this
case the specified *Kspring* is in force units. When the climbing replica
is on, :math:`RD_{ideal}` and :math:`meanDist` are calculated separately
each side of the climbing image. Note that the *ideal* form of nudging
can often be more effective at keeping the replicas equally spaced before
climbing, then equally spaced either side of the climbing image whilst
climbing.
Note that the *ideal* form of nudging can often be more effective at
keeping the replicas equally spaced.
With a value of *equal* the spring force is computed as for *ideal*
when the climbing replica is off, promoting equidistance. When the climbing
replica is on, the spring force is computed to promote equidistant
absolute differences in energy, rather than distance, each side of
the climbing image:
.. math::
F_\parallel = -Kspring \cdot (ED - ED_{ideal}) / (2 \cdot meanEDist)
where *ED* is the cumulative sum of absolute energy differences:
.. math::
ED = \sum_{i<N} \left|E(R_{i+1}) - E(R_i)\right|,
*meanEdist* is the average absolute energy difference between
replicas up to the climbing image or from the climbing image
to the final image, for images before or after the climbing
image respectively. :math:`ED_{ideal}` is the corresponding
cumulative sum of average absolute energy differences in
each case, in close analogy to *ideal*. This form of nudging
is to aid schemes which integrate forces along, or near to,
NEB pathways such as :doc:`fix_pafi <fix_pafi>`.
----------
@ -135,14 +163,16 @@ resolution is poor. I.e. when few replicas are used; see
The perpendicular spring force is given by
.. parsed-literal::
.. math::
Fnudge_perp = *Kspring2* \* F(Ri-1,Ri,Ri+1) (Ri+1 + Ri-1 - 2 Ri)
F_\perp = K_{spring2} \cdot F(R_{i-1},R_i,R_{i+1}) (R_{i+1} + R_{i-1} - 2 R_i)
where *Kspring2* is the specified value. F(Ri-1 Ri R+1) is a smooth
scalar function of the angle Ri-1 Ri Ri+1. It is equal to 0.0 when
the path is straight and is equal to 1 when the angle Ri-1 Ri Ri+1 is
acute. F(Ri-1 Ri R+1) is defined in :ref:`(Jonsson) <Jonsson>`.
where *Kspring2* is the specified value. :math:`F(R_{i-1}, R_i,
R_{i+1})` is a smooth scalar function of the angle :math:`R_{i-1} R_i
R_{i+1}`. It is equal to 0.0 when the path is straight and is equal to
1 when the angle :math:`R_{i-1} R_i R_{i+1}` is acute.
:math:`F(R_{i-1}, R_i, R_{i+1})` is defined in :ref:`(Jonsson)
<Jonsson>`.
If *Kspring2* is set to 0.0 (the default) then no perpendicular spring
force is added.
@ -156,12 +186,13 @@ forces can be applied to the first and/or last replicas, to enable
them to relax toward a MEP while constraining their energy E to the
target energy ETarget.
If ETarget>E, the interatomic force Fi for the specified replica becomes:
If :math:`E_{Target} > E`, the interatomic force :math:`F_i` for the
specified replica becomes:
.. parsed-literal::
.. math::
Fi = -Grad(V) + (Grad(V) dot T' + (E-ETarget)\*Kspring3) T', *when* Grad(V) dot T' < 0
Fi = -Grad(V) + (Grad(V) dot T' + (ETarget- E)\*Kspring3) T', *when* Grad(V) dot T' > 0
F_i & = -\nabla V + (\nabla V \cdot T' + (E - E_{Target}) \cdot K_{spring3}) T', \qquad \textrm{when} \quad \nabla V \cdot T' < 0 \\
F_i & = -\nabla V + (\nabla V \cdot T' + (E_{Target} - E) \cdot K_{spring3}) T', \qquad \textrm{when} \quad \nabla V \cdot T' > 0
The "spring" constant on the difference in energies is the specified
*Kspring3* value.

52
doc/src/fix_nvt_sllod.rst
View File

@ -17,7 +17,15 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* nvt/sllod = style name of this fix command
* additional thermostat related keyword/value pairs from the :doc:`fix nvt <fix_nh>` command can be appended
* zero or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *psllod*
*psllod* value = *no* or *yes* = use SLLOD or p-SLLOD variant, respectively
* additional thermostat related keyword/value pairs from the :doc:`fix nvt <fix_nh>`
command can be appended
Examples
""""""""
@ -61,22 +69,27 @@ large x velocity. These velocities do not contribute to the thermal
consistent.
The SLLOD equations of motion, originally proposed by Hoover and Ladd
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be
equivalent to Newton's equations of motion for shear flow by
:ref:`(Evans and Morriss) <Evans3>`. They were later shown to generate
the desired velocity gradient and the correct production of work by
stresses for all forms of homogeneous flow by :ref:`(Daivis and Todd)
<Daivis>`.
The LAMMPS implementation corresponds to the p-SLLOD variant
of SLLOD. :ref:`(Edwards) <Edwards>`.
The equations of motion are coupled to a
(see :ref:`(Evans and Morriss) <Evans3>`), were proven to be equivalent
to Newton's equations of motion for shear flow by :ref:`(Evans and
Morriss) <Evans3>`. They were later shown to generate the desired
velocity gradient and the correct production of work by stresses for all
forms of homogeneous flow by :ref:`(Daivis and Todd) <Daivis>`.
.. versionchanged:: TBD
For the default (*psllod* = *no*), the LAMMPS implementation adheres to
the standard SLLOD equations of motion, as defined by :ref:`(Evans and
Morriss) <Evans3>`. The option *psllod* = *yes* invokes the slightly
different SLLOD variant first introduced by :ref:`(Tuckerman et al.)
<Tuckerman>` as g-SLLOD and later by :ref:`(Edwards) <Edwards>` as
p-SLLOD. In all cases, the equations of motion are coupled to a
Nose/Hoover chain thermostat in a velocity Verlet formulation, closely
following the implementation used for the :doc:`fix nvt <fix_nh>`
command.
.. note::
A recent (2017) book by :ref:`(Daivis and Todd) <Daivis-sllod>`
A recent (2017) book by :ref:`(Todd and Daivis) <Todd-sllod>`
discusses use of the SLLOD method and non-equilibrium MD (NEMD)
thermostatting generally, for both simple and complex fluids,
e.g. molecular systems. The latter can be tricky to do correctly.
@ -159,7 +172,7 @@ Restrictions
""""""""""""
This fix works best without Nose-Hoover chain thermostats, i.e. using
tchain = 1. Setting tchain to larger values can result in poor
*tchain* = 1. Setting *tchain* to larger values can result in poor
equilibration.
Related commands
@ -171,7 +184,7 @@ Related commands
Default
"""""""
Same as :doc:`fix nvt <fix_nh>`, except tchain = 1.
Same as :doc:`fix nvt <fix_nh>`, except *tchain* = 1, psllod = *no*.
----------
@ -183,11 +196,16 @@ Same as :doc:`fix nvt <fix_nh>`, except tchain = 1.
**(Daivis and Todd)** Daivis and Todd, J Chem Phys, 124, 194103 (2006).
.. _Todd-sllod:
**(Todd and Daivis)** Todd and Daivis, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, (2017) https://doi.org/10.1017/9781139017848.
.. _Tuckerman:
**(Tuckerman et al.)** Tuckerman, Mundy, Balasubramanian, and Klein, J Chem Phys 106, 5615 (1997).
.. _Edwards:
**(Edwards)** Edwards, Baig, and Keffer, J Chem Phys 124, 194104 (2006).
.. _Daivis-sllod:
**(Daivis and Todd)** Daivis and Todd, Nonequilibrium Molecular Dynamics (book),
Cambridge University Press, https://doi.org/10.1017/9781139017848, (2017).

24
doc/src/fix_nvt_sllod_eff.rst
View File

@ -12,7 +12,15 @@ Syntax
* ID, group-ID are documented in :doc:`fix <fix>` command
* nvt/sllod/eff = style name of this fix command
* additional thermostat related keyword/value pairs from the :doc:`fix nvt/eff <fix_nh_eff>` command can be appended
* zero or more keyword/value pairs may be appended
.. parsed-literal::
keyword = *psllod*
*psllod* value = *no* or *yes* = use SLLOD or p-SLLOD variant, respectively
* additional thermostat related keyword/value pairs from the :doc:`fix
nvt/eff <fix_nh_eff>` command may be appended, too.
Examples
""""""""
@ -25,18 +33,20 @@ Examples
Description
"""""""""""
Perform constant NVT integration to update positions and velocities
each timestep for nuclei and electrons in the group for the :doc:`electron force field <pair_eff>` model, using a Nose/Hoover temperature
Perform constant NVT integration to update positions and velocities each
timestep for nuclei and electrons in the group for the :doc:`electron
force field <pair_eff>` model, using a Nose/Hoover temperature
thermostat. V is volume; T is temperature. This creates a system
trajectory consistent with the canonical ensemble.
The operation of this fix is exactly like that described by the :doc:`fix nvt/sllod <fix_nvt_sllod>` command, except that the radius and
The operation of this fix is exactly like that described by the
:doc:`fix nvt/sllod <fix_nvt_sllod>` command, except that the radius and
radial velocity of electrons are also updated and thermostatted.
Likewise the temperature calculated by the fix, using the compute it
creates (as discussed in the :doc:`fix nvt, npt, and nph <fix_nh>` doc
page), is performed with a :doc:`compute temp/deform/eff <compute_temp_deform_eff>` command that includes
the eFF contribution to the temperature from the electron radial
velocity.
page), is performed with a :doc:`compute temp/deform/eff
<compute_temp_deform_eff>` command that includes the eFF contribution to
the temperature from the electron radial velocity.
Restart, fix_modify, output, run start/stop, minimize info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

9
doc/src/fix_pair.rst
View File

@ -1,7 +1,7 @@
.. index:: fix pair
fix pair command
=======================
================
Syntax
""""""
@ -47,7 +47,12 @@ These are example use cases:
The *N* argument determines how often the fix is invoked.
The *pstyle* argument is the name of the pair style. It can be a
sub-style used in a :doc:`pair_style hybrid <pair_hybrid>` command.
sub-style used in a :doc:`pair_style hybrid <pair_hybrid>` command. If
there are multiple sub-styles using the same pair style, then *pstyle*
should be specified as "style:N", where *N* is the number of the
instance of the pair style you wish monitor (e.g., the first or second).
For example, *pstyle* could be specified as "pace/extrapolation" or
"amoeba" or "eam:1" or "eam:2".
One or more *name/flag* pairs of arguments follow. Each *name* is a
per-atom quantity which the pair style must recognize as an extraction

5
doc/src/fix_setforce.rst
View File

@ -129,8 +129,9 @@ non-zero force to atoms during a minimization.
Restrictions
""""""""""""
The fix *setforce/spin* only makes sense when LAMMPS was built with the
SPIN package.
Fix *setforce/spin* is part of the SPIN 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
""""""""""""""""

2
doc/src/labelmap.rst
View File

@ -25,10 +25,10 @@ Examples
.. code-block:: LAMMPS
labelmap atom 3 carbon 4 'c3"' 5 "c1'" 6 "c#"
labelmap bond 1 carbonyl 2 nitrile 3 """ c1'-c2" """
labelmap atom $(label2type(atom,carbon)) C # change type label from 'carbon' to 'C'
labelmap clear
labelmap write mymap.include
labelmap bond 1 carbonyl 2 nitrile 3 """ c1'-c2" """
Description
"""""""""""

122
doc/src/lepton_expression.rst Normal file
View File

@ -0,0 +1,122 @@
Lepton expression syntax and features
"""""""""""""""""""""""""""""""""""""
Lepton supports the following operators in expressions:
.. table_from_list::
:columns: 14
* \+
* Add
*
* \-
* Subtract
*
* \*
* Multiply
*
* \/
* Divide
*
* \^
* Power
The following mathematical functions are available:
.. table_from_list::
:columns: 4
* sqrt(x)
* Square root
* exp(x)
* Exponential
* log(x)
* Natural logarithm
* sin(x)
* Sine (angle in radians)
* cos(x)
* Cosine (angle in radians)
* sec(x)
* Secant (angle in radians)
* csc(x)
* Cosecant (angle in radians)
* tan(x)
* Tangent (angle in radians)
* cot(x)
* Cotangent (angle in radians)
* asin(x)
* Inverse sine (in radians)
* acos(x)
* Inverse cosine (in radians)
* atan(x)
* Inverse tangent (in radians)
* sinh(x)
* Hyperbolic sine
* cosh(x)
* Hyperbolic cosine
* tanh(x)
* Hyperbolic tangent
* erf(x)
* Error function
* erfc(x)
* Complementary Error function
* abs(x)
* Absolute value
* min(x,y)
* Minimum of two values
* max(x,y)
* Maximum of two values
* delta(x)
* delta(x) is 1 for `x = 0`, otherwise 0
* step(x)
* step(x) is 0 for `x < 0`, otherwise 1
Numbers may be given in either decimal or exponential form. All of the
following are valid numbers: `5`, `-3.1`, `1e6`, and `3.12e-2`.
As an extension to the standard Lepton syntax, it is also possible to
use LAMMPS :doc:`variables <variable>` in the format "v_name". Before
evaluating the expression, "v_name" will be replaced with the value of
the variable "name". This is compatible with all kinds of scalar
variables, but not with vectors, arrays, local, or per-atom
variables. If necessary, a custom scalar variable needs to be defined
that can access the desired (single) item from a non-scalar variable.
As an example, the following lines will instruct LAMMPS to ramp
the force constant for a harmonic bond from 100.0 to 200.0 during the
next run:
.. code-block:: LAMMPS
variable fconst equal ramp(100.0, 200)
bond_style lepton
bond_coeff 1 1.5 "v_fconst * (r^2)"
An expression may be followed by definitions for intermediate values that appear in the
expression. A semicolon ";" is used as a delimiter between value definitions. For example,
the expression:
.. code-block:: C
a^2+a*b+b^2; a=a1+a2; b=b1+b2
is exactly equivalent to
.. code-block:: C
(a1+a2)^2+(a1+a2)*(b1+b2)+(b1+b2)^2
The definition of an intermediate value may itself involve other
intermediate values. Whitespace and quotation characters ('\'' and '"')
are ignored. All uses of a value must appear *before* that value's
definition. For efficiency reasons, the expression string is parsed,
optimized, and then stored in an internal, pre-parsed representation for
evaluation.
Evaluating a Lepton expression is typically between 2.5 and 5 times
slower than the corresponding compiled and optimized C++ code. If
additional speed or GPU acceleration (via GPU or KOKKOS) is required,
the interaction can be represented as a table. Suitable table files
can be created either internally using the :doc:`pair_write <pair_write>`
or :doc:`bond_write <bond_write>` command or through the Python scripts
in the :ref:`tools/tabulate <tabulate>` folder.

59
doc/src/min_modify.rst
View File

@ -14,7 +14,7 @@ Syntax
.. parsed-literal::
keyword = *dmax* or *line* or *norm* or *alpha_damp* or *discrete_factor* or *integrator* or *tmax*
keyword = *dmax* or *line* or *norm* or *alpha_damp* or *discrete_factor* or *integrator* or *abcfire* or *tmax*
*dmax* value = max
max = maximum distance for line search to move (distance units)
*line* value = *backtrack* or *quadratic* or *forcezero* or *spin_cubic* or *spin_none*
@ -27,8 +27,11 @@ Syntax
damping = fictitious magnetic damping for spin minimization (adim)
*discrete_factor* value = factor
factor = discretization factor for adaptive spin timestep (adim)
*integrator* value = *eulerimplicit* or *verlet*
*integrator* value = *eulerimplicit* or *verlet* or *leapfrog* or *eulerexplicit*
time integration scheme for fire minimization
*abcfire* value = yes or no (default no)
yes = use ABC-FIRE variant of fire minimization style
no = use default FIRE variant of fire minimization style
*tmax* value = factor
factor = maximum adaptive timestep for fire minimization (adim)
@ -127,27 +130,35 @@ procedure. The *spin_none* is a default value for *line* keyword for
both *spin/lbfgs* and *spin/cg*\ . Convergence of *spin/lbfgs* can be
more robust if *spin_cubic* line search is used.
The Newton *integrator* used for *fire* minimization can be selected
to be either the symplectic Euler (\ *eulerimplicit*\ ) or velocity
Verlet (\ *verlet*\ ). *tmax* defines the maximum value for the
adaptive timestep during a *fire* minimization. It is a multiplication
factor applied to the current :doc:`timestep <timestep>` (not in time
unit). For example, *tmax* = 4.0 with a :doc:`timestep <timestep>` of
2fs, means that the maximum value the timestep can reach during a *fire*
minimization is 4fs.
Note that parameter defaults has been chosen to be reliable in most cases,
but one should consider adjusting :doc:`timestep <timestep>` and *tmax* to
optimize the minimization for large or complex systems. Other
parameters of the *fire* minimization can be tuned (\ *tmin*,
*delaystep*, *dtgrow*, *dtshrink*, *alpha0*, and
*alphashrink*\ ). Please refer to the references describing the
:doc:`min_style <min_style>` *fire*.
An additional stopping criteria *vdfmax* is used by *fire* in order to avoid
unnecessary looping when it is reasonable to think the system will not
be relaxed further. Note that in this case the system will NOT have
The Newton *integrator* used for *fire* minimization can be selected to
be either the symplectic Euler (\ *eulerimplicit*\ ), velocity Verlet (\
*verlet*\ ), Leapfrog (\ *leapfrog*\ ) or non-symplectic forward Euler
(\ *eulerexplicit* \). The keyword *tmax* defines the maximum value for
the adaptive timestep during a *fire* minimization. It is a
multiplication factor applied to the current :doc:`timestep <timestep>`
(not in time unit). For example, *tmax* = 4.0 with a :doc:`timestep
<timestep>` of 2fs, means that the maximum value the timestep can reach
during a *fire* minimization is 4fs. Note that parameter defaults has
been chosen to be reliable in most cases, but one should consider
adjusting :doc:`timestep <timestep>` and *tmax* to optimize the
minimization for large or complex systems. Other parameters of the
*fire* minimization can be tuned (\ *tmin*, *delaystep*, *dtgrow*,
*dtshrink*, *alpha0*, and *alphashrink*\ ). Please refer to the
references describing the :doc:`min_style <min_style>` *fire*. An
additional stopping criteria *vdfmax* is used by *fire* in order to
avoid unnecessary looping when it is reasonable to think the system will
not be relaxed further. Note that in this case the system will NOT have
reached your minimization criteria. This could happen when the system
comes to be stuck in a local basin of the phase space. *vdfmax* is
the maximum number of consecutive iterations with P(t) < 0.
comes to be stuck in a local basin of the phase space. *vdfmax* is the
maximum number of consecutive iterations with P(t) < 0.
.. versionadded:: TBD
The *abcfire* keyword allows to activate the ABC-FIRE variant of the
*fire* minimization algorithm. ABC-FIRE introduces an additional factor
that modifies the bias and scaling of the velocities of the atoms during
the mixing step :ref:`(Echeverri Restrepo) <EcheverriRestrepo>`. This
can lead to faster convergence of the minimizer.
The :doc:`min_style <min_style>` *fire* is an optimized implementation of
:doc:`min_style <min_style>` *fire/old*. It can however behave similarly
@ -184,3 +195,7 @@ For the *fire* style, the option defaults are integrator =
eulerimplicit, tmax = 10.0, tmin = 0.02, delaystep = 20, dtgrow = 1.1,
dtshrink = 0.5, alpha0 = 0.25, alphashrink = 0.99, vdfmax = 2000,
halfstepback = yes and initialdelay = yes.
.. _EcheverriRestrepo:
**(EcheverriRestrepo)** Echeverri Restrepo, Andric, Comput Mater Sci, 218, 111978 (2023).

39
doc/src/min_style.rst
View File

@ -15,9 +15,6 @@ min_style quickmin command
min_style fire command
======================
min_style fire/old command
==========================
:doc:`min_style spin <min_spin>` command
========================================
@ -34,7 +31,7 @@ Syntax
min_style style
* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *fire/old* or *spin* or *spin/cg* or *spin/lbfgs*
* style = *cg* or *hftn* or *sd* or *quickmin* or *fire* or *spin* or *spin/cg* or *spin/lbfgs*
.. parsed-literal::
@ -91,23 +88,12 @@ by this style, at the beginning of a minimization.
Style *fire* is a damped dynamics method described in :ref:`(Bitzek)
<Bitzek>`, which is similar to *quickmin* but adds a variable timestep
and alters the projection operation to maintain components of the
velocity non-parallel to the current force vector. The velocity of
each atom is initialized to 0.0 by this style, at the beginning of a
minimization. This style correspond to an optimized version described
velocity non-parallel to the current force vector. The velocity of each
atom is initialized to 0.0 by this style, at the beginning of a
minimization. This style correspond to an optimized version described
in :ref:`(Guenole) <Guenole>` that include different time integration
schemes and defaults parameters. The default parameters can be
modified with the command :doc:`min_modify <min_modify>`.
Style *fire/old* is the original implementation of *fire* in Lammps,
conserved for backward compatibility. The main differences regarding
the current version *fire* are: time integration by Explicit Euler
only, different sequence in maintaining velocity components non-parallel
to the current force vector and hard-coded minimization parameters.
A complete description of the differences between *fire/old* and *fire*
can be found in :ref:`(Guenole) <Guenole>` (where the current *fire*
in LAMMPS is called *fire2.0*). By using an appropriate set of
parameters, *fire* can behave similar to *fire/old*, as described
in the :doc:`min_modify <min_modify>` command.
schemes and default parameters. The default parameters can be modified
with the command :doc:`min_modify <min_modify>`.
Style *spin* is a damped spin dynamics with an adaptive timestep.
@ -121,13 +107,12 @@ to minimize spin configurations.
See the :doc:`min/spin <min_spin>` page for more information about
the *spin*, *spin/cg* and *spin/lbfgs* styles.
Either the *quickmin*, *fire* and *fire/old* styles are useful in the
context of nudged elastic band (NEB) calculations via the :doc:`neb
<neb>` command.
Either the *quickmin* or the *fire* styles are useful in the context of
nudged elastic band (NEB) calculations via the :doc:`neb <neb>` command.
Either the *spin*, *spin/cg* and *spin/lbfgs* styles are useful in
the context of magnetic geodesic nudged elastic band (GNEB)
calculations via the :doc:`neb/spin <neb_spin>` command.
Either the *spin*, *spin/cg*, or *spin/lbfgs* styles are useful in the
context of magnetic geodesic nudged elastic band (GNEB) calculations via
the :doc:`neb/spin <neb_spin>` command.
.. note::
@ -140,7 +125,7 @@ calculations via the :doc:`neb/spin <neb_spin>` command.
.. note::
The *quickmin*, *fire*, *fire/old*, *hftn*, and *cg/kk* styles do not yet
The *quickmin*, *fire*, *hftn*, and *cg/kk* styles do not yet
support the use of the :doc:`fix box/relax <fix_box_relax>` command
or minimizations involving the electron radius in :doc:`eFF
<pair_eff>` models.

93
doc/src/neb.rst
View File

@ -8,7 +8,7 @@ Syntax
.. parsed-literal::
neb etol ftol N1 N2 Nevery file-style arg keyword
neb etol ftol N1 N2 Nevery file-style arg keyword values
* etol = stopping tolerance for energy (energy units)
* ftol = stopping tolerance for force (force units)
@ -29,7 +29,15 @@ Syntax
*none* arg = no argument all replicas assumed to already have
their initial coords
keyword = *verbose*
* zero or more keyword/value pairs may be appended
* keyword = *verbosity*
.. parsed-literal::
*verbosity* value = *verbose* or *default* or *terse*
*verbose* = very detailed per-replica output
*default* = some per-replica output
*terse* = only global state output
Examples
""""""""
@ -47,19 +55,21 @@ Perform a nudged elastic band (NEB) calculation using multiple
replicas of a system. Two or more replicas must be used; the first
and last are the end points of the transition path.
NEB is a method for finding both the atomic configurations and height
of the energy barrier associated with a transition state, e.g. for an
atom to perform a diffusive hop from one energy basin to another in a
NEB is a method for finding both the atomic configurations and height of
the energy barrier associated with a transition state, e.g. for an atom
to perform a diffusive hop from one energy basin to another in a
coordinated fashion with its neighbors. The implementation in LAMMPS
follows the discussion in these 4 papers: :ref:`(HenkelmanA) <HenkelmanA>`,
:ref:`(HenkelmanB) <HenkelmanB>`, :ref:`(Nakano) <Nakano3>` and :ref:`(Maras) <Maras2>`.
follows the discussion in these 4 papers: :ref:`(HenkelmanA)
<HenkelmanA>`, :ref:`(HenkelmanB) <HenkelmanB>`, :ref:`(Nakano)
<Nakano3>` and :ref:`(Maras) <Maras2>`.
Each replica runs on a partition of one or more processors. Processor
partitions are defined at run-time using the :doc:`-partition command-line switch <Run_options>`. Note that if you have MPI installed, you
can run a multi-replica simulation with more replicas (partitions)
than you have physical processors, e.g you can run a 10-replica
simulation on just one or two processors. You will simply not get the
performance speed-up you would see with one or more physical
partitions are defined at run-time using the :doc:`-partition
command-line switch <Run_options>`. Note that if you have MPI
installed, you can run a multi-replica simulation with more replicas
(partitions) than you have physical processors, e.g you can run a
10-replica simulation on just one or two processors. You will simply
not get the performance speed-up you would see with one or more physical
processors per replica. See the :doc:`Howto replica <Howto_replica>`
doc page for further discussion.
@ -302,12 +312,26 @@ and restart files.
When running with multiple partitions (each of which is a replica in
this case), the print-out to the screen and master log.lammps file
contains a line of output, printed once every *Nevery* timesteps. It
contains the timestep, the maximum force per replica, the maximum
force per atom (in any replica), potential gradients in the initial,
final, and climbing replicas, the forward and backward energy
barriers, the total reaction coordinate (RDT), and the normalized
reaction coordinate and potential energy of each replica.
contains a line of output, printed once every *Nevery* timesteps. The
amount of information printed in this line can be selected with the
*verbosity* keyword. Available options are *terse*, *default*, and
*verbose*.
With the *terse* setting, it contains the timestep, the maximum force of
a replica, the maximum force per atom (in any replica), potential
gradients in the initial, final, and climbing replicas, the forward and
backward energy barriers, the total reaction coordinate (RDT).
With the *default* setting, additionally the normalized
reaction coordinate and potential energy of each replica are printed.
With the *verbose* setting, additional per-replica properties are
printed: the "path angle" (pathangle), the angle between the 3N-length
tangent vector and the 3N-length force vector at image *i*
(angletangrad), the angle between the 3N-length energy gradient vector
of replica *i* and that of replica *i*\ +1 (anglegrad), the norm of the
energy gradient (gradV), the the two-norm of the 3N-length force vector
(RepForce), and the maximum force component of any atom (MaxAtomForce).
The "maximum force per replica" is the two-norm of the 3N-length force
vector for the atoms in each replica, maximized across replicas, which
@ -330,22 +354,21 @@ the fix neb command.
The forward (reverse) energy barrier is the potential energy of the
highest replica minus the energy of the first (last) replica.
Supplementary information for all replicas can be printed out to the
screen and master log.lammps file by adding the verbose keyword. This
information include the following. The "path angle" (pathangle) for
the replica i which is the angle between the 3N-length vectors (Ri-1 -
Ri) and (Ri+1 - Ri) (where Ri is the atomic coordinates of replica
i). A "path angle" of 180 indicates that replicas i-1, i and i+1 are
aligned. "angletangrad" is the angle between the 3N-length tangent
vector and the 3N-length force vector at image i. The tangent vector
is calculated as in :ref:`(HenkelmanA) <HenkelmanA>` for all intermediate
replicas and at R2 - R1 and RM - RM-1 for the first and last replica,
respectively. "anglegrad" is the angle between the 3N-length energy
gradient vector of replica i and that of replica i+1. It is not
defined for the final replica and reads nan. gradV is the norm of the
energy gradient of image i. ReplicaForce is the two-norm of the
3N-length force vector (including nudging forces) for replica i.
MaxAtomForce is the maximum force component of any atom in replica i.
The "path angle" (pathangle) for the replica i which is the angle
between the 3N-length vectors :math:`(R_{i-1} - R_i)` and
:math:`(R_{i+1} - R_i)` (where :math:`R_i` is the atomic coordinates of
replica *i*). A "path angle" of 180 indicates that replicas *i*\ -1, *i*
and *i*\ +1 are aligned. "angletangrad" is the angle between the
3N-length tangent vector and the 3N-length force vector at image
*i*. The tangent vector is calculated as in :ref:`(HenkelmanA)
<HenkelmanA>` for all intermediate replicas and at R2 - R1 and RM - RM-1
for the first and last replica, respectively. "anglegrad" is the angle
between the 3N-length energy gradient vector of replica *i* and that of
replica *i*\ +1. It is not defined for the final replica and reads nan.
gradV is the norm of the energy gradient of image *i* (:math:`\nabla
V`). ReplicaForce is the two-norm of the 3N-length force vector
(including nudging forces) for replica *i*. MaxAtomForce is the maximum
force component of any atom in replica *i*.
When a NEB calculation does not converge properly, the supplementary
information can help understanding what is going wrong. For instance
@ -427,7 +450,7 @@ Related commands
Default
"""""""
none
*verbosity* = *default*
----------

12
doc/src/pair_coeff.rst
View File

@ -131,21 +131,21 @@ for
csh, tcsh:
.. parsed-literal::
.. code-block:: tcsh
% setenv LAMMPS_POTENTIALS /path/to/lammps/potentials
setenv LAMMPS_POTENTIALS /path/to/lammps/potentials
bash:
.. parsed-literal::
.. code-block:: bash
% export LAMMPS_POTENTIALS=/path/to/lammps/potentials
export LAMMPS_POTENTIALS=/path/to/lammps/potentials
Windows:
.. parsed-literal::
.. code-block:: console
% set LAMMPS_POTENTIALS="C:\\Path to LAMMPS\\Potentials"
set LAMMPS_POTENTIALS="C:\\Path to LAMMPS\\Potentials"
The ``LAMMPS_POTENTIALS`` environment variable may contain paths
to multiple folders, if they are separated by ";" on Windows and

170
doc/src/pair_lepton.rst Normal file
View File

@ -0,0 +1,170 @@
.. index:: pair_style lepton
.. index:: pair_style lepton/omp
.. index:: pair_style lepton/coul
.. index:: pair_style lepton/coul/omp
pair_style lepton command
=========================
Accelerator Variants: *lepton/omp*, *lepton/coul/comp*
Syntax
""""""
.. code-block:: LAMMPS
pair_style style args
* style = *lepton* or *lepton/coul*
* args = list of arguments for a particular style
.. parsed-literal::
*lepton* args = cutoff
cutoff = global cutoff for the interactions (distance units)
*lepton/coul* args = cutoff keyword
cutoff = global cutoff for the interactions (distance units)
zero or more keywords may be appended
keyword = *ewald* or *pppm* or *msm* or *dispersion* or *tip4p*
Examples
""""""""
.. code-block:: LAMMPS
pair_style lepton 2.5
pair_coeff * * "k*((r-r0)^2*step(r0-r)); k=200; r0=1.5" 2.0
pair_coeff 1 2 "4.0*eps*((sig/r)^12 - (sig/r)^6);eps=1.0;sig=1.0" 1.12246204830937
pair_coeff 2 2 "eps*(2.0*(sig/r)^9 - 3.0*(sig/r)^6);eps=1.0;sig=1.0"
pair_coeff 1 3 "zbl(13,6,r)"
pair_coeff 3 3 "(1.0-switch)*zbl(6,6,r)-switch*4.0*eps*((sig/r)^6);switch=0.5*(tanh(10.0*(r-sig))+1.0);eps=0.05;sig=3.20723"
pair_style lepton/coul 2.5
pair_coeff 1 1 "qi*qj/r" 4.0
pair_coeff 1 2 "lj+coul; lj=4.0*eps*((sig/r)^12 - (sig/r)^6); eps=1.0; sig=1.0; coul=qi*qj/r"
pair_style lepton/coul 2.5 pppm
kspace_style pppm 1.0e-4
pair_coeff 1 1 "qi*qj/r*erfc(alpha*r); alpha=1.067"
Description
"""""""""""
.. versionadded:: TBD
Pair styles *lepton* and *lepton/coul* compute pairwise interactions
between particles which depend solely on the distance and have a cutoff.
The potential function must be provided as an expression string using
"r" as the distance variable. With pair style *lepton/coul* one may
additionally reference the charges of the two atoms of the pair with
"qi" and "qj", respectively. Note that further constants in the
expression can be defined in the same string as additional expressions
separated by semi-colons as shown in the examples above.
The expression `"200.0*(r-1.5)^2"` represents a harmonic potential
around the pairwise distance :math:`r_0` of 1.5 distance units and a
force constant *K* of 200.0 energy units:
.. math::
U_{ij} = K (r-r_0)^2
The expression `"qi*qj/r"` represents a regular Coulombic potential with cutoff:
.. math::
U_{ij} = \frac{C q_i q_j}{\epsilon r} \qquad r < r_c
The `Lepton library <https://simtk.org/projects/lepton>`_, that the
*lepton* pair style interfaces with, evaluates this expression string at
run time to compute the pairwise energy. It also creates an analytical
representation of the first derivative of this expression with respect
to "r" and then uses that to compute the force between the pairs of
particles within the given cutoff.
The following coefficients must be defined for each pair of atoms types
via the :doc:`pair_coeff <pair_coeff>` command as in the examples above,
or in the data file or restart files read by the :doc:`read_data
<read_data>` or :doc:`read_restart <read_restart>` commands:
* Lepton expression (energy units)
* cutoff (distance units)
The Lepton expression must be either enclosed in quotes or must not
contain any whitespace so that LAMMPS recognizes it as a single keyword.
More on valid Lepton expressions below. The last coefficient is
optional; it allows to set the cutoff for a pair of atom types to a
different value than the global cutoff.
For pair style *lepton* only the "lj" value of the :doc:`special_bonds <special_bonds>`
settings apply in case the interacting pair is also connected with a bond.
The potential energy will *only* be added to the "evdwl" property.
For pair style *lepton/coul* only the "coul" value of the :doc:`special_bonds <special_bonds>`
settings apply in case the interacting pair is also connected with a bond.
The potential energy will *only* be added to the "ecoul" property.
In addition to the functions listed below, both pair styles support in
addition a custom "zbl(zi,zj,r)" function which computes the
Ziegler-Biersack-Littmark (ZBL) screened nuclear repulsion for
describing high-energy collisions between atoms. For details of the
function please see the documentation for :doc:`pair style zbl
<pair_zbl>`. The arguments of the function are the atomic numbers of
atom i (zi), atom j (zj) and the distance r. Please see the examples
above.
----------
.. include:: lepton_expression.rst
----------
.. include:: accel_styles.rst
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Pair styles *lepton* and *lepton/coul* do not support mixing. Thus,
expressions for *all* I,J pairs must be specified explicitly.
Only pair style *lepton* supports the :doc:`pair_modify shift <pair_modify>`
option for shifting the energy of the pair interaction so that it is
0 at the cutoff, pair style *lepton/coul* does *not*.
The :doc:`pair_modify table <pair_modify>` options are not relevant for
the these pair styles.
These pair styles do not support the :doc:`pair_modify tail
<pair_modify>` option for adding long-range tail corrections to energy
and pressure.
These pair styles write its information to :doc:`binary restart files
<restart>`, so pair_style and pair_coeff commands do not need to be
specified in an input script that reads a restart file.
These pair styles can only be used via the *pair* keyword of the
:doc:`run_style respa <run_style>` command. They do not support the
*inner*, *middle*, *outer* keywords.
----------
Restrictions
""""""""""""
These pair styles are part of the LEPTON package and only enabled if
LAMMPS was built with this package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""
:doc:`pair_coeff <pair_coeff>`, :doc:`pair_style python <pair_python>`,
:doc:`pair_style table <pair_table>`, :doc:`pair_write <pair_write>`
Default
"""""""
none

2
doc/src/pair_morse.rst
View File

@ -107,7 +107,7 @@ I,J pairs must be specified explicitly.
All of these pair styles support the :doc:`pair_modify <pair_modify>`
shift option for the energy of the pair interaction.
The :doc:`pair_modify <pair_modify>` table options is not relevant for
The :doc:`pair_modify <pair_modify>` table options are not relevant for
the Morse pair styles.
None of these pair styles support the :doc:`pair_modify <pair_modify>`

6
doc/src/pair_pace.rst
View File

@ -1,6 +1,7 @@
.. index:: pair_style pace
.. index:: pair_style pace/kk
.. index:: pair_style pace/extrapolation
.. index:: pair_style pace/extrapolation/kk
pair_style pace command
=======================
@ -127,6 +128,9 @@ but not more often than every 20 steps.
On all other steps `pair_style pace recursive` will be used.
When using the pair style *pace/extrapolation* with the KOKKOS package on GPUs
product B-basis evaluator is always used and only *linear* ASI is supported.
----------
See the :doc:`pair_coeff <pair_coeff>` page for alternate ways
@ -186,4 +190,4 @@ recursive, chunksize = 4096,
.. _Lysogorskiy2022:
**(Lysogorskiy2022)** Lysogorskiy, Bochkarev, Mrovec, Drautz, TBS (2022).
**(Lysogorskiy2022)** Lysogorskiy, Bochkarev, Mrovec, Drautz, arXiv:2212.08716 (2022).

2
doc/src/pair_style.rst
View File

@ -212,6 +212,8 @@ accelerated styles exist.
* :doc:`lcbop <pair_lcbop>` - long-range bond-order potential (LCBOP)
* :doc:`lebedeva/z <pair_lebedeva_z>` - Lebedeva interlayer potential for graphene with normals along z-axis
* :doc:`lennard/mdf <pair_mdf>` - LJ potential in A/B form with a taper function
* :doc:`lepton <pair_lepton>` - pair potential from evaluating a string
* :doc:`lepton/coul <pair_lepton>` - pair potential from evaluating a string with support for charges
* :doc:`line/lj <pair_line_lj>` - LJ potential between line segments
* :doc:`list <pair_list>` - potential between pairs of atoms explicitly listed in an input file
* :doc:`lj/charmm/coul/charmm <pair_charmm>` - CHARMM potential with cutoff Coulomb

9
doc/src/pair_table.rst
View File

@ -122,10 +122,11 @@ best effect:
Suitable tables in the correct format for use with these pair styles can
be created by LAMMPS itself using the :doc:`pair_write <pair_write>`
command. In combination with the :doc:`pair style python <pair_python>`
this can be a powerful mechanism to implement and test tables for use
with LAMMPS. Another option to generate tables is the Python code in
the ``tools/tabulate`` folder of the LAMMPS source code distribution.
command. In combination with the pair styles :doc:`python <pair_python>`,
:doc:`lepton, or lepton/coul <pair_lepton>` this can be a powerful
mechanism to implement and test tables for use with LAMMPS. Another
option to generate tables is the Python code in the ``tools/tabulate``
folder of the LAMMPS source code distribution.
The format of a tabulated file has an (optional) header followed by a
series of one or more sections, defined as follows (without the

2
doc/src/pair_zero.rst
View File

@ -46,6 +46,8 @@ section for any pair style. Similarly, any pair_coeff commands
will only be checked for the atom type numbers and the rest ignored.
In this case, only the global cutoff will be used.
.. versionadded:: 3Nov2022
The optional *full* flag builds a full neighbor list instead of the default
half neighbor list.

4
doc/src/read_dump.rst
View File

@ -161,7 +161,7 @@ snapshot was written on for the *native* or *adios* formats.
The list of timestamps available in an adios .bp file is stored in the
variable *ntimestep*:
.. parsed-literal::
.. parsed-literal:: console
$ bpls dump.bp -d ntimestep
uint64_t ntimestep 5*scalar
@ -253,7 +253,7 @@ except for the *q* charge field.
The list of fields stored in an adios .bp file is recorded in the attributes
*columns* (array of short strings) and *columnstr* (space-separated single string).
.. parsed-literal::
.. parsed-literal:: console
$ bpls -la dump.bp column*
string columns attr = {"id", "type", "x", "y", "z", "vx", "vy", "vz"}

2
doc/src/shell.rst
View File

@ -105,7 +105,7 @@ would be the same as invoking
.. code-block:: bash
% my_setup file1 10 file2
my_setup file1 10 file2
from a command-line prompt. The executable program "my_setup" is run
with 3 arguments: file1 10 file2.