Files
lammps/doc/html/Library.html
2025-01-13 14:55:48 +00:00

337 lines
25 KiB
HTML

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>1. LAMMPS Library Interfaces &mdash; LAMMPS documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinx-design.min.css" type="text/css" />
<link rel="stylesheet" href="_static/css/lammps.css" type="text/css" />
<link rel="shortcut icon" href="_static/lammps.ico"/>
<link rel="canonical" href="https://docs.lammps.org/Library.html" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/design-tabs.js?v=f930bc37"></script>
<script async="async" src="_static/mathjax/es5/tex-mml-chtml.js?v=cadf963e"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="1.1.1. Creating or deleting a LAMMPS object" href="Library_create.html" />
<link rel="prev" title="11.6. Warning messages" href="Errors_warnings.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="Manual.html">
<img src="_static/lammps-logo.png" class="logo" alt="Logo"/>
</a>
<div class="lammps_version">Version: <b>19 Nov 2024</b></div>
<div class="lammps_release">git info: </div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="Intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Install.html">2. Install LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Build.html">3. Build LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Run_head.html">4. Run LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Commands.html">5. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Packages.html">6. Optional packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Speed.html">7. Accelerate performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Howto.html">8. Howto discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Examples.html">9. Example scripts</a></li>
<li class="toctree-l1"><a class="reference internal" href="Tools.html">10. Auxiliary tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Errors.html">11. Errors</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Programmer Guide</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">1. LAMMPS Library Interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#lammps-c-library-api">1.1. LAMMPS C Library API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Library_create.html">1.1.1. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_execute.html">1.1.2. Executing commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_properties.html">1.1.3. System properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_atoms.html">1.1.4. Per-atom properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_objects.html">1.1.5. Compute, fixes, variables</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_scatter.html">1.1.6. Scatter/gather operations</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_neighbor.html">1.1.7. Neighbor list access</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_config.html">1.1.8. Configuration information</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_utility.html">1.1.9. Utility functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="Library_add.html">1.1.10. Extending the C API</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#lammps-python-apis">1.2. LAMMPS Python APIs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#lammps-fortran-api">1.3. LAMMPS Fortran API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Fortran.html">1.3.1. The <code class="xref f f-mod docutils literal notranslate"><span class="pre">LIBLAMMPS</span></code> Fortran Module</a></li>
<li class="toctree-l3"><a class="reference internal" href="Fortran.html#creating-or-deleting-a-lammps-object">1.3.2. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l3"><a class="reference internal" href="Fortran.html#executing-lammps-commands">1.3.3. Executing LAMMPS commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="Fortran.html#accessing-system-properties">1.3.4. Accessing system properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="Fortran.html#the-liblammps-module-api">1.3.5. The <code class="xref f f-mod docutils literal notranslate"><span class="pre">LIBLAMMPS</span></code> module API</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#lammps-cplusplus-api">1.4. LAMMPS C++ API</a><ul>
<li class="toctree-l3"><a class="reference internal" href="Cplusplus.html">1.4.1. Using the C++ API directly</a></li>
<li class="toctree-l3"><a class="reference internal" href="Cplusplus.html#creating-or-deleting-a-lammps-object">1.4.2. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l3"><a class="reference internal" href="Cplusplus.html#executing-lammps-commands">1.4.3. Executing LAMMPS commands</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Python_head.html">2. Use Python with LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Modify.html">3. Modifying &amp; extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Developer.html">4. Information for Developers</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Command Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="commands_list.html">Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="fixes.html">Fix Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="computes.html">Compute Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="pairs.html">Pair Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="bonds.html">Bond Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="angles.html">Angle Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="dihedrals.html">Dihedral Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="impropers.html">Improper Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="dumps.html">Dump Styles</a></li>
<li class="toctree-l1"><a class="reference internal" href="fix_modify_atc_commands.html">fix_modify AtC commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Bibliography.html">Bibliography</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="Manual.html">LAMMPS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content style-external-links">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active"><span class="section-number">1. </span>LAMMPS Library Interfaces</li>
<li class="wy-breadcrumbs-aside">
<a href="https://www.lammps.org"><img src="_static/lammps-logo.png" width="64" height="16" alt="LAMMPS Homepage"></a> | <a href="Commands_all.html">Commands</a>
</li>
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
<a href="Errors_warnings.html" class="btn btn-neutral float-left" title="11.6. Warning messages" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Library_create.html" class="btn btn-neutral float-right" title="1.1.1. Creating or deleting a LAMMPS object" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<p><span class="math notranslate nohighlight">\(\renewcommand{\AA}{\text{Å}}\)</span></p>
<section id="lammps-library-interfaces">
<h1><span class="section-number">1. </span>LAMMPS Library Interfaces<a class="headerlink" href="#lammps-library-interfaces" title="Link to this heading"></a></h1>
<p>As described on the <a class="reference internal" href="Howto_library.html"><span class="doc">library interface to LAMMPS</span></a>
page, LAMMPS can be built as a library (static or shared), so that it
can be called by another code, used in a <a class="reference internal" href="Howto_couple.html"><span class="doc">coupled manner</span></a> with other codes, or driven through a <a class="reference internal" href="Python_head.html"><span class="doc">Python
script</span></a>. The LAMMPS standalone executable itself is
essentially a thin wrapper on top of the LAMMPS library, which creates a
LAMMPS instance, passes the input for processing to that instance, and
then exits.</p>
<p>Most of the APIs described below are based on C language wrapper
functions in the files <code class="docutils literal notranslate"><span class="pre">src/library.h</span></code> and <code class="docutils literal notranslate"><span class="pre">src/library.cpp</span></code>, but
it is also possible to use C++ directly. The basic procedure is
always the same: you create one or more instances of
<a class="reference internal" href="Classes_lammps.html#_CPPv4N9LAMMPS_NS6LAMMPSE" title="LAMMPS_NS::LAMMPS"><code class="xref cpp cpp-class docutils literal notranslate"><span class="pre">LAMMPS</span></code></a>, 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.</p>
<div class="note admonition" id="thread-safety">
<p class="admonition-title">Thread-safety</p>
<p>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 <em>lib</em>
folder, interface LAMMPS to Fortran libraries, or the code uses
static variables (like the COLVARS package).</p>
<p>Another major issue to deal with is to correctly handle MPI.
Creating a LAMMPS instance requires passing an MPI communicator, or
it assumes the <code class="docutils literal notranslate"><span class="pre">MPI_COMM_WORLD</span></code> 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.</p>
</div>
<hr class="docutils" />
<section id="lammps-c-library-api">
<span id="lammps-c-api"></span><h2><span class="section-number">1.1. </span>LAMMPS C Library API<a class="headerlink" href="#lammps-c-library-api" title="Link to this heading"></a></h2>
<p>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 <a class="reference internal" href="Python_module.html"><span class="doc">Python</span></a> and <a class="reference internal" href="Fortran.html"><span class="doc">Fortran</span></a> modules. Almost all
functions of the C language API require an argument containing a
“handle” in the form of a <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> type variable, which points to the
location of a LAMMPS class instance.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">library.h</span></code> header file by default does not include the <code class="docutils literal notranslate"><span class="pre">mpi.h</span></code>
header file and thus hides the <a class="reference internal" href="Library_create.html#_CPPv411lammps_openiPPc8MPI_CommPPv" title="lammps_open"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">lammps_open()</span></code></a> function which
requires the declaration of the <code class="docutils literal notranslate"><span class="pre">MPI_comm</span></code> data type. This is only
a problem when the communicator that would be passed is different from
<code class="docutils literal notranslate"><span class="pre">MPI_COMM_WORLD</span></code>. Otherwise calling <a class="reference internal" href="Library_create.html#_CPPv418lammps_open_no_mpiiPPcPPv" title="lammps_open_no_mpi"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">lammps_open_no_mpi()</span></code></a>
will work just as well. To make <a class="reference internal" href="Library_create.html#_CPPv411lammps_openiPPc8MPI_CommPPv" title="lammps_open"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">lammps_open()</span></code></a> available,
you need to compile the code with <code class="docutils literal notranslate"><span class="pre">-DLAMMPS_LIB_MPI</span></code> or add the line
<code class="docutils literal notranslate"><span class="pre">#define</span> <span class="pre">LAMMPS_LIB_MPI</span></code> before <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">&quot;library.h&quot;</span></code>.</p>
<p>Please note the <code class="docutils literal notranslate"><span class="pre">mpi.h</span></code> 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
<code class="docutils literal notranslate"><span class="pre">STUBS</span></code> MPI library. In that case the calling code may be compiled
with a different MPI library so long as <a class="reference internal" href="Library_create.html#_CPPv418lammps_open_no_mpiiPPcPPv" title="lammps_open_no_mpi"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">lammps_open_no_mpi()</span></code></a>
is called to create a LAMMPS instance. In that case each MPI rank will
run LAMMPS in serial mode.</p>
<div class="note admonition">
<p class="admonition-title">Errors versus exceptions</p>
<p>If the LAMMPS executable encounters an error condition, it will abort
after printing an error message. It does so by catching the
exceptions that LAMMPS could throw. For a C library interface this
is usually not desirable since the calling code might lack the
ability to catch such exceptions. Thus, the library functions will
catch those exceptions and return from the affected functions. The
error status <a class="reference internal" href="Library_utility.html#_CPPv416lammps_has_errorPv" title="lammps_has_error"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">can</span> <span class="pre">be</span> <span class="pre">queried</span></code></a> and an
<a class="reference internal" href="Library_utility.html#_CPPv429lammps_get_last_error_messagePvPci" title="lammps_get_last_error_message"><code class="xref cpp cpp-func docutils literal notranslate"><span class="pre">error</span> <span class="pre">message</span> <span class="pre">retrieved</span></code></a>.
This is, for example used by the <a class="reference internal" href="Python_module.html"><span class="doc">LAMMPS python module</span></a> and then a suitable Python exception is thrown.</p>
</div>
<div class="note admonition">
<p class="admonition-title">Using the C library interface as a plugin</p>
<p>Rather than including the C library directly and link to the LAMMPS
library at compile time, you can use the <code class="docutils literal notranslate"><span class="pre">liblammpsplugin.h</span></code> header
file and the <code class="docutils literal notranslate"><span class="pre">liblammpsplugin.c</span></code> C code in the
<code class="docutils literal notranslate"><span class="pre">examples/COUPLE/plugin</span></code> folder for an interface to LAMMPS that is
largely identical to the regular library interface, only that it will
load a LAMMPS shared library file at runtime. This can be useful for
applications where the interface to LAMMPS would be an optional
feature.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>No checks are made on the arguments of the function calls of the C
library interface. <em>All</em> function arguments must be non-NULL unless
<em>explicitly</em> 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.</p>
</div>
<hr class="docutils" />
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Library_create.html">1.1.1. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_execute.html">1.1.2. Executing commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_properties.html">1.1.3. System properties</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_atoms.html">1.1.4. Per-atom properties</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_objects.html">1.1.5. Compute, fixes, variables</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_scatter.html">1.1.6. Scatter/gather operations</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_neighbor.html">1.1.7. Neighbor list access</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_config.html">1.1.8. Configuration information</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_utility.html">1.1.9. Utility functions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Library_add.html">1.1.10. Extending the C API</a></li>
</ul>
</div>
<hr class="docutils" />
</section>
<section id="lammps-python-apis">
<span id="lammps-python-api"></span><h2><span class="section-number">1.2. </span>LAMMPS Python APIs<a class="headerlink" href="#lammps-python-apis" title="Link to this heading"></a></h2>
<p>The LAMMPS Python module enables calling the LAMMPS C library API from
Python by dynamically loading functions in the LAMMPS shared library through
the <a class="reference external" href="https://docs.python.org/3/library/ctypes.html">Python ctypes module</a>.
Because of the dynamic loading, it is <strong>required</strong> that LAMMPS is compiled
in <a class="reference internal" href="Build_basics.html#exe"><span class="std std-ref">“shared” mode</span></a>. 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 <a class="reference internal" href="Python_head.html"><span class="doc">Use Python with LAMMPS</span></a>
section of the manual. Use of the LAMMPS Python module is described in
<a class="reference internal" href="Python_module.html"><span class="doc">The lammps Python module</span></a>.</p>
<hr class="docutils" />
</section>
<section id="lammps-fortran-api">
<span id="id1"></span><h2><span class="section-number">1.3. </span>LAMMPS Fortran API<a class="headerlink" href="#lammps-fortran-api" title="Link to this heading"></a></h2>
<p>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.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Fortran.html">1.3.1. The <code class="xref f f-mod docutils literal notranslate"><span class="pre">LIBLAMMPS</span></code> Fortran Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fortran.html#creating-or-deleting-a-lammps-object">1.3.2. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fortran.html#executing-lammps-commands">1.3.3. Executing LAMMPS commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fortran.html#accessing-system-properties">1.3.4. Accessing system properties</a></li>
<li class="toctree-l1"><a class="reference internal" href="Fortran.html#the-liblammps-module-api">1.3.5. The <code class="xref f f-mod docutils literal notranslate"><span class="pre">LIBLAMMPS</span></code> module API</a></li>
</ul>
</div>
<hr class="docutils" />
</section>
<section id="lammps-cplusplus-api">
<span id="id2"></span><h2><span class="section-number">1.4. </span>LAMMPS C++ API<a class="headerlink" href="#lammps-cplusplus-api" title="Link to this heading"></a></h2>
<p>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.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Cplusplus.html">1.4.1. Using the C++ API directly</a></li>
<li class="toctree-l1"><a class="reference internal" href="Cplusplus.html#creating-or-deleting-a-lammps-object">1.4.2. Creating or deleting a LAMMPS object</a></li>
<li class="toctree-l1"><a class="reference internal" href="Cplusplus.html#executing-lammps-commands">1.4.3. Executing LAMMPS commands</a></li>
</ul>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="Errors_warnings.html" class="btn btn-neutral float-left" title="11.6. Warning messages" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Library_create.html" class="btn btn-neutral float-right" title="1.1.1. Creating or deleting a LAMMPS object" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2003-2025 Sandia Corporation.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(false);
});
</script>
</body>
</html>