495 lines
35 KiB
HTML
495 lines
35 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>2.2. Installation — 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/tabs.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/Python_install.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/tabs.js?v=3030b3cb"></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="2.3. Run LAMMPS from Python" href="Python_run.html" />
|
||
<link rel="prev" title="2.1. Overview" href="Python_overview.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"><a class="reference internal" href="Library.html">1. LAMMPS Library Interfaces</a></li>
|
||
<li class="toctree-l1 current"><a class="reference internal" href="Python_head.html">2. Use Python with LAMMPS</a><ul class="current">
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_overview.html">2.1. Overview</a></li>
|
||
<li class="toctree-l2 current"><a class="current reference internal" href="#">2.2. Installation</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#installing-the-lammps-python-module-and-shared-library">2.2.1. Installing the LAMMPS Python Module and Shared Library</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#extending-python-to-run-in-parallel">2.2.2. Extending Python to run in parallel</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_run.html">2.3. Run LAMMPS from Python</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_module.html">2.4. The <code class="docutils literal notranslate"><span class="pre">lammps</span></code> Python module</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_ext.html">2.5. Extending the Python interface</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_call.html">2.6. Calling Python from LAMMPS</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_formats.html">2.7. Output Readers</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_examples.html">2.8. Example Python scripts</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_error.html">2.9. Handling LAMMPS errors</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Python_trouble.html">2.10. Troubleshooting</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Modify.html">3. Modifying & 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"><a href="Python_head.html"><span class="section-number">2. </span>Use Python with LAMMPS</a></li>
|
||
<li class="breadcrumb-item active"><span class="section-number">2.2. </span>Installation</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="Python_overview.html" class="btn btn-neutral float-left" title="2.1. Overview" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="Python_run.html" class="btn btn-neutral float-right" title="2.3. Run LAMMPS from Python" 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="installation">
|
||
<h1><span class="section-number">2.2. </span>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h1>
|
||
<p>The LAMMPS Python module enables calling the <a class="reference internal" href="Library.html#lammps-c-api"><span class="std std-ref">LAMMPS C library API</span></a> from Python by dynamically loading functions in the
|
||
LAMMPS shared library through the Python <a class="reference external" href="https://docs.python.org/3/library/ctypes.html">ctypes</a>
|
||
module. Because of the dynamic loading, it is required that LAMMPS is
|
||
compiled in <a class="reference internal" href="Build_basics.html#exe"><span class="std std-ref">“shared” mode</span></a>.</p>
|
||
<p>Two components are necessary for Python to be able to invoke LAMMPS code:</p>
|
||
<ul class="simple">
|
||
<li><p>The LAMMPS Python Package (<code class="docutils literal notranslate"><span class="pre">lammps</span></code>) from the <code class="docutils literal notranslate"><span class="pre">python</span></code> folder</p></li>
|
||
<li><p>The LAMMPS Shared Library (<code class="docutils literal notranslate"><span class="pre">liblammps.so</span></code>, <code class="docutils literal notranslate"><span class="pre">liblammps.dylib</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">liblammps.dll</span></code>) from the folder where you compiled LAMMPS.</p></li>
|
||
</ul>
|
||
<section id="installing-the-lammps-python-module-and-shared-library">
|
||
<span id="python-install-guides"></span><h2><span class="section-number">2.2.1. </span>Installing the LAMMPS Python Module and Shared Library<a class="headerlink" href="#installing-the-lammps-python-module-and-shared-library" title="Link to this heading"></a></h2>
|
||
<p>Making LAMMPS usable within Python and vice versa requires putting the
|
||
LAMMPS Python package (<code class="docutils literal notranslate"><span class="pre">lammps</span></code>) 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 inside of the installed
|
||
<code class="docutils literal notranslate"><span class="pre">lammps</span></code> package folder. There are multiple ways to achieve this.</p>
|
||
<ol class="arabic simple">
|
||
<li><p>Install both components into a Python <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> 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.</p></li>
|
||
<li><p>Do an installation into a virtual environment.</p></li>
|
||
<li><p>Leave the files where they are in the source/development tree and
|
||
adjust some environment variables.</p></li>
|
||
</ol>
|
||
<div class="sphinx-tabs docutils container">
|
||
<div aria-label="Tabbed content" class="closeable" role="tablist"><button aria-controls="panel-0-0-0" aria-selected="true" class="sphinx-tabs-tab" id="tab-0-0-0" name="0-0" role="tab" tabindex="0">Python package</button><button aria-controls="panel-0-0-1" aria-selected="false" class="sphinx-tabs-tab" id="tab-0-0-1" name="0-1" role="tab" tabindex="-1">Virtual environment</button><button aria-controls="panel-0-0-2" aria-selected="false" class="sphinx-tabs-tab" id="tab-0-0-2" name="0-2" role="tab" tabindex="-1">In place usage</button></div><div aria-labelledby="tab-0-0-0" class="sphinx-tabs-panel" id="panel-0-0-0" name="0-0" role="tabpanel" tabindex="0"><p>Compile LAMMPS with either <a class="reference internal" href="Build_cmake.html"><span class="doc">CMake</span></a> or the
|
||
<a class="reference internal" href="Build_make.html"><span class="doc">traditional make</span></a> procedure in <a class="reference internal" href="Build_basics.html#exe"><span class="std std-ref">shared
|
||
mode</span></a>. After compilation has finished, type (in the
|
||
compilation folder):</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>install-python
|
||
</pre></div>
|
||
</div>
|
||
<p>This will try to build a so-called (binary) wheel file, a
|
||
compressed binary python package and then install it with the
|
||
python package manager ‘pip’. Installation will be attempted into
|
||
a system-wide <code class="docutils literal notranslate"><span class="pre">site-packages</span></code> folder and if that fails into the
|
||
corresponding folder in the user’s home directory. For a
|
||
system-wide installation you usually would have to gain superuser
|
||
privilege first, e.g. though <code class="docutils literal notranslate"><span class="pre">sudo</span></code></p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>File</p></th>
|
||
<th class="head"><p>Location</p></th>
|
||
<th class="head"><p>Notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>LAMMPS Python package</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">$HOME/.local/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>LAMMPS shared library</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">$HOME/.local/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>For a system-wide installation those folders would then become.</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>File</p></th>
|
||
<th class="head"><p>Location</p></th>
|
||
<th class="head"><p>Notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>LAMMPS Python package</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>LAMMPS shared library</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">/usr/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>No environment variables need to be set for those, as those
|
||
folders are searched by default by Python or the LAMMPS Python
|
||
package.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 24Mar2022.</span></p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>If there is an existing installation of the LAMMPS python
|
||
module, <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install-python</span></code> will try to update it.
|
||
However, that will fail if the older version of the module
|
||
was installed by LAMMPS versions until 17Feb2022. Those
|
||
were using the distutils package, which does not create a
|
||
“manifest” that allows a clean uninstall. The <code class="docutils literal notranslate"><span class="pre">make</span>
|
||
<span class="pre">install-python</span></code> command will always produce a
|
||
lammps-<version>-<python>-<abi>-<os>-<arch>.whl file (the
|
||
‘wheel’). And this file can be later installed directly with
|
||
<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">pip</span> <span class="pre">install</span> <span class="pre"><wheel</span> <span class="pre">file>.whl</span></code> without having to
|
||
type <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install-python</span></code> again and repeating the build
|
||
step, too.</p>
|
||
</div>
|
||
<p>For the traditional make process you can override the python
|
||
version to version x.y when calling <code class="docutils literal notranslate"><span class="pre">make</span></code> with
|
||
<code class="docutils literal notranslate"><span class="pre">PYTHON=pythonX.Y</span></code>. For a CMake based compilation this choice
|
||
has to be made during the CMake configuration step.</p>
|
||
<p>If the default settings of <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install-python</span></code> are not what you want,
|
||
you can invoke <code class="docutils literal notranslate"><span class="pre">install.py</span></code> from the python directory manually as</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python<span class="w"> </span>install.py<span class="w"> </span>-p<span class="w"> </span><python<span class="w"> </span>package><span class="w"> </span>-l<span class="w"> </span><shared<span class="w"> </span>library><span class="w"> </span>-v<span class="w"> </span><version.h<span class="w"> </span>file><span class="w"> </span><span class="o">[</span>-n<span class="o">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul class="simple">
|
||
<li><p>The <code class="docutils literal notranslate"><span class="pre">-p</span></code> flag points to the <code class="docutils literal notranslate"><span class="pre">lammps</span></code> Python package folder to be installed,</p></li>
|
||
<li><p>the <code class="docutils literal notranslate"><span class="pre">-l</span></code> flag points to the LAMMPS shared library file to be installed,</p></li>
|
||
<li><p>the <code class="docutils literal notranslate"><span class="pre">-v</span></code> flag points to the LAMMPS version header file to extract the version date,</p></li>
|
||
<li><p>and the optional <code class="docutils literal notranslate"><span class="pre">-n</span></code> instructs the script to only build a wheel file
|
||
but not attempt to install it.</p></li>
|
||
</ul>
|
||
</div><div aria-labelledby="tab-0-0-1" class="sphinx-tabs-panel" hidden="true" id="panel-0-0-1" name="0-1" role="tabpanel" tabindex="0"><p>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 <a class="reference external" href="https://peps.python.org/pep-0405/">PEP 405:
|
||
Python Virtual Environments</a> for more
|
||
information.</p>
|
||
<p>To create a virtual environment in the folder <code class="docutils literal notranslate"><span class="pre">$HOME/myenv</span></code>,
|
||
use the <a class="reference external" href="https://docs.python.org/3/library/venv.html">venv</a> module as follows.</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># create virtual environment in folder $HOME/myenv</span>
|
||
python3<span class="w"> </span>-m<span class="w"> </span>venv<span class="w"> </span><span class="nv">$HOME</span>/myenv
|
||
</pre></div>
|
||
</div>
|
||
<p>For Python versions prior 3.3 you can use <a class="reference external" href="https://packaging.python.org/en/latest/key_projects/#virtualenv">virtualenv</a>
|
||
command instead of “python3 -m venv”. This step has to be done
|
||
only once.</p>
|
||
<p>To activate the virtual environment type:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">source</span><span class="w"> </span><span class="nv">$HOME</span>/myenv/bin/activate
|
||
</pre></div>
|
||
</div>
|
||
<p>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
|
||
<code class="docutils literal notranslate"><span class="pre">deactivate</span></code> command.</p>
|
||
<p>When using CMake to build LAMMPS, you need to set
|
||
<code class="docutils literal notranslate"><span class="pre">CMAKE_INSTALL_PREFIX</span></code> to the value of the <code class="docutils literal notranslate"><span class="pre">$VIRTUAL_ENV</span></code>
|
||
environment variable during the configuration step. For the
|
||
traditional make procedure, no additional steps are needed.
|
||
After compiling LAMMPS you can do a “Python package only”
|
||
installation with <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install-python</span></code> and the LAMMPS Python
|
||
package and the shared library file are installed into the
|
||
following locations:</p>
|
||
<table class="docutils align-default">
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>File</p></th>
|
||
<th class="head"><p>Location</p></th>
|
||
<th class="head"><p>Notes</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p>LAMMPS Python Module</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p>LAMMPS shared library</p></td>
|
||
<td><ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">$VIRTUAL_ENV/lib/pythonX.Y/site-packages/lammps</span></code></p></li>
|
||
</ul>
|
||
</td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">X.Y</span></code> depends on the installed Python version</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
</div><div aria-labelledby="tab-0-0-2" class="sphinx-tabs-panel" hidden="true" id="panel-0-0-2" name="0-2" role="tabpanel" tabindex="0"><p>You can also <a class="reference internal" href="Build.html"><span class="doc">compile LAMMPS</span></a> as usual in
|
||
<a class="reference internal" href="Build_basics.html#exe"><span class="std std-ref">“shared” mode</span></a> leave the shared library and Python
|
||
package inside the source/compilation folders. Instead of
|
||
copying the files where they can be found, you need to set the environment
|
||
variables <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> (for the Python package) and
|
||
<code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code> (or <code class="docutils literal notranslate"><span class="pre">DYLD_LIBRARY_PATH</span></code> on macOS</p>
|
||
<p>For Bourne shells (bash, ksh and similar) the commands are:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PYTHONPATH</span><span class="o">=</span><span class="si">${</span><span class="nv">PYTHONPATH</span><span class="si">}</span>:<span class="si">${</span><span class="nv">HOME</span><span class="si">}</span>/lammps/python
|
||
<span class="nb">export</span><span class="w"> </span><span class="nv">LD_LIBRARY_PATH</span><span class="o">=</span><span class="si">${</span><span class="nv">LD_LIBRARY_PATH</span><span class="si">}</span>:<span class="si">${</span><span class="nv">HOME</span><span class="si">}</span>/lammps/src
|
||
</pre></div>
|
||
</div>
|
||
<p>For the C-shells like csh or tcsh the commands are:</p>
|
||
<div class="highlight-csh notranslate"><div class="highlight"><pre><span></span><span class="nb">setenv </span>PYTHONPATH <span class="k">${</span><span class="nv">PYTHONPATH</span><span class="k">}</span>:<span class="k">${</span><span class="nv">HOME</span><span class="k">}</span>/lammps/python
|
||
<span class="nb">setenv </span>LD_LIBRARY_PATH <span class="k">${</span><span class="nv">LD_LIBRARY_PATH</span><span class="k">}</span>:<span class="k">${</span><span class="nv">HOME</span><span class="k">}</span>/lammps/src
|
||
</pre></div>
|
||
</div>
|
||
<p>On macOS you may also need to set <code class="docutils literal notranslate"><span class="pre">DYLD_LIBRARY_PATH</span></code> accordingly.
|
||
You can make those changes permanent by editing your <code class="docutils literal notranslate"><span class="pre">$HOME/.bashrc</span></code>
|
||
or <code class="docutils literal notranslate"><span class="pre">$HOME/.login</span></code> files, respectively.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> needs to point to the parent folder that contains the <code class="docutils literal notranslate"><span class="pre">lammps</span></code> package!</p>
|
||
</div>
|
||
</div></div>
|
||
<p>To verify if LAMMPS can be successfully started from Python, start the
|
||
Python interpreter, load the <code class="docutils literal notranslate"><span class="pre">lammps</span></code> Python module and create a
|
||
LAMMPS instance. This should not generate an error message and produce
|
||
output similar to the following:</p>
|
||
<blockquote>
|
||
<div><div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python
|
||
<span class="go">Python 3.8.5 (default, Sep 5 2020, 10:50:12)</span>
|
||
<span class="go">[GCC 10.2.0] on linux</span>
|
||
<span class="go">Type "help", "copyright", "credits" or "license" for more information.</span>
|
||
<span class="go">>>> import lammps</span>
|
||
<span class="go">>>> lmp = lammps.lammps()</span>
|
||
<span class="go">LAMMPS (18 Sep 2020)</span>
|
||
<span class="go">using 1 OpenMP thread(s) per MPI task</span>
|
||
<span class="go">>>></span>
|
||
</pre></div>
|
||
</div>
|
||
</div></blockquote>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Unless you opted for “In place use”, you will have to rerun the installation
|
||
any time you recompile LAMMPS to ensure the latest Python package and shared
|
||
library are installed and used.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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. <code class="docutils literal notranslate"><span class="pre">liblammps_mpi.so</span></code> or <code class="docutils literal notranslate"><span class="pre">liblammps_gpu.so</span></code>) into the
|
||
appropriate folder as indicated above. You can then select the
|
||
desired library through the <em>name</em> argument of the LAMMPS object
|
||
constructor (see <a class="reference internal" href="Python_create.html#python-create-lammps"><span class="std std-ref">Creating or deleting a LAMMPS object</span></a>).</p>
|
||
</div>
|
||
</section>
|
||
<section id="extending-python-to-run-in-parallel">
|
||
<span id="python-install-mpi4py"></span><h2><span class="section-number">2.2.2. </span>Extending Python to run in parallel<a class="headerlink" href="#extending-python-to-run-in-parallel" title="Link to this heading"></a></h2>
|
||
<p>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.</p>
|
||
<p>We have tested this with <a class="reference external" href="https://mpi4py.readthedocs.io/">MPI for Python</a>
|
||
(aka mpi4py) and you will find installation instruction for it below.</p>
|
||
<p>Installation of mpi4py (version 3.0.3 as of Sep 2020) can be done as
|
||
follows:</p>
|
||
<ul>
|
||
<li><p>Via <code class="docutils literal notranslate"><span class="pre">pip</span></code> into a local user folder with:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>--user<span class="w"> </span>mpi4py
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Via <code class="docutils literal notranslate"><span class="pre">dnf</span></code> into a system folder for RedHat/Fedora systems:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># for use with OpenMPI</span>
|
||
sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>python3-mpi4py-openmpi
|
||
<span class="c1"># for use with MPICH</span>
|
||
sudo<span class="w"> </span>dnf<span class="w"> </span>install<span class="w"> </span>python3-mpi4py-openmpi
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Via <code class="docutils literal notranslate"><span class="pre">pip</span></code> into a virtual environment (see above):</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span><span class="nb">source</span><span class="w"> </span><span class="nv">$HOME</span>/myenv/activate
|
||
<span class="gp gp-VirtualEnv">(myenv)</span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>mpi4py
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>Via <code class="docutils literal notranslate"><span class="pre">pip</span></code> into a system folder (not recommended):</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>mpi4py
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>For more detailed installation instructions and additional options,
|
||
please see the <a class="reference external" href="https://mpi4py.readthedocs.io/en/stable/install.html">mpi4py installation</a> page.</p>
|
||
<p>To use <code class="docutils literal notranslate"><span class="pre">mpi4py</span></code> and LAMMPS in parallel from Python, you <strong>must</strong> make
|
||
certain that <strong>both</strong> are using the <strong>same</strong> 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
|
||
<code class="docutils literal notranslate"><span class="pre">src/MAKE/Makefile.foo</span></code> file. The installation process of <code class="docutils literal notranslate"><span class="pre">mpi4py</span></code>
|
||
uses the <code class="docutils literal notranslate"><span class="pre">mpicc</span></code> command to find information about the MPI it uses to
|
||
build against. And it tries to load “libmpi.so” from the
|
||
<code class="docutils literal notranslate"><span class="pre">LD_LIBRARY_PATH</span></code>. 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.</p>
|
||
<p>If you have successfully installed mpi4py, you should be able to run
|
||
Python and type</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">mpi4py</span><span class="w"> </span><span class="kn">import</span> <span class="n">MPI</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>without error. You should also be able to run Python in parallel
|
||
on a simple test script</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mpirun<span class="w"> </span>-np<span class="w"> </span><span class="m">4</span><span class="w"> </span>python3<span class="w"> </span>test.py
|
||
</pre></div>
|
||
</div>
|
||
<p>where <code class="docutils literal notranslate"><span class="pre">test.py</span></code> contains the lines</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">mpi4py</span><span class="w"> </span><span class="kn">import</span> <span class="n">MPI</span>
|
||
<span class="n">comm</span> <span class="o">=</span> <span class="n">MPI</span><span class="o">.</span><span class="n">COMM_WORLD</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Proc </span><span class="si">%d</span><span class="s2"> out of </span><span class="si">%d</span><span class="s2"> procs"</span> <span class="o">%</span> <span class="p">(</span><span class="n">comm</span><span class="o">.</span><span class="n">Get_rank</span><span class="p">(),</span><span class="n">comm</span><span class="o">.</span><span class="n">Get_size</span><span class="p">()))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>and see one line of output for each processor you run on. Please note
|
||
that the order of the lines is not deterministic</p>
|
||
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>mpirun<span class="w"> </span>-np<span class="w"> </span><span class="m">4</span><span class="w"> </span>python3<span class="w"> </span>test.py
|
||
<span class="go">Proc 0 out of 4 procs</span>
|
||
<span class="go">Proc 1 out of 4 procs</span>
|
||
<span class="go">Proc 2 out of 4 procs</span>
|
||
<span class="go">Proc 3 out of 4 procs</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||
<a href="Python_overview.html" class="btn btn-neutral float-left" title="2.1. Overview" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="Python_run.html" class="btn btn-neutral float-right" title="2.3. Run LAMMPS from Python" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||
</div>
|
||
|
||
<hr/>
|
||
|
||
<div role="contentinfo">
|
||
<p>© 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> |