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

Merge branch 'master' of github.com:lammps/lammps

Browse Source
This commit is contained in:
jstewa
2020-10-13 19:10:32 -06:00
parent 0cc0d10092 b3d9f648ef
commit 7fdf70c960
199 changed files with 20993 additions and 4006 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.github/CODEOWNERS vendored
View File

@ -114,6 +114,7 @@ src/info.* @akohlmey @rbberger
src/timer.* @akohlmey
src/min* @sjplimp @stanmoore1
src/utils.* @akohlmey @rbberger
src/math_eigen_impl.h @jewettaij
# tools
tools/msi2lmp/* @akohlmey
@ -134,6 +135,9 @@ cmake/presets/*.cmake @junghans @rbberger @akohlmey
# python
python/* @rbberger
# fortran
fortran/* @akohlmey
# docs
doc/utils/*/* @rbberger
doc/Makefile @rbberger

1
.gitignore vendored
View File

@ -37,6 +37,7 @@ vgcore.*
ehthumbs.db
Thumbs.db
.clang-format
.lammps_history
#cmake
/build*

49
cmake/CMakeLists.txt
View File

@ -90,6 +90,7 @@ if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg
endif()
option(BUILD_TOOLS "Build and install LAMMPS tools (msi2lmp, binary2txt, chain)" OFF)
option(BUILD_LAMMPS_SHELL "Build and install the LAMMPS shell" OFF)
include(GNUInstallDirs)
file(GLOB ALL_SOURCES ${LAMMPS_SOURCE_DIR}/[^.]*.cpp)
@ -343,20 +344,22 @@ find_program(GZIP_EXECUTABLE gzip)
find_package_handle_standard_args(GZIP REQUIRED_VARS GZIP_EXECUTABLE)
option(WITH_GZIP "Enable GZIP support" ${GZIP_FOUND})
if(WITH_GZIP)
if(NOT GZIP_FOUND)
if(GZIP_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
else()
message(FATAL_ERROR "gzip executable not found")
endif()
target_compile_definitions(lammps PRIVATE -DLAMMPS_GZIP)
endif()
find_program(FFMPEG_EXECUTABLE ffmpeg)
find_package_handle_standard_args(FFMPEG REQUIRED_VARS FFMPEG_EXECUTABLE)
option(WITH_FFMPEG "Enable FFMPEG support" ${FFMPEG_FOUND})
if(WITH_FFMPEG)
if(NOT FFMPEG_FOUND)
if(FFMPEG_FOUND OR ((CMAKE_SYSTEM_NAME STREQUAL Windows) AND CMAKE_CROSSCOMPILING))
target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
else()
message(FATAL_ERROR "ffmpeg executable not found")
endif()
target_compile_definitions(lammps PRIVATE -DLAMMPS_FFMPEG)
endif()
if(BUILD_SHARED_LIBS)
@ -610,36 +613,7 @@ if(BUILD_SHARED_LIBS)
endif()
install(FILES ${LAMMPS_DOC_DIR}/lammps.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1 RENAME ${LAMMPS_BINARY}.1)
if(BUILD_TOOLS)
add_executable(binary2txt ${LAMMPS_TOOLS_DIR}/binary2txt.cpp)
target_compile_definitions(binary2txt PRIVATE -DLAMMPS_${LAMMPS_SIZES})
install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
include(CheckGeneratorSupport)
if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
include(CheckLanguage)
check_language(Fortran)
if(CMAKE_Fortran_COMPILER)
enable_language(Fortran)
add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
else()
message(WARNING "No suitable Fortran compiler found, skipping building 'chain.x'")
endif()
else()
message(WARNING "CMake build doesn't support fortran, skipping building 'chain.x'")
endif()
enable_language(C)
get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
add_executable(msi2lmp ${MSI2LMP_SOURCES})
target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
endif()
include(Tools)
include(Documentation)
###############################################################################
@ -735,6 +709,7 @@ get_target_property(DEFINES lammps COMPILE_DEFINITIONS)
include(FeatureSummary)
feature_summary(DESCRIPTION "The following tools and libraries have been found and configured:" WHAT PACKAGES_FOUND)
message(STATUS "<<< Build configuration >>>
Operating System: ${CMAKE_SYSTEM_NAME}
Build type: ${CMAKE_BUILD_TYPE}
Install path: ${CMAKE_INSTALL_PREFIX}
Generator: ${CMAKE_GENERATOR} using ${CMAKE_MAKE_PROGRAM}
@ -834,3 +809,9 @@ endif()
if(BUILD_DOC)
message(STATUS "<<< Building HTML Manual >>>")
endif()
if(BUILD_TOOLS)
message(STATUS "<<< Building Tools >>>")
endif()
if(BUILD_LAMMPS_SHELL)
message(STATUS "<<< Building LAMMPS Shell >>>")
endif()

46
cmake/Modules/Tools.cmake Normal file
View File

@ -0,0 +1,46 @@
if(BUILD_TOOLS)
add_executable(binary2txt ${LAMMPS_TOOLS_DIR}/binary2txt.cpp)
target_compile_definitions(binary2txt PRIVATE -DLAMMPS_${LAMMPS_SIZES})
install(TARGETS binary2txt DESTINATION ${CMAKE_INSTALL_BINDIR})
include(CheckGeneratorSupport)
if(CMAKE_GENERATOR_SUPPORT_FORTRAN)
include(CheckLanguage)
check_language(Fortran)
if(CMAKE_Fortran_COMPILER)
enable_language(Fortran)
add_executable(chain.x ${LAMMPS_TOOLS_DIR}/chain.f)
target_link_libraries(chain.x PRIVATE ${CMAKE_Fortran_IMPLICIT_LINK_LIBRARIES})
install(TARGETS chain.x DESTINATION ${CMAKE_INSTALL_BINDIR})
else()
message(WARNING "No suitable Fortran compiler found, skipping build of 'chain.x'")
endif()
else()
message(WARNING "CMake build doesn't support fortran, skipping build of 'chain.x'")
endif()
enable_language(C)
get_filename_component(MSI2LMP_SOURCE_DIR ${LAMMPS_TOOLS_DIR}/msi2lmp/src ABSOLUTE)
file(GLOB MSI2LMP_SOURCES ${MSI2LMP_SOURCE_DIR}/[^.]*.c)
add_executable(msi2lmp ${MSI2LMP_SOURCES})
target_link_libraries(msi2lmp PRIVATE ${MATH_LIBRARIES})
install(TARGETS msi2lmp DESTINATION ${CMAKE_INSTALL_BINDIR})
install(FILES ${LAMMPS_DOC_DIR}/msi2lmp.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/man1)
endif()
if(BUILD_LAMMPS_SHELL)
find_package(PkgConfig REQUIRED)
pkg_check_modules(READLINE IMPORTED_TARGET REQUIRED readline)
if(NOT LAMMPS_EXCEPTIONS)
message(WARNING "The LAMMPS shell needs LAMMPS_EXCEPTIONS enabled for full functionality")
endif()
add_executable(lammps-shell ${LAMMPS_TOOLS_DIR}/lammps-shell/lammps-shell.cpp)
# workaround for broken readline pkg-config file on FreeBSD
if(CMAKE_SYSTEM_NAME STREQUAL FreeBSD)
target_include_directories(lammps-shell PRIVATE /usr/local/include)
endif()
target_link_libraries(lammps-shell PRIVATE lammps PkgConfig::READLINE)
install(TARGETS lammps-shell EXPORT LAMMPS_Targets DESTINATION ${CMAKE_INSTALL_BINDIR})
endif()

6
cmake/presets/all_off.cmake
View File

@ -2,9 +2,9 @@
# an existing package selection without losing any other settings
set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MOLECULE
MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
SRD VORONOI
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
SNAP SPIN SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD

6
cmake/presets/all_on.cmake
View File

@ -4,9 +4,9 @@
# with just a working C++ compiler and an MPI library.
set(ALL_PACKAGES ASPHERE BODY CLASS2 COLLOID COMPRESS CORESHELL DIPOLE GPU
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MOLECULE
MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK SNAP SPIN
SRD VORONOI
GRANULAR KIM KOKKOS KSPACE LATTE MANYBODY MC MISC MESSAGE MLIAP
MOLECULE MPIIO MSCG OPT PERI POEMS PYTHON QEQ REPLICA RIGID SHOCK
SNAP SPIN SRD VORONOI
USER-ADIOS USER-ATC USER-AWPMD USER-BOCS USER-CGDNA USER-CGSDK
USER-COLVARS USER-DIFFRACTION USER-DPD USER-DRUDE USER-EFF USER-FEP
USER-H5MD USER-INTEL USER-LB USER-MANIFOLD USER-MEAMC USER-MESODPD

4
cmake/presets/intel.cmake
View File

@ -1,7 +1,8 @@
# preset that will enable clang/clang++ with support for MPI and OpenMP (on Linux boxes)
# preset that will enable Intel compilers with support for MPI and OpenMP (on Linux boxes)
set(CMAKE_CXX_COMPILER "icpc" CACHE STRING "" FORCE)
set(CMAKE_C_COMPILER "icc" CACHE STRING "" FORCE)
set(CMAKE_Fortran_COMPILER "ifort" CACHE STRING "" FORCE)
set(MPI_CXX "icpc" CACHE STRING "" FORCE)
set(MPI_CXX_COMPILER "mpicxx" CACHE STRING "" FORCE)
unset(HAVE_OMP_H_INCLUDE CACHE)
@ -12,5 +13,6 @@ set(OpenMP_C_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_CXX "icpc" CACHE STRING "" FORCE)
set(OpenMP_CXX_FLAGS "-qopenmp" CACHE STRING "" FORCE)
set(OpenMP_CXX_LIB_NAMES "omp" CACHE STRING "" FORCE)
set(OpenMP_Fortran_FLAGS "-qopenmp" CACHE STRING "" FORCE)
set(OpenMP_omp_LIBRARY "libiomp5.so" CACHE PATH "" FORCE)

2
doc/Makefile
View File

@ -65,7 +65,7 @@ DOXYFILES = $(shell sed -n -e 's/\#.*$$//' -e '/^ *INPUT \+=/,/^[A-Z_]\+ \+
help:
@if [ "$(HAS_BASH)" == "NO" ] ; then echo "bash was not found at $(OSHELL)! Please use: $(MAKE) SHELL=/path/to/bash" 1>&2; exit 1; fi
@echo "Please use \`make <target>' where <target> is one of"
@echo " html create HTML doc pages in html dir"
@echo " html create HTML pages in html dir"
@echo " pdf create Manual.pdf in this dir"
@echo " fetch fetch HTML and PDF files from LAMMPS web site"
@echo " epub create ePUB format manual for e-book readers"

27
doc/graphviz/lammps-invoke-python.dot Normal file
View File

@ -0,0 +1,27 @@
// LAMMPS -> Python
digraph api {
rankdir="LR";
edge [constraint=false];
input [shape=box label="LAMMPS\nInput Script" height=1.5];
subgraph cluster0 {
style=filled;
color="#e5e5e5";
rank=same;
capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
capi -> instance [dir=both];
label="LAMMPS Shared Library\nor LAMMPS Executable";
}
python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
subgraph cluster1 {
style=filled;
color="#e5e5e5";
lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
label="LAMMPS Python Module";
}
input -> instance [constraint=true];
instance -> python [dir=both constraint=true];
python:e -> lammps:w [dir=both constraint=true];
lammps:s -> capi:e [dir=both label=ctypes constraint=true];
}

30
doc/graphviz/pylammps-invoke-lammps.dot Normal file
View File

@ -0,0 +1,30 @@
// PyLammps -> LAMMPS
digraph api {
rankdir="LR";
edge [constraint=false];
python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
subgraph cluster0 {
style=filled;
color="#e5e5e5";
height=1.5;
rank=same;
pylammps [shape=box style=filled height=1 color="#729fcf" label="(I)PyLammps"];
lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
pylammps -> lammps [dir=both];
label="LAMMPS Python Module";
}
subgraph cluster1 {
style=filled;
color="#e5e5e5";
height=1.5;
capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
capi -> instance [dir=both constraint=true];
label="LAMMPS Shared Library";
}
python -> pylammps [dir=both constraint=true];
lammps -> capi [dir=both label=ctypes constraint=true];
pylammps:e -> instance:ne [dir=back, style=dashed label="captured standard output"];
}

24
doc/graphviz/python-invoke-lammps.dot Normal file
View File

@ -0,0 +1,24 @@
// Python -> LAMMPS
digraph api {
rankdir="LR";
python [shape=box style=filled color="#4e9a06" fontcolor=white label="Python\nScript" height=1.5];
subgraph cluster0 {
style=filled;
color="#e5e5e5";
height=1.5;
lammps [shape=box style=filled height=1 color="#729fcf" label="lammps\n\nptr: 0x01abcdef"];
label="LAMMPS Python Module";
}
subgraph cluster1 {
style=filled;
color="#e5e5e5";
height=1.5;
capi [shape=box style=filled height=1 color="#666666" fontcolor=white label="LAMMPS\nC Library API"];
instance [shape=box style=filled height=1 color="#3465a4" fontcolor=white label="LAMMPS\ninstance\n\n0x01abcdef"];
capi -> instance [dir=both];
label="LAMMPS Shared Library";
}
python -> lammps [dir=both];
lammps -> capi [dir=both,label=ctypes];
}

2
doc/lammps.1
View File

@ -1,4 +1,4 @@
.TH LAMMPS "18 September 2020" "2020-09-18"
.TH LAMMPS "9 October 2020" "2020-10-09"
.SH NAME
.B LAMMPS
\- Molecular Dynamics Simulator.

1394
doc/src/Bibliography.rst Normal file
View File

File diff suppressed because it is too large Load Diff

3
doc/src/Build.rst
View File

@ -8,7 +8,7 @@ Makefiles, Ninja, Xcode, Visual Studio, KDevelop, CodeBlocks and more).
As an alternative you can download a package with pre-built executables
or automated build trees as described on the :doc:`Install <Install>`
doc page.
page.
.. toctree::
:maxdepth: 1
@ -20,5 +20,6 @@ doc page.
Build_settings
Build_package
Build_extras
Build_manual
Build_windows
Build_development

82
doc/src/Build_basics.rst
View File

@ -8,7 +8,6 @@ CMake and make:
* :ref:`Choice of compiler and compile/link options <compile>`
* :ref:`Build the LAMMPS executable and library <exe>`
* :ref:`Including and removing debug support <debug>`
* :ref:`Build the LAMMPS documentation <doc>`
* :ref:`Install LAMMPS after a build <install>`
----------
@ -134,8 +133,8 @@ support included as well. These are commands in the ``MPIIO``,
``SNAP``, ``USER-DIFFRACTION``, and ``USER-DPD`` packages. In addition
some packages support OpenMP threading indirectly through the libraries
they interface to: e.g. ``LATTE``, ``KSPACE``, and ``USER-COLVARS``.
See the :doc:`Packages details <Packages_details>` doc page for more
info on these packages and the doc pages for their respective commands
See the :doc:`Packages details <Packages_details>` page for more
info on these packages and the pages for their respective commands
for OpenMP threading info.
For CMake, if you use ``BUILD_OMP=yes``, you can use these packages
@ -159,11 +158,11 @@ others (e.g. GCC version 9 and beyond, Clang version 10 and later) may
implement strict OpenMP 4.0 and later semantics, which are incompatible
with the OpenMP 3.1 semantics used in LAMMPS for maximal compatibility
with compiler versions in use. If compilation with OpenMP enabled fails
because of your compiler requiring strict OpenMP 4.0 semantic, you can
because of your compiler requiring strict OpenMP 4.0 semantics, you can
change the behavior by adding ``-D LAMMPS_OMP_COMPAT=4`` to the
``LMP_INC`` variable in your makefile, or add it to the command line
while configuring with CMake. CMake will detect the suitable setting for
the GNU, Clang, and Intel compilers.
while configuring with CMake. LAMMPS will auto-detect a suitable setting
for most GNU, Clang, and Intel compilers.
----------
@ -310,7 +309,7 @@ LAMMPS.
required or recommended to enable required features and to
achieve optimal performance. You need to include these in the
CCFLAGS and LINKFLAGS settings above. For details, see the
individual package doc pages listed on the
documentation for the individual packages listed on the
:doc:`Speed_packages` page. Or examine these files in the
src/MAKE/OPTIONS directory. They correspond to each of the 5
accelerator packages and their hardware variants:
@ -329,6 +328,7 @@ LAMMPS.
----------
.. _exe:
.. _library:
Build the LAMMPS executable and library
---------------------------------------
@ -340,7 +340,7 @@ will then process commands provided via a file or from the console
input. The LAMMPS library can also be called from another application
or a scripting language. See the :doc:`Howto couple <Howto_couple>` doc
page for more info on coupling LAMMPS to other codes. See the
:doc:`Python <Python_head>` doc page for more info on wrapping and
:doc:`Python <Python_head>` page for more info on wrapping and
running LAMMPS from Python via its library interface.
.. tabs::
@ -465,68 +465,6 @@ the debug information from the LAMMPS executable:
----------
.. _doc:
Build the LAMMPS documentation
----------------------------------------
The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
can be translated to different output format using the `Sphinx <sphinx_>`_
document generator tool. Currently the translation to HTML and PDF (via
LaTeX) are supported. For that to work a Python 3 interpreter and
internet access is required. For the documentation build a python
based virtual environment is set up in the folder doc/docenv and various
python packages are installed into that virtual environment via the pip
tool. The actual translation is then done via make commands.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://www.sphinx-doc.org
Documentation makefile options
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following make commands can be issued in the doc folder of the
LAMMPS source distribution.
.. code-block:: bash
make html # create HTML doc pages in html 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
make anchor_check # scan for duplicate anchor labels
make style_check # check for complete and consistent style lists
make package_check # check for complete and consistent package lists
make spelling # spell-check the manual
Thus "make html" will create a "doc/html" directory with the HTML format
manual pages so that you can browse them with a web browser locally on
your system.
.. note::
You can also download a tarball of the documentation for the
current LAMMPS version (HTML and PDF files), from the website
`download page <https://lammps.sandia.gov/download.html>`_.
CMake build options
^^^^^^^^^^^^^^^^^^^
It is also possible to create the HTML version (and only the HTML
version) of the manual within the :doc:`CMake build directory
<Build_cmake>`. The reason for this option is to include the
installation of the HTML manual pages into the "install" step when
installing LAMMPS after the CMake build via ``make install``. The
documentation build is included in the default build target, but can
also be requested independently with ``make doc``.
.. code-block:: bash
-D BUILD_DOC=value # yes or no (default)
----------
.. _tools:
Build LAMMPS tools
@ -542,6 +480,7 @@ using CMake or Make.
.. code-block:: bash
-D BUILD_TOOLS=value # yes or no (default)
-D BUILD_LAMMPS_SHELL=value # yes or no (default)
The generated binaries will also become part of the LAMMPS installation
(see below).
@ -557,6 +496,9 @@ using CMake or Make.
make micelle2d # build only micelle2d tool
make thermo_extract # build only thermo_extract tool
cd lammps/tools/lammps-shell
make # build LAMMPS shell
----------
.. _install:

2
doc/src/Build_extras.rst
View File

@ -18,7 +18,7 @@ in addition to
$ make yes-name
as described on the :doc:`Build_package <Build_package>` doc page.
as described on the :doc:`Build_package <Build_package>` page.
For a CMake build there may be additional optional or required
variables to set. For a build with make, a provided library under the

4
doc/src/Build_make.rst
View File

@ -27,14 +27,14 @@ additional tools to be available and functioning.
* a few shell utilities: ``ls``, ``mv``, ``ln``, ``rm``, ``grep``, ``sed``, ``tr``, ``cat``, ``touch``, ``diff``, ``dirname``
* python (optional, required for ``make lib-<pkg>`` in the src folder).
python scripts are currently tested with python 2.7 and 3.6. The procedure
for :doc:`building the documentation <Manual_build>` requires python 3.
for :doc:`building the documentation <Build_manual>` requires python 3.5 or later.
Getting started
^^^^^^^^^^^^^^^
To include LAMMPS packages (i.e. optional commands and styles) you must
enable (or "install") them first, as discussed on the :doc:`Build
package <Build_package>` doc page. If a packages requires (provided or
package <Build_package>` page. If a packages requires (provided or
external) libraries, you must configure and build those libraries
**before** building LAMMPS itself and especially **before** enabling
such a package with ``make yes-<package>``. :doc:`Building LAMMPS with

137
doc/src/Manual_build.rst → doc/src/Build_manual.rst
View File

@ -1,5 +1,5 @@
Building the LAMMPS manual
**************************
Build the LAMMPS documentation
==============================
Depending on how you obtained LAMMPS and whether you have built the
manual yourself, this directory has a number of sub-directories and
@ -32,37 +32,59 @@ and PDF files are not included. Instead you need to create them, in one
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 a Manual_www.pdf file. Note that if new LAMMPS features
site. Just type ``make fetch``. This should download a ``html_www``
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 repository).
b. You can build the HTML or PDF files yourself, by typing ``make html``
or ``make pdf``. This requires various tools and files. Some of them
have to be installed (more on that below). For the rest the build
process will attempt to download and install them into a python
virtual environment and local folders. This download is required
only once, unless you type ``make clean-all``. After that, viewing and
processing of the documentation can be done without internet access.
or ``make pdf`` in the ``doc`` folder. This requires various tools
and files. Some of them have to be installed (see below). For the
rest the build process will attempt to download and install them into
a python virtual environment and local folders.
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/>`_
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/>`_
----------
Build using GNU make
--------------------
The generation of all documentation is managed by the Makefile in the
doc directory. The following documentation related make commands are
available:
The LAMMPS manual is written in `reStructuredText <rst_>`_ format which
can be translated to different output format using the `Sphinx
<sphinx_>`_ document generator tool. It also incorporates programmer
documentation extracted from the LAMMPS C++ sources through the `Doxygen
<https://doxygen.nl>`_ program. Currently the translation to HTML, PDF
(via LaTeX), ePUB (for many e-book readers) and MOBI (for Amazon Kindle
readers) are supported. For that to work a Python 3 interpreter, the
``doxygen`` tools and internet access to download additional files and
tools are required. This download is usually only required once or
after the documentation folder is returned to a pristine state with
``make clean-all``.
.. _rst: https://docutils.readthedocs.io/en/sphinx-docs/user/rst/quickstart.html
.. _sphinx: https://www.sphinx-doc.org
For the documentation build a python virtual environment is set up in
the folder ``doc/docenv`` and various python packages are installed into
that virtual environment via the ``pip`` tool. For rendering embedded
LaTeX code also the `MathJax <https://www.mathjax.org/>`_ and the
`Polyfill <https://polyfill.io/>`_ JavaScript engines need to be downloaded.
The actual translation is then done via ``make`` commands in the doc
folder. The following ``make`` commands are available:
.. code-block:: bash
make html # generate HTML in html dir using Sphinx
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 fetch # fetch HTML pages and PDF files from LAMMPS web site
# and unpack into the html_www folder and Manual_www.pdf
make epub # generate LAMMPS.epub in ePUB format using Sphinx
make mobi # generate LAMMPS.mobi in MOBI format using ebook-convert
@ -76,66 +98,79 @@ available:
----------
Installing prerequisites for HTML build
=======================================
Build using CMake
-----------------
It is also possible to create the HTML version (and **only** the HTML
version) of the manual within the :doc:`CMake build directory
<Build_cmake>`. The reason for this option is to include the
installation of the HTML manual pages into the "install" step when
installing LAMMPS after the CMake build via ``cmake --build . --target
install``. The documentation build is included in the default build
target, but can also be requested independently with
``cmake --build . --target doc``.
.. code-block:: bash
-D BUILD_DOC=value # yes or no (default)
----------
Prerequisites for HTML
----------------------
To run the HTML documentation build toolchain, python 3, git, doxygen,
and virtualenv have to be installed locally. Here are instructions for
common setups:
Ubuntu
------
.. tabs::
.. code-block:: bash
.. tab:: Ubuntu
.. code-block:: bash
sudo apt-get install python-virtualenv git doxygen
Fedora (up to version 21) and Red Hat Enterprise Linux or CentOS (up to version 7.x)
------------------------------------------------------------------------------------
.. tab:: RHEL or CentOS (Version 7.x)
.. code-block:: bash
.. code-block:: bash
sudo yum install python3-virtualenv git doxygen
Fedora (since version 22)
-------------------------
.. tab:: Fedora or RHEL/CentOS (8.x or later)
.. code-block:: bash
.. code-block:: bash
sudo dnf install python3-virtualenv git doxygen
MacOS X
-------
.. tab:: MacOS X
Python 3
^^^^^^^^
*Python 3*
Download the latest Python 3 MacOS X package from
`https://www.python.org <https://www.python.org>`_
and install it. This will install both Python 3
and pip3.
Download the latest Python 3 MacOS X package from
`https://www.python.org <https://www.python.org>`_ and install it.
This will install both Python 3 and pip3.
virtualenv
^^^^^^^^^^
*virtualenv*
Once Python 3 is installed, open a Terminal and type
Once Python 3 is installed, open a Terminal and type
.. code-block:: bash
.. code-block:: bash
pip3 install virtualenv
This will install virtualenv from the Python Package Index.
This will install virtualenv from the Python Package Index.
Installing prerequisites for PDF build
======================================
Prerequisites for PDF
---------------------
In addition to the tools needed for building the HTML format manual,
a working LaTeX installation with support for PDFLaTeX and a selection
of LaTeX styles/packages are required. To run the PDFLaTeX translation
the ``latexmk`` script needs to be installed as well.
Installing prerequisites for e-book reader builds
=================================================
Prerequisites for ePUB and MOBI
-------------------------------
In addition to the tools needed for building the HTML format manual,
a working LaTeX installation with a few add-on LaTeX packages
@ -152,12 +187,12 @@ files, so you could download and view the PDF version as an alternative.
Instructions for Developers
===========================
---------------------------
When adding new styles or options to the LAMMPS code, corresponding
documentation is required and either existing files in the ``src``
folder need to be updated or new files added. These files are written
in `reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
folder need to be updated or new files added. These files are written in
`reStructuredText <rst_>`_ markup for translation with the Sphinx tool.
Before contributing any documentation, please check that both the HTML
and the PDF format documentation can translate without errors. Please also

4
doc/src/Build_package.rst
View File

@ -7,7 +7,7 @@ rigid-body constraints are in packages. In the src directory, each
package is a sub-directory with the package name in capital letters.
An overview of packages is given on the :doc:`Packages <Packages>` doc
page. Brief overviews of each package are on the :doc:`Packages details <Packages_details>` doc page.
page. Brief overviews of each package are on the :doc:`Packages details <Packages_details>` page.
When building LAMMPS, you can choose to include or exclude each
package. In general there is no need to include a package if you
@ -25,7 +25,7 @@ when building that executable.
For the majority of packages, if you follow the single step below to
include it, you can then build LAMMPS exactly the same as you would
without any packages installed. A few packages may require additional
steps, as explained on the :doc:`Build extras <Build_extras>` doc page.
steps, as explained on the :doc:`Build extras <Build_extras>` page.
These links take you to the extra instructions for those select
packages:

13
doc/src/Build_settings.rst
View File

@ -122,7 +122,7 @@ communication can be costly). A breakdown of these timings is printed
to the screen at the end of a run when using the
:doc:`kspace_style pppm <kspace_style>` command. The
:doc:`Screen and logfile output <Run_output>`
doc page gives more details. A more detailed (and time consuming)
page gives more details. A more detailed (and time consuming)
report of the FFT performance is generated with the
:doc:`kspace_modify fftbench yes <kspace_modify>` command.
@ -266,12 +266,11 @@ in neighbor lists for storing special bonds info).
Image flags store 3 values per atom in a single integer which count the
number of times an atom has moved through the periodic box in each
dimension. See the :doc:`dump <dump>` doc page for a discussion. If an
atom moves through the periodic box more than this limit, the value will
"roll over", e.g. from 511 to -512, which can cause diagnostics like the
mean-squared displacement, as calculated by the :doc:`compute msd
<compute_msd>` command, to be faulty.
dimension. See the :doc:`dump <dump>` manual page for a discussion. If
an atom moves through the periodic box more than this limit, the value
will "roll over", e.g. from 511 to -512, which can cause diagnostics
like the mean-squared displacement, as calculated by the :doc:`compute
msd <compute_msd>` command, to be faulty.
Also note that the GPU package requires its lib/gpu library to be
compiled with the same size setting, or the link will fail. A CMake

8
doc/src/pg_dev_classes.rst → doc/src/Classes.rst
View File

@ -5,7 +5,7 @@ LAMMPS is designed to be used as a C++ class library where one can set
up and drive a simulation through creating a class instance and then
calling some abstract operations or commands on that class or its member
class instances. These are interfaced to the :doc:`C library API
<pg_library>`, which providing an additional level of abstraction
<Library>`, which providing an additional level of abstraction
simplification for common operations. The C API is also the basis for
calling LAMMPS from Python or Fortran.
@ -33,6 +33,6 @@ some selected examples for derived classes of specific models.
:caption: Individual Base Classes
:name: lammpsbase
pg_lammps
pg_atom
pg_input
Classes_lammps
Classes_atom
Classes_input

0
doc/src/pg_atom.rst → doc/src/Classes_atom.rst
View File

0
doc/src/pg_input.rst → doc/src/Classes_input.rst
View File

0
doc/src/pg_lammps.rst → doc/src/Classes_lammps.rst
View File

1
doc/src/Commands_pair.rst
View File

@ -81,6 +81,7 @@ OPT.
* :doc:`coul/slater/long <pair_coul_slater>`
* :doc:`coul/shield <pair_coul_shield>`
* :doc:`coul/streitz <pair_coul>`
* :doc:`coul/tt <pair_coul_tt>`
* :doc:`coul/wolf (ko) <pair_coul>`
* :doc:`coul/wolf/cs <pair_cs>`
* :doc:`dpd (gio) <pair_dpd>`

0
doc/src/pg_cplusplus.rst → doc/src/Cplusplus.rst
View File

10
doc/src/pg_developer.rst → doc/src/Developer.rst
View File

@ -10,8 +10,8 @@ of time and requests from the LAMMPS user community.
.. toctree::
:maxdepth: 1
pg_dev_org
pg_dev_flow
pg_dev_write
pg_dev_utils
pg_dev_classes
Developer_org
Developer_flow
Developer_write
Developer_utils
Classes

0
doc/src/pg_dev_flow.rst → doc/src/Developer_flow.rst
View File

0
doc/src/pg_dev_org.rst → doc/src/Developer_org.rst
View File

0
doc/src/pg_dev_utils.rst → doc/src/Developer_utils.rst
View File

0
doc/src/pg_dev_write.rst → doc/src/Developer_write.rst
View File

12
doc/src/Errors_messages.rst
View File

@ -3005,9 +3005,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
*Dump image line requires atom style line*
Self-explanatory.
*Dump image persp option is not yet supported*
Self-explanatory.
*Dump image requires one snapshot per file*
Use a "\*" in the filename.
@ -5108,9 +5105,6 @@ Doc page with :doc:`WARNING messages <Errors_warnings>`
The file produced by dump image cannot be binary and must
be for a single processor.
*Invalid dump image persp value*
Persp value must be >= 0.0.
*Invalid dump image theta value*
Theta must be between 0.0 and 180.0 inclusive.
@ -8116,9 +8110,6 @@ keyword to allow for additional bonds to be formed
*Variable for dump image center is invalid style*
Must be an equal-style variable.
*Variable for dump image persp is invalid style*
Must be an equal-style variable.
*Variable for dump image phi is invalid style*
Must be an equal-style variable.
@ -8259,9 +8250,6 @@ keyword to allow for additional bonds to be formed
*Variable name for dump image center does not exist*
Self-explanatory.
*Variable name for dump image persp does not exist*
Self-explanatory.
*Variable name for dump image phi does not exist*
Self-explanatory.

11
doc/src/pg_fortran.rst → doc/src/Fortran.rst
View File

@ -24,15 +24,24 @@ 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
.. versionadded:: 9Oct2020
.. admonition:: Work in Progress
:class: note
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.
.. note::
A contributed (and complete!) Fortran interface that is more
closely resembling the C-library interface is available
in the ``examples/COUPLE/fortran2`` folder. Please see the
``README`` file in that folder for more information about that
Fortran interface and how to contact its author and maintainer.
----------
Creating or deleting a LAMMPS object

25
doc/src/Howto.rst
View File

@ -9,18 +9,6 @@ example input scripts included in the examples directory of the LAMMPS
distribution and highlighted on the :doc:`Examples <Examples>` doc page
also show how to setup and run various kinds of simulations.
Tutorials howto
===============
.. toctree::
:name: tutorials
:maxdepth: 1
Howto_cmake
Howto_github
Howto_pylammps
Howto_wsl
General howto
=============
@ -94,3 +82,16 @@ Packages howto
Howto_drude2
Howto_manifold
Howto_spins
Tutorials howto
===============
.. toctree::
:name: tutorials
:maxdepth: 1
Howto_cmake
Howto_github
Howto_pylammps
Howto_wsl

2
doc/src/Howto_cmake.rst
View File

@ -328,6 +328,8 @@ Some common LAMMPS specific variables
- build LAMMPS with OpenMP support (default: ``on`` if compiler supports OpenMP fully, else ``off``)
* - ``BUILD_TOOLS``
- compile some additional executables from the ``tools`` folder (default: ``off``)
* - ``BUILD_LAMMPS_SHELL``
- compile the LAMMPS shell from the ``tools/lammps-shell`` folder (default: ``off``)
* - ``BUILD_DOC``
- include building the HTML format documentation for packaging/installing (default: ``off``)
* - ``CMAKE_TUNE_FLAGS``

2
doc/src/Howto_couple.rst
View File

@ -54,7 +54,7 @@ context of your application.
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.
<Library>` documentation.
.. spacer

6
doc/src/Howto_library.rst
View File

@ -20,8 +20,8 @@ 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
and is also the basis for the :doc:`Python <Python_module>` and
:doc:`Fortran <Fortran>` interfaces or wrappers included in the
LAMMPS source code.
The ``examples/COUPLE`` and ``python/examples`` directories contain some
@ -33,5 +33,5 @@ LAMMPS.
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.
<Library>` section of this manual.

2
doc/src/Howto_pylammps.rst
View File

@ -11,7 +11,7 @@ on its own or use an existing lammps Python object. It creates a simpler,
more "pythonic" interface to common LAMMPS functionality, in contrast to
the ``lammps.py`` wrapper for the C-style LAMMPS library interface which
is written using `Python ctypes <ctypes_>`_. The ``lammps.py`` wrapper
is discussed on the :doc:`Python library <Python_library>` doc page.
is discussed on the :doc:`Python_head` doc page.
Unlike the flat ``ctypes`` interface, PyLammps exposes a discoverable
API. It no longer requires knowledge of the underlying C++ code

2
doc/src/Install_git.rst
View File

@ -94,7 +94,7 @@ changed. To do this, you should cd to the src directory and type:
$ make package-update # sync package files with src files
$ make foo # re-build for your machine (mpi, serial, etc)
just as described on the :doc:`Apply patch <Install_patch>` doc page,
just as described on the :doc:`Apply patch <Install_patch>` page,
after a patch has been installed.
.. warning::

2
doc/src/Install_patch.rst
View File

@ -10,7 +10,7 @@ If you prefer to download a tarball, as described on the
:doc:`tarball download <Install_tarball>` page, you can stay current by
downloading "patch files" when new patch releases are made. A link to
a patch file is posted on the
`bugf fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
`bug fixes and new feature page <https://lammps.sandia.gov/bug.html>`_
of the LAMMPS website, along
with a list of changed files and details about what is in the new patch
release. This page explains how to apply the patch file to your local

2
doc/src/Install_tarball.rst
View File

@ -61,4 +61,4 @@ periodically.)
The patch files are posted on the `bug and feature page <bug_>`_ of the
website, along with a list of changed files and details about what is
in the new patch release. Instructions for applying a patch file are
on the :doc:`Install patch <Install_patch>` doc page.
on the :doc:`Install patch <Install_patch>` page.

16
doc/src/Install_windows.rst
View File

@ -12,14 +12,20 @@ Note that each installer package has a date in its name, which
corresponds to the LAMMPS version of the same date. Installers for
current and older versions of LAMMPS are available. 32-bit and 64-bit
installers are available, and each installer contains both a serial
and parallel executable. The installer site also explains how to
and parallel executable. The installer web site also explains how to
install the Windows MPI package (MPICH2 from Argonne National Labs),
needed to run in parallel.
The LAMMPS binaries contain all optional packages included in the
source distribution except: KIM, KOKKOS, USER-INTEL, and USER-QMMM.
The LAMMPS binaries contain *all* :doc:`optional packages <Packages>`
included in the source distribution except: KIM, KOKKOS, MSCG, PYTHON,
USER-ADIOS, USER-H5MD, USER-NETCDF, USER-QMMM, USER-QUIP, and USER-VTK.
The serial version also does not include the MPIIO and
USER-LB packages. GPU support is provided for OpenCL.
USER-LB packages. The GPU package is compiled for OpenCL with
mixed precision kernels.
The LAMMPS library is compiled as a shared library and the
:doc:`LAMMPS Python module <Python_module>` is installed, so that
it is possible to load LAMMPS into a Python interpreter.
The installer site also has instructions on how to run LAMMPS under
Windows, once it is installed, in both serial and parallel.
@ -42,5 +48,3 @@ install multiple versions of LAMMPS (in different directories), but
only the executable for the last-installed package will be found
automatically, so this should only be done for debugging purposes.
Thanks to Axel Kohlmeyer (Temple U, akohlmey at gmail.com) for setting
up this Windows capability.

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

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 245 KiB

After

Width:  |  Height:  |  Size: 266 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 36 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

167
doc/src/Library.rst Normal file
View File

@ -0,0 +1,167 @@
LAMMPS Library Interfaces
*************************
As described on the :doc:`library interface to LAMMPS <Howto_library>`
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.
Most of the APIs described below 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
:cpp:class:`LAMMPS <LAMMPS_NS::LAMMPS>`, pass commands as strings or
from files to that LAMMPS instance to execute calculations, and/or
call functions that read, manipulate, and update data from the active
class instances inside LAMMPS to do analysis or perform operations
that are not possible with existing input script 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 the most commonly used path to manage LAMMPS
instances from a compiled code and it is the basis for the :doc:`Python
<Python_module>` and :doc:`Fortran <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 does not include the ``mpi.h``
header file and thus hides the :cpp:func:`lammps_open` function which
requires the declaration of the ``MPI_comm`` data type. This is only
a problem when the communicator that would be passed is different from
``MPI_COMM_WORLD``. Otherwise calling :cpp:func:`lammps_open_no_mpi`
will work just as well. To make :cpp:func:`lammps_open` available,
you need to compile the code with ``-DLAMMPS_LIB_MPI`` or add the line
``#define LAMMPS_LIB_MPI`` before ``#include "library.h"``.
Please note the ``mpi.h`` file must usually be the same (and thus the
MPI library in use) for the LAMMPS code and library and the calling code.
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 so long as :cpp:func:`lammps_open_no_mpi`
is called to create a LAMMPS instance. In that case each MPI rank will
run LAMMPS in serial mode.
.. admonition:: Errors versus exceptions
:class: note
If the LAMMPS executable encounters an error condition, it will abort
after printing an error message. For a library interface this is
usually not desirable. Thus LAMMPS can be compiled to to :ref:`throw
a C++ exception <exceptions>` instead. If enabled, the library
functions will catch those exceptions and return. The error status
:cpp:func:`can be queried <lammps_has_error>` and an :cpp:func:`error
message retrieved <lammps_get_last_error_message>`. We thus
recommend enabling C++ exceptions when using the library interface,
.. 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 must 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
Library_create
Library_execute
Library_properties
Library_atoms
Library_objects
Library_scatter
Library_neighbor
Library_config
Library_utility
Library_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 tries to be very similar to the C library API. Three different
Python classes to run LAMMPS are available and they build on each other.
More information on this is in the :doc:`Python_head`
section of the manual. Use of the LAMMPS Python module is described in
:doc:`Python_module`.
-------------------
.. _lammps_fortran_api:
LAMMPS Fortran API
==================
The LAMMPS Fortran module is a wrapper around calling functions from the
LAMMPS C library API. This is done using the ISO_C_BINDING feature in
Fortran 2003. The interface is object oriented but otherwise tries to
be very similar to the C library API and the basic Python module.
.. toctree::
:maxdepth: 1
Fortran
-------------------
.. _lammps_cplusplus_api:
LAMMPS C++ API
==============
It is also possible to invoke the LAMMPS C++ API directly in your code.
It lacks some of the convenience of the C library API, but it allows
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
Cplusplus

36
doc/src/Library_add.rst Normal file
View File

@ -0,0 +1,36 @@
Extending the C API
===================
The functionality of the LAMMPS library interface has historically
been motivated by the needs of its users. Functions have been 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 Spring 2020,
there are now a few requirements for including new changes or extensions.
- 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://doxygen.nl>`_ 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.
- New features should also be implemented and documented not just
for the C interface, but also the Python and Fortran interfaces.
- All additions should work and be compatible with ``-DLAMMPS_BIGBIG``,
``-DLAMMPS_SMALLBIG``, ``-DLAMMPS_SMALLSMALL`` as well as when
compiling with and without MPI support.
- The ``library.h`` file should be kept compatible to C code at
a level similar to C89. Its interfaces may not reference any
custom data types (e.g. ``bigint``, ``tagint``, and so on) that
are only known inside of LAMMPS; instead ``int`` and ``int64_t``
should be used.
- only use C style comments, not C++ style
Please note that these are not **strict** requirements, but the LAMMPS
developers very much appreciate, if they are followed and can assist
with implementing what is missing. It helps maintaining the code base
and keeping it consistent.

18
doc/src/Library_atoms.rst Normal file
View File

@ -0,0 +1,18 @@
Per-atom properties
===================
This section documents the following functions:
- :cpp:func:`lammps_extract_atom_datatype`
- :cpp:func:`lammps_extract_atom`
-----------------------
.. doxygenfunction:: lammps_extract_atom_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_atom
:project: progguide

75
doc/src/pg_lib_config.rst → doc/src/Library_config.rst
View File

@ -1,18 +1,40 @@
Retrieving LAMMPS configuration information
===========================================
Configuration information
=========================
The following library functions can be used to query the LAMMPS library
about compile time settings and included packages and styles. This
enables programs that use the library interface to run LAMMPS
simulations to determine, whether the linked LAMMPS library is compatible
with the requirements of the application without crashing during the
LAMMPS functions (e.g. due to missing pair styles from packages) or to
choose between different options (e.g. whether to use ``lj/cut``,
``lj/cut/opt``, ``lj/cut/omp`` or ``lj/cut/intel``). Most of the
functions can be called directly without first creating a LAMMPS
instance. While crashes within LAMMPS may be recovered from through
enabling :ref:`exceptions <exceptions>`, avoiding them proactively is
a safer approach.
This section documents the following functions:
- :cpp:func:`lammps_version`
- :cpp:func:`lammps_get_os_info`
- :cpp:func:`lammps_config_has_mpi_support`
- :cpp:func:`lammps_config_has_gzip_support`
- :cpp:func:`lammps_config_has_png_support`
- :cpp:func:`lammps_config_has_jpeg_support`
- :cpp:func:`lammps_config_has_ffmpeg_support`
- :cpp:func:`lammps_config_has_exceptions`
- :cpp:func:`lammps_config_has_package`
- :cpp:func:`lammps_config_package_count`
- :cpp:func:`lammps_config_package_name`
- :cpp:func:`lammps_has_style`
- :cpp:func:`lammps_style_count`
- :cpp:func:`lammps_style_name`
- :cpp:func:`lammps_has_id`
- :cpp:func:`lammps_id_count`
- :cpp:func:`lammps_id_name`
--------------------
These library functions can be used to query the LAMMPS library for
compile time settings and included packages and styles. This enables
programs that use the library interface to determine whether the
linked LAMMPS library is compatible with the requirements of the
application without crashing during the LAMMPS functions (e.g. due to
missing pair styles from packages) or to choose between different
options (e.g. whether to use ``lj/cut``, ``lj/cut/opt``,
``lj/cut/omp`` or ``lj/cut/intel``). Most of the functions can be
called directly without first creating a LAMMPS instance. While
crashes within LAMMPS may be recovered from by enabling
:ref:`exceptions <exceptions>`, avoiding them proactively is a safer
approach.
.. code-block:: C
:caption: Example for using configuration settings functions
@ -49,6 +71,16 @@ a safer approach.
-----------------------
.. doxygenfunction:: lammps_version
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_os_info
:project: progguide
-----------------------
.. doxygenfunction:: lammps_config_has_mpi_support
:project: progguide
@ -107,3 +139,18 @@ a safer approach.
.. doxygenfunction:: lammps_style_name
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_id
:project: progguide
-----------------------
.. doxygenfunction:: lammps_id_count
:project: progguide
-----------------------
.. doxygenfunction:: lammps_id_name
:project: progguide

116
doc/src/Library_create.rst Normal file
View File

@ -0,0 +1,116 @@
Creating or deleting a LAMMPS object
====================================
This section documents the following functions:
- :cpp:func:`lammps_open`
- :cpp:func:`lammps_open_no_mpi`
- :cpp:func:`lammps_open_fortran`
- :cpp:func:`lammps_close`
- :cpp:func:`lammps_mpi_init`
- :cpp:func:`lammps_mpi_finalize`
- :cpp:func:`lammps_free`
--------------------
The :cpp:func:`lammps_open` and :cpp:func:`lammps_open_no_mpi` functions
are used to create and initialize a :cpp:func:`LAMMPS` instance. They
return a reference to this instance as a ``void *`` pointer to be used
as the "handle" argument in 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 uses 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 passed as 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 one 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 invoking ``MPI_Finalize()`` explicitly from the
calling program.
The :cpp:func:`lammps_free` function is a clean-up
function to free memory that the library allocated previously
via other function calls. See below for notes in the descriptions
of the individual commands where such memory buffers were allocated.
-----------------------
.. doxygenfunction:: lammps_open
: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

40
doc/src/pg_lib_execute.rst → doc/src/Library_execute.rst
View File

@ -1,5 +1,14 @@
Executing LAMMPS commands
=========================
Executing commands
==================
This section documents the following functions:
- :cpp:func:`lammps_file`
- :cpp:func:`lammps_command`
- :cpp:func:`lammps_commands_list`
- :cpp:func:`lammps_commands_string`
--------------------
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
@ -7,23 +16,26 @@ 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.
Via these functions, the calling code can have LAMMPS act on a series
of :doc:`input file commands <Commands_all>` that are either read from
a file or passed as strings. For example, this allows setup of a
problem from an input script, and then running it in stages while
performing other operations in between or concurrently. The caller
can interleave the LAMMPS function calls with operations it performs,
such as 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.
Just as with :doc:`input script parsing <Commands_parse>` comments can
be included in the file or strings, and expansion of variables with
``${name}`` or ``$(expression)`` syntax is performed.
Below is a short example using some of these functions.
.. code-block:: C
/* define to make the otherwise hidden prototype for "lammps_open()" visible */
#define LAMMPS_LIB_MPI
#include "library.h"
#include <mpi.h>
#include <stdio.h>

14
doc/src/pg_lib_neighbor.rst → doc/src/Library_neighbor.rst
View File

@ -1,8 +1,14 @@
Accessing LAMMPS Neighbor lists
===============================
Neighbor list access
====================
The following functions allow to access neighbor lists
generated by LAMMPS or query their properties.
The following functions enable access to neighbor lists generated by
LAMMPS or querying of their properties:
- :cpp:func:`lammps_find_compute_neighlist`
- :cpp:func:`lammps_find_fix_neighlist`
- :cpp:func:`lammps_find_pair_neighlist`
- :cpp:func:`lammps_neighlist_num_elements`
- :cpp:func:`lammps_neighlist_element_neighbors`
-----------------------

13
doc/src/pg_lib_objects.rst → doc/src/Library_objects.rst
View File

@ -1,8 +1,13 @@
Retrieving or setting properties of LAMMPS objects
==================================================
Compute, fixes, variables
=========================
This section documents accessing or modifying data from objects like
computes, fixes, or variables in LAMMPS.
This section documents accessing or modifying data stored by computes,
fixes, or variables in LAMMPS using the following functions:
- :cpp:func:`lammps_extract_compute`
- :cpp:func:`lammps_extract_fix`
- :cpp:func:`lammps_extract_variable`
- :cpp:func:`lammps_set_variable`
-----------------------

116
doc/src/Library_properties.rst Normal file
View File

@ -0,0 +1,116 @@
System properties
=================
This section documents the following functions:
- :cpp:func:`lammps_get_natoms`
- :cpp:func:`lammps_get_thermo`
- :cpp:func:`lammps_extract_box`
- :cpp:func:`lammps_reset_box`
- :cpp:func:`lammps_memory_usage`
- :cpp:func:`lammps_get_mpi_comm`
- :cpp:func:`lammps_extract_setting`
- :cpp:func:`lammps_extract_global_datatype`
- :cpp:func:`lammps_extract_global`
--------------------
The library interface allows extraction of different kinds of
information about the active simulation instance and also
modifications to it. This enables combining of a LAMMPS simulation
with other processing and simulation methods computed by the calling
code, or by another code that is coupled to LAMMPS via the library
interface. In some cases the data returned is direct 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 for the calling program to
access it, and you may need to know the correct dimensions and
lengths. This also means you can directly change those value(s) from
the calling program, e.g. to modify atom positions. Of course, this
should be done with care. When accessing per-atom data, please note
that this data is the per-processor **local** data and is indexed
accordingly. Per-atom data can change sizes and ordering at every
neighbor list rebuild or atom sort event as atoms migrate between
sub-domains and processors.
.. code-block:: C
#include "library.h"
#include <stdio.h>
int main(int argc, char **argv)
{
void *handle;
int i;
handle = lammps_open_no_mpi(0, NULL, NULL);
lammps_file(handle,"in.sysinit");
printf("Running a simulation with %g atoms.\n",
lammps_get_natoms(handle));
printf(" %d local and %d ghost atoms. %d atom types\n",
lammps_extract_setting(handle,"nlocal"),
lammps_extract_setting(handle,"nghost"),
lammps_extract_setting(handle,"ntypes"));
double *dt = (double *)lammps_extract_global(handle,"dt");
printf("Changing timestep from %g to 0.5\n", *dt);
*dt = 0.5;
lammps_command(handle,"run 1000 post no");
for (i=0; i < 10; ++i) {
lammps_command(handle,"run 100 pre no post no");
printf("PE = %g\nKE = %g\n",
lammps_get_thermo(handle,"pe"),
lammps_get_thermo(handle,"ke"));
}
lammps_close(handle);
return 0;
}
-----------------------
.. 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_memory_usage
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_mpi_comm
:project: progguide
-------------------
.. doxygenfunction:: lammps_extract_setting
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_global_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_global
:project: progguide

82
doc/src/Library_scatter.rst Normal file
View File

@ -0,0 +1,82 @@
Scatter/gather operations
=========================
This section has functions which gather per-atom data from one or more
processors into a contiguous global list ordered by atom ID. The same
list is returned to all calling processors. It also contains
functions which scatter per-atom data from a contiguous global list
across the processors that own those atom IDs. It also has a
create_atoms() function which can create new atoms by scattering them
appropriately to owning processors in the LAMMPS spatial
decomposition.
It documents the following functions:
- :cpp:func:`lammps_gather_atoms`
- :cpp:func:`lammps_gather_atoms_concat`
- :cpp:func:`lammps_gather_atoms_subset`
- :cpp:func:`lammps_scatter_atoms`
- :cpp:func:`lammps_scatter_atoms_subset`
- :cpp:func:`lammps_gather`
- :cpp:func:`lammps_gather_concat`
- :cpp:func:`lammps_gather_subset`
- :cpp:func:`lammps_scatter`
- :cpp:func:`lammps_scatter_subset`
- :cpp:func:`lammps_create_atoms`
-----------------------
.. 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
-----------------------
.. doxygenfunction:: lammps_gather
:project: progguide
-----------------------
.. doxygenfunction:: lammps_gather_concat
:project: progguide
-----------------------
.. doxygenfunction:: lammps_gather_subset
:project: progguide
-----------------------
.. doxygenfunction:: lammps_scatter
:project: progguide
-----------------------
.. doxygenfunction:: lammps_scatter_subset
:project: progguide
-----------------------
.. doxygenfunction:: lammps_create_atoms(void *handle, int n, int *id, int *type, double *x, double *v, int *image, int bexpand)
:project: progguide

60
doc/src/Library_utility.rst Normal file
View File

@ -0,0 +1,60 @@
Utility functions
=================
To simplify some tasks, the library interface contains these utility
functions. They do not directly call the LAMMPS library.
- :cpp:func:`lammps_encode_image_flags`
- :cpp:func:`lammps_decode_image_flags`
- :cpp:func:`lammps_set_fix_external_callback`
- :cpp:func:`lammps_fix_external_set_energy_global`
- :cpp:func:`lammps_fix_external_set_virial_global`
- :cpp:func:`lammps_is_running`
- :cpp:func:`lammps_force_timeout`
- :cpp:func:`lammps_has_error`
- :cpp:func:`lammps_get_last_error_message`
-----------------------
.. 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_fix_external_set_energy_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_fix_external_set_virial_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_is_running
:project: progguide
-----------------------
.. doxygenfunction:: lammps_force_timeout
:project: progguide
-----------------------
.. doxygenfunction:: lammps_has_error
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_last_error_message
:project: progguide

21
doc/src/Manual.rst
View File

@ -19,10 +19,10 @@ 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.
The manual is organized in two parts:
The content for this manual is part of the LAMMPS distribution. You can
build a local copy of the Manual as HTML pages or a PDF file, by
following the steps on the :doc:`Build_manual` page. The manual is
organized in two parts:
1) the :ref:`User documentation <user_documentation>` for how to install
and use LAMMPS and 2) the :ref:`Programmer documentation <programmer_documentation>`
for how to write programs using the LAMMPS library from different
@ -30,8 +30,9 @@ programming languages and how to modify and extend LAMMPS.
.. only:: html
Once you are familiar with LAMMPS, you may want to bookmark :doc:`this page <Commands_all>` since it gives quick access to a doc page for
every LAMMPS command.
Once you are familiar with LAMMPS, you may want to bookmark
:doc:`this page <Commands_all>` since it gives quick access
the documentation for all LAMMPS commands.
.. _lws: https://lammps.sandia.gov
@ -58,9 +59,7 @@ User Documentation
Howto
Examples
Tools
Python_head
Errors
Manual_build
Programmer Documentation
************************
@ -73,9 +72,10 @@ Programmer Documentation
:name: progdoc
:includehidden:
pg_library
Library
Python_head
Modify
pg_developer
Developer
.. toctree::
:caption: Index
@ -91,6 +91,7 @@ Programmer Documentation
dihedrals
impropers
fix_modify_atc_commands
Bibliography
Indices and tables
******************

