686 lines
58 KiB
HTML
686 lines
58 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>8.6.5. PyLammps Tutorial — 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/Howto_pylammps.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="8.6.6. Using LAMMPS on Windows 10 with WSL" href="Howto_wsl.html" />
|
||
<link rel="prev" title="8.6.4. Moltemplate Tutorial" href="Howto_moltemplate.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 class="current">
|
||
<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 current"><a class="reference internal" href="Howto.html">8. Howto discussions</a><ul class="current">
|
||
<li class="toctree-l2"><a class="reference internal" href="Howto.html#general-howto">8.1. General howto</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Howto.html#settings-howto">8.2. Settings howto</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Howto.html#analysis-howto">8.3. Analysis howto</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Howto.html#force-fields-howto">8.4. Force fields howto</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="Howto.html#packages-howto">8.5. Packages howto</a></li>
|
||
<li class="toctree-l2 current"><a class="reference internal" href="Howto.html#tutorials-howto">8.6. Tutorials howto</a><ul class="current">
|
||
<li class="toctree-l3"><a class="reference internal" href="Howto_cmake.html">8.6.1. Using CMake with LAMMPS</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="Howto_github.html">8.6.2. LAMMPS GitHub tutorial</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="Howto_lammps_gui.html">8.6.3. Using LAMMPS-GUI</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="Howto_moltemplate.html">8.6.4. Moltemplate Tutorial</a></li>
|
||
<li class="toctree-l3 current"><a class="current reference internal" href="#">8.6.5. PyLammps Tutorial</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="Howto_wsl.html">8.6.6. Using LAMMPS on Windows 10 with WSL</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</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>
|
||
<li class="toctree-l1"><a class="reference internal" href="Library.html">1. LAMMPS Library Interfaces</a></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 & 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="Howto.html"><span class="section-number">8. </span>Howto discussions</a></li>
|
||
<li class="breadcrumb-item active"><span class="section-number">8.6.5. </span>PyLammps Tutorial</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="Howto_moltemplate.html" class="btn btn-neutral float-left" title="8.6.4. Moltemplate Tutorial" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="Howto_wsl.html" class="btn btn-neutral float-right" title="8.6.6. Using LAMMPS on Windows 10 with WSL" 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="pylammps-tutorial">
|
||
<h1><a class="toc-backref" href="#id2" role="doc-backlink"><span class="section-number">8.6.5. </span>PyLammps Tutorial</a><a class="headerlink" href="#pylammps-tutorial" title="Link to this heading"></a></h1>
|
||
<nav class="contents" id="contents">
|
||
<p class="topic-title">Contents</p>
|
||
<ul class="simple">
|
||
<li><p><a class="reference internal" href="#pylammps-tutorial" id="id2">PyLammps Tutorial</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#overview" id="id3">Overview</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#comparison-of-lammps-and-pylammps-interfaces" id="id4">Comparison of lammps and PyLammps interfaces</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#lammps-lammps" id="id5">lammps.lammps</a></p></li>
|
||
<li><p><a class="reference internal" href="#lammps-pylammps" id="id6">lammps.PyLammps</a></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#quick-start" id="id7">Quick Start</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#system-wide-installation" id="id8">System-wide Installation</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#step-1-building-lammps-as-a-shared-library" id="id9">Step 1: Building LAMMPS as a shared library</a></p></li>
|
||
<li><p><a class="reference internal" href="#step-2-installing-the-lammps-python-package" id="id10">Step 2: Installing the LAMMPS Python package</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#installation-inside-of-a-virtualenv" id="id11">Installation inside of a virtualenv</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#benefits-of-using-a-virtualenv" id="id12">Benefits of using a virtualenv</a></p></li>
|
||
<li><p><a class="reference internal" href="#creating-a-virtualenv-with-lammps-installed" id="id13">Creating a virtualenv with lammps installed</a></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#creating-a-new-instance-of-pylammps" id="id14">Creating a new instance of PyLammps</a></p></li>
|
||
<li><p><a class="reference internal" href="#commands" id="id15">Commands</a></p></li>
|
||
<li><p><a class="reference internal" href="#system-state" id="id16">System state</a></p></li>
|
||
<li><p><a class="reference internal" href="#working-with-lammps-variables" id="id17">Working with LAMMPS variables</a></p></li>
|
||
<li><p><a class="reference internal" href="#retrieving-the-value-of-an-arbitrary-lammps-expressions" id="id18">Retrieving the value of an arbitrary LAMMPS expressions</a></p></li>
|
||
<li><p><a class="reference internal" href="#accessing-atom-data" id="id19">Accessing atom data</a></p></li>
|
||
<li><p><a class="reference internal" href="#evaluating-thermo-data" id="id20">Evaluating thermo data</a></p></li>
|
||
<li><p><a class="reference internal" href="#error-handling-with-pylammps" id="id21">Error handling with PyLammps</a></p></li>
|
||
<li><p><a class="reference internal" href="#using-pylammps-in-ipython-notebooks-and-jupyter" id="id22">Using PyLammps in IPython notebooks and Jupyter</a></p></li>
|
||
<li><p><a class="reference internal" href="#ipylammps-examples" id="id23">IPyLammps Examples</a></p>
|
||
<ul>
|
||
<li><p><a class="reference internal" href="#validating-a-dihedral-potential" id="id24">Validating a dihedral potential</a></p></li>
|
||
<li><p><a class="reference internal" href="#running-a-monte-carlo-relaxation" id="id25">Running a Monte Carlo relaxation</a></p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><a class="reference internal" href="#using-pylammps-and-mpi4py-experimental" id="id26">Using PyLammps and mpi4py (Experimental)</a></p></li>
|
||
<li><p><a class="reference internal" href="#feedback-and-contributing" id="id27">Feedback and Contributing</a></p></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
<section id="overview">
|
||
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Overview</a><a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
|
||
<p><a class="reference internal" href="Python_module.html#lammps.PyLammps" title="lammps.PyLammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">PyLammps</span></code></a> is a Python wrapper class for
|
||
LAMMPS which can be created on its own or use an existing
|
||
<a class="reference internal" href="Python_module.html#lammps.lammps" title="lammps.lammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">lammps</span> <span class="pre">Python</span></code></a> object. It creates a simpler,
|
||
more “pythonic” interface to common LAMMPS functionality, in contrast to
|
||
the <a class="reference internal" href="Python_module.html#lammps.lammps" title="lammps.lammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">lammps</span></code></a> wrapper for the LAMMPS <a class="reference internal" href="Library.html#lammps-c-api"><span class="std std-ref">C
|
||
language library interface API</span></a> which is written using
|
||
<a class="reference external" href="https://docs.python.org/3/library/ctypes.html">Python ctypes</a>. The <a class="reference internal" href="Python_module.html#lammps.lammps" title="lammps.lammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">lammps</span></code></a>
|
||
wrapper is discussed on the <a class="reference internal" href="Python_head.html"><span class="doc">Use Python with LAMMPS</span></a> doc page.</p>
|
||
<p>Unlike the flat <a class="reference external" href="https://docs.python.org/3/library/ctypes.html">ctypes</a> interface, PyLammps exposes a
|
||
discoverable API. It no longer requires knowledge of the underlying C++
|
||
code implementation. Finally, the <a class="reference internal" href="Python_module.html#lammps.IPyLammps" title="lammps.IPyLammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">IPyLammps</span></code></a> wrapper builds on top of <a class="reference internal" href="Python_module.html#lammps.PyLammps" title="lammps.PyLammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">PyLammps</span></code></a> and adds some additional features for <a class="reference external" href="https://ipython.org/">IPython
|
||
integration</a> into <a class="reference external" href="https://jupyter.org/">Jupyter notebooks</a>, e.g. for
|
||
embedded visualization output from <a class="reference internal" href="dump_image.html"><span class="doc">dump style image</span></a>.</p>
|
||
<section id="comparison-of-lammps-and-pylammps-interfaces">
|
||
<h3><a class="toc-backref" href="#id4" role="doc-backlink">Comparison of lammps and PyLammps interfaces</a><a class="headerlink" href="#comparison-of-lammps-and-pylammps-interfaces" title="Link to this heading"></a></h3>
|
||
<section id="lammps-lammps">
|
||
<h4><a class="toc-backref" href="#id5" role="doc-backlink">lammps.lammps</a><a class="headerlink" href="#lammps-lammps" title="Link to this heading"></a></h4>
|
||
<ul class="simple">
|
||
<li><p>uses <a class="reference external" href="https://docs.python.org/3/library/ctypes.html">ctypes</a></p></li>
|
||
<li><p>direct memory access to native C++ data with optional support for NumPy arrays</p></li>
|
||
<li><p>provides functions to send and receive data to LAMMPS</p></li>
|
||
<li><p>interface modeled after the LAMMPS <a class="reference internal" href="Library.html#lammps-c-api"><span class="std std-ref">C language library interface API</span></a></p></li>
|
||
<li><p>requires knowledge of how LAMMPS internally works (C pointers, etc)</p></li>
|
||
<li><p>full support for running Python with MPI using <a class="reference external" href="https://mpi4py.readthedocs.io">mpi4py</a></p></li>
|
||
<li><p>no overhead from creating a more Python-like interface</p></li>
|
||
</ul>
|
||
</section>
|
||
<section id="lammps-pylammps">
|
||
<h4><a class="toc-backref" href="#id6" role="doc-backlink">lammps.PyLammps</a><a class="headerlink" href="#lammps-pylammps" title="Link to this heading"></a></h4>
|
||
<ul class="simple">
|
||
<li><p>higher-level abstraction built on <em>top</em> of the original <a class="reference internal" href="Python_module.html#lammps.lammps" title="lammps.lammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">ctypes</span> <span class="pre">based</span> <span class="pre">interface</span></code></a></p></li>
|
||
<li><p>manipulation of Python objects</p></li>
|
||
<li><p>communication with LAMMPS is hidden from API user</p></li>
|
||
<li><p>shorter, more concise Python</p></li>
|
||
<li><p>better IPython integration, designed for quick prototyping</p></li>
|
||
<li><p>designed for serial execution</p></li>
|
||
<li><p>additional overhead from capturing and parsing the LAMMPS screen output</p></li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="quick-start">
|
||
<h2><a class="toc-backref" href="#id7" role="doc-backlink">Quick Start</a><a class="headerlink" href="#quick-start" title="Link to this heading"></a></h2>
|
||
<section id="system-wide-installation">
|
||
<h3><a class="toc-backref" href="#id8" role="doc-backlink">System-wide Installation</a><a class="headerlink" href="#system-wide-installation" title="Link to this heading"></a></h3>
|
||
<section id="step-1-building-lammps-as-a-shared-library">
|
||
<h4><a class="toc-backref" href="#id9" role="doc-backlink">Step 1: Building LAMMPS as a shared library</a><a class="headerlink" href="#step-1-building-lammps-as-a-shared-library" title="Link to this heading"></a></h4>
|
||
<p>To use LAMMPS inside of Python it has to be compiled as shared
|
||
library. This library is then loaded by the Python interface. In this
|
||
example we enable the MOLECULE package and compile LAMMPS with PNG, JPEG
|
||
and FFMPEG output support enabled.</p>
|
||
<p>Step 1a: For the CMake based build system, the steps are:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mkdir<span class="w"> </span><span class="nv">$LAMMPS_DIR</span>/build-shared
|
||
<span class="nb">cd</span><span class="w"> </span><span class="nv">$LAMMPS_DIR</span>/build-shared
|
||
|
||
<span class="c1"># MPI, PNG, Jpeg, FFMPEG are auto-detected</span>
|
||
cmake<span class="w"> </span>../cmake<span class="w"> </span>-DPKG_MOLECULE<span class="o">=</span>yes<span class="w"> </span>-DBUILD_LIB<span class="o">=</span>yes<span class="w"> </span>-DBUILD_SHARED_LIBS<span class="o">=</span>yes
|
||
make
|
||
</pre></div>
|
||
</div>
|
||
<p>Step 1b: For the legacy, make based build system, the steps are:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span><span class="nv">$LAMMPS_DIR</span>/src
|
||
|
||
<span class="c1"># add packages if necessary</span>
|
||
make<span class="w"> </span>yes-MOLECULE
|
||
|
||
<span class="c1"># compile shared library using Makefile</span>
|
||
make<span class="w"> </span>mpi<span class="w"> </span><span class="nv">mode</span><span class="o">=</span>shlib<span class="w"> </span><span class="nv">LMP_INC</span><span class="o">=</span><span class="s2">"-DLAMMPS_PNG -DLAMMPS_JPEG -DLAMMPS_FFMPEG"</span><span class="w"> </span><span class="nv">JPG_LIB</span><span class="o">=</span><span class="s2">"-lpng -ljpeg"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="step-2-installing-the-lammps-python-package">
|
||
<h4><a class="toc-backref" href="#id10" role="doc-backlink">Step 2: Installing the LAMMPS Python package</a><a class="headerlink" href="#step-2-installing-the-lammps-python-package" title="Link to this heading"></a></h4>
|
||
<p>PyLammps is part of the lammps Python package. To install it simply install
|
||
that package into your current Python installation with:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>install-python
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Recompiling the shared library requires re-installing the Python package</p>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
<section id="installation-inside-of-a-virtualenv">
|
||
<h3><a class="toc-backref" href="#id11" role="doc-backlink">Installation inside of a virtualenv</a><a class="headerlink" href="#installation-inside-of-a-virtualenv" title="Link to this heading"></a></h3>
|
||
<p>You can use virtualenv to create a custom Python environment specifically tuned
|
||
for your workflow.</p>
|
||
<section id="benefits-of-using-a-virtualenv">
|
||
<h4><a class="toc-backref" href="#id12" role="doc-backlink">Benefits of using a virtualenv</a><a class="headerlink" href="#benefits-of-using-a-virtualenv" title="Link to this heading"></a></h4>
|
||
<ul class="simple">
|
||
<li><p>isolation of your system Python installation from your development installation</p></li>
|
||
<li><p>installation can happen in your user directory without root access (useful for HPC clusters)</p></li>
|
||
<li><p>installing packages through pip allows you to get newer versions of packages than e.g., through apt-get or yum package managers (and without root access)</p></li>
|
||
<li><p>you can even install specific old versions of a package if necessary</p></li>
|
||
</ul>
|
||
<p><strong>Prerequisite (e.g. on Ubuntu)</strong></p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>apt-get<span class="w"> </span>install<span class="w"> </span>python-virtualenv
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="creating-a-virtualenv-with-lammps-installed">
|
||
<h4><a class="toc-backref" href="#id13" role="doc-backlink">Creating a virtualenv with lammps installed</a><a class="headerlink" href="#creating-a-virtualenv-with-lammps-installed" title="Link to this heading"></a></h4>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># create virtualenv named 'testing'</span>
|
||
virtualenv<span class="w"> </span><span class="nv">$HOME</span>/python/testing
|
||
|
||
<span class="c1"># activate 'testing' environment</span>
|
||
<span class="nb">source</span><span class="w"> </span><span class="nv">$HOME</span>/python/testing/bin/activate
|
||
</pre></div>
|
||
</div>
|
||
<p>Now configure and compile the LAMMPS shared library as outlined above.
|
||
When using CMake and the shared library has already been build, you
|
||
need to re-run CMake to update the location of the python executable
|
||
to the location in the virtual environment with:</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>.<span class="w"> </span>-DPython_EXECUTABLE<span class="o">=</span><span class="k">$(</span>which<span class="w"> </span>python<span class="k">)</span>
|
||
|
||
<span class="c1"># install LAMMPS package in virtualenv</span>
|
||
<span class="o">(</span>testing<span class="o">)</span><span class="w"> </span>make<span class="w"> </span>install-python
|
||
|
||
<span class="c1"># install other useful packages</span>
|
||
<span class="o">(</span>testing<span class="o">)</span><span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>matplotlib<span class="w"> </span>jupyter<span class="w"> </span>mpi4py
|
||
|
||
...
|
||
|
||
<span class="c1"># return to original shell</span>
|
||
<span class="o">(</span>testing<span class="o">)</span><span class="w"> </span>deactivate
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="creating-a-new-instance-of-pylammps">
|
||
<h2><a class="toc-backref" href="#id14" role="doc-backlink">Creating a new instance of PyLammps</a><a class="headerlink" href="#creating-a-new-instance-of-pylammps" title="Link to this heading"></a></h2>
|
||
<p>To create a PyLammps object you need to first import the class from the lammps
|
||
module. By using the default constructor, a new <em>lammps</em> instance is created.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">lammps</span><span class="w"> </span><span class="kn">import</span> <span class="n">PyLammps</span>
|
||
<span class="n">L</span> <span class="o">=</span> <span class="n">PyLammps</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can also initialize PyLammps on top of this existing <em>lammps</em> object:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">lammps</span><span class="w"> </span><span class="kn">import</span> <span class="n">lammps</span><span class="p">,</span> <span class="n">PyLammps</span>
|
||
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
|
||
<span class="n">L</span> <span class="o">=</span> <span class="n">PyLammps</span><span class="p">(</span><span class="n">ptr</span><span class="o">=</span><span class="n">lmp</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="commands">
|
||
<h2><a class="toc-backref" href="#id15" role="doc-backlink">Commands</a><a class="headerlink" href="#commands" title="Link to this heading"></a></h2>
|
||
<p>Sending a LAMMPS command with the existing library interfaces is done using
|
||
the command method of the lammps object instance.</p>
|
||
<p>For instance, let’s take the following LAMMPS command:</p>
|
||
<div class="highlight-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">region </span><span class="nv nv-Identifier">box</span><span class="w"> </span><span class="n">block</span><span class="w"> </span><span class="m">0</span><span class="w"> </span><span class="m">10</span><span class="w"> </span><span class="m">0</span><span class="w"> </span><span class="m">5</span><span class="w"> </span><span class="o">-</span><span class="m">0.5</span><span class="w"> </span><span class="m">0.5</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the original interface this command can be executed with the following
|
||
Python code if <em>L</em> was a lammps instance:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"region box block 0 10 0 5 -0.5 0.5"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>With the PyLammps interface, any command can be split up into arbitrary parts
|
||
separated by white-space, passed as individual arguments to a region method.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">region</span><span class="p">(</span><span class="s2">"box block"</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="o">-</span><span class="mf">0.5</span><span class="p">,</span> <span class="mf">0.5</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that each parameter is set as Python literal floating-point number. In the
|
||
PyLammps interface, each command takes an arbitrary parameter list and transparently
|
||
merges it to a single command string, separating individual parameters by white-space.</p>
|
||
<p>The benefit of this approach is avoiding redundant command calls and easier
|
||
parameterization. In the original interface parameterization needed to be done
|
||
manually by creating formatted strings.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"region box block </span><span class="si">%f</span><span class="s2"> </span><span class="si">%f</span><span class="s2"> </span><span class="si">%f</span><span class="s2"> </span><span class="si">%f</span><span class="s2"> </span><span class="si">%f</span><span class="s2"> </span><span class="si">%f</span><span class="s2">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">xlo</span><span class="p">,</span> <span class="n">xhi</span><span class="p">,</span> <span class="n">ylo</span><span class="p">,</span> <span class="n">yhi</span><span class="p">,</span> <span class="n">zlo</span><span class="p">,</span> <span class="n">zhi</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In contrast, methods of PyLammps accept parameters directly and will convert
|
||
them automatically to a final command string.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">region</span><span class="p">(</span><span class="s2">"box block"</span><span class="p">,</span> <span class="n">xlo</span><span class="p">,</span> <span class="n">xhi</span><span class="p">,</span> <span class="n">ylo</span><span class="p">,</span> <span class="n">yhi</span><span class="p">,</span> <span class="n">zlo</span><span class="p">,</span> <span class="n">zhi</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="system-state">
|
||
<h2><a class="toc-backref" href="#id16" role="doc-backlink">System state</a><a class="headerlink" href="#system-state" title="Link to this heading"></a></h2>
|
||
<p>In addition to dispatching commands directly through the PyLammps object, it
|
||
also provides several properties which allow you to query the system state.</p>
|
||
<dl class="simple">
|
||
<dt>L.system</dt><dd><p>Is a dictionary describing the system such as the bounding box or number of atoms</p>
|
||
</dd>
|
||
<dt>L.system.xlo, L.system.xhi</dt><dd><p>bounding box limits along x-axis</p>
|
||
</dd>
|
||
<dt>L.system.ylo, L.system.yhi</dt><dd><p>bounding box limits along y-axis</p>
|
||
</dd>
|
||
<dt>L.system.zlo, L.system.zhi</dt><dd><p>bounding box limits along z-axis</p>
|
||
</dd>
|
||
<dt>L.communication</dt><dd><p>configuration of communication subsystem, such as the number of threads or processors</p>
|
||
</dd>
|
||
<dt>L.communication.nthreads</dt><dd><p>number of threads used by each LAMMPS process</p>
|
||
</dd>
|
||
<dt>L.communication.nprocs</dt><dd><p>number of MPI processes used by LAMMPS</p>
|
||
</dd>
|
||
<dt>L.fixes</dt><dd><p>List of fixes in the current system</p>
|
||
</dd>
|
||
<dt>L.computes</dt><dd><p>List of active computes in the current system</p>
|
||
</dd>
|
||
<dt>L.dump</dt><dd><p>List of active dumps in the current system</p>
|
||
</dd>
|
||
<dt>L.groups</dt><dd><p>List of groups present in the current system</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
<section id="working-with-lammps-variables">
|
||
<h2><a class="toc-backref" href="#id17" role="doc-backlink">Working with LAMMPS variables</a><a class="headerlink" href="#working-with-lammps-variables" title="Link to this heading"></a></h2>
|
||
<p>LAMMPS variables can be both defined and accessed via the PyLammps interface.</p>
|
||
<p>To define a variable you can use the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">variable</span><span class="p">(</span><span class="s2">"a index 2"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A dictionary of all variables is returned by L.variables</p>
|
||
<p>you can access an individual variable by retrieving a variable object from the
|
||
L.variables dictionary by name</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">a</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">variables</span><span class="p">[</span><span class="s1">'a'</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The variable value can then be easily read and written by accessing the value
|
||
property of this object.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nb">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">value</span><span class="p">)</span>
|
||
<span class="n">a</span><span class="o">.</span><span class="n">value</span> <span class="o">=</span> <span class="mi">4</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="retrieving-the-value-of-an-arbitrary-lammps-expressions">
|
||
<h2><a class="toc-backref" href="#id18" role="doc-backlink">Retrieving the value of an arbitrary LAMMPS expressions</a><a class="headerlink" href="#retrieving-the-value-of-an-arbitrary-lammps-expressions" title="Link to this heading"></a></h2>
|
||
<p>LAMMPS expressions can be immediately evaluated by using the eval method. The
|
||
passed string parameter can be any expression containing global thermo values,
|
||
variables, compute or fix data.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">result</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"ke"</span><span class="p">)</span> <span class="c1"># kinetic energy</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"pe"</span><span class="p">)</span> <span class="c1"># potential energy</span>
|
||
|
||
<span class="n">result</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"v_t/2.0"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="accessing-atom-data">
|
||
<h2><a class="toc-backref" href="#id19" role="doc-backlink">Accessing atom data</a><a class="headerlink" href="#accessing-atom-data" title="Link to this heading"></a></h2>
|
||
<p>All atoms in the current simulation can be accessed by using the L.atoms list.
|
||
Each element of this list is an object which exposes its properties (id, type,
|
||
position, velocity, force, etc.).</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># access first atom</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">id</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">type</span>
|
||
|
||
<span class="c1"># access second atom</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">position</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">velocity</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">force</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Some properties can also be used to set:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># set position in 2D simulation</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">)</span>
|
||
|
||
<span class="c1"># set position in 3D simulation</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">0.0</span><span class="p">,</span> <span class="mf">1.</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="evaluating-thermo-data">
|
||
<h2><a class="toc-backref" href="#id20" role="doc-backlink">Evaluating thermo data</a><a class="headerlink" href="#evaluating-thermo-data" title="Link to this heading"></a></h2>
|
||
<p>Each simulation run usually produces thermo output based on system state,
|
||
computes, fixes or variables. The trajectories of these values can be queried
|
||
after a run via the L.runs list. This list contains a growing list of run data.
|
||
The first element is the output of the first run, the second element that of
|
||
the second run.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="c1"># data of first 1000 time steps</span>
|
||
|
||
<span class="n">L</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="mi">1000</span><span class="p">)</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="c1"># data of second 1000 time steps</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Each run contains a dictionary of all trajectories. Each trajectory is
|
||
accessible through its thermo name:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">thermo</span><span class="o">.</span><span class="n">Step</span> <span class="c1"># list of time steps in first run</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">thermo</span><span class="o">.</span><span class="n">Ke</span> <span class="c1"># list of kinetic energy values in first run</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Together with matplotlib plotting data out of LAMMPS becomes simple:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">matplotlib.plot</span><span class="w"> </span><span class="k">as</span><span class="w"> </span><span class="nn">plt</span>
|
||
<span class="n">steps</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">thermo</span><span class="o">.</span><span class="n">Step</span>
|
||
<span class="n">ke</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">runs</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">thermo</span><span class="o">.</span><span class="n">Ke</span>
|
||
<span class="n">plt</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">steps</span><span class="p">,</span> <span class="n">ke</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="error-handling-with-pylammps">
|
||
<h2><a class="toc-backref" href="#id21" role="doc-backlink">Error handling with PyLammps</a><a class="headerlink" href="#error-handling-with-pylammps" title="Link to this heading"></a></h2>
|
||
<p>Using C++ exceptions in LAMMPS for errors allows capturing them on the
|
||
C++ side and rethrowing them on the Python side. This way you can handle
|
||
LAMMPS errors through the Python exception handling mechanism.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>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.</p>
|
||
</div>
|
||
</section>
|
||
<section id="using-pylammps-in-ipython-notebooks-and-jupyter">
|
||
<h2><a class="toc-backref" href="#id22" role="doc-backlink">Using PyLammps in IPython notebooks and Jupyter</a><a class="headerlink" href="#using-pylammps-in-ipython-notebooks-and-jupyter" title="Link to this heading"></a></h2>
|
||
<p>If the LAMMPS Python package is installed for the same Python interpreter as
|
||
IPython, you can use PyLammps directly inside of an IPython notebook inside of
|
||
Jupyter. Jupyter is a powerful integrated development environment (IDE) for
|
||
many dynamic languages like Python, Julia and others, which operates inside of
|
||
any web browser. Besides auto-completion and syntax highlighting it allows you
|
||
to create formatted documents using Markup, mathematical formulas, graphics and
|
||
animations intermixed with executable Python code. It is a great format for
|
||
tutorials and showcasing your latest research.</p>
|
||
<p>To launch an instance of Jupyter simply run the following command inside your
|
||
Python environment (this assumes you followed the Quick Start instructions):</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>jupyter<span class="w"> </span>notebook
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="ipylammps-examples">
|
||
<h2><a class="toc-backref" href="#id23" role="doc-backlink">IPyLammps Examples</a><a class="headerlink" href="#ipylammps-examples" title="Link to this heading"></a></h2>
|
||
<p>Examples of IPython notebooks can be found in the python/examples/pylammps
|
||
subdirectory. To open these notebooks launch <em>jupyter notebook</em> inside this
|
||
directory and navigate to one of them. If you compiled and installed
|
||
a LAMMPS shared library with exceptions, PNG, JPEG and FFMPEG support
|
||
you should be able to rerun all of these notebooks.</p>
|
||
<section id="validating-a-dihedral-potential">
|
||
<h3><a class="toc-backref" href="#id24" role="doc-backlink">Validating a dihedral potential</a><a class="headerlink" href="#validating-a-dihedral-potential" title="Link to this heading"></a></h3>
|
||
<p>This example showcases how an IPython Notebook can be used to compare a simple
|
||
LAMMPS simulation of a harmonic dihedral potential to its analytical solution.
|
||
Four atoms are placed in the simulation and the dihedral potential is applied on
|
||
them using a datafile. Then one of the atoms is rotated along the central axis by
|
||
setting its position from Python, which changes the dihedral angle.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">phi</span> <span class="o">=</span> <span class="p">[</span><span class="n">d</span> \<span class="o">*</span> <span class="n">math</span><span class="o">.</span><span class="n">pi</span> <span class="o">/</span> <span class="mi">180</span> <span class="k">for</span> <span class="n">d</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">360</span><span class="p">)]</span>
|
||
|
||
<span class="n">pos</span> <span class="o">=</span> <span class="p">[(</span><span class="mf">1.0</span><span class="p">,</span> <span class="n">math</span><span class="o">.</span><span class="n">cos</span><span class="p">(</span><span class="n">p</span><span class="p">),</span> <span class="n">math</span><span class="o">.</span><span class="n">sin</span><span class="p">(</span><span class="n">p</span><span class="p">))</span> <span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">phi</span><span class="p">]</span>
|
||
|
||
<span class="n">pe</span> <span class="o">=</span> <span class="p">[]</span>
|
||
<span class="k">for</span> <span class="n">p</span> <span class="ow">in</span> <span class="n">pos</span><span class="p">:</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="n">p</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">pe</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"pe"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>By evaluating the potential energy for each position we can verify that
|
||
trajectory with the analytical formula. To compare both solutions, we plot
|
||
both trajectories over each other using matplotlib, which embeds the generated
|
||
plot inside the IPython notebook.</p>
|
||
<img alt="_images/pylammps_dihedral.jpg" class="align-center" src="_images/pylammps_dihedral.jpg" />
|
||
</section>
|
||
<section id="running-a-monte-carlo-relaxation">
|
||
<h3><a class="toc-backref" href="#id25" role="doc-backlink">Running a Monte Carlo relaxation</a><a class="headerlink" href="#running-a-monte-carlo-relaxation" title="Link to this heading"></a></h3>
|
||
<p>This second example shows how to use PyLammps to create a 2D Monte Carlo Relaxation
|
||
simulation, computing and plotting energy terms and even embedding video output.</p>
|
||
<p>Initially, a 2D system is created in a state with minimal energy.</p>
|
||
<img alt="_images/pylammps_mc_minimum.jpg" class="align-center" src="_images/pylammps_mc_minimum.jpg" />
|
||
<p>It is then disordered by moving each atom by a random delta.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">27848</span><span class="p">)</span>
|
||
<span class="n">deltaperturb</span> <span class="o">=</span> <span class="mf">0.2</span>
|
||
|
||
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">L</span><span class="o">.</span><span class="n">system</span><span class="o">.</span><span class="n">natoms</span><span class="p">):</span>
|
||
<span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">position</span>
|
||
<span class="n">dx</span> <span class="o">=</span> <span class="n">deltaperturb</span> \<span class="o">*</span> <span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">dy</span> <span class="o">=</span> <span class="n">deltaperturb</span> \<span class="o">*</span> <span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">dx</span><span class="p">,</span> <span class="n">y</span><span class="o">+</span><span class="n">dy</span><span class="p">)</span>
|
||
|
||
<span class="n">L</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<img alt="_images/pylammps_mc_disordered.jpg" class="align-center" src="_images/pylammps_mc_disordered.jpg" />
|
||
<p>Finally, the Monte Carlo algorithm is implemented in Python. It continuously
|
||
moves random atoms by a random delta and only accepts certain moves.</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">estart</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"pe"</span><span class="p">)</span>
|
||
<span class="n">elast</span> <span class="o">=</span> <span class="n">estart</span>
|
||
|
||
<span class="n">naccept</span> <span class="o">=</span> <span class="mi">0</span>
|
||
<span class="n">energies</span> <span class="o">=</span> <span class="p">[</span><span class="n">estart</span><span class="p">]</span>
|
||
|
||
<span class="n">niterations</span> <span class="o">=</span> <span class="mi">3000</span>
|
||
<span class="n">deltamove</span> <span class="o">=</span> <span class="mf">0.1</span>
|
||
<span class="n">kT</span> <span class="o">=</span> <span class="mf">0.05</span>
|
||
|
||
<span class="n">natoms</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">system</span><span class="o">.</span><span class="n">natoms</span>
|
||
|
||
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">niterations</span><span class="p">):</span>
|
||
<span class="n">iatom</span> <span class="o">=</span> <span class="n">random</span><span class="o">.</span><span class="n">randrange</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">natoms</span><span class="p">)</span>
|
||
<span class="n">current_atom</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">atoms</span><span class="p">[</span><span class="n">iatom</span><span class="p">]</span>
|
||
|
||
<span class="n">x0</span><span class="p">,</span> <span class="n">y0</span> <span class="o">=</span> <span class="n">current_atom</span><span class="o">.</span><span class="n">position</span>
|
||
|
||
<span class="n">dx</span> <span class="o">=</span> <span class="n">deltamove</span> \<span class="o">*</span> <span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
<span class="n">dy</span> <span class="o">=</span> <span class="n">deltamove</span> \<span class="o">*</span> <span class="n">random</span><span class="o">.</span><span class="n">uniform</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
|
||
|
||
<span class="n">current_atom</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="p">(</span><span class="n">x0</span><span class="o">+</span><span class="n">dx</span><span class="p">,</span> <span class="n">y0</span><span class="o">+</span><span class="n">dy</span><span class="p">)</span>
|
||
|
||
<span class="n">L</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s2">"pre no post no"</span><span class="p">)</span>
|
||
|
||
<span class="n">e</span> <span class="o">=</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"pe"</span><span class="p">)</span>
|
||
<span class="n">energies</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">e</span><span class="p">)</span>
|
||
|
||
<span class="k">if</span> <span class="n">e</span> <span class="o"><=</span> <span class="n">elast</span><span class="p">:</span>
|
||
<span class="n">naccept</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="n">elast</span> <span class="o">=</span> <span class="n">e</span>
|
||
<span class="k">elif</span> <span class="n">random</span><span class="o">.</span><span class="n">random</span><span class="p">()</span> <span class="o"><=</span> <span class="n">math</span><span class="o">.</span><span class="n">exp</span><span class="p">(</span><span class="n">natoms</span>\<span class="o">*</span><span class="p">(</span><span class="n">elast</span><span class="o">-</span><span class="n">e</span><span class="p">)</span><span class="o">/</span><span class="n">kT</span><span class="p">):</span>
|
||
<span class="n">naccept</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="n">elast</span> <span class="o">=</span> <span class="n">e</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="n">current_atom</span><span class="o">.</span><span class="n">position</span> <span class="o">=</span> <span class="p">(</span><span class="n">x0</span><span class="p">,</span> <span class="n">y0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The energies of each iteration are collected in a Python list and finally plotted using matplotlib.</p>
|
||
<img alt="_images/pylammps_mc_energies_plot.jpg" class="align-center" src="_images/pylammps_mc_energies_plot.jpg" />
|
||
<p>The IPython notebook also shows how to use dump commands and embed video files
|
||
inside of the IPython notebook.</p>
|
||
</section>
|
||
</section>
|
||
<section id="using-pylammps-and-mpi4py-experimental">
|
||
<h2><a class="toc-backref" href="#id26" role="doc-backlink">Using PyLammps and mpi4py (Experimental)</a><a class="headerlink" href="#using-pylammps-and-mpi4py-experimental" title="Link to this heading"></a></h2>
|
||
<p>PyLammps can be run in parallel using <a class="reference external" href="https://mpi4py.readthedocs.io">mpi4py</a>. This python package can be installed
|
||
using</p>
|
||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>mpi4py
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p>Usually, any <a class="reference internal" href="Python_module.html#lammps.PyLammps" title="lammps.PyLammps"><code class="xref py py-class docutils literal notranslate"><span class="pre">PyLammps</span></code></a> command must be
|
||
executed by <em>all</em> MPI processes. However, evaluations and querying
|
||
the system state is only available on MPI rank 0. Using these
|
||
functions from other MPI ranks will raise an exception.</p>
|
||
</div>
|
||
<p>The following is a short example which reads in an existing LAMMPS input
|
||
file and executes it in parallel. You can find in.melt in the
|
||
examples/melt folder. Please take note that the
|
||
<a class="reference internal" href="Python_module.html#lammps.PyLammps.eval" title="lammps.PyLammps.eval"><code class="xref py py-meth docutils literal notranslate"><span class="pre">PyLammps.eval()</span></code></a> is called only from
|
||
MPI rank 0.</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="kn">from</span><span class="w"> </span><span class="nn">lammps</span><span class="w"> </span><span class="kn">import</span> <span class="n">PyLammps</span>
|
||
|
||
<span class="n">L</span> <span class="o">=</span> <span class="n">PyLammps</span><span class="p">()</span>
|
||
<span class="n">L</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s2">"in.melt"</span><span class="p">)</span>
|
||
|
||
<span class="k">if</span> <span class="n">MPI</span><span class="o">.</span><span class="n">COMM_WORLD</span><span class="o">.</span><span class="n">rank</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Potential energy: "</span><span class="p">,</span> <span class="n">L</span><span class="o">.</span><span class="n">eval</span><span class="p">(</span><span class="s2">"pe"</span><span class="p">))</span>
|
||
|
||
<span class="n">MPI</span><span class="o">.</span><span class="n">Finalize</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To run this script (melt.py) in parallel using 4 MPI processes we invoke the
|
||
following mpirun command:</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>python<span class="w"> </span>melt.py
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="feedback-and-contributing">
|
||
<h2><a class="toc-backref" href="#id27" role="doc-backlink">Feedback and Contributing</a><a class="headerlink" href="#feedback-and-contributing" title="Link to this heading"></a></h2>
|
||
<p>If you find this Python interface useful, please feel free to provide feedback
|
||
and ideas on how to improve it to Richard Berger (<a class="reference external" href="mailto:richard.berger%40outlook.com">richard<span>.</span>berger<span>@</span>outlook<span>.</span>com</a>). We also
|
||
want to encourage people to write tutorial style IPython notebooks showcasing LAMMPS usage
|
||
and maybe their latest research results.</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||
<a href="Howto_moltemplate.html" class="btn btn-neutral float-left" title="8.6.4. Moltemplate Tutorial" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="Howto_wsl.html" class="btn btn-neutral float-right" title="8.6.6. Using LAMMPS on Windows 10 with WSL" 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> |