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

Merge remote-tracking branch 'origin/master' into zstd_support

Browse Source
This commit is contained in:
Richard Berger
2020-09-01 12:58:41 -04:00
parent 40ea03234f 24f5807623
commit 31bd76efa5
2104 changed files with 34692 additions and 82065 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/src/Build_basics.rst
View File

@ -471,7 +471,7 @@ LAMMPS source distribution.
.. code-block:: bash
make html # create HTML doc pages in html directory
make pdf # create Developer.pdf and Manual.pdf in this directory
make pdf # create Manual.pdf in this directory
make fetch # fetch HTML and PDF files from LAMMPS web site
make clean # remove all intermediate files
make clean-all # reset the entire doc build environment

8
doc/src/Build_development.rst
View File

@ -378,22 +378,22 @@ The images below illustrate how the data is presented.
.. list-table::
* - .. figure:: JPG/coverage-overview-top.png
:target: JPG/coverage-overview-top.png
:scale: 25%
Top of the overview page
- .. figure:: JPG/coverage-overview-manybody.png
:target: JPG/coverage-overview-manybody.png
:scale: 25%
Styles with good coverage
- .. figure:: JPG/coverage-file-top.png
:target: JPG/coverage-file-top.png
:scale: 25%
Top of individual source page
- .. figure:: JPG/coverage-file-branches.png
:target: JPG/coverage-file-branches.png
:scale: 25%
Source page with branches

13
doc/src/Build_extras.rst
View File

@ -361,9 +361,12 @@ be specified in uppercase.
* - AMDAVX
- HOST
- AMD 64-bit x86 CPU (AVX 1)
* - EPYC
* - ZEN
- HOST
- AMD EPYC Zen class CPU (AVX 2)
- AMD Zen class CPU (AVX 2)
* - ZEN2
- HOST
- AMD Zen2 class CPU (AVX 2)
* - ARMV80
- HOST
- ARMv8.0 Compatible CPU
@ -445,12 +448,18 @@ be specified in uppercase.
* - TURING75
- GPU
- NVIDIA Turing generation CC 7.5 GPU
* - AMPERE80
- GPU
- NVIDIA Ampere generation CC 8.0 GPU
* - VEGA900
- GPU
- AMD GPU MI25 GFX900
* - VEGA906
- GPU
- AMD GPU MI50/MI60 GFX906
* - INTEL_GEN
- GPU
- Intel GPUs Gen9+
Basic CMake build settings:
^^^^^^^^^^^^^^^^^^^^^^^^^^^

3
doc/src/Developer/.gitignore vendored
View File

@ -1,3 +0,0 @@
/developer.aux
/developer.log
/developer.toc

198
doc/src/Developer/classes.fig
View File

@ -1,198 +0,0 @@
#FIG 3.2 Produced by xfig version 3.2.5a
Portrait
Center
Inches
Letter
100.00
Single
-2
1200 2
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2232 1170 3540 1170 3540 1505 2232 1505 2232 1170
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2220 1830 3015 1830 3015 2219 2220 2219 2220 1830
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2226 3285 3300 3285 3300 3665 2226 3665 2226 3285
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2223 5190 3225 5190 3225 5525 2223 5525 2223 5190
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2232 7125 3090 7125 3090 7478 2232 7478 2232 7125
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2226 10230 3300 10230 3300 10565 2226 10565 2226 10230
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4026 10305 4980 10305 4980 10592 4026 10592 4026 10305
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4029 9900 5205 9900 5205 10250 4029 10250 4029 9900
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4038 9315 5370 9315 5370 9659 4038 9659 4038 9315
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4023 8955 4530 8955 4530 9278 4023 9278 4023 8955
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4029 8475 5190 8475 5190 8762 4029 8762 4029 8475
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4008 8115 5430 8115 5430 8408 4008 8408 4008 8115
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4026 7425 4995 7425 4995 7712 4026 7712 4026 7425
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4035 6720 4650 6720 4650 7025 4035 7025 4035 6720
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4044 7080 4830 7080 4830 7358 4044 7358 4044 7080
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4032 6105 5205 6105 5205 6419 4032 6419 4032 6105
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4026 5715 5115 5715 5115 6062 4026 6062 4026 5715
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4023 3585 4605 3585 4605 3872 4023 3872 4023 3585
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3954 1680 5175 1680 5175 1997 3954 1997 3954 1680
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
1620 5235 2100 615
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
1605 5445 2070 10695
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3120 1935 3855 1800
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3150 2115 3765 2250
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3135 7230 3945 6840
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3150 7335 3945 8610
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
5265 8610 6195 8400
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
5280 8655 6180 8820
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3345 10290 3930 10020
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3360 10395 3930 10425
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3360 10455 3930 10755
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2193 360 3435 360 3435 647 2193 647 2193 360
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3398 3472 3923 3307
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3413 3601 3923 3721
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3285 2806 3870 2802
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3315 5372 3900 5368
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6354 2280 7470 2280 7470 2585 6354 2585 6354 2280
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6348 1875 7320 1875 7320 2222 6348 2222 6348 1875
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3954 2070 5505 2070 5505 2372 3954 2372 3954 2070
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
5634 2137 6230 2045
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
5670 2310 6265 2418
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
3900 2640 5400 2640 5400 2975 3900 2975 3900 2640
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4038 3165 5385 3165 5385 3497 4038 3497 4038 3165
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4245 4110 5730 4110 5730 4499 4245 4499 4245 4110
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4233 4545 6390 4545 6390 4862 4233 4862 4233 4545
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4026 5190 5385 5190 5385 5525 4026 5525 4026 5190
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4038 7755 5310 7755 5310 8075 4038 8075 4038 7755
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6270 8250 7365 8250 7365 8610 6270 8610 6270 8250
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
6273 8655 7380 8655 7380 8978 6273 8978 6273 8655
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
4041 10620 5985 10620 5985 10943 4041 10943 4041 10620
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2217 10830 3135 10830 3135 11156 2217 11156 2217 10830
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2229 9780 3240 9780 3240 10118 2229 10118 2229 9780
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2214 9015 3285 9015 3285 9362 2214 9362 2214 9015
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2208 5850 3420 5850 3420 6209 2208 6209 2208 5850
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2217 4275 3615 4275 3615 4634 2217 4634 2217 4275
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2235 2655 3150 2655 3150 3000 2235 3000 2235 2655
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
60 5115 1500 5115 1500 5610 60 5610 60 5115
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3486 6018 4011 5853
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3486 6129 3996 6249
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3361 9291 3991 9531
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3345 9129 4005 9099
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3691 4412 4216 4277
2 1 0 2 0 7 50 -1 -1 0.000 0 0 -1 1 0 2
1 1 2.00 120.00 240.00
3695 4561 4175 4711
2 2 0 1 0 7 50 -1 -1 0.000 0 0 -1 0 0 5
2220 735 3129 735 3129 1043 2220 1043 2220 735
4 0 1 50 -1 18 18 0.0000 4 225 1275 2265 1455 Universe\001
4 0 1 50 -1 18 18 0.0000 4 285 735 2265 2175 Input\001
4 0 1 50 -1 18 18 0.0000 4 225 780 2265 2925 Atom\001
4 0 1 50 -1 18 18 0.0000 4 285 1020 2265 3600 Update\001
4 0 1 50 -1 18 18 0.0000 4 285 1320 2265 4575 Neighbor\001
4 0 1 50 -1 18 18 0.0000 4 225 945 2265 5475 Comm\001
4 0 1 50 -1 18 18 0.0000 4 225 1110 2265 6150 Domain\001
4 0 1 50 -1 18 18 0.0000 4 225 810 2265 7425 Force\001
4 0 1 50 -1 18 18 0.0000 4 285 975 2265 9300 Modify\001
4 0 1 50 -1 18 18 0.0000 4 285 900 2265 10050 Group\001
4 0 1 50 -1 18 18 0.0000 4 285 990 2265 10500 Output\001
4 0 1 50 -1 18 18 0.0000 4 225 825 2265 11100 Timer\001
4 0 0 50 -1 18 18 0.0000 4 225 1170 3990 1950 Variable\001
4 0 4 50 -1 18 18 0.0000 4 225 1470 3990 2325 Command\001
4 0 4 50 -1 18 18 0.0000 4 285 1275 4065 3450 Integrate\001
4 0 4 50 -1 18 18 0.0000 4 225 525 4065 3825 Min\001
4 0 0 50 -1 18 18 0.0000 4 285 1230 4065 5475 Irregular\001
4 0 4 50 -1 18 18 0.0000 4 285 1020 4065 6000 Region\001
4 0 0 50 -1 18 18 0.0000 4 225 975 4065 6375 Lattice\001
4 0 4 50 -1 18 18 0.0000 4 225 435 4065 9225 Fix\001
4 0 4 50 -1 18 18 0.0000 4 285 1305 4065 9600 Compute\001
4 0 4 50 -1 18 18 0.0000 4 225 570 4065 6975 Pair\001
4 0 4 50 -1 18 18 0.0000 4 285 840 4065 7665 Angle\001
4 0 4 50 -1 18 18 0.0000 4 225 1215 4065 8010 Dihedral\001
4 0 4 50 -1 18 18 0.0000 4 285 1305 4065 8355 Improper\001
4 0 4 50 -1 18 18 0.0000 4 285 1095 4065 8700 KSpace\001
4 0 4 50 -1 18 18 0.0000 4 285 855 4065 10545 Dump\001
4 0 0 50 -1 18 18 0.0000 4 225 1815 4065 10890 WriteRestart\001
4 0 0 50 -1 18 18 0.0000 4 225 930 6315 8550 FFT3D\001
4 0 0 50 -1 18 18 0.0000 4 285 1005 6315 8925 Remap\001
4 0 0 50 -1 18 18 0.0000 4 225 885 6390 2175 Finish\001
4 0 0 50 -1 18 18 0.0000 4 285 1050 6390 2550 Special\001
4 0 4 50 -1 18 18 0.0000 4 225 1305 3990 2925 AtomVec\001
4 0 4 50 -1 18 18 0.0000 4 225 765 4065 7320 Bond\001
4 0 0 50 -1 18 18 0.0000 4 225 1095 4065 10200 Thermo\001
4 0 0 50 -1 18 18 0.0000 4 285 1380 4305 4425 NeighList\001
4 0 0 50 -1 18 18 0.0000 4 285 2025 4305 4800 NeighRequest\001
4 0 1 50 -1 18 18 0.0000 4 285 1155 2250 600 Memory\001
4 0 0 50 -1 18 18 0.0000 4 225 1305 120 5475 LAMMPS\001
4 0 1 50 -1 18 18 0.0000 4 225 735 2265 1005 Error\001

BIN
doc/src/Developer/classes.pdf
View File

Binary file not shown.

699
doc/src/Developer/developer.tex
View File

