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

Merge branch 'master' into reset-invalid-image-flags

Browse Source
This commit is contained in:
Axel Kohlmeyer
2020-11-11 16:15:11 -05:00
parent fcd6074190 c0a101192e
commit a96cb43957
1902 changed files with 74950 additions and 66033 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Build.rst
View File

@ -1,5 +1,5 @@
Build LAMMPS
************
============
LAMMPS is built as a library and an executable from source code using
either traditional makefiles for use with GNU make (which may require

9
doc/src/Build_basics.rst
View File

@ -299,10 +299,11 @@ LAMMPS.
then you have either an unsupported (old) compiler or you have
to turn on C++11 mode. The latter applies to GCC 4.8.x shipped
with RHEL 7.x and CentOS 7.x. For those compilers, you need to
add the ``-std=c++11`` flag. Otherwise, you would have to
install a newer compiler that supports C++11; either as a
binary package or through compiling from source.
with RHEL 7.x and CentOS 7.x or GCC 5.4.x shipped with Ubuntu16.04.
For those compilers, you need to add the ``-std=c++11`` flag.
If there is no compiler that supports this flag (or equivalent),
you would have to install a newer compiler that supports C++11;
either as a binary package or through compiling from source.
If you build LAMMPS with any :doc:`Speed_packages` included,
there may be specific compiler or linker flags that are either

2
doc/src/Build_cmake.rst
View File

@ -1,5 +1,5 @@
Build LAMMPS with CMake
=======================
-----------------------
This page describes how to use `CMake <https://cmake.org>`_ in general
to build LAMMPS. Details for specific compile time settings and options

4
doc/src/Build_manual.rst
View File

@ -73,8 +73,8 @@ after the documentation folder is returned to a pristine state with
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into
that virtual environment via the ``pip`` tool. For rendering embedded
LaTeX code also the `MathJax <https://www.mathjax.org/>`_ and the
`Polyfill <https://polyfill.io/>`_ JavaScript engines need to be downloaded.
LaTeX code also the `MathJax <https://www.mathjax.org/>`_ JavaScript
engine needs to be downloaded.
The actual translation is then done via ``make`` commands in the doc
folder. The following ``make`` commands are available:

9
doc/src/Build_package.rst
View File

@ -158,6 +158,7 @@ one of them as a starting point and customize it to your needs.
cmake -C ../cmake/presets/download.cmake [OPTIONS] ../cmake # enable packages which download sources or potential files
cmake -C ../cmake/presets/nolib.cmake [OPTIONS] ../cmake # disable packages that do require extra libraries or tools
cmake -C ../cmake/presets/clang.cmake [OPTIONS] ../cmake # change settings to use the Clang compilers by default
cmake -C ../cmake/presets/gcc.cmake [OPTIONS] ../cmake # change settings to use the GNU compilers by default
cmake -C ../cmake/presets/intel.cmake [OPTIONS] ../cmake # change settings to use the Intel compilers by default
cmake -C ../cmake/presets/all_on.cmake [OPTIONS] ../cmake # enable all packages
cmake -C ../cmake/presets/all_off.cmake [OPTIONS] ../cmake # disable all packages
@ -166,9 +167,11 @@ one of them as a starting point and customize it to your needs.
.. note::
Running cmake this way manipulates the CMake settings cache in your
current build directory. You can combine multiple presets and options
current build directory. You can combine multiple presets and options
in a single cmake run, or change settings incrementally by running
cmake with new flags.
cmake with new flags. If you use a present for selecting a set of
compilers, it will reset all settings from previous CMake runs.
Example
"""""""
@ -187,7 +190,7 @@ Example
# to reset the package selection from above to the default of no packages
# but leaving all other settings untouched. You can run:
cmake -C ../cmake/presets/no_all.cmake .
cmake -C ../cmake/presets/all_off.cmake .
----------

102
doc/src/Build_windows.rst
View File

@ -1,5 +1,5 @@
Notes for building LAMMPS on Windows
====================================
------------------------------------
* :ref:`General remarks <generic>`
* :ref:`Running Linux on Windows <linux>`
@ -11,59 +11,58 @@ Notes for building LAMMPS on Windows
.. _generic:
General remarks
-----------------------------
^^^^^^^^^^^^^^^
LAMMPS is developed and tested primarily on Linux machines. The vast
majority of HPC clusters and supercomputers today runs on Linux as well.
majority of HPC clusters and supercomputers today run on Linux as well.
While portability to other platforms is desired, it is not always achieved.
The LAMMPS developers strongly rely on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This is particularly
The LAMMPS developers are dependent on LAMMPS users giving feedback and
providing assistance in resolving portability issues. This is particularly
true for compiling LAMMPS on Windows, since this platform has significant
differences with some low-level functionality.
differences in some low-level functionality.
.. _linux:
Running Linux on Windows
------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^
So before trying to build LAMMPS on Windows, please consider if using
the pre-compiled Windows binary packages are sufficient for your needs
(as an aside, those packages themselves are build on a Linux machine
using cross-compilers). If it is necessary for you to compile LAMMPS
on a Windows machine (e.g. because it is your main desktop), please also
consider using a virtual machine software and compile and run LAMMPS in
a Linux virtual machine, or - if you have a recently updated Windows 10
Before trying to build LAMMPS on Windows, please consider if the
pre-compiled Windows binary packages are sufficient for your needs. If
it is necessary for you to compile LAMMPS on a Windows machine
(e.g. because it is your main desktop), please also consider using a
virtual machine software and compile and run LAMMPS in a Linux virtual
machine, or - if you have a sufficiently up-to-date Windows 10
installation - consider using the Windows subsystem for Linux. This
optional Windows feature allows you to run the bash shell from Ubuntu
from within Windows and from there on, you can pretty much use that
shell like you are running on an Ubuntu Linux machine (e.g. installing
software via apt-get and more). For more details on that, please
see :doc:`this tutorial <Howto_wsl>`.
software via apt-get and more). For more details on that, please see
:doc:`this tutorial <Howto_wsl>`.
.. _gnu:
Using a GNU GCC ported to Windows
-----------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One option for compiling LAMMPS on Windows natively, that has been known
One option for compiling LAMMPS on Windows natively that has been known
to work in the past is to install a bash shell, unix shell utilities,
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin package
provides a unix/linux interface to low-level Windows functions, so LAMMPS
can be compiled on Windows. The necessary (minor) modifications to LAMMPS
are included, but may not always up-to-date for recently added functionality
and the corresponding new code. A machine makefile for using cygwin for
the old build system is provided. Using CMake for this mode of compilation
is untested and not likely to work.
perl, GNU make, and a GNU compiler ported to Windows. The Cygwin
package provides a unix/linux interface to low-level Windows functions,
so LAMMPS can be compiled on Windows. The necessary (minor)
modifications to LAMMPS are included, but may not always up-to-date for
recently added functionality and the corresponding new code. A machine
makefile for using cygwin for the old build system is provided. Using
CMake for this mode of compilation is untested and not likely to work.
When compiling for Windows do **not** set the -DLAMMPS_MEMALIGN define
in the LMP_INC makefile variable and add -lwsock32 -lpsapi to the linker
flags in LIB makefile variable. Try adding -static-libgcc or -static or
both to the linker flags when your resulting LAMMPS Windows executable
complains about missing .dll files. The CMake configuration should set
this up automatically, but is untested.
When compiling for Windows do **not** set the ``-DLAMMPS_MEMALIGN``
define in the LMP_INC makefile variable and add ``-lwsock32 -lpsapi`` to
the linker flags in LIB makefile variable. Try adding ``-static-libgcc``
or ``-static`` or both to the linker flags when your resulting LAMMPS
Windows executable complains about missing .dll files. The CMake
configuration should set this up automatically, but is untested.
In case of problems, you are recommended to contact somebody with
experience in using cygwin. If you do come across portability problems
experience in using Cygwin. If you do come across portability problems
requiring changes to the LAMMPS source code, or figure out corrections
yourself, please report them on the lammps-users mailing list, or file
them as an issue or pull request on the LAMMPS GitHub project.
@ -71,31 +70,23 @@ them as an issue or pull request on the LAMMPS GitHub project.
.. _cross:
Using a cross-compiler
----------------------------------
^^^^^^^^^^^^^^^^^^^^^^
If you need to provide custom LAMMPS binaries for Windows, but do not
need to do the compilation on Windows, please consider using a Linux
to Windows cross-compiler. This is how currently the Windows binary
packages are created by the LAMMPS developers. Because of that, this is
need to do the compilation on Windows, please consider using a Linux to
Windows cross-compiler. This is how currently the Windows binary
packages are created by the LAMMPS developers. Because of that, this is
probably the currently best tested and supported way to build LAMMPS
executables for Windows. There are makefiles provided for the
traditional build system, but CMake has also been successfully tested
using the mingw32-cmake and mingw64-cmake wrappers that are bundled
with the cross-compiler environment on Fedora machines. A CMake preset
selecting all packages compatible with this cross-compilation build
is provided. The GPU package can only be compiled with OpenCL support
and you need to download and install the pre-compiled
`OpenCL ICD loader library <https://download.lammps.org/thirdparty/opencl-win-devel.tar.gz>`_
into your MinGW64 cross-compiler environment. With CMake this will be
done transparently. To compile with MPI support, a pre-compiled
library and the corresponding header files are required. There is
`one package for 32-bit Windows <https://download.lammps.org/thirdparty/mpich2-win32-devel.tar.gz>`_
and `a second package for 64-bit Windows <https://download.lammps.org/thirdparty/mpich2-win64-devel.tar.gz>`_.
When building with CMake, the matching package will be downloaded
automatically, but MPI support has to be explicitly enabled with ``-DBUILD_MPI=on``.
executables for Windows. A CMake preset selecting all packages
compatible with this cross-compilation build is provided. The GPU
package can only be compiled with OpenCL support. To compile with MPI
support, a pre-compiled library and the corresponding header files are
required. When building with CMake the matching package will be
downloaded automatically, but MPI support has to be explicitly enabled
with ``-DBUILD_MPI=on``.
Please keep in mind, though, that this only applies to **compiling** LAMMPS.
Whether the resulting binaries do work correctly is not tested by the
Whether the resulting binaries do work correctly is rarely tested by the
LAMMPS developers. We instead rely on the feedback of the users
of these pre-compiled LAMMPS packages for Windows. We will try to resolve
issues to the best of our abilities if we become aware of them. However
@ -104,9 +95,10 @@ this is subject to time constraints and focus on HPC platforms.
.. _native:
Native Visual C++ support
--------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^
Support for the Visual C++ compilers is currently not available. The
CMake build system is capable of creating suitable a Visual Studio
style build environment, but the LAMMPS code itself is not fully ported
to support Visual C++. Volunteers to take on this task are welcome.
style build environment, but the LAMMPS source code itself is not
ported to fully support Visual C++. Volunteers to take on this task
are welcome.

4
doc/src/Classes.rst
View File

@ -1,5 +1,5 @@
LAMMPS C++ base classes
=======================
C++ base classes
================
LAMMPS is designed to be used as a C++ class library where one can set
up and drive a simulation through creating a class instance and then

6
doc/src/Developer.rst
View File

@ -1,5 +1,5 @@
LAMMPS Developer Guide
**********************
Information for Developers
==========================
This section describes the internal structure and basic algorithms
of the LAMMPS code. This is a work in progress and additional
@ -13,5 +13,5 @@ of time and requests from the LAMMPS user community.
Developer_org
Developer_flow
Developer_write
Developer_utils
Classes
Developer_utils

2
doc/src/Developer_flow.rst
View File

@ -1,5 +1,5 @@
How a timestep works
====================
--------------------
The first and most fundamental operation within LAMMPS to understand is
how a timestep is structured. Timestepping is performed by calling

10
doc/src/Developer_org.rst
View File

@ -1,5 +1,5 @@
LAMMPS source files
===================
Source files
------------
The source files of the LAMMPS code are found in two
directories of the distribution: ``src`` and ``lib``.
@ -46,8 +46,8 @@ class. They are discussed in the next section.
A small number of C++ classes and utility functions are implemented with
only a ``.h`` file. Examples are the Pointer class or the MathVec functions.
LAMMPS class topology
=====================
Class topology
--------------
Though LAMMPS has a lot of source files and classes, its class topology
is relative flat, as outlined in the :ref:`class-topology` figure. Each
@ -78,7 +78,7 @@ in the figure for demonstration purposes.
the core is the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class, which
holds pointers to class instances with specific purposes. Those may
hold instances of other classes, sometimes directly, or only
temporarily, sometimes as derived classes or derived classes or
temporarily, sometimes as derived classes or derived classes of
derived classes, which may also hold instances of other classes.
The :cpp:class:`LAMMPS_NS::LAMMPS` class is the topmost class and

54
doc/src/Developer_utils.rst
View File