4
doc/src/Manual_version.rst
View File

@ -17,7 +17,7 @@ run LAMMPS. It is also in the file src/version.h and in the LAMMPS
directory name created when you unpack a tarball. And it is on the
first page of the :doc:`manual <Manual>`.
* If you browse the HTML doc pages on the LAMMPS WWW site, they always
* If you browse the HTML pages on the LAMMPS WWW site, they always
describe the most current patch release of LAMMPS.
* If you browse the HTML doc pages included in your tarball, they
* If you browse the HTML pages included in your tarball, they
describe the version you have, which may be older.

2
doc/src/Modify_overview.rst
View File

@ -56,7 +56,7 @@ the executable and can be invoked with a pair_style command like the
example above. Arguments like 0.1 and 3.5 can be defined and
processed by your new class.
.. note:
.. note::
With the traditional make process, simply adding the new files to the
src folder and compiling LAMMPS again for the desired configuration

33
doc/src/Python_call.rst
View File

@ -1,5 +1,5 @@
Call Python from a LAMMPS input script
======================================
Calling Python from a LAMMPS input script
*****************************************
LAMMPS has several commands which can be used to invoke Python
code directly from an input script:
@ -47,32 +47,3 @@ See the :doc:`python <python>` doc page and the :doc:`variable <variable>`
doc page for its python-style variables for more info, including
examples of Python code you can write for both pure Python operations
and callbacks to LAMMPS.
The :doc:`fix python/invoke <fix_python_invoke>` command can execute
Python code at selected timesteps during a simulation run.
The :doc:`pair_style python <pair_python>` command allows you to define
pairwise potentials as python code which encodes a single pairwise
interaction. This is useful for rapid development and debugging of a
new potential.
To use any of these commands, you only need to build LAMMPS with the
PYTHON package installed:
.. code-block:: bash
make yes-python
make machine
Note that this will link LAMMPS with the Python library on your
system, which typically requires several auxiliary system libraries to
also be linked. The list of these libraries and the paths to find
them are specified in the lib/python/Makefile.lammps file. You need
to insure that file contains the correct information for your version
of Python and your machine to successfully build LAMMPS. See the
lib/python/README file for more info.
If you want to write Python code with callbacks to LAMMPS, then you
must also follow the steps summarized in the :doc:`Python run <Python_run>` doc page. I.e. you must build LAMMPS as a shared
library and insure that Python can find the python/lammps.py file and
the shared library.