@ -1,699 +0,0 @@
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\centerline{\Large \bf LAMMPS Developer Guide}
\centerline{\bf 23 Aug 2011}
\vspace{0.5in}
This document is a developer guide to the LAMMPS molecular dynamics
package, whose WWW site is at lammps.sandia.gov. It describes the
internal structure and algorithms of the code. Sections will be added
as we have time, and in response to requests from developers and
users.
\tableofcontents
\pagebreak
\section{LAMMPS source files}
LAMMPS source files are in two directories of the distribution
tarball. The src directory has the majority of them, all of which are
C++ files (*.cpp and *.h). Many of these files are in the src
directory itself. There are also dozens of ``packages'', which can be
included or excluded when LAMMPS is built. See the
doc/Section\_build.html section of the manual for more information
about packages, or type ``make'' from within the src directory, which
lists package-related commands, such as ``make package-status''. The
source files for each package are in an all-uppercase sub-directory of
src, like src/MOLECULE or src/USER-CUDA. If the package is currently
installed, copies of the package source files will also exist in the
src directory itself. The src/STUBS sub-directory is not a package
but contains a dummy version of the MPI library, used when building a
serial version of the code.
The lib directory also contains source code for external libraries,
used by a few of the packages. Each sub-directory, like meam or gpu,
contains the source files, some of which are in different languages
such as Fortran. The files are compiled into libraries from within
each sub-directory, e.g. performing a ``make'' in the lib/meam directory
creates a libmeam.a file. These libraries are linked to during a
LAMMPS build, if the corresponding package is installed.
LAMMPS C++ source files almost always come in pairs, such as run.cpp
and run.h. The pair of files defines a C++ class, the Run class in
this case, which contains the code invoked by the ``run'' command in a
LAMMPS input script. As this example illustrates, source file and
class names often have a one-to-one correspondence with a command used
in a LAMMPS input script. Some source files and classes do not have a
corresponding input script command, e.g. ``force.cpp'' and the Force
class. They are discussed in the next section.
\pagebreak
\section{Class hierarchy of LAMMPS}
Though LAMMPS has a lot of source files and classes, its class
hierarchy is quite simple, as outlined in Fig \ref{fig:classes}. Each
boxed name refers to a class and has a pair of associated source files
in lammps/src, e.g. ``memory.cpp'' and ``memory.h''. More details on the
class and its methods and data structures can be found by examining
its *.h file.
LAMMPS (lammps.cpp/h) is the top-level class for the entire code. It
holds an ``instance'' of LAMMPS and can be instantiated one or more
times by a calling code. For example, the file src/main.cpp simply
instantiates one instance of LAMMPS and passes it the input script.
The file src/library.cpp contains a C-style library interface to the
LAMMPS class. See the lammps/couple and lammps/python directories for
examples of simple programs that use LAMMPS through its library
interface. A driver program can instantiate the LAMMPS class multiple
times, e.g. to embed several atomistic simulation regions within a
mesoscale or continuum simulation domain.
There are a dozen or so top-level classes within the LAMMPS class that
are visible everywhere in the code. They are shaded blue in Fig
\ref{fig:classes}. Thus any class can refer to the y-coordinate of
local atom $I$ as atom$\rightarrow$x[i][1]. This visibility is
enabled by a bit of cleverness in the Pointers class (see
src/pointers.h) which every class inherits from.
There are a handful of virtual parent classes in LAMMPS that define
what LAMMPS calls ``styles''. They are shaded red in Fig
\ref{fig:classes}. Each of these are parents of a number of child
classes that implement the interface defined by the parent class. For
example, the fix style has around 100 child classes. They are the
possible fixes that can be specified by the fix command in an input
script, e.g. fix nve, fix shake, fix ave/time, etc. The corresponding
classes are Fix (for the parent class), FixNVE, FixShake, FixAveTime,
etc. The source files for these classes are easy to identify in the
src directory, since they begin with the word ``fix'', e,g,
fix\_nve.cpp, fix\_shake,cpp, fix\_ave\_time.cpp, etc.
The one exception is child class files for the ``command'' style. These
implement specific commands in the input script that can be invoked
before/after/between runs or which launch a simulation. Examples are
the create\_box, minimize, run, and velocity commands which encode the
CreateBox, Minimize, Run, and Velocity classes. The corresponding
files are create\_box,cpp, minimize.cpp, run.cpp, and velocity.cpp.
The list of command style files can be found by typing ``grep
COMMAND\_CLASS *.h'' from within the src directory, since that word in
the header file identifies the class as an input script command.
Similar words can be grepped to list files for the other LAMMPS
styles. E.g. ATOM\_CLASS, PAIR\_CLASS, BOND\_CLASS, REGION\_CLASS,
FIX\_CLASS, COMPUTE\_CLASS, DUMP\_CLASS, etc.
\begin{figure}[htb]
\begin{center}
\includegraphics[height=4in]{classes.pdf}
\end{center}
\caption{Class hierarchy within LAMMPS source code.}
\label{fig:classes}
\end{figure}
More details on individual classes in Fig \ref{fig:classes} are as
follows:
\begin{itemize}
\item The Memory class handles allocation of all large vectors and
arrays.
\item The Error class prints all error and warning messages.
\item The Universe class sets up partitions of processors so that
multiple simulations can be run, each on a subset of the processors
allocated for a run, e.g. by the mpirun command.
\item The Input class reads an input script, stores variables, and
invokes stand-alone commands that are child classes of the Command
class.
\item As discussed above, the Command class is a parent class for
certain input script commands that perform a one-time operation
before/after/between simulations or which invoke a simulation. They
are instantiated from within the Input class, invoked, then
immediately destructed.
\item The Finish class is instantiated to print statistics to the
screen after a simulation is performed, by commands like run and
minimize.
\item The Special class walks the bond topology of a molecular system
to find first, second, third neighbors of each atom. It is invoked by
several commands, like read\_data, read\_restart, and replicate.
\item The Atom class stores all per-atom arrays. More precisely, they
are allocated and stored by the AtomVec class, and the Atom class
simply stores a pointer to them. The AtomVec class is a parent
class for atom styles, defined by the atom\_style command.
\item The Update class holds an integrator and a minimizer. The
Integrate class is a parent style for the Verlet and rRESPA time
integrators, as defined by the run\_style input command. The Min
class is a parent style for various energy minimizers.
\item The Neighbor class builds and stores neighbor lists. The
NeighList class stores a single list (for all atoms). The
NeighRequest class is called by pair, fix, or compute styles when
they need a particular kind of neighbor list.
\item The Comm class performs interprocessor communication, typically
of ghost atom information. This usually involves MPI message
exchanges with 6 neighboring processors in the 3d logical grid of
processors mapped to the simulation box. Sometimes the Irregular
class is used, when atoms may migrate to arbitrary processors.
\item The Domain class stores the simulation box geometry, as well as
geometric Regions and any user definition of a Lattice. The latter
are defined by region and lattice commands in an input script.
\item The Force class computes various forces between atoms. The Pair
parent class is for non-bonded or pair-wise forces, which in LAMMPS
lingo includes many-body forces such as the Tersoff 3-body
potential. The Bond, Angle, Dihedral, Improper parent classes are
styles for bonded interactions within a static molecular topology.
The KSpace parent class is for computing long-range Coulombic
interactions. One of its child classes, PPPM, uses the FFT3D and
Remap classes to communicate grid-based information with neighboring
processors.
\item The Modify class stores lists of Fix and Compute classes, both
of which are parent styles.
\item The Group class manipulates groups that atoms are assigned to
via the group command. It also computes various attributes of
groups of atoms.
\item The Output class is used to generate 3 kinds of output from a
LAMMPS simulation: thermodynamic information printed to the screen
and log file, dump file snapshots, and restart files. These
correspond to the Thermo, Dump, and WriteRestart classes
respectively. The Dump class is a parent style.
\item The Timer class logs MPI timing information, output at the end
of a run.
\end{itemize}
%%\pagebreak
%%\section{Spatial decomposition and parallel operations}
%%distributed memory
%%Ref to JCP paper
%%diagram of 3d grid of procs and spatial decomp
%%6-way comm
%%ghost atoms, PBC added when comm (in atom class)
%%\pagebreak
%%\section{Fixes, computes, variables}
%%fixes intercolate in timestep, store per-atom info
%%computes based on current snapshot
%%equal- and atom-style variables
%%output they produce - see write-up in HowTo
\pagebreak
\section{How a timestep works}
The first and most fundamental operation within LAMMPS to understand
is how a timestep is structured. Timestepping is performed by the
Integrate class within the Update class. Since Integrate is a parent
class, corresponding to the run\_style input script command, it has
child classes. In this section, the timestep implemented by the
Verlet child class is described. A similar timestep is implemented by
the Respa child class, for the rRESPA hierarchical timestepping
method. The Min parent class performs energy minimization, so does
not perform a literal timestep. But it has logic similar to what is
described here, to compute forces and invoke fixes at each iteration
of a minimization. Differences between time integration and
minimization are highlighted at the end of this section.
The Verlet class is encoded in the src/verlet.cpp and verlet.h files.
It implements the velocity-Verlet timestepping algorithm. The
workhorse method is Verlet::run(), but first we highlight several
other methods in the class.
\begin{itemize}
\item The init() method is called at the beginning of each dynamics
run. It simply sets some internal flags, based on user settings in
other parts of the code.
\item The setup() or setup\_minimal() methods are also called before
each run. The velocity-Verlet method requires current forces be
calculated before the first timestep, so these routines compute
forces due to all atomic interactions, using the same logic that
appears in the timestepping described next. A few fixes are also
invoked, using the mechanism described in the next section. Various
counters are also initialized before the run begins. The
setup\_minimal() method is a variant that has a flag for performing
less setup. This is used when runs are continued and information
from the previous run is still valid. For example, if repeated
short LAMMPS runs are being invoked, interleaved by other commands,
via the ``pre no'' and ``every'' options of the run command, the
setup\_minimal() method is used.
\item The force\_clear() method initializes force and other arrays to
zero before each timestep, so that forces (torques, etc) can be
accumulated.
\end{itemize}
Now for the Verlet::run() method. Its structure in hi-level pseudo
code is shown in Fig \ref{fig:verlet}. In the actual code in
src/verlet.cpp some of these operations are conditionally invoked.
\begin{figure}[htb]
\begin{center}
\begin{verbatim}
loop over N timesteps:
ev_set()
fix->initial_integrate()
fix->post_integrate()
nflag = neighbor->decide()
if nflag:
fix->pre_exchange()
domain->pbc()
domain->reset_box()
comm->setup()
neighbor->setup_bins()
comm->exchange()
comm->borders()
fix->pre_neighbor()
neighbor->build()
else
comm->forward_comm()
force_clear()
fix->pre_force()
pair->compute()
bond->compute()
angle->compute()
dihedral->compute()
improper->compute()
kspace->compute()
comm->reverse_comm()
fix->post_force()
fix->final_integrate()
fix->end_of_step()
if any output on this step: output->write()
\end{verbatim}
\end{center}
\caption{Pseudo-code for the Verlet::run() method.}
\label{fig:verlet}
\end{figure}
The ev\_set() method (in the parent Integrate class), sets two flags
({\em eflag} and {\em vflag}) for energy and virial computation. Each
flag encodes whether global and/or per-atom energy and virial should
be calculated on this timestep, because some fix or variable or output
will need it. These flags are passed to the various methods that
compute particle interactions, so that they can skip the extra
calculations if the energy and virial are not needed. See the
comments with the Integrate::ev\_set() method which document the flag
values.
At various points of the timestep, fixes are invoked,
e.g. fix$\rightarrow$initial\_integrate(). In the code, this is
actually done via the Modify class which stores all the Fix objects
and lists of which should be invoked at what point in the timestep.
Fixes are the LAMMPS mechanism for tailoring the operations of a
timestep for a particular simulation. As described elsewhere
(unwritten section), each fix has one or more methods, each of which
is invoked at a specific stage of the timestep, as in Fig
\ref{fig:verlet}. All the fixes defined in an input script with an
initial\_integrate() method are invoked at the beginning of each
timestep. Fix nve, nvt, npt are examples, since they perform the
start-of-timestep velocity-Verlet integration to update velocities by
a half-step, and coordinates by a full step. The post\_integrate()
method is next. Only a few fixes use this, e.g. to reflect particles
off box boundaries in the FixWallReflect class.
The decide() method in the Neighbor class determines whether neighbor
lists need to be rebuilt on the current timestep. If not, coordinates
of ghost atoms are acquired by each processor via the forward\_comm()
method of the Comm class. If neighbor lists need to be built, several
operations within the inner if clause of Fig \ref{fig:verlet} are
first invoked. The pre\_exchange() method of any defined fixes is
invoked first. Typically this inserts or deletes particles from the
system.
Periodic boundary conditions are then applied by the Domain class via
its pbc() method to remap particles that have moved outside the
simulation box back into the box. Note that this is not done every
timestep. but only when neighbor lists are rebuilt. This is so that
each processor's sub-domain will have consistent (nearby) atom
coordinates for its owned and ghost atoms. It is also why dumped atom
coordinates can be slightly outside the simulation box.
The box boundaries are then reset (if needed) via the reset\_box()
method of the Domain class, e.g. if box boundaries are shrink-wrapped
to current particle coordinates. A change in the box size or shape
requires internal information for communicating ghost atoms (Comm
class) and neighbor list bins (Neighbor class) be updated. The
setup() method of the Comm class and setup\_bins() method of the
Neighbor class perform the update.
The code is now ready to migrate atoms that have left a processor's
geometric sub-domain to new processors. The exchange() method of the
Comm class performs this operation. The borders() method of the Comm
class then identifies ghost atoms surrounding each processor's
sub-domain and communicates ghost atom information to neighboring
processors. It does this by looping over all the atoms owned by a
processor to make lists of those to send to each neighbor processor.
On subsequent timesteps, the lists are used by the
Comm::forward\_comm() method.
Fixes with a pre\_neighbor() method are then called. These typically
re-build some data structure stored by the fix that depends on the
current atoms owned by each processor.
Now that each processor has a current list of its owned and ghost
atoms, LAMMPS is ready to rebuild neighbor lists via the build()
method of the Neighbor class. This is typically done by binning all
owned and ghost atoms, and scanning a stencil of bins around each
owned atom's bin to make a Verlet list of neighboring atoms within the
force cutoff plus neighbor skin distance.
In the next portion of the timestep, all interaction forces between
particles are computed, after zeroing the per-atom force vector via
the force\_clear() method. If the newton flag is set to ``on'' by the
newton command, forces on both owned and ghost atoms are calculated.
Pairwise forces are calculated first, which enables the global virial
(if requested) to be calculated cheaply (at the end of the
Pair::compute() method), by a dot product of atom coordinates and
forces. By including owned and ghost atoms in the dot product, the
effect of periodic boundary conditions is correctly accounted for.
Molecular topology interactions (bonds, angles, dihedrals, impropers)
are calculated next. The final contribution is from long-range
Coulombic interactions, invoked by the KSpace class.
If the newton flag is on, forces on ghost atoms are communicated and
summed back to their corresponding owned atoms. The reverse\_comm()
method of the Comm class performs this operation, which is essentially
the inverse operation of sending copies of owned atom coordinates to
other processor's ghost atoms.
At this point in the timestep, the total force on each atom is known.
Additional force constraints (external forces, SHAKE, etc) are applied
by Fixes that have a post\_force() method. The second half of the
velocity-Verlet integration is then performed (another half-step
update of the velocities) via fixes like nve, nvt, npt.
At the end of the timestep, fixes that define an end\_of\_step()
method are invoked. These typically perform a diagnostic calculation,
e.g. the ave/time and ave/spatial fixes. The final operation of the
timestep is to perform any requested output, via the write() method of
the Output class. There are 3 kinds of LAMMPS output: thermodynamic
output to the screen and log file, snapshots of atom data to a dump
file, and restart files. See the thermo\_style, dump, and restart
commands for more details.
The iteration performed by an energy minimization is similar to the
dynamics timestep of Fig \ref{fig:verlet}. Forces are computed,
neighbor lists are built as needed, atoms migrate to new processors,
and atom coordinates and forces are communicated to neighboring
processors. The only difference is what Fix class operations are
invoked when. Only a subset of LAMMPS fixes are useful during energy
minimization, as explained in their individual doc pages. The
relevant Fix class methods are min\_pre\_exchange(),
min\_pre\_force(), and min\_post\_force(). Each is invoked at the
appropriate place within the minimization iteration. For example, the
min\_post\_force() method is analogous to the post\_force() method for
dynamics; it is used to alter or constrain forces on each atom, which
affects the minimization procedure.
\pagebreak
\section{Extending LAMMPS}
The Section\_modify.html file in the doc directory of
the LAMMPS distribution gives an overview of how LAMMPS can
be extended by writing new classes that derive from existing
parent classes in LAMMPS. Here, some specific coding
details are provided for writing a new fix.
\subsection{New fixes}
(this section provided by Kirill Lykov)
\vspace{0.25cm}
Writing fixes is a flexible way of extending LAMMPS. Users can
implement many things using fixes:
\begin{itemize}
\item changing particles attributes (positions, velocities, forces, etc.).
Example: FixFreeze.
\item reading/writing data. Example: FixRestart.
\item implementing boundary conditions. Example: FixWall.
\item saving information about particles for future use (previous positions,
for instance). Example: FixStoreState.
\end{itemize}
All fixes are derived from class Fix and must have constructor with the
signature: FixMine(class LAMMPS *, int, char **).
Every fix must be registered in LAMMPS by writing the following lines
of code in the header before include guards:
\begin{center}
\begin{verbatim}
#ifdef FIX_CLASS
FixStyle(your/fix/name,FixMine)
#else
\end{verbatim}
\end{center}
Where ``your/fix/name'' is a name of your fix in the script and FixMine
is the name of the class. This code allows LAMMPS to find your fix
when it parses input script. In addition, your fix header must be
included in the file ``style\_fix.h''. In case if you use LAMMPS make,
this file is generated automatically - all files starting with prefix
fix\_ are included, so call your header the same way. Otherwise, don't
forget to add your include into ``style\_fix.h''.
Let's write a simple fix which will print average velocity at the end
of each timestep. First of all, implement a constructor:
\begin{center}
\begin{verbatim}
FixPrintVel::FixPrintVel(LAMMPS *lmp, int narg, char **arg)
: Fix(lmp, narg, arg)
{
if (narg < 4)
error->all(FLERR,"Illegal fix print command");
nevery = atoi(arg[3]);
if (nevery <= 0)
error->all(FLERR,"Illegal fix print command");
}
\end{verbatim}
\end{center}
In the constructor you should parse your fix arguments which are
specified in the script. All fixes have pretty the same syntax: fix
[fix\_identifier] [group\_name] [fix\_name] [fix\_arguments]. The
first 3 parameters are parsed by Fix class constructor, while
[fix\_arguments] should be parsed by you. In our case, we need to
specify how often we want to print an average velocity. For instance,
once in 50 timesteps: fix 1 print/vel 50. There is a special variable
in Fix class called nevery which specifies how often method
end\_of\_step() is called. Thus all we need to do is just set it up.
The next method we need to implement is setmask():
\begin{center}
\begin{verbatim}
int FixPrintVel::setmask()
{
int mask = 0;
mask |= FixConst::END_OF_STEP;
return mask;
}
\end{verbatim}
\end{center}
Here user specifies which methods of your fix should be called during
the execution. For instance, END\_OF\_STEP corresponds to the
end\_of\_step() method. Overall, there are 8 most important methods,
methods are called in predefined order during the execution of the
verlet algorithm as was mentioned in the Section 3:
\begin{itemize}
\item initial\_integrate()
\item post\_integrate()
\item pre\_exchange()
\item pre\_neighbor()
\item pre\_force()
\item post\_force()
\item final\_integrate()
\item end\_of\_step()
\end{itemize}
Fix developer must understand when he wants to execute his code. In
case if we want to write FixPrintVel, we need only end\_of\_step():
\begin{center}
\begin{verbatim}
void FixPrintVel::end_of_step()
{
// for add3, scale3
using namespace MathExtra;
double** v = atom->v;
int nlocal = atom->nlocal;
double localAvgVel[4]; // 4th element for particles count
memset(localAvgVel, 0, 4 * sizeof(double));
for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
add3(localAvgVel, v[particleInd], localAvgVel);
}
localAvgVel[3] = nlocal;
double globalAvgVel[4];
memset(globalAvgVel, 0, 4 * sizeof(double));
MPI_Allreduce(localAvgVel, globalAvgVel, 4, MPI_DOUBLE, MPI_SUM, world);
scale3(1.0 / globalAvgVel[3], globalAvgVel);
if (comm->me == 0) {
printf("\%e, \%e, \%e\n",
globalAvgVel[0], globalAvgVel[1], globalAvgVel[2]);
}
}
\end{verbatim}
\end{center}
In the code above, we use MathExtra routines defined in
``math\_extra.h''. There are bunch of math functions to work with
arrays of doubles as with math vectors.
In this code we use an instance of Atom class. This object is stored
in the Pointers class (see ``pointers.h''). This object contains all
global information about the simulation system. Data from Pointers
class available to all classes inherited from it using protected
inheritance. Hence when you write you own class, which is going to use
LAMMPS data, don't forget to inherit from Pointers. When writing
fixes we inherit from class Fix which is inherited from Pointers so
there is no need to inherit from it directly.
The code above computes average velocity for all particles in the
simulation. Yet you have one unused parameter in fix call from the
script - [group\_name]. This parameter specifies the group of atoms
used in the fix. So we should compute average for all particles in the
simulation if group\_name == all, but it can be any group. The group
information is specified by groupbit which is defined in class Fix:
\begin{center}
\begin{verbatim}
for (int particleInd = 0; particleInd < nlocal; ++particleInd) {
if (atom->mask[particleInd] & groupbit) {
//Do all job here
}
}
\end{verbatim}
\end{center}
Class Atom encapsulates atoms positions, velocities, forces, etc. User
can access them using particle index. Note, that particle indexes are
usually changed every timestep because of sorting.
Lets consider another Fix example. We want to have a fix which stores
atoms position from previous time step in your fix. The local atoms
indexes will not be valid on the next iteration. In order to handle
this situation there are several methods which should be implemented:
\begin{itemize}
\item \verb|double memory_usage| - return how much memory fix uses
\item \verb|void grow_arrays(int)| - do reallocation of the per particle arrays
in your fix
\item \verb|void copy_arrays(int i, int j, int delflag)| - copy i-th per-particle
information to j-th. Used when atoms sorting is performed. if delflag is set
and atom j owns a body, move the body information to atom i.
\item \verb|void set_arrays(int i)| - sets i-th particle related information to zero
\end{itemize}
Note, that if your class implements these methods, it must call add calls of
add\_callback and delete\_callback to constructor and destructor:
\begin{center}
\begin{verbatim}
FixSavePos::FixSavePos(LAMMPS *lmp, int narg, char **arg) {
//...
atom->add_callback(0);
}
FixSavePos::~FixSavePos() {
atom->delete_callback(id, 0);
}
\end{verbatim}
\end{center}
Since we want to store positions of atoms from previous timestep, we
need to add double** x to the header file. Than add allocation code to
constructor:
\verb|memory->create(this->x, atom->nmax, 3, "FixSavePos:x");|. Free memory
at destructor: \verb|memory->destroy(x);|
Finally, implement mentioned methods:
\begin{center}
\begin{verbatim}
double FixSavePos::memory_usage()
{
int nmax = atom->nmax;
double bytes = 0.0;
bytes += nmax * 3 * sizeof(double);
return bytes;
}
void FixSavePos::grow_arrays(int nmax)
{
memory->grow(this->x, nmax, 3, "FixSavePos:x");
}
void FixSavePos::copy_arrays(int i, int j, int delflag)
{
memcpy(this->x[j], this->x[i], sizeof(double) * 3);
}
void FixSavePos::set_arrays(int i)
{
memset(this->x[i], 0, sizeof(double) * 3);
}
int FixSavePos::pack_exchange(int i, double *buf)
{
int m = 0;
buf[m++] = x[i][0];
buf[m++] = x[i][1];
buf[m++] = x[i][2];
return m;
}
int FixSavePos::unpack_exchange(int nlocal, double *buf)
{
int m = 0;
x[nlocal][0] = buf[m++];
x[nlocal][1] = buf[m++];
x[nlocal][2] = buf[m++];
return m;
}
\end{verbatim}
\end{center}
Now, a little bit about memory allocation. We used Memory class which
is just a bunch of template functions for allocating 1D and 2D
arrays. So you need to add include ``memory.h'' to have access to them.
Finally, if you need to write/read some global information used in
your fix to the restart file, you might do it by setting flag
restart\_global = 1 in the constructor and implementing methods void
write\_restart(FILE *fp) and void restart(char *buf).
\end{document}