@ -1,6 +1,6 @@
LAMMPS utility functions
========================
Utility functions
-----------------
The ``utils`` sub-namespace inside the ``LAMMPS_NS`` namespace provides
a collection of convenience functions and utilities that perform common
@ -172,29 +172,8 @@ Customized standard functions
---------------------------
Communication buffer coding with *ubuf*
=========================================
LAMMPS uses communication buffers where it collects data from various
class instances and then exchanges the data with neighboring sub-domains.
For simplicity those buffers are defined as ``double`` buffers and
used for doubles and integer numbers. This presents a unique problem
when 64-bit integers are used. While the storage needed for a ``double``
is also 64-bit, it cannot be used by a simple assignment. To get around
that limitation, LAMMPS uses the :cpp:union:`ubuf <LAMMPS_NS::ubuf>`
union. It is used in the various "pack" and "unpack" functions in the
LAMMPS classes to store and retrieve integers that may be 64-bit from
the communication buffers.
---------------------------
.. doxygenunion:: LAMMPS_NS::ubuf
:project: progguide
---------------------------
Tokenizer classes
=================
-----------------
The purpose of the tokenizer classes is to simplify the recurring task
of breaking lines of text down into words and/or numbers.
@ -308,7 +287,7 @@ This code example should produce the following output:
----------
File reader classes
====================
-------------------
The purpose of the file reader classes is to simplify the recurring task
of reading and parsing files. They can use the
@ -382,7 +361,7 @@ A file that would be parsed by the reader code fragment looks like this:
----------
Memory pool classes
===================
-------------------
The memory pool classes are used for cases where otherwise many
small memory allocations would be needed and where the data would
@ -446,7 +425,7 @@ its size is registered later with :cpp:func:`vgot()
----------
Eigensolver functions
=====================
---------------------
The ``MathEigen`` sub-namespace of the ``LAMMPS_NS`` namespace contains
functions and classes for eigensolvers. Currently only the
@ -482,3 +461,24 @@ Tohoku University (under MIT license)
.. doxygenfunction:: MathEigen::jacobi3(double const mat[3][3], double *eval, double evec[3][3])
:project: progguide
---------------------------
Communication buffer coding with *ubuf*
---------------------------------------
LAMMPS uses communication buffers where it collects data from various
class instances and then exchanges the data with neighboring sub-domains.
For simplicity those buffers are defined as ``double`` buffers and
used for doubles and integer numbers. This presents a unique problem
when 64-bit integers are used. While the storage needed for a ``double``
is also 64-bit, it cannot be used by a simple assignment. To get around
that limitation, LAMMPS uses the :cpp:union:`ubuf <LAMMPS_NS::ubuf>`
union. It is used in the various "pack" and "unpack" functions in the
LAMMPS classes to store and retrieve integers that may be 64-bit from
the communication buffers.
---------------------------
.. doxygenunion:: LAMMPS_NS::ubuf
:project: progguide

4
doc/src/Developer_write.rst
View File

@ -1,5 +1,5 @@
Writing LAMMPS styles
=====================
Writing new styles
------------------
The :doc:`Modify` section of the manual gives an overview of how LAMMPS can
be extended by writing new classes that derive from existing

18
doc/src/Fortran.rst
View File

@ -19,10 +19,12 @@ for a simple program using the Fortran interface would be:
mpifort -o testlib.x lammps.f90 testlib.f90 -L. -llammps
Please note, that the MPI compiler wrapper is only required when the
calling the library from an MPI parallel code. Please also note the order
of the source files: the lammps.f90 file needs to be compiled first,
since it provides the ``LIBLAMMPS`` module that is imported by the
Fortran code using the interface.
calling the library from an MPI parallel code. Please also note the
order of the source files: the ``lammps.f90`` file needs to be compiled
first, since it provides the ``LIBLAMMPS`` module that is imported by
the Fortran code using the interface. A working example code can be
found together with equivalent examples in C and C++ in the
``examples/COUPLE/simple`` folder of the LAMMPS distribution.
.. versionadded:: 9Oct2020
@ -36,11 +38,11 @@ Fortran code using the interface.
.. note::
A contributed (and complete!) Fortran interface that is more
closely resembling the C-library interface is available
A contributed (and complete!) Fortran interface that more
closely resembles the C-library interface is available
in the ``examples/COUPLE/fortran2`` folder. Please see the
``README`` file in that folder for more information about that
Fortran interface and how to contact its author and maintainer.
``README`` file in that folder for more information about it
and how to contact its author and maintainer.
----------

12
doc/src/Howto_cmake.rst
View File

@ -401,11 +401,19 @@ It is also possible to do this incrementally.
cmake -C ../cmake/presets/minimal.cmake ../cmake
cmake -D PKG_MISC=on .
will achieve the same configuration like in the first example above. In
this scenario it is particularly convenient to do the second
will achieve the same final configuration as in the first example above.
In this scenario it is particularly convenient to do the second
configuration step using either the text mode or graphical user
interface (``ccmake`` or ``cmake-gui``).
.. note::
Using a preset to select a compiler package (``clang.cmake``,
``gcc.cmake``, or ``intel.cmake``) are an exception to the option
of updating the configuration incrementally, as they will trigger
a reset of cached internal CMake settings and thus reset them to
their default values.
Compilation and build targets
-----------------------------

4
doc/src/Howto_library.rst
View File

@ -32,6 +32,6 @@ concurrently), grab data from LAMMPS, change it, and send it back into
LAMMPS.
A detailed documentation of the available APIs and examples of how to
use them can be found in the :doc:`Programmer Documentation
<Library>` section of this manual.
use them can be found in the :ref:`Programmer Guide <programmer_documentation>`
section of this manual.

2
doc/src/Install.rst
View File

@ -1,5 +1,5 @@
Install LAMMPS
**************
==============
You can download LAMMPS as an executable or as source code.

2
doc/src/Install_conda.rst
View File

@ -1,5 +1,5 @@
Download an executable for Linux or Mac via Conda
=================================================
-------------------------------------------------
Binaries are available for MacOS or Linux via `Conda <conda_>`_.

2
doc/src/Install_git.rst
View File

@ -1,5 +1,5 @@
Download the LAMMPS source with git
===================================
-----------------------------------
All LAMMPS development is coordinated through the "LAMMPS GitHub
site". If you clone the LAMMPS repository onto your local machine, it

14
doc/src/Install_linux.rst
View File

@ -1,5 +1,5 @@
Download an executable for Linux
================================
--------------------------------
Binaries are available for different versions of Linux:
@ -16,7 +16,7 @@ Binaries are available for different versions of Linux:
.. _ubuntu:
Pre-built Ubuntu Linux executables
-----------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A pre-built LAMMPS executable suitable for running on the latest
Ubuntu Linux versions, can be downloaded as a Debian package. This
@ -108,7 +108,7 @@ Ubuntu package capability.
.. _fedora:
Pre-built Fedora Linux executables
-----------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pre-built LAMMPS packages for stable releases are available
in the Fedora Linux distribution as of version 28. The packages
@ -162,7 +162,7 @@ Thanks to Christoph Junghans (LANL) for making LAMMPS available in Fedora.
.. _epel:
Pre-built EPEL Linux executable
------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pre-built LAMMPS (and KIM) packages for stable releases are available
in the `Extra Packages for Enterprise Linux (EPEL) repository <https://fedoraproject.org/wiki/EPEL>`_
@ -182,7 +182,7 @@ Thanks to Christoph Junghans (LANL) for making LAMMPS available in EPEL.
.. _opensuse:
Pre-built OpenSuse Linux executable
--------------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A pre-built LAMMPS package for stable releases is available
in OpenSuse as of Leap 15.0. You can install the package with:
@ -217,7 +217,7 @@ Thanks to Christoph Junghans (LANL) for making LAMMPS available in OpenSuse.
.. _gentoo:
Gentoo Linux executable
------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^
LAMMPS is part of Gentoo's main package tree and can be installed by
typing:
@ -245,7 +245,7 @@ this Gentoo capability.
.. _arch:
Archlinux build-script
---------------------------------
^^^^^^^^^^^^^^^^^^^^^^
LAMMPS is available via Arch's unofficial Arch User repository (AUR).
There are three scripts available, named lammps, lammps-beta and lammps-git.

2
doc/src/Install_mac.rst
View File

@ -1,5 +1,5 @@
Download an executable for Mac
==============================
------------------------------
LAMMPS can be downloaded, built, and configured for OS X on a Mac with
`Homebrew <homebrew_>`_. (Alternatively, see the install instructions for

2
doc/src/Install_patch.rst
View File

@ -1,5 +1,5 @@
Applying patches
================
----------------
It is easy to stay current with the most recent LAMMPS patch releases
if you use git to track the LAMMPS development. Instructions for

2
doc/src/Install_tarball.rst
View File

@ -1,5 +1,5 @@
Download source and documentation as a tarball
==============================================
----------------------------------------------
You can download a current LAMMPS tarball from the `download page <download_>`_
of the `LAMMPS website <lws_>`_.

2
doc/src/Install_windows.rst
View File

@ -1,5 +1,5 @@
Download an executable for Windows
==================================
----------------------------------
Pre-compiled Windows installers which install LAMMPS executables on a
Windows system can be downloaded from this site:

2
doc/src/Intro.rst
View File

@ -1,5 +1,5 @@
Introduction
************
============
These pages provide a brief introduction to LAMMPS.

2
doc/src/Intro_authors.rst
View File

@ -1,5 +1,5 @@
Authors of LAMMPS
=================
-----------------
The primary LAMMPS developers are at Sandia National Labs and Temple
University:

14
doc/src/Intro_citing.rst
View File

@ -1,5 +1,5 @@
Citing LAMMPS
=============
-------------
Core Algorithms
^^^^^^^^^^^^^^^
@ -24,13 +24,15 @@ DOI for the LAMMPS code
LAMMPS developers use the `Zenodo service at CERN
<https://zenodo.org/>`_ to create digital object identifies (DOI) for
stable releases of the LAMMPS code. There are two types of DOIs for the
LAMMPS source code: 1) the canonical DOI for **all** versions of LAMMPS,
which will always point to the latest stable release version is:
LAMMPS source code: the canonical DOI for **all** versions of LAMMPS,
which will always point to the **latest** stable release version is:
`DOI: 10.5281/zenodo.3726416 <https://dx.doi/org/10.5281/zenodo.3726416>`_
- DOI: `10.5281/zenodo.3726416 <https://dx.doi.org/10.5281/zenodo.3726416>`_
In addition there are DOIs for individual stable releases starting with
the `3 March 2020 version, DOI:10.5281/zenodo.3726417 <https://dx.doi/org/10.5281/zenodo.3726416>`_
In addition there are DOIs for individual stable releases. Currently there are:
- 3 March 2020 version: `DOI:10.5281/zenodo.3726417 <https://dx.doi.org/10.5281/zenodo.3726417>`_
- 29 October 2020 version: `DOI:10.5281/zenodo.4157471 <https://dx.doi.org/10.5281/zenodo.4157471>`_
Home page

36
doc/src/Intro_features.rst
View File

@ -1,5 +1,5 @@
LAMMPS features
===============
---------------
LAMMPS is a classical molecular dynamics (MD) code with these general
classes of functionality:
@ -21,7 +21,7 @@ classes of functionality:
.. _general:
General features
------------------------------
^^^^^^^^^^^^^^^^
* runs on a single processor or in parallel
* distributed-memory message-passing parallelism (MPI)
@ -41,9 +41,9 @@ General features
.. _particle:
Particle and model types
---------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^
(:doc:`atom style <atom_style>` command)
(See :doc:`atom style <atom_style>` command)
* atoms
* coarse-grained particles (e.g. bead-spring polymers)
@ -61,9 +61,9 @@ Particle and model types
.. _ff:
Interatomic potentials (force fields)
----------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(:doc:`pair style <pair_style>`, :doc:`bond style <bond_style>`,
(See :doc:`pair style <pair_style>`, :doc:`bond style <bond_style>`,
:doc:`angle style <angle_style>`, :doc:`dihedral style <dihedral_style>`,
:doc:`improper style <improper_style>`, :doc:`kspace style <kspace_style>`
commands)
@ -92,9 +92,9 @@ commands)
.. _create:
Atom creation
--------------------------
^^^^^^^^^^^^^
(:doc:`read_data <read_data>`, :doc:`lattice <lattice>`,
(See :doc:`read_data <read_data>`, :doc:`lattice <lattice>`,
:doc:`create_atoms <create_atoms>`, :doc:`delete_atoms <delete_atoms>`,
:doc:`displace_atoms <displace_atoms>`, :doc:`replicate <replicate>` commands)
@ -107,9 +107,9 @@ Atom creation
.. _ensemble:
Ensembles, constraints, and boundary conditions
--------------------------------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(:doc:`fix <fix>` command)
(See :doc:`fix <fix>` command)
* 2d or 3d systems
* orthogonal or non-orthogonal (triclinic symmetry) simulation domains
@ -129,9 +129,9 @@ Ensembles, constraints, and boundary conditions
.. _integrate:
Integrators
---------------------------
^^^^^^^^^^^
(:doc:`run <run>`, :doc:`run_style <run_style>`, :doc:`minimize <minimize>` commands)
(See :doc:`run <run>`, :doc:`run_style <run_style>`, :doc:`minimize <minimize>` commands)
* velocity-Verlet integrator
* Brownian dynamics
@ -143,14 +143,14 @@ Integrators
.. _diag:
Diagnostics
----------------------
^^^^^^^^^^^
* see various flavors of the :doc:`fix <fix>` and :doc:`compute <compute>` commands
.. _output:
Output
-------------------
^^^^^^
(:doc:`dump <dump>`, :doc:`restart <restart>` commands)
@ -167,7 +167,7 @@ Output
.. _replica1:
Multi-replica models
-----------------------------------
^^^^^^^^^^^^^^^^^^^^
* :doc:`nudged elastic band <neb>`
* :doc:`parallel replica dynamics <prd>`
@ -177,11 +177,11 @@ Multi-replica models
.. _prepost:
Pre- and post-processing
--------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^
* A handful of pre- and post-processing tools are packaged with LAMMPS,
some of which can convert input and output files to/from formats used
by other codes; see the :doc:`Tools <Tools>` doc page.
by other codes; see the :doc:`Tools <Tools>` page.
* Our group has also written and released a separate toolkit called
`Pizza.py <pizza_>`_ which provides tools for doing setup, analysis,
plotting, and visualization for LAMMPS simulations. Pizza.py is
@ -194,7 +194,7 @@ Pre- and post-processing
.. _special:
Specialized features
----------------------------------
^^^^^^^^^^^^^^^^^^^^
LAMMPS can be built with optional packages which implement a variety
of additional capabilities. See the :doc:`Optional Packages <Packages>`

2
doc/src/Intro_nonfeatures.rst
View File

@ -1,5 +1,5 @@
LAMMPS non-features
===================
-------------------
LAMMPS is designed to be a fast, parallel engine for molecular
dynamics (MD) simulations. It provides only a modest amount of

2
doc/src/Intro_opensource.rst
View File

@ -1,5 +1,5 @@
LAMMPS open-source license
==========================
--------------------------
LAMMPS is a freely-available open-source code, distributed under the
terms of the `GNU Public License <gnu_>`_, which means you can use or

2
doc/src/Intro_overview.rst
View File

@ -1,5 +1,5 @@
Overview of LAMMPS
==================
------------------
LAMMPS is a classical molecular dynamics (MD) code that models
ensembles of particles in a liquid, solid, or gaseous state. It can

2
doc/src/Intro_website.rst
View File

@ -1,5 +1,5 @@
Additional website links
========================
------------------------
The `LAMMPS website <lws_>`_ has a variety of additional info about
LAMMPS, beyond what is in this manual. Some other useful resources

BIN
doc/src/JPG/lammps-classes.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 266 KiB

After

Width:  |  Height:  |  Size: 254 KiB

11
doc/src/Library_create.rst
View File

@ -9,7 +9,6 @@ This section documents the following functions:
- :cpp:func:`lammps_close`
- :cpp:func:`lammps_mpi_init`
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_free`
--------------------
@ -75,11 +74,6 @@ that may only be called once. See :cpp:func:`lammps_mpi_finalize` for
an alternative to invoking ``MPI_Finalize()`` explicitly from the
calling program.
The :cpp:func:`lammps_free` function is a clean-up
function to free memory that the library allocated previously
via other function calls. See below for notes in the descriptions
of the individual commands where such memory buffers were allocated.
-----------------------
.. doxygenfunction:: lammps_open
@ -109,8 +103,3 @@ of the individual commands where such memory buffers were allocated.
.. doxygenfunction:: lammps_mpi_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_free
:project: progguide

12
doc/src/Library_utility.rst
View File

@ -9,11 +9,18 @@ functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_set_fix_external_callback`
- :cpp:func:`lammps_fix_external_set_energy_global`
- :cpp:func:`lammps_fix_external_set_virial_global`
- :cpp:func:`lammps_free`
- :cpp:func:`lammps_is_running`
- :cpp:func:`lammps_force_timeout`
- :cpp:func:`lammps_has_error`
- :cpp:func:`lammps_get_last_error_message`
The :cpp:func:`lammps_free` function is a clean-up function to free
memory that the library had allocated previously via other function
calls. Look for notes in the descriptions of the individual commands
where such memory buffers were allocated that require the use of
:cpp:func:`lammps_free`.
-----------------------
.. doxygenfunction:: lammps_encode_image_flags
@ -41,6 +48,11 @@ functions. They do not directly call the LAMMPS library.
-----------------------
.. doxygenfunction:: lammps_free
:project: progguide
-----------------------
.. doxygenfunction:: lammps_is_running
:project: progguide

57
doc/src/Manual.rst
View File

@ -1,3 +1,4 @@
######################################
LAMMPS version |version| Documentation
######################################
@ -12,19 +13,26 @@ funding for LAMMPS has come from the US Department of Energy (DOE).
LAMMPS is an open-source code, distributed freely under the terms of
the GNU Public License (GPL).
The `LAMMPS website <lws_>`_ has a variety of information about the code.
It includes links to an on-line version of this manual, a `mailing list <https://lammps.sandia.gov/mail.html>`_ where users can post
questions, and a `GitHub site <https://github.com/lammps/lammps>`_ where
all LAMMPS development is coordinated.
The `LAMMPS website <lws_>`_ has a variety of information about the
code. It includes links to an on-line version of this manual, a
`mailing list <https://lammps.sandia.gov/mail.html>`_ where users can
post questions, and a `GitHub site <https://github.com/lammps/lammps>`_
where all LAMMPS development is coordinated.
----------
The content for this manual is part of the LAMMPS distribution. You can
build a local copy of the Manual as HTML pages or a PDF file, by
following the steps on the :doc:`Build_manual` page. The manual is
organized in two parts:
1) the :ref:`User documentation <user_documentation>` for how to install
and use LAMMPS and 2) the :ref:`Programmer documentation <programmer_documentation>`
The content for this manual is part of the LAMMPS distribution. The
online version always corresponds to the latest development version.
If needed, you can download or build a local copy of the manual as
HTML pages or a PDF file by following the steps on the
:doc:`Build_manual` page. If you have difficulties viewing the pages
please :ref:`see this note <webbrowser>`.
-----------
The manual is organized in two parts:
1) the :ref:`User Guide <user_documentation>` for how to install
and use LAMMPS and 2) the :ref:`Programmer Guide <programmer_documentation>`
for how to write programs using the LAMMPS library from different
programming languages and how to modify and extend LAMMPS.
@ -38,14 +46,16 @@ programming languages and how to modify and extend LAMMPS.
----------
User Documentation
******************
************
User Guide
************
.. _user_documentation:
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: User Documentation
:caption: User Guide
:name: userdoc
:includehidden:
@ -61,14 +71,16 @@ User Documentation
Tools
Errors
Programmer Documentation
************************
******************
Programmer Guide
******************
.. _programmer_documentation:
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: Programmer Documentation
:caption: Programmer Guide
:name: progdoc
:includehidden:
@ -93,6 +105,7 @@ Programmer Documentation
fix_modify_atc_commands
Bibliography
******************
Indices and tables
******************
@ -100,3 +113,15 @@ Indices and tables
* :ref:`genindex`
* :ref:`search`
.. _webbrowser:
.. admonition:: Web Browser Compatibility
The HTML version of the manual makes use of advanced features present
int "modern" web browsers. This can lead to incompatibilities with older
web browsers (released more than 4 years ago) and specific vendor browsers
(e.g. Internet Explorer on Windows; Microsoft Edge works well though)
where parts of the pages are not rendered as expected (e.g. the layout is
broken or mathematical expressions not typeset). In that case we
recommend to install/use a different/newer web browser or use
the `PDF version of the manual <https://lammps.sandia.gov/doc/Manual.pdf>`_.