45
doc/src/Python_config.rst Normal file
View File

@ -0,0 +1,45 @@
Retrieving LAMMPS configuration information
*******************************************
The following methods can be used to query the LAMMPS library
about compile time settings and included packages and styles.
.. code-block:: Python
:caption: Example for using configuration settings functions
from lammps import lammps
lmp = lammps()
try:
lmp.file("in.missing")
except Exception as e:
print("LAMMPS failed with error:", e)
# write compressed dump file depending on available of options
if lmp.has_style("dump", "atom/zstd"):
lmp.command("dump d1 all atom/zstd 100 dump.zst")
elif lmp.has_style("dump", "atom/gz"):
lmp.command("dump d1 all atom/gz 100 dump.gz")
elif lmp.has_gzip_support():
lmp.command("dump d1 all atom 100 dump.gz")
else:
lmp.command("dump d1 all atom 100 dump")
-----------------------
**Methods:**
* :py:attr:`lammps.has_mpi_support <lammps.lammps.has_mpi_support>`
* :py:attr:`lammps.has_exceptions <lammps.lammps.has_exceptions>`
* :py:attr:`lammps.has_gzip_support <lammps.lammps.has_gzip_support>`
* :py:attr:`lammps.has_png_support <lammps.lammps.has_png_support>`
* :py:attr:`lammps.has_jpeg_support <lammps.lammps.has_jpeg_support>`
* :py:attr:`lammps.has_ffmpeg_support <lammps.lammps.has_ffmpeg_support>`
* :py:attr:`lammps.installed_packages <lammps.lammps.installed_pages>`
* :py:meth:`lammps.has_style() <lammps.lammps.has_style()>`
* :py:meth:`lammps.available_styles() <lammps.lammps.available_styles()>`

36
doc/src/Python_error.rst Normal file
View File

@ -0,0 +1,36 @@
LAMMPS error handling in Python
*******************************
Compiling the shared library with :ref:`C++ exception support <exceptions>` provides a better error
handling experience. Without exceptions the LAMMPS code will terminate the
current Python process with an error message. C++ exceptions allow capturing
them on the C++ side and rethrowing them on the Python side. This way
LAMMPS errors can be handled through the Python exception handling mechanism.
.. code-block:: Python
from lammps import lammps, MPIAbortException
lmp = lammps()
try:
# LAMMPS will normally terminate itself and the running process if an error
# occurs. This would kill the Python interpreter. To avoid this, make sure to
# compile with LAMMPS_EXCEPTIONS enabled. This ensures the library API calls
# will not terminate the parent process. Instead, the library wrapper will
# detect that an error has occured and throw a Python exception
lmp.command('unknown')
except MPIAbortException as ae:
# Single MPI process got killed. This would normally be handled by an MPI abort
pass
except Exception as e:
# All (MPI) processes have reached this error
pass
.. warning::
Capturing a LAMMPS exception in Python can still mean that the
current LAMMPS process is in an illegal state and must be terminated. It is
advised to save your data and terminate the Python instance as quickly as
possible.

3
doc/src/Python_examples.rst
View File

@ -1,6 +1,9 @@
Example Python scripts that use LAMMPS
======================================
The python/examples directory has Python scripts which show how Python
can run LAMMPS, grab data, change it, and put it back into LAMMPS.
These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of
things that are possible when Python wraps LAMMPS. If you create your

16
doc/src/Python_ext.rst Normal file
View File

@ -0,0 +1,16 @@
Extending the library and Python interface
******************************************
As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in ``src/library.cpp`` and
``library.h``. This means you can extend the Python wrapper via the
following steps:
* Add a new interface function to ``src/library.cpp`` and
``src/library.h``.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to ``python/lammps.py`` for this interface
function.
* You should now be able to invoke the new interface function from a
Python script.

59
doc/src/Python_head.rst
View File

@ -1,43 +1,50 @@
Use Python with LAMMPS
**********************
These doc pages describe various ways that LAMMPS and Python can be
used together.
These pages describe various ways that LAMMPS and Python can be used
together.
.. toctree::
:maxdepth: 1
Python_overview
Python_run
Python_shlib
Python_install
Python_mpi
Python_test
Python_library
Python_pylammps
Python_examples
Python_run
Python_usage
Python_call
Python_config
Python_neighbor
Python_module
Python_examples
Python_error
Python_ext
Python_trouble
If you're not familiar with `Python <http://www.python.org>`_, it's a
powerful scripting and programming language which can do most
everything that lower-level languages like C or C++ can do in fewer
lines of code. The only drawback is slower execution speed. Python
is also easy to use as a "glue" language to drive a program through
its library interface, or to hook multiple pieces of software
together, such as a simulation code plus a visualization tool, or to
run a coupled multiscale or multiphysics model.
If you are not familiar with `Python <http://www.python.org>`_, it is a
powerful scripting and programming language which can do almost
everything that compiled languages like C, C++, or Fortran can do in
fewer lines of code. It also comes with a large collection of add-on
modules for many purposes (either bundled or easily installed from
Python code repositories). The major drawback is slower execution speed
of the script code compared to compiled programming languages. But when
the script code is interfaced to optimized compiled code, performance can
be on par with a standalone executable, for as long as the scripting is
restricted to high-level operations. Thus Python is also convenient to
use as a "glue" language to "drive" a program through its library
interface, or to hook multiple pieces of software together, such as a
simulation code and a visualization tool, or to run a coupled
multi-scale or multi-physics model.
See the :doc:`Howto_couple <Howto_couple>` doc page for more ideas about
coupling LAMMPS to other codes. See the :doc:`Howto library <Howto_library>` doc page for a description of the LAMMPS
library interface provided in src/library.h and src/library.h. That
interface is exposed to Python either when calling LAMMPS from Python
or when calling Python from a LAMMPS input script and then calling
back to LAMMPS from Python code. The library interface is designed to
be easy to add functionality to. Thus the Python interface to LAMMPS
is also easy to extend as well.
See the :doc:`Howto_couple` page for more ideas about coupling LAMMPS
to other codes. See the :doc:`Library` page for a description of the
LAMMPS library interfaces. That interface is exposed to Python either
when calling LAMMPS from Python or when calling Python from a LAMMPS
input script and then calling back to LAMMPS from Python code. The
C-library interface is designed to be easy to add functionality to,
thus the Python interface to LAMMPS is easy to extend as well.
If you create interesting Python scripts that run LAMMPS or
interesting Python functions that can be called from a LAMMPS input
script, that you think would be generally useful, please post them as
a pull request to our `GitHub site <https://github.com/lammps/lammps>`_,
and they can be added to the LAMMPS distribution or webpage.
and they can be added to the LAMMPS distribution or web page.

502
doc/src/Python_install.rst
View File

@ -1,68 +1,468 @@
Installing LAMMPS in Python
===========================
Installation
************
For Python to invoke LAMMPS, there are 2 files it needs to know about:
The LAMMPS Python module enables calling the :ref:`LAMMPS C library API
<lammps_c_api>` from Python by dynamically loading functions in the
LAMMPS shared library through the Python `ctypes <ctypes_>`_
module. Because of the dynamic loading, it is required that LAMMPS is
compiled in :ref:`"shared" mode <exe>`. It is also recommended to
compile LAMMPS with :ref:`C++ exceptions <exceptions>` enabled.
* python/lammps.py
* liblammps.so or liblammps.dylib
Two files are necessary for Python to be able to invoke LAMMPS code:
The python source code in lammps.py is the Python wrapper on the
LAMMPS library interface. The liblammps.so or liblammps.dylib file
is the shared LAMMPS library that Python loads dynamically.
* The LAMMPS Python Module (``lammps.py``) from the ``python`` folder
* The LAMMPS Shared Library (``liblammps.so``, ``liblammps.dylib`` or
``liblammps.dll``) from the folder where you compiled LAMMPS.
You can achieve that Python can find these files in one of two ways:
.. _ctypes: https://docs.python.org/3/library/ctypes.html
.. _python_virtualenv: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
.. _python_venv: https://docs.python.org/3/library/venv.html
.. _python_pep405: https://www.python.org/dev/peps/pep-0405
* set two environment variables pointing to the location in the source tree
* run "make install-python" or run the python/install.py script explicitly
.. _python_install_guides:
When calling "make install-python" LAMMPS will try to install the
python module and the shared library into the python site-packages folders;
either the system-wide ones, or the local users ones (in case of insufficient
permissions for the global install). Python will then find the module
and shared library file automatically. The exact location of these folders
depends on your python version and your operating system. When using
the CMake build system, you can set the python executable to use during
the CMake configuration process. Details are given in the build instructions
for the :ref:`PYTHON <python>` package. When using the conventional make
system, you can override the python version to version x.y when calling
make with PYTHON=pythonx.y.
Installing the LAMMPS Python Module and Shared Library
======================================================
If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:
Making LAMMPS usable within Python and vice versa requires putting the
LAMMPS Python module file (``lammps.py``) into a location where the
Python interpreter can find it and installing the LAMMPS shared library
into a folder that the dynamic loader searches or into the same folder
where the ``lammps.py`` file is. There are multiple ways to achieve
this.
.. code-block:: csh
#. Do a full LAMMPS installation of libraries, executables, selected
headers, documentation (if enabled), and supporting files (only
available via CMake), which can also be either system-wide or into
user specific folders.
setenv PYTHONPATH ${PYTHONPATH}:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/home/sjplimp/lammps/src
#. Install both files into a Python ``site-packages`` folder, either
system-wide or in the corresponding user-specific folder. This way no
additional environment variables need to be set, but the shared
library is otherwise not accessible.
On MacOSX you may also need to set DYLD_LIBRARY_PATH accordingly.
For Bourne/Korn shells accordingly into the corresponding files using
the "export" shell builtin.
#. Do an installation into a virtual environment. This can either be
an installation of the python module only or a full installation.
If you use "make install-python" or the python/install.py script, you need
to invoke it every time you rebuild LAMMPS (as a shared library) or
make changes to the python/lammps.py file, so that the site-packages
files are updated with the new version.
#. Leave the files where they are in the source/development tree and
adjust some environment variables.
If the default settings of "make install-python" are not what you want,
you can invoke install.py from the python directory manually as
.. tabs::
.. parsed-literal::
.. tab:: Full install (CMake-only)
% python install.py -m \<python module\> -l <shared library> -v <version.h file> [-d \<pydir\>]
:ref:`Build the LAMMPS executable and library <library>` with
``-DBUILD_SHARED_LIBS=on``, ``-DLAMMPS_EXCEPTIONS=on`` and
``-DPKG_PYTHON=on`` (The first option is required, the other two
are optional by recommended). The exact file name of the shared
library depends on the platform (Unix/Linux, MacOS, Windows) and
the build configuration being used. The installation base folder
is already set by default to the ``$HOME/.local`` directory, but
it can be changed to a custom location defined by the
``CMAKE_INSTALL_PREFIX`` CMake variable. This uses a folder
called ``build`` to store files generated during compilation.
* The -m flag points to the lammps.py python module file to be installed,
* the -l flag points to the LAMMPS shared library file to be installed,
* the -v flag points to the version.h file in the LAMMPS source
* and the optional -d flag to a custom (legacy) installation folder
.. code-block:: bash
If you use a legacy installation folder, you will need to set your
PYTHONPATH and LD_LIBRARY_PATH (and/or DYLD_LIBRARY_PATH) environment
variables accordingly, as described above.
# create build folder
mkdir build
cd build
# configure LAMMPS compilation
cmake -C cmake/presets/minimal.cmake -D BUILD_SHARED_LIBS=on \
-D LAMMPS_EXCEPTIONS=on -D PKG_PYTHON=on ../cmake
# compile LAMMPS
cmake --build .
# install LAMMPS into $HOME/.local
cmake --install .
This leads to an installation to the following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/`` (32bit) | |
| | * ``$HOME/.local/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$HOME/.local/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$HOME/.local/share/lammps/potentials/`` | Set ``LAMMPS_POTENTIALS`` environment variable to this path |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation you need to set
``CMAKE_INSTALL_PREFIX`` to a system folder like ``/usr`` (or
``/usr/local``). The installation step (**not** the
configuration/compilation) needs to be done with superuser
privilege, e.g. by using ``sudo cmake --install .``. The
installation folders will then by changed to:
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===================================================+=============================================================+
| LAMMPS Python Module | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/`` (32bit) | |
| | * ``/usr/lib64/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``/usr/bin/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``/usr/share/lammps/potentials/`` | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
To be able to use the "user" installation you have to ensure that
the folder containing the LAMMPS shared library is either included
in a path searched by the shared linker (e.g. like
``/usr/lib64/``) or part of the ``LD_LIBRARY_PATH`` environment
variable (or ``DYLD_LIBRARY_PATH`` on MacOS). Otherwise you will
get an error when trying to create a LAMMPS object through the
Python module.
.. code-block:: bash
# Unix/Linux
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
# MacOS
export DYLD_LIBRARY_PATH=$HOME/.local/lib:$DYLD_LIBRARY_PATH
If you plan to use the LAMMPS executable (e.g., ``lmp``), you may
also need to adjust the ``PATH`` environment variable (but many
newer Linux distributions already have ``$HOME/.local/bin``
included). Example:
.. code-block:: bash
export PATH=$HOME/.local/bin:$PATH
To make those changes permanent, you can add the commands to your
``$HOME/.bashrc`` file. For a system-wide installation is is not
necessary due to files installed in system folders that are loaded
automatically when a login shell is started.
.. tab:: Python module only
Compile LAMMPS with either :doc:`CMake <Build_cmake>` or the
:doc:`traditional make <Build_make>` procedure in :ref:`shared
mode <exe>`. After compilation has finished type (in the
compilation folder):
.. code-block:: bash
make install-python
This will try to install (only) the shared library and the python
module into a system folder and if that fails (due to missing
write permissions) will instead do the installation to a user
folder under ``$HOME/.local``. For a system-wide installation you
would have to gain superuser privilege, e.g. though ``sudo``
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$HOME/.local/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$HOME/.local/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
For a system-wide installation those folders would then become.
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===================================================+=============================================================+
| LAMMPS Python Module | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``/usr/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``/usr/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+---------------------------------------------------+-------------------------------------------------------------+
No environment variables need to be set for those, as those
folders are searched by default by Python or the LAMMPS Python
module.
For the traditional make process you can override the python
version to version x.y when calling ``make`` with
``PYTHON=pythonX.Y``. For a CMake based compilation this choice
has to be made during the CMake configuration step.
If the default settings of ``make install-python`` are not what you want,
you can invoke ``install.py`` from the python directory manually as
.. code-block:: bash
$ python install.py -m <python module> -l <shared library> -v <version.h file> [-d <pydir>]
* The ``-m`` flag points to the ``lammps.py`` python module file to be installed,
* the ``-l`` flag points to the LAMMPS shared library file to be installed,
* the ``-v`` flag points to the ``version.h`` file in the LAMMPS source
* and the optional ``-d`` flag to a custom (legacy) installation folder
If you use a legacy installation folder, you will need to set your
``PYTHONPATH`` and ``LD_LIBRARY_PATH`` (and/or ``DYLD_LIBRARY_PATH``) environment
variables accordingly as explained in the description for "In place use".
.. tab:: Virtual environment
A virtual environment is a minimal Python installation inside of a
folder. It allows isolating and customizing a Python environment
that is mostly independent from a user or system installation.
For the core Python environment, it uses symbolic links to the
system installation and thus it can be set up quickly and will not
take up much disk space. This gives you the flexibility to
install (newer/different) versions of Python packages that would
potentially conflict with already installed system packages. It
also does not requite any superuser privileges. See `PEP 405:
Python Virtual Environments <python_pep405>`_ for more
information.
To create a virtual environment in the folder ``$HOME/myenv``,
use the `venv <python_venv>`_ module as follows.
.. code-block:: bash
# create virtual environment in folder $HOME/myenv
python3 -m venv $HOME/myenv
For Python versions prior 3.3 you can use `virtualenv
<python_virtualenv>`_ command instead of "python3 -m venv". This
step has to be done only once.
To activate the virtual environment type:
.. code-block:: bash
source $HOME/myenv/bin/activate
This has to be done every time you log in or open a new terminal
window and after you turn off the virtual environment with the
``deactivate`` command.
When using CMake to build LAMMPS, you need to set
``CMAKE_INSTALL_PREFIX`` to the value of the ``$VIRTUAL_ENV``
environment variable during the configuration step. For the
traditional make procedure, not additional steps are needed.
After compiling LAMMPS you can do a "Python module only"
installation with ``make install-python`` and the LAMMPS Python
module and the shared library file are installed into the
following locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
If you do a full installation (CMake only) with "install", this
leads to the following installation locations:
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| File | Location | Notes |
+========================+===========================================================+=============================================================+
| LAMMPS Python Module | * ``$VIRTUAL_ENV/lib/pythonX.Y/site-packages/`` (32bit) | ``X.Y`` depends on the installed Python version |
| | * ``$VIRTUAL_ENV/lib64/pythonX.Y/site-packages/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS shared library | * ``$VIRTUAL_ENV/lib/`` (32bit) | |
| | * ``$VIRTUAL_ENV/lib64/`` (64bit) | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS executable | * ``$VIRTUAL_ENV/bin/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
| LAMMPS potential files | * ``$VIRTUAL_ENV/share/lammps/potentials/`` | |
+------------------------+-----------------------------------------------------------+-------------------------------------------------------------+
In that case you need to modify the ``$HOME/myenv/bin/activate``
script in a similar fashion you need to update your
``$HOME/.bashrc`` file to include the shared library and
executable locations in ``LD_LIBRARY_PATH`` (or
``DYLD_LIBRARY_PATH`` on MacOS) and ``PATH``, respectively.
For example with:
.. code-block:: bash
# Unix/Linux
echo 'export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
# MacOS
echo 'export DYLD_LIBRARY_PATH=$VIRTUAL_ENV/lib:$LD_LIBRARY_PATH' >> $HOME/myenv/bin/activate
.. tab:: In place usage
You can also :doc:`compile LAMMPS <Build>` as usual in
:ref:`"shared" mode <exe>` leave the shared library and Python
module files inside the source/compilation folders. Instead of
copying the files where they can be found, you need to set the environment
variables ``PYTHONPATH`` (for the Python module) and
``LD_LIBRARY_PATH`` (or ``DYLD_LIBRARY_PATH`` on MacOS
For Bourne shells (bash, ksh and similar) the commands are:
.. code-block:: bash
export PYTHONPATH=${PYTHONPATH}:${HOME}/lammps/python
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/lammps/src
For the C-shells like csh or tcsh the commands are:
.. code-block:: csh
setenv PYTHONPATH ${PYTHONPATH}:${HOME}/lammps/python
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${HOME}/lammps/src
On MacOS you may also need to set ``DYLD_LIBRARY_PATH`` accordingly.
You can make those changes permanent by editing your ``$HOME/.bashrc``
or ``$HOME/.login`` files, respectively.
To verify if LAMMPS can be successfully started from Python, start the
Python interpreter, load the ``lammps`` Python module and create a
LAMMPS instance. This should not generate an error message and produce
output similar to the following:
.. code-block:: bash
$ python
Python 3.8.5 (default, Sep 5 2020, 10:50:12)
[GCC 10.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import lammps
>>> lmp = lammps.lammps()
LAMMPS (18 Sep 2020)
using 1 OpenMP thread(s) per MPI task
>>>
.. note::
Unless you opted for "In place use", you will have to rerun the installation
any time you recompile LAMMPS to ensure the latest Python module and shared
library are installed and used.
.. note::
If you want Python to be able to load different versions of the
LAMMPS shared library with different settings, you will need to
manually copy the files under different names
(e.g. ``liblammps_mpi.so`` or ``liblammps_gpu.so``) into the
appropriate folder as indicated above. You can then select the
desired library through the *name* argument of the LAMMPS object
constructor (see :ref:`python_create_lammps`).
.. _python_install_mpi4py:
Extending Python to run in parallel
===================================
If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
make MPI calls directly from Python in your script, if you desire.
We have tested this with `MPI for Python <https://mpi4py.readthedocs.io/>`_
(aka mpi4py) and you will find installation instruction for it below.
.. note::
Older LAMMPS versions were also tested with `PyPar <https://github.com/daleroberts/pypar>`_
but we can no longer test it, since it does not work with the Python
(3.x) versions on our test servers. Since there have been no updates
to PyPar visible in its repository since November 2016 we have to assume
it is no longer maintained.
Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as
follows:
- Via ``pip`` into a local user folder with:
.. code-block:: bash
pip install --user mpi4py
- Via ``dnf`` into a system folder for RedHat/Fedora systems:
.. code-block:: bash
# for use with OpenMPI
sudo dnf install python3-mpi4py-openmpi
# for use with MPICH
sudo dnf install python3-mpi4py-openmpi
- Via ``pip`` into a virtual environment (see above):
.. code-block:: bash
$ source $HOME/myenv/activate
(myenv)$ pip install mpi4py
- Via ``pip`` into a system folder (not recommended):
.. code-block:: bash
sudo pip install mpi4py
.. _mpi4py_install: https://mpi4py.readthedocs.io/en/stable/install.html
For more detailed installation instructions and additional options,
please see the `mpi4py installation <mpi4py_install>`_ page.
To use ``mpi4py`` and LAMMPS in parallel from Python, you **must** make
certain that **both** are using the **same** implementation and version
of MPI library. If you only have one MPI library installed on your
system this is not an issue, but it can be if you have multiple MPI
installations (e.g. on an HPC cluster to be selected through environment
modules). Your LAMMPS build is explicit about which MPI it is using,
since it is either detected during CMake configuration or in the
traditional make build system you specify the details in your low-level
``src/MAKE/Makefile.foo`` file. The installation process of ``mpi4py``
uses the ``mpicc`` command to find information about the MPI it uses to
build against. And it tries to load "libmpi.so" from the
``LD_LIBRARY_PATH``. This may or may not find the MPI library that
LAMMPS is using. If you have problems running both mpi4py and LAMMPS
together, this is an issue you may need to address, e.g. by loading the
module for different MPI installation so that mpi4py finds the right
one.
If you have successfully installed mpi4py, you should be able to run
Python and type
.. code-block:: python
from mpi4py import MPI
without error. You should also be able to run Python in parallel
on a simple test script
.. code-block:: bash
$ mpirun -np 4 python3 test.py
where ``test.py`` contains the lines
.. code-block:: python
from mpi4py import MPI
comm = MPI.COMM_WORLD
print("Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size()))
and see one line of output for each processor you run on.
.. code-block:: bash
# NOTE: the line order is not deterministic
$ mpirun -np 4 python3 test.py
Proc 0 out of 4 procs
Proc 1 out of 4 procs
Proc 2 out of 4 procs
Proc 3 out of 4 procs
Note that if you want Python to be able to load different versions of
the LAMMPS shared library (see :doc:`this section <Python_shlib>`), you will
need to manually copy files like liblammps_g++.so into the appropriate
system directory. This is not needed if you set the LD_LIBRARY_PATH
environment variable as described above.

256
doc/src/Python_library.rst
View File

@ -1,256 +0,0 @@
Python library interface
========================
As described previously, the Python interface to LAMMPS consists of a
Python "lammps" module, the source code for which is in
python/lammps.py, which creates a "lammps" object, with a set of
methods that can be invoked on that object. The sample Python code
below assumes you have first imported the "lammps" module in your
Python script, as follows:
.. code-block:: Python
from lammps import lammps
These are the methods defined by the lammps module. If you look at
the files src/library.cpp and src/library.h you will see they
correspond one-to-one with calls you can make to the LAMMPS library
from a C++ or C or Fortran program, and which are described on the
:doc:`Howto library <Howto_library>` doc page.
The python/examples directory has Python scripts which show how Python
can run LAMMPS, grab data, change it, and put it back into LAMMPS.
.. code-block:: Python
lmp = lammps() # create a LAMMPS object using the default liblammps.so library
# 4 optional args are allowed: name, cmdargs, ptr, comm
lmp = lammps(ptr=lmpptr) # use lmpptr as previously created LAMMPS object
lmp = lammps(comm=split) # create a LAMMPS object with a custom communicator, requires mpi4py 2.0.0 or later
lmp = lammps(name="g++") # create a LAMMPS object using the liblammps_g++.so library
lmp = lammps(name="g++",cmdargs=list) # add LAMMPS command-line args, e.g. list = ["-echo","screen"]
lmp.close() # destroy a LAMMPS object
version = lmp.version() # return the numerical version id, e.g. LAMMPS 2 Sep 2015 -> 20150902
lmp.file(file) # run an entire input script, file = "in.lj"
lmp.command(cmd) # invoke a single LAMMPS command, cmd = "run 100"
lmp.commands_list(cmdlist) # invoke commands in cmdlist = **"run 10", "run 20"**
lmp.commands_string(multicmd) # invoke commands in multicmd = "run 10\nrun 20"
size = lmp.extract_setting(name) # return data type info
xlo = lmp.extract_global(name,type) # extract a global quantity
# name = "boxxlo", "nlocal", etc
# type = 0 = int
# 1 = double
boxlo,boxhi,xy,yz,xz,periodicity,box_change = lmp.extract_box() # extract box info
coords = lmp.extract_atom(name,type) # extract a per-atom quantity
# name = "x", "type", etc
# type = 0 = vector of ints
# 1 = array of ints
# 2 = vector of doubles
# 3 = array of doubles
eng = lmp.extract_compute(id,style,type) # extract value(s) from a compute
v3 = lmp.extract_fix(id,style,type,i,j) # extract value(s) from a fix
# id = ID of compute or fix
# style = 0 = global data
# 1 = per-atom data
# 2 = local data
# type = 0 = scalar
# 1 = vector
# 2 = array
# i,j = indices of value in global vector or array
var = lmp.extract_variable(name,group,flag) # extract value(s) from a variable
# name = name of variable
# group = group ID (ignored for equal-style variables)
# flag = 0 = equal-style variable
# 1 = atom-style variable
value = lmp.get_thermo(name) # return current value of a thermo keyword
natoms = lmp.get_natoms() # total # of atoms as int
flag = lmp.set_variable(name,value) # set existing named string-style variable to value, flag = 0 if successful
lmp.reset_box(boxlo,boxhi,xy,yz,xz) # reset the simulation box size
data = lmp.gather_atoms(name,type,count) # return per-atom property of all atoms gathered into data, ordered by atom ID
# name = "x", "charge", "type", etc
data = lmp.gather_atoms_concat(name,type,count) # ditto, but concatenated atom values from each proc (unordered)
data = lmp.gather_atoms_subset(name,type,count,ndata,ids) # ditto, but for subset of Ndata atoms with IDs
lmp.scatter_atoms(name,type,count,data) # scatter per-atom property to all atoms from data, ordered by atom ID
# name = "x", "charge", "type", etc
# count = # of per-atom values, 1 or 3, etc
lmp.scatter_atoms_subset(name,type,count,ndata,ids,data) # ditto, but for subset of Ndata atoms with IDs
lmp.create_atoms(n,ids,types,x,v,image,shrinkexceed) # create N atoms with IDs, types, x, v, and image flags
----------
The lines
.. code-block:: Python
from lammps import lammps
lmp = lammps()
create an instance of LAMMPS, wrapped in a Python class by the lammps
Python module, and return an instance of the Python class as lmp. It
is used to make all subsequent calls to the LAMMPS library.
Additional arguments to lammps() can be used to tell Python the name
of the shared library to load or to pass arguments to the LAMMPS
instance, the same as if LAMMPS were launched from a command-line
prompt.
If the ptr argument is set like this:
.. code-block:: Python
lmp = lammps(ptr=lmpptr)
then lmpptr must be an argument passed to Python via the LAMMPS
:doc:`python <python>` command, when it is used to define a Python
function that is invoked by the LAMMPS input script. This mode of
calling Python from LAMMPS is described in the :doc:`Python call <Python_call>` doc page. The variable lmpptr refers to the
instance of LAMMPS that called the embedded Python interpreter. Using
it as an argument to lammps() allows the returned Python class
instance "lmp" to make calls to that instance of LAMMPS. See the
:doc:`python <python>` command doc page for examples using this syntax.
Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.
.. code-block:: Python
from lammps import lammps
lmp1 = lammps()
lmp2 = lammps()
lmp1.file("in.file1")
lmp2.file("in.file2")
The file(), command(), commands_list(), commands_string() methods
allow an input script, a single command, or multiple commands to be
invoked.
The extract_setting(), extract_global(), extract_box(),
extract_atom(), extract_compute(), extract_fix(), and
extract_variable() methods return values or pointers to data
structures internal to LAMMPS.
For extract_global() see the src/library.cpp file for the list of
valid names. New names could easily be added. A double or integer is
returned. You need to specify the appropriate data type via the type
argument.
For extract_atom(), a pointer to internal LAMMPS atom-based data is
returned, which you can use via normal Python subscripting. See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added if the property you want is not
listed. A pointer to a vector of doubles or integers, or a pointer to
an array of doubles (double \*\*) or integers (int \*\*) is returned. You
need to specify the appropriate data type via the type argument.
For extract_compute() and extract_fix(), the global, per-atom, or
local data calculated by the compute or fix can be accessed. What is
returned depends on whether the compute or fix calculates a scalar or
vector or array. For a scalar, a single double value is returned. If
the compute or fix calculates a vector or array, a pointer to the
internal LAMMPS data is returned, which you can use via normal Python
subscripting. The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices. The I,J arguments can be left out if not needed.
See the :doc:`Howto output <Howto_output>` doc page for a discussion of
global, per-atom, and local data, and of scalar, vector, and array
data types. See the doc pages for individual :doc:`computes <compute>`
and :doc:`fixes <fix>` for a description of what they calculate and
store.
For extract_variable(), an :doc:`equal-style or atom-style variable <variable>` is evaluated and its result returned.
For equal-style variables a single double value is returned and the
group argument is ignored. For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.
The get_thermo() method returns the current value of a thermo
keyword as a float.
The get_natoms() method returns the total number of atoms in the
simulation, as an int.
The set_variable() method sets an existing string-style variable to a
new string value, so that subsequent LAMMPS commands can access the
variable.
The reset_box() method resets the size and shape of the simulation
box, e.g. as part of restoring a previously extracted and saved state
of a simulation.
The gather methods collect peratom info of the requested type (atom
coords, atom types, forces, etc) from all processors, and returns the
same vector of values to each calling processor. The scatter
functions do the inverse. They distribute a vector of peratom values,
passed by all calling processors, to individual atoms, which may be
owned by different processors.
Note that the data returned by the gather methods,
e.g. gather_atoms("x"), is different from the data structure returned
by extract_atom("x") in four ways. (1) Gather_atoms() returns a
vector which you index as x[i]; extract_atom() returns an array
which you index as x[i][j]. (2) Gather_atoms() orders the atoms
by atom ID while extract_atom() does not. (3) Gather_atoms() returns
a list of all atoms in the simulation; extract_atoms() returns just
the atoms local to each processor. (4) Finally, the gather_atoms()
data structure is a copy of the atom coords stored internally in
LAMMPS, whereas extract_atom() returns an array that effectively
points directly to the internal data. This means you can change
values inside LAMMPS from Python by assigning a new values to the
extract_atom() array. To do this with the gather_atoms() vector, you
need to change values in the vector, then invoke the scatter_atoms()
method.
For the scatter methods, the array of coordinates passed to must be a
ctypes vector of ints or doubles, allocated and initialized something
like this:
.. code-block:: Python
from ctypes import \*
natoms = lmp.get_natoms()
n3 = 3\*natoms
x = (n3\*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_atoms("x",1,3,x)
Alternatively, you can just change values in the vector returned by
the gather methods, since they are also ctypes vectors.
----------
As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in src/library.cpp and
library.h. This means you can extend the Python wrapper via the
following steps:
* Add a new interface function to src/library.cpp and
src/library.h.
* Rebuild LAMMPS as a shared library.
* Add a wrapper method to python/lammps.py for this interface
function.
* You should now be able to invoke the new interface function from a
Python script.

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

@ -0,0 +1,158 @@
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
:ref:`C-library API <lammps_c_api>` 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
----------
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 :ref:`LAMMPS C library
API <lammps_c_api>` 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:
.. autoclass:: lammps.numpy_wrapper
:members:
----------
The ``PyLammps`` class API
==========================
The :py:class:`PyLammps <lammps.PyLammps>` class is a wrapper that creates a
simpler, more "Pythonic" interface to common LAMMPS functionality. LAMMPS
data structures are exposed through objects and properties. This makes Python
scripts shorter and more concise. See the :doc:`PyLammps Tutorial
<Howto_pylammps>` for an introduction on how to use this interface.
.. autoclass:: lammps.PyLammps
:members:
.. autoclass:: lammps.AtomList
:members:
.. autoclass:: lammps.Atom
:members:
.. autoclass:: lammps.Atom2D
:members:
----------
The ``IPyLammps`` class API
===========================
The :py:class:`IPyLammps <lammps.PyLammps>` class is an extension of
:py:class:`PyLammps <lammps.PyLammps>`, adding additional functions to
quickly display visualizations such as images and videos inside of IPython.
See the :doc:`PyLammps Tutorial <Howto_pylammps>` for examples.
.. 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_datatype_constants:
Data Types
----------
.. py:data:: LAMMPS_INT, LAMMPS_INT_2D, LAMMPS_DOUBLE, LAMMPS_DOUBLE_2D, LAMMPS_INT64, LAMMPS_INT64_2D, 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` and :py:func:`lammps.extract_atom`.
See :cpp:enum:`_LMP_DATATYPE_CONST` for the equivalent constants in the
C library interface.
.. _py_style_constants:
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`, :py:func:`lammps.extract_fix`, and their NumPy variants
:py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
.. _py_type_constants:
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`, :py:func:`lammps.extract_fix`, and their NumPy variants
:py:func:`lammps.numpy.extract_compute() <numpy_wrapper.extract_compute>` and
:py:func:`lammps.numpy.extract_fix() <numpy_wrapper.extract_fix>`.
.. _py_vartype_constants:
Variable Type Constants
------------------------
.. py:data:: LMP_VAR_EQUAL, LMP_VAR_ATOM
:type: int
Constants in the :py:mod:`lammps` module to select what type of
variable to query when calling :py:func:`lammps.extract_variable`. See also: :doc:`variable command <variable>`.
Classes representing internal objects
-------------------------------------
.. autoclass:: lammps.NeighList
:members:
:no-undoc-members:
.. autoclass:: lammps.NumPyNeighList
:members:
:no-undoc-members:

71
doc/src/Python_mpi.rst
View File

@ -1,71 +0,0 @@
Extending Python to run in parallel
===================================
If you wish to run LAMMPS in parallel from Python, you need to extend
your Python with an interface to MPI. This also allows you to
make MPI calls directly from Python in your script, if you desire.
We have tested this with mpi4py and pypar:
* `MPI for Python <https://mpi4py.readthedocs.io/>`_
* `pypar <https://github.com/daleroberts/pypar>`_
We recommend the use of mpi4py as it is the more complete MPI interface,
and as of version 2.0.0 mpi4py allows passing a custom MPI communicator
to the LAMMPS constructor, which means one can easily run one or more
LAMMPS instances on subsets of the total MPI ranks.
To install mpi4py (version mpi4py-3.0.3 as of Nov 2019), unpack it
and from its main directory, type
.. code-block:: bash
python setup.py build
sudo python setup.py install
Again, the "sudo" is only needed if required to copy mpi4py files into
your Python distribution's site-packages directory. To install with
user privilege into the user local directory type
.. code-block:: bash
python setup.py install --user
If you have successfully installed mpi4py, you should be able to run
Python and type
.. code-block:: python
from mpi4py import MPI
without error. You should also be able to run python in parallel
on a simple test script
.. code-block:: bash
% mpirun -np 4 python test.py
where test.py contains the lines
.. code-block:: python
from mpi4py import MPI
comm = MPI.COMM_WORLD
print "Proc %d out of %d procs" % (comm.Get_rank(),comm.Get_size())
and see one line of output for each processor you run on.
.. note::
To use mpi4py and LAMMPS in parallel from Python, you must
insure both are using the same version of MPI. If you only have one
MPI installed on your system, this is not an issue, but it can be if
you have multiple MPIs. Your LAMMPS build is explicit about which MPI
it is using, since you specify the details in your low-level
src/MAKE/Makefile.foo file. Mpi4py uses the "mpicc" command to find
information about the MPI it uses to build against. And it tries to
load "libmpi.so" from the LD_LIBRARY_PATH. This may or may not find
the MPI library that LAMMPS is using. If you have problems running
both mpi4py and LAMMPS together, this is an issue you may need to
address, e.g. by moving other MPI installations so that mpi4py finds
the right one.

18
doc/src/Python_neighbor.rst Normal file
View File

@ -0,0 +1,18 @@
Accessing LAMMPS Neighbor lists
*******************************
**Methods:**
* :py:meth:`lammps.get_neighlist() <lammps.lammps.get_neighlist()>`: Get neighbor list for given index
* :py:meth:`lammps.get_neighlist_size()`: Get number of elements in neighbor list
* :py:meth:`lammps.get_neighlist_element_neighbors()`: Get element in neighbor list and its neighbors
* :py:meth:`lammps.find_pair_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
* :py:meth:`lammps.find_fix_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
* :py:meth:`lammps.find_compute_neighlist() <lammps.lammps.find_pair_neighlist()>`: Find neighbor list of pair style
**NumPy Methods:**
* :py:meth:`lammps.numpy.get_neighlist() <lammps.numpy_wrapper.get_neighlist()>`: Get neighbor list for given index, which uses NumPy arrays for its element neighbor arrays
* :py:meth:`lammps.numpy.get_neighlist_element_neighbors() <lammps.numpy_wrapper.get_neighlist_element_neighbors()>`: Get element in neighbor list and its neighbors (as numpy array)

106
doc/src/Python_overview.rst
View File

@ -1,25 +1,93 @@
Overview of Python and LAMMPS
=============================
Overview
========
The LAMMPS distribution includes a ``python`` directory with the Python
code needed to run LAMMPS from Python. The ``python/lammps.py``
contains :doc:`the "lammps" Python <Python_module>` that wraps the
LAMMPS C-library interface. This file makes it is possible to do the
following either from a Python script, or interactively from a Python
prompt:
- create one or more instances of LAMMPS
- invoke LAMMPS commands or read them from an input script
- run LAMMPS incrementally
- extract LAMMPS results
- and modify internal LAMMPS data structures.
From a Python script you can do this in serial or in parallel. Running
Python interactively in parallel does not generally work, unless you
have a version of Python that extends Python to enable multiple
instances of Python to read what you type.
To do all of this, you must build LAMMPS in :ref:`"shared" mode <exe>`
and make certain that your Python interpreter can find the ``lammps.py``
file and the LAMMPS shared library file.
.. _ctypes: https://docs.python.org/3/library/ctypes.html
The Python wrapper for LAMMPS uses the `ctypes <ctypes_>`_ package in
Python, which auto-generates the interface code needed between Python
and a set of C-style library functions. Ctypes has been part of the
standard Python distribution since version 2.5. You can check which
version of Python you have by simply typing "python" at a shell prompt.
Below is an example output for Python version 3.8.5.
.. code-block::
$ python
Python 3.8.5 (default, Aug 12 2020, 00:00:00)
[GCC 10.2.1 20200723 (Red Hat 10.2.1-1)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
.. warning:: Python 2 support is deprecated
While the LAMMPS Python module was originally developed to support
both, Python 2 and 3, any new code is only tested with Python 3.
Please note that Python 2 is no longer maintained as of `January 1,
2020 <https://www.python.org/doc/sunset-python-2/>`_. Therefore, we
highly recommend using Python version 3.6 or later. Compatibility to
Python 2 will be removed eventually.
---------
LAMMPS can work together with Python in three ways. First, Python can
wrap LAMMPS through the its :doc:`library interface <Howto_library>`, so
wrap LAMMPS through the its :doc:`library interface <Library>`, so
that a Python script can create one or more instances of LAMMPS and
launch one or more simulations. In Python lingo, this is called
launch one or more simulations. In Python terms, this is referred to as
"extending" Python with a LAMMPS module.
Second, a lower-level Python interface can be used indirectly through
the provided PyLammps and IPyLammps wrapper classes, written in Python.
These wrappers try to simplify the usage of LAMMPS in Python by
providing an object-based interface to common LAMMPS functionality.
They also reduces the amount of code necessary to parameterize LAMMPS
scripts through Python and make variables and computes directly
accessible.
.. figure:: JPG/python-invoke-lammps.png
:figclass: align-center
Third, LAMMPS can use the Python interpreter, so that a LAMMPS
input script or styles can invoke Python code directly, and pass
information back-and-forth between the input script and Python
functions you write. This Python code can also callback to LAMMPS
to query or change its attributes through the LAMMPS Python module
mentioned above. In Python lingo, this is "embedding" Python in
LAMMPS. When used in this mode, Python can perform script operations
that the simple LAMMPS input script syntax can not.
Launching LAMMPS via Python
Second, the lower-level Python interface in the :py:class:`lammps Python
class <lammps.lammps>` can be used indirectly through the provided
:py:class:`PyLammps <lammps.PyLammps>` and :py:class:`IPyLammps
<lammps.IPyLammps>` wrapper classes, also written in Python. These
wrappers try to simplify the usage of LAMMPS in Python by providing a
more object-based interface to common LAMMPS functionality. They also
reduce the amount of code necessary to parameterize LAMMPS scripts
through Python and make variables and computes directly accessible.
.. figure:: JPG/pylammps-invoke-lammps.png
:figclass: align-center
Using the PyLammps / IPyLammps wrappers
Third, LAMMPS can use the Python interpreter, so that a LAMMPS input
script or styles can invoke Python code directly, and pass information
back-and-forth between the input script and Python functions you write.
This Python code can also call back to LAMMPS to query or change its
attributes through the LAMMPS Python module mentioned above. In Python
terms, this is called "embedding" Python into LAMMPS. When used in this
mode, Python can perform script operations that the simple LAMMPS input
script syntax can not.
.. figure:: JPG/lammps-invoke-python.png
:figclass: align-center
Calling Python code from LAMMPS

5
doc/src/Python_pylammps.rst
View File

@ -1,5 +0,0 @@
PyLammps interface
==================
PyLammps is a Python wrapper class which can be created on its own or
use an existing lammps Python object. It has its own :doc:`Howto pylammps <Howto_pylammps>` doc page.

130
doc/src/Python_run.rst
View File

@ -1,32 +1,110 @@
Run LAMMPS from Python
======================
The LAMMPS distribution includes a python directory with all you need
to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS
library interface, with one wrapper function per LAMMPS library
function. This file makes it is possible to do the following either
from a Python script, or interactively from a Python prompt: create
one or more instances of LAMMPS, invoke LAMMPS commands or give it an
input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do
this in serial or parallel. Running Python interactively in parallel
does not generally work, unless you have a version of Python that
extends Python to enable multiple instances of Python to read what you
type.
Running LAMMPS and Python in serial:
-------------------------------------
To do all of this, you must first build LAMMPS as a shared library,
then insure that your Python can find the python/lammps.py file and
the shared library.
To run a LAMMPS in serial, type these lines into Python
interactively from the ``bench`` directory:
Two advantages of using Python to run LAMMPS are how concise the
language is, and that it can be run interactively, enabling rapid
development and debugging. If you use it to mostly invoke costly
operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS through Python will be negligible.
.. code-block:: python
The Python wrapper for LAMMPS uses the "ctypes" package in Python,
which auto-generates the interface code needed between Python and a
set of C-style library functions. Ctypes is part of standard Python
for versions 2.5 and later. You can check which version of Python you
have by simply typing "python" at a shell prompt.
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
Or put the same lines in the file ``test.py`` and run it as
.. code-block:: bash
$ python3 test.py
Either way, you should see the results of running the ``in.lj`` benchmark
on a single processor appear on the screen, the same as if you had
typed something like:
.. code-block:: bash
lmp_serial -in in.lj
Running LAMMPS and Python in parallel with MPI
----------------------------------------------
To run LAMMPS in parallel, assuming you have installed the
`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
:ref:`python_install_mpi4py`, create a ``test.py`` file containing these lines:
.. code-block:: python
from mpi4py import MPI
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
me = MPI.COMM_WORLD.Get_rank()
nprocs = MPI.COMM_WORLD.Get_size()
print("Proc %d out of %d procs has" % (me,nprocs),lmp)
MPI.Finalize()
You can run the script in parallel as:
.. code-block:: bash
$ mpirun -np 4 python3 test.py
and you should see the same output as if you had typed
.. code-block:: bash
$ mpirun -np 4 lmp_mpi -in in.lj
Note that without the mpi4py specific lines from ``test.py``
.. code-block::
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
running the script with ``mpirun`` on :math:`P` processors would lead to
:math:`P` independent simulations to run parallel, each with a single
processor. Therefore, if you use the mpi4py lines and you see multiple LAMMPS
single processor outputs, mpi4py is not working correctly.
Also note that once you import the mpi4py module, mpi4py initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the mpi4py documentation. The last line of your Python
script should be ``MPI.finalize()``, to insure MPI is shut down
correctly.
Running Python scripts
----------------------
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
.. code-block:: bash
$ python script.py
$ python -i script.py
$ ./script.py
The last command requires that the first line of the script be
something like this:
.. code-block:: bash
#!/usr/bin/python
#!/usr/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
.. code-block:: bash
$ chmod +x script.py
Without the ``-i`` flag, Python will exit when the script finishes.
With the ``-i`` flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.

78
doc/src/Python_shlib.rst
View File

@ -1,78 +0,0 @@
Build LAMMPS as a shared library
================================
.. TODO this is mostly redundant and should be addressed in the 'progguide' branch if it has not already
Build LAMMPS as a shared library using make
-------------------------------------------
Instructions on how to build LAMMPS as a shared library are given on
the :doc:`Build_basics <Build_basics>` doc page. A shared library is
one that is dynamically loadable, which is what Python requires to
wrap LAMMPS. On Linux this is a library file that ends in ".so", not
".a".
From the src directory, type
.. code-block:: bash
make foo mode=shared
where foo is the machine target name, such as mpi or serial.
This should create the file liblammps_foo.so in the src directory, as
well as a soft link liblammps.so, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.
.. note::
If you are building LAMMPS with an MPI or FFT library or other
auxiliary libraries (used by various packages), then all of these
extra libraries must also be shared libraries. If the LAMMPS
shared-library build fails with an error complaining about this, see
the :doc:`Build_basics <Build_basics>` doc page.
Build LAMMPS as a shared library using CMake
--------------------------------------------
When using CMake the following two options are necessary to generate the LAMMPS
shared library:
.. code-block:: bash
-D BUILD_SHARED_LIBS=on # enable building of LAMMPS shared library (both options are needed!)
What this does is create a liblammps.so which contains the majority of LAMMPS
code. The generated lmp binary also dynamically links to this library. This
means that either this liblammps.so file has to be in the same directory, a system
library path (e.g. /usr/lib64/) or in the LD_LIBRARY_PATH.
If you want to use the shared library with Python the recommended way is to create a virtualenv and use it as
CMAKE_INSTALL_PREFIX.
.. code-block:: bash
# create virtualenv
virtualenv --python=$(which python3) myenv3
source myenv3/bin/activate
# build library
mkdir build
cd build
cmake -D PKG_PYTHON=on -D BUILD_SHARED_LIBS=on -D CMAKE_INSTALL_PREFIX=$VIRTUAL_ENV ../cmake
make -j 4
# install into prefix
make install
This will also install the Python module into your virtualenv. Since virtualenv
does not change your LD_LIBRARY_PATH, you still need to add its lib64 folder to
it, which contains the installed liblammps.so.
.. code-block:: bash
export LD_LIBRARY_PATH=$VIRTUAL_ENV/lib64:$LD_LIBRARY_PATH
Starting Python outside (!) of your build directory, but with the virtualenv
enabled and with the LD_LIBRARY_PATH set gives you access to LAMMPS via Python.

152
doc/src/Python_test.rst
View File

@ -1,152 +0,0 @@
Test the Python/LAMMPS interface
================================
To test if LAMMPS is callable from Python, launch Python interactively
and type:
.. parsed-literal::
>>> from lammps import lammps
>>> lmp = lammps()
If you get no errors, you're ready to use LAMMPS from Python. If the
second command fails, the most common error to see is
.. parsed-literal::
OSError: Could not load LAMMPS dynamic library
which means Python was unable to load the LAMMPS shared library. This
typically occurs if the system can't find the LAMMPS shared library or
one of the auxiliary shared libraries it depends on, or if something
about the library is incompatible with your Python. The error message
should give you an indication of what went wrong.
You can also test the load directly in Python as follows, without
first importing from the lammps.py file:
.. parsed-literal::
>>> from ctypes import CDLL
>>> CDLL("liblammps.so")
If an error occurs, carefully go through the steps on the
:doc:`Build_basics <Build_basics>` doc page about building a shared
library and the :doc:`Python_install <Python_install>` doc page about
insuring Python can find the necessary two files it needs.
Test LAMMPS and Python in serial:
-------------------------------------
To run a LAMMPS test in serial, type these lines into Python
interactively from the bench directory:
.. parsed-literal::
>>> from lammps import lammps
>>> lmp = lammps()
>>> lmp.file("in.lj")
Or put the same lines in the file test.py and run it as
.. code-block:: bash
% python test.py
Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:
.. parsed-literal::
lmp_g++ -in in.lj
Test LAMMPS and Python in parallel:
---------------------------------------
To run LAMMPS in parallel, assuming you have installed the
`PyPar <https://github.com/daleroberts/pypar>`_ package as discussed
above, create a test.py file containing these lines:
.. code-block:: python
import pypar
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
pypar.finalize()
To run LAMMPS in parallel, assuming you have installed the
`mpi4py <https://mpi4py.readthedocs.io>`_ package as discussed
above, create a test.py file containing these lines:
.. code-block:: python
from mpi4py import MPI
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
me = MPI.COMM_WORLD.Get_rank()
nprocs = MPI.COMM_WORLD.Get_size()
print "Proc %d out of %d procs has" % (me,nprocs),lmp
MPI.Finalize()
You can either script in parallel as:
.. code-block:: bash
% mpirun -np 4 python test.py
and you should see the same output as if you had typed
.. code-block:: bash
% mpirun -np 4 lmp_g++ -in in.lj
Note that if you leave out the 3 lines from test.py that specify PyPar
commands you will instantiate and run LAMMPS independently on each of
the P processors specified in the mpirun command. In this case you
should get 4 sets of output, each showing that a LAMMPS run was made
on a single processor, instead of one set of output showing that
LAMMPS ran on 4 processors. If the 1-processor outputs occur, it
means that PyPar is not working correctly.
Also note that once you import the PyPar module, PyPar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the PyPar documentation. The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.
Running Python scripts:
---------------------------
Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:
.. code-block:: bash
% python foo.script
% python -i foo.script
% foo.script
The last command requires that the first line of the script be
something like this:
.. code-block:: bash
#!/usr/local/bin/python
#!/usr/local/bin/python -i
where the path points to where you have Python installed, and that you
have made the script file executable:
.. code-block:: bash
% chmod +x foo.script
Without the "-i" flag, Python will exit when the script finishes.
With the "-i" flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.

44
doc/src/Python_trouble.rst Normal file
View File

@ -0,0 +1,44 @@
Troubleshooting
***************
Testing if Python can launch LAMMPS
===================================
To test if LAMMPS is callable from Python, launch Python interactively
and type:
.. code-block:: python
>>> from lammps import lammps
>>> lmp = lammps()
If you get no errors, you're ready to use LAMMPS from Python. If the
second command fails, the most common error to see is
.. code-block:: bash
OSError: Could not load LAMMPS dynamic library
which means Python was unable to load the LAMMPS shared library. This
typically occurs if the system can't find the LAMMPS shared library or
one of the auxiliary shared libraries it depends on, or if something
about the library is incompatible with your Python. The error message
should give you an indication of what went wrong.
If your shared library uses a suffix, such as ``liblammps_mpi.so``, change
the constructor call as follows (see :ref:`python_create_lammps` for more details):
.. code-block:: python
>>> lmp = lammps(name='mpi')
You can also test the load directly in Python as follows, without
first importing from the lammps.py file:
.. code-block:: python
>>> from ctypes import CDLL
>>> CDLL("liblammps.so")
If an error occurs, carefully go through the steps in :ref:`python_install_guides` and on the
:doc:`Build_basics <Build_basics>` doc page about building a shared library.

569
doc/src/Python_usage.rst Normal file
View File

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

3
doc/src/Speed_kokkos.rst
View File

@ -27,6 +27,7 @@ GPUs) and HIP (for AMD GPUs). You choose the mode at build time to
produce an executable compatible with a specific hardware.
.. admonition:: NVIDIA CUDA support
:class: note
To build with Kokkos support for NVIDIA GPUs, the NVIDIA CUDA toolkit
software version 9.0 or later must be installed on your system. See
@ -34,6 +35,7 @@ produce an executable compatible with a specific hardware.
how to check and do this.
.. admonition:: CUDA and MPI library compatibility
:class: note
Kokkos with CUDA currently implicitly assumes that the MPI library is
CUDA-aware. This is not always the case, especially when using
@ -46,6 +48,7 @@ produce an executable compatible with a specific hardware.
cuda/aware off <package>` in the input file.
.. admonition:: AMD GPU support
:class: note
To build with Kokkos the HIPCC compiler from the AMD ROCm software
version 3.5 or later is required. Supporting this Kokkos mode in

135
doc/src/Tools.rst
View File

@ -92,6 +92,7 @@ Miscellaneous tools
* :ref:`emacs <emacs>`
* :ref:`i-pi <ipi>`
* :ref:`kate <kate>`
* :ref:`LAMMPS shell <lammps_shell>`
* :ref:`singularity <singularity_tool>`
* :ref:`vim <vim>`
@ -397,10 +398,141 @@ The file was provided by Alessandro Luigi Sellerio
----------
.. _lammps_shell:
LAMMPS shell
------------
.. versionadded:: 9Oct2020
Overview
========
The LAMMPS Shell, ``lammps-shell`` is a program that functions very
similar to the regular LAMMPS executable but has several modifications
and additions that make it more powerful for interactive sessions,
i.e. where you type LAMMPS commands from the prompt instead of reading
them from a file.
- It uses the readline and history libraries to provide command line
editing and context aware TAB-expansion (details on that below).
- When processing an input file with the '-in' or '-i' flag from the
command line, it does not exit at the end of that input file but
stops at a prompt, so that additional commands can be issued
- Errors will not abort the shell but return to the prompt.
- It has additional commands aimed at interactive use (details below).
- Interrupting a calculation with CTRL-C will not terminate the
session but rather enforce a timeout to cleanly stop an ongoing
run (more info on timeouts is in the timer command documentation).
These enhancements makes the LAMMPS shell an attractive choice for
interactive LAMMPS sessions in graphical user interfaces.
TAB-expansion
=============
When writing commands interactively at the shell prompt, you can hit
the TAB key at any time to try and complete the text. This completion
is context aware and will expand any first word only to commands
available in that executable.
- For style commands it will expand to available styles of the
corresponding category (e.g. pair styles after a
:doc:`pair_style <pair_style>` command).
- For :doc:`compute <compute>`, :doc:`fix <fix>`, or :doc:`dump <dump>`
it will also expand only to already defined groups for the group-ID
keyword.
- For commands like :doc:`compute_modify <compute_modify>`,
:doc:`fix_modify <fix_modify>`, or :doc:`dump_modify <dump_modify>`
it will expand to known compute/fix/dump IDs only.
- When typing references to computes, fixes, or variables with a
"c\_", "f\_", or "v\_" prefix, respectively, then the expansion will
be to known compute/fix IDs and variable names. Variable name
expansion is also available for the ${name} variable syntax.
- In all other cases TAB expansion will complete to names of files
and directories.
Command line editing and history
================================
When typing commands, command line editing similar to what BASH
provides is available. Thus it is possible to move around the
currently line and perform various cut and insert and edit operations.
Previous commands can be retrieved by scrolling up (and down)
or searching (e.g. with CTRL-r).
Also history expansion through using the exclamation mark '!'
can be performed. Examples: '!!' will be replaced with the previous
command, '!-2' will repeat the command before that, '!30' will be
replaced with event number 30 in the command history list, and
'!run' with the last command line that started with "run". Adding
a ":p" to such a history expansion will result that the expansion is
printed and added to the history list, but NOT executed.
On exit the LAMMPS shell will write the history list to a file
".lammps_history" in the current working directory. If such a
file exists when the LAMMPS shell is launched it will be read to
populate the history list.
This is realized via the readline library and can thus be customized
with an ``.inputrc`` file in the home directory. For application
specific customization, the LAMMPS shell uses the name "lammps-shell".
For more information about using and customizing an application using
readline, please see the available documentation at:
`http://www.gnu.org/s/readline/#Documentation
<http://www.gnu.org/s/readline/#Documentation>`_
Additional commands
===================
The following commands are added to the LAMMPS shell on top of the
regular LAMMPS commands:
.. parsed-literal::
help (or ?) print a brief help message
history display the current command history list
clear_history wipe out the current command history list
pwd print current working directory
cd <directory> change current working directory (same as pwd if no directory)
mem print current and maximum memory usage
\|<command> execute <command> as a shell command and return to the command prompt
exit exit the LAMMPS shell cleanly (unlike the "quit" command)
Please note that some known shell operations are implemented in the
LAMMPS :doc:`shell command <shell>` in a platform neutral fashion,
while using the '\|' character will always pass the following text
to the operating system's shell command.
Compilation
===========
Compilation of the LAMMPS shell can be enabled by setting the CMake
variable ``BUILD_LAMMPS_SHELL`` to "on" or using the makefile in the
``tools/lammps-shell`` folder to compile after building LAMMPS using
the conventional make procedure. The makefile will likely need
customization depending on the features and settings used for
compiling LAMMPS.
Limitations
===========
The LAMMPS shell was not designed for use with MPI parallelization
via ``mpirun`` or ``mpiexec`` or ``srun``.
----------
.. _arc:
lmp2arc tool
----------------------
------------
The lmp2arc sub-directory contains a tool for converting LAMMPS output
files to the format for Accelrys' Insight MD code (formerly
@ -663,6 +795,7 @@ The singularity sub-directory contains container definitions files
that can be used to build container images for building and testing
LAMMPS on specific OS variants using the `Singularity <https://sylabs.io>`_
container software. Contributions for additional variants are welcome.
For more details please see the README.md file in that folder.
----------

2
doc/src/compute_centro_atom.rst
View File

@ -133,7 +133,7 @@ simulation into gold (FCC). These were provided by Jon Zimmerman
Stacking faults ~ 5.0 (4.0 to 6.0)
Free surface ~ 23.0
These values are \*not\* normalized by the square of the lattice
These values are **not** normalized by the square of the lattice
parameter. If they were, normalized values would be:
.. parsed-literal::

4
doc/src/compute_tally.rst
View File

@ -107,8 +107,8 @@ The computes in this package are not compatible with dynamic groups.
Related commands
""""""""""""""""
*compute group/group*\ _compute_group_group.html, *compute
heat/flux*\ _compute_heat_flux.html
* :doc:`compute group/group <compute_group_group>`
* :doc:`compute heat/flux <compute_heat_flux>`
Default
"""""""

4
doc/src/dump_cfg_uef.rst
View File

@ -24,8 +24,8 @@ Examples
.. code-block:: LAMMPS
dump 1 all cfg/uef 10 dump.\*.cfg mass type xs ys zs
dump 2 all cfg/uef 100 dump.\*.cfg mass type xs ys zs id c_stress
dump 1 all cfg/uef 10 dump.*.cfg mass type xs ys zs
dump 2 all cfg/uef 100 dump.*.cfg mass type xs ys zs id c_stress
Description
"""""""""""

32
doc/src/dump_image.rst
View File

@ -21,7 +21,7 @@ Syntax
* color = atom attribute that determines color of each atom
* diameter = atom attribute that determines size of each atom
* zero or more keyword/value pairs may be appended
* keyword = *atom* or *adiam* or *bond* or *line* or *tri* or *body* or *fix* or *size* or *view* or *center* or *up* or *zoom* or *persp* or *box* or *axes* or *subbox* or *shiny* or *ssao*
* keyword = *atom* or *adiam* or *bond* or *line* or *tri* or *body* or *fix* or *size* or *view* or *center* or *up* or *zoom* or *box* or *axes* or *subbox* or *shiny* or *ssao*
.. parsed-literal::
@ -62,9 +62,6 @@ Syntax
*zoom* value = zfactor = size that simulation box appears in image
zfactor = scale image size by factor > 1 to enlarge, factor < 1 to shrink
zfactor can be a variable (see below)
*persp* value = pfactor = amount of "perspective" in image
pfactor = amount of perspective (0 = none, < 1 = some, > 1 = highly skewed)
pfactor can be a variable (see below)
*box* values = yes/no diam = draw outline of simulation box
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
@ -87,9 +84,9 @@ Examples
.. code-block:: LAMMPS
dump d0 all image 100 dump.\*.jpg type type
dump d1 mobile image 500 snap.\*.png element element ssao yes 4539 0.6
dump d2 all image 200 img-\*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
dump d0 all image 100 dump.*.jpg type type
dump d1 mobile image 500 snap.*.png element element ssao yes 4539 0.6
dump d2 all image 200 img-*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
dump m0 all movie 1000 movie.mpg type type size 640 480
dump m1 all movie 1000 movie.avi type type size 640 480
dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720
@ -426,13 +423,14 @@ i.e. the number of pixels in each direction.
----------
The *view*\ , *center*\ , *up*\ , *zoom*\ , and *persp* values determine how
The *view*\ , *center*\ , *up*\ , and *zoom* values determine how
3d simulation space is mapped to the 2d plane of the image. Basically
they control how the simulation box appears in the image.
All of the *view*\ , *center*\ , *up*\ , *zoom*\ , and *persp* values can be
All of the *view*\ , *center*\ , *up*\ , and *zoom* values can be
specified as numeric quantities, whose meaning is explained below.
Any of them can also be specified as an :doc:`equal-style variable <variable>`, by using v_name as the value, where "name" is
Any of them can also be specified as an :doc:`equal-style variable <variable>`,
by using v_name as the value, where "name" is
the variable name. In this case the variable will be evaluated on the
timestep each image is created to create a new value. If the
equal-style variable is time-dependent, this is a means of changing
@ -483,19 +481,6 @@ image mostly filled by the atoms in the simulation box. A *zfactor* >
1 will make the simulation box larger; a *zfactor* < 1 will make it
smaller. *Zfactor* must be a value > 0.0.
The *persp* keyword determines how much depth perspective is present
in the image. Depth perspective makes lines that are parallel in
simulation space appear non-parallel in the image. A *pfactor* value
of 0.0 means that parallel lines will meet at infinity (1.0/pfactor),
which is an orthographic rendering with no perspective. A *pfactor*
value between 0.0 and 1.0 will introduce more perspective. A *pfactor*
value > 1 will create a highly skewed image with a large amount of
perspective.
.. note::
The *persp* keyword is not yet supported as an option.
----------
The *box* keyword determines if and how the simulation box boundaries
@ -692,7 +677,6 @@ The defaults for the keywords are as follows:
* up = 0 0 1 (for 3d)
* up = 0 1 0 (for 2d)
* zoom = 1.0
* persp = 0.0
* box = yes 0.02
* axes = no 0.0 0.0
* subbox no 0.0

2
doc/src/fix_property_atom.rst
View File

@ -106,6 +106,7 @@ when ghost atoms are created (at every re-neighboring) to insure the
new properties are also defined for the ghost atoms.
.. admonition:: Properties on ghost atoms
:class: note
If you use this command with the *mol*\ , *q* or *rmass* vectors,
then you most likely want to set *ghost* yes, since these properties
@ -116,6 +117,7 @@ new properties are also defined for the ghost atoms.
those vectors but do not set *ghost* yes.
.. admonition:: Limitations on ghost atom properties
:class: note
The properties for ghost atoms are not updated every timestep,
but only once every few steps when neighbor lists are re-built. Thus

6
doc/src/fix_wall_gran.rst
View File

@ -205,11 +205,11 @@ the following table:
+-------+----------------------------------------------------+----------------+
| 4 | Force :math:`f_z` exerted on the wall | force units |
+-------+----------------------------------------------------+----------------+
| 5 | :math:`\Delta x` between wall surface and particle | distance units |
| 5 | :math:`x`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 6 | :math:`\Delta y` between wall surface and particle | distance units |
| 6 | :math:`y`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 7 | :math:`\Delta z` between wall surface and particle | distance units |
| 7 | :math:`z`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 8 | Radius :math:`r` of atom | distance units |
+-------+----------------------------------------------------+----------------+

6
doc/src/fix_wall_gran_region.rst
View File

@ -246,11 +246,11 @@ the following table:
+-------+----------------------------------------------------+----------------+
| 4 | Force :math:`f_z` exerted on the wall | force units |
+-------+----------------------------------------------------+----------------+
| 5 | :math:`\Delta x` between wall surface and particle | distance units |
| 5 | :math:`x`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 6 | :math:`\Delta y` between wall surface and particle | distance units |
| 6 | :math:`y`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 7 | :math:`\Delta z` between wall surface and particle | distance units |
| 7 | :math:`z`-coordinate of contact point on wall | distance units |
+-------+----------------------------------------------------+----------------+
| 8 | Radius :math:`r` of atom | distance units |
+-------+----------------------------------------------------+----------------+

6
doc/src/if.rst
View File

@ -140,12 +140,12 @@ clarity, you must enclose the entire expression in quotes.
An expression is built out of numbers (which start with a digit or
period or minus sign) or strings (which start with a letter and can
contain alphanumeric characters or underscores):
contain alphanumeric characters, underscores, or forward slashes):
.. parsed-literal::
0.2, 100, 1.0e20, -15.4, etc
InP, myString, a123, ab_23_cd, etc
0.2, 100, 1.0e20, -15.4, ...
InP, myString, a123, ab_23_cd, lj/cut, ...
and Boolean operators:

131
doc/src/pair_coul_tt.rst Normal file
View File

@ -0,0 +1,131 @@
.. index:: pair_style coul/tt
pair_style coul/tt command
==========================
Syntax
""""""
.. code-block:: LAMMPS
pair_style style args
* style = *coul/tt*
* args = list of arguments for a particular style
.. parsed-literal::
*coul/tt* args = n cutoff
n = degree of polynomial
cutoff = global cutoff (distance units)
Examples
""""""""
.. code-block:: LAMMPS
pair_style hybrid/overlay ... coul/tt 4 12.0
pair_coeff 1 2 coul/tt 4.5 1.0
pair_coeff 1 2 coul/tt 4.0 1.0 4 12.0
pair_coeff 1 3* coul/tt 4.5 1.0 4
Description
"""""""""""
The *coul/tt* pair style is meant to be used with force fields that
include explicit polarization through Drude dipoles.
The *coul/tt* pair style should be used as a sub-style within in the
:doc:`pair_style hybrid/overlay <pair_hybrid>` command, in conjunction with a
main pair style including Coulomb interactions and *thole* pair style,
or with *lj/cut/thole/long* pair style that is equivalent to the combination
of preceding two.
The *coul/tt* pair styles compute the charge-dipole Coulomb interaction damped
at short distances by a function
.. math::
f_{n,ij}(r) = 1 - c_{ij} \cdot e^{-b_{ij} r} \sum_{k=0}^n \frac{(b_{ij} r)^k}{k!}
This function results from an adaptation to the Coulomb interaction :ref:`(Salanne)
<Salanne1>` of the damping function originally proposed
by :ref:`Tang Toennies <TangToennies1>` for van der Waals interactions.
The polynomial takes the degree 4 for damping the Coulomb interaction.
The parameters :math:`b_{ij}` and :math:`c_{ij}` could be determined from
first-principle calculations for small, mainly mono-atomic, ions :ref:`(Salanne)
<Salanne1>`, or else treated as empirical for large molecules.
In pair styles with Drude induced dipoles, this damping function is typically
applied to the interactions between a Drude charge (either :math:`q_{D,i}` on
a Drude particle or :math:`-q_{D,i}` on the respective
Drude core)) and a charge on a non-polarizable atom, :math:`q_{j}`.
The Tang-Toennies function could also be used to damp electrostatic
interactions between the (non-polarizable part of the) charge of a core,
:math:`q_{i}-q_{D,i}`, and the Drude charge of another, :math:`-q_{D,j}`.
The :math:`b_{ij}` and :math:`c_{ij}` are equal to :math:`b_{ji}` and
:math:`c_{ji}` in the case of core-core interactions.
For pair_style *coul/tt*\ , the following coefficients must be defined for
each pair of atoms types via the :doc:`pair_coeff <pair_coeff>` command
as in the example above.
* :math:`b_{ij}`
* :math:`c_{ij}`
* degree of polynomial (positive integer)
* cutoff (distance units)
The last two coefficients are optional. If not specified the global
degree of the polynomial or the global cutoff specified in the pair_style
command are used. In order to specify a cutoff (forth argument), the degree of
the polynomial (third argument) must also be specified.
----------
Mixing, shift, table, tail correction, restart, rRESPA info
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
The *coul/tt* pair style does not support mixing. Thus, coefficients
for all I,J pairs must be specified explicitly.
Restrictions
""""""""""""
These pair styles are part of the USER-DRUDE package. They are only
enabled if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` doc page for more info.
This pair_style should currently not be used with the :doc:`charmm dihedral
style <dihedral_charmm>` if the latter has non-zero 1-4 weighting
factors. This is because the *coul/tt* pair style does not know which
pairs are 1-4 partners of which dihedrals.
Related commands
""""""""""""""""
:doc:`fix drude <fix_drude>`, :doc:`fix langevin/drude <fix_langevin_drude>`,
:doc:`fix drude/transform <fix_drude_transform>`,
:doc:`compute temp/drude <compute_temp_drude>`,
:doc:`pair_style thole <pair_thole>`
Default
"""""""
none
----------
.. _Thole3:
**(Thole)** Chem Phys, 59, 341 (1981).
.. _Salanne1:
**(Salanne)** Salanne, Rotenberg, Jahn, Vuilleumier, Simon, Christian and Madden, Theor Chem Acc, 131, 1143 (2012).
.. _TangToennies1:
**(Tang and Toennies)** J Chem Phys, 80, 3726 (1984).

7
doc/src/pair_mesocnt.rst
View File

@ -77,8 +77,11 @@ boron nitride nanotubes.
.. note::
LAMMPS comes with one *mesocnt* style potential file
where the default number of data points per table is 1001.
Because of their size, *mesocnt* style potential files
are not bundled with LAMMPS. When compiling LAMMPS from
source code, the file ``C_10_10.mesocnt`` should be downloaded
transparently from `https://download.lammps.org/potentials/C_10_10.mesocnt <https://download.lammps.org/potentials/C_10_10.mesocnt>`_
This file has as number of data points per table 1001.
This is sufficient for NVT simulations. For proper energy
conservation, we recommend using a potential file where
the resolution for Phi is at least 2001 data points.

15
doc/src/pair_mesont_tpm.rst
View File

@ -147,12 +147,17 @@ where L is the maximum segment length, R is the maximum tube radius, and
segments. Because of the use of extended chain concept at CNT ends, the recommended
cutoff is 3L.
The MESONT-TABTP_10_10.xrs potential file provided with LAMMPS (see the
potentials directory) is parameterized for metal :doc:`units <units>`.
.. note::
Because of their size, *mesont* style potential files
are not bundled with LAMMPS. When compiling LAMMPS from
source code, the file ``TABTP_10_10.mesont`` should be downloaded
transparently from `https://download.lammps.org/potentials/TABTP_10_10.mesont <https://download.lammps.org/potentials/TABTP_10_10.mesont>`_
The ``TABTP_10_10.mesont`` potential file is parameterized for metal :doc:`units <units>`.
You can use the carbon nanotube mesoscopic force field with any LAMMPS units,
but you would need to create your own TPMSSTP.xrs and TPMA.xrs potential files
with coefficients listed in appropriate units, if your simulation
does not use "metal" units.
but you would need to create your own potential files with coefficients listed in
appropriate units, if your simulation does not use "metal" units.
The chirality parameters set during system generation must match the values
specified during generation of the potential tables.

110
doc/src/pair_reaxc.rst
View File

@ -92,13 +92,11 @@ tested).
create a suitable ReaxFF parameterization.
The *cfile* setting can be specified as NULL, in which case default
settings are used. A control file can be specified which defines
values of control variables. Some control variables are
global parameters for the ReaxFF potential. Others define certain
performance and output settings.
Each line in the control file specifies the value for
a control variable. The format of the control file is described
below.
settings are used. A control file can be specified which defines values
of control variables. Some control variables are global parameters for
the ReaxFF potential. Others define certain performance and output
settings. Each line in the control file specifies the value for a
control variable. The format of the control file is described below.
.. note::
@ -224,7 +222,10 @@ H, you would use the following pair_coeff command:
pair_coeff * * ffield.reax C C N H
----------
-------------
Control file
""""""""""""
The format of a line in the control file is as follows:
@ -238,60 +239,73 @@ If the value of a control variable is not specified, then default
values are used. What follows is the list of variables along with a
brief description of their use and default values.
simulation_name: Output files produced by *pair_style reax/c* carry
this name + extensions specific to their contents. Partial energies
are reported with a ".pot" extension, while the trajectory file has
".trj" extension.
tabulate_long_range: To improve performance, long range interactions
can optionally be tabulated (0 means no tabulation). Value of this
variable denotes the size of the long range interaction table. The
range from 0 to long range cutoff (defined in the *ffield* file) is
divided into *tabulate_long_range* points. Then at the start of
simulation, we fill in the entries of the long range interaction table
by computing the energies and forces resulting from van der Waals and
Coulomb interactions between every possible atom type pairs present in
the input system. During the simulation we consult to the long range
interaction table to estimate the energy and forces between a pair of
atoms. Linear interpolation is used for estimation. (default value =
0)
*simulation_name*
Output files produced by *pair_style reax/c* carry
this name + extensions specific to their contents. Partial energies
are reported with a ".pot" extension, while the trajectory file has
".trj" extension.
energy_update_freq: Denotes the frequency (in number of steps) of
writes into the partial energies file. (default value = 0)
*tabulate_long_range*
To improve performance, long range interactions can optionally be
tabulated (0 means no tabulation). Value of this variable denotes the
size of the long range interaction table. The range from 0 to long
range cutoff (defined in the *ffield* file) is divided into
*tabulate_long_range* points. Then at the start of simulation, we
fill in the entries of the long range interaction table by computing
the energies and forces resulting from van der Waals and Coulomb
interactions between every possible atom type pairs present in the
input system. During the simulation we consult to the long range
interaction table to estimate the energy and forces between a pair of
atoms. Linear interpolation is used for estimation. (default value = 0)
nbrhood_cutoff: Denotes the near neighbors cutoff (in Angstroms)
regarding the bonded interactions. (default value = 5.0)
*energy_update_freq*
Denotes the frequency (in number of steps) of writes into the partial
energies file. (default value = 0)
hbond_cutoff: Denotes the cutoff distance (in Angstroms) for hydrogen
bond interactions.(default value = 7.5. A value of 0.0 turns off
hydrogen bonds)
*nbrhood_cutoff*
Denotes the near neighbors cutoff (in Angstroms)
regarding the bonded interactions. (default value = 5.0)
bond_graph_cutoff: is the threshold used in determining what is a
physical bond, what is not. Bonds and angles reported in the
trajectory file rely on this cutoff. (default value = 0.3)
*hbond_cutoff*
Denotes the cutoff distance (in Angstroms) for hydrogen
bond interactions.(default value = 7.5. A value of 0.0 turns off
hydrogen bonds)
thb_cutoff: cutoff value for the strength of bonds to be considered in
three body interactions. (default value = 0.001)
*bond_graph_cutoff*
is the threshold used in determining what is a
physical bond, what is not. Bonds and angles reported in the
trajectory file rely on this cutoff. (default value = 0.3)
thb_cutoff_sq: cutoff value for the strength of bond order products
to be considered in three body interactions. (default value = 0.00001)
*thb_cutoff*
cutoff value for the strength of bonds to be considered in
three body interactions. (default value = 0.001)
write_freq: Frequency of writes into the trajectory file. (default
value = 0)
*thb_cutoff_sq*
cutoff value for the strength of bond order products
to be considered in three body interactions. (default value = 0.00001)
traj_title: Title of the trajectory - not the name of the trajectory
file.
*write_freq*
Frequency of writes into the trajectory file. (default
value = 0)
atom_info: 1 means print only atomic positions + charge (default = 0)
*traj_title*
Title of the trajectory - not the name of the trajectory file.
atom_forces: 1 adds net forces to atom lines in the trajectory file
(default = 0)
*atom_info*
1 means print only atomic positions + charge (default = 0)
atom_velocities: 1 adds atomic velocities to atoms line (default = 0)
*atom_forces*
1 adds net forces to atom lines in the trajectory file (default = 0)
bond_info: 1 prints bonds in the trajectory file (default = 0)
*atom_velocities*
1 adds atomic velocities to atoms line (default = 0)
angle_info: 1 prints angles in the trajectory file (default = 0)
*bond_info*
1 prints bonds in the trajectory file (default = 0)
*angle_info*
1 prints angles in the trajectory file (default = 0)
----------

2
doc/src/pair_resquared.rst
View File

@ -231,4 +231,4 @@ none
.. _Babadi:
**(Berardi)** Babadi, Ejtehadi, Everaers, J Comp Phys, 219, 770-779 (2006).
**(Babadi)** Babadi, Ejtehadi, Everaers, J Comp Phys, 219, 770-779 (2006).

1
doc/src/pair_style.rst
View File

@ -144,6 +144,7 @@ accelerated styles exist.
* :doc:`coul/slater/long <pair_coul>` - long-range smeared out Coulomb
* :doc:`coul/shield <pair_coul_shield>` - Coulomb for boron nitride for use with :doc:`ilp/graphene/hbn <pair_ilp_graphene_hbn>` potential
* :doc:`coul/streitz <pair_coul>` - Coulomb via Streitz/Mintmire Slater orbitals
* :doc:`coul/tt <pair_coul_tt>` - damped charge-dipole Coulomb for Drude dipoles
* :doc:`coul/wolf <pair_coul>` - Coulomb via Wolf potential
* :doc:`coul/wolf/cs <pair_cs>` - Coulomb via Wolf potential with core/shell adjustments
* :doc:`dpd <pair_dpd>` - dissipative particle dynamics (DPD)

33
doc/src/pg_lib_add.rst
View File

@ -1,33 +0,0 @@
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://doxygen.nl>`_ 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.

104
doc/src/pg_lib_create.rst
View File

@ -1,104 +0,0 @@
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

111
doc/src/pg_lib_properties.rst
View File

@ -1,111 +0,0 @@
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 it.
This enables combining 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.
.. code-block:: C
#include "library.h"
#include <stdio.h>
int main(int argc, char **argv)
{
void *handle;
int i;
handle = lammps_open_no_mpi(0, NULL, NULL);
lammps_file(handle,"in.sysinit");
printf("running simulation with %g atoms\n",
lammps_get_natoms(handle));
lammps_command(handle,"run 1000 post no");
for (i=0; i < 10; ++i) {
lammps_command(handle,"run 100 pre no post no");
printf("PE = %g\nKE = %g\n",
lammps_get_thermo(handle,"pe"),
lammps_get_thermo(handle,"ke"));
}
lammps_close(handle);
return 0;
}
-----------------------
.. doxygenfunction:: lammps_version
:project: progguide
-----------------------
.. doxygenfunction:: lammps_memory_usage
:project: progguide
-----------------------
.. doxygenfunction:: lammps_get_mpi_comm
: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_datatype
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_global
:project: progguide
-----------------------
.. doxygenfunction:: lammps_extract_atom_datatype
: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
View File

@ -1,29 +0,0 @@
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
View File

@ -1,30 +0,0 @@
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
View File

@ -1,158 +0,0 @@
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

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