4
doc/src/Errors_messages.rst
View File

@ -502,10 +502,10 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Bond/react: Unknown section in map file*
Please ensure reaction map files are properly formatted.
*Bond/react: Atom affected by reaction too close to template edge*
*Bond/react: Atom/Bond type affected by reaction too close to template edge*
This means an atom which changes type or connectivity during the
reaction is too close to an 'edge' atom defined in the map
file. This could cause incorrect assignment of bonds, angle, etc.
file. This could cause incorrect assignment of bonds, angle, etc.
Generally, this means you must include more atoms in your templates,
such that there are at least two atoms between each atom involved in
the reaction and an edge atom.

12
doc/src/Howto_cmake.rst
View File

@ -191,19 +191,19 @@ You start the command ``ccmake ../cmake`` in the ``build`` folder.
.. list-table::
* - .. figure:: JPG/ccmake-initial.png
:target: JPG/ccmake-initial.png
:scale: 33%
:align: center
Initial ``ccmake`` screen
- .. figure:: JPG/ccmake-config.png
:target: JPG/ccmake-config.png
:scale: 33%
:align: center
Configure output of ``ccmake``
- .. figure:: JPG/ccmake-options.png
:target: JPG/ccmake-options.png
:scale: 33%
:align: center
Options screen of ``ccmake``
@ -236,19 +236,19 @@ not required, it can also be entered from the GUI.
.. list-table::
* - .. figure:: JPG/cmake-gui-initial.png
:target: JPG/cmake-gui-initial.png
:scale: 40%
:align: center
Initial ``cmake-gui`` screen
- .. figure:: JPG/cmake-gui-popup.png
:target: JPG/cmake-gui-popup.png
:scale: 60%
:align: center
Generator selection in ``cmake-gui``
- .. figure:: JPG/cmake-gui-options.png
:target: JPG/cmake-gui-options.png
:scale: 40%
:align: center
Options screen of ``cmake-gui``

126
doc/src/Howto_couple.rst
View File

@ -12,96 +12,52 @@ LAMMPS can be coupled to other codes in at least 4 ways. Each has
advantages and disadvantages, which you will have to think about in the
context of your application.
----------
1. Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During timestepping,
the fix is invoked, and can make library calls to the other code,
which has been linked to LAMMPS as a library. This is the way how the
:ref:`LATTE <PKG-LATTE>` package, which performs density-functional
tight-binding calculations using the `LATTE software <https://github.com/lanl/LATTE>`_
to compute forces, is hooked to LAMMPS.
See the :doc:`fix latte <fix_latte>` command for more details.
Also see the :doc:`Modify <Modify>` doc pages for info on how to
add a new fix to LAMMPS.
(1) Define a new :doc:`fix <fix>` command that calls the other code. In
this scenario, LAMMPS is the driver code. During its timestepping,
the fix is invoked, and can make library calls to the other code,
which has been linked to LAMMPS as a library. This is the way the
`POEMS <poems_>`_ package that performs constrained rigid-body motion on
groups of atoms is hooked to LAMMPS. See the :doc:`fix poems <fix_poems>` command for more details. See the
:doc:`Modify <Modify>` doc pages for info on how to add a new fix to
LAMMPS.
.. spacer
.. _poems: http://www.rpi.edu/~anderk5/lab
2. Define a new LAMMPS command that calls the other code. This is
conceptually similar to method (1), but in this case LAMMPS and the
other code are on a more equal footing. Note that now the other code
is not called during the timestepping of a LAMMPS run, but between
runs. The LAMMPS input script can be used to alternate LAMMPS runs
with calls to the other code, invoked via the new command. The
:doc:`run <run>` command facilitates this with its *every* option,
which makes it easy to run a few steps, invoke the command, run a few
steps, invoke the command, etc.
----------
In this scenario, the other code can be called as a library, as in
1., or it could be a stand-alone code, invoked by a system() call
made by the command (assuming your parallel machine allows one or
more processors to start up another program). In the latter case the
stand-alone code could communicate with LAMMPS through files that the
command writes and reads.
(2) Define a new LAMMPS command that calls the other code. This is
conceptually similar to method (1), but in this case LAMMPS and the
other code are on a more equal footing. Note that now the other code
is not called during the timestepping of a LAMMPS run, but between
runs. The LAMMPS input script can be used to alternate LAMMPS runs
with calls to the other code, invoked via the new command. The
:doc:`run <run>` command facilitates this with its *every* option, which
makes it easy to run a few steps, invoke the command, run a few steps,
invoke the command, etc.
See the :doc:`Modify command <Modify_command>` doc page for info on how
to add a new command to LAMMPS.
In this scenario, the other code can be called as a library, as in
(1), or it could be a stand-alone code, invoked by a system() call
made by the command (assuming your parallel machine allows one or more
processors to start up another program). In the latter case the
stand-alone code could communicate with LAMMPS through files that the
command writes and reads.
.. spacer
See the :doc:`Modify command <Modify_command>` doc page for info on how
to add a new command to LAMMPS.
3. Use LAMMPS as a library called by another code. In this case the
other code is the driver and calls LAMMPS as needed. Or a wrapper
code could link and call both LAMMPS and another code as libraries.
Again, the :doc:`run <run>` command has options that allow it to be
invoked with minimal overhead (no setup or clean-up) if you wish to
do multiple short runs, driven by another program. Details about
using the library interface are given in the :doc:`library API
<pg_library>` documentation.
----------
.. spacer
(3) Use LAMMPS as a library called by another code. In this case the
other code is the driver and calls LAMMPS as needed. Or a wrapper
code could link and call both LAMMPS and another code as libraries.
Again, the :doc:`run <run>` command has options that allow it to be
invoked with minimal overhead (no setup or clean-up) if you wish to do
multiple short runs, driven by another program.
Examples of driver codes that call LAMMPS as a library are included in
the examples/COUPLE directory of the LAMMPS distribution; see
examples/COUPLE/README for more details:
* simple: simple driver programs in C++ and C which invoke LAMMPS as a
library
* plugin: simple driver program in C which invokes LAMMPS as a plugin
from a shared library.
* lammps_quest: coupling of LAMMPS and `Quest <quest_>`_, to run classical
MD with quantum forces calculated by a density functional code
* lammps_spparks: coupling of LAMMPS and `SPPARKS <spparks_>`_, to couple
a kinetic Monte Carlo model for grain growth using MD to calculate
strain induced across grain boundaries
.. _quest: http://dft.sandia.gov/Quest
.. _spparks: http://www.sandia.gov/~sjplimp/spparks.html
The :doc:`Build basics <Build_basics>` doc page describes how to build
LAMMPS as a library. Once this is done, you can interface with LAMMPS
either via C++, C, Fortran, or Python (or any other language that
supports a vanilla C-like interface). For example, from C++ you could
create one (or more) "instances" of LAMMPS, pass it an input script to
process, or execute individual commands, all by invoking the correct
class methods in LAMMPS. From C or Fortran you can make function
calls to do the same things. See the :doc:`Python <Python_head>` doc
pages for a description of the Python wrapper provided with LAMMPS
that operates through the LAMMPS library interface.
The files src/library.cpp and library.h contain the C-style interface
to LAMMPS. See the :doc:`Howto library <Howto_library>` doc page for a
description of the interface and how to extend it for your needs.
Note that the lammps_open() function that creates an instance of
LAMMPS takes an MPI communicator as an argument. This means that
instance of LAMMPS will run on the set of processors in the
communicator. Thus the calling code can run LAMMPS on all or a subset
of processors. For example, a wrapper script might decide to
alternate between LAMMPS and another code, allowing them both to run
on all the processors. Or it might allocate half the processors to
LAMMPS and half to the other code and run both codes simultaneously
before syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
----------
(4) Couple LAMMPS with another code in a client/server mode. This is
described on the :doc:`Howto client/server <Howto_client_server>` doc
page.
4. Couple LAMMPS with another code in a client/server mode. This is
described on the :doc:`Howto client/server <Howto_client_server>` doc
page.

261
doc/src/Howto_library.rst
View File

@ -2,241 +2,36 @@ Library interface to LAMMPS
===========================
As described on the :doc:`Build basics <Build_basics>` doc page, LAMMPS
can be built as a library, so that it can be called by another code,
used in a :doc:`coupled manner <Howto_couple>` with other codes, or
driven through a :doc:`Python interface <Python_head>`.
can be built as a static or shared library, so that it can be called by
another code, used in a :doc:`coupled manner <Howto_couple>` with other
codes, or driven through a :doc:`Python interface <Python_head>`.
All of these methodologies use a C-style interface to LAMMPS that is
provided in the files src/library.cpp and src/library.h. The
functions therein have a C-style argument list, but contain C++ code
you could write yourself in a C++ application that was invoking LAMMPS
directly. The C++ code in the functions illustrates how to invoke
internal LAMMPS operations. Note that LAMMPS classes are defined
within a LAMMPS namespace (LAMMPS_NS) if you use them from another C++
application.
At the core of LAMMPS is the ``LAMMPS`` class which encapsulates the
state of the simulation program through the state of the various class
instances that it is composed of. So a calculation using LAMMPS
requires to create an instance of the ``LAMMPS`` class and then send it
(text) commands, either individually or from a file, or perform other
operations that modify the state stored inside that instance or drive
simulations. This is essentially what the ``src/main.cpp`` file does
as well for the standalone LAMMPS executable with reading commands
either from an input file or stdin.
The examples/COUPLE and python/examples directories have example C++
and C and Python codes which show how a driver code can link to LAMMPS
as a library, run LAMMPS on a subset of processors, grab data from
LAMMPS, change it, and put it back into LAMMPS.
Creating a LAMMPS instance can be done by using C++ code directly or
through a C-style interface library to LAMMPS that is provided in the
files ``src/library.cpp`` and ``library.h``. This
:ref:`C language API <lammps_c_api>`, can be used from C and C++,
and is also the basis for the :doc:`Python <pg_python>` and
:doc:`Fortran <pg_fortran>` interfaces or wrappers included in the
LAMMPS source code.
Thread-safety
-------------
The ``examples/COUPLE`` and ``python/examples`` directories contain some
example programs written in C++, C, Fortran, and Python, which show how
a driver code can link to LAMMPS as a library, run LAMMPS on a subset of
processors (so the others are available to run some other code
concurrently), grab data from LAMMPS, change it, and send it back into
LAMMPS.
LAMMPS has not initially been conceived as a thread-safe program, but
over the years changes have been applied to replace operations that
collide with creating multiple LAMMPS instances from multiple-threads
of the same process with thread-safe alternatives. This primarily
applies to the core LAMMPS code and less so on add-on packages, especially
when those packages require additional code in the *lib* folder,
interface LAMMPS to Fortran libraries, or the code uses static variables
(like the USER-COLVARS package.
A detailed documentation of the available APIs and examples of how to
use them can be found in the :doc:`Programmer Documentation
<pg_library>` section of this manual.
Another major issue to deal with is to correctly handle MPI. Creating
a LAMMPS instance requires passing an MPI communicator, or it assumes
the MPI_COMM_WORLD communicator, which spans all MPI processor ranks.
When creating multiple LAMMPS object instances from different threads,
this communicator has to be different for each thread or else collisions
can happen, or it has to be guaranteed, that only one thread at a time
is active. MPI communicators, however, are not a problem, if LAMMPS is
compiled with the MPI STUBS library, which implies that there is no MPI
communication and only 1 MPI rank.
Provided APIs
-------------
The file src/library.cpp contains the following functions for creating
and destroying an instance of LAMMPS and sending it commands to
execute. See the documentation in the src/library.cpp file for
details.
.. note::
You can write code for additional functions as needed to define
how your code talks to LAMMPS and add them to src/library.cpp and
src/library.h, as well as to the :doc:`Python interface <Python_head>`.
The added functions can access or change any internal LAMMPS data you
wish.
.. code-block:: c
void lammps_open(int, char **, MPI_Comm, void **)
void lammps_open_no_mpi(int, char **, void **)
void lammps_close(void *)
int lammps_version(void *)
void lammps_file(void *, char *)
char *lammps_command(void *, char *)
void lammps_commands_list(void *, int, char **)
void lammps_commands_string(void *, char *)
void lammps_free(void *)
The lammps_open() function is used to initialize LAMMPS, passing in a
list of strings as if they were :doc:`command-line arguments <Run_options>` when LAMMPS is run in stand-alone mode
from the command line, and a MPI communicator for LAMMPS to run under.
It returns a ptr to the LAMMPS object that is created, and which is
used in subsequent library calls. The lammps_open() function can be
called multiple times, to create multiple instances of LAMMPS.
LAMMPS will run on the set of processors in the communicator. This
means the calling code can run LAMMPS on all or a subset of
processors. For example, a wrapper script might decide to alternate
between LAMMPS and another code, allowing them both to run on all the
processors. Or it might allocate half the processors to LAMMPS and
half to the other code and run both codes simultaneously before
syncing them up periodically. Or it might instantiate multiple
instances of LAMMPS to perform different calculations.
The lammps_open_no_mpi() function is similar except that no MPI
communicator is passed from the caller. Instead, MPI_COMM_WORLD is
used to instantiate LAMMPS, and MPI is initialized if necessary.
The lammps_close() function is used to shut down an instance of LAMMPS
and free all its memory.
The lammps_version() function can be used to determined the specific
version of the underlying LAMMPS code. This is particularly useful
when loading LAMMPS as a shared library via dlopen(). The code using
the library interface can than use this information to adapt to
changes to the LAMMPS command syntax between versions. The returned
LAMMPS version code is an integer (e.g. 2 Sep 2015 results in
20150902) that grows with every new LAMMPS version.
The lammps_file(), lammps_command(), lammps_commands_list(), and
lammps_commands_string() functions are used to pass one or more
commands to LAMMPS to execute, the same as if they were coming from an
input script.
Via these functions, the calling code can read or generate a series of
LAMMPS commands one or multiple at a time and pass it through the library
interface to setup a problem and then run it in stages. The caller
can interleave the command function calls with operations it performs,
calls to extract information from or set information within LAMMPS, or
calls to another code's library.
The lammps_file() function passes the filename of an input script.
The lammps_command() function passes a single command as a string.
The lammps_commands_list() function passes multiple commands in a
char\*\* list. In both lammps_command() and lammps_commands_list(),
individual commands may or may not have a trailing newline. The
lammps_commands_string() function passes multiple commands
concatenated into one long string, separated by newline characters.
In both lammps_commands_list() and lammps_commands_string(), a single
command can be spread across multiple lines, if the last printable
character of all but the last line is "&", the same as if the lines
appeared in an input script.
The lammps_free() function is a clean-up function to free memory that
the library allocated previously via other function calls. See
comments in src/library.cpp file for which other functions need this
clean-up.
The file src/library.cpp also contains these functions for extracting
information from LAMMPS and setting value within LAMMPS. Again, see
the documentation in the src/library.cpp file for details, including
which quantities can be queried by name:
.. code-block:: c
int lammps_extract_setting(void *, char *)
void *lammps_extract_global(void *, char *)
void lammps_extract_box(void *, double *, double *,
double *, double *, double *, int *, int *)
void *lammps_extract_atom(void *, char *)
void *lammps_extract_compute(void *, char *, int, int)
void *lammps_extract_fix(void *, char *, int, int, int, int)
void *lammps_extract_variable(void *, char *, char *)
The extract_setting() function returns info on the size
of data types (e.g. 32-bit or 64-bit atom IDs) used
by the LAMMPS executable (a compile-time choice).
The other extract functions return a pointer to various global or
per-atom quantities stored in LAMMPS or to values calculated by a
compute, fix, or variable. The pointer returned by the
extract_global() function can be used as a permanent reference to a
value which may change. For the extract_atom() method, see the
extract() method in the src/atom.cpp file for a list of valid per-atom
properties. New names could easily be added if the property you want
is not listed. For the other extract functions, the underlying
storage may be reallocated as LAMMPS runs, so you need to re-call the
function to assure a current pointer or returned value(s).
.. code-block:: c
double lammps_get_thermo(void *, char *)
int lammps_get_natoms(void *)
int lammps_set_variable(void *, char *, char *)
void lammps_reset_box(void *, double *, double *, double, double, double)
The lammps_get_thermo() function returns the current value of a thermo
keyword as a double precision value.
The lammps_get_natoms() function returns the total number of atoms in
the system and can be used by the caller to allocate memory for the
lammps_gather_atoms() and lammps_scatter_atoms() functions.
The lammps_set_variable() function can set an existing string-style
variable to a new string value, so that subsequent LAMMPS commands can
access the variable.
The lammps_reset_box() function resets the size and shape of the
simulation box, e.g. as part of restoring a previously extracted and
saved state of a simulation.
.. code-block:: c
void lammps_gather_atoms(void *, char *, int, int, void *)
void lammps_gather_atoms_concat(void *, char *, int, int, void *)
void lammps_gather_atoms_subset(void *, char *, int, int, int, int *, void *)
void lammps_scatter_atoms(void *, char *, int, int, void *)
void lammps_scatter_atoms_subset(void *, char *, int, int, int, int *, void *)
The gather functions 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.
.. warning::
These functions are not compatible with the
-DLAMMPS_BIGBIG setting when compiling LAMMPS. Dummy functions
that result in an error message and abort will be substituted
instead of resulting in random crashes and memory corruption.
The lammps_gather_atoms() function does this for all N atoms in the
system, ordered by atom ID, from 1 to N. The
lammps_gather_atoms_concat() function does it for all N atoms, but
simply concatenates the subset of atoms owned by each processor. The
resulting vector is not ordered by atom ID. Atom IDs can be requested
by the same function if the caller needs to know the ordering. The
lammps_gather_subset() function allows the caller to request values
for only a subset of atoms (identified by ID).
For all 3 gather function, per-atom image flags can be retrieved in 2 ways.
If the count is specified as 1, they are returned
in a packed format with all three image flags stored in a single integer.
If the count is specified as 3, the values are unpacked into xyz flags
by the library before returning them.
The lammps_scatter_atoms() function takes a list of values for all N
atoms in the system, ordered by atom ID, from 1 to N, and assigns
those values to each atom in the system. The
lammps_scatter_atoms_subset() function takes a subset of IDs as an
argument and only scatters those values to the owning atoms.
.. code-block:: c
void lammps_create_atoms(void *, int, tagint *, int *, double *, double *,
imageint *, int)
The lammps_create_atoms() function takes a list of N atoms as input
with atom types and coords (required), an optionally atom IDs and
velocities and image flags. It uses the coords of each atom to assign
it as a new atom to the processor that owns it. This function is
useful to add atoms to a simulation or (in tandem with
lammps_reset_box()) to restore a previously extracted and saved state
of a simulation. Additional properties for the new atoms can then be
assigned via the lammps_scatter_atoms() or lammps_extract_atom()
functions.

6
doc/src/Install_linux.rst
View File

@ -79,13 +79,13 @@ To get a copy of the current potentials files:
which will download the potentials files to
``/usr/share/lammps-stable/potentials``. The ``lmp_stable`` binary is
hard-coded to look for potential files in this directory (it does not
use the `LAMMPS_POTENTIALS` environment variable, as described
use the ``LAMMPS_POTENTIALS`` environment variable, as described
in :doc:`pair_coeff <pair_coeff>` command).
The ``lmp_stable`` binary is built with the :ref:`KIM package <kim>` which
results in the above command also installing the `kim-api` binaries when LAMMPS
results in the above command also installing the ``kim-api`` binaries when LAMMPS
is installed. In order to use potentials from `openkim.org <openkim_>`_, you
can install the `openkim-models` package
can install the ``openkim-models`` package
.. code-block:: bash

1
doc/src/Intro_website.rst
View File

@ -23,7 +23,6 @@ this Intr are included in this list.
* `Mail list <https://lammps.sandia.gov/mail.html>`_
* `Workshops <https://lammps.sandia.gov/workshops.html>`_
* `Tutorials <https://lammps.sandia.gov/tutorials.html>`_
* `Developer guide <https://lammps.sandia.gov/Developer.pdf>`_
* `Pre- and post-processing tools for LAMMPS <https://lammps.sandia.gov/prepost.html>`_
* `Other software usable with LAMMPS <https://lammps.sandia.gov/offsite.html>`_

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 245 KiB

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

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

18
doc/src/Manual.rst
View File

@ -27,8 +27,7 @@ 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:`Manual build <Manual_build>` doc page.
There is also a `Developer.pdf <Developer.pdf>`_ document which gives
a brief description of the basic code structure of LAMMPS.
The manual is split into two parts: 1) User documentation and 2) Programmer documentation.
----------
@ -55,11 +54,24 @@ every LAMMPS command.
Howto
Examples
Tools
Modify
Python_head
Errors
Manual_build
.. _programmer_documentation:
.. toctree::
:maxdepth: 2
:numbered: 3
:caption: Programmer Documentation
:name: progdoc
:includehidden:
pg_library
Modify
pg_developer
.. pg_modify
.. pg_base
.. toctree::
:caption: Index
:name: index

15
doc/src/Manual_build.rst
View File