2
doc/src/Manual_version.rst
View File

@ -1,5 +1,5 @@
What does a LAMMPS version mean
===============================
-------------------------------
The LAMMPS "version" is the date when it was released, such as 1 May
2014. LAMMPS is updated continuously. Whenever we fix a bug or add a

42
doc/src/Modify_bond.rst
View File

@ -13,24 +13,24 @@ Here is a brief description of common methods you define in your
new derived class. See bond.h, angle.h, dihedral.h, and improper.h
for details and specific additional methods.
+-----------------------+---------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init_style* (optional) |
+-----------------------+---------------------------------------------------------------------------+
| init_style | check if style specific conditions are met (optional) |
+-----------------------+---------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+-----------------------+---------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+-----------------------+---------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+-----------------------+---------------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (required, bond only) |
+-----------------------+---------------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (required, angle only) |
+-----------------------+---------------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files (required) |
+-----------------------+---------------------------------------------------------------------------+
| single | force and energy of a single bond or angle (required, bond or angle only) |
+-----------------------+---------------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style (optional) |
+-----------------------+---------------------------------------------------------------------------+
+-----------------------+---------------------------------------------------------------------------------------+
| init | check if all coefficients are set, calls *init_style* (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| init_style | check if style specific conditions are met (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| compute | compute the molecular interactions (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| settings | apply global settings for all types (optional) |
+-----------------------+---------------------------------------------------------------------------------------+
| coeff | set coefficients for one type (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_distance | length of bond, used by SHAKE (required, bond only) |
+-----------------------+---------------------------------------------------------------------------------------+
| equilibrium_angle | opening of angle, used by SHAKE (required, angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| write & read_restart | writes/reads coeffs to restart files (required) |
+-----------------------+---------------------------------------------------------------------------------------+
| single | force (bond only) and energy of a single bond or angle (required, bond or angle only) |
+-----------------------+---------------------------------------------------------------------------------------+
| memory_usage | tally memory allocated by the style (optional) |
+-----------------------+---------------------------------------------------------------------------------------+

4
doc/src/Modify_compute.rst
View File

@ -53,5 +53,5 @@ in two stages: the callback function is registered with the pair style
and then called from the Pair::ev_tally() function, which is called for
each pair after force and energy has been computed for this pair. Then
the tallied values are retrieved with the standard compute_scalar or
compute_vector or compute_peratom methods. The USER-TALLY package
provides *examples*\ _compute_tally.html for utilizing this mechanism.
compute_vector or compute_peratom methods. The :doc:`compute styles in the USER-TALLY package <compute_tally>`
provide *examples* for utilizing this mechanism.

80
doc/src/Packages_details.rst
View File

@ -10,10 +10,10 @@ scripts, and pictures/movies (if available) that illustrate use of the
package.
The majority of packages can be included in a LAMMPS build with a
single setting (-D PGK_NAME for CMake) or command ("make yes-name" for
make). See the :doc:`Build package <Build_package>` doc page for more
info. A few packages may require additional steps; this is indicated
in the descriptions below. The :doc:`Build extras <Build_extras>` doc
single setting (``-D PGK_<NAME>=on`` for CMake) or command
(``make yes-<name>`` for make). See the :doc:`Build package <Build_package>`
page for more info. A few packages may require additional steps;
this is indicated in the descriptions below. The :doc:`Build extras <Build_extras>`
page gives those details.
.. note::
@ -143,7 +143,7 @@ BODY package
Body-style particles with internal structure. Computes,
time-integration fixes, pair styles, as well as the body styles
themselves. See the :doc:`Howto body <Howto_body>` doc page for an
themselves. See the :doc:`Howto body <Howto_body>` page for an
overview.
**Supporting info:**
@ -225,7 +225,7 @@ available on your system.
**Install:**
This package has :ref:`specific installation instructions <compress>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <compress>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -249,7 +249,7 @@ 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>` doc page for an overview of how to use
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).
@ -312,7 +312,7 @@ Kuznetsov, Vladimir Stegailov, and Vsevolod Nikolskiy (HSE University).
**Install:**
This package has :ref:`specific installation instructions <gpu>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <gpu>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -410,7 +410,7 @@ Ryan Elliott.
**Install:**
This package has :ref:`specific installation instructions <kim>` on the
:doc:`Build extras <Build_extras>` doc page.
:doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -434,7 +434,7 @@ Dozens of atom, pair, bond, angle, dihedral, improper, fix, compute
styles adapted to compile using the Kokkos library which can convert
them to OpenMP or CUDA code so that they run efficiently on multicore
CPUs, KNLs, or GPUs. All the styles have a "kk" as a suffix in their
style name. The :doc:`KOKKOS package <Speed_kokkos>` doc page gives
style name. The :doc:`KOKKOS package <Speed_kokkos>` page gives
details of what hardware and software is required on your system, and
how to build and use this package. Its styles can be invoked at run
time via the "-sf kk" or "-suffix kk" :doc:`command-line switches <Run_options>`. Also see the :ref:`GPU <PKG-GPU>`, :ref:`OPT <PKG-OPT>`,
@ -457,7 +457,7 @@ lib/kokkos.
**Install:**
This package has :ref:`specific installation instructions <kokkos>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <kokkos>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -494,7 +494,7 @@ interactions. These include Ewald, particle-particle particle-mesh
Building with this package requires a 1d FFT library be present on
your system for use by the PPPM solvers. This can be the KISS FFT
library provided with LAMMPS, third party libraries like FFTW, or a
vendor-supplied FFT library. See the :doc:`Build settings <Build_settings>` doc page for details on how to select
vendor-supplied FFT library. See the :doc:`Build settings <Build_settings>` page for details on how to select
different FFT options for your LAMPMS build.
**Supporting info:**
@ -535,7 +535,7 @@ Cawkwell, Anders Niklasson, and Christian Negre.
**Install:**
This package has :ref:`specific installation instructions <latte>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <latte>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -609,7 +609,7 @@ another application.
**Install:**
This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <message>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -753,7 +753,7 @@ University of Chicago.
**Install:**
This package has :ref:`specific installation instructions <mscg>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <mscg>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -774,7 +774,7 @@ OPT package
A handful of pair styles which are optimized for improved CPU
performance on single or multiple cores. These include EAM, LJ,
CHARMM, and Morse potentials. The styles have an "opt" suffix in
their style name. The :doc:`OPT package <Speed_opt>` doc page gives
their style name. The :doc:`OPT package <Speed_opt>` page gives
details of how to build and use this package. Its styles can be
invoked at run time via the "-sf opt" or "-suffix opt" :doc:`command-line switches <Run_options>`. See also the :ref:`KOKKOS <PKG-KOKKOS>`,
:ref:`USER-INTEL <PKG-USER-INTEL>`, and :ref:`USER-OMP <PKG-USER-OMP>` packages, which
@ -785,7 +785,7 @@ and Vincent Natoli (Stone Ridge Technology).
**Install:**
This package has :ref:`specific installation instructions <opt>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <opt>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -846,7 +846,7 @@ connections at hinge points.
**Install:**
This package has :ref:`specific installation instructions <poems>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <poems>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -867,8 +867,8 @@ PYTHON package
A :doc:`python <python>` command which allow you to execute Python code
from a LAMMPS input script. The code can be in a separate file or
embedded in the input script itself. See the :doc:`Python call <Python_call>` doc page for an overview of using Python from
LAMMPS in this manner and all the :doc:`Python <Python_head>` doc pages
embedded in the input script itself. See the :doc:`Python call <Python_call>` page for an overview of using Python from
LAMMPS in this manner and all the :doc:`Python <Python_head>` manual pages
for other ways to use LAMMPS and Python together.
.. note::
@ -880,7 +880,7 @@ for other ways to use LAMMPS and Python together.
**Install:**
This package has :ref:`specific installation instructions <python>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <python>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -919,7 +919,7 @@ REPLICA package
**Contents:**
A collection of multi-replica methods which can be used when running
multiple LAMMPS simulations (replicas). See the :doc:`Howto replica <Howto_replica>` doc page for an overview of how to run
multiple LAMMPS simulations (replicas). See the :doc:`Howto replica <Howto_replica>` page for an overview of how to run
multi-replica simulations in LAMMPS. Methods in the package include
nudged elastic band (NEB), parallel replica dynamics (PRD),
temperature accelerated dynamics (TAD), parallel tempering, and a
@ -1093,7 +1093,7 @@ and LBNL.
**Install:**
This package has :ref:`specific installation instructions <voronoi>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <voronoi>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1121,7 +1121,7 @@ commands to write and read data using the ADIOS library.
**Install:**
This package has :ref:`specific installation instructions <user-adios>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-adios>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1150,7 +1150,7 @@ atomic information to continuum fields.
**Install:**
This package has :ref:`specific installation instructions <user-atc>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-atc>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1178,7 +1178,7 @@ model.
**Install:**
This package has :ref:`specific installation instructions <user-awpmd>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-awpmd>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1297,7 +1297,7 @@ the NAMD MD code, but with portability in mind. Axel Kohlmeyer
**Install:**
This package has :ref:`specific installation instructions <user-colvars>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-colvars>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1330,7 +1330,7 @@ Tribello.
**Install:**
This package has :ref:`specific installation instructions <user-plumed>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-plumed>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1412,7 +1412,7 @@ USER-DRUDE package
**Contents:**
Fixes, pair styles, and a compute to simulate thermalized Drude
oscillators as a model of polarization. See the :doc:`Howto drude <Howto_drude>` and :doc:`Howto drude2 <Howto_drude2>` doc pages
oscillators as a model of polarization. See the :doc:`Howto drude <Howto_drude>` and :doc:`Howto drude2 <Howto_drude2>` pages
for an overview of how to use the package. There are auxiliary tools
for using this package in tools/drude.
@ -1522,7 +1522,7 @@ H5MD format.
**Install:**
This package has :ref:`specific installation instructions <user-h5md>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-h5md>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1563,7 +1563,7 @@ supported, performance will be sub-optimal.
**Install:**
This package has :ref:`specific installation instructions <user-intel>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-intel>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1650,7 +1650,7 @@ src/USER-MISC/README file.
* src/USER-MISC: filenames -> commands
* src/USER-MISC/README
* one doc page per individual command listed in src/USER-MISC/README
* one page per individual command listed in src/USER-MISC/README
* examples/USER/misc
----------
@ -1856,7 +1856,7 @@ at
**Install:**
This package has :ref:`specific installation instructions <user-molfile>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-molfile>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1896,7 +1896,7 @@ tools:
**Install:**
This package has :ref:`specific installation instructions <user-netcdf>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-netcdf>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -1943,7 +1943,7 @@ install/un-install the package and build LAMMPS in the usual manner:
**Install:**
This package has :ref:`specific installation instructions <user-omp>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-omp>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -2043,7 +2043,7 @@ changes to LAMMPS itself.
**Install:**
This package has :ref:`specific installation instructions <user-qmmm>`
on the :doc:`Build extras <Build_extras>` doc page.
on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -2104,7 +2104,7 @@ on your system.
**Install:**
This package has :ref:`specific installation instructions <user-quip>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-quip>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -2194,7 +2194,7 @@ the Forschungszentrum Juelich.
**Install:**
This package has :ref:`specific installation instructions <user-scafacos>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-scafacos>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -2260,7 +2260,7 @@ Dynamics, Ernst Mach Institute, Germany).
**Install:**
This package has :ref:`specific installation instructions <user-smd>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-smd>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**
@ -2399,7 +2399,7 @@ system.
**Install:**
This package has :ref:`specific installation instructions <user-vtk>` on the :doc:`Build extras <Build_extras>` doc page.
This package has :ref:`specific installation instructions <user-vtk>` on the :doc:`Build extras <Build_extras>` page.
**Supporting info:**

81
doc/src/Python_atoms.rst Normal file
View File

@ -0,0 +1,81 @@
Per-atom properties
===================
Similar to what is described in :doc:`Library_atoms`, the instances of
:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`, or
:py:class:`IPyLammps <lammps.IPyLammps>` can be used to extract atom quantities
and modify some of them. The main difference between the interfaces is how the information
is exposed.
While the :py:class:`lammps <lammps.lammps>` is just a thin layer that wraps C API calls,
:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps <lammps.IPyLammps>` expose
information as objects and properties.
In some cases the data returned is a direct reference to the original data
inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will
determine the ``ctypes`` data type and cast pointers accordingly. If
``numpy`` is installed arrays can also be extracted as numpy arrays, which
will access the C arrays directly and have the correct dimensions to protect
against invalid accesses.
.. warning::
When accessing per-atom data,
please note that this data is the per-processor local data and indexed
accordingly. These arrays can change sizes and order at every neighbor list
rebuild and atom sort event as atoms are migrating between sub-domains.
.. tabs::
.. tab:: lammps API
.. code-block:: python
from lammps import lammps
lmp = lammps()
lmp.file("in.sysinit")
nlocal = lmp.extract_global("nlocal")
x = lmp.extract_atom("x")
for i in range(nlocal):
print("(x,y,z) = (", x[i][0], x[i][1], x[i][2], ")")
lmp.close()
**Methods**:
* :py:meth:`extract_atom() <lammps.lammps.extract_atom()>`: extract a per-atom quantity
**Numpy Methods**:
* :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
.. tab:: PyLammps/IPyLammps API
All atoms in the current simulation can be accessed by using the :py:attr:`PyLammps.atoms <lammps.PyLammps.atoms>` property.
Each element of this list is a :py:class:`Atom <lammps.Atom>` or :py:class:`Atom2D <lammps.Atom2D>` object. The attributes of
these objects provide access to their data (id, type, position, velocity, force, etc.):
.. code-block:: Python
# access first atom
L.atoms[0].id
L.atoms[0].type
# access second atom
L.atoms[1].position
L.atoms[1].velocity
L.atoms[1].force
Some attributes can be changed:
.. code-block:: Python
# set position in 2D simulation
L.atoms[0].position = (1.0, 0.0)
# set position in 3D simulation
L.atoms[0].position = (1.0, 0.0, 1.0)

4
doc/src/Python_call.rst
View File

@ -1,5 +1,5 @@
Calling Python from a LAMMPS input script
*****************************************
Calling Python from LAMMPS
**************************
LAMMPS has several commands which can be used to invoke Python
code directly from an input script:

4
doc/src/Python_config.rst
View File

@ -1,5 +1,5 @@
Retrieving LAMMPS configuration information
*******************************************
Configuration information
=========================
The following methods can be used to query the LAMMPS library
about compile time settings and included packages and styles.

148
doc/src/Python_create.rst Normal file
View File

@ -0,0 +1,148 @@
.. _mpi4py_url: https://mpi4py.readthedocs.io/
.. _python_create_lammps:
Creating or deleting a LAMMPS object
====================================
With the Python interface the creation of a :cpp:class:`LAMMPS
<LAMMPS_NS::LAMMPS>` instance is included in the constructors for the
:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`,
and :py:class:`IPyLammps <lammps.IPyLammps>` classes.
Internally it will call either :cpp:func:`lammps_open` or :cpp:func:`lammps_open_no_mpi` from the C
library API to create the class instance.
All arguments are optional. The *name* argument allows loading a
LAMMPS shared library that is named ``liblammps_machine.so`` instead of
the default name of ``liblammps.so``. In most cases the latter will be
installed or used. The *ptr* argument is for use of the
:py:mod:`lammps` module from inside a LAMMPS instance, e.g. with the
:doc:`python <python>` command, where a pointer to the already existing
:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance can be passed
to the Python class and used instead of creating a new instance. The
*comm* argument may be used in combination with the `mpi4py <mpi4py_url_>`_
module to pass an MPI communicator to LAMMPS and thus it is possible
to run the Python module like the library interface on a subset of the
MPI ranks after splitting the communicator.
Here are simple examples using all three Python interfaces:
.. tabs::
.. tab:: lammps API
.. code-block:: python
from lammps import lammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", lmp.version())
# explicitly close and delete LAMMPS instance (optional)
lmp.close()
.. tab:: PyLammps API
The :py:class:`PyLammps <lammps.PyLammps>` class is a wrapper around the
:py:class:`lammps <lammps.lammps>` class and all of its lower level functions.
By default, it will create a new instance of :py:class:`lammps <lammps.lammps>` passing
along all arguments to the constructor of :py:class:`lammps <lammps.lammps>`.
.. code-block:: python
from lammps import PyLammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
L = PyLammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", L.version())
# explicitly close and delete LAMMPS instance (optional)
L.close()
:py:class:`PyLammps <lammps.PyLammps>` objects can also be created on top of an existing
:py:class:`lammps <lammps.lammps>` object:
.. code-block:: Python
from lammps import lammps, PyLammps
...
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# create PyLammps instance using previously created LAMMPS instance
L = PyLammps(ptr=lmp)
This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
instance is a specific way, but want to take advantage of the
:py:class:`PyLammps <lammps.PyLammps>` interface.
.. tab:: IPyLammps API
The :py:class:`IPyLammps <lammps.IPyLammps>` class is an extension of the
:py:class:`PyLammps <lammps.PyLammps>` class. It has the same construction behavior. By
default, it will create a new instance of :py:class:`lammps` passing
along all arguments to the constructor of :py:class:`lammps`.
.. code-block:: python
from lammps import IPyLammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
L = IPyLammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", L.version())
# explicitly close and delete LAMMPS instance (optional)
L.close()
You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object:
.. code-block:: Python
from lammps import lammps, IPyLammps
...
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# create PyLammps instance using previously created LAMMPS instance
L = PyLammps(ptr=lmp)
This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
instance is a specific way, but want to take advantage of the
:py:class:`IPyLammps <lammps.IPyLammps>` interface.
In all of the above cases, same as with the :ref:`C library API <lammps_c_api>`, this will use the
``MPI_COMM_WORLD`` communicator for the MPI library that LAMMPS was
compiled with.
The :py:func:`lmp.close() <lammps.lammps.close()>` call is
optional since the LAMMPS class instance will also be deleted
automatically during the :py:class:`lammps <lammps.lammps>` class
destructor.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
.. code-block:: Python
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")

2
doc/src/Python_error.rst
View File

@ -1,4 +1,4 @@
LAMMPS error handling in Python
Handling LAMMPS errors
*******************************
Compiling the shared library with :ref:`C++ exception support <exceptions>` provides a better error

77
doc/src/Python_examples.rst
View File

@ -1,54 +1,50 @@
Example Python scripts that use LAMMPS
======================================
Example Python scripts
======================
The python/examples directory has Python scripts which show how Python
The ``python/examples`` directory has Python scripts which show how Python
can run LAMMPS, grab data, change it, and put it back into LAMMPS.
These are the Python scripts included as demos in the python/examples
These are the Python scripts included as demos in the ``python/examples``
directory of the LAMMPS distribution, to illustrate the kinds of
things that are possible when Python wraps LAMMPS. If you create your
own scripts, send them to us and we can include them in the LAMMPS
distribution.
+----------------------------------------------------------------+--------------------------------------------------+
| trivial.py | read/run a LAMMPS input script through Python |
+----------------------------------------------------------------+--------------------------------------------------+
| demo.py | invoke various LAMMPS library interface routines |
+----------------------------------------------------------------+--------------------------------------------------+
| simple.py | run in parallel |
+----------------------------------------------------------------+--------------------------------------------------+
| similar to examples/COUPLE/simple/simple.cpp | split.py |
+----------------------------------------------------------------+--------------------------------------------------+
| same as simple.py but running in parallel on a subset of procs | gui.py |
+----------------------------------------------------------------+--------------------------------------------------+
| GUI go/stop/temperature-slider to control LAMMPS | plot.py |
+----------------------------------------------------------------+--------------------------------------------------+
| real-time temperature plot with GnuPlot via Pizza.py | viz_tool.py |
+----------------------------------------------------------------+--------------------------------------------------+
| real-time viz via some viz package | vizplotgui_tool.py |
+----------------------------------------------------------------+--------------------------------------------------+
| combination of viz_tool.py and plot.py and gui.py | |
+----------------------------------------------------------------+--------------------------------------------------+
+------------------------+--------------------------------------------------------------------+
| ``trivial.py`` | read/run a LAMMPS input script through Python |
+------------------------+--------------------------------------------------------------------+
| ``demo.py`` | invoke various LAMMPS library interface routines |
+------------------------+--------------------------------------------------------------------+
| ``simple.py`` | run in parallel, similar to ``examples/COUPLE/simple/simple.cpp`` |
+------------------------+--------------------------------------------------------------------+
| ``split.py`` | same as ``simple.py`` but running in parallel on a subset of procs |
+------------------------+--------------------------------------------------------------------+
| ``gui.py`` | GUI go/stop/temperature-slider to control LAMMPS |
+------------------------+--------------------------------------------------------------------+
| ``plot.py`` | real-time temperature plot with GnuPlot via Pizza.py |
+------------------------+--------------------------------------------------------------------+
| ``viz_TOOL.py`` | real-time viz via some viz package |
+------------------------+--------------------------------------------------------------------+
| ``vizplotgui_TOOL.py`` | combination of ``viz_TOOL.py`` and ``plot.py`` and ``gui.py`` |
+------------------------+--------------------------------------------------------------------+
----------
For the viz_tool.py and vizplotgui_tool.py commands, replace "tool"
with "gl" or "atomeye" or "pymol" or "vmd", depending on what
For the ``viz_TOOL.py`` and ``vizplotgui_TOOL.py`` commands, replace ``TOOL``
with ``gl`` or ``atomeye`` or ``pymol`` or ``vmd``, depending on what
visualization package you have installed.
Note that for GL, you need to be able to run the Pizza.py GL tool,
which is included in the pizza sub-directory. See the `Pizza.py doc pages <pizza_>`_ for more info:
which is included in the pizza sub-directory. See the Pizza.py doc pages for more info:
* `https://pizza.sandia.gov <pizza_>`_
.. _pizza: https://pizza.sandia.gov
Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye WWW pages `here <atomeye_>`_ or `here <atomeye3_>`_ for more details:
AtomEye web pages for more details:
.. parsed-literal::
http://li.mit.edu/Archive/Graphics/A/
http://li.mit.edu/Archive/Graphics/A3/A3.html
* `http://li.mit.edu/Archive/Graphics/A/ <atomeye_>`_
* `http://li.mit.edu/Archive/Graphics/A3/A3.html <atomeye3_>`_
.. _atomeye: http://li.mit.edu/Archive/Graphics/A/
@ -59,13 +55,10 @@ capability needed by these Python scripts.
Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script. See the PyMol WWW pages `here <pymolhome_>`_ or
`here <pymolopen_>`_ for more details:
from a Python script. See the PyMol web pages for more details:
.. parsed-literal::
https://www.pymol.org
https://github.com/schrodinger/pymol-open-source
* `https://www.pymol.org <pymolhome_>`_
* `https://github.com/schrodinger/pymol-open-source <pymolopen_>`_
.. _pymolhome: https://www.pymol.org
@ -74,15 +67,15 @@ from a Python script. See the PyMol WWW pages `here <pymolhome_>`_ or
The latter link is to the open-source version.
Note that for VMD, you need a fairly current version (1.8.7 works for
me) and there are some lines in the pizza/vmd.py script for 4 PIZZA
me) and there are some lines in the ``pizza/vmd.py`` script for 4 PIZZA
variables that have to match the VMD installation on your system.
----------
See the python/README file for instructions on how to run them and the
See the ``python/README`` file for instructions on how to run them and the
source code for individual scripts for comments about what they do.
Here are screenshots of the vizplotgui_tool.py script in action for
Here are screenshots of the ``vizplotgui_tool.py`` script in action for
different visualization package options:
.. |pyex1| image:: img/screenshot_gl.jpg

127
doc/src/Python_execute.rst Normal file
View File

@ -0,0 +1,127 @@
Executing commands
==================
Once an instance of the :py:class:`lammps <lammps.lammps>`,
:py:class:`PyLammps <lammps.PyLammps>`, or
:py:class:`IPyLammps <lammps.IPyLammps>` class is created, there are
multiple ways to "feed" it commands. In a way that is not very different from
running a LAMMPS input script, except that Python has many more facilities
for structured programming than the LAMMPS input script syntax. Furthermore
it is possible to "compute" what the next LAMMPS command should be.
.. tabs::
.. tab:: lammps API
Same as in the equivalent
:doc:`C library functions <Library_execute>`, commands can be read from a file, a
single string, a list of strings and a block of commands in a single
multi-line string. They are processed under the same boundary conditions
as the C library counterparts. The example below demonstrates the use
of :py:func:`lammps.file()`, :py:func:`lammps.command()`,
:py:func:`lammps.commands_list()`, and :py:func:`lammps.commands_string()`:
.. code-block:: python
from lammps import lammps
lmp = lammps()
# read commands from file 'in.melt'
lmp.file('in.melt')
# issue a single command
lmp.command('variable zpos index 1.0')
# create 10 groups with 10 atoms each
cmds = ["group g{} id {}:{}".format(i,10*i+1,10*(i+1)) for i in range(10)]
lmp.commands_list(cmds)
# run commands from a multi-line string
block = """
clear
region box block 0 2 0 2 0 2
create_box 1 box
create_atoms 1 single 1.0 1.0 ${zpos}
"""
lmp.commands_string(block)
.. tab:: PyLammps/IPyLammps API
Unlike the lammps API, the PyLammps/IPyLammps APIs allow running LAMMPS
commands by calling equivalent member functions of :py:class:`PyLammps <lammps.PyLammps>`
and :py:class:`IPyLammps <lammps.IPyLammps>` instances.
For instance, the following LAMMPS command
.. code-block:: LAMMPS
region box block 0 10 0 5 -0.5 0.5
can be executed using with the lammps API with the following Python code if ``lmp`` is an
instance of :py:class:`lammps <lammps.lammps>`:
.. code-block:: Python
from lammps import lammps
lmp = lammps()
lmp.command("region box block 0 10 0 5 -0.5 0.5")
With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts.
These parts are then passed to a member function with the name of the :doc:`command <Commands_all>`.
For the :doc:`region <region>` command that means the :code:`region()` method can be called.
The arguments of the command can be passed as one string, or
individually.
.. code-block:: Python
from lammps import PyLammps
L = PyLammps()
# pass command parameters as one string
L.region("box block 0 10 0 5 -0.5 0.5")
# OR pass them individually
L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
In the latter example, all parameters except the first are Python floating-point literals. The
member function takes the entire parameter list and transparently merges it to a single command
string.
The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the lammps API parameterization needed to be done
manually by creating formatted command strings.
.. code-block:: Python
lmp.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
.. code-block:: Python
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
Using these facilities, the example shown for the lammps API can be rewritten as follows:
.. code-block:: python
from lammps import PyLammps
L = PyLammps()
# read commands from file 'in.melt'
L.file('in.melt')
# issue a single command
L.variable('zpos', 'index', 1.0)
# create 10 groups with 10 atoms each
for i in range(10):
L.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}")
L.clear()
L.region("box block", 0, 2, 0, 2, 0, 2)
L.create_box(1, "box")
L.create_atoms(1, "single", 1.0, 1.0, "${zpos}")

14
doc/src/Python_ext.rst
View File

@ -1,16 +1,20 @@
Extending the library and Python interface
Extending the Python interface
******************************************
As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in ``src/library.cpp`` and
``library.h``. This means you can extend the Python wrapper via the
following steps:
As noted previously, most of the :py:class:`lammps <lammps.lammps>`
Python class methods correspond one-to-one with the functions in the
LAMMPS library interface in ``src/library.cpp`` and ``library.h``.
This means you can extend the Python wrapper by following these steps:
* Add a new interface function to ``src/library.cpp`` and
``src/library.h``.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to ``python/lammps.py`` for this interface
function.
* Define the corresponding ``argtypes`` list and ``restype``
in the ``lammps.__init__()`` function.
* Re-install the shared library and the python module, if needed
* You should now be able to invoke the new interface function from a
Python script.

7
doc/src/Python_head.rst
View File

@ -10,14 +10,11 @@ together.
Python_overview
Python_install
Python_run
Python_usage
Python_call
Python_config
Python_neighbor
Python_module
Python_ext
Python_call
Python_examples
Python_error
Python_ext
Python_trouble
If you are not familiar with `Python <http://www.python.org>`_, it is a

108
doc/src/Python_launch.rst Normal file
View File

@ -0,0 +1,108 @@
Running LAMMPS and Python in serial
-----------------------------------
To run a LAMMPS in serial, type these lines into Python
interactively from the ``bench`` directory:
.. code-block:: python
>>> 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
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
typed something like:
.. code-block:: bash
lmp_serial -in in.lj
Running LAMMPS and Python in parallel with MPI
----------------------------------------------
To run LAMMPS in parallel, assuming you have installed the
`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
.. code-block:: python
from mpi4py import MPI
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
me = MPI.COMM_WORLD.Get_rank()
nprocs = MPI.COMM_WORLD.Get_size()
print("Proc %d out of %d procs has" % (me,nprocs),lmp)
MPI.Finalize()
You can run the script in parallel as:
.. code-block:: bash
$ 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
Note that without the mpi4py specific lines from ``test.py``
.. code-block:: Python
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
running the script with ``mpirun`` on :math:`P` processors would lead to
:math:`P` independent simulations to run parallel, each with a single
processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
single processor outputs, mpi4py is not working correctly.
Also note that once you import the mpi4py module, mpi4py initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the mpi4py documentation. The last line of your Python
script should be ``MPI.finalize()``, to insure MPI is shut down
correctly.
Running Python scripts
----------------------
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
.. code-block:: bash
$ python script.py
$ python -i script.py
$ ./script.py
The last command requires that the first line of the script be
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:
.. 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.

4
doc/src/Python_neighbor.rst
View File

@ -1,5 +1,5 @@
Accessing LAMMPS Neighbor lists
*******************************
Neighbor list access
====================
**Methods:**

98
doc/src/Python_objects.rst Normal file
View File

@ -0,0 +1,98 @@
Compute, fixes, variables
*************************
This section documents accessing or modifying data from objects like
computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
.. tabs::
.. tab:: lammps API
For :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>` and
:py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`, the global, per-atom,
or local data calculated by the compute or fix can be accessed. What is returned
depends on whether the compute or fix calculates a scalar or vector or array.
For a scalar, a single double value is returned. If the compute or fix calculates
a vector or array, a pointer to the internal LAMMPS data is returned, which you can
use via normal Python subscripting.
The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices.
See the :doc:`Howto output <Howto_output>` doc page for a discussion of
global, per-atom, and local data, and of scalar, vector, and array
data types. See the doc pages for individual :doc:`computes <compute>`
and :doc:`fixes <fix>` for a description of what they calculate and
store.
For :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`,
an :doc:`equal-style or atom-style variable <variable>` is evaluated and
its result returned.
For equal-style variables a single ``c_double`` value is returned and the
group argument is ignored. For atom-style variables, a vector of
``c_double`` is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
:py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
:py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
:py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
existing string-style variable to a new string value, so that subsequent LAMMPS
commands can access the variable.
**Methods**:
* :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>`: extract value(s) from a compute
* :py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`: extract value(s) from a fix
* :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`: extract value(s) from a variable
* :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>`: set existing named string-style variable to value
**NumPy Methods**:
* :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
.. tab:: PyLammps/IPyLammps API
PyLammps and IPyLammps classes currently do not add any additional ways of
retrieving information out of computes and fixes. This information can still be accessed by using the lammps API:
.. code-block:: python
L.lmp.extract_compute(...)
L.lmp.extract_fix(...)
# OR
L.lmp.numpy.extract_compute(...)
L.lmp.numpy.extract_fix(...)
LAMMPS variables can be both defined and accessed via the :py:class:`PyLammps <lammps.PyLammps>` interface.
To define a variable you can use the :doc:`variable <variable>` command:
.. code-block:: Python
L.variable("a index 2")
A dictionary of all variables is returned by the :py:attr:`PyLammps.variables <lammps.PyLammps.variables>` property:
you can access an individual variable by retrieving a variable object from the
``L.variables`` dictionary by name
.. code-block:: Python
a = L.variables['a']
The variable value can then be easily read and written by accessing the value
property of this object.
.. code-block:: Python
print(a.value)
a.value = 4

14
doc/src/Python_overview.rst
View File

@ -41,14 +41,14 @@ Below is an example output for Python version 3.8.5.
>>>
.. warning:: Python 2 support is deprecated
.. warning::
While the LAMMPS Python module was originally developed to support
both, Python 2 and 3, any new code is only tested with Python 3.
Please note that Python 2 is no longer maintained as of `January 1,
2020 <https://www.python.org/doc/sunset-python-2/>`_. Therefore, we
highly recommend using Python version 3.6 or later. Compatibility to
Python 2 will be removed eventually.
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.
---------

132
doc/src/Python_properties.rst Normal file
View File

@ -0,0 +1,132 @@
System properties
=================
Similar to what is described in :doc:`Library_properties`, the instances of
:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`, or
:py:class:`IPyLammps <lammps.IPyLammps>` can be used to extract different kinds
of information about the active LAMMPS instance and also to modify some of it. The
main difference between the interfaces is how the information is exposed.
While the :py:class:`lammps <lammps.lammps>` is just a thin layer that wraps C API calls,
:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps <lammps.IPyLammps>` expose
information as objects and properties.
In some cases the data returned is a direct reference to the original data
inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will
determine the ``ctypes`` data type and cast pointers accordingly. If
``numpy`` is installed arrays can also be extracted as numpy arrays, which
will access the C arrays directly and have the correct dimensions to protect
against invalid accesses.
.. warning::
When accessing per-atom data,
please note that this data is the per-processor local data and indexed
accordingly. These arrays can change sizes and order at every neighbor list
rebuild and atom sort event as atoms are migrating between sub-domains.
.. tabs::
.. tab:: lammps API
.. code-block:: python
from lammps import lammps
lmp = lammps()
lmp.file("in.sysinit")
natoms = lmp.get_natoms()
print(f"running simulation with {natoms} atoms")
lmp.command("run 1000 post no");
for i in range(10):
lmp.command("run 100 pre no post no")
pe = lmp.get_thermo("pe")
ke = lmp.get_thermo("ke")
print(f"PE = {pe}\nKE = {ke}")
lmp.close()
**Methods**:
* :py:meth:`version() <lammps.lammps.version()>`: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
* :py:meth:`get_thermo() <lammps.lammps.get_thermo()>`: return current value of a thermo keyword
* :py:meth:`get_natoms() <lammps.lammps.get_natoms()>`: total # of atoms as int
* :py:meth:`reset_box() <lammps.lammps.reset_box()>`: reset the simulation box size
* :py:meth:`extract_setting() <lammps.lammps.extract_setting()>`: return a global setting
* :py:meth:`extract_global() <lammps.lammps.extract_global()>`: extract a global quantity
* :py:meth:`extract_box() <lammps.lammps.extract_box()>`: extract box info
* :py:meth:`create_atoms() <lammps.lammps.create_atoms()>`: create N atoms with IDs, types, x, v, and image flags
.. tab:: PyLammps/IPyLammps API
In addition to the functions provided by :py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>` objects
have several properties which allow you to query the system state:
L.system
Is a dictionary describing the system such as the bounding box or number of atoms
L.system.xlo, L.system.xhi
bounding box limits along x-axis
L.system.ylo, L.system.yhi
bounding box limits along y-axis
L.system.zlo, L.system.zhi
bounding box limits along z-axis
L.communication
configuration of communication subsystem, such as the number of threads or processors
L.communication.nthreads
number of threads used by each LAMMPS process
L.communication.nprocs
number of MPI processes used by LAMMPS
L.fixes
List of fixes in the current system
L.computes
List of active computes in the current system
L.dump
List of active dumps in the current system
L.groups
List of groups present in the current system
**Retrieving the value of an arbitrary LAMMPS expressions**
LAMMPS expressions can be immediately evaluated by using the ``eval`` method. The
passed string parameter can be any expression containing global :doc:`thermo` values,
variables, compute or fix data (see :doc:`Howto_output`):
.. code-block:: Python
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy
result = L.eval("v_t/2.0")
**Example**
.. code-block:: python
from lammps import PyLammps
L = PyLammps()
L.file("in.sysinit")
print(f"running simulation with {L.system.natoms} atoms")
L.run(1000, "post no");
for i in range(10):
L.run(100, "pre no post no")
pe = L.eval("pe")
ke = L.eval("ke")
print(f"PE = {pe}\nKE = {ke}")

121
doc/src/Python_run.rst
View File

@ -1,110 +1,29 @@
Run LAMMPS from Python
======================
Running LAMMPS and Python in serial:
-------------------------------------
After compiling the LAMMPS shared library and making it ready to use,
you can now write and run Python scripts that import the LAMMPS Python
module and launch LAMMPS simulations through Python scripts.
The following pages take you through the various steps necessary,
what functionality is available and give some examples how to use it.
To run a LAMMPS in serial, type these lines into Python
interactively from the ``bench`` directory:
------
.. code-block:: python
.. toctree::
:maxdepth: 1
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
Python_launch
Or put the same lines in the file ``test.py`` and run it as
------
.. code-block:: bash
.. toctree::
:maxdepth: 1
$ 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
typed something like:
.. code-block:: bash
lmp_serial -in in.lj
Running LAMMPS and Python in parallel with MPI
----------------------------------------------
To run LAMMPS in parallel, assuming you have installed the
`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
.. code-block:: python
from mpi4py import MPI
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
me = MPI.COMM_WORLD.Get_rank()
nprocs = MPI.COMM_WORLD.Get_size()
print("Proc %d out of %d procs has" % (me,nprocs),lmp)
MPI.Finalize()
You can run the script in parallel as:
.. code-block:: bash
$ 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
Note that without the mpi4py specific lines from ``test.py``
.. code-block::
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
running the script with ``mpirun`` on :math:`P` processors would lead to
:math:`P` independent simulations to run parallel, each with a single
processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
single processor outputs, mpi4py is not working correctly.
Also note that once you import the mpi4py module, mpi4py initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the mpi4py documentation. The last line of your Python
script should be ``MPI.finalize()``, to insure MPI is shut down
correctly.
Running Python scripts
----------------------
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
.. code-block:: bash
$ python script.py
$ python -i script.py
$ ./script.py
The last command requires that the first line of the script be
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:
.. 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.
Python_create
Python_execute
Python_properties
Python_atoms
Python_objects
Python_scatter
Python_neighbor
Python_config

61
doc/src/Python_scatter.rst Normal file
View File

@ -0,0 +1,61 @@
Scatter/gather operations
=========================
.. code-block:: Python
data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered)
data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs
lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs
The gather methods collect peratom info of the requested type (atom
coords, atom types, forces, etc) from all processors, and returns the
same vector of values to each calling processor. The scatter
functions do the inverse. They distribute a vector of peratom values,
passed by all calling processors, to individual atoms, which may be
owned by different processors.
Note that the data returned by the gather methods,
e.g. gather_atoms("x"), is different from the data structure returned
by extract_atom("x") in four ways. (1) Gather_atoms() returns a
vector which you index as x[i]; extract_atom() returns an array
which you index as x[i][j]. (2) Gather_atoms() orders the atoms
by atom ID while extract_atom() does not. (3) Gather_atoms() returns
a list of all atoms in the simulation; extract_atoms() returns just
the atoms local to each processor. (4) Finally, the gather_atoms()
data structure is a copy of the atom coords stored internally in
LAMMPS, whereas extract_atom() returns an array that effectively
points directly to the internal data. This means you can change
values inside LAMMPS from Python by assigning a new values to the
extract_atom() array. To do this with the gather_atoms() vector, you
need to change values in the vector, then invoke the scatter_atoms()
method.
For the scatter methods, the array of coordinates passed to must be a
ctypes vector of ints or doubles, allocated and initialized something
like this:
.. code-block:: Python
from ctypes import c_double
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_atoms("x",1,3,x)
Alternatively, you can just change values in the vector returned by
the gather methods, since they are also ctypes vectors.

569
doc/src/Python_usage.rst
View File

@ -1,569 +0,0 @@
.. _mpi4py_url: https://mpi4py.readthedocs.io/
.. _python_create_lammps:
Creating or deleting a LAMMPS object
************************************
With the Python interface the creation of a :cpp:class:`LAMMPS
<LAMMPS_NS::LAMMPS>` instance is included in the constructors for the
:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`,
and :py:class:`IPyLammps <lammps.IPyLammps>` classes.
Internally it will call either :cpp:func:`lammps_open` or :cpp:func:`lammps_open_no_mpi` from the C
library API to create the class instance.
All arguments are optional. The *name* argument allows loading a
LAMMPS shared library that is named ``liblammps_machine.so`` instead of
the default name of ``liblammps.so``. In most cases the latter will be
installed or used. The *ptr* argument is for use of the
:py:mod:`lammps` module from inside a LAMMPS instance, e.g. with the
:doc:`python <python>` command, where a pointer to the already existing
:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance can be passed
to the Python class and used instead of creating a new instance. The
*comm* argument may be used in combination with the `mpi4py <mpi4py_url_>`_
module to pass an MPI communicator to LAMMPS and thus it is possible
to run the Python module like the library interface on a subset of the
MPI ranks after splitting the communicator.
Here are simple examples using all three Python interfaces:
.. tabs::
.. tab:: lammps API
.. code-block:: python
from lammps import lammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", lmp.version())
# explicitly close and delete LAMMPS instance (optional)
lmp.close()
.. tab:: PyLammps API
The :py:class:`PyLammps <lammps.PyLammps>` class is a wrapper around the
:py:class:`lammps <lammps.lammps>` class and all of its lower level functions.
By default, it will create a new instance of :py:class:`lammps <lammps.lammps>` passing
along all arguments to the constructor of :py:class:`lammps <lammps.lammps>`.
.. code-block:: python
from lammps import PyLammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
L = PyLammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", L.version())
# explicitly close and delete LAMMPS instance (optional)
L.close()
:py:class:`PyLammps <lammps.PyLammps>` objects can also be created on top of an existing
:py:class:`lammps <lammps.lammps>` object:
.. code-block:: Python
from lammps import lammps, PyLammps
...
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# create PyLammps instance using previously created LAMMPS instance
L = PyLammps(ptr=lmp)
This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
instance is a specific way, but want to take advantage of the
:py:class:`PyLammps <lammps.PyLammps>` interface.
.. tab:: IPyLammps API
The :py:class:`IPyLammps <lammps.IPyLammps>` class is an extension of the
:py:class:`PyLammps <lammps.PyLammps>` class. It has the same construction behavior. By
default, it will create a new instance of :py:class:`lammps` passing
along all arguments to the constructor of :py:class:`lammps`.
.. code-block:: python
from lammps import IPyLammps
# NOTE: argv[0] is set by the lammps class constructor
args = ["-log", "none"]
# create LAMMPS instance
L = IPyLammps(cmdargs=args)
# get and print numerical version code
print("LAMMPS Version: ", L.version())
# explicitly close and delete LAMMPS instance (optional)
L.close()
You can also initialize IPyLammps on top of an existing :py:class:`lammps` or :py:class:`PyLammps` object:
.. code-block:: Python
from lammps import lammps, IPyLammps
...
# create LAMMPS instance
lmp = lammps(cmdargs=args)
# create PyLammps instance using previously created LAMMPS instance
L = PyLammps(ptr=lmp)
This is useful if you have to create the :py:class:`lammps <lammps.lammps>`
instance is a specific way, but want to take advantage of the
:py:class:`IPyLammps <lammps.IPyLammps>` interface.
In all of the above cases, same as with the :ref:`C library API <lammps_c_api>`, this will use the
``MPI_COMM_WORLD`` communicator for the MPI library that LAMMPS was
compiled with.
The :py:func:`lmp.close() <lammps.lammps.close()>` call is
optional since the LAMMPS class instance will also be deleted
automatically during the :py:class:`lammps <lammps.lammps>` class
destructor.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
.. code-block:: Python
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")
Executing LAMMPS commands
*************************
Once an instance of the :py:class:`lammps <lammps.lammps>`,
:py:class:`PyLammps <lammps.PyLammps>`, or
:py:class:`IPyLammps <lammps.IPyLammps>` class is created, there are
multiple ways to "feed" it commands. In a way that is not very different from
running a LAMMPS input script, except that Python has many more facilities
for structured programming than the LAMMPS input script syntax. Furthermore
it is possible to "compute" what the next LAMMPS command should be.
.. tabs::
.. tab:: lammps API
Same as in the equivalent
:doc:`C library functions <Library_execute>`, commands can be read from a file, a
single string, a list of strings and a block of commands in a single
multi-line string. They are processed under the same boundary conditions
as the C library counterparts. The example below demonstrates the use
of :py:func:`lammps.file()`, :py:func:`lammps.command()`,
:py:func:`lammps.commands_list()`, and :py:func:`lammps.commands_string()`:
.. code-block:: python
from lammps import lammps
lmp = lammps()
# read commands from file 'in.melt'
lmp.file('in.melt')
# issue a single command
lmp.command('variable zpos index 1.0')
# create 10 groups with 10 atoms each
cmds = ["group g{} id {}:{}".format(i,10*i+1,10*(i+1)) for i in range(10)]
lmp.commands_list(cmds)
# run commands from a multi-line string
block = """
clear
region box block 0 2 0 2 0 2
create_box 1 box
create_atoms 1 single 1.0 1.0 ${zpos}
"""
lmp.commands_string(block)
.. tab:: PyLammps/IPyLammps API
Unlike the lammps API, the PyLammps/IPyLammps APIs allow running LAMMPS
commands by calling equivalent member functions of :py:class:`PyLammps <lammps.PyLammps>`
and :py:class:`IPyLammps <lammps.IPyLammps>` instances.
For instance, the following LAMMPS command
.. code-block:: LAMMPS
region box block 0 10 0 5 -0.5 0.5
can be executed using with the lammps AI with the following Python code if *L* is an
instance of :py:class:`lammps <lammps.lammps>`:
.. code-block:: Python
L.command("region box block 0 10 0 5 -0.5 0.5")
With the PyLammps interface, any LAMMPS command can be split up into arbitrary parts.
These parts are then passed to a member function with the name of the command.
For the ``region`` command that means the :code:`region()` method can be called.
The arguments of the command can be passed as one string, or
individually.
.. code-block:: Python
L.region("box block", 0, 10, 0, 5, -0.5, 0.5)
In this example all parameters except the first are Python floating-point literals. The
PyLammps interface takes the entire parameter list and transparently
merges it to a single command string.
The benefit of this approach is avoiding redundant command calls and easier
parameterization. In the original interface parameterization this needed to be done
manually by creating formatted strings.
.. code-block:: Python
L.command("region box block %f %f %f %f %f %f" % (xlo, xhi, ylo, yhi, zlo, zhi))
In contrast, methods of PyLammps accept parameters directly and will convert
them automatically to a final command string.
.. code-block:: Python
L.region("box block", xlo, xhi, ylo, yhi, zlo, zhi)
Using these facilities, the example shown for the lammps API can be rewritten as follows:
.. code-block:: python
from lammps import PyLammps
L = PyLammps()
# read commands from file 'in.melt'
L.file('in.melt')
# issue a single command
L.variable('zpos', 'index', 1.0)
# create 10 groups with 10 atoms each
for i in range(10):
L.group(f"g{i}", "id", f"{10*i+1}:{10*(i+1)}")
L.clear()
L.region("box block", 0, 2, 0, 2, 0, 2)
L.create_box(1, "box")
L.create_atoms(1, "single", 1.0, 1.0, "${zpos}")
Retrieving or setting LAMMPS system properties
**********************************************
Similar to what is described in :doc:`Library_properties`, the instances of
:py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>`, or
:py:class:`IPyLammps <lammps.IPyLammps>` can be used to extract different kinds
of information about the active LAMMPS instance and also to modify some of it. The
main difference between the interfaces is how the information is exposed.
While the :py:class:`lammps <lammps.lammps>` is just a thin layer that wraps C API calls,
:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps <lammps.IPyLammps>` expose
information as objects and properties.
In some cases the data returned is a direct reference to the original data
inside LAMMPS cast to ``ctypes`` pointers. Where possible, the wrappers will
determine the ``ctypes`` data type and cast pointers accordingly. If
``numpy`` is installed arrays can also be extracted as numpy arrays, which
will access the C arrays directly and have the correct dimensions to protect
against invalid accesses.
.. warning::
When accessing per-atom data,
please note that this data is the per-processor local data and indexed
accordingly. These arrays can change sizes and order at every neighbor list
rebuild and atom sort event as atoms are migrating between sub-domains.
.. tabs::
.. tab:: lammps API
.. code-block:: python
from lammps import lammps
lmp = lammps()
lmp.file("in.sysinit")
natoms = lmp.get_natoms()
print(f"running simulation with {natoms} atoms")
lmp.command("run 1000 post no");
for i in range(10):
lmp.command("run 100 pre no post no")
pe = lmp.get_thermo("pe")
ke = lmp.get_thermo("ke")
print(f"PE = {pe}\nKE = {ke}")
lmp.close()
**Methods**:
* :py:meth:`version() <lammps.lammps.version()>`: return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
* :py:meth:`get_thermo() <lammps.lammps.get_thermo()>`: return current value of a thermo keyword
* :py:meth:`get_natoms() <lammps.lammps.get_natoms()>`: total # of atoms as int
* :py:meth:`reset_box() <lammps.lammps.reset_box()>`: reset the simulation box size
* :py:meth:`extract_setting() <lammps.lammps.extract_setting()>`: return a global setting
* :py:meth:`extract_global() <lammps.lammps.extract_global()>`: extract a global quantity
* :py:meth:`extract_atom() <lammps.lammps.extract_atom()>`: extract a per-atom quantity
* :py:meth:`extract_box() <lammps.lammps.extract_box()>`: extract box info
* :py:meth:`create_atoms() <lammps.lammps.create_atoms()>`: create N atoms with IDs, types, x, v, and image flags
**Numpy Methods**:
* :py:meth:`numpy.extract_atom() <lammps.numpy_wrapper.extract_atom()>`: extract a per-atom quantity as numpy array
.. tab:: PyLammps/IPyLammps API
In addition to the functions provided by :py:class:`lammps <lammps.lammps>`, :py:class:`PyLammps <lammps.PyLammps>` objects
have several properties which allow you to query the system state:
L.system
Is a dictionary describing the system such as the bounding box or number of atoms
L.system.xlo, L.system.xhi
bounding box limits along x-axis
L.system.ylo, L.system.yhi
bounding box limits along y-axis
L.system.zlo, L.system.zhi
bounding box limits along z-axis
L.communication
configuration of communication subsystem, such as the number of threads or processors
L.communication.nthreads
number of threads used by each LAMMPS process
L.communication.nprocs
number of MPI processes used by LAMMPS
L.fixes
List of fixes in the current system
L.computes
List of active computes in the current system
L.dump
List of active dumps in the current system
L.groups
List of groups present in the current system
**Retrieving the value of an arbitrary LAMMPS expressions**
LAMMPS expressions can be immediately evaluated by using the ``eval`` method. The
passed string parameter can be any expression containing global :doc:`thermo` values,
variables, compute or fix data (see :doc:`Howto_output`):
.. code-block:: Python
result = L.eval("ke") # kinetic energy
result = L.eval("pe") # potential energy
result = L.eval("v_t/2.0")
**Example**
.. code-block:: python
from lammps import PyLammps
L = PyLammps()
L.file("in.sysinit")
print(f"running simulation with {L.system.natoms} atoms")
L.run(1000, "post no");
for i in range(10):
L.run(100, "pre no post no")
pe = L.eval("pe")
ke = L.eval("ke")
print(f"PE = {pe}\nKE = {ke}")
Retrieving or setting properties of LAMMPS objects
**************************************************
This section documents accessing or modifying data from objects like
computes, fixes, or variables in LAMMPS using the :py:mod:`lammps` module.
.. tabs::
.. tab:: lammps API
For :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>` and
:py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`, the global, per-atom,
or local data calculated by the compute or fix can be accessed. What is returned
depends on whether the compute or fix calculates a scalar or vector or array.
For a scalar, a single double value is returned. If the compute or fix calculates
a vector or array, a pointer to the internal LAMMPS data is returned, which you can
use via normal Python subscripting.
The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices.
See the :doc:`Howto output <Howto_output>` doc page for a discussion of
global, per-atom, and local data, and of scalar, vector, and array
data types. See the doc pages for individual :doc:`computes <compute>`
and :doc:`fixes <fix>` for a description of what they calculate and
store.
For :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`,
an :doc:`equal-style or atom-style variable <variable>` is evaluated and
its result returned.
For equal-style variables a single ``c_double`` value is returned and the
group argument is ignored. For atom-style variables, a vector of
``c_double`` is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
:py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`,
:py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`, and
:py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>` are
equivalent NumPy implementations that return NumPy arrays instead of ``ctypes`` pointers.
The :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>` method sets an
existing string-style variable to a new string value, so that subsequent LAMMPS
commands can access the variable.
**Methods**:
* :py:meth:`lammps.extract_compute() <lammps.lammps.extract_compute()>`: extract value(s) from a compute
* :py:meth:`lammps.extract_fix() <lammps.lammps.extract_fix()>`: extract value(s) from a fix
* :py:meth:`lammps.extract_variable() <lammps.lammps.extract_variable()>`: extract value(s) from a variable
* :py:meth:`lammps.set_variable() <lammps.lammps.set_variable()>`: set existing named string-style variable to value
**NumPy Methods**:
* :py:meth:`lammps.numpy.extract_compute() <lammps.numpy_wrapper.extract_compute()>`: extract value(s) from a compute, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_fix() <lammps.numpy_wrapper.extract_fix()>`: extract value(s) from a fix, return arrays as numpy arrays
* :py:meth:`lammps.numpy.extract_variable() <lammps.numpy_wrapper.extract_variable()>`: extract value(s) from a variable, return arrays as numpy arrays
.. tab:: PyLammps/IPyLammps API
PyLammps and IPyLammps classes currently do not add any additional ways of
retrieving information out of computes and fixes. This information can still be accessed by using the lammps API:
.. code-block:: python
L.lmp.extract_compute(...)
L.lmp.extract_fix(...)
# OR
L.lmp.numpy.extract_compute(...)
L.lmp.numpy.extract_fix(...)
LAMMPS variables can be both defined and accessed via the :py:class:`PyLammps <lammps.PyLammps>` interface.
To define a variable you can use the :doc:`variable <variable>` command:
.. code-block:: Python
L.variable("a index 2")
A dictionary of all variables is returned by the :py:attr:`PyLammps.variables <lammps.PyLammps.variables>` property:
you can access an individual variable by retrieving a variable object from the
``L.variables`` dictionary by name
.. code-block:: Python
a = L.variables['a']
The variable value can then be easily read and written by accessing the value
property of this object.
.. code-block:: Python
print(a.value)
a.value = 4
Gather and Scatter Data between MPI processors
**********************************************
.. code-block:: Python
data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered)
data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs
lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs
The gather methods collect peratom info of the requested type (atom
coords, atom types, forces, etc) from all processors, and returns the
same vector of values to each calling processor. The scatter
functions do the inverse. They distribute a vector of peratom values,
passed by all calling processors, to individual atoms, which may be
owned by different processors.
Note that the data returned by the gather methods,
e.g. gather_atoms("x"), is different from the data structure returned
by extract_atom("x") in four ways. (1) Gather_atoms() returns a
vector which you index as x[i]; extract_atom() returns an array
which you index as x[i][j]. (2) Gather_atoms() orders the atoms
by atom ID while extract_atom() does not. (3) Gather_atoms() returns
a list of all atoms in the simulation; extract_atoms() returns just
the atoms local to each processor. (4) Finally, the gather_atoms()
data structure is a copy of the atom coords stored internally in
LAMMPS, whereas extract_atom() returns an array that effectively
points directly to the internal data. This means you can change
values inside LAMMPS from Python by assigning a new values to the
extract_atom() array. To do this with the gather_atoms() vector, you
need to change values in the vector, then invoke the scatter_atoms()
method.
For the scatter methods, the array of coordinates passed to must be a
ctypes vector of ints or doubles, allocated and initialized something
like this:
.. code-block:: Python
from ctypes import c_double
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_atoms("x",1,3,x)
Alternatively, you can just change values in the vector returned by
the gather methods, since they are also ctypes vectors.

22
doc/src/Speed_packages.rst
View File

@ -40,13 +40,13 @@ standard or user packages:
Inverting this list, LAMMPS currently has acceleration support for
three kinds of hardware, via the listed packages:
+----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Many-core CPUs | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>`, :doc:`USER-OMP <Speed_omp>`, :doc:`OPT <Speed_opt>` packages |
+----------------+-----------------------------------------------------------------------------------------------------------------------------+
| NVIDIA GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Intel Phi | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+----------------+-----------------------------------------------------------------------------------------------------------------------------+
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Many-core CPUs | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>`, :doc:`USER-OMP <Speed_omp>`, :doc:`OPT <Speed_opt>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| NVIDIA/AMD GPUs | :doc:`GPU <Speed_gpu>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
| Intel Phi/AVX | :doc:`USER-INTEL <Speed_intel>`, :doc:`KOKKOS <Speed_kokkos>` packages |
+-----------------+-----------------------------------------------------------------------------------------------------------------------------+
Which package is fastest for your hardware may depend on the size
problem you are running and what commands (accelerated and
@ -153,8 +153,8 @@ size and number of compute nodes, on different hardware platforms.
Here is a brief summary of what the various packages provide. Details
are in the individual accelerator sections.
* Styles with a "gpu" suffix are part of the GPU package, and can be run
on NVIDIA GPUs. The speed-up on a GPU depends on a variety of
* Styles with a "gpu" suffix are part of the GPU package and can be run
on NVIDIA or AMD GPUs. The speed-up on a GPU depends on a variety of
factors, discussed in the accelerator sections.
* Styles with an "intel" suffix are part of the USER-INTEL
package. These styles support vectorized single and mixed precision
@ -164,8 +164,8 @@ are in the individual accelerator sections.
co-processors. This can result in additional speedup over 2x depending
on the hardware configuration.
* Styles with a "kk" suffix are part of the KOKKOS package, and can be
run using OpenMP on multicore CPUs, on an NVIDIA GPU, or on an Intel
Xeon Phi in "native" mode. The speed-up depends on a variety of
run using OpenMP on multicore CPUs, on an NVIDIA or AMD GPU, or on an
Intel Xeon Phi in "native" mode. The speed-up depends on a variety of
factors, as discussed on the KOKKOS accelerator page.
* Styles with an "omp" suffix are part of the USER-OMP package and allow
a pair-style to be run in multi-threaded mode using OpenMP. This can

215
doc/src/Tools.rst
View File

@ -94,6 +94,7 @@ Miscellaneous tools
* :ref:`kate <kate>`
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`singularity <singularity_tool>`
* :ref:`SWIG interface <swig>`
* :ref:`vim <vim>`
----------
@ -406,7 +407,7 @@ LAMMPS shell
.. versionadded:: 9Oct2020
Overview
========
^^^^^^^^
The LAMMPS Shell, ``lammps-shell`` is a program that functions very
similar to the regular LAMMPS executable but has several modifications
@ -427,13 +428,15 @@ them from a file.
- Interrupting a calculation with CTRL-C will not terminate the
session but rather enforce a timeout to cleanly stop an ongoing
run (more info on timeouts is in the timer command documentation).
run (more info on timeouts is in the :doc:`timer command <timer>`
documentation).
These enhancements makes the LAMMPS shell an attractive choice for
interactive LAMMPS sessions in graphical user interfaces.
These enhancements make the LAMMPS shell an attractive choice for
interactive LAMMPS sessions in graphical desktop environments
(e.g. Gnome, KDE, Cinnamon, XFCE, Windows).
TAB-expansion
=============
^^^^^^^^^^^^^
When writing commands interactively at the shell prompt, you can hit
the TAB key at any time to try and complete the text. This completion
@ -461,7 +464,7 @@ available in that executable.
and directories.
Command line editing and history
================================
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When typing commands, command line editing similar to what BASH
provides is available. Thus it is possible to move around the
@ -490,7 +493,7 @@ readline, please see the available documentation at:
<http://www.gnu.org/s/readline/#Documentation>`_
Additional commands
===================
^^^^^^^^^^^^^^^^^^^
The following commands are added to the LAMMPS shell on top of the
regular LAMMPS commands:
@ -500,6 +503,11 @@ regular LAMMPS commands:
help (or ?) print a brief help message
history display the current command history list
clear_history wipe out the current command history list
save_history <range> <file>
write commands from the history to file.
The range is given as <from>-<to>, where <from> and <to>
may be empty. Example: save_history 100- in.recent
source <file> read commands from file (same as "include")
pwd print current working directory
cd <directory> change current working directory (same as pwd if no directory)
mem print current and maximum memory usage
@ -512,7 +520,7 @@ while using the '\|' character will always pass the following text
to the operating system's shell command.
Compilation
===========
^^^^^^^^^^^
Compilation of the LAMMPS shell can be enabled by setting the CMake
variable ``BUILD_LAMMPS_SHELL`` to "on" or using the makefile in the
@ -522,11 +530,83 @@ customization depending on the features and settings used for
compiling LAMMPS.
Limitations
===========
^^^^^^^^^^^
The LAMMPS shell was not designed for use with MPI parallelization
via ``mpirun`` or ``mpiexec`` or ``srun``.
Readline customization
^^^^^^^^^^^^^^^^^^^^^^
The behavior of the readline functionality can be customized in the
``${HOME}/.inputrc`` file. This can be used to alter the default
settings or change the key-bindings. The LAMMPS Shell sets the
application name ``lammps-shell``, so settings can be either applied
globally or only for the LAMMPS shell by bracketing them between
``$if lammps-shell`` and ``$endif`` like in the following example:
.. code-block:: bash
$if lammps-shell
# disable "beep" or "screen flash"
set bell-style none
# bind the "Insert" key to toggle overwrite mode
"\e[2~": overwrite-mode
$endif
More details about this are in the `readline documentation <https://tiswww.cwru.edu/php/chet/readline/rluserman.html#SEC9>`_.
LAMMPS Shell tips and tricks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Below are some suggestions for how to use and customize the LAMMPS shell.
Enable tilde expansion
""""""""""""""""""""""
Adding ``set expand-tilde on`` to ``${HOME}/.inputrc`` is recommended as
this will change the filename expansion behavior to replace any text
starting with "~" by the full path to the corresponding user's home
directory. While the expansion of filenames **will** happen on all
arguments where the context is not known (e.g. ``~/compile/lamm<TAB>``
will expand to ``~/compile/lammps/``), it will not replace the tilde by
default. But since LAMMPS does not do tilde expansion itself (unlike a
shell), this will result in errors. Instead the tilde-expression should
be expanded into a valid path, where the plain "~/" stands for the
current user's home directory and "~someuser/" stands for
"/home/someuser" or whatever the full path to that user's home directory
is.
File extension association
""""""""""""""""""""""""""
Since the LAMMPS shell (unlike the regular LAMMPS executable) does not
exit when an input file is passed on the command line with the "-in" or
"-i" flag (the behavior is like for ``python -i <filename>``), it makes
the LAMMPS shell suitable for associating it with input files based on
their filename extension (e.g. ".lmp"). Since ``lammps-shell`` is a
console application, you have to run it inside a terminal program with a
command line like this:
.. code-block:: bash
xterm -title "LAMMPS Shell" -e /path/to/lammps-shell -i in.file.lmp
Use history to create an input file
"""""""""""""""""""""""""""""""""""
When experimenting with commands to interactively to figure out a
suitable choice of settings or simply the correct syntax, you may want
to record part of your commands to a file for later use. This can be
done with the ``save_history`` commands, which allows to selectively
write a section of the command history to a file (Example:
``save_history 25-30 in.run``). This file can be further edited
(Example: ``|vim in.run``) and then the file read back in and tried out
(Example: ``source in.run``). If the input also creates a system box,
you first need to use the :doc:`clear` command.
----------
.. _arc:
@ -799,6 +879,123 @@ For more details please see the README.md file in that folder.
----------
.. _swig:
SWIG interface
--------------
The `SWIG tool <http://swig.org>`_ offers a mostly automated way to
incorporate compiled code modules into scripting languages. It
processes the function prototypes in C and generates wrappers for a wide
variety of scripting languages from it. Thus it can also be applied to
the :doc:`C language library interface <Library>` of LAMMPS so that
build a wrapper that allows to call LAMMPS from programming languages
like: C#/Mono, Lua, Java, JavaScript, Perl, Python, R, Ruby, Tcl, and
more.
What is included
^^^^^^^^^^^^^^^^
We provide here an "interface file", ``lammps.i``, that has the content
of the ``library.h`` file adapted so SWIG can process it. That will
create wrappers for all the functions that are present in the LAMMPS C
library interface. Please note that not all kinds of C functions can be
automatically translated, so you would have to add custom functions to
be able to utilize those where the automatic translation does not work.
A few functions for converting pointers and accessing arrays are
predefined. We provide the file here on an "as is" basis to help people
getting started, but not as a fully tested and supported feature of the
LAMMPS distribution. Any contributions to complete this are, of course,
welcome. Please also note, that for the case of creating a Python wrapper,
a fully supported :doc:`Ctypes based lammps module <Python_module>`
already exists. That module is designed to be object oriented while
SWIG will generate a 1:1 translation of the functions in the interface file.
Building the wrapper
^^^^^^^^^^^^^^^^^^^^
When using CMake, the build steps for building a wrapper
module are integrated for the languages: Java, Lua,
Perl5, Python, Ruby, and Tcl. These require that the
LAMMPS library is build as a shared library and all
necessary development headers and libraries are present.
.. code-block:: bash
-D WITH_SWIG=on # to enable building any SWIG wrapper
-D BUILD_SWIG_JAVA=on # to enable building the Java wrapper
-D BUILD_SWIG_LUA=on # to enable building the Lua wrapper
-D BUILD_SWIG_PERL5=on # to enable building the Perl 5.x wrapper
-D BUILD_SWIG_PYTHON=on # to enable building the Python wrapper
-D BUILD_SWIG_RUBY=on # to enable building the Ruby wrapper
-D BUILD_SWIG_TCL=on # to enable building the Tcl wrapper
Manual building allows a little more flexibility. E.g. one can choose
the name of the module and build and use a dynamically loaded object
for Tcl with:
.. code-block:: bash
$ swig -tcl -module tcllammps lammps.i
$ gcc -fPIC -shared $(pkgconf --cflags tcl) -o tcllammps.so \
lammps_wrap.c -L ../src/ -llammps
$ 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 \
-DHAVE_CONFIG_H $(pkgconf --cflags tcl) \
$(pkgconf --libs tcl) -L ../src -llammps
In both cases it is assumed that the LAMMPS library was compiled
as a shared library in the ``src`` folder. Otherwise the last
part of the commands needs to be adjusted.
Utility functions
^^^^^^^^^^^^^^^^^
Definitions for several utility functions required to manage and access
data passed or returned as pointers are included in the ``lammps.i``
file. So most of the functionality of the library interface should be
accessible. What works and what does not depends a bit on the
individual language for which the wrappers are built and how well SWIG
supports those. The `SWIG documentation <http://swig.org/doc.html>`_
has very detailed instructions and recommendations.
Usage examples
^^^^^^^^^^^^^^
The ``tools/swig`` folder has multiple shell scripts, ``run_<name>_example.sh``
that will create a small example script and demonstrate how to load
the wrapper and run LAMMPS through it in the corresponding programming
language.
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
----------
.. _vim:
vim tool

3
doc/src/atom_style.rst
View File

@ -42,6 +42,7 @@ Examples
atom_style hybrid charge body nparticle 2 5
atom_style spin
atom_style template myMols
atom_style hybrid template twomols charge
atom_style tdpd 2
Description
@ -239,6 +240,8 @@ can save memory for systems comprised of a large number of small
molecules, all of a single type (or small number of types). See the
paper by Grime and Voth, in :ref:`(Grime) <Grime>`, for examples of how this
can be advantageous for large-scale coarse-grained systems.
The ``examples/template`` directory has a few demo inputs and examples
showing the use of the *template* atom style versus *molecular*.
.. note::

4
doc/src/compute_angle.rst
View File

@ -24,8 +24,8 @@ Description
"""""""""""
Define a computation that extracts the angle energy calculated by each
of the angle sub-styles used in the "angle_style
hybrid" angle_hybrid.html command. These values are made accessible
of the angle sub-styles used in the doc:`angle_style hybrid <angle_hybrid>`
command. These values are made accessible
for output or further processing by other commands. The group
specified for this command is ignored.

2
doc/src/create_atoms.rst
View File

@ -28,7 +28,7 @@ Syntax
* zero or more keyword/value pairs may be appended
* keyword = *mol* or *basis* or *ratio* or *subset* or *remap* or *var* or *set* or *rotate* or *units*
.. code-block:: LAMMPS
.. parsed-literal::
*mol* value = template-ID seed
template-ID = ID of molecule template specified in a separate :doc:`molecule <molecule>` command

43
doc/src/fix_bond_react.rst
View File

@ -174,10 +174,12 @@ integer.
Three physical conditions must be met for a reaction to occur. First,
a bonding atom pair must be identified within the reaction distance
cutoffs. Second, the topology surrounding the bonding atom pair must
match the topology of the pre-reaction template. Finally, any reaction
constraints listed in the map file (see below) must be satisfied. If
all of these conditions are met, the reaction site is eligible to be
modified to match the post-reaction template.
match the topology of the pre-reaction template. Only atom types and
bond connectivity are used to identify a valid reaction site (not bond
types, etc.). Finally, any reaction constraints listed in the map file
(see below) must be satisfied. If all of these conditions are met, the
reaction site is eligible to be modified to match the post-reaction
template.
A bonding atom pair will be identified if several conditions are met.
First, a pair of atoms I,J within the specified react-group-ID of type
@ -192,19 +194,26 @@ be a function of the reaction conversion using the following commands:
fix myrxn all bond/react react myrxn1 all 1 0 v_rmax mol1 mol2 map_file.txt
variable rmax equal 3+f_myrxn[1]/100 # arbitrary function of reaction count
It is possible that multiple bonding atom pairs are identified: if the
bonding atoms in the pre-reacted template are 1-2 neighbors, i.e.
directly bonded, the farthest bonding atom partner is set as its
bonding partner; otherwise, the closest potential partner is chosen.
Then, if both an atom I and atom J have each other as their bonding
partners, these two atoms are identified as the bonding atom pair of
the reaction site. Once this unique bonding atom pair is identified
for each reaction, there could two or more reactions that involve a
given atom on the same timestep. If this is the case, only one such
reaction is permitted to occur. This reaction is chosen randomly from
all potential reactions. This capability allows e.g. for different
reaction pathways to proceed from identical reaction sites with
user-specified probabilities.
The following criteria are used if multiple candidate bonding atom
pairs are identified within the cutoff distance: 1) If the bonding
atoms in the pre-reaction template are not 1-2 neighbors (i.e. not
directly bonded) the closest potential partner is chosen. 2)
Otherwise, if the bonding atoms in the pre-reaction template are 1-2
neighbors (i.e. directly bonded) the farthest potential partner is
chosen. 3) Then, if both an atom I and atom J have each other as their
bonding partners, these two atoms are identified as the bonding atom
pair of the reaction site. Note that it can be helpful to select
unique atom types for the bonding atoms: if a bonding atom pair is
identified, as described in the previous steps, but 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 bonding atom pair is identified for each reaction, there
could be two or more reactions that involve the same atom on the same
timestep. 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 e.g. for
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

6
doc/src/fix_nh_uef.rst
View File

@ -222,9 +222,9 @@ Default
"""""""
The default keyword values specific to this fix are exy = xyz, strain
= 0 0. The remaining defaults are the same as for *fix
npt*\ _fix_nh.html except tchain = 1. The reason for this change is
given in :doc:`fix nvt/sllod <fix_nvt_sllod>`.
= 0 0. The remaining defaults are the same as for :doc:`fix npt <fix_nh>`
except tchain = 1. The reason for this change is given in
:doc:`fix nvt/sllod <fix_nvt_sllod>`.
----------

5
doc/src/fix_widom.rst
View File

@ -86,11 +86,6 @@ molecule file. See the :doc:`molecule <molecule>` command for details.
The only settings required to be in this file are the coordinates and
types of atoms in the molecule.
If you wish to insert molecules via the *mol* keyword, that will have
their bonds or angles constrained via SHAKE, use the *shake* keyword,
specifying as its value the ID of a separate :doc:`fix shake
<fix_shake>` command which also appears in your input script.
Note that fix widom does not use configurational bias MC or any other
kind of sampling of intramolecular degrees of freedom. Inserted
molecules can have different orientations, but they will all have the

10
doc/src/molecule.rst
View File

@ -79,9 +79,9 @@ make it easy to use the same molecule file in different molecule
templates or in different simulations. You can specify the same file
multiple times with different optional keywords.
The *offset*\ , *toff*\ , *aoff*\ , *doff*\ , *ioff* keywords add the
specified offset values to the atom types, bond types, angle types,
dihedral types, and/or improper types as they are read from the
The *offset*\ , *toff*\ , *boff*\ , *aoff*\ , *doff*\ , *ioff* keywords
add the specified offset values to the atom types, bond types, angle
types, dihedral types, and/or improper types as they are read from the
molecule file. E.g. if *toff* = 2, and the file uses atom types
1,2,3, then each created molecule will have atom types 3,4,5. For the
*offset* keyword, all five offset values must be specified, but
@ -484,9 +484,7 @@ of SHAKE clusters.
Restrictions
""""""""""""
This command must come after the simulation box is define by a
:doc:`read_data <read_data>`, :doc:`read_restart <read_restart>`, or
:doc:`create_box <create_box>` command.
None
Related commands
""""""""""""""""

2
doc/src/pair_atm.rst
View File

@ -143,7 +143,7 @@ combinations, else an error will result.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair styles do not support the :doc:`pair_modify <pair_modify>`
This pair style do not support the :doc:`pair_modify <pair_modify>`
mix, shift, table, and tail options.
This pair style writes its information to :doc:`binary restart files

2
doc/src/pair_buck_long.rst
View File

@ -117,7 +117,7 @@ global Coulombic cutoff is allowed.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair styles does not support mixing. Thus, coefficients for all
This pair style does not support mixing. Thus, coefficients for all
I,J pairs must be specified explicitly.
This pair style supports the :doc:`pair_modify <pair_modify>` shift

17
doc/src/pair_eam.rst
View File

@ -345,8 +345,11 @@ given by
\rho_{\alpha\beta} (r_{ij})\right) +
\frac{1}{2} \sum_{j \neq i} \phi_{\alpha\beta} (r_{ij})
where :math:`\rho_{\alpha\beta}` refers to the density contributed
by a neighbor atom J of element :math:`\beta` at the site of atom I
of element :math:`\alpha`.
This has the same form as the EAM formula above, except that rho is
now a functional specific to the atomic types of both atoms I and J,
now a functional specific to the elements of both atoms I and J,
so that different elements can contribute differently to the total
electron density at an atomic site depending on the identity of the
element at that atomic site.
@ -393,20 +396,20 @@ have an ".eam.fs" suffix. They are formatted as follows:
The 5-line header section is identical to an EAM *setfl* file.
Following the header are Nelements sections, one for each element I,
Following the header are Nelements sections, one for each element :math:`\beta`,
each with the following format:
* line 1 = atomic number, mass, lattice constant, lattice type (e.g. FCC)
* embedding function F(rho) (Nrho values)
* density function rho(r) for element I at element 1 (Nr values)
* density function rho(r) for element I at element 2
* density function :math:`\rho_{1\beta} (r)` for element :math:`\beta` at element 1 (Nr values)
* density function :math:`\rho_{2\beta} (r)` for element :math:`\beta` at element 2
* ...
* density function rho(r) for element I at element Nelement
* density function :math:`\rho_{N_{elem}\beta} (r)` for element :math:`\beta` at element :math:`N_{elem}`
The units of these quantities in line 1 are the same as for *setfl*
files. Note that the rho(r) arrays in Finnis/Sinclair can be
asymmetric (i,j != j,i) so there are Nelements\^2 of them listed in the
file.
asymmetric (:math:`\rho_{\alpha\beta} (r) \neq \rho_{\beta\alpha} (r)` )
so there are Nelements\^2 of them listed in the file.
Following the Nelements sections, Nr values for each pair potential
phi(r) array are listed in the same manner (r\*phi, units of

2
doc/src/pair_gayberne.rst
View File

@ -160,7 +160,7 @@ For atom type pairs I,J and I != J, the epsilon and sigma coefficients
and cutoff distance for this pair style can be mixed. The default mix
value is *geometric*\ . See the "pair_modify" command for details.
This pair styles supports the :doc:`pair_modify <pair_modify>` shift
This pair style supports the :doc:`pair_modify <pair_modify>` shift
option for the energy of the Lennard-Jones portion of the pair
interaction, but only for sphere-sphere interactions. There is no
shifting performed for ellipsoidal interactions due to the anisotropic

9
doc/src/pair_lcbop.rst
View File

@ -75,14 +75,15 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This pair styles is part of the MANYBODY package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
This pair style is part of the MANYBODY package. It is only enabled
if LAMMPS was built with that package.
See the :doc:`Build package <Build_package>` doc page for more info.
This pair potential requires the :doc:`newton <newton>` setting to be
"on" for pair interactions.
The C.lcbop potential file provided with LAMMPS (see the potentials
directory) is parameterized for metal :doc:`units <units>`. You can use
The ``C.lcbop`` potential file provided with LAMMPS (see the potentials
directory) is parameterized for :doc:`metal units <units>`. You can use
the LCBOP potential with any LAMMPS units, but you would need to
create your own LCBOP potential file with coefficients listed in the
appropriate units if your simulation does not use "metal" units.

2
doc/src/pair_polymorphic.rst
View File

@ -298,7 +298,7 @@ described above. For each of the F functions, nx values are listed.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair styles does not support the :doc:`pair_modify <pair_modify>`
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift, table, and tail options.
This pair style does not write their information to :doc:`binary restart

2
doc/src/pair_resquared.rst
View File

@ -173,7 +173,7 @@ equation for the Hamaker constant presented here. Mixing of sigma and
epsilon followed by calculation of the energy prefactors using the
equations above is recommended.
This pair styles supports the :doc:`pair_modify <pair_modify>` shift
This pair style supports the :doc:`pair_modify <pair_modify>` shift
option for the energy of the Lennard-Jones portion of the pair
interaction, but only for sphere-sphere interactions. There is no
shifting performed for ellipsoidal interactions due to the anisotropic

2
doc/src/pair_srp.rst
View File

@ -124,7 +124,7 @@ at the cutoff distance :math:`r_c`.
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
This pair styles does not support mixing.
This pair style does not support mixing.
This pair style does not support the :doc:`pair_modify <pair_modify>`
shift option for the energy of the pair interaction. Note that as

8
doc/src/read_data.rst
View File

@ -636,7 +636,7 @@ of analysis.
* - tdpd
- atom-ID atom-type x y z cc1 cc2 ... ccNspecies
* - template
- atom-ID molecule-ID template-index template-atom atom-type x y z
- atom-ID atom-type molecule-ID template-index template-atom x y z
* - tri
- atom-ID molecule-ID atom-type triangleflag density x y z
* - wavepacket
@ -713,9 +713,9 @@ triangle, or body in the corresponding *Ellipsoids*\ , *Lines*\ ,
The *template-index* and *template-atom* are only defined used by
:doc:`atom_style template <atom_style>`. In this case the
:doc:`molecule <molecule>` command is used to define a molecule template
which contains one or more molecules. If an atom belongs to one of
those molecules, its *template-index* and *template-atom* are both set
to positive integers; if not the values are both 0. The
which contains one or more molecules (as separate files). If an atom
belongs to one of those molecules, its *template-index* and *template-atom*
are both set to positive integers; if not the values are both 0. The
*template-index* is which molecule (1 to Nmols) the atom belongs to.
The *template-atom* is which atom (1 to Natoms) within the molecule
the atom is.

2
doc/src/read_dump.rst
View File

@ -370,6 +370,8 @@ needed to generate absolute, unscaled coordinates.
Restrictions
""""""""""""
The *native* dump file reader does not support binary .bin dump files.
To read gzipped dump files, you must compile LAMMPS with the
-DLAMMPS_GZIP option. See the :doc:`Build settings <Build_settings>`
doc page for details.

29
doc/src/rerun.rst
View File

@ -99,14 +99,15 @@ files do not match the specified output frequency.
----------
If more than one dump file is specified, the dump files are read one
after the other. It is assumed that snapshot timesteps will be in
ascending order. If a snapshot is encountered that is not in
ascending order, it will skip the snapshot until it reads one that is.
after the other in the order specified. It is assumed that snapshot
timesteps will be in ascending order. If a snapshot is encountered that
is not in ascending order, it will skip the snapshot until it reads one
that is.
This allows skipping of a duplicate snapshot (same timestep),
e.g. that appeared at the end of one file and beginning of the next.
However if you specify a series of dump files in an incorrect order
(with respect to the timesteps they contain), you may skip large
numbers of snapshots
numbers of snapshots.
Note that the dump files specified as part of the *dump* keyword can be
parallel files, i.e. written as multiple files either per processor
@ -118,17 +119,24 @@ and write parallel dump files.
The *first*\ , *last*\ , *every*\ , *skip* keywords determine which
snapshots are read from the dump file(s). Snapshots are skipped until
they have a timestamp >= *Nfirst*\ . When a snapshot with a timestamp >
*Nlast* is encountered, the rerun command finishes. Note below that
they have a timestep >= *Nfirst*\ . When a snapshot with a timestep >
*Nlast* is encountered, the rerun command finishes. Note that
the defaults for *first* and *last* are to read all snapshots. If the
*every* keyword is set to a value > 0, then only snapshots with
timestamps that are a multiple of *Nevery* are read (the first
timesteps that are a multiple of *Nevery* are read (the first
snapshot is always read). If *Nevery* = 0, then this criterion is
ignored, i.e. every snapshot is read that meets the other criteria.
If the *skip* keyword is used, then after the first snapshot is read,
every Nth snapshot is read, where N = *Nskip*\ . E.g. if *Nskip* = 3,
then only 1 out of every 3 snapshots is read, assuming the snapshot
timestamp is also consistent with the other criteria.
timestep is also consistent with the other criteria.
.. note::
Not all dump formats contain the timestep and not all dump readers
support reading it. In that case individual snapshots are assigned
consecutive timestep numbers starting at 1.
The *start* and *stop* keywords do not affect which snapshots are read
from the dump file(s). Rather, they have the same meaning that they
@ -205,9 +213,8 @@ thermodynamic output or new dump file output.
Restrictions
""""""""""""
To read gzipped dump files, you must compile LAMMPS with the
-DLAMMPS_GZIP option. See the :doc:`Build settings <Build_settings>`
doc page for details.
The *rerun* command is subject to all restrictions of
the :doc:`read_dump <read_dump>` command.
Related commands
""""""""""""""""

17
doc/src/write_restart.rst
View File

@ -58,10 +58,21 @@ file via the MPI-IO library, which is part of the MPI standard for
versions 2.0 and above. Using MPI-IO requires two steps. First,
build LAMMPS with its MPIIO package installed, e.g.
.. code-block:: bash
.. tabs::
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
.. tab:: CMake build
.. code-block:: bash
cmake . -DPKG_MPIIO=on # enables the MPIIO package in the build folder
cmake --build . # recompiles LAMMPS with the package code included
.. tab:: Traditional make
.. code-block:: bash
make yes-mpiio # installs the MPIIO package
make mpi # build LAMMPS for your platform
Second, use a restart filename which contains ".mpiio". Note that it
does not have to end in ".mpiio", just contain those characters.