@ -14,7 +14,6 @@ files. Here is a list with descriptions:
lammps.1 # man page for the lammps command
msi2lmp.1 # man page for the msi2lmp command
Manual.pdf # large PDF version of entire manual
Developer.pdf # small PDF with info about how LAMMPS is structured
LAMMPS.epub # Manual in ePUB e-book format
LAMMPS.mobi # Manual in MOBI e-book format
docenv # virtualenv folder for processing the manual sources
@ -35,7 +34,7 @@ of two ways:
a. You can "fetch" the current HTML and PDF files from the LAMMPS web
site. Just type ``make fetch``. This should download a html_www
directory and Manual_www.pdf/Developer_www.pdf files. Note that if
directory and a Manual_www.pdf file. Note that if
new LAMMPS features have been added more recently than the date of
your LAMMPS version, the fetched documentation will include those
changes (but your source code will not, unless you update your local
@ -49,6 +48,11 @@ b. You can build the HTML or PDF files yourself, by typing ``make html``
only once, unless you type ``make clean-all``. After that, viewing and
processing of the documentation can be done without internet access.
A current version of the manual (latest patch release, aka unstable branch)
is is available online at: `https://lammps.sandia.gov/doc/Manual.html <https://lammps.sandia.gov/doc/Manual.html>`_
A version of the manual corresponding to the ongoing development
(aka master branch) is available online at: `https://docs.lammps.org/ <https://docs.lammps.org/>`_
----------
The generation of all documentation is managed by the Makefile in the
@ -58,10 +62,9 @@ available:
.. code-block:: bash
make html # generate HTML in html dir using Sphinx
make pdf # generate 2 PDF files (Manual.pdf,Developer.pdf)
# in doc dir via htmldoc and pdflatex
make fetch # fetch HTML doc pages and 2 PDF files from web site
# as a tarball and unpack into html dir and 2 PDFs
make pdf # generate PDF as Manual.pdf using Sphinx and pdflatex
make fetch # fetch HTML doc pages and PDF file from web site
# as a tarball and unpack into html dir and PDF
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert

4
doc/src/Modify.rst
View File

@ -1,5 +1,5 @@
Modify & extend LAMMPS
**********************
Modifying & extending LAMMPS
****************************
LAMMPS is designed in a modular fashion so as to be easy to modify and
extend with new functionality. In fact, about 95% of its source code

2
doc/src/Packages_details.rst
View File

@ -1692,7 +1692,7 @@ USER-MEAMC package
**Contents:**
A pair style for the modified embedded atom (MEAM) potential
translated from the Fortran version in the (obsolete) "MEAM" package
translated from the Fortran version in the (obsolete) MEAM package
to plain C++. The USER-MEAMC fully replaces the MEAM package, which
has been removed from LAMMPS after the 12 December 2018 version.

2
doc/src/Packages_user.rst
View File

@ -6,7 +6,7 @@ name gives more details.
User packages have been contributed by users, and begin with the
"user" prefix. If a contribution is a single command (single file),
it is typically in the user-misc package. User packages don't
it is typically in the USER-MISC package. User packages don't
necessarily meet the requirements of the :doc:`standard packages <Packages_standard>`. This means the developers will try
to keep things working and usually can answer technical questions
about compiling the package. If you have problems using a specific

16
doc/src/Tools.rst
View File

@ -89,7 +89,6 @@ Miscellaneous tools
:columns: 6
* :ref:`CMake <cmake>`
* :ref:`doxygen <doxygen>`
* :ref:`emacs <emacs>`
* :ref:`i-pi <ipi>`
* :ref:`kate <kate>`
@ -254,21 +253,6 @@ The tool is authored by Xiaowang Zhou (Sandia), xzhou at sandia.gov.
----------
.. _doxygen:
doxygen tool
--------------------------
The tools/doxygen directory contains a shell script called
doxygen.sh which can generate a call graph and API lists using
the `Doxygen software <http://doxygen.org>`_.
See the included README file for details.
The tool is authored by Nandor Tamaskovics, numericalfreedom at googlemail.com.
----------
.. _drude:
drude tool

54
doc/src/fix_bond_react.rst
View File

@ -14,19 +14,22 @@ Syntax
react react-ID react-group-ID Nevery Rmin Rmax template-ID(pre-reacted) template-ID(post-reacted) map_file individual_keyword values ...
...
* ID, group-ID are documented in :doc:`fix <fix>` command. Group-ID is ignored.
* ID, group-ID are documented in :doc:`fix <fix>` command.
* bond/react = style name of this fix command
* the common keyword/values may be appended directly after 'bond/react'
* this applies to all reaction specifications (below)
* common_keyword = *stabilization*
* common_keyword = *stabilization* or *reset_mol_ids*
.. parsed-literal::
*stabilization* values = *no* or *yes* *group-ID* *xmax*
*no* = no reaction site stabilization
*no* = no reaction site stabilization (default)
*yes* = perform reaction site stabilization
*group-ID* = user-assigned prefix for the dynamic group of atoms not currently involved in a reaction
*xmax* = xmax value that is used by an internally-created :doc:`nve/limit <fix_nve_limit>` integrator
*reset_mol_ids* values = *yes* or *no*
*yes* = update molecule IDs based on new global topology (default)
*no* = do not update molecule IDs
* react = mandatory argument indicating new reaction specification
* react-ID = user-assigned name for the reaction
@ -50,9 +53,9 @@ Syntax
*stabilize_steps* value = timesteps
timesteps = number of timesteps to apply the internally-created :doc:`nve/limit <fix_nve_limit>` fix to reacting atoms
*update_edges* value = *none* or *charges* or *custom*
none = do not update topology near the edges of reaction templates
charges = update atomic charges of all atoms in reaction templates
custom = force the update of user-specified atomic charges
*none* = do not update topology near the edges of reaction templates
*charges* = update atomic charges of all atoms in reaction templates
*custom* = force the update of user-specified atomic charges
Examples
""""""""
@ -154,6 +157,13 @@ due to the internal dynamic grouping performed by fix bond/react.
If the group-ID is an existing static group, react-group-IDs
should also be specified as this static group, or a subset.
The *reset_mol_ids* keyword invokes the :doc:`reset_mol_ids <reset_mol_ids>`
command after a reaction occurs, to ensure that molecule IDs are
consistent with the new bond topology. The group-ID used for
:doc:`reset_mol_ids <reset_mol_ids>` is the group-ID for this fix.
Resetting molecule IDs is necessarily a global operation, and so can
be slow for very large systems.
The following comments pertain to each *react* argument (in other
words, can be customized for each reaction, or reaction step):
@ -203,9 +213,10 @@ surrounding topology. As described below, the bonding atom pairs of
the pre-reacted template are specified by atom ID in the map file. The
pre-reacted molecule template should contain as few atoms as possible
while still completely describing the topology of all atoms affected
by the reaction. For example, if the force field contains dihedrals,
the pre-reacted template should contain any atom within three bonds of
reacting atoms.
by the reaction (which includes all atoms that change atom type or
connectivity, and all bonds that change bond type). For example, if
the force field contains dihedrals, the pre-reacted template should
contain any atom within three bonds of reacting atoms.
Some atoms in the pre-reacted template that are not reacting may have
missing topology with respect to the simulation. For example, the
@ -300,8 +311,8 @@ either 'none' or 'charges.' Further details are provided in the
discussion of the 'update_edges' keyword. The fifth optional section
begins with the keyword 'Constraints' and lists additional criteria
that must be satisfied in order for the reaction to occur. Currently,
there are four types of constraints available, as discussed below:
'distance', 'angle', 'dihedral', and 'arrhenius'.
there are five types of constraints available, as discussed below:
'distance', 'angle', 'dihedral', 'arrhenius', and 'rmsd'.
A sample map file is given below:
@ -421,6 +432,25 @@ temperature calculations. A uniform random number between 0 and 1 is
generated using *seed*\ ; if this number is less than the result of the
Arrhenius equation above, the reaction is permitted to occur.
The constraint of type 'rmsd' has the following syntax:
.. parsed-literal::
rmsd *RMSDmax* *molfragment*
where 'rmsd' is the required keyword, and *RMSDmax* is the maximum
root-mean-square deviation between atom positions of the pre-reaction
template and the local reaction site (distance units), after optimal
translation and rotation of the pre-reaction template. Optionally, the
name of a molecule fragment (of the pre-reaction template) can be
specified by *molfragment*\ . If a molecule fragment is specified,
only atoms that are part of this molecule fragment are used to
determine the RMSD. A molecule fragment must have been defined in the
:doc:`molecule <molecule>` command for the pre-reaction template. For
example, the molecule fragment could consist of only the backbone
atoms of a polymer chain. This constraint can be used to enforce a
specific relative position and orientation between reacting molecules.
Once a reaction site has been successfully identified, data structures
within LAMMPS that store bond topology are updated to reflect the
post-reacted molecule template. All force fields with fixed bonds,
@ -554,7 +584,7 @@ Default
"""""""
The option defaults are stabilization = no, prob = 1.0, stabilize_steps = 60,
update_edges = none
reset_mol_ids = yes, update_edges = none
----------

9
doc/src/pair_coeff.rst
View File

@ -110,8 +110,8 @@ location specified. E.g. if the file is specified as "niu3.eam", it
is looked for in the current working directory. If it is specified as
"../potentials/niu3.eam", then it is looked for in the potentials
directory, assuming it is a sister directory of the current working
directory. If the file is not found, it is then looked for in the
directory specified by the LAMMPS_POTENTIALS environment variable.
directory. If the file is not found, it is then looked for in one of
the directories specified by the ``LAMMPS_POTENTIALS`` environment variable.
Thus if this is set to the potentials directory in the LAMMPS distribution,
then you can use those files from anywhere on your system, without
copying them into your working directory. Environment variables are
@ -136,6 +136,11 @@ Windows:
% set LAMMPS_POTENTIALS="C:\\Path to LAMMPS\\Potentials"
The ``LAMMPS_POTENTIALS`` environment variable may contain paths
to multiple folders, if they are separated by ";" on Windows and
":" on all other operating systems, just like the ``PATH`` and
similar environment variables.
----------
The alphabetic list of pair styles defined in LAMMPS is given on the

4
doc/src/pair_comb.rst
View File

@ -129,10 +129,10 @@ For style *comb3*\ , in addition to ffield.comb3, a special parameter
file, *lib.comb3*\ , that is exclusively used for C/O/H systems, will be
automatically loaded if carbon atom is detected in LAMMPS input
structure. This file must be in your working directory or in the
directory pointed to by the environment variable LAMMPS_POTENTIALS, as
directories listed in the environment variable ``LAMMPS_POTENTIALS``, as
described on the :doc:`pair_coeff <pair_coeff>` command doc page.
Keyword *polar* indicates whether the force field includes
The keyword *polar* indicates whether the force field includes
the atomic polarization. Since the equilibration of the polarization
has not yet been implemented, it can only set polar_off at present.

2
doc/src/pair_cosine_squared.rst
View File

@ -107,7 +107,7 @@ These pair styles can only be used via the *pair* keyword of the
Restrictions
""""""""""""
The *cosine/squared* style is part of the "USER-MISC" package. It is only
The *cosine/squared* style is part of the USER-MISC package. It is only
enabled if LAMMPS is build with that package. See the :doc:`Build package <Build_package>` doc page for more info.
Related commands

2
doc/src/pair_coul_diel.rst
View File

@ -95,7 +95,7 @@ This pair style can only be used via the *pair* keyword of the
Restrictions
""""""""""""
This style is part of the "USER-MISC" package. It is only enabled if
This style is part of the USER-MISC package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
Related commands

2
doc/src/pair_coul_slater.rst
View File

@ -95,7 +95,7 @@ Restrictions
The *coul/slater/long* style requires the long-range solvers included in the KSPACE package.
These styles are part of the "USER-MISC" package. They are only enabled if
These styles are part of the USER-MISC package. They are only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` doc page for more info.
Related commands

14
doc/src/pair_gauss.rst
View File

@ -164,8 +164,18 @@ heading) the following commands could be included in an input script:
Restrictions
""""""""""""
The *gauss/cut* style is part of the "user-misc" package. It is only
enabled if LAMMPS is build with that package. See the :doc:`Build package <Build_package>` doc page for more info.
The *gauss/cut* style is part of the USER-MISC package. It is only
enabled if LAMMPS is build with that package. See the :doc:`Build
package <Build_package>` doc page for more info.
The *gauss* style does not apply :doc:`special_bonds <special_bonds>`
factors. When using this pair style on a system that has bonds, the
special_bonds factors, if using the default setting of 0.0, may need to
be adjusted to some very small number (e.g. 1.0e-100), so that those
special pairs are not completely excluded from the neighbor lists, but
won't contribute forces or energies from styles (e.g. when used in
combination with a :doc:`hybrid pair style <pair_hybrid>`) that do
apply those factors.
Related commands
""""""""""""""""

143
doc/src/pair_granular.rst
View File

@ -93,7 +93,7 @@ on particle *i* due to contact with particle *j* is given by:
.. math::
\mathbf{F}_{ne, Hooke} = k_N \delta_{ij} \mathbf{n}
\mathbf{F}_{ne, Hooke} = k_n \delta_{ij} \mathbf{n}
Where :math:`\delta_{ij} = R_i + R_j - \|\mathbf{r}_{ij}\|` is the particle
overlap, :math:`R_i, R_j` are the particle radii, :math:`\mathbf{r}_{ij} = \mathbf{r}_i - \mathbf{r}_j` is the vector separating the two
@ -106,7 +106,7 @@ For the *hertz* model, the normal component of force is given by:
.. math::
\mathbf{F}_{ne, Hertz} = k_N R_{eff}^{1/2}\delta_{ij}^{3/2} \mathbf{n}
\mathbf{F}_{ne, Hertz} = k_n R_{eff}^{1/2}\delta_{ij}^{3/2} \mathbf{n}
Here, :math:`R_{eff} = \frac{R_i R_j}{R_i + R_j}` is the effective
radius, denoted for simplicity as *R* from here on. For *hertz*\ , the
@ -123,7 +123,7 @@ Here, :math:`E_{eff} = E = \left(\frac{1-\nu_i^2}{E_i} + \frac{1-\nu_j^2}{E_j}\r
modulus, with :math:`\nu_i, \nu_j` the Poisson ratios of the particles of
types *i* and *j*\ . Note that if the elastic modulus and the shear
modulus of the two particles are the same, the *hertz/material* model
is equivalent to the *hertz* model with :math:`k_N = 4/3 E_{eff}`
is equivalent to the *hertz* model with :math:`k_n = 4/3 E_{eff}`
The *dmt* model corresponds to the
:ref:`(Derjaguin-Muller-Toporov) <DMT1975>` cohesive model, where the force
@ -140,7 +140,7 @@ where the force is computed as:
\mathbf{F}_{ne, jkr} = \left(\frac{4Ea^3}{3R} - 2\pi a^2\sqrt{\frac{4\gamma E}{\pi a}}\right)\mathbf{n}
Here, *a* is the radius of the contact zone, related to the overlap
Here, :math:`a` is the radius of the contact zone, related to the overlap
:math:`\delta` according to:
.. math::
@ -167,7 +167,7 @@ following general form:
\mathbf{F}_{n,damp} = -\eta_n \mathbf{v}_{n,rel}
Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot \mathbf{n} \mathbf{n}` is the component of relative velocity along
Here, :math:`\mathbf{v}_{n,rel} = (\mathbf{v}_j - \mathbf{v}_i) \cdot \mathbf{n}\ \mathbf{n}` is the component of relative velocity along
:math:`\mathbf{n}`.
The optional *damping* keyword to the *pair_coeff* command followed by
@ -259,7 +259,9 @@ tangential model choices and their expected parameters are as follows:
1. *linear_nohistory* : :math:`x_{\gamma,t}`, :math:`\mu_s`
2. *linear_history* : :math:`k_t`, :math:`x_{\gamma,t}`, :math:`\mu_s`
3. *mindlin* : :math:`k_t` or NULL, :math:`x_{\gamma,t}`, :math:`\mu_s`
4. *mindlin_rescale* : :math:`k_t` or NULL, :math:`x_{\gamma,t}`, :math:`\mu_s`
4. *mindlin/force* : :math:`k_t` or NULL, :math:`x_{\gamma,t}`, :math:`\mu_s`
5. *mindlin_rescale* : :math:`k_t` or NULL, :math:`x_{\gamma,t}`, :math:`\mu_s`
6. *mindlin_rescale/force* : :math:`k_t` or NULL, :math:`x_{\gamma,t}`, :math:`\mu_s`
Here, :math:`x_{\gamma,t}` is a dimensionless multiplier for the normal
damping :math:`\eta_n` that determines the magnitude of the tangential
@ -268,11 +270,11 @@ coefficient, and :math:`k_t` is the tangential stiffness coefficient.
For *tangential linear_nohistory*, a simple velocity-dependent Coulomb
friction criterion is used, which mimics the behavior of the *pair
gran/hooke* style. The tangential force (\mathbf{F}_t\) is given by:
gran/hooke* style. The tangential force :math:`\mathbf{F}_t` is given by:
.. math::
\mathbf{F}_t = -min(\mu_t F_{n0}, \|\mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
\mathbf{F}_t = -\min(\mu_t F_{n0}, \|\mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
The tangential damping force :math:`\mathbf{F}_\mathrm{t,damp}` is given by:
@ -294,8 +296,8 @@ keyword also affects the tangential damping. The parameter
literature use :math:`x_{\gamma,t} = 1` (:ref:`Marshall <Marshall2009>`,
:ref:`Tsuji et al <Tsuji1992>`, :ref:`Silbert et al <Silbert2001>`). The relative
tangential velocity at the point of contact is given by
:math:`\mathbf{v}_{t, rel} = \mathbf{v}_{t} - (R_i\Omega_i + R_j\Omega_j) \times \mathbf{n}`, where :math:`\mathbf{v}_{t} = \mathbf{v}_r - \mathbf{v}_r\cdot\mathbf{n}{n}`,
:math:`\mathbf{v}_r = \mathbf{v}_j - \mathbf{v}_i`.
:math:`\mathbf{v}_{t, rel} = \mathbf{v}_{t} - (R_i\mathbf{\Omega}_i + R_j\mathbf{\Omega}_j) \times \mathbf{n}`, where :math:`\mathbf{v}_{t} = \mathbf{v}_r - \mathbf{v}_r\cdot\mathbf{n}\ \mathbf{n}`,
:math:`\mathbf{v}_r = \mathbf{v}_j - \mathbf{v}_i` .
The direction of the applied force is :math:`\mathbf{t} = \mathbf{v_{t,rel}}/\|\mathbf{v_{t,rel}}\|` .
The normal force value :math:`F_{n0}` used to compute the critical force
@ -314,21 +316,24 @@ form:
.. math::
F_{n0} = \|\mathbf{F}_ne + 2 F_{pulloff}\|
F_{n0} = \|\mathbf{F}_{ne} + 2 F_{pulloff}\|
Where :math:`F_{pulloff} = 3\pi \gamma R` for *jkr*\ , and
:math:`F_{pulloff} = 4\pi \gamma R` for *dmt*\ .
The remaining tangential options all use accumulated tangential
displacement (i.e. contact history). This is discussed below in the
context of the *linear_history* option, but the same treatment of the
accumulated displacement applies to the other options as well.
displacement (i.e. contact history), except for the options
*mindlin/force* and *mindlin_rescale/force*, that use accumulated
tangential force instead, and are discussed further below.
The accumulated tangential displacement is discussed in details below
in the context of the *linear_history* option. The same treatment of
the accumulated displacement applies to the other options as well.
For *tangential linear_history*, the tangential force is given by:
.. math::
\mathbf{F}_t = -min(\mu_t F_{n0}, \|-k_t\mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
\mathbf{F}_t = -\min(\mu_t F_{n0}, \|-k_t\mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
Here, :math:`\mathbf{\xi}` is the tangential displacement accumulated
during the entire duration of the contact:
@ -356,7 +361,7 @@ work:
.. math::
\mathbf{\xi} = \left(\mathbf{\xi'} - (\mathbf{n} \cdot \mathbf{\xi'})\mathbf{n}\right) \frac{\|\mathbf{\xi'}\|}{\|\mathbf{\xi'}\| - \mathbf{n}\cdot\mathbf{\xi'}}
\mathbf{\xi} = \left(\mathbf{\xi'} - (\mathbf{n} \cdot \mathbf{\xi'})\mathbf{n}\right) \frac{\|\mathbf{\xi'}\|}{\|\mathbf{\xi'} - (\mathbf{n}\cdot\mathbf{\xi'})\mathbf{n}\|}
Here, :math:`\mathbf{\xi'}` is the accumulated displacement prior to the
current time step and :math:`\mathbf{\xi}` is the corrected
@ -372,7 +377,7 @@ discussion):
.. math::
\mathbf{\xi} = -\frac{1}{k_t}\left(\mu_t F_{n0}\mathbf{t} + \mathbf{F}_{t,damp}\right)
\mathbf{\xi} = -\frac{1}{k_t}\left(\mu_t F_{n0}\mathbf{t} - \mathbf{F}_{t,damp}\right)
The tangential force is added to the total normal force (elastic plus
damping) to produce the total force on the particle. The tangential
@ -387,27 +392,68 @@ overlap region) to induce a torque on each particle according to:
\mathbf{\tau}_j = -(R_j - 0.5 \delta) \mathbf{n} \times \mathbf{F}_t
For *tangential mindlin*\ , the :ref:`Mindlin <Mindlin1949>` no-slip solution is used, which differs from the *linear_history*
option by an additional factor of *a*\ , the radius of the contact region. The tangential force is given by:
For *tangential mindlin*\ , the :ref:`Mindlin <Mindlin1949>` no-slip solution
is used which differs from the *linear_history* option by an additional factor
of :math:`a`, the radius of the contact region. The tangential force is given by:
.. math::
\mathbf{F}_t = -min(\mu_t F_{n0}, \|-k_t a \mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
\mathbf{F}_t = -\min(\mu_t F_{n0}, \|-k_t a \mathbf{\xi} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
Here, *a* is the radius of the contact region, given by :math:`a =\sqrt{R\delta}`
Here, :math:`a` is the radius of the contact region, given by :math:`a =\sqrt{R\delta}`
for all normal contact models, except for *jkr*\ , where it is given
implicitly by :math:`\delta = a^2/R - 2\sqrt{\pi \gamma a/E}`, see
discussion above. To match the Mindlin solution, one should set :math:`k_t = 4G/(2-\nu)`, where :math:`G` is the shear modulus, related to Young's modulus
:math:`E` by :math:`G = E/(2(1+\nu))`, where :math:`\nu` is Poisson's ratio. This
can also be achieved by specifying *NULL* for :math:`k_t`, in which case a
discussion above. To match the Mindlin solution, one should set
:math:`k_t = 8G_{eff}`, where :math:`G_{eff}` is the effective shear modulus given by:
.. math::
G_{eff} = \left(\frac{2-\nu_i}{G_i} + \frac{2-\nu_j}{G_j}\right)^{-1}
where :math:`G` is the shear modulus, related to Young's modulus :math:`E`
and Poisson's ratio :math:`\nu` by :math:`G = E/(2(1+\nu))`. This can also be
achieved by specifying *NULL* for :math:`k_t`, in which case a
normal contact model that specifies material parameters :math:`E` and
:math:`\nu` is required (e.g. *hertz/material*\ , *dmt* or *jkr*\ ). In this
case, mixing of the shear modulus for different particle types *i* and
*j* is done according to:
*j* is done according to the formula above.
.. note::
The radius of the contact region :math:`a` depends on the normal overlap.
As a result, the tangential force for *mindlin* can change due to
a variation in normal overlap, even with no change in tangential displacement.
For *tangential mindlin/force*, the accumulated elastic tangential force
characterizes the contact history, instead of the accumulated tangential
displacement. This prevents the dependence of the tangential force on the
normal overlap as noted above. The tangential force is given by:
.. math::
1/G = 2(2-\nu_i)(1+\nu_i)/E_i + 2(2-\nu_j)(1+\nu_j)/E_j
\mathbf{F}_t = -\min(\mu_t F_{n0}, \|\mathbf{F}_{te} + \mathbf{F}_\mathrm{t,damp}\|) \mathbf{t}
The increment of the elastic component of the tangential force
:math:`\mathbf{F}_{te}` is given by:
.. math::
\mathrm{d}\mathbf{F}_{te} = -k_t a \mathbf{v}_{t,rel} \mathrm{d}\tau
The changes in frame of reference of the contacting pair of particles during
contact are accounted for by the same formula as above, replacing the
accumulated tangential displacement :math:`\xi`, by the accumulated tangential
elastic force :math:`F_{te}`. When the tangential force exceeds the critical
force, the tangential force is directly re-scaled to match the value for
the critical force:
.. math::
\mathbf{F}_{te} = - \mu_t F_{n0}\mathbf{t} + \mathbf{F}_{t,damp}
The same rules as those described for *mindlin* apply regarding the tangential
stiffness and mixing of the shear modulus for different particle types.
The *mindlin_rescale* option uses the same form as *mindlin*\ , but the
magnitude of the tangential displacement is re-scaled as the contact
@ -421,9 +467,32 @@ Here, :math:`t_{n-1}` indicates the value at the previous time
step. This rescaling accounts for the fact that a decrease in the
contact area upon unloading leads to the contact being unable to
support the previous tangential loading, and spurious energy is
created without the rescaling above (:ref:`Walton <WaltonPC>` ). See also
discussion in :ref:`Thornton et al, 2013 <Thornton2013>` , particularly
equation 18(b) of that work and associated discussion.
created without the rescaling above (:ref:`Walton <WaltonPC>` ).
.. note::
For *mindlin*, a decrease in the tangential force already occurs as the
contact unloads, due to the dependence of the tangential force on the normal
force described above. By re-scaling :math:`\xi`, *mindlin_rescale*
effectively re-scales the tangential force twice, i.e., proportionally to
:math:`a^2`. This peculiar behavior results from use of the accumulated
tangential displacement to characterize the contact history. Although
*mindlin_rescale* remains available for historic reasons and backward
compatibility purposes, it should be avoided in favor of *mindlin_rescale/force*.
The *mindlin_rescale/force* option uses the same form as *mindlin/force*,
but the magnitude of the tangential elastic force is re-scaled as the contact
unloads, i.e. if :math:`a < a_{t_{n-1}}`:
.. math::
\mathbf{F}_{te} = \mathbf{F}_{te, t_{n-1}} \frac{a}{a_{t_{n-1}}}
This approach provides a better approximation of the :ref:`Mindlin-Deresiewicz <Mindlin1953>`
laws and is more consistent than *mindlin_rescale*. See discussions in
:ref:`Thornton et al, 2013 <Thornton2013>`, particularly equation 18(b) of that
work and associated discussion, and :ref:`Agnolin and Roux, 2007 <AgnolinRoux2007>`,
particularly Appendix A.
----------
@ -460,7 +529,7 @@ exceeds a critical value:
.. math::
\mathbf{F}_{roll} = min(\mu_{roll} F_{n,0}, \|\mathbf{F}_{roll,0}\|)\mathbf{k}
\mathbf{F}_{roll} = \min(\mu_{roll} F_{n,0}, \|\mathbf{F}_{roll,0}\|)\mathbf{k}
Here, :math:`\mathbf{k} = \mathbf{v}_{roll}/\|\mathbf{v}_{roll}\|` is the direction of
the pseudo-force. As with tangential displacement, the rolling
@ -512,7 +581,7 @@ is then truncated according to:
.. math::
\tau_{twist} = min(\mu_{twist} F_{n,0}, \tau_{twist,0})
\tau_{twist} = \min(\mu_{twist} F_{n,0}, \tau_{twist,0})
Similar to the sliding and rolling displacement, the angular
displacement is rescaled so that it corresponds to the critical value
@ -763,3 +832,15 @@ Technology, 233, 30-46.
.. _WaltonPC:
**(Otis R. Walton)** Walton, O.R., Personal Communication
.. _Mindlin1953:
**(Mindlin and Deresiewicz, 1953)** Mindlin, R.D., & Deresiewicz, H (1953).
Elastic Spheres in Contact under Varying Oblique Force.
J. Appl. Mech., ASME 20, 327-344.
.. _AgnolinRoux2007:
**(Agnolin and Roux 2007)** Agnolin, I. & Roux, J-N. (2007).
Internal states of model isotropic granular packings.
I. Assembling process, geometry, and contact networks. Phys. Rev. E, 76, 061302.

6
doc/src/pair_mesodpd.rst
View File

@ -250,8 +250,12 @@ from :ref:`(Li2013_POF) <Li2013_POF>`. The short mDPD run (about 2 minutes
on a single core) generates a particle trajectory which can
be visualized as follows.
.. only:: html
.. image:: JPG/examples_mdpd.gif
:align: center
.. image:: JPG/examples_mdpd_first.jpg
:target: JPG/examples_mdpd.gif
:align: center
.. image:: JPG/examples_mdpd_last.jpg

4
doc/src/pair_peri.rst
View File

@ -128,7 +128,7 @@ viscoelastic relaxation parameter and time constant,
respectively. m_lambdai varies within zero to one. For very small
values of m_lambdai the viscoelastic model responds very similar to a
linear elastic model. For details please see the description in
"(Mtchell2011)".
"(Mitchell2011)".
For the *peri/eps* style:
@ -142,7 +142,7 @@ For the *peri/eps* style:
K is the bulk modulus and G is the shear modulus. The horizon is a
cutoff distance and s00 and :math:`\alpha` are used as a bond breaking
criteria. m_yield_stress is the yield stress of the material. For
details please see the description in "(Mtchell2011a)".
details please see the description in "(Mitchell2011a)".
----------

12
doc/src/pair_python.rst
View File

@ -38,12 +38,12 @@ corresponding compiled code. This penalty can be significantly reduced
through generating tabulations from the python code through the
:doc:`pair_write <pair_write>` command, which is supported by this style.
Only a single pair_coeff command is used with the *python* pair style
which specifies a python class inside a python module or file that
LAMMPS will look up in the current directory, the folder pointed to by
the LAMMPS_POTENTIALS environment variable or somewhere in your python
path. A single python module can hold multiple python pair class
definitions. The class definitions itself have to follow specific
Only a single :doc:`pair_coeff <pair_coeff>` command is used with the
*python* pair style which specifies a python class inside a python module
or a file that LAMMPS will look up in the current directory, a folder
pointed to by the ``LAMMPS_POTENTIALS`` environment variable or somewhere
in your python path. A single python module can hold multiple python pair
class definitions. The class definitions itself have to follow specific
rules that are explained below.
Atom types in the python class are specified through symbolic

91
doc/src/pg_cplusplus.rst Normal file
View File

@ -0,0 +1,91 @@
Using the C++ API directly
**************************
Using the C++ classes of the LAMMPS library is lacking some of the
convenience of the C library API, but it allows a more direct access to
simulation data and thus more low-level manipulations and tighter
integration of LAMMPS into another code. While for the complete C
library API is provided in the ``library.h`` header file, for using
the C++ API it is required to include the individual header files
defining the individual classes in use. Typically the name of the
class and the name of the header follow some simple rule. Examples
are given below.
Creating or deleting a LAMMPS object
*************************************
When using the LAMMPS library interfaces, the core task is to create an
instance of the :cpp:class:`LAMMPS_NS::LAMMPS` class. In C++ this can
be done directly through the ``new`` operator. All further operations
are then initiated through calling member functions of some of the
components of the LAMMPS class or accessing their data members. The
destruction of the LAMMPS instance is correspondingly initiated by using
the ``delete`` operator. Here is a simple example:
.. code-block:: c++
#include "lammps.h"
#include "universe.h"
#include <mpi.h>
#include <iostream>
int main(int argc, char **argv)
{
LAMMPS_NS::LAMMPS *lmp;
// custom argument vector for LAMMPS library
const char *lmpargv[] {"liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);
// explicitly initialize MPI
MPI_Init(&argc, &argv);
// create LAMMPS instance
lmp = new LAMMPS_NS::LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
// output numerical version string
std::cout << "LAMMPS version: " << lmp->universe->num_ver << std::endl;
// delete LAMMPS instance
delete lmp;
// stop MPI environment
MPI_Finalize();
return 0;
}
Please note that this requires to include the ``lammps.h`` header for accessing
the members of the LAMMPS class and then the ``universe.h`` header for accessing the ``num_ver`` member of the :cpp:class:`Universe` class.
Executing LAMMPS commands
*************************
Once a LAMMPS instance is created by your C++ code, you need to set up a
simulation and that is most conveniently done by "driving" it through
issuing commands like you would do when running a LAMMPS simulation from
an input script. Processing of input in LAMMPS is handled by the
:cpp:class:`Input <LAMMPS_NS::Input>` class an instance of which is a
member of the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class. You have
two options: reading commands from a file, or executing a single
command from a string. See below for a small example:
.. code-block:: c++
#include "lammps.h"
#include "input.h"
#include <mpi.h>
using namespace LAMMPS_NS;
int main(int argc, char **argv)
{
const char *lmpargv[] {"liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);
MPI_Init(&argc, &argv);
LAMMPS *lmp = new LAMMPS(lmpargc, (char **)lmpargv, MPI_COMM_WORLD);
lmp->input->file("in.melt");
lmp->input->one("run 100 post no");
delete lmp;
return 0;
}

1088
doc/src/pg_developer.rst Normal file
View File

File diff suppressed because it is too large Load Diff

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

@ -0,0 +1,202 @@
The ``LIBLAMMPS`` Fortran Module
********************************
The ``LIBLAMMPS`` module provides an interface to call LAMMPS from a
Fortran code. It is based on the LAMMPS C-library interface and
requires a Fortran 2003 compatible compiler to be compiled.
While C libraries have a defined binary interface (ABI) and can thus be
used from multiple compiler versions from different vendors for as long
as they are compatible with the hosting operating system, the same is
not true for Fortran codes. Thus the LAMMPS Fortran module needs to be
compiled alongside the code using it from the source code in
``fortran/lammps.f90``. When linking, you also need to
:doc:`link to the LAMMPS library <Build_link>`. A typical command line
for a simple program using the Fortran interface would be:
.. code-block:: bash
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.
.. versionadded:: 30Sep2020
.. admonition:: Work in Progress
This Fortran module is work in progress and only the documented
functionality is currently available. The final implementation should
cover the entire range of functionality available in the C and
Python library interfaces.
----------
Creating or deleting a LAMMPS object
************************************
With the Fortran interface the creation of a :cpp:class:`LAMMPS
<LAMMPS_NS::LAMMPS>` instance is included in the constructor for
creating the :f:func:`lammps` derived type. To import the definition of
that type and its type bound procedures you need to add a ``USE
LIBLAMMPS`` statement. Internally it will call either
:cpp:func:`lammps_open_fortran` or :cpp:func:`lammps_open_no_mpi` from
the C library API to create the class instance. All arguments are
optional and :cpp:func:`lammps_mpi_init` will be called automatically,
if it is needed. Similarly, a possible call to :cpp:func:`lammps_finalize`
is integrated into the :f:func:`close` function and triggered with
the optional logical argument set to ``.true.``. Here is a simple example:
.. code-block:: fortran
PROGRAM testlib
USE LIBLAMMPS ! include the LAMMPS library interface
TYPE(lammps) :: lmp ! derived type to hold LAMMPS instance
CHARACTER(len=*), DIMENSION(*), PARAMETER :: args = &
[ CHARACTER(len=12) :: 'liblammps', '-log', 'none' ]
! create a LAMMPS instance (and initialize MPI)
lmp = lammps(args)
! get and print numerical version code
PRINT*, 'LAMMPS Version: ', lmp%version()
! delete LAMMPS instance (and shuts down MPI)
CALL lmp%close(.true.)
END PROGRAM testlib
--------------------
Executing LAMMPS commands
=========================
Once a LAMMPS instance is created, it is possible to "drive" the LAMMPS
simulation by telling LAMMPS to read commands from a file, or pass
individual or multiple commands from strings or lists of strings. This
is done similar to how it is implemented in the `C-library
<pg_lib_execute>` interface. Before handing off the calls to the
C-library interface, the corresponding Fortran versions of the calls
(:f:func:`file`, :f:func:`command`, :f:func:`commands_list`, and
:f:func:`commands_string`) have to make a copy of the strings passed as
arguments so that they can be modified to be compatible with the
requirements of strings in C without affecting the original strings.
Those copies are automatically deleted after the functions return.
Below is a small demonstration of the uses of the different functions:
.. code-block:: fortran
PROGRAM testcmd
USE LIBLAMMPS
TYPE(lammps) :: lmp
CHARACTER(len=512) :: cmds
CHARACTER(len=40),ALLOCATABLE :: cmdlist(:)
CHARACTER(len=10) :: trimmed
INTEGER :: i
lmp = lammps()
CALL lmp%file('in.melt')
CALL lmp%command('variable zpos index 1.0')
! define 10 groups of 10 atoms each
ALLOCATE(cmdlist(10))
DO i=1,10
WRITE(trimmed,'(I10)') 10*i
WRITE(cmdlist(i),'(A,I1,A,I10,A,A)') &
'group g',i-1,' id ',10*(i-1)+1,':',ADJUSTL(trimmed)
END DO
CALL lmp%commands_list(cmdlist)
! run multiple commands from multi-line string
cmds = 'clear' // NEW_LINE('A') // &
'region box block 0 2 0 2 0 2' // NEW_LINE('A') // &
'create_box 1 box' // NEW_LINE('A') // &
'create_atoms 1 single 1.0 1.0 ${zpos}'
CALL lmp%commands_string(cmds)
CALL lmp%close()
END PROGRAM testcmd
---------------
The ``LIBLAMMPS`` module API
****************************
Below are the detailed descriptions of definitions and interfaces
of the contents of the ``LIBLAMMPS`` Fortran interface to LAMMPS.
.. f:type:: lammps
Derived type that is the general class of the Fortran interface.
It holds a reference to the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class instance
that any of the included calls are forwarded to.
:f c_ptr handle: reference to the LAMMPS class
:f close: :f:func:`close`
:f version: :f:func:`version`
:f file: :f:func:`file`
:f command: :f:func:`command`
:f commands_list: :f:func:`commands_list`
:f commands_string: :f:func:`commands_string`
.. f:function:: lammps(args[,comm])
This is the constructor for the Fortran class and will forward
the arguments to a call to either :cpp:func:`lammps_open_fortran`
or :cpp:func:`lammps_open_no_mpi`. If the LAMMPS library has been
compiled with MPI support, it will also initialize MPI, if it has
not already been initialized before.
The *args* argument with the list of command line parameters is
optional and so it the *comm* argument with the MPI communicator.
If *comm* is not provided, ``MPI_COMM_WORLD`` is assumed. For
more details please see the documentation of :cpp:func:`lammps_open`.
:p character(len=*) args(*) [optional]: arguments as list of strings
:o integer comm [optional]: MPI communicator
:r lammps: an instance of the :f:type:`lammps` derived type
.. f:subroutine:: close([finalize])
This method will close down the LAMMPS instance through calling
:cpp:func:`lammps_close`. If the *finalize* argument is present and
has a value of ``.true.``, then this subroutine also calls
:cpp:func:`lammps_mpi_finalize`.
:o logical finalize [optional]: shut down the MPI environment of the LAMMPS library if true.
.. f:function:: version()
This method returns the numeric LAMMPS version like :cpp:func:`lammps_version`
:r integer: LAMMPS version
--------
.. f:subroutine:: file(filename)
This method will call :cpp:func:`lammps_file` to have LAMMPS read
and process commands from a file.
:p character(len=*) filename: name of file with LAMMPS commands
.. f:subroutine:: command(cmd)
This method will call :cpp:func:`lammps_command` to have LAMMPS
execute a single command.
:p character(len=*) cmd: single LAMMPS command
.. f:subroutine:: commands_list(cmds)
This method will call :cpp:func:`lammps_commands_list` to have LAMMPS
execute a list of input lines.
:p character(len=*) cmd(*): list of LAMMPS input lines
.. f:subroutine:: commands_string(str)
This method will call :cpp:func:`lammps_commands_string` to have LAMMPS
execute a block of commands from a string.
:p character(len=*) str: LAMMPS input in string

33
doc/src/pg_lib_add.rst Normal file
View File

@ -0,0 +1,33 @@
Adding code to the Library interface
====================================
The functionality of the LAMMPS library interface has historically
always been motivated by the needs of its users and functions were
added or expanded as they were needed and used. Contributions to
the interface are always welcome. However with a refactoring of
the library interface and its documentation that started in 2020,
there are now a few requirements for inclusion of changes.
- New functions should be orthogonal to existing ones and not
implement functionality that can already be achieved with the
existing APIs.
- All changes and additions should be documented with
`Doxygen <https://doxgygen.org>`_ style comments and references
to those functions added to the corresponding files in the
``doc/src`` folder.
- If possible, new unit tests to test those new features should
be added.
- The new feature should also be implemented and documented for
the Python and Fortran modules.
- All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,
``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` and compiling
with and without MPI support.
- The ``library.h`` file should be kept compatible to C code at
a level similar to C89. Its interfaces may not reference any
custom data types (e.g. ``bigint``, ``tagint``, and so on) only
known inside of LAMMPS.
- only C style comments, not C++ style
Please note, that these are *not* *strict* requirements, but the
LAMMPS developers appreciate if they are followed closely and will
assist with implementing what is missing.

67
doc/src/pg_lib_config.rst Normal file
View File

@ -0,0 +1,67 @@
Retrieving LAMMPS configuration information
===========================================
The following library functions can be used to query the
LAMMPS library about compile time settings and included
packages and styles.
-----------------------
.. doxygenfunction:: lammps_config_has_mpi_support
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_gzip_support
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_png_support
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_jpeg_support
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_ffmpeg_support
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_exceptions
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_package
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_package_count
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_package_name
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_style
:project: progguide
-----------------------
.. doxygenfunction:: lammps_style_count
:project: progguide
-----------------------
.. doxygenfunction:: lammps_style_name
:project: progguide

104
doc/src/pg_lib_create.rst Normal file
View File

@ -0,0 +1,104 @@
Creating or deleting a LAMMPS object
====================================
The :cpp:func:`lammps_open` and :cpp:func:`lammps_open_no_mpi`
functions are used to create and initialize a
:cpp:func:`LAMMPS` instance. The calling program has to
provide a handle where a reference to this instance can be stored and
which has to be used in all subsequent function calls until that
instance is destroyed by calling :cpp:func:`lammps_close`.
Here is a simple example demonstrating its use:
.. code-block:: C
#include "library.h"
#include <stdio.h>
int main(int argc, char **argv)
{
void *handle;
int version;
const char *lmpargv[] = { "liblammps", "-log", "none"};
int lmpargc = sizeof(lmpargv)/sizeof(const char *);
/* create LAMMPS instance */
handle = lammps_open_no_mpi(lmpargc, lmpargv, NULL);
if (handle == NULL) {
printf("LAMMPS initialization failed");
lammps_mpi_finalize();
return 1;
}
/* get and print numerical version code */
version = lammps_version(handle);
printf("LAMMPS Version: %d\n",version);
/* delete LAMMPS instance and shut down MPI */
lammps_close(handle);
lammps_mpi_finalize();
return 0;
}
The LAMMPS library will be using the MPI library it was compiled with
and will either run on all processors in the ``MPI_COMM_WORLD``
communicator or on the set of processors in the communicator given in
the ``comm`` argument of :cpp:func:`lammps_open`. This means
the calling code can run LAMMPS on all or a subset of processors. For
example, a wrapper code might decide to alternate between LAMMPS and
another code, allowing them both to run on all the processors. Or it
might allocate part of the processors to LAMMPS and the rest to the
other code by creating a custom communicator with ``MPI_Comm_split()``
and running both codes concurrently before syncing them up periodically.
Or it might instantiate multiple instances of LAMMPS to perform
different calculations and either alternate between them, run them
concurrently on split communicators, or run them one after the other.
The :cpp:func:`lammps_open` function may be called multiple
times for this latter purpose.
The :cpp:func:`lammps_close` function is used to shut down
the :cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` class pointed to by the handle
passed as an argument and free all its memory. This has to be called for
every instance created with any of the :cpp:func:`lammps_open` functions. It will, however, **not** call
``MPI_Finalize()``, since that may only be called once. See
:cpp:func:`lammps_mpi_finalize` for an alternative to calling
``MPI_Finalize()`` explicitly in 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
:project: progguide
-----------------------
.. doxygenfunction:: lammps_open_no_mpi
:project: progguide
-----------------------
.. doxygenfunction:: lammps_open_fortran
:project: progguide
-----------------------
.. doxygenfunction:: lammps_close
:project: progguide
-----------------------
.. doxygenfunction:: lammps_mpi_init
:project: progguide
-----------------------
.. doxygenfunction:: lammps_mpi_finalize
:project: progguide
-----------------------
.. doxygenfunction:: lammps_free
:project: progguide

69
doc/src/pg_lib_execute.rst Normal file
View File

@ -0,0 +1,69 @@
Executing LAMMPS commands
=========================
Once a LAMMPS instance is created, there are multiple ways to "drive" a
simulation. In most cases it is easiest to process single or multiple
LAMMPS commands like in an input file. This can be done through reading
a file or passing single commands or lists of commands or blocks of
commands with the following functions.
Via these functions, the calling code can have the LAMMPS instance act
on a series of :doc:`input file commands <Commands_all>` that are either
read from a file or passed as strings. This for, for example, allows to
setup a problem from a template file and then run it in stages while
performing other operations in between or concurrently. The caller can
interleave the LAMMPS function calls with operations it performs, calls
to extract information from or set information within LAMMPS, or calls
to another code's library.
Also equivalent to regular :doc:`input script parsing <Commands_parse>`
is the handling of comments and expansion of variables with ``${name}``
or ``$(expression)`` syntax before the commands are parsed and
executed. Below is a short example using some of these functions.
.. code-block:: C
#include "library.h"
#include <mpi.h>
#include <stdio.h>
int main(int argc, char **argv)
{
void *handle;
int i;
MPI_Init(&argc, &argv);
handle = lammps_open(0, NULL, MPI_COMM_WORLD, NULL);
lammps_file(handle,"in.sysinit");
lammps_command(handle,"run 1000 post no");
for (i=0; i < 100; ++i) {
lammps_commands_string(handle,"run 100 pre no post no\n"
"print 'PE = $(pe)'\n"
"print 'KE = $(ke)'\n");
}
lammps_close(handle);
MPI_Finalize();
return 0;
}
-----------------------
.. doxygenfunction:: lammps_file
:project: progguide
-----------------------
.. doxygenfunction:: lammps_command
:project: progguide
-----------------------
.. doxygenfunction:: lammps_commands_list
:project: progguide
-----------------------
.. doxygenfunction:: lammps_commands_string
:project: progguide

30
doc/src/pg_lib_neighbor.rst Normal file
View File

@ -0,0 +1,30 @@
Accessing LAMMPS Neighbor lists
===============================
The following functions allow to access neighbor lists
generated by LAMMPS or query their properties.
-----------------------
.. doxygenfunction:: lammps_find_compute_neighlist
:project: progguide
-----------------------
.. doxygenfunction:: lammps_find_fix_neighlist
:project: progguide
-----------------------
.. doxygenfunction:: lammps_find_pair_neighlist
:project: progguide
-----------------------
.. doxygenfunction:: lammps_neighlist_num_elements
:project: progguide
-----------------------
.. doxygenfunction:: lammps_neighlist_element_neighbors
:project: progguide

31
doc/src/pg_lib_objects.rst Normal file
View File

@ -0,0 +1,31 @@
Retrieving or setting properties of LAMMPS objects
==================================================
This section documents accessing or modifying data from objects like
computes, fixes, or variables in LAMMPS.
-----------------------
.. doxygenfunction:: lammps_extract_compute
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_fix
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_variable
:project: progguide
-----------------------
.. doxygenfunction:: lammps_set_variable
:project: progguide
-----------------------
.. doxygenenum:: _LMP_STYLE_CONST
.. doxygenenum:: _LMP_TYPE_CONST

62
doc/src/pg_lib_properties.rst Normal file
View File

@ -0,0 +1,62 @@
Retrieving or setting LAMMPS system properties
==============================================
The library interface allows to extract different kinds of information
about the active simulation instance and also to modify some of them.
This allows to combine MD simulation steps with other processing and
simulation methods computed in the calling code or another code that is
coupled to LAMMPS via the library interface. In some cases the data
returned is direct reference to the original data inside LAMMPS cast
to a void pointer. In that case the data needs to be cast to a suitable
pointer to be able to access it, and you need to know the correct dimensions
and lengths. 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.
-----------------------
.. doxygenfunction:: lammps_version
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_natoms
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_thermo
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_box
:project: progguide
-----------------------
.. doxygenfunction:: lammps_reset_box
:project: progguide
-------------------
.. doxygenfunction:: lammps_extract_setting
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_atom
:project: progguide
-----------------------
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
:project: progguide

29
doc/src/pg_lib_scatter.rst Normal file
View File

@ -0,0 +1,29 @@
Library functions for scatter/gather operations
================================================
.. TODO add description
-----------------------
.. doxygenfunction:: lammps_gather_atoms
:project: progguide
-----------------------
.. doxygenfunction:: lammps_gather_atoms_concat
:project: progguide
-----------------------
.. doxygenfunction:: lammps_gather_atoms_subset
:project: progguide
-----------------------
.. doxygenfunction:: lammps_scatter_atoms
:project: progguide
-----------------------
.. doxygenfunction:: lammps_scatter_atoms_subset
:project: progguide

30
doc/src/pg_lib_utility.rst Normal file
View File

@ -0,0 +1,30 @@
Library interface utility functions
===================================
To simplify some of the tasks, the library interface contains
some utility functions that are not directly calling LAMMPS.
-----------------------
.. doxygenfunction:: lammps_encode_image_flags
:project: progguide
-----------------------
.. doxygenfunction:: lammps_decode_image_flags(int image, int *flags)
:project: progguide
-----------------------
.. doxygenfunction:: lammps_set_fix_external_callback(void *, char *, FixExternalFnPtr, void*)
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_error
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_last_error_message
:project: progguide

158
doc/src/pg_library.rst Normal file
View File

@ -0,0 +1,158 @@
LAMMPS Library Interfaces
*************************
As described on the :doc:`library interface to LAMMPS <Howto_library>`
doc page, LAMMPS can be built as a library (static or shared), so that
it can be called by another code, used in a :doc:`coupled manner
<Howto_couple>` with other codes, or driven through a :doc:`Python
script <Python_head>`. Even the LAMMPS standalone executable is
essentially a thin wrapper on top of the LAMMPS library, creating a
LAMMPS instance, processing input and then existing.
Several of these approaches are based on C language wrapper functions
in the files ``src/library.h`` and ``src/library.cpp``, but it is also
possible to use C++ directly. The basic procedure is always the same:
you create one or more instances of the
:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>` and then pass commands as
strings or from files to that LAMMPS instance to execute calculations,
or read, manipulate, and update data from the active class instances
inside the LAMMPS to do analysis or perform operations that are not
possible with existing commands.
.. _thread-safety:
.. admonition:: Thread-safety
:class: note
LAMMPS was initially not conceived as a thread-safe program, but over
the years changes have been applied to replace operations that
collide with creating multiple LAMMPS instances from multiple-threads
of the same process with thread-safe alternatives. This primarily
applies to the core LAMMPS code and less so on add-on packages,
especially when those packages require additional code in the *lib*
folder, interface LAMMPS to Fortran libraries, or the code uses
static variables (like the USER-COLVARS package).
Another major issue to deal with is to correctly handle MPI.
Creating a LAMMPS instance requires passing an MPI communicator, or
it assumes the ``MPI_COMM_WORLD`` communicator, which spans all MPI
processor ranks. When creating multiple LAMMPS object instances from
different threads, this communicator has to be different for each
thread or else collisions can happen. or it has to be guaranteed,
that only one thread at a time is active. MPI communicators,
however, are not a problem, if LAMMPS is compiled with the MPI STUBS
library, which implies that there is no MPI communication and only 1
MPI rank.
----------
.. _lammps_c_api:
LAMMPS C Library API
====================
The C library interface is most commonly used path to manage LAMMPS
instances from a compiled code and it is the basis for the :doc:`Python
<pg_python>` and :doc:`Fortran <pg_fortran>` modules. Almost all
functions of the C language API require an argument containing a
"handle" in the form of a ``void *`` type variable, which points to the
location of a LAMMPS class instance.
The ``library.h`` header file by default includes the ``mpi.h`` header
for an MPI library, so it must be present when compiling code using the
library interface. This usually must be the header from the same MPI
library as the LAMMPS library was compiled with. The exception is when
LAMMPS was compiled in serial mode using the ``STUBS`` MPI library. In
that case the calling code may be compiled with a different MPI library
for as long as :cpp:func:`lammps_open_no_mpi` is called to create a
LAMMPS instance. Then you may set the define ``-DLAMMPS_LIB_NO_MPI``
when compiling your code and the inclusion of ``mpi.h`` will be skipped
and consequently the function :cpp:func:`lammps_open` may not be used.
.. admonition:: Errors versus exceptions
:class: note
If any of the function calls in the LAMMPS library API will trigger
an error inside LAMMPS, this will result in an abort of the entire
program. This is not always desirable. Instead, LAMMPS can be
compiled to instead :ref:`throw a C++ exception <exceptions>`.
.. warning::
No checks are made on the arguments of the function calls of the C
library interface. *All* function arguments must be non-NULL unless
*explicitly* allowed and point to consistent and valid data. Buffers
for storing returned data must be allocated to a suitable size.
Passing invalid or unsuitable information will likely cause crashes
or corrupt data.
------------------------------
.. toctree::
:maxdepth: 1
pg_lib_create
pg_lib_execute
pg_lib_properties
pg_lib_objects
pg_lib_scatter
pg_lib_neighbor
pg_lib_config
pg_lib_utility
pg_lib_add
--------------------
.. _lammps_python_api:
LAMMPS Python APIs
==================
The LAMMPS Python module enables calling the LAMMPS C library API from
Python by dynamically loading functions in the LAMMPS shared library through
the `Python ctypes module <https://docs.python.org/3/library/ctypes.html>`_.
Because of the dynamic loading, it is **required** that LAMMPS is compiled
in :ref:`"shared" mode <exe>`. The Python interface is object oriented, but
otherwise trying to be very similar to the C library API. Three different
Python classes to run LAMMPS are available and they build on each other.
.. toctree::
:maxdepth: 1
pg_python
-------------------
.. _lammps_fortran_api:
LAMMPS Fortran API
==================
The LAMMPS Fortran module is a wrapper around calling functions from the
LAMMPS C library API from Fortran through the ISO_C_BINDING feature in
Fortran 2003. The interface is object oriented but otherwise trying to
be very similar to the C library API and the basic Python module.
.. toctree::
:maxdepth: 1
pg_fortran
-------------------
.. _lammps_cplusplus_api:
LAMMPS C++ API
==============
It is also possible to invoke the LAMMPS C++ API directly in your code.
It is lacking some of the convenience of the C library API, but it allows
a more direct access to simulation data and thus more low-level manipulations.
The following links provide some examples and references to the C++ API.
.. toctree::
:maxdepth: 1
pg_cplusplus

188
doc/src/pg_python.rst Normal file
View File

@ -0,0 +1,188 @@
The ``lammps`` Python module
****************************
.. py:module:: lammps
The LAMMPS Python interface is implemented as a module called
:py:mod:`lammps` in the ``lammps.py`` file in the ``python`` folder of
the LAMMPS source code distribution. After compilation of LAMMPS, the
module can be installed into a Python system folder or a user folder
with ``make install-python``. Components of the module can then loaded
into a Python session with the ``import`` command.
There are multiple Python interface classes in the :py:mod:`lammps` module:
- the :py:class:`lammps <lammps.lammps>` class. This is a wrapper around
the C-library interface and its member functions try to replicate the
:doc:`C-library API <pg_library>` closely. This is the most
feature-complete Python API.
- the :py:class:`PyLammps <lammps.PyLammps>` class. This is a more high-level
and more Python style class implemented on top of the
:py:class:`lammps <lammps.lammps>` class.
- the :py:class:`IPyLammps <lammps.IPyLammps>` class is derived from
:py:class:`PyLammps <lammps.PyLammps>` and adds embedded graphics
features to conveniently include LAMMPS into `Jupyter
<https://jupyter.org/>`_ notebooks.
.. _mpi4py_url: https://mpi4py.readthedocs.io
----------
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 constructor for the
:py:func:`lammps <lammps.lammps>` class. 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 is to allow 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 is a simple example:
.. code-block:: python
from lammps import lammps
# NOTE: argv[0] is set by the Python module
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()
Same as with the :doc:`C library API <pg_lib_create>` 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.
Executing LAMMPS commands
*************************
Once an instance of the :py:class:`lammps <lammps.lammps>` 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. Same as in the equivalent `C
library functions <pg_lib_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)
----------
The ``lammps`` class API
************************
The :py:class:`lammps <lammps.lammps>` class is the core of the LAMMPS
Python interfaces. It is a wrapper around the :doc:`LAMMPS C library
API <pg_library>` using the `Python ctypes module
<https://docs.python.org/3/library/ctypes.html>`_ and a shared library
compiled from the LAMMPS sources code. The individual methods in this
class try to closely follow the corresponding C functions. The handle
argument that needs to be passed to the C functions is stored internally
in the class and automatically added when calling the C library
functions. Below is a detailed documentation of the API.
.. autoclass:: lammps.lammps
:members:
----------
The ``PyLammps`` class API
**************************
.. autoclass:: lammps.PyLammps
:members:
----------
The ``IPyLammps`` class API
***************************
.. autoclass:: lammps.IPyLammps
:members:
----------
Additional components of the ``lammps`` module
**********************************************
The :py:mod:`lammps` module additionally contains several constants
and the :py:class:`NeighList <lammps.NeighList>` class:
.. _py_data_constants:
.. py:data:: LAMMPS_INT, LAMMPS_DOUBLE, LAMMPS_BIGINT, LAMMPS_TAGINT, LAMMPS_STRING
:type: int
Constants in the :py:mod:`lammps` module to indicate how to
cast data when the C library function returns a void pointer.
Used in :py:func:`lammps.extract_global`.
.. _py_style_constants:
.. py:data:: LMP_STYLE_GLOBAL, LMP_STYLE_ATOM, LMP_STYLE_LOCAL
:type: int
Constants in the :py:mod:`lammps` module to select what style of data
to request from computes or fixes. See :cpp:enum:`_LMP_STYLE_CONST`
for the equivalent constants in the C library interface. Used in
:py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
.. _py_type_constants:
.. py:data:: LMP_TYPE_SCALAR, LMP_TYLE_VECTOR, LMP_TYPE_ARRAY, LMP_SIZE_VECTOR, LMP_SIZE_ROWS, LMP_SIZE_COLS
:type: int
Constants in the :py:mod:`lammps` module to select what type of data
to request from computes or fixes. See :cpp:enum:`_LMP_TYPE_CONST`
for the equivalent constants in the C library interface. Used in
:py:func:`lammps.extract_compute` and :py:func:`lammps.extract_fix`.
.. _py_var_constants:
.. py:data:: LMP_VAR_EQUAL, LMP_VAR_ATOM
:type: int
Constants in the :py:mod:`lammps` module to select what style of
variable to query when calling :py:func:`lammps.extract_variable`.
.. autoclass:: lammps.NeighList
:members:
:no-undoc-members: