diff --git a/doc/Section_python.html b/doc/Section_python.html
index ae9920415..a92472052 100644
--- a/doc/Section_python.html
+++ b/doc/Section_python.html
@@ -1,966 +1,966 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>11. Python interface to LAMMPS — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<link rel="next" title="12. Errors" href="Section_errors.html"/>
<link rel="prev" title="10. Modifying & extending LAMMPS" href="Section_modify.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">11. Python interface to LAMMPS</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#overview-of-running-lammps-from-python">11.1. Overview of running LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#overview-of-using-python-from-a-lammps-script">11.2. Overview of using Python from a LAMMPS script</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-lammps-as-a-shared-library">11.3. Building LAMMPS as a shared library</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installing-the-python-wrapper-into-python">11.4. Installing the Python wrapper into Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#extending-python-with-mpi-to-run-in-parallel">11.5. Extending Python with MPI to run in parallel</a></li>
<li class="toctree-l2"><a class="reference internal" href="#testing-the-python-lammps-interface">11.6. Testing the Python-LAMMPS interface</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#test-lammps-and-python-in-serial">11.6.1. <strong>Test LAMMPS and Python in serial:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#test-lammps-and-python-in-parallel">11.6.2. <strong>Test LAMMPS and Python in parallel:</strong></a></li>
<li class="toctree-l3"><a class="reference internal" href="#running-python-scripts">11.6.3. <strong>Running Python scripts:</strong></a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#using-lammps-from-python">11.7. Using LAMMPS from Python</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-python-scripts-that-use-lammps">11.8. Example Python scripts that use LAMMPS</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>11. Python interface to LAMMPS</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="python-interface-to-lammps">
<h1>11. Python interface to LAMMPS<a class="headerlink" href="#python-interface-to-lammps" title="Permalink to this headline">¶</a></h1>
<p>LAMMPS can work together with Python in two ways. First, Python can
wrap LAMMPS through the <a class="reference internal" href="Section_howto.html#howto-19"><span>LAMMPS library interface</span></a>, so that a Python script can
create one or more instances of LAMMPS and launch one or more
simulations. In Python lingo, this is “extending” Python with LAMMPS.</p>
<p>Second, LAMMPS can use the Python interpreter, so that a LAMMPS input
script can invoke Python code, and pass information back-and-forth
between the input script and Python functions you write. The Python
code can also callback to LAMMPS to query or change its attributes.
In Python lingo, this is “embedding” Python in LAMMPS.</p>
<p>This section describes how to do both.</p>
<ul class="simple">
<li>11.1 <a class="reference internal" href="#py-1"><span>Overview of running LAMMPS from Python</span></a></li>
<li>11.2 <a class="reference internal" href="#py-2"><span>Overview of using Python from a LAMMPS script</span></a></li>
<li>11.3 <a class="reference internal" href="#py-3"><span>Building LAMMPS as a shared library</span></a></li>
<li>11.4 <a class="reference internal" href="#py-4"><span>Installing the Python wrapper into Python</span></a></li>
<li>11.5 <a class="reference internal" href="#py-5"><span>Extending Python with MPI to run in parallel</span></a></li>
<li>11.6 <a class="reference internal" href="#py-6"><span>Testing the Python-LAMMPS interface</span></a></li>
<li>11.7 <a class="reference internal" href="#py-7"><span>Using LAMMPS from Python</span></a></li>
<li>11.8 <a class="reference internal" href="#py-8"><span>Example Python scripts that use LAMMPS</span></a></li>
</ul>
<p>If you are not familiar with it, <a class="reference external" href="http://www.python.org">Python</a> is a
powerful scripting and programming language which can essentially do
anything that faster, lower-level languages like C or C++ can do, but
typically with much fewer lines of code. When used in embedded mode,
Python can perform operations that the simplistic LAMMPS input script
syntax cannot. Python can be also be used as a “glue” language to
drive a program through its library interface, or to hook multiple
pieces of software together, such as a simulation package plus a
visualization package, or to run a coupled multiscale or multiphysics
model.</p>
<p>See <a class="reference internal" href="Section_howto.html#howto-10"><span>Section_howto 10</span></a> of the manual and
the couple directory of the distribution for more ideas about coupling
LAMMPS to other codes. See <a class="reference internal" href="Section_howto.html#howto-19"><span>Section_howto 19</span></a> for a description of the LAMMPS
library interface provided in src/library.cpp and src/library.h, and
how to extend it for your needs. As described below, that interface
is what is exposed to Python either when calling LAMMPS from Python or
when calling Python from a LAMMPS input script and then calling back
to LAMMPS from Python code. The library interface is designed to be
easy to add functions to. Thus the Python interface to LAMMPS is also
easy to extend as well.</p>
<p>If you create interesting Python scripts that run LAMMPS or
interesting Python functions that can be called from a LAMMPS input
script, that you think would be useful to other users, please <a class="reference external" href="http://lammps.sandia.gov/authors.html">email them to the developers</a>. We can
include them in the LAMMPS distribution.</p>
<div class="section" id="overview-of-running-lammps-from-python">
<span id="py-1"></span><h2>11.1. Overview of running LAMMPS from Python<a class="headerlink" href="#overview-of-running-lammps-from-python" title="Permalink to this headline">¶</a></h2>
<p>The LAMMPS distribution includes a python directory with all you need
to run LAMMPS from Python. The python/lammps.py file wraps the LAMMPS
library interface, with one wrapper function per LAMMPS library
function. This file makes it is possible to do the following either
from a Python script, or interactively from a Python prompt: create
one or more instances of LAMMPS, invoke LAMMPS commands or give it an
input script, run LAMMPS incrementally, extract LAMMPS results, an
modify internal LAMMPS variables. From a Python script you can do
this in serial or parallel. Running Python interactively in parallel
does not generally work, unless you have a version of Python that
extends standard Python to enable multiple instances of Python to read
what you type.</p>
<p>To do all of this, you must first build LAMMPS as a shared library,
then insure that your Python can find the python/lammps.py file and
the shared library. These steps are explained in subsequent sections
11.3 and 11.4. Sections 11.5 and 11.6 discuss using MPI from a
parallel Python program and how to test that you are ready to use
LAMMPS from Python. Section 11.7 lists all the functions in the
current LAMMPS library interface and how to call them from Python.</p>
<p>Section 11.8 gives some examples of coupling LAMMPS to other tools via
Python. For example, LAMMPS can easily be coupled to a GUI or other
visualization tools that display graphs or animations in real time as
LAMMPS runs. Examples of such scripts are inlcluded in the python
directory.</p>
<p>Two advantages of using Python to run LAMMPS are how concise the
language is, and that it can be run interactively, enabling rapid
development and debugging of programs. If you use it to mostly invoke
costly operations within LAMMPS, such as running a simulation for a
reasonable number of timesteps, then the overhead cost of invoking
LAMMPS thru Python will be negligible.</p>
<p>The Python wrapper for LAMMPS uses the amazing and magical (to me)
“ctypes” package in Python, which auto-generates the interface code
needed between Python and a set of C interface routines for a library.
Ctypes is part of standard Python for versions 2.5 and later. You can
check which version of Python you have installed, by simply typing
“python” at a shell prompt.</p>
<hr class="docutils" />
</div>
<div class="section" id="overview-of-using-python-from-a-lammps-script">
<span id="py-2"></span><h2>11.2. Overview of using Python from a LAMMPS script<a class="headerlink" href="#overview-of-using-python-from-a-lammps-script" title="Permalink to this headline">¶</a></h2>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">It is not currently possible to use the
<a class="reference internal" href="python.html"><em>python</em></a> command described in this section with Python 3,
only with Python 2. The C API changed from Python 2 to 3 and the
LAMMPS code is not compatible with both.</p>
</div>
<p>LAMMPS has a <a class="reference internal" href="python.html"><em>python</em></a> command which can be used in an
input script to define and execute a Python function that you write
the code for. The Python function can also be assigned to a LAMMPS
python-style variable via the <a class="reference internal" href="variable.html"><em>variable</em></a> command. Each
time the variable is evaluated, either in the LAMMPS input script
itself, or by another LAMMPS command that uses the variable, this will
trigger the Python function to be invoked.</p>
<p>The Python code for the function can be included directly in the input
script or in an auxiliary file. The function can have arguments which
are mapped to LAMMPS variables (also defined in the input script) and
it can return a value to a LAMMPS variable. This is thus a mechanism
for your input script to pass information to a piece of Python code,
ask Python to execute the code, and return information to your input
script.</p>
<p>Note that a Python function can be arbitrarily complex. It can import
other Python modules, instantiate Python classes, call other Python
functions, etc. The Python code that you provide can contain more
code than the single function. It can contain other functions or
Python classes, as well as global variables or other mechanisms for
storing state between calls from LAMMPS to the function.</p>
<p>The Python function you provide can consist of “pure” Python code that
only performs operations provided by standard Python. However, the
Python function can also “call back” to LAMMPS through its
Python-wrapped library interface, in the manner described in the
previous section 11.1. This means it can issue LAMMPS input script
commands or query and set internal LAMMPS state. As an example, this
can be useful in an input script to create a more complex loop with
branching logic, than can be created using the simple looping and
brancing logic enabled by the <a class="reference internal" href="next.html"><em>next</em></a> and <a class="reference internal" href="if.html"><em>if</em></a>
commands.</p>
<p>See the <a class="reference internal" href="python.html"><em>python</em></a> doc page and the <a class="reference internal" href="variable.html"><em>variable</em></a>
doc page for its python-style variables for more info, including
examples of Python code you can write for both pure Python operations
and callbacks to LAMMPS.</p>
<p>To run pure Python code from LAMMPS, you only need to build LAMMPS
with the PYTHON package installed:</p>
<p>make yes-python
make machine</p>
<p>Note that this will link LAMMPS with the Python library on your
system, which typically requires several auxiliary system libraries to
also be linked. The list of these libraries and the paths to find
them are specified in the lib/python/Makefile.lammps file. You need
to insure that file contains the correct information for your version
of Python and your machine to successfully build LAMMPS. See the
lib/python/README file for more info.</p>
<p>If you want to write Python code with callbacks to LAMMPS, then you
must also follow the steps overviewed in the preceeding section (11.1)
for running LAMMPS from Python. I.e. you must build LAMMPS as a
shared library and insure that Python can find the python/lammps.py
file and the shared library.</p>
<hr class="docutils" />
</div>
<div class="section" id="building-lammps-as-a-shared-library">
<span id="py-3"></span><h2>11.3. Building LAMMPS as a shared library<a class="headerlink" href="#building-lammps-as-a-shared-library" title="Permalink to this headline">¶</a></h2>
<p>Instructions on how to build LAMMPS as a shared library are given in
<a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a>. A shared library is one
that is dynamically loadable, which is what Python requires to wrap
LAMMPS. On Linux this is a library file that ends in ”.so”, not ”.a”.</p>
<p>>From the src directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>make foo mode=shlib
</pre></div>
</div>
<p>where foo is the machine target name, such as linux or g++ or serial.
This should create the file liblammps_foo.so in the src directory, as
well as a soft link liblammps.so, which is what the Python wrapper will
load by default. Note that if you are building multiple machine
versions of the shared library, the soft link is always set to the
most recently built version.</p>
<p>If this fails, see <a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a> for
more details, especially if your LAMMPS build uses auxiliary libraries
like MPI or FFTW which may not be built as shared libraries on your
system.</p>
<hr class="docutils" />
</div>
<div class="section" id="installing-the-python-wrapper-into-python">
<span id="py-4"></span><h2>11.4. Installing the Python wrapper into Python<a class="headerlink" href="#installing-the-python-wrapper-into-python" title="Permalink to this headline">¶</a></h2>
<p>For Python to invoke LAMMPS, there are 2 files it needs to know about:</p>
<ul class="simple">
<li>python/lammps.py</li>
<li>src/liblammps.so</li>
</ul>
<p>Lammps.py is the Python wrapper on the LAMMPS library interface.
Liblammps.so is the shared LAMMPS library that Python loads, as
described above.</p>
<p>You can insure Python can find these files in one of two ways:</p>
<ul class="simple">
<li>set two environment variables</li>
<li>run the python/install.py script</li>
</ul>
<p>If you set the paths to these files as environment variables, you only
have to do it once. For the csh or tcsh shells, add something like
this to your ~/.cshrc file, one line for each of the two files:</p>
<div class="highlight-python"><div class="highlight"><pre>setenv PYTHONPATH $*PYTHONPATH*:/home/sjplimp/lammps/python
setenv LD_LIBRARY_PATH $*LD_LIBRARY_PATH*:/home/sjplimp/lammps/src
</pre></div>
</div>
<p>If you use the python/install.py script, you need to invoke it every
time you rebuild LAMMPS (as a shared library) or make changes to the
python/lammps.py file.</p>
<p>You can invoke install.py from the python directory as</p>
<div class="highlight-python"><div class="highlight"><pre>% python install.py [libdir] [pydir]
</pre></div>
</div>
<p>The optional libdir is where to copy the LAMMPS shared library to; the
default is /usr/local/lib. The optional pydir is where to copy the
lammps.py file to; the default is the site-packages directory of the
version of Python that is running the install script.</p>
<p>Note that libdir must be a location that is in your default
LD_LIBRARY_PATH, like /usr/local/lib or /usr/lib. And pydir must be a
location that Python looks in by default for imported modules, like
its site-packages dir. If you want to copy these files to
non-standard locations, such as within your own user space, you will
need to set your PYTHONPATH and LD_LIBRARY_PATH environment variables
accordingly, as above.</p>
<p>If the install.py script does not allow you to copy files into system
directories, prefix the python command with “sudo”. If you do this,
make sure that the Python that root runs is the same as the Python you
run. E.g. you may need to do something like</p>
<div class="highlight-python"><div class="highlight"><pre>% sudo /usr/local/bin/python install.py [libdir] [pydir]
</pre></div>
</div>
<p>You can also invoke install.py from the make command in the src
directory as</p>
<div class="highlight-python"><div class="highlight"><pre>% make install-python
</pre></div>
</div>
<p>In this mode you cannot append optional arguments. Again, you may
need to prefix this with “sudo”. In this mode you cannot control
which Python is invoked by root.</p>
<p>Note that if you want Python to be able to load different versions of
the LAMMPS shared library (see <a class="reference internal" href="#py-5"><span>this section</span></a> below), you will
need to manually copy files like liblammps_g++.so into the appropriate
system directory. This is not needed if you set the LD_LIBRARY_PATH
environment variable as described above.</p>
<hr class="docutils" />
</div>
<div class="section" id="extending-python-with-mpi-to-run-in-parallel">
<span id="py-5"></span><h2>11.5. Extending Python with MPI to run in parallel<a class="headerlink" href="#extending-python-with-mpi-to-run-in-parallel" title="Permalink to this headline">¶</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>There are several Python packages available that purport to wrap MPI
as a library and allow MPI functions to be called from Python.</p>
<p>These include</p>
<ul class="simple">
<li><a class="reference external" href="http://pympi.sourceforge.net/">pyMPI</a></li>
<li><a class="reference external" href="http://code.google.com/p/maroonmpi/">maroonmpi</a></li>
<li><a class="reference external" href="http://code.google.com/p/mpi4py/">mpi4py</a></li>
<li><a class="reference external" href="http://nbcr.sdsc.edu/forum/viewtopic.php?t=89&sid=c997fefc3933bd66204875b436940f16">myMPI</a></li>
<li><a class="reference external" href="http://code.google.com/p/pypar">Pypar</a></li>
</ul>
<p>All of these except pyMPI work by wrapping the MPI library and
exposing (some portion of) its interface to your Python script. This
means Python cannot be used interactively in parallel, since they do
not address the issue of interactive input to multiple instances of
Python running on different processors. The one exception is pyMPI,
which alters the Python interpreter to address this issue, and (I
believe) creates a new alternate executable (in place of “python”
itself) as a result.</p>
<p>In principle any of these Python/MPI packages should work to invoke
LAMMPS in parallel and to make MPI calls themselves from a Python
script which is itself running in parallel. However, when I
downloaded and looked at a few of them, their documentation was
incomplete and I had trouble with their installation. It’s not clear
if some of the packages are still being actively developed and
supported.</p>
<p>The one I recommend, since I have successfully used it with LAMMPS, is
Pypar. Pypar requires the ubiquitous <a class="reference external" href="http://numpy.scipy.org">Numpy package</a> be installed in your Python. After
launching python, type</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span>
</pre></div>
</div>
<p>to see if it is installed. If not, here is how to install it (version
1.3.0b1 as of April 2009). Unpack the numpy tarball and from its
top-level directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py build
sudo python setup.py install
</pre></div>
</div>
<p>The “sudo” is only needed if required to copy Numpy files into your
Python distribution’s site-packages directory.</p>
<p>To install Pypar (version pypar-2.1.4_94 as of Aug 2012), unpack it
and from its “source” directory, type</p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py build
sudo python setup.py install
</pre></div>
</div>
<p>Again, the “sudo” is only needed if required to copy Pypar files into
your Python distribution’s site-packages directory.</p>
<p>If you have successully installed Pypar, you should be able to run
Python and type</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pypar</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-python"><div class="highlight"><pre>% mpirun -np 4 python test.py
</pre></div>
</div>
<p>where test.py contains the lines</p>
<div class="highlight-python"><div class="highlight"><pre>import pypar
print "Proc %d out of %d procs" % (pypar.rank(),pypar.size())
</pre></div>
</div>
<p>and see one line of output for each processor you run on.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">To use Pypar and LAMMPS in parallel from Python, you
must insure both are using the same version of MPI. If you only have
one MPI installed on your system, this is not an issue, but it can be
if you have multiple MPIs. Your LAMMPS build is explicit about which
MPI it is using, since you specify the details in your lo-level
src/MAKE/Makefile.foo file. Pypar uses the “mpicc” command to find
information about the MPI it uses to build against. And it tries to
load “libmpi.so” from the LD_LIBRARY_PATH. This may or may not find
the MPI library that LAMMPS is using. If you have problems running
both Pypar and LAMMPS together, this is an issue you may need to
address, e.g. by moving other MPI installations so that Pypar finds
the right one.</p>
</div>
<hr class="docutils" />
</div>
<div class="section" id="testing-the-python-lammps-interface">
<span id="py-6"></span><h2>11.6. Testing the Python-LAMMPS interface<a class="headerlink" href="#testing-the-python-lammps-interface" title="Permalink to this headline">¶</a></h2>
<p>To test if LAMMPS is callable from Python, launch Python interactively
and type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lammps</span> <span class="kn">import</span> <span class="n">lammps</span>
<span class="gp">>>> </span><span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
</pre></div>
</div>
<p>If you get no errors, you’re ready to use LAMMPS from Python. If the
2nd command fails, the most common error to see is</p>
<div class="highlight-python"><div class="highlight"><pre>OSError: Could not load LAMMPS dynamic library
</pre></div>
</div>
<p>which means Python was unable to load the LAMMPS shared library. This
typically occurs if the system can’t find the LAMMPS shared library or
one of the auxiliary shared libraries it depends on, or if something
about the library is incompatible with your Python. The error message
should give you an indication of what went wrong.</p>
<p>You can also test the load directly in Python as follows, without
first importing from the lammps.py file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">ctypes</span> <span class="kn">import</span> <span class="n">CDLL</span>
<span class="gp">>>> </span><span class="n">CDLL</span><span class="p">(</span><span class="s">"liblammps.so"</span><span class="p">)</span>
</pre></div>
</div>
<p>If an error occurs, carefully go thru the steps in <a class="reference internal" href="Section_start.html#start-5"><span>Section_start 5</span></a> and above about building a shared
library and about insuring Python can find the necessary two files
it needs.</p>
<div class="section" id="test-lammps-and-python-in-serial">
<h3>11.6.1. <strong>Test LAMMPS and Python in serial:</strong><a class="headerlink" href="#test-lammps-and-python-in-serial" title="Permalink to this headline">¶</a></h3>
<p>To run a LAMMPS test in serial, type these lines into Python
interactively from the bench directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lammps</span> <span class="kn">import</span> <span class="n">lammps</span>
<span class="gp">>>> </span><span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">lmp</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s">"in.lj"</span><span class="p">)</span>
</pre></div>
</div>
<p>Or put the same lines in the file test.py and run it as</p>
<div class="highlight-python"><div class="highlight"><pre>% python test.py
</pre></div>
</div>
<p>Either way, you should see the results of running the in.lj benchmark
on a single processor appear on the screen, the same as if you had
typed something like:</p>
<div class="highlight-python"><div class="highlight"><pre>lmp_g++ < in.lj
</pre></div>
</div>
</div>
<div class="section" id="test-lammps-and-python-in-parallel">
<h3>11.6.2. <strong>Test LAMMPS and Python in parallel:</strong><a class="headerlink" href="#test-lammps-and-python-in-parallel" title="Permalink to this headline">¶</a></h3>
<p>To run LAMMPS in parallel, assuming you have installed the
<a class="reference external" href="http://datamining.anu.edu.au/~ole/pypar">Pypar</a> package as discussed
above, create a test.py file containing these lines:</p>
<div class="highlight-python"><div class="highlight"><pre>import pypar
from lammps import lammps
lmp = lammps()
lmp.file("in.lj")
print "Proc %d out of %d procs has" % (pypar.rank(),pypar.size()),lmp
pypar.finalize()
</pre></div>
</div>
<p>You can then run it in parallel as:</p>
<div class="highlight-python"><div class="highlight"><pre>% mpirun -np 4 python test.py
</pre></div>
</div>
<p>and you should see the same output as if you had typed</p>
<div class="highlight-python"><div class="highlight"><pre>% mpirun -np 4 lmp_g++ < in.lj
</pre></div>
</div>
<p>Note that if you leave out the 3 lines from test.py that specify Pypar
commands you will instantiate and run LAMMPS independently on each of
the P processors specified in the mpirun command. In this case you
should get 4 sets of output, each showing that a LAMMPS run was made
on a single processor, instead of one set of output showing that
LAMMPS ran on 4 processors. If the 1-processor outputs occur, it
means that Pypar is not working correctly.</p>
<p>Also note that once you import the PyPar module, Pypar initializes MPI
for you, and you can use MPI calls directly in your Python script, as
described in the Pypar documentation. The last line of your Python
script should be pypar.finalize(), to insure MPI is shut down
correctly.</p>
</div>
<div class="section" id="running-python-scripts">
<h3>11.6.3. <strong>Running Python scripts:</strong><a class="headerlink" href="#running-python-scripts" title="Permalink to this headline">¶</a></h3>
<p>Note that any Python script (not just for LAMMPS) can be invoked in
one of several ways:</p>
<div class="highlight-python"><div class="highlight"><pre>% python foo.script
% python -i foo.script
% foo.script
</pre></div>
</div>
<p>The last command requires that the first line of the script be
something like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/local/bin/python</span>
<span class="c">#!/usr/local/bin/python -i</span>
</pre></div>
</div>
<p>where the path points to where you have Python installed, and that you
have made the script file executable:</p>
<div class="highlight-python"><div class="highlight"><pre>% chmod +x foo.script
</pre></div>
</div>
<p>Without the “-i” flag, Python will exit when the script finishes.
With the “-i” flag, you will be left in the Python interpreter when
the script finishes, so you can type subsequent commands. As
mentioned above, you can only run Python interactively when running
Python on a single processor, not in parallel.</p>
</div>
</div>
<div class="section" id="using-lammps-from-python">
<span id="py-7"></span><h2>11.7. Using LAMMPS from Python<a class="headerlink" href="#using-lammps-from-python" title="Permalink to this headline">¶</a></h2>
<p>As described above, the Python interface to LAMMPS consists of a
Python “lammps” module, the source code for which is in
python/lammps.py, which creates a “lammps” object, with a set of
methods that can be invoked on that object. The sample Python code
below assumes you have first imported the “lammps” module in your
Python script, as follows:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">lammps</span> <span class="kn">import</span> <span class="n">lammps</span>
</pre></div>
</div>
<p>These are the methods defined by the lammps module. If you look at
the files src/library.cpp and src/library.h you will see that they
correspond one-to-one with calls you can make to the LAMMPS library
from a C++ or C or Fortran program.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span> <span class="c"># create a LAMMPS object using the default liblammps.so library</span>
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">(</span><span class="n">ptr</span><span class="o">=</span><span class="n">lmpptr</span><span class="p">)</span> <span class="c"># ditto, but use lmpptr as previously created LAMMPS object</span>
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">(</span><span class="s">"g++"</span><span class="p">)</span> <span class="c"># create a LAMMPS object using the liblammps_g++.so library</span>
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">(</span><span class="s">""</span><span class="p">,</span><span class="nb">list</span><span class="p">)</span> <span class="c"># ditto, with command-line args, e.g. list = ["-echo","screen"]</span>
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">(</span><span class="s">"g++"</span><span class="p">,</span><span class="nb">list</span><span class="p">)</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lmp</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="c"># destroy a LAMMPS object</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lmp</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="nb">file</span><span class="p">)</span> <span class="c"># run an entire input script, file = "in.lj"</span>
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="n">cmd</span><span class="p">)</span> <span class="c"># invoke a single LAMMPS command, cmd = "run 100"</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">xlo</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">extract_global</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span> <span class="c"># extract a global quantity</span>
<span class="c"># name = "boxxlo", "nlocal", etc</span>
<span class="c"># type = 0 = int</span>
<span class="c"># 1 = double</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">coords</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">extract_atom</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span> <span class="c"># extract a per-atom quantity</span>
<span class="c"># name = "x", "type", etc</span>
<span class="c"># type = 0 = vector of ints</span>
<span class="c"># 1 = array of ints</span>
<span class="c"># 2 = vector of doubles</span>
<span class="c"># 3 = array of doubles</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">eng</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">extract_compute</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span><span class="n">style</span><span class="p">,</span><span class="nb">type</span><span class="p">)</span> <span class="c"># extract value(s) from a compute</span>
<span class="n">v3</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">extract_fix</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span><span class="n">style</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">i</span><span class="p">,</span><span class="n">j</span><span class="p">)</span> <span class="c"># extract value(s) from a fix</span>
<span class="c"># id = ID of compute or fix</span>
<span class="c"># style = 0 = global data</span>
<span class="c"># 1 = per-atom data</span>
<span class="c"># 2 = local data</span>
<span class="c"># type = 0 = scalar</span>
<span class="c"># 1 = vector</span>
<span class="c"># 2 = array</span>
<span class="c"># i,j = indices of value in global vector or array</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">var</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">extract_variable</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="n">group</span><span class="p">,</span><span class="n">flag</span><span class="p">)</span> <span class="c"># extract value(s) from a variable</span>
<span class="c"># name = name of variable</span>
<span class="c"># group = group ID (ignored for equal-style variables)</span>
<span class="c"># flag = 0 = equal-style variable</span>
<span class="c"># 1 = atom-style variable</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="n">flag</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">set_variable</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="n">value</span><span class="p">)</span> <span class="c"># set existing named string-style variable to value, flag = 0 if successful</span>
<span class="n">natoms</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">get_natoms</span><span class="p">()</span> <span class="c"># total # of atoms as int</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">lmp</span><span class="o">.</span><span class="n">gather_atoms</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">count</span><span class="p">)</span> <span class="c"># return atom attribute of all atoms gathered into data, ordered by atom ID</span>
<span class="c"># name = "x", "charge", "type", etc</span>
<span class="c"># count = # of per-atom values, 1 or 3, etc</span>
<span class="n">lmp</span><span class="o">.</span><span class="n">scatter_atoms</span><span class="p">(</span><span class="n">name</span><span class="p">,</span><span class="nb">type</span><span class="p">,</span><span class="n">count</span><span class="p">,</span><span class="n">data</span><span class="p">)</span> <span class="c"># scatter atom attribute of all atoms from data, ordered by atom ID</span>
<span class="c"># name = "x", "charge", "type", etc</span>
<span class="c"># count = # of per-atom values, 1 or 3, etc</span>
</pre></div>
</div>
<hr class="docutils" />
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Currently, the creation of a LAMMPS object from within
lammps.py does not take an MPI communicator as an argument. There
should be a way to do this, so that the LAMMPS instance runs on a
subset of processors if desired, but I don’t know how to do it from
Pypar. So for now, it runs with MPI_COMM_WORLD, which is all the
processors. If someone figures out how to do this with one or more of
the Python wrappers for MPI, like Pypar, please let us know and we
will amend these doc pages.</p>
</div>
<p>The lines</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">lammps</span> <span class="kn">import</span> <span class="n">lammps</span>
<span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
</pre></div>
</div>
<p>create an instance of LAMMPS, wrapped in a Python class by the lammps
Python module, and return an instance of the Python class as lmp. It
is used to make all subequent calls to the LAMMPS library.</p>
<p>Additional arguments can be used to tell Python the name of the shared
library to load or to pass arguments to the LAMMPS instance, the same
as if LAMMPS were launched from a command-line prompt.</p>
<p>If the ptr argument is set like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">lmp</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">(</span><span class="n">ptr</span><span class="o">=</span><span class="n">lmpptr</span><span class="p">)</span>
</pre></div>
</div>
<p>then lmpptr must be an argument passed to Python via the LAMMPS
<a class="reference internal" href="python.html"><em>python</em></a> command, when it is used to define a Python
function that is invoked by the LAMMPS input script. This mode of
using Python with LAMMPS is described above in 11.2. The variable
lmpptr refers to the instance of LAMMPS that called the embedded
Python interpreter. Using it as an argument to lammps() allows the
returned Python class instance “lmp” to make calls to that instance of
LAMMPS. See the <a class="reference internal" href="python.html"><em>python</em></a> command doc page for examples
using this syntax.</p>
<p>Note that you can create multiple LAMMPS objects in your Python
script, and coordinate and run multiple simulations, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">lammps</span> <span class="kn">import</span> <span class="n">lammps</span>
<span class="n">lmp1</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
<span class="n">lmp2</span> <span class="o">=</span> <span class="n">lammps</span><span class="p">()</span>
<span class="n">lmp1</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s">"in.file1"</span><span class="p">)</span>
<span class="n">lmp2</span><span class="o">.</span><span class="n">file</span><span class="p">(</span><span class="s">"in.file2"</span><span class="p">)</span>
</pre></div>
</div>
<p>The file() and command() methods allow an input script or single
commands to be invoked.</p>
<p>The extract_global(), extract_atom(), extract_compute(),
extract_fix(), and extract_variable() methods return values or
pointers to data structures internal to LAMMPS.</p>
<p>For extract_global() see the src/library.cpp file for the list of
valid names. New names could easily be added. A double or integer is
returned. You need to specify the appropriate data type via the type
argument.</p>
<p>For extract_atom(), a pointer to internal LAMMPS atom-based data is
returned, which you can use via normal Python subscripting. See the
extract() method in the src/atom.cpp file for a list of valid names.
Again, new names could easily be added. A pointer to a vector of
doubles or integers, or a pointer to an array of doubles (double <a href="#id2"><span class="problematic" id="id3">**</span></a>)
or integers (int <a href="#id4"><span class="problematic" id="id5">**</span></a>) is returned. You need to specify the appropriate
data type via the type argument.</p>
<p>For extract_compute() and extract_fix(), the global, per-atom, or
local data calulated by the compute or fix can be accessed. What is
returned depends on whether the compute or fix calculates a scalar or
vector or array. For a scalar, a single double value is returned. If
the compute or fix calculates a vector or array, a pointer to the
internal LAMMPS data is returned, which you can use via normal Python
subscripting. The one exception is that for a fix that calculates a
global vector or array, a single double value from the vector or array
is returned, indexed by I (vector) or I and J (array). I,J are
zero-based indices. The I,J arguments can be left out if not needed.
See <a class="reference internal" href="Section_howto.html#howto-15"><span>Section_howto 15</span></a> of the manual for a
discussion of global, per-atom, and local data, and of scalar, vector,
and array data types. See the doc pages for individual
<a class="reference internal" href="compute.html"><em>computes</em></a> and <a class="reference internal" href="fix.html"><em>fixes</em></a> for a description of what
they calculate and store.</p>
<p>For extract_variable(), an <a class="reference internal" href="variable.html"><em>equal-style or atom-style variable</em></a> is evaluated and its result returned.</p>
<p>For equal-style variables a single double value is returned and the
group argument is ignored. For atom-style variables, a vector of
doubles is returned, one value per atom, which you can use via normal
Python subscripting. The values will be zero for atoms not in the
specified group.</p>
<p>The get_natoms() method returns the total number of atoms in the
simulation, as an int.</p>
<p>The gather_atoms() method returns a ctypes vector of ints or doubles
as specified by type, of length count*natoms, for the property of all
the atoms in the simulation specified by name, ordered by count and
then by atom ID. The vector can be used via normal Python
subscripting. If atom IDs are not consecutively ordered within
LAMMPS, a None is returned as indication of an error.</p>
<p>Note that the data structure gather_atoms(“x”) returns is different
from the data structure returned by extract_atom(“x”) in four ways.
(1) Gather_atoms() returns a vector which you index as x[i];
extract_atom() returns an array which you index as x[i][j]. (2)
Gather_atoms() orders the atoms by atom ID while extract_atom() does
not. (3) Gathert_atoms() returns a list of all atoms in the
simulation; extract_atoms() returns just the atoms local to each
processor. (4) Finally, the gather_atoms() data structure is a copy
of the atom coords stored internally in LAMMPS, whereas extract_atom()
returns an array that effectively points directly to the internal
data. This means you can change values inside LAMMPS from Python by
assigning a new values to the extract_atom() array. To do this with
the gather_atoms() vector, you need to change values in the vector,
then invoke the scatter_atoms() method.</p>
<p>The scatter_atoms() method takes a vector of ints or doubles as
specified by type, of length count*natoms, for the property of all the
atoms in the simulation specified by name, ordered by bount and then
by atom ID. It uses the vector of data to overwrite the corresponding
properties for each atom inside LAMMPS. This requires LAMMPS to have
its “map” option enabled; see the <a class="reference internal" href="atom_modify.html"><em>atom_modify</em></a>
command for details. If it is not, or if atom IDs are not
consecutively ordered, no coordinates are reset.</p>
<p>The array of coordinates passed to scatter_atoms() must be a ctypes
vector of ints or doubles, allocated and initialized something like
this:</p>
<div class="highlight-python"><div class="highlight"><pre>from ctypes import *
natoms = lmp.get_natoms()
n3 = 3*natoms
x = (n3*c_double)()
x[0] = x coord of atom with ID 1
x[1] = y coord of atom with ID 1
x[2] = z coord of atom with ID 1
x[3] = x coord of atom with ID 2
...
x[n3-1] = z coord of atom with ID natoms
lmp.scatter_coords("x",1,3,x)
</pre></div>
</div>
<p>Alternatively, you can just change values in the vector returned by
gather_atoms(“x”,1,3), since it is a ctypes vector of doubles.</p>
<hr class="docutils" />
<p>As noted above, these Python class methods correspond one-to-one with
the functions in the LAMMPS library interface in src/library.cpp and
library.h. This means you can extend the Python wrapper via the
following steps:</p>
<ul class="simple">
<li>Add a new interface function to src/library.cpp and
src/library.h.</li>
<li>Rebuild LAMMPS as a shared library.</li>
<li>Add a wrapper method to python/lammps.py for this interface
function.</li>
<li>You should now be able to invoke the new interface function from a
Python script. Isn’t ctypes amazing?</li>
</ul>
</div>
<div class="section" id="example-python-scripts-that-use-lammps">
<span id="py-8"></span><h2>11.8. Example Python scripts that use LAMMPS<a class="headerlink" href="#example-python-scripts-that-use-lammps" title="Permalink to this headline">¶</a></h2>
<p>These are the Python scripts included as demos in the python/examples
directory of the LAMMPS distribution, to illustrate the kinds of
things that are possible when Python wraps LAMMPS. If you create your
own scripts, send them to us and we can include them in the LAMMPS
distribution.</p>
<table border="1" class="docutils">
<colgroup>
<col width="27%" />
<col width="73%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>trivial.py</td>
<td>read/run a LAMMPS input script thru Python</td>
</tr>
<tr class="row-even"><td>demo.py</td>
<td>invoke various LAMMPS library interface routines</td>
</tr>
<tr class="row-odd"><td>simple.py</td>
<td>mimic operation of couple/simple/simple.cpp in Python</td>
</tr>
<tr class="row-even"><td>gui.py</td>
<td>GUI go/stop/temperature-slider to control LAMMPS</td>
</tr>
<tr class="row-odd"><td>plot.py</td>
<td>real-time temeperature plot with GnuPlot via Pizza.py</td>
</tr>
<tr class="row-even"><td>viz_tool.py</td>
<td>real-time viz via some viz package</td>
</tr>
<tr class="row-odd"><td>vizplotgui_tool.py</td>
<td>combination of viz_tool.py and plot.py and gui.py</td>
</tr>
</tbody>
</table>
<hr class="docutils" />
<p>For the viz_tool.py and vizplotgui_tool.py commands, replace “tool”
with “gl” or “atomeye” or “pymol” or “vmd”, depending on what
visualization package you have installed.</p>
<p>Note that for GL, you need to be able to run the Pizza.py GL tool,
which is included in the pizza sub-directory. See the <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py doc pages</a> for more info:</p>
<p>Note that for AtomEye, you need version 3, and there is a line in the
scripts that specifies the path and name of the executable. See the
AtomEye WWW pages <a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A">here</a> or <a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html">here</a> for more details:</p>
<div class="highlight-python"><div class="highlight"><pre>http://mt.seas.upenn.edu/Archive/Graphics/A
http://mt.seas.upenn.edu/Archive/Graphics/A3/A3.html
</pre></div>
</div>
<p>The latter link is to AtomEye 3 which has the scriping
capability needed by these Python scripts.</p>
<p>Note that for PyMol, you need to have built and installed the
open-source version of PyMol in your Python, so that you can import it
from a Python script. See the PyMol WWW pages <a class="reference external" href="http://www.pymol.org">here</a> or
<a class="reference external" href="http://sourceforge.net/scm/?type=svn&group_id=4546">here</a> for more details:</p>
<div class="highlight-python"><div class="highlight"><pre>http://www.pymol.org
http://sourceforge.net/scm/?type=svn&group_id=4546
</pre></div>
</div>
<p>The latter link is to the open-source version.</p>
<p>Note that for VMD, you need a fairly current version (1.8.7 works for
me) and there are some lines in the pizza/vmd.py script for 4 PIZZA
variables that have to match the VMD installation on your system.</p>
<hr class="docutils" />
<p>See the python/README file for instructions on how to run them and the
source code for individual scripts for comments about what they do.</p>
<p>Here are screenshots of the vizplotgui_tool.py script in action for
different visualization package options. Click to see larger images:</p>
-<a data-lightbox="group-abad215d-0434-41e2-bc11-9f41aac64349"
+<a data-lightbox="group-471f42f4-09a2-4ede-a20b-a936fac66d51"
href="_images/screenshot_gl.jpg"
class=""
title=""
data-title=""
><img src="_images/screenshot_gl.jpg"
class=""
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-0060607e-2e72-4d15-a243-c7e743159460"
+ </a><a data-lightbox="group-7b3546ac-262b-4b14-965b-be6248eb6d13"
href="_images/screenshot_atomeye.jpg"
class=""
title=""
data-title=""
><img src="_images/screenshot_atomeye.jpg"
class=""
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-678e5623-6cd3-4bcb-8ec4-1ca57392d6d8"
+ </a><a data-lightbox="group-33cf83f7-5084-4237-9bb3-0f8f642c9073"
href="_images/screenshot_pymol.jpg"
class=""
title=""
data-title=""
><img src="_images/screenshot_pymol.jpg"
class=""
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-ca92cc6f-e5c3-492e-a2da-af16743cbf57"
+ </a><a data-lightbox="group-34da1da2-45fe-4216-a06c-84976989f2b6"
href="_images/screenshot_vmd.jpg"
class=""
title=""
data-title=""
><img src="_images/screenshot_vmd.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a></div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="Section_errors.html" class="btn btn-neutral float-right" title="12. Errors" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="Section_modify.html" class="btn btn-neutral" title="10. Modifying & extending LAMMPS" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/balance.html b/doc/balance.html
index 51e629484..6d07b7887 100644
--- a/doc/balance.html
+++ b/doc/balance.html
@@ -1,541 +1,541 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>balance command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>balance command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="balance-command">
<span id="index-0"></span><h1>balance command<a class="headerlink" href="#balance-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>balance thresh style args ... keyword value ...
</pre></div>
</div>
<ul class="simple">
<li>thresh = imbalance threshhold that must be exceeded to perform a re-balance</li>
<li>one style/arg pair can be used (or multiple for <em>x</em>,*y*,*z*)</li>
<li>style = <em>x</em> or <em>y</em> or <em>z</em> or <em>shift</em> or <em>rcb</em></li>
</ul>
<pre class="literal-block">
<em>x</em> args = <em>uniform</em> or Px-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in x dimension
numbers = Px-1 ascending values between 0 and 1, Px - # of processors in x dimension
<em>x</em> can be specified together with <em>y</em> or <em>z</em>
<em>y</em> args = <em>uniform</em> or Py-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in y dimension
numbers = Py-1 ascending values between 0 and 1, Py - # of processors in y dimension
<em>y</em> can be specified together with <em>x</em> or <em>z</em>
<em>z</em> args = <em>uniform</em> or Pz-1 numbers between 0 and 1
<em>uniform</em> = evenly spaced cuts between processors in z dimension
numbers = Pz-1 ascending values between 0 and 1, Pz - # of processors in z dimension
<em>z</em> can be specified together with <em>x</em> or <em>y</em>
<em>shift</em> args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshhold is reached
<em>rcb</em> args = none
</pre>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>out</em></li>
</ul>
<pre class="literal-block">
<em>out</em> value = filename
filename = write each processor's sub-domain to a file
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>balance 0.9 x uniform y 0.4 0.5 0.6
balance 1.2 shift xz 5 1.1
balance 1.0 shift xz 5 1.1
balance 1.1 rcb
balance 1.0 shift x 20 1.0 out tmp.balance
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This command adjusts the size and shape of processor sub-domains
within the simulation box, to attempt to balance the number of
particles and thus the computational cost (load) evenly across
processors. The load balancing is “static” in the sense that this
command performs the balancing once, before or between simulations.
The processor sub-domains will then remain static during the
subsequent run. To perform “dynamic” balancing, see the <a class="reference internal" href="fix_balance.html"><em>fix balance</em></a> command, which can adjust processor
sub-domain sizes and shapes on-the-fly during a <a class="reference internal" href="run.html"><em>run</em></a>.</p>
<p>Load-balancing is typically only useful if the particles in the
simulation box have a spatially-varying density distribution. E.g. a
model of a vapor/liquid interface, or a solid with an irregular-shaped
geometry containing void regions. In this case, the LAMMPS default of
dividing the simulation box volume into a regular-spaced grid of 3d
bricks, with one equal-volume sub-domain per procesor, may assign very
different numbers of particles per processor. This can lead to poor
performance when the simulation is run in parallel.</p>
<p>Note that the <a class="reference internal" href="processors.html"><em>processors</em></a> command allows some control
over how the box volume is split across processors. Specifically, for
a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
Pz, subject to the constraint that Px * Py * Pz = P, the total number
of processors. This is sufficient to achieve good load-balance for
some problems on some processor counts. However, all the processor
sub-domains will still have the same shape and same volume.</p>
<p>The requested load-balancing operation is only performed if the
current “imbalance factor” in particles owned by each processor
exceeds the specified <em>thresh</em> parameter. The imbalance factor is
defined as the maximum number of particles owned by any processor,
divided by the average number of particles per processor. Thus an
imbalance factor of 1.0 is perfect balance.</p>
<p>As an example, for 10000 particles running on 10 processors, if the
most heavily loaded processor has 1200 particles, then the factor is
1.2, meaning there is a 20% imbalance. Note that a re-balance can be
forced even if the current balance is perfect (1.0) be specifying a
<em>thresh</em> < 1.0.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Balancing is performed even if the imbalance factor
does not exceed the <em>thresh</em> parameter if a “grid” style is specified
when the current partitioning is “tiled”. The meaning of “grid” vs
“tiled” is explained below. This is to allow forcing of the
partitioning to “grid” so that the <a class="reference internal" href="comm_style.html"><em>comm_style brick</em></a>
command can then be used to replace a current <a class="reference internal" href="comm_style.html"><em>comm_style tiled</em></a> setting.</p>
</div>
<p>When the balance command completes, it prints statistics about the
result, including the change in the imbalance factor and the change in
the maximum number of particles on any processor. For “grid” methods
(defined below) that create a logical 3d grid of processors, the
positions of all cutting planes in each of the 3 dimensions (as
fractions of the box length) are also printed.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This command attempts to minimize the imbalance
factor, as defined above. But depending on the method a perfect
balance (1.0) may not be achieved. For example, “grid” methods
(defined below) that create a logical 3d grid cannot achieve perfect
balance for many irregular distributions of particles. Likewise, if a
portion of the system is a perfect lattice, e.g. the intiial system is
generated by the <a class="reference internal" href="create_atoms.html"><em>create_atoms</em></a> command, then “grid”
methods may be unable to achieve exact balance. This is because
entire lattice planes will be owned or not owned by a single
processor.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The imbalance factor is also an estimate of the
maximum speed-up you can hope to achieve by running a perfectly
balanced simulation versus an imbalanced one. In the example above,
the 10000 particle simulation could run up to 20% faster if it were
perfectly balanced, versus when imbalanced. However, computational
cost is not strictly proportional to particle count, and changing the
relative size and shape of processor sub-domains may lead to
additional computational and communication overheads, e.g. in the PPPM
solver used via the <a class="reference internal" href="kspace_style.html"><em>kspace_style</em></a> command. Thus
you should benchmark the run times of a simulation before and after
balancing.</p>
</div>
<hr class="docutils" />
<p>The method used to perform a load balance is specified by one of the
listed styles (or more in the case of <em>x</em>,*y*,*z*), which are
described in detail below. There are 2 kinds of styles.</p>
<p>The <em>x</em>, <em>y</em>, <em>z</em>, and <em>shift</em> styles are “grid” methods which produce
a logical 3d grid of processors. They operate by changing the cutting
planes (or lines) between processors in 3d (or 2d), to adjust the
volume (area in 2d) assigned to each processor, as in the following 2d
diagram where processor sub-domains are shown and atoms are colored by
the processor that owns them. The leftmost diagram is the default
partitioning of the simulation box across processors (one sub-box for
each of 16 processors); the middle diagram is after a “grid” method
has been applied.</p>
-<a data-lightbox="group-be41eda3-1235-46a9-a40b-77e8fd6ad5ad"
+<a data-lightbox="group-6e7c213c-b987-4061-8585-27da8657e31a"
href="_images/balance_uniform.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_uniform.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-7a12768d-cd54-48b6-9995-f7cf94f0625f"
+ </a><a data-lightbox="group-ddd51b74-c3a0-47b0-911d-532ebe682ab8"
href="_images/balance_nonuniform.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_nonuniform.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-430fe552-2b09-44ab-b73a-959b24d83be3"
+ </a><a data-lightbox="group-be056d80-767f-45c4-b836-a732c86d1282"
href="_images/balance_rcb.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_rcb.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>The <em>rcb</em> style is a “tiling” method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles in each sub-box, as
in the rightmost diagram above.</p>
<p>The “grid” methods can be used with either of the
<a class="reference internal" href="comm_style.html"><em>comm_style</em></a> command options, <em>brick</em> or <em>tiled</em>. The
“tiling” methods can only be used with <a class="reference internal" href="comm_style.html"><em>comm_style tiled</em></a>. Note that it can be useful to use a “grid”
method with <a class="reference internal" href="comm_style.html"><em>comm_style tiled</em></a> to return the domain
partitioning to a logical 3d grid of processors so that “comm_style
brick” can afterwords be specified for subsequent <a class="reference internal" href="run.html"><em>run</em></a>
commands.</p>
<p>When a “grid” method is specified, the current domain partitioning can
be either a logical 3d grid or a tiled partitioning. In the former
case, the current logical 3d grid is used as a starting point and
changes are made to improve the imbalance factor. In the latter case,
the tiled partitioning is discarded and a logical 3d grid is created
with uniform spacing in all dimensions. This becomes the starting
point for the balancing operation.</p>
<p>When a “tiling” method is specified, the current domain partitioning
(“grid” or “tiled”) is ignored, and a new partitioning is computed
from scratch.</p>
<hr class="docutils" />
<p>The <em>x</em>, <em>y</em>, and <em>z</em> styles invoke a “grid” method for balancing, as
described above. Note that any or all of these 3 styles can be
specified together, one after the other, but they cannot be used with
any other style. This style adjusts the position of cutting planes
between processor sub-domains in specific dimensions. Only the
specified dimensions are altered.</p>
<p>The <em>uniform</em> argument spaces the planes evenly, as in the left
diagrams above. The <em>numeric</em> argument requires listing Ps-1 numbers
that specify the position of the cutting planes. This requires
knowing Ps = Px or Py or Pz = the number of processors assigned by
LAMMPS to the relevant dimension. This assignment is made (and the
Px, Py, Pz values printed out) when the simulation box is created by
the “create_box” or “read_data” or “read_restart” command and is
influenced by the settings of the <a class="reference internal" href="processors.html"><em>processors</em></a>
command.</p>
<p>Each of the numeric values must be between 0 and 1, and they must be
listed in ascending order. They represent the fractional position of
the cutting place. The left (or lower) edge of the box is 0.0, and
the right (or upper) edge is 1.0. Neither of these values is
specified. Only the interior Ps-1 positions are specified. Thus is
there are 2 procesors in the x dimension, you specify a single value
such as 0.75, which would make the left processor’s sub-domain 3x
larger than the right processor’s sub-domain.</p>
<hr class="docutils" />
<p>The <em>shift</em> style invokes a “grid” method for balancing, as
described above. It changes the positions of cutting planes between
processors in an iterative fashion, seeking to reduce the imbalance
factor, similar to how the <a class="reference internal" href="fix_balance.html"><em>fix balance shift</em></a>
command operates.</p>
<p>The <em>dimstr</em> argument is a string of characters, each of which must be
an “x” or “y” or “z”. Eacn character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.</p>
<p>Balancing proceeds by adjusting the cutting planes in each of the
dimensions listed in <em>dimstr</em>, one dimension at a time. For a single
dimension, the balancing operation (described below) is iterated on up
to <em>Niter</em> times. After each dimension finishes, the imbalance factor
is re-computed, and the balancing operation halts if the <em>stopthresh</em>
criterion is met.</p>
<p>A rebalance operation in a single dimension is performed using a
recursive multisectioning algorithm, where the position of each
cutting plane (line in 2d) in the dimension is adjusted independently.
This is similar to a recursive bisectioning for a single value, except
that the bounds used for each bisectioning take advantage of
information from neighboring cuts if possible. At each iteration, the
count of particles on either side of each plane is tallied. If the
counts do not match the target value for the plane, the position of
the cut is adjusted to be halfway between a low and high bound. The
low and high bounds are adjusted on each iteration, using new count
information, so that they become closer together over time. Thus as
the recustion progresses, the count of particles on either side of the
plane gets closer to the target value.</p>
<p>Once the rebalancing is complete and final processor sub-domains
assigned, particles are migrated to their new owning processor, and
the balance procedure ends.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">At each rebalance operation, the bisectioning for each
cutting plane (line in 2d) typcially starts with low and high bounds
separated by the extent of a processor’s sub-domain in one dimension.
The size of this bracketing region shrinks by 1/2 every iteration.
Thus if <em>Niter</em> is specified as 10, the cutting plane will typically
be positioned to 1 part in 1000 accuracy (relative to the perfect
target position). For <em>Niter</em> = 20, it will be accurate to 1 part in
a million. Thus there is no need ot set <em>Niter</em> to a large value.
LAMMPS will check if the threshold accuracy is reached (in a
dimension) is less iterations than <em>Niter</em> and exit early. However,
<em>Niter</em> should also not be set too small, since it will take roughly
the same number of iterations to converge even if the cutting plane is
initially close to the target value.</p>
</div>
<hr class="docutils" />
<p>The <em>rcb</em> style invokes a “tiled” method for balancing, as described
above. It performs a recursive coordinate bisectioning (RCB) of the
simulation domain. The basic idea is as follows.</p>
<p>The simulation domain is cut into 2 boxes by an axis-aligned cut in
the longest dimension, leaving one new box on either side of the cut.
All the processors are also partitioned into 2 groups, half assigned
to the box on the lower side of the cut, and half to the box on the
upper side. (If the processor count is odd, one side gets an extra
processor.) The cut is positioned so that the number of atoms in the
lower box is exactly the number that the processors assigned to that
box should own for load balance to be perfect. This also makes load
balance for the upper box perfect. The positioning is done
iteratively, by a bisectioning method. Note that counting atoms on
either side of the cut requires communication between all processors
at each iteration.</p>
<p>That is the procedure for the first cut. Subsequent cuts are made
recursively, in exactly the same manner. The subset of processors
assigned to each box make a new cut in the longest dimension of that
box, splitting the box, the subset of processsors, and the atoms in
the box in two. The recursion continues until every processor is
assigned a sub-box of the entire simulation domain, and owns the atoms
in that sub-box.</p>
<hr class="docutils" />
<p>The <em>out</em> keyword writes a text file to the specified <em>filename</em> with
the results of the balancing operation. The file contains the bounds
of the sub-domain for each processor after the balancing operation
completes. The format of the file is compatible with the
<a class="reference external" href="pizza">Pizza.py</a> <em>mdump</em> tool which has support for manipulating and
visualizing mesh files. An example is shown here for a balancing by 4
processors for a 2d problem:</p>
<div class="highlight-python"><div class="highlight"><pre>ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16
</pre></div>
</div>
<p>The coordinates of all the vertices are listed in the NODES section, 5
per processor. Note that the 4 sub-domains share vertices, so there
will be duplicate nodes in the list.</p>
<p>The “SQUARES” section lists the node IDs of the 4 vertices in a
rectangle for each processor (1 to 4).</p>
<p>For a 3d problem, the syntax is similar with 8 vertices listed for
each processor, instead of 4, and “SQUARES” replaced by “CUBES”.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>For 2d simulations, the <em>z</em> style cannot be used. Nor can a “z”
appear in <em>dimstr</em> for the <em>shift</em> style.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="processors.html"><em>processors</em></a>, <a class="reference internal" href="fix_balance.html"><em>fix balance</em></a></p>
<p><strong>Default:</strong> none</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/compute_saed.html b/doc/compute_saed.html
index 58cdbd610..e3525a6d5 100644
--- a/doc/compute_saed.html
+++ b/doc/compute_saed.html
@@ -1,362 +1,362 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>compute saed command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>compute saed command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="compute-saed-command">
<span id="index-0"></span><h1>compute saed command<a class="headerlink" href="#compute-saed-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>compute ID group-ID saed lambda type1 type2 ... typeN keyword value ...
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="compute.html"><em>compute</em></a> command</li>
<li>saed = style name of this compute command</li>
<li>lambda = wavelength of incident radiation (length units)</li>
<li>type1 type2 ... typeN = chemical symbol of each atom type (see valid options below)</li>
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>Kmax</em> or <em>Zone</em> or <em>dR_Ewald</em> or <em>c</em> or <em>manual</em> or <em>echo</em></li>
</ul>
<pre class="literal-block">
<em>Kmax</em> value = Maximum distance explored from reciprocal space origin
(inverse length units)
<em>Zone</em> values = z1 z2 z3
z1,z2,z3 = Zone axis of incident radiation. If z1=z2=z3=0 all
reciprocal space will be meshed up to <em>Kmax</em>
<em>dR_Ewald</em> value = Thickness of Ewald sphere slice intercepting
reciprocal space (inverse length units)
<em>c</em> values = c1 c2 c3
c1,c2,c3 = parameters to adjust the spacing of the reciprocal
lattice nodes in the h, k, and l directions respectively
<em>manual</em> = flag to use manual spacing of reciprocal lattice points
based on the values of the <em>c</em> parameters
<em>echo</em> = flag to provide extra output for debugging purposes
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>compute 1 all saed 0.0251 Al O Kmax 1.70 Zone 0 0 1 dR_Ewald 0.01 c 0.5 0.5 0.5
compute 2 all saed 0.0251 Ni Kmax 1.70 Zone 0 0 0 c 0.05 0.05 0.05 manual echo
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>fix saed/vtk 1 1 1 c_1 file Al2O3_001.saed
fix saed/vtk 1 1 1 c_2 file Ni_000.saed
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Define a computation that calculates electron diffraction intensity as
described in <a class="reference internal" href="fix_saed_vtk.html#coleman"><span>(Coleman)</span></a> on a mesh of reciprocal lattice nodes
defined by the entire simulation domain (or manually) using simulated
radiation of wavelength lambda.</p>
<p>The electron diffraction intensity I at each reciprocal lattice point
is computed from the structure factor F using the equations:</p>
<img alt="_images/compute_saed1.jpg" class="align-center" src="_images/compute_saed1.jpg" />
<img alt="_images/compute_saed2.jpg" class="align-center" src="_images/compute_saed2.jpg" />
<p>Here, K is the location of the reciprocal lattice node, rj is the
position of each atom, fj are atomic scattering factors.</p>
<p>Diffraction intensities are calculated on a three-dimensional mesh of
reciprocal lattice nodes. The mesh spacing is defined either (a) by
the entire simulation domain or (b) manually using selected values as
shown in the 2D diagram below.</p>
-<a data-lightbox="group-59ebfa1f-2682-4e85-8723-aaad71f16549"
+<a data-lightbox="group-daea89e3-8273-4ecb-9619-5bdfbb8911ce"
href="_images/saed_mesh.jpg"
class=""
title=""
data-title=""
><img src="_images/saed_mesh.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>For a mesh defined by the simulation domain, a rectilinear grid is
constructed with spacing <a href="#id1"><span class="problematic" id="id2">*</span></a>c**inv(A) along each reciprocal lattice
axis. Where A are the vectors corresponding to the edges of the
simulation cell. If one or two directions has non-periodic boundary
conditions, then the spacing in these directions is defined from the
average of the (inversed) box lengths with periodic boundary conditions.
Meshes defined by the simulation domain must contain at least one periodic
boundary.</p>
<p>If the <em>manual</em> flag is included, the mesh of reciprocal lattice nodes
will defined using the <em>c</em> values for the spacing along each reciprocal
lattice axis. Note that manual mapping of the reciprocal space mesh is
good for comparing diffraction results from multiple simulations; however
it can reduce the likelihood that Bragg reflections will be satisfied
unless small spacing parameters <0.05 Angstrom^(-1) are implemented.
Meshes with manual spacing do not require a periodic boundary.</p>
<p>The limits of the reciprocal lattice mesh are determined by the use of
the <em>Kmax</em>, <em>Zone</em>, and <em>dR_Ewald</em> parameters. The rectilinear mesh
created about the origin of reciprocal space is terminated at the
boundary of a sphere of radius <em>Kmax</em> centered at the origin. If
<em>Zone</em> parameters z1=z2=z3=0 are used, diffraction intensities are
computed throughout the entire spherical volume - note this can greatly
increase the cost of computation. Otherwise, <em>Zone</em> parameters will
denote the z1=h, z2=k, and z3=l (in a global since) zone axis of an
intersecting Ewald sphere. Diffraction intensities will only be
computed at the intersection of the reciprocal lattice mesh and a
<em>dR_Ewald</em> thick surface of the Ewald sphere. See the example 3D
intestiety data and the intersection of a [010] zone axis in the below image.</p>
-<a data-lightbox="group-02bf6c2f-3186-4f52-82eb-5a24fa516cfd"
+<a data-lightbox="group-15501aab-aa21-4ebd-b806-f3ef30fbe207"
href="_images/saed_ewald_intersect.jpg"
class=""
title=""
data-title=""
><img src="_images/saed_ewald_intersect.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>The atomic scattering factors, fj, accounts for the reduction in
diffraction intensity due to Compton scattering. Compute saed uses
analytical approximations of the atomic scattering factors that vary
for each atom type (type1 type2 ... typeN) and angle of diffraction.
The analytic approximation is computed using the formula
<a class="reference internal" href="#brown"><span>(Brown)</span></a>:</p>
<img alt="_images/compute_saed3.jpg" class="align-center" src="_images/compute_saed3.jpg" />
<p>Coefficients parameterized by <a class="reference internal" href="#fox"><span>(Fox)</span></a> are assigned for each
atom type designating the chemical symbol and charge of each atom
type. Valid chemical symbols for compute saed are:</p>
<dl class="docutils">
<dt>H: He: Li: Be: B:</dt>
<dd><blockquote class="first">
<div>C: N: O: F: Ne:</div></blockquote>
<dl class="docutils">
<dt>Na: Mg: Al: Si: P:</dt>
<dd>S: Cl: Ar: K: Ca:</dd>
</dl>
<p class="last">Sc: Ti: V: Cr: Mn:
Fe: Co: Ni: Cu: Zn:
Ga: Ge: As: Se: Br:
Kr: Rb: Sr: Y: Zr:
Nb: Mo: Tc: Ru: Rh:
Pd: Ag: Cd: In: Sn:
Sb: Te: I: Xe: Cs:
Ba: La: Ce: Pr: Nd:
Pm: Sm: Eu: Gd: Tb:
Dy: Ho: Er: Tm: Yb:
Lu: Hf: Ta: W: Re:
Os: Ir: Pt: Au: Hg:
Tl: Pb: Bi: Po: At:
Rn: Fr: Ra: Ac: Th:
Pa: U: Np: Pu: Am:
Cm: Bk: Cf:tb(c=5,s=:)</p>
</dd>
</dl>
<p>If the <em>echo</em> keyword is specified, compute saed will provide extra
reporting information to the screen.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global vector. The length of the vector is
the number of reciprocal lattice nodes that are explored by the mesh.
The entries of the global vector are the computed diffraction
intensities as described above.</p>
<p>The vector can be accessed by any command that uses global values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span>this section</span></a> for an overview of LAMMPS output
options.</p>
<p>All array values calculated by this compute are “intensive”.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>The compute_saed command does not work for triclinic cells.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="fix_saed_vtk.html"><em>fix saed_vtk</em></a>, <a class="reference internal" href="compute_xrd.html"><em>compute xrd</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The option defaults are Kmax = 1.70, Zone 1 0 0, c 1 1 1, dR_Ewald =
0.01.</p>
<hr class="docutils" />
<p id="coleman"><strong>(Coleman)</strong> Coleman, Spearot, Capolungo, MSMSE, 21, 055020
(2013).</p>
<p id="brown"><strong>(Brown)</strong> Brown et al. International Tables for Crystallography
Volume C: Mathematical and Chemical Tables, 554-95 (2004).</p>
<p id="fox"><strong>(Fox)</strong> Fox, O’Keefe, Tabbernor, Acta Crystallogr. A, 45, 786-93
(1989).</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/compute_xrd.html b/doc/compute_xrd.html
index 0e6681612..97a62cbc6 100644
--- a/doc/compute_xrd.html
+++ b/doc/compute_xrd.html
@@ -1,388 +1,388 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>compute xrd command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>compute xrd command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="compute-xrd-command">
<span id="index-0"></span><h1>compute xrd command<a class="headerlink" href="#compute-xrd-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>compute ID group-ID xrd lambda type1 type2 ... typeN keyword value ...
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="compute.html"><em>compute</em></a> command</li>
<li>xrd = style name of this compute command</li>
<li>lambda = wavelength of incident radiation (length units)</li>
<li>type1 type2 ... typeN = chemical symbol of each atom type (see valid options below)</li>
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>2Theta</em> or <em>c</em> or <em>LP</em> or <em>manual</em> or <em>echo</em></li>
</ul>
<pre class="literal-block">
<em>2Theta</em> values = Min2Theta Max2Theta
Min2Theta,Max2Theta = minimum and maximum 2 theta range to explore
(radians or degrees)
<em>c</em> values = c1 c2 c3
c1,c2,c3 = parameters to adjust the spacing of the reciprocal
lattice nodes in the h, k, and l directions respectively
<em>LP</em> value = switch to apply Lorentz-polarization factor
0/1 = off/on
<em>manual</em> = flag to use manual spacing of reciprocal lattice points
based on the values of the <em>c</em> parameters
<em>echo</em> = flag to provide extra output for debugging purposes
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>compute 1 all xrd 1.541838 Al O 2Theta 0.087 0.87 c 1 1 1 LP 1 echo
compute 2 all xrd 1.541838 Al O 2Theta 10 100 c 0.05 0.05 0.05 LP 1 manual
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>fix 1 all ave/histo/weights 1 1 1 0.087 0.87 250 c_1[1] c_1[2] mode vector file Rad2Theta.xrd
fix 2 all ave/histo/weights 1 1 1 10 100 250 c_2[1] c_2[2] mode vector file Deg2Theta.xrd
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Define a computation that calculates x-ray diffraction intensity as described
in <a class="reference internal" href="fix_saed_vtk.html#coleman"><span>(Coleman)</span></a> on a mesh of reciprocal lattice nodes defined
by the entire simulation domain (or manually) using a simulated radiation
of wavelength lambda.</p>
<p>The x-ray diffraction intensity, I, at each reciprocal lattice point, k,
is computed from the structure factor, F, using the equations:</p>
<img alt="_images/compute_xrd1.jpg" class="align-center" src="_images/compute_xrd1.jpg" />
<img alt="_images/compute_xrd2.jpg" class="align-center" src="_images/compute_xrd2.jpg" />
<img alt="_images/compute_xrd3.jpg" class="align-center" src="_images/compute_xrd3.jpg" />
<img alt="_images/compute_xrd4.jpg" class="align-center" src="_images/compute_xrd4.jpg" />
<p>Here, K is the location of the reciprocal lattice node, rj is the
position of each atom, fj are atomic scattering factors, LP is the
Lorentz-polarization factor, and theta is the scattering angle of
diffraction. The Lorentz-polarization factor can be turned off using
the optional <em>LP</em> keyword.</p>
<p>Diffraction intensities are calculated on a three-dimensional mesh of
reciprocal lattice nodes. The mesh spacing is defined either (a)
by the entire simulation domain or (b) manually using selected values as
shown in the 2D diagram below.</p>
-<a data-lightbox="group-b594ec59-db88-4076-b9a2-0026d73658c4"
+<a data-lightbox="group-13692fe7-8a16-4953-af8e-6c530dcccb1a"
href="_images/xrd_mesh.jpg"
class=""
title=""
data-title=""
><img src="_images/xrd_mesh.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>For a mesh defined by the simulation domain, a rectilinear grid is
constructed with spacing <a href="#id1"><span class="problematic" id="id2">*</span></a>c**inv(A) along each reciprocal lattice
axis. Where A are the vectors corresponding to the edges of the
simulation cell. If one or two directions has non-periodic boundary
conditions, then the spacing in these directions is defined from the
average of the (inversed) box lengths with periodic boundary conditions.
Meshes defined by the simulation domain must contain at least one periodic
boundary.</p>
<p>If the <em>manual</em> flag is included, the mesh of reciprocal lattice nodes
will defined using the <em>c</em> values for the spacing along each
reciprocal lattice axis. Note that manual mapping of the reciprocal
space mesh is good for comparing diffraction results from multiple
simulations; however it can reduce the likelihood that Bragg
reflections will be satisfied unless small spacing parameters (< 0.05
Angstrom^(-1)) are implemented. Meshes with manual spacing do not
require a periodic boundary.</p>
<p>The limits of the reciprocal lattice mesh are determined by range of
scattering angles explored. The <em>2Theta</em> parameters allows the user
to reduce the scattering angle range to only the region of interest
which reduces the cost of the computation.</p>
<p>The atomic scattering factors, fj, accounts for the reduction in
diffraction intensity due to Compton scattering. Compute xrd uses
analytical approximations of the atomic scattering factors that vary
for each atom type (type1 type2 ... typeN) and angle of diffraction.
The analytic approximation is computed using the formula
<a class="reference internal" href="#colliex"><span>(Colliex)</span></a>:</p>
<img alt="_images/compute_xrd5.jpg" class="align-center" src="_images/compute_xrd5.jpg" />
<p>Coefficients parameterized by <a class="reference internal" href="#peng"><span>(Peng)</span></a> are assigned for each
atom type designating the chemical symbol and charge of each atom
type. Valid chemical symbols for compute xrd are:</p>
<dl class="docutils">
<dt>H: He1-: He: Li: Li1+:</dt>
<dd><blockquote class="first">
<div><blockquote>
<div><dl class="docutils">
<dt>Be: Be2+: B: C: Cval:</dt>
<dd>N: O: O1-: F: F1-:</dd>
</dl>
<p>Ne: Na: Na1+: Mg: Mg2+:
Al: Al3+: Si: Sival: Si4+:</p>
<blockquote>
<div>P: S: Cl: Cl1-: Ar:
K: Ca: Ca2+: Sc: Sc3+:</div></blockquote>
<p>Ti: Ti2+: Ti3+: Ti4+: V:</p>
</div></blockquote>
<p>V2+: V3+: V5+: Cr: Cr2+:</p>
</div></blockquote>
<dl class="docutils">
<dt>Cr3+: Mn: Mn2+: Mn3+: Mn4+:</dt>
<dd>Fe: Fe2+: Fe3+: Co: Co2+:
Co: Ni: Ni2+: Ni3+: Cu:</dd>
</dl>
<p>Cu1+: Cu2+: Zn: Zn2+: Ga:
Ga3+: Ge: Ge4+: As: Se:</p>
<blockquote>
<div>Br: Br1-: Kr: Rb: Rb1+:
Sr: Sr2+: Y: Y3+: Zr:</div></blockquote>
<p>Zr4+: Nb: Nb3+: Nb5+: Mo:
Mo3+: Mo5+: Mo6+: Tc: Ru:
Ru3+: Ru4+: Rh: Rh3+: Rh4+:</p>
<blockquote>
<div>Pd: Pd2+: Pd4+: Ag: Ag1+:</div></blockquote>
<dl class="docutils">
<dt>Ag2+: Cd: Cd2+: In: In3+:</dt>
<dd>Sn: Sn2+: Sn4+: Sb: Sb3+:</dd>
<dt>Sb5+: Te: I: I1-: Xe:</dt>
<dd>Cs: Cs1+: Ba: Ba2+: La:</dd>
</dl>
<p>La3+: Ce: Ce3+: Ce4+: Pr:
Pr3+: Pr4+: Nd: Nd3+: Pm:
Pm3+: Sm: Sm3+: Eu: Eu2+:
Eu3+: Gd: Gd3+: Tb: Tb3+:</p>
<blockquote>
<div>Dy: Dy3+: Ho: Ho3+: Er:</div></blockquote>
<p>Er3+: Tm: Tm3+: Yb: Yb2+:
Yb3+: Lu: Lu3+: Hf: Hf4+:</p>
<blockquote>
<div>Ta: Ta5+: W: W6+: Re:
Os: Os4+: Ir: Ir3+: Ir4+:
Pt: Pt2+: Pt4+: Au: Au1+:</div></blockquote>
<p>Au3+: Hg: Hg1+: Hg2+: Tl:
Tl1+: Tl3+: Pb: Pb2+: Pb4+:</p>
<blockquote>
<div>Bi: Bi3+: Bi5+: Po: At:
Rn: Fr: Ra: Ra2+: Ac:</div></blockquote>
<dl class="docutils">
<dt>Ac3+: Th: Th4+: Pa: U:</dt>
<dd>U3+: U4+: U6+: Np: Np3+:</dd>
</dl>
<p class="last">Np4+: Np6+: Pu: Pu3+: Pu4+:
Pu6+: Am: Cm: Bk: Cf:tb(c=5,s=:)</p>
</dd>
</dl>
<p>If the <em>echo</em> keyword is specified, compute xrd will provide extra
reporting information to the screen.</p>
<p><strong>Output info:</strong></p>
<p>This compute calculates a global array. The number of rows in the
array is the number of reciprocal lattice nodes that are explored
which by the mesh. The global array has 2 columns.</p>
<p>The first column contains the diffraction angle in the units (radians
or degrees) provided with the <em>2Theta</em> values. The second column contains
the computed diffraction intensities as described above.</p>
<p>The array can be accessed by any command that uses global values
from a compute as input. See <a class="reference internal" href="Section_howto.html#howto-15"><span>this section</span></a> for an overview of LAMMPS output
options.</p>
<p>All array values calculated by this compute are “intensive”.</p>
</div>
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>The compute_xrd command does not work for triclinic cells.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="fix_ave_histo.html"><em>fix ave/histo</em></a>,
<a class="reference internal" href="compute_saed.html"><em>compute saed</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The option defaults are 2Theta = 1 179 (degrees), c = 1 1 1, LP = 1,
no manual flag, no echo flag.</p>
<hr class="docutils" />
<p id="coleman"><strong>(Coleman)</strong> Coleman, Spearot, Capolungo, MSMSE, 21, 055020
(2013).</p>
<p id="colliex"><strong>(Colliex)</strong> Colliex et al. International Tables for Crystallography
Volume C: Mathematical and Chemical Tables, 249-429 (2004).</p>
<p id="peng"><strong>(Peng)</strong> Peng, Ren, Dudarev, Whelan, Acta Crystallogr. A, 52, 257-76
(1996).</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/create_atoms.html b/doc/create_atoms.html
index d92dcff00..6a7997446 100644
--- a/doc/create_atoms.html
+++ b/doc/create_atoms.html
@@ -1,493 +1,493 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>create_atoms command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>create_atoms command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="create-atoms-command">
<span id="index-0"></span><h1>create_atoms command<a class="headerlink" href="#create-atoms-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>create_atoms type style args keyword values ...
</pre></div>
</div>
<ul class="simple">
<li>type = atom type (1-Ntypes) of atoms to create (offset for molecule creation)</li>
<li>style = <em>box</em> or <em>region</em> or <em>single</em> or <em>random</em></li>
</ul>
<pre class="literal-block">
<em>box</em> args = none
<em>region</em> args = region-ID
region-ID = particles will only be created if contained in the region
<em>single</em> args = x y z
x,y,z = coordinates of a single particle (distance units)
<em>random</em> args = N seed region-ID
N = number of particles to create
seed = random # seed (positive integer)
region-ID = create atoms within this region, use NULL for entire simulation box
</pre>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>mol</em> or <em>basis</em> or <em>remap</em> or <em>var</em> or <em>set</em> or <em>units</em></li>
</ul>
<pre class="literal-block">
<em>mol</em> value = template-ID seed
template-ID = ID of molecule template specified in a separate <a class="reference internal" href="molecule.html"><em>molecule</em></a> command
seed = random # seed (positive integer)
<em>basis</em> values = M itype
M = which basis atom
itype = atom type (1-N) to assign to this basis atom
<em>remap</em> value = <em>yes</em> or <em>no</em>
<em>var</em> value = name = variable name to evaluate for test of atom creation
<em>set</em> values = dim vname
dim = <em>x</em> or <em>y</em> or <em>z</em>
name = name of variable to set with x,y,z atom position
<em>rotate</em> values = Rx Ry Rz theta
Rx,Ry,Rz = rotation vector for single molecule
theta = rotation angle for single molecule (degrees)
<em>units</em> value = <em>lattice</em> or <em>box</em>
<em>lattice</em> = the geometry is defined in lattice units
<em>box</em> = the geometry is defined in simulation box units
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>create_atoms 1 box
create_atoms 3 region regsphere basis 2 3
create_atoms 3 single 0 0 5
create_atoms 1 box var v set x xpos set y ypos
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This command creates atoms (or molecules) on a lattice, or a single
atom (or molecule), or a random collection of atoms (or molecules), as
an alternative to reading in their coordinates explicitly via a
<a class="reference internal" href="read_data.html"><em>read_data</em></a> or <a class="reference internal" href="read_restart.html"><em>read_restart</em></a>
command. A simulation box must already exist, which is typically
created via the <a class="reference internal" href="create_box.html"><em>create_box</em></a> command. Before using
this command, a lattice must also be defined using the
<a class="reference internal" href="lattice.html"><em>lattice</em></a> command, unless you specify the <em>single</em> style
with units = box or the <em>random</em> style. For the remainder of this doc
page, a created atom or molecule is referred to as a “particle”.</p>
<p>If created particles are individual atoms, they are assigned the
specified atom <em>type</em>, though this can be altered via the <em>basis</em>
keyword as discussed below. If molecules are being created, the type
of each atom in the created molecule is specified in the file read by
the <a class="reference internal" href="molecule.html"><em>molecule</em></a> command, and those values are added to
the specified atom <em>type</em>. E.g. if <em>type</em> = 2, and the file specifies
atom types 1,2,3, then each created molecule will have atom types
3,4,5.</p>
<p>For the <em>box</em> style, the create_atoms command fills the entire
simulation box with particles on the lattice. If your simulation box
is periodic, you should insure its size is a multiple of the lattice
spacings, to avoid unwanted atom overlaps at the box boundaries. If
your box is periodic and a multiple of the lattice spacing in a
particular dimension, LAMMPS is careful to put exactly one particle at
the boundary (on either side of the box), not zero or two.</p>
<p>For the <em>region</em> style, a geometric volume is filled with particles on
the lattice. This volume what is inside the simulation box and is
also consistent with the region volume. See the <a class="reference internal" href="region.html"><em>region</em></a>
command for details. Note that a region can be specified so that its
“volume” is either inside or outside a geometric boundary. Also note
that if your region is the same size as a periodic simulation box (in
some dimension), LAMMPS does not implement the same logic described
above as for the <em>box</em> style, to insure exactly one particle at
periodic boundaries. if this is what you desire, you should either
use the <em>box</em> style, or tweak the region size to get precisely the
particles you want.</p>
<p>For the <em>single</em> style, a single particle is added to the system at
the specified coordinates. This can be useful for debugging purposes
or to create a tiny system with a handful of particles at specified
positions.</p>
<p>For the <em>random</em> style, N particles are added to the system at
randomly generated coordinates, which can be useful for generating an
amorphous system. The particles are created one by one using the
speficied random number <em>seed</em>, resulting in the same set of particles
coordinates, independent of how many processors are being used in the
simulation. If the <em>region-ID</em> argument is specified as NULL, then
the created particles will be anywhere in the simulation box. If a
<em>region-ID</em> is specified, a geometric volume is filled which is both
inside the simulation box and is also consistent with the region
volume. See the <a class="reference internal" href="region.html"><em>region</em></a> command for details. Note that
a region can be specified so that its “volume” is either inside or
outside a geometric boundary.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Particles generated by the <em>random</em> style will
typically be highly overlapped which will cause many interatomic
potentials to compute large energies and forces. Thus you should
either perform an <a class="reference internal" href="minimize.html"><em>energy minimization</em></a> or run dynamics
with <a class="reference internal" href="fix_nve_limit.html"><em>fix nve/limit</em></a> to equilibrate such a system,
before running normal dynamics.</p>
</div>
<p>Note that this command adds particles to those that already exist.
This means it can be used to add particles to a system previously read
in from a data or restart file. Or the create_atoms command can be
used multiple times, to add multiple sets of particles to the
simulation. For example, grain boundaries can be created, by
interleaving create_atoms with <a class="reference internal" href="lattice.html"><em>lattice</em></a> commands
specifying different orientations. By using the create_atoms command
in conjunction with the <a class="reference internal" href="delete_atoms.html"><em>delete_atoms</em></a> command,
reasonably complex geometries can be created, or a protein can be
solvated with a surrounding box of water molecules.</p>
<p>In all these cases, care should be taken to insure that new atoms do
not overlap existing atoms inappropriately, especially if molecules
are being added. The <a class="reference internal" href="delete_atoms.html"><em>delete_atoms</em></a> command can be
used to remove overlapping atoms or molecules.</p>
<hr class="docutils" />
<p>Individual atoms are inserted by this command, unless the <em>mol</em>
keyword is used. It specifies a <em>template-ID</em> previously defined
using the <a class="reference internal" href="molecule.html"><em>molecule</em></a> command, which reads a file that
defines the molecule. The coordinates, atom types, charges, etc, as
well as any bond/angle/etc and special neighbor information for the
molecule can be specified in the molecule file. See the
<a class="reference internal" href="molecule.html"><em>molecule</em></a> command for details. The only settings
required to be in this file are the coordinates and types of atoms in
the molecule.</p>
<p>Using a lattice to add molecules, e.g. via the <em>box</em> or <em>region</em> or
<em>single</em> styles, is exactly the same as adding atoms on lattice
points, except that entire molecules are added at each point, i.e. on
the point defined by each basis atom in the unit cell as it tiles the
simulation box or region. This is done by placing the geometric
center of the molecule at the lattice point, and giving the molecule a
random orientation about the point. The random <em>seed</em> specified with
the <em>mol</em> keyword is used for this operation, and the random numbers
generated by each processor are different. This means the coordinates
of individual atoms (in the molecules) will be different when running
on different numbers of processors, unlike when atoms are being
created in parallel.</p>
<p>Also note that because of the random rotations, it may be important to
use a lattice with a large enough spacing that adjacent molecules will
not overlap, regardless of their relative orientations.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If the <a class="reference internal" href="create_box.html"><em>create_box</em></a> command is used to
create the simulation box, followed by the create_atoms command with
its <em>mol</em> option for adding molecules, then you typically need to use
the optional keywords allowed by the <a class="reference internal" href="create_box.html"><em>create_box</em></a>
command for extra bonds (angles,etc) or extra special neighbors. This
is because by default, the <a class="reference internal" href="create_box.html"><em>create_box</em></a> command sets
up a non-molecular system which doesn’t allow molecules to be added.</p>
</div>
<hr class="docutils" />
<p>This is the meaning of the other allowed keywords.</p>
<p>The <em>basis</em> keyword is only used when atoms (not molecules) are being
created. It specifies an atom type that will be assigned to specific
basis atoms as they are created. See the <a class="reference internal" href="lattice.html"><em>lattice</em></a>
command for specifics on how basis atoms are defined for the unit cell
of the lattice. By default, all created atoms are assigned the
argument <em>type</em> as their atom type.</p>
<p>The <em>remap</em> keyword only applies to the <em>single</em> style. If it is set
to <em>yes</em>, then if the specified position is outside the simulation
box, it will mapped back into the box, assuming the relevant
dimensions are periodic. If it is set to <em>no</em>, no remapping is done
and no particle is created if its position is outside the box.</p>
<p>The <em>var</em> and <em>set</em> keywords can be used to provide a criterion for
accepting or rejecting the addition of an individual atom, based on
its coordinates. The <em>vname</em> specified for the <em>var</em> keyword is the
name of an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a> which should evaluate
to a zero or non-zero value based on one or two or three variables
which will store the x, y, or z coordinates of an atom (one variable
per coordinate). These other variables must be <a class="reference internal" href="variable.html"><em>equal-style variables</em></a> defined in the input script, but their
formula can by anything. The <em>set</em> keyword is used to identify the
names of these other variables, one variable for the x-coordinate of a
created atom, one for y, and one for z.</p>
<p>When an atom is created, its x, y, or z coordinates override the
formula for any <em>set</em> variable that is defined. The <em>var</em> variable is
then evaluated. If the returned value is 0.0, the atom is not
created. If it is non-zero, the atom is created. After all atoms are
created, the formulas defined for all of the <em>set</em> variables are
restored to their original strings.</p>
<p>As an example, these commands can be used in a 2d simulation, to
create a sinusoidal surface. Note that the surface is “rough” due to
individual lattice points being “above” or “below” the mathematical
expression for the sinusoidal curve. If a finer lattice were used,
the sinusoid would appear to be “smoother”. Also note the use of the
“xlat” and “ylat” <a class="reference internal" href="thermo_style.html"><em>thermo_style</em></a> keywords which
converts lattice spacings to distance. Click on the image for a
larger version.</p>
<div class="highlight-python"><div class="highlight"><pre>variable x equal 100
variable y equal 25
lattice hex 0.8442
region box block 0 $x 0 $y -0.5 0.5
create_box 1 box
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>variable xx equal 0.0
variable yy equal 0.0
variable v equal "(0.2*v_y*ylat * cos(v_xx/xlat * 2.0*PI*4.0/v_x) + 0.5*v_y*ylat - v_yy) > 0.0"
create_atoms 1 box var v set x xx set y yy
</pre></div>
</div>
-<a data-lightbox="group-33c0efcb-d94d-4219-a127-595ee2853510"
+<a data-lightbox="group-ab24e3be-a47a-407d-af33-4b01db76c6a1"
href="_images/sinusoid.jpg"
class=""
title=""
data-title=""
><img src="_images/sinusoid.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>The <em>rotate</em> keyword can be used with the <em>single</em> style, when adding
a single molecule to specify the orientation at which the molecule is
inserted. The axis of rotation is determined by the rotation vector
(Rx,Ry,Rz) that goes through the insertion point. The specified
<em>theta</em> determines the angle of rotation around that axis. Note that
the direction of rotation for the atoms around the rotation axis is
consistent with the right-hand rule: if your right-hand’s thumb points
along <em>R</em>, then your fingers wrap around the axis in the direction of
rotation.</p>
<p>The <em>units</em> keyword determines the meaning of the distance units used
to specify the coordinates of the one particle created by the <em>single</em>
style. A <em>box</em> value selects standard distance units as defined by
the <a class="reference internal" href="units.html"><em>units</em></a> command, e.g. Angstroms for units = real or
metal. A <em>lattice</em> value means the distance units are in lattice
spacings.</p>
<hr class="docutils" />
<p>Atom IDs are assigned to created atoms in the following way. The
collection of created atoms are assigned consecutive IDs that start
immediately following the largest atom ID existing before the
create_atoms command was invoked. When a simulation is performed on
different numbers of processors, there is no guarantee a particular
created atom will be assigned the same ID. If molecules are being
created, molecule IDs are assigned to created molecules in a similar
fashion.</p>
<p>Aside from their ID, atom type, and xyz position, other properties of
created atoms are set to default values, depending on which quantities
are defined by the chosen <a class="reference internal" href="atom_style.html"><em>atom style</em></a>. See the <a class="reference internal" href="atom_style.html"><em>atom style</em></a> command for more details. See the
<a class="reference internal" href="set.html"><em>set</em></a> and <a class="reference internal" href="velocity.html"><em>velocity</em></a> commands for info on how
to change these values.</p>
<ul class="simple">
<li>charge = 0.0</li>
<li>dipole moment magnitude = 0.0</li>
<li>diameter = 1.0</li>
<li>shape = 0.0 0.0 0.0</li>
<li>density = 1.0</li>
<li>volume = 1.0</li>
<li>velocity = 0.0 0.0 0.0</li>
<li>angular velocity = 0.0 0.0 0.0</li>
<li>angular momentum = 0.0 0.0 0.0</li>
<li>quaternion = (1,0,0,0)</li>
<li>bonds, angles, dihedrals, impropers = none</li>
</ul>
<p>If molecules are being created, these defaults can be overridden by
values specified in the file read by the <a class="reference internal" href="molecule.html"><em>molecule</em></a>
command. E.g. the file typically defines bonds (angles,etc) between
atoms in the molecule, and can optionally define charges on each atom.</p>
<p>Note that the <em>sphere</em> atom style sets the default particle diameter
to 1.0 as well as the density. This means the mass for the particle
is not 1.0, but is PI/6 * diameter^3 = 0.5236.</p>
<p>Note that the <em>ellipsoid</em> atom style sets the default particle shape
to (0.0 0.0 0.0) and the density to 1.0 which means it is a point
particle, not an ellipsoid, and has a mass of 1.0.</p>
<p>Note that the <em>peri</em> style sets the default volume and density to 1.0
and thus also set the mass for the particle to 1.0.</p>
<p>The <a class="reference internal" href="set.html"><em>set</em></a> command can be used to override many of these
default settings.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>An <a class="reference internal" href="atom_style.html"><em>atom_style</em></a> must be previously defined to use this
command.</p>
<p>A rotation vector specified for a single molecule must be in
the z-direction for a 2d model.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="lattice.html"><em>lattice</em></a>, <a class="reference internal" href="region.html"><em>region</em></a>, <a class="reference internal" href="create_box.html"><em>create_box</em></a>,
<a class="reference internal" href="read_data.html"><em>read_data</em></a>, <a class="reference internal" href="read_restart.html"><em>read_restart</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The default for the <em>basis</em> keyword is that all created atoms are
assigned the argument <em>type</em> as their atom type (when single atoms are
being created). The other defaults are <em>remap</em> = no, <em>rotate</em> =
random, and <em>units</em> = lattice.</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/dump_image.html b/doc/dump_image.html
index 2fef87e97..a97bbdd72 100644
--- a/doc/dump_image.html
+++ b/doc/dump_image.html
@@ -1,709 +1,709 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>dump image command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>dump image command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="dump-image-command">
<span id="index-0"></span><h1>dump image command<a class="headerlink" href="#dump-image-command" title="Permalink to this headline">¶</a></h1>
</div>
<div class="section" id="dump-movie-command">
<h1>dump movie command<a class="headerlink" href="#dump-movie-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>dump ID group-ID style N file color diameter keyword value ...
</pre></div>
</div>
<ul class="simple">
<li>ID = user-assigned name for the dump</li>
<li>group-ID = ID of the group of atoms to be imaged</li>
<li>style = <em>image</em> or <em>movie</em> = style of dump command (other styles <em>atom</em> or <em>cfg</em> or <em>dcd</em> or <em>xtc</em> or <em>xyz</em> or <em>local</em> or <em>custom</em> are discussed on the <a class="reference internal" href="dump.html"><em>dump</em></a> doc page)</li>
<li>N = dump every this many timesteps</li>
<li>file = name of file to write image to</li>
<li>color = atom attribute that determines color of each atom</li>
<li>diameter = atom attribute that determines size of each atom</li>
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>adiam</em> or <em>atom</em> or <em>bond</em> or <em>size</em> or <em>view</em> or <em>center</em> or <em>up</em> or <em>zoom</em> or <em>persp</em> or <em>box</em> or <em>axes</em> or <em>subbox</em> or <em>shiny</em> or <em>ssao</em></li>
</ul>
<pre class="literal-block">
<em>adiam</em> value = number = numeric value for atom diameter (distance units)
<em>atom</em> = yes/no = do or do not draw atoms
<em>bond</em> values = color width = color and width of bonds
color = <em>atom</em> or <em>type</em> or <em>none</em>
width = number or <em>atom</em> or <em>type</em> or <em>none</em>
number = numeric value for bond width (distance units)
<em>size</em> values = width height = size of images
width = width of image in # of pixels
height = height of image in # of pixels
<em>view</em> values = theta phi = view of simulation box
theta = view angle from +z axis (degrees)
phi = azimuthal view angle (degrees)
theta or phi can be a variable (see below)
<em>center</em> values = flag Cx Cy Cz = center point of image
flag = "s" for static, "d" for dynamic
Cx,Cy,Cz = center point of image as fraction of box dimension (0.5 = center of box)
Cx,Cy,Cz can be variables (see below)
<em>up</em> values = Ux Uy Uz = direction that is "up" in image
Ux,Uy,Uz = components of up vector
Ux,Uy,Uz can be variables (see below)
<em>zoom</em> value = zfactor = size that simulation box appears in image
zfactor = scale image size by factor > 1 to enlarge, factor < 1 to shrink
zfactor can be a variable (see below)
<em>persp</em> value = pfactor = amount of "perspective" in image
pfactor = amount of perspective (0 = none, < 1 = some, > 1 = highly skewed)
pfactor can be a variable (see below)
<em>box</em> values = yes/no diam = draw outline of simulation box
yes/no = do or do not draw simulation box lines
diam = diameter of box lines as fraction of shortest box length
<em>axes</em> values = yes/no length diam = draw xyz axes
yes/no = do or do not draw xyz axes lines next to simulation box
length = length of axes lines as fraction of respective box lengths
diam = diameter of axes lines as fraction of shortest box length
<em>subbox</em> values = yes/no diam = draw outline of processor sub-domains
yes/no = do or do not draw sub-domain lines
diam = diameter of sub-domain lines as fraction of shortest box length
<em>shiny</em> value = sfactor = shinyness of spheres and cylinders
sfactor = shinyness of spheres and cylinders from 0.0 to 1.0
<em>ssao</em> value = yes/no seed dfactor = SSAO depth shading
yes/no = turn depth shading on/off
seed = random # seed (positive integer)
dfactor = strength of shading from 0.0 to 1.0
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>dump d0 all image 100 dump.*.jpg type type
dump d1 mobile image 500 snap.*.png element element ssao yes 4539 0.6
dump d2 all image 200 img-*.ppm type type zoom 2.5 adiam 1.5 size 1280 720
dump m0 all movie 1000 movie.mpg type type size 640 480
dump m1 all movie 1000 movie.avi type type size 640 480
dump m2 all movie 100 movie.m4v type type zoom 1.8 adiam v_value size 1280 720
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Dump a high-quality rendered image of the atom configuration every N
timesteps and save the images either as a sequence of JPEG or PNG or
PPM files, or as a single movie file. The options for this command as
well as the <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command control what is
included in the image or movie and how it appears. A series of such
images can easily be manually converted into an animated movie of your
simulation or the process can be automated without writing the
intermediate files using the dump movie style; see further details
below. Other dump styles store snapshots of numerical data asociated
with atoms in various formats, as discussed on the <a class="reference internal" href="dump.html"><em>dump</em></a>
doc page.</p>
<p>Note that a set of images or a movie can be made after a simulation
has been run, using the <a class="reference internal" href="rerun.html"><em>rerun</em></a> command to read snapshots
from an existing dump file, and using these dump commands in the rerun
script to generate the images/movie.</p>
<p>Here are two sample images, rendered as 1024x1024 JPEG files. Click
to see the full-size images:</p>
-<DIV ALIGN=center><a data-lightbox="group-a8d1ce4b-2f8a-471c-84fd-5e80856b9d57"
+<DIV ALIGN=center><a data-lightbox="group-51fa2cc7-f548-4cad-8416-050b8c350eb6"
href="_images/dump1.jpg"
class=""
title=""
data-title=""
><img src="_images/dump1.jpg"
class=""
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-0e6fb646-7cf3-4c1b-9ebb-e93f758d7891"
+ </a><a data-lightbox="group-7df8ebec-fdc6-4e0f-bd1a-769bc9e5ffeb"
href="_images/dump2.jpg"
class=""
title=""
data-title=""
><img src="_images/dump2.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a></DIV><p>Only atoms in the specified group are rendered in the image. The
<a class="reference internal" href="dump_modify.html"><em>dump_modify region and thresh</em></a> commands can also
alter what atoms are included in the image.
The filename suffix determines whether a JPEG, PNG, or PPM file is
created with the <em>image</em> dump style. If the suffix is ”.jpg” or
”.jpeg”, then a JPEG format file is created, if the suffix is ”.png”,
then a PNG format is created, else a PPM (aka NETPBM) format file is
created. The JPEG and PNG files are binary; PPM has a text mode
header followed by binary data. JPEG images have lossy compression;
PNG has lossless compression; and PPM files are uncompressed but can
be compressed with gzip, if LAMMPS has been compiled with
-DLAMMPS_GZIP and a ”.gz” suffix is used.</p>
<p>Similarly, the format of the resulting movie is chosen with the
<em>movie</em> dump style. This is handled by the underlying FFmpeg converter
and thus details have to be looked up in the FFmpeg documentation.
Typical examples are: .avi, .mpg, .m4v, .mp4, .mkv, .flv, .mov, .gif
Additional settings of the movie compression like bitrate and
framerate can be set using the <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command.</p>
<p>To write out JPEG and PNG format files, you must build LAMMPS with
support for the corresponding JPEG or PNG library. To convert images
into movies, LAMMPS has to be compiled with the -DLAMMPS_FFMPEG
flag. See <a class="reference internal" href="Section_start.html#start-2-4"><span>this section</span></a> of the manual
for instructions on how to do this.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Because periodic boundary conditions are enforced only
on timesteps when neighbor lists are rebuilt, the coordinates of an
atom in the image may be slightly outside the simulation box.</p>
</div>
<hr class="docutils" />
<p>Dumps are performed on timesteps that are a multiple of N (including
timestep 0) and on the last timestep of a minimization if the
minimization converges. Note that this means a dump will not be
performed on the initial timestep after the dump command is invoked,
if the current timestep is not a multiple of N. This behavior can be
changed via the <a class="reference internal" href="dump_modify.html"><em>dump_modify first</em></a> command, which
can be useful if the dump command is invoked after a minimization
ended on an arbitrary timestep. N can be changed between runs by
using the <a class="reference internal" href="dump_modify.html"><em>dump_modify every</em></a> command.</p>
<p>Dump <em>image</em> filenames must contain a wildcard character “*”, so that
one image file per snapshot is written. The “*” character is replaced
with the timestep value. For example, tmp.dump.*.jpg becomes
tmp.dump.0.jpg, tmp.dump.10000.jpg, tmp.dump.20000.jpg, etc. Note
that the <a class="reference internal" href="dump_modify.html"><em>dump_modify pad</em></a> command can be used to
insure all timestep numbers are the same length (e.g. 00010), which
can make it easier to convert a series of images into a movie in the
correct ordering.</p>
<p>Dump <em>movie</em> filenames on the other hand, must not have any wildcard
character since only one file combining all images into a single
movie will be written by the movie encoder.</p>
<hr class="docutils" />
<p>The <em>color</em> and <em>diameter</em> settings determine the color and size of
atoms rendered in the image. They can be any atom attribute defined
for the <a class="reference internal" href="dump.html"><em>dump custom</em></a> command, including <em>type</em> and
<em>element</em>. This includes per-atom quantities calculated by a
<a class="reference internal" href="compute.html"><em>compute</em></a>, <a class="reference internal" href="fix.html"><em>fix</em></a>, or <a class="reference internal" href="variable.html"><em>variable</em></a>,
which are prefixed by “<a href="#id9"><span class="problematic" id="id10">c_</span></a>”, “<a href="#id11"><span class="problematic" id="id12">f_</span></a>”, or “<a href="#id13"><span class="problematic" id="id14">v_</span></a>” respectively. Note that the
<em>diameter</em> setting can be overridden with a numeric value by the
optional <em>adiam</em> keyword, in which case you can specify the <em>diameter</em>
setting with any valid atom attribute.</p>
<p>If <em>type</em> is specified for the <em>color</em> setting, then the color of each
atom is determined by its atom type. By default the mapping of types
to colors is as follows:</p>
<ul class="simple">
<li>type 1 = red</li>
<li>type 2 = green</li>
<li>type 3 = blue</li>
<li>type 4 = yellow</li>
<li>type 5 = aqua</li>
<li>type 6 = cyan</li>
</ul>
<p>and repeats itself for types > 6. This mapping can be changed by the
<a class="reference internal" href="dump_modify.html"><em>dump_modify acolor</em></a> command.</p>
<p>If <em>type</em> is specified for the <em>diameter</em> setting then the diameter of
each atom is determined by its atom type. By default all types have
diameter 1.0. This mapping can be changed by the <a class="reference internal" href="dump_modify.html"><em>dump_modify adiam</em></a> command.</p>
<p>If <em>element</em> is specified for the <em>color</em> and/or <em>diameter</em> setting,
then the color and/or diameter of each atom is determined by which
element it is, which in turn is specified by the element-to-type
mapping specified by the “dump_modify element” command. By default
every atom type is C (carbon). Every element has a color and diameter
associated with it, which is the same as the colors and sizes used by
the <a class="reference external" href="http://mt.seas.upenn.edu/Archive/Graphics/A">AtomEye</a> visualization package.</p>
<p>If other atom attributes are used for the <em>color</em> or <em>diameter</em>
settings, they are interpreted in the following way.</p>
<p>If “vx”, for example, is used as the <em>color</em> setting, then the color
of the atom will depend on the x-component of its velocity. The
association of a per-atom value with a specific color is determined by
a “color map”, which can be specified via the
<a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command. The basic idea is that the
atom-attribute will be within a range of values, and every value
within the range is mapped to a specific color. Depending on how the
color map is defined, that mapping can take place via interpolation so
that a value of -3.2 is halfway between “red” and “blue”, or
discretely so that the value of -3.2 is “orange”.</p>
<p>If “vx”, for example, is used as the <em>diameter</em> setting, then the atom
will be rendered using the x-component of its velocity as the
diameter. If the per-atom value <= 0.0, them the atom will not be
drawn. Note that finite-size spherical particles, as defined by
<a class="reference internal" href="atom_style.html"><em>atom_style sphere</em></a> define a per-particle radius or
diameter, which can be used as the <em>diameter</em> setting.</p>
<hr class="docutils" />
<p>The various kewords listed above control how the image is rendered.
As listed below, all of the keywords have defaults, most of which you
will likely not need to change. The <a class="reference internal" href="dump_modify.html"><em>dump modify</em></a>
also has options specific to the dump image style, particularly for
assigning colors to atoms, bonds, and other image features.</p>
<hr class="docutils" />
<p>The <em>adiam</em> keyword allows you to override the <em>diameter</em> setting to a
per-atom attribute with a specified numeric value. All atoms will be
drawn with that diameter, e.g. 1.5, which is in whatever distance
<a class="reference internal" href="units.html"><em>units</em></a> the input script defines, e.g. Angstroms.</p>
<p>The <em>atom</em> keyword allow you to turn off the drawing of all atoms,
if the specified value is <em>no</em>.</p>
<p>The <em>bond</em> keyword allows to you to alter how bonds are drawn. A bond
is only drawn if both atoms in the bond are being drawn due to being
in the specified group and due to other selection criteria
(e.g. region, threshhold settings of the
<a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a> command). By default, bonds are drawn
if they are defined in the input data file as read by the
<a class="reference internal" href="read_data.html"><em>read_data</em></a> command. Using <em>none</em> for both the bond
<em>color</em> and <em>width</em> value will turn off the drawing of all bonds.</p>
<p>If <em>atom</em> is specified for the bond <em>color</em> value, then each bond is
drawn in 2 halves, with the color of each half being the color of the
atom at that end of the bond.</p>
<p>If <em>type</em> is specified for the <em>color</em> value, then the color of each
bond is determined by its bond type. By default the mapping of bond
types to colors is as follows:</p>
<ul class="simple">
<li>type 1 = red</li>
<li>type 2 = green</li>
<li>type 3 = blue</li>
<li>type 4 = yellow</li>
<li>type 5 = aqua</li>
<li>type 6 = cyan</li>
</ul>
<p>and repeats itself for bond types > 6. This mapping can be changed by
the <a class="reference internal" href="dump_modify.html"><em>dump_modify bcolor</em></a> command.</p>
<p>The bond <em>width</em> value can be a numeric value or <em>atom</em> or <em>type</em> (or
<em>none</em> as indicated above).</p>
<p>If a numeric value is specified, then all bonds will be drawn as
cylinders with that diameter, e.g. 1.0, which is in whatever distance
<a class="reference internal" href="units.html"><em>units</em></a> the input script defines, e.g. Angstroms.</p>
<p>If <em>atom</em> is specified for the <em>width</em> value, then each bond
will be drawn with a width corresponding to the minimum diameter
of the 2 atoms in the bond.</p>
<p>If <em>type</em> is specified for the <em>width</em> value then the diameter of each
bond is determined by its bond type. By default all types have
diameter 0.5. This mapping can be changed by the <a class="reference internal" href="dump_modify.html"><em>dump_modify bdiam</em></a> command.</p>
<hr class="docutils" />
<p>The <em>size</em> keyword sets the width and height of the created images,
i.e. the number of pixels in each direction.</p>
<hr class="docutils" />
<p>The <em>view</em>, <em>center</em>, <em>up</em>, <em>zoom</em>, and <em>persp</em> values determine how
3d simulation space is mapped to the 2d plane of the image. Basically
they control how the simulation box appears in the image.</p>
<p>All of the <em>view</em>, <em>center</em>, <em>up</em>, <em>zoom</em>, and <em>persp</em> values can be
specified as numeric quantities, whose meaning is explained below.
Any of them can also be specified as an <a class="reference internal" href="variable.html"><em>equal-style variable</em></a>, by using v_name as the value, where “name” is
the variable name. In this case the variable will be evaluated on the
timestep each image is created to create a new value. If the
equal-style variable is time-dependent, this is a means of changing
the way the simulation box appears from image to image, effectively
doing a pan or fly-by view of your simulation.</p>
<p>The <em>view</em> keyword determines the viewpoint from which the simulation
box is viewed, looking towards the <em>center</em> point. The <em>theta</em> value
is the vertical angle from the +z axis, and must be an angle from 0 to
180 degrees. The <em>phi</em> value is an azimuthal angle around the z axis
and can be positive or negative. A value of 0.0 is a view along the
+x axis, towards the <em>center</em> point. If <em>theta</em> or <em>phi</em> are
specified via variables, then the variable values should be in
degrees.</p>
<p>The <em>center</em> keyword determines the point in simulation space that
will be at the center of the image. <em>Cx</em>, <em>Cy</em>, and <em>Cz</em> are
speficied as fractions of the box dimensions, so that (0.5,0.5,0.5) is
the center of the simulation box. These values do not have to be
between 0.0 and 1.0, if you want the simulation box to be offset from
the center of the image. Note, however, that if you choose strange
values for <em>Cx</em>, <em>Cy</em>, or <em>Cz</em> you may get a blank image. Internally,
<em>Cx</em>, <em>Cy</em>, and <em>Cz</em> are converted into a point in simulation space.
If <em>flag</em> is set to “s” for static, then this conversion is done once,
at the time the dump command is issued. If <em>flag</em> is set to “d” for
dynamic then the conversion is performed every time a new image is
created. If the box size or shape is changing, this will adjust the
center point in simulation space.</p>
<p>The <em>up</em> keyword determines what direction in simulation space will be
“up” in the image. Internally it is stored as a vector that is in the
plane perpendicular to the view vector implied by the <em>theta</em> and
<em>pni</em> values, and which is also in the plane defined by the view
vector and user-specified up vector. Thus this internal vector is
computed from the user-specified <em>up</em> vector as</p>
<div class="highlight-python"><div class="highlight"><pre>up_internal = view cross (up cross view)
</pre></div>
</div>
<p>This means the only restriction on the specified <em>up</em> vector is that
it cannot be parallel to the <em>view</em> vector, implied by the <em>theta</em> and
<em>phi</em> values.</p>
<p>The <em>zoom</em> keyword scales the size of the simulation box as it appears
in the image. The default <em>zfactor</em> value of 1 should display an
image mostly filled by the atoms in the simulation box. A <em>zfactor</em> >
1 will make the simulation box larger; a <em>zfactor</em> < 1 will make it
smaller. <em>Zfactor</em> must be a value > 0.0.</p>
<p>The <em>persp</em> keyword determines how much depth perspective is present
in the image. Depth perspective makes lines that are parallel in
simulation space appear non-parallel in the image. A <em>pfactor</em> value
of 0.0 means that parallel lines will meet at infininty (1.0/pfactor),
which is an orthographic rendering with no persepctive. A <em>pfactor</em>
value between 0.0 and 1.0 will introduce more perspective. A <em>pfactor</em>
value > 1 will create a highly skewed image with a large amount of
perspective.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The <em>persp</em> keyword is not yet supported as an option.</p>
</div>
<hr class="docutils" />
<p>The <em>box</em> keyword determines if and how the simulation box boundaries
are rendered as thin cylinders in the image. If <em>no</em> is set, then the
box boundaries are not drawn and the <em>diam</em> setting is ignored. If
<em>yes</em> is set, the 12 edges of the box are drawn, with a diameter that
is a fraction of the shortest box length in x,y,z (for 3d) or x,y (for
2d). The color of the box boundaries can be set with the <a class="reference internal" href="dump_modify.html"><em>dump_modify boxcolor</em></a> command.</p>
<p>The <em>axes</em> keyword determines if and how the coordinate axes are
rendered as thin cylinders in the image. If <em>no</em> is set, then the
axes are not drawn and the <em>length</em> and <em>diam</em> settings are ignored.
If <em>yes</em> is set, 3 thin cylinders are drawn to represent the x,y,z
axes in colors red,green,blue. The origin of these cylinders will be
offset from the lower left corner of the box by 10%. The <em>length</em>
setting determines how long the cylinders will be as a fraction of the
respective box lengths. The <em>diam</em> setting determines their thickness
as a fraction of the shortest box length in x,y,z (for 3d) or x,y (for
2d).</p>
<p>The <em>subbox</em> keyword determines if and how processor sub-domain
boundaries are rendered as thin cylinders in the image. If <em>no</em> is
set (default), then the sub-domain boundaries are not drawn and the
<em>diam</em> setting is ignored. If <em>yes</em> is set, the 12 edges of each
processor sub-domain are drawn, with a diameter that is a fraction of
the shortest box length in x,y,z (for 3d) or x,y (for 2d). The color
of the sub-domain boundaries can be set with the <a class="reference internal" href="dump_modify.html"><em>dump_modify boxcolor</em></a> command.</p>
<hr class="docutils" />
<p>The <em>shiny</em> keyword determines how shiny the objects rendered in the
image will appear. The <em>sfactor</em> value must be a value 0.0 <=
<em>sfactor</em> <= 1.0, where <em>sfactor</em> = 1 is a highly reflective surface
and <em>sfactor</em> = 0 is a rough non-shiny surface.</p>
<p>The <em>ssao</em> keyword turns on/off a screen space ambient occlusion
(SSAO) model for depth shading. If <em>yes</em> is set, then atoms further
away from the viewer are darkened via a randomized process, which is
perceived as depth. The calculation of this effect can increase the
cost of computing the image by roughly 2x. The strength of the effect
can be scaled by the <em>dfactor</em> parameter. If <em>no</em> is set, no depth
shading is performed.</p>
<hr class="docutils" />
<p>A series of JPEG, PNG, or PPM images can be converted into a movie
file and then played as a movie using commonly available tools. Using
dump style <em>movie</em> automates this step and avoids the intermediate
step of writing (many) image snapshot file. But LAMMPS has to be
compiled with -DLAMMPS_FFMPEG and an FFmpeg executable have to be
installed.</p>
<p>To manually convert JPEG, PNG or PPM files into an animated GIF or
MPEG or other movie file you can use:</p>
<ul class="simple">
<li><ol class="first loweralpha">
<li>Use the ImageMagick convert program.</li>
</ol>
</li>
</ul>
<div class="highlight-python"><div class="highlight"><pre>% convert *.jpg foo.gif
% convert -loop 1 *.ppm foo.mpg
</pre></div>
</div>
<p>Animated GIF files from ImageMagick are unoptimized. You can use a
program like gifsicle to optimize and massively shrink them.
MPEG files created by ImageMagick are in MPEG-1 format with rather
inefficient compression and low quality.</p>
<ul class="simple">
<li><ol class="first loweralpha" start="2">
<li>Use QuickTime.</li>
</ol>
</li>
</ul>
<p>Select “Open Image Sequence” under the File menu Load the images into
QuickTime to animate them Select “Export” under the File menu Save the
movie as a QuickTime movie (<a href="#id7"><span class="problematic" id="id8">*</span></a>.mov) or in another format. QuickTime
can generate very high quality and efficiently compressed movie
files. Some of the supported formats require to buy a license and some
are not readable on all platforms until specific runtime libraries are
installed.</p>
<ul class="simple">
<li><ol class="first loweralpha" start="3">
<li>Use FFmpeg</li>
</ol>
</li>
</ul>
<p>FFmpeg is a command line tool that is available on many platforms and
allows extremely flexible encoding and decoding of movies.</p>
<div class="highlight-python"><div class="highlight"><pre>cat snap.*.jpg | ffmpeg -y -f image2pipe -c:v mjpeg -i - -b:v 2000k movie.m4v
cat snap.*.ppm | ffmpeg -y -f image2pipe -c:v ppm -i - -b:v 2400k movie.avi
</pre></div>
</div>
<p>Frontends for FFmpeg exist for multiple platforms. For more
information see the <a class="reference external" href="http://www.ffmpeg.org/">FFmpeg homepage</a></p>
<hr class="docutils" />
<p>Play the movie:</p>
<ul class="simple">
<li><ol class="first loweralpha">
<li>Use your browser to view an animated GIF movie.</li>
</ol>
</li>
</ul>
<p>Select “Open File” under the File menu
Load the animated GIF file</p>
<ul class="simple">
<li>b) Use the freely available mplayer or ffplay tool to view a
movie. Both are available for multiple OSes and support a large
variety of file formats and decoders.</li>
</ul>
<div class="highlight-python"><div class="highlight"><pre>% mplayer foo.mpg
% ffplay bar.avi
</pre></div>
</div>
<ul class="simple">
<li>c) Use the <a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza.html">Pizza.py</a>
<a class="reference external" href="http://www.sandia.gov/~sjplimp/pizza/doc/animate.html">animate tool</a>,
which works directly on a series of image files.</li>
</ul>
<div class="highlight-python"><div class="highlight"><pre><span class="n">a</span> <span class="o">=</span> <span class="n">animate</span><span class="p">(</span><span class="s">"foo*.jpg"</span><span class="p">)</span>
</pre></div>
</div>
<ul class="simple">
<li>d) QuickTime and other Windows- or MacOS-based media players can
obviously play movie files directly. Similarly for corresponding tools
bundled with Linux desktop environments. However, due to licensing
issues with some file formats, the formats may require installing
additional libraries, purchasing a license, or may not be
supported.</li>
</ul>
<hr class="docutils" />
<p>See <a class="reference internal" href="Section_modify.html"><em>Section_modify</em></a> of the manual for information
on how to add new compute and fix styles to LAMMPS to calculate
per-atom quantities which could then be output into dump files.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>To write JPEG images, you must use the -DLAMMPS_JPEG switch when
building LAMMPS and link with a JPEG library. To write PNG images, you
must use the -DLAMMPS_PNG switch when building LAMMPS and link with a
PNG library.</p>
<p>To write <em>movie</em> dumps, you must use the -DLAMMPS_FFMPEG switch when
building LAMMPS and have the FFmpeg executable available on the
machine where LAMMPS is being run. Typically it’s name is lowercase,
i.e. ffmpeg.</p>
<p>See the <a class="reference internal" href="Section_start.html#start-2-4"><span>Making LAMMPS</span></a> section of the
documentation for details on how to compile with optional switches.</p>
<p>Note that since FFmpeg is run as an external program via a pipe,
LAMMPS has limited control over its execution and no knowledge about
errors and warnings printed by it. Those warnings and error messages
will be printed to the screen only. Due to the way image data is
communicated to FFmpeg, it will often print the message</p>
<div class="highlight-python"><div class="highlight"><pre>pipe:: Input/output error
</pre></div>
</div>
<p>which can be safely ignored. Other warnings
and errors have to be addressed according to the FFmpeg documentation.
One known issue is that certain movie file formats (e.g. MPEG level 1
and 2 format streams) have video bandwith limits that can be crossed
when rendering too large of image sizes. Typical warnings look like
this:</p>
<div class="highlight-python"><div class="highlight"><pre>[mpeg @ 0x98b5e0] packet too large, ignoring buffer limits to mux it
[mpeg @ 0x98b5e0] buffer underflow st=0 bufi=281407 size=285018
[mpeg @ 0x98b5e0] buffer underflow st=0 bufi=283448 size=285018
</pre></div>
</div>
<p>In this case it is recommended to either reduce the size of the image
or encode in a different format that is also supported by your copy of
FFmpeg, and which does not have this limitation (e.g. .avi, .mkv,
mp4).</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="dump.html"><em>dump</em></a>, <a class="reference internal" href="dump_modify.html"><em>dump_modify</em></a>, <a class="reference internal" href="undump.html"><em>undump</em></a></p>
</div>
<div class="section" id="default">
<h2>Default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h2>
<p>The defaults for the keywords are as follows:</p>
<ul class="simple">
<li>adiam = not specified (use diameter setting)</li>
<li>atom = yes</li>
<li>bond = none none (if no bonds in system)</li>
<li>bond = atom 0.5 (if bonds in system)</li>
<li>size = 512 512</li>
<li>view = 60 30 (for 3d)</li>
<li>view = 0 0 (for 2d)</li>
<li>center = s 0.5 0.5 0.5</li>
<li>up = 0 0 1 (for 3d)</li>
<li>up = 0 1 0 (for 2d)</li>
<li>zoom = 1.0</li>
<li>persp = 0.0</li>
<li>box = yes 0.02</li>
<li>axes = no 0.0 0.0</li>
<li>subbox no 0.0</li>
<li>shiny = 1.0</li>
<li>ssao = no</li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/fix_balance.html b/doc/fix_balance.html
index b567d192c..3036f1219 100644
--- a/doc/fix_balance.html
+++ b/doc/fix_balance.html
@@ -1,533 +1,533 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>fix balance command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>fix balance command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="fix-balance-command">
<span id="index-0"></span><h1>fix balance command<a class="headerlink" href="#fix-balance-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>fix ID group-ID balance Nfreq thresh style args keyword value ...
</pre></div>
</div>
<ul class="simple">
<li>ID, group-ID are documented in <a class="reference internal" href="fix.html"><em>fix</em></a> command</li>
<li>balance = style name of this fix command</li>
<li>Nfreq = perform dynamic load balancing every this many steps</li>
<li>thresh = imbalance threshhold that must be exceeded to perform a re-balance</li>
<li>style = <em>shift</em> or <em>rcb</em></li>
</ul>
<div class="highlight-python"><div class="highlight"><pre>shift args = dimstr Niter stopthresh
dimstr = sequence of letters containing "x" or "y" or "z", each not more than once
Niter = # of times to iterate within each dimension of dimstr sequence
stopthresh = stop balancing when this imbalance threshhold is reached
rcb args = none
</pre></div>
</div>
<ul class="simple">
<li>zero or more keyword/value pairs may be appended</li>
<li>keyword = <em>out</em></li>
</ul>
<pre class="literal-block">
<em>out</em> value = filename
filename = write each processor's sub-domain to a file, at each re-balancing
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>fix 2 all balance 1000 1.05 shift x 10 1.05
fix 2 all balance 100 0.9 shift xy 20 1.1 out tmp.balance
fix 2 all balance 1000 1.1 rcb
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This command adjusts the size and shape of processor sub-domains
within the simulation box, to attempt to balance the number of
particles and thus the computational cost (load) evenly across
processors. The load balancing is “dynamic” in the sense that
rebalancing is performed periodically during the simulation. To
perform “static” balancing, before or between runs, see the
<a class="reference internal" href="balance.html"><em>balance</em></a> command.</p>
<p>Load-balancing is typically only useful if the particles in the
simulation box have a spatially-varying density distribution. E.g. a
model of a vapor/liquid interface, or a solid with an irregular-shaped
geometry containing void regions. In this case, the LAMMPS default of
dividing the simulation box volume into a regular-spaced grid of 3d
bricks, with one equal-volume sub-domain per processor, may assign
very different numbers of particles per processor. This can lead to
poor performance when the simulation is run in parallel.</p>
<p>Note that the <a class="reference internal" href="processors.html"><em>processors</em></a> command allows some control
over how the box volume is split across processors. Specifically, for
a Px by Py by Pz grid of processors, it allows choice of Px, Py, and
Pz, subject to the constraint that Px * Py * Pz = P, the total number
of processors. This is sufficient to achieve good load-balance for
some problems on some processor counts. However, all the processor
sub-domains will still have the same shape and same volume.</p>
<p>On a particular timestep, a load-balancing operation is only performed
if the current “imbalance factor” in particles owned by each processor
exceeds the specified <em>thresh</em> parameter. The imbalance factor is
defined as the maximum number of particles owned by any processor,
divided by the average number of particles per processor. Thus an
imbalance factor of 1.0 is perfect balance.</p>
<p>As an example, for 10000 particles running on 10 processors, if the
most heavily loaded processor has 1200 particles, then the factor is
1.2, meaning there is a 20% imbalance. Note that re-balances can be
forced even if the current balance is perfect (1.0) be specifying a
<em>thresh</em> < 1.0.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This command attempts to minimize the imbalance
factor, as defined above. But depending on the method a perfect
balance (1.0) may not be achieved. For example, “grid” methods
(defined below) that create a logical 3d grid cannot achieve perfect
balance for many irregular distributions of particles. Likewise, if a
portion of the system is a perfect lattice, e.g. the initial system is
generated by the <a class="reference internal" href="create_atoms.html"><em>create_atoms</em></a> command, then “grid”
methods may be unable to achieve exact balance. This is because
entire lattice planes will be owned or not owned by a single
processor.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The imbalance factor is also an estimate of the
maximum speed-up you can hope to achieve by running a perfectly
balanced simulation versus an imbalanced one. In the example above,
the 10000 particle simulation could run up to 20% faster if it were
perfectly balanced, versus when imbalanced. However, computational
cost is not strictly proportional to particle count, and changing the
relative size and shape of processor sub-domains may lead to
additional computational and communication overheads, e.g. in the PPPM
solver used via the <a class="reference internal" href="kspace_style.html"><em>kspace_style</em></a> command. Thus
you should benchmark the run times of a simulation before and after
balancing.</p>
</div>
<hr class="docutils" />
<p>The method used to perform a load balance is specified by one of the
listed styles, which are described in detail below. There are 2 kinds
of styles.</p>
<p>The <em>shift</em> style is a “grid” method which produces a logical 3d grid
of processors. It operates by changing the cutting planes (or lines)
between processors in 3d (or 2d), to adjust the volume (area in 2d)
assigned to each processor, as in the following 2d diagram where
processor sub-domains are shown and atoms are colored by the processor
that owns them. The leftmost diagram is the default partitioning of
the simulation box across processors (one sub-box for each of 16
processors); the middle diagram is after a “grid” method has been
applied.</p>
-<a data-lightbox="group-3c3a3ca4-30c8-41c7-aeb3-4f9488855663"
+<a data-lightbox="group-be62a711-896a-43e3-9c19-a5af8154cac4"
href="_images/balance_uniform.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_uniform.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-9caab12f-e8e4-4609-a2ff-f142dd4226d3"
+ </a><a data-lightbox="group-17ee0c91-2ef3-4cf9-8b74-e6df1df7708e"
href="_images/balance_nonuniform.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_nonuniform.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-30de4a9e-ee03-4752-8522-d6699eb5af54"
+ </a><a data-lightbox="group-b94b0d56-eb6d-4f6a-983a-eeca125d3082"
href="_images/balance_rcb.jpg"
class=""
title=""
data-title=""
><img src="_images/balance_rcb.jpg"
class="align-center"
width="25%"
height="auto"
alt=""/>
</a><p>The <em>rcb</em> style is a “tiling” method which does not produce a logical
3d grid of processors. Rather it tiles the simulation domain with
rectangular sub-boxes of varying size and shape in an irregular
fashion so as to have equal numbers of particles in each sub-box, as
in the rightmost diagram above.</p>
<p>The “grid” methods can be used with either of the
<a class="reference internal" href="comm_style.html"><em>comm_style</em></a> command options, <em>brick</em> or <em>tiled</em>. The
“tiling” methods can only be used with <a class="reference internal" href="comm_style.html"><em>comm_style tiled</em></a>.</p>
<p>When a “grid” method is specified, the current domain partitioning can
be either a logical 3d grid or a tiled partitioning. In the former
case, the current logical 3d grid is used as a starting point and
changes are made to improve the imbalance factor. In the latter case,
the tiled partitioning is discarded and a logical 3d grid is created
with uniform spacing in all dimensions. This is the starting point
for the balancing operation.</p>
<p>When a “tiling” method is specified, the current domain partitioning
(“grid” or “tiled”) is ignored, and a new partitioning is computed
from scratch.</p>
<hr class="docutils" />
<p>The <em>group-ID</em> is currently ignored. In the future it may be used to
determine what particles are considered for balancing. Normally it
would only makes sense to use the <em>all</em> group. But in some cases it
may be useful to balance on a subset of the particles, e.g. when
modeling large nanoparticles in a background of small solvent
particles.</p>
<p>The <em>Nfreq</em> setting determines how often a rebalance is performed. If
<em>Nfreq</em> > 0, then rebalancing will occur every <em>Nfreq</em> steps. Each
time a rebalance occurs, a reneighboring is triggered, so <em>Nfreq</em>
should not be too small. If <em>Nfreq</em> = 0, then rebalancing will be
done every time reneighboring normally occurs, as determined by the
the <a class="reference internal" href="neighbor.html"><em>neighbor</em></a> and <a class="reference internal" href="neigh_modify.html"><em>neigh_modify</em></a>
command settings.</p>
<p>On rebalance steps, rebalancing will only be attempted if the current
imbalance factor, as defined above, exceeds the <em>thresh</em> setting.</p>
<hr class="docutils" />
<p>The <em>shift</em> style invokes a “grid” method for balancing, as described
above. It changes the positions of cutting planes between processors
in an iterative fashion, seeking to reduce the imbalance factor.</p>
<p>The <em>dimstr</em> argument is a string of characters, each of which must be
an “x” or “y” or “z”. Eacn character can appear zero or one time,
since there is no advantage to balancing on a dimension more than
once. You should normally only list dimensions where you expect there
to be a density variation in the particles.</p>
<p>Balancing proceeds by adjusting the cutting planes in each of the
dimensions listed in <em>dimstr</em>, one dimension at a time. For a single
dimension, the balancing operation (described below) is iterated on up
to <em>Niter</em> times. After each dimension finishes, the imbalance factor
is re-computed, and the balancing operation halts if the <em>stopthresh</em>
criterion is met.</p>
<p>A rebalance operation in a single dimension is performed using a
density-dependent recursive multisectioning algorithm, where the
position of each cutting plane (line in 2d) in the dimension is
adjusted independently. This is similar to a recursive bisectioning
for a single value, except that the bounds used for each bisectioning
take advantage of information from neighboring cuts if possible, as
well as counts of particles at the bounds on either side of each cuts,
which themselves were cuts in previous iterations. The latter is used
to infer a density of pariticles near each of the current cuts. At
each iteration, the count of particles on either side of each plane is
tallied. If the counts do not match the target value for the plane,
the position of the cut is adjusted based on the local density. The
low and high bounds are adjusted on each iteration, using new count
information, so that they become closer together over time. Thus as
the recursion progresses, the count of particles on either side of the
plane gets closer to the target value.</p>
<p>The density-dependent part of this algorithm is often an advantage
when you rebalance a system that is already nearly balanced. It
typically converges more quickly than the geometric bisectioning
algorithm used by the <a class="reference internal" href="balance.html"><em>balance</em></a> command. However, if can
be a disadvantage if you attempt to rebalance a system that is far
from balanced, and converge more slowly. In this case you probably
want to use the <a class="reference internal" href="balance.html"><em>balance</em></a> command before starting a run,
so that you begin the run with a balanced system.</p>
<p>Once the rebalancing is complete and final processor sub-domains
assigned, particles migrate to their new owning processor as part of
the normal reneighboring procedure.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">At each rebalance operation, the bisectioning for each
cutting plane (line in 2d) typcially starts with low and high bounds
separated by the extent of a processor’s sub-domain in one dimension.
The size of this bracketing region shrinks based on the local density,
as described above, which should typically be 1/2 or more every
iteration. Thus if <em>Niter</em> is specified as 10, the cutting plane will
typically be positioned to better than 1 part in 1000 accuracy
(relative to the perfect target position). For <em>Niter</em> = 20, it will
be accurate to better than 1 part in a million. Thus there is no need
to set <em>Niter</em> to a large value. This is especially true if you are
rebalancing often enough that each time you expect only an incremental
adjustement in the cutting planes is necessary. LAMMPS will check if
the threshold accuracy is reached (in a dimension) is less iterations
than <em>Niter</em> and exit early.</p>
</div>
<hr class="docutils" />
<p>The <em>rcb</em> style invokes a “tiled” method for balancing, as described
above. It performs a recursive coordinate bisectioning (RCB) of the
simulation domain. The basic idea is as follows.</p>
<p>The simulation domain is cut into 2 boxes by an axis-aligned cut in
the longest dimension, leaving one new box on either side of the cut.
All the processors are also partitioned into 2 groups, half assigned
to the box on the lower side of the cut, and half to the box on the
upper side. (If the processor count is odd, one side gets an extra
processor.) The cut is positioned so that the number of atoms in the
lower box is exactly the number that the processors assigned to that
box should own for load balance to be perfect. This also makes load
balance for the upper box perfect. The positioning is done
iteratively, by a bisectioning method. Note that counting atoms on
either side of the cut requires communication between all processors
at each iteration.</p>
<p>That is the procedure for the first cut. Subsequent cuts are made
recursively, in exactly the same manner. The subset of processors
assigned to each box make a new cut in the longest dimension of that
box, splitting the box, the subset of processsors, and the atoms in
the box in two. The recursion continues until every processor is
assigned a sub-box of the entire simulation domain, and owns the atoms
in that sub-box.</p>
<hr class="docutils" />
<p>The <em>out</em> keyword writes a text file to the specified <em>filename</em> with
the results of each rebalancing operation. The file contains the
bounds of the sub-domain for each processor after the balancing
operation completes. The format of the file is compatible with the
<a class="reference external" href="pizza">Pizza.py</a> <em>mdump</em> tool which has support for manipulating and
visualizing mesh files. An example is shown here for a balancing by 4
processors for a 2d problem:</p>
<div class="highlight-python"><div class="highlight"><pre>ITEM: TIMESTEP
0
ITEM: NUMBER OF NODES
16
ITEM: BOX BOUNDS
0 10
0 10
0 10
ITEM: NODES
1 1 0 0 0
2 1 5 0 0
3 1 5 5 0
4 1 0 5 0
5 1 5 0 0
6 1 10 0 0
7 1 10 5 0
8 1 5 5 0
9 1 0 5 0
10 1 5 5 0
11 1 5 10 0
12 1 10 5 0
13 1 5 5 0
14 1 10 5 0
15 1 10 10 0
16 1 5 10 0
ITEM: TIMESTEP
0
ITEM: NUMBER OF SQUARES
4
ITEM: SQUARES
1 1 1 2 3 4
2 1 5 6 7 8
3 1 9 10 11 12
4 1 13 14 15 16
</pre></div>
</div>
<p>The coordinates of all the vertices are listed in the NODES section, 5
per processor. Note that the 4 sub-domains share vertices, so there
will be duplicate nodes in the list.</p>
<p>The “SQUARES” section lists the node IDs of the 4 vertices in a
rectangle for each processor (1 to 4).</p>
<p>For a 3d problem, the syntax is similar with 8 vertices listed for
each processor, instead of 4, and “SQUARES” replaced by “CUBES”.</p>
</div>
<hr class="docutils" />
<div class="section" id="restart-fix-modify-output-run-start-stop-minimize-info">
<h2>Restart, fix_modify, output, run start/stop, minimize info<a class="headerlink" href="#restart-fix-modify-output-run-start-stop-minimize-info" title="Permalink to this headline">¶</a></h2>
<p>No information about this fix is written to <a class="reference internal" href="restart.html"><em>binary restart files</em></a>. None of the <a class="reference internal" href="fix_modify.html"><em>fix_modify</em></a> options
are relevant to this fix.</p>
<p>This fix computes a global scalar which is the imbalance factor
after the most recent rebalance and a global vector of length 3 with
additional information about the most recent rebalancing. The 3
values in the vector are as follows:</p>
<ul class="simple">
<li>1 = max # of particles per processor</li>
<li>2 = total # iterations performed in last rebalance</li>
<li>3 = imbalance factor right before the last rebalance was performed</li>
</ul>
<p>As explained above, the imbalance factor is the ratio of the maximum
number of particles on any processor to the average number of
particles per processor.</p>
<p>These quantities can be accessed by various <a class="reference internal" href="Section_howto.html#howto-15"><span>output commands</span></a>. The scalar and vector values
calculated by this fix are “intensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <a class="reference internal" href="run.html"><em>run</em></a> command. This fix is not invoked during <a class="reference internal" href="minimize.html"><em>energy minimization</em></a>.</p>
</div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>For 2d simulations, a “z” cannot appear in <em>dimstr</em> for the <em>shift</em>
style.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="processors.html"><em>processors</em></a>, <a class="reference internal" href="balance.html"><em>balance</em></a></p>
<p><strong>Default:</strong> none</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file
diff --git a/doc/neb.html b/doc/neb.html
index 8bcc80203..95d9c9542 100644
--- a/doc/neb.html
+++ b/doc/neb.html
@@ -1,582 +1,582 @@
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>neb command — LAMMPS 15 May 2015 version documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/sphinxcontrib-images/LightBox2/lightbox2/css/lightbox.css" type="text/css" />
<link rel="top" title="LAMMPS 15 May 2015 version documentation" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="Manual.html" class="icon icon-home"> LAMMPS
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="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="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="Section_intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_start.html">2. Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_commands.html">3. Commands</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_packages.html">4. Packages</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_accelerate.html">5. Accelerating LAMMPS performance</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_howto.html">6. How-to discussions</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_example.html">7. Example problems</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_perf.html">8. Performance & scalability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_tools.html">9. Additional tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_modify.html">10. Modifying & extending LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_python.html">11. Python interface to LAMMPS</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_errors.html">12. Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="Section_history.html">13. Future and history</a></li>
</ul>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<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">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="Manual.html">Docs</a> »</li>
<li>neb command</li>
<li class="wy-breadcrumbs-aside">
<a href="http://lammps.sandia.gov">Homepage</a>
<a href="Section_commands.html#comm">Commands</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="neb-command">
<span id="index-0"></span><h1>neb command<a class="headerlink" href="#neb-command" title="Permalink to this headline">¶</a></h1>
<div class="section" id="syntax">
<h2>Syntax<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>neb etol ftol N1 N2 Nevery file-style arg
</pre></div>
</div>
<ul class="simple">
<li>etol = stopping tolerance for energy (energy units)</li>
<li>ftol = stopping tolerance for force (force units)</li>
<li>N1 = max # of iterations (timesteps) to run initial NEB</li>
<li>N2 = max # of iterations (timesteps) to run barrier-climbing NEB</li>
<li>Nevery = print replica energies and reaction coordinates every this many timesteps</li>
<li>file-style= <em>final</em> or <em>each</em> or <em>none</em></li>
</ul>
<pre class="literal-block">
<em>final</em> arg = filename
filename = file with initial coords for final replica
coords for intermediate replicas are linearly interpolated between first and last replica
<em>each</em> arg = filename
filename = unique filename for each replica (except first) with its initial coords
<em>none</em> arg = no argument
all replicas assumed to already have their initial coords
</pre>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>neb 0.1 0.0 1000 500 50 final coords.final
neb 0.0 0.001 1000 500 50 each coords.initial.$i
neb 0.0 0.001 1000 500 50 none
</pre></div>
</div>
</div>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>Perform a nudged elastic band (NEB) calculation using multiple
replicas of a system. Two or more replicas must be used; the first
and last are the end points of the transition path.</p>
<p>NEB is a method for finding both the atomic configurations and height
of the energy barrier associated with a transition state, e.g. for an
atom to perform a diffusive hop from one energy basin to another in a
coordinated fashion with its neighbors. The implementation in LAMMPS
follows the discussion in these 3 papers: <a class="reference internal" href="#henkelman1"><span>(Henkelman1)</span></a>,
<a class="reference internal" href="#henkelman2"><span>(Henkelman2)</span></a>, and <a class="reference internal" href="#nakano"><span>(Nakano)</span></a>.</p>
<p>Each replica runs on a partition of one or more processors. Processor
partitions are defined at run-time using the -partition command-line
switch; see <a class="reference internal" href="Section_start.html#start-7"><span>Section_start 7</span></a> of the
manual. Note that if you have MPI installed, you can run a
multi-replica simulation with more replicas (partitions) than you have
physical processors, e.g you can run a 10-replica simulation on just
one or two processors. You will simply not get the performance
speed-up you would see with one or more physical processors per
replica. See <a class="reference internal" href="Section_howto.html#howto-5"><span>this section</span></a> of the manual
for further discussion.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The current NEB implementation in LAMMPS only allows
there to be one processor per replica.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">As explained below, a NEB calculation perfoms a damped
dynamics minimization across all the replicas. The mimimizer uses
whatever timestep you have defined in your input script, via the
<a class="reference internal" href="timestep.html"><em>timestep</em></a> command. Often NEB will converge more
quickly if you use a timestep about 10x larger than you would normally
use for dynamics simulations.</p>
</div>
<p>When a NEB calculation is performed, it is assumed that each replica
is running the same system, though LAMMPS does not check for this.
I.e. the simulation domain, the number of atoms, the interaction
potentials, and the starting configuration when the neb command is
issued should be the same for every replica.</p>
<p>In a NEB calculation each atom in a replica is connected to the same
atom in adjacent replicas by springs, which induce inter-replica
forces. These forces are imposed by the <a class="reference internal" href="fix_neb.html"><em>fix neb</em></a>
command, which must be used in conjunction with the neb command. The
group used to define the fix neb command defines the NEB atoms which
are the only ones that inter-replica springs are applied to. If the
group does not include all atoms, then non-NEB atoms have no
inter-replica springs and the forces they feel and their motion is
computed in the usual way due only to other atoms within their
replica. Conceptually, the non-NEB atoms provide a background force
field for the NEB atoms. They can be allowed to move during the NEB
minimiation procedure (which will typically induce different
coordinates for non-NEB atoms in different replicas), or held fixed
using other LAMMPS commands such as <a class="reference external" href="fix_setforce">fix setforce</a>. Note
that the <a class="reference internal" href="partition.html"><em>partition</em></a> command can be used to invoke a
command on a subset of the replicas, e.g. if you wish to hold NEB or
non-NEB atoms fixed in only the end-point replicas.</p>
<p>The initial atomic configuration for each of the replicas can be
specified in different manners via the <em>file-style</em> setting, as
discussed below. Only atoms whose initial coordinates should differ
from the current configuration need be specified.</p>
<p>Conceptually, the initial configuration for the first replica should
be a state with all the atoms (NEB and non-NEB) having coordinates on
one side of the energy barrier. A perfect energy minimum is not
required, since atoms in the first replica experience no spring forces
from the 2nd replica. Thus the damped dynamics minimizaiton will
drive the first replica to an energy minimum if it is not already
there. However, you will typically get better convergence if the
initial state is already at a minimum. For example, for a system with
a free surface, the surface should be fully relaxed before attempting
a NEB calculation.</p>
<p>Likewise, the initial configuration of the final replica should be a
state with all the atoms (NEB and non-NEB) on the other side of the
energy barrier. Again, a perfect energy minimum is not required,
since the atoms in the last replica also experience no spring forces
from the next-to-last replica, and thus the damped dynamics
minimization will drive it to an energy minimum.</p>
<p>As explained below, the initial configurations of intermediate
replicas can be atomic coordinates interpolated in a linear fashion
between the first and last replicas. This is often adequate state for
simple transitions. For more complex transitions, it may lead to slow
convergence or even bad results if the minimum energy path (MEP, see
below) of states over the barrier cannot be correctly converged to
from such an initial configuration. In this case, you will want to
generate initial states for the intermediate replicas that are
geometrically closer to the MEP and read them in.</p>
<hr class="docutils" />
<p>For a <em>file-style</em> setting of <em>final</em>, a filename is specified which
contains atomic coordinates for zero or more atoms, in the format
described below. For each atom that appears in the file, the new
coordinates are assigned to that atom in the final replica. Each
intermediate replica also assigns a new position to that atom in an
interpolated manner. This is done by using the current position of
the atom as the starting point and the read-in position as the final
point. The distance between them is calculated, and the new position
is assigned to be a fraction of the distance. E.g. if there are 10
replicas, the 2nd replica will assign a position that is 10% of the
distance along a line between the starting and final point, and the
9th replica will assign a position that is 90% of the distance along
the line. Note that this procedure to produce consistent coordinates
across all the replicas, the current coordinates need to be the same
in all replicas. LAMMPS does not check for this, but invalid initial
configurations will likely result if it is not the case.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The “distance” between the starting and final point is
calculated in a minimum-image sense for a periodic simulation box.
This means that if the two positions are on opposite sides of a box
(periodic in that dimension), the distance between them will be small,
because the periodic image of one of the atoms is close to the other.
Similarly, even if the assigned position resulting from the
interpolation is outside the periodic box, the atom will be wrapped
back into the box when the NEB calculation begins.</p>
</div>
<p>For a <em>file-style</em> setting of <em>each</em>, a filename is specified which is
assumed to be unique to each replica. This can be done by
using a variable in the filename, e.g.</p>
<div class="highlight-python"><div class="highlight"><pre>variable i equal part
neb 0.0 0.001 1000 500 50 each coords.initial.$i
</pre></div>
</div>
<p>which in this case will substitute the partition ID (0 to N-1) for the
variable I, which is also effectively the replica ID. See the
<a class="reference internal" href="variable.html"><em>variable</em></a> command for other options, such as using
world-, universe-, or uloop-style variables.</p>
<p>Each replica (except the first replica) will read its file, formatted
as described below, and for any atom that appears in the file, assign
the specified coordinates to its atom. The various files do not need
to contain the same set of atoms.</p>
<p>For a <em>file-style</em> setting of <em>none</em>, no filename is specified. Each
replica is assumed to already be in its initial configuration at the
time the neb command is issued. This allows each replica to define
its own configuration by reading a replica-specific data or restart or
dump file, via the <a class="reference internal" href="read_data.html"><em>read_data</em></a>,
<a class="reference internal" href="read_restart.html"><em>read_restart</em></a>, or <a class="reference internal" href="read_dump.html"><em>read_dump</em></a>
commands. The replica-specific names of these files can be specified
as in the discussion above for the <em>each</em> file-style. Also see the
section below for how a NEB calculation can produce restart files, so
that a long calculation can be restarted if needed.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">None of the <em>file-style</em> settings change the initial
configuration of any atom in the first replica. The first replica
must thus be in the correct initial configuration at the time the neb
command is issued.</p>
</div>
<hr class="docutils" />
<p>A NEB calculation proceeds in two stages, each of which is a
minimization procedure, performed via damped dynamics. To enable
this, you must first define a damped dynamics
<a class="reference internal" href="min_style.html"><em>min_style</em></a>, such as <em>quickmin</em> or <em>fire</em>. The <em>cg</em>,
<em>sd</em>, and <em>hftn</em> styles cannot be used, since they perform iterative
line searches in their inner loop, which cannot be easily synchronized
across multiple replicas.</p>
<p>The minimizer tolerances for energy and force are set by <em>etol</em> and
<em>ftol</em>, the same as for the <a class="reference internal" href="minimize.html"><em>minimize</em></a> command.</p>
<p>A non-zero <em>etol</em> means that the NEB calculation will terminate if the
energy criterion is met by every replica. The energies being compared
to <em>etol</em> do not include any contribution from the inter-replica
forces, since these are non-conservative. A non-zero <em>ftol</em> means
that the NEB calculation will terminate if the force criterion is met
by every replica. The forces being compared to <em>ftol</em> include the
inter-replica forces between an atom and its images in adjacent
replicas.</p>
<p>The maximum number of iterations in each stage is set by <em>N1</em> and
<em>N2</em>. These are effectively timestep counts since each iteration of
damped dynamics is like a single timestep in a dynamics
<a class="reference internal" href="run.html"><em>run</em></a>. During both stages, the potential energy of each
replica and its normalized distance along the reaction path (reaction
coordinate RD) will be printed to the screen and log file every
<em>Nevery</em> timesteps. The RD is 0 and 1 for the first and last replica.
For intermediate replicas, it is the cumulative distance (normalized
by the total cumulative distance) between adjacent replicas, where
“distance” is defined as the length of the 3N-vector of differences in
atomic coordinates, where N is the number of NEB atoms involved in the
transition. These outputs allow you to monitor NEB’s progress in
finding a good energy barrier. <em>N1</em> and <em>N2</em> must both be multiples
of <em>Nevery</em>.</p>
<p>In the first stage of NEB, the set of replicas should converge toward
the minimum energy path (MEP) of conformational states that transition
over the barrier. The MEP for a barrier is defined as a sequence of
3N-dimensional states that cross the barrier at its saddle point, each
of which has a potential energy gradient parallel to the MEP itself.
The replica states will also be roughly equally spaced along the MEP
due to the inter-replica spring force added by the <a class="reference internal" href="fix_neb.html"><em>fix neb</em></a> command.</p>
<p>In the second stage of NEB, the replica with the highest energy
is selected and the inter-replica forces on it are converted to a
force that drives its atom coordinates to the top or saddle point of
the barrier, via the barrier-climbing calculation described in
<span class="xref std std-ref">(Henkelman2)</span>. As before, the other replicas rearrange
themselves along the MEP so as to be roughly equally spaced.</p>
<p>When both stages are complete, if the NEB calculation was successful,
one of the replicas should be an atomic configuration at the top or
saddle point of the barrier, the potential energies for the set of
replicas should represent the energy profile of the barrier along the
MEP, and the configurations of the replicas should be a sequence of
configurations along the MEP.</p>
<hr class="docutils" />
<p>A few other settings in your input script are required or advised to
perform a NEB calculation. See the IMPORTANT NOTE about the choice of
timestep at the beginning of this doc page.</p>
<p>An atom map must be defined which it is not by default for <a class="reference internal" href="atom_style.html"><em>atom_style atomic</em></a> problems. The <a class="reference internal" href="atom_modify.html"><em>atom_modify map</em></a> command can be used to do this.</p>
<p>The “atom_modify sort 0 0.0” command should be used to turn off atom
sorting.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This sorting restriction will be removed in a future version of
NEB in LAMMPS.</p>
</div>
<p>The minimizers in LAMMPS operate on all atoms in your system, even
non-NEB atoms, as defined above. To prevent non-NEB atoms from moving
during the minimization, you should use the <a class="reference internal" href="fix_setforce.html"><em>fix setforce</em></a> command to set the force on each of those
atoms to 0.0. This is not required, and may not even be desired in
some cases, but if those atoms move too far (e.g. because the initial
state of your system was not well-minimized), it can cause problems
for the NEB procedure.</p>
<p>The damped dynamics <a class="reference internal" href="min_style.html"><em>minimizers</em></a>, such as <em>quickmin</em>
and <em>fire</em>), adjust the position and velocity of the atoms via an
Euler integration step. Thus you must define an appropriate
<a class="reference internal" href="timestep.html"><em>timestep</em></a> to use with NEB. As mentioned above, NEB
will often converge more quickly if you use a timestep about 10x
larger than you would normally use for dynamics simulations.</p>
<hr class="docutils" />
<p>Each file read by the neb command containing atomic coordinates used
to initialize one or more replicas must be formatted as follows.</p>
<p>The file can be ASCII text or a gzipped text file (detected by a .gz
suffix). The file can contain initial blank lines or comment lines
starting with “#” which are ignored. The first non-blank, non-comment
line should list N = the number of lines to follow. The N successive
lines contain the following information:</p>
<div class="highlight-python"><div class="highlight"><pre>ID1 x1 y1 z1
ID2 x2 y2 z2
...
IDN xN yN zN
</pre></div>
</div>
<p>The fields are the the atom ID, followed by the x,y,z coordinates.
The lines can be listed in any order. Additional trailing information
on the line is OK, such as a comment.</p>
<p>Note that for a typical NEB calculation you do not need to specify
initial coordinates for very many atoms to produce differing starting
and final replicas whose intermediate replicas will converge to the
energy barrier. Typically only new coordinates for atoms
geometrically near the barrier need be specified.</p>
<p>Also note there is no requirement that the atoms in the file
correspond to the NEB atoms in the group defined by the <a class="reference internal" href="fix_neb.html"><em>fix neb</em></a> command. Not every NEB atom need be in the file,
and non-NEB atoms can be listed in the file.</p>
<hr class="docutils" />
<p>Four kinds of output can be generated during a NEB calculation: energy
barrier statistics, thermodynamic output by each replica, dump files,
and restart files.</p>
<p>When running with multiple partitions (each of which is a replica in
this case), the print-out to the screen and master log.lammps file
contains a line of output, printed once every <em>Nevery</em> timesteps. It
contains the timestep, the maximum force per replica, the maximum
force per atom (in any replica), potential gradients in the initial,</p>
<blockquote>
<div>final, and climbing replicas,</div></blockquote>
<p>the forward and backward energy barriers,
the total reaction coordinate (RDT), and
the normalized reaction coordinate and potential energy of each replica.</p>
<p>The “maximum force per replica” is
the two-norm of the 3N-length force vector for the atoms in each
replica, maximized across replicas, which is what the <em>ftol</em> setting
is checking against. In this case, N is all the atoms in each
replica. The “maximum force per atom” is the maximum force component
of any atom in any replica. The potential gradients are the two-norm
of the 3N-length force vector solely due to the interaction potential i.e.
without adding in inter-replica forces. Note that inter-replica forces
are zero in the initial and final replicas, and only affect
the direction in the climbing replica. For this reason, the “maximum
force per replica” is often equal to the potential gradient in the
climbing replica. In the first stage of NEB, there is no climbing
replica, and so the potential gradient in the highest energy replica
is reported, since this replica will become the climbing replica
in the second stage of NEB.</p>
<p>The “reaction coordinate” (RD) for each
replica is the two-norm of the 3N-length vector of distances between
its atoms and the preceding replica’s atoms, added to the RD of the
preceding replica. The RD of the first replica RD1 = 0.0;
the RD of the final replica RDN = RDT, the total reaction coordinate.
The normalized RDs are divided by RDT,
so that they form a monotonically increasing sequence
from zero to one. When computing RD, N only includes the atoms
being operated on by the fix neb command.</p>
<p>The forward (reverse) energy barrier is the potential energy of the highest
replica minus the energy of the first (last) replica.</p>
<p>When running on multiple partitions, LAMMPS produces additional log
files for each partition, e.g. log.lammps.0, log.lammps.1, etc. For a
NEB calculation, these contain the thermodynamic output for each
replica.</p>
<p>If <a class="reference internal" href="dump.html"><em>dump</em></a> commands in the input script define a filename
that includes a <em>universe</em> or <em>uloop</em> style <a class="reference internal" href="variable.html"><em>variable</em></a>,
then one dump file (per dump command) will be created for each
replica. At the end of the NEB calculation, the final snapshot in
each file will contain the sequence of snapshots that transition the
system over the energy barrier. Earlier snapshots will show the
convergence of the replicas to the MEP.</p>
<p>Likewise, <a class="reference internal" href="restart.html"><em>restart</em></a> filenames can be specified with a
<em>universe</em> or <em>uloop</em> style <a class="reference internal" href="variable.html"><em>variable</em></a>, to generate
restart files for each replica. These may be useful if the NEB
calculation fails to converge properly to the MEP, and you wish to
restart the calculation from an intermediate point with altered
parameters.</p>
<p>There are 2 Python scripts provided in the tools/python directory,
neb_combine.py and neb_final.py, which are useful in analyzing output
from a NEB calculation. Assume a NEB simulation with M replicas, and
the NEB atoms labelled with a specific atom type.</p>
<p>The neb_combine.py script extracts atom coords for the NEB atoms from
all M dump files and creates a single dump file where each snapshot
contains the NEB atoms from all the replicas and one copy of non-NEB
atoms from the first replica (presumed to be identical in other
replicas). This can be visualized/animated to see how the NEB atoms
relax as the NEB calculation proceeds.</p>
<p>The neb_final.py script extracts the final snapshot from each of the M
dump files to create a single dump file with M snapshots. This can be
visualized to watch the system make its transition over the energy
barrier.</p>
<p>To illustrate, here are images from the final snapshot produced by the
neb_combine.py script run on the dump files produced by the two
example input scripts in examples/neb. Click on them to see a larger
image.</p>
-<a data-lightbox="group-f5c1df75-20d4-4a80-810c-e8bb668cdbe1"
+<a data-lightbox="group-0eb1e253-2977-45e3-863d-e69fe78196e9"
href="_images/hop1.jpg"
class=""
title=""
data-title=""
><img src="_images/hop1.jpg"
class=""
width="25%"
height="auto"
alt=""/>
- </a><a data-lightbox="group-445d89a5-1eb9-4204-8d86-136f90dc78ca"
+ </a><a data-lightbox="group-fb58d79f-e00a-4e78-b97a-b1bff65370eb"
href="_images/hop2.jpg"
class=""
title=""
data-title=""
><img src="_images/hop2.jpg"
class=""
width="25%"
height="auto"
alt=""/>
</a></div>
<hr class="docutils" />
<div class="section" id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
<p>This command can only be used if LAMMPS was built with the REPLICA
package. See the <a class="reference internal" href="Section_start.html#start-3"><span>Making LAMMPS</span></a> section
for more info on packages.</p>
</div>
<div class="section" id="related-commands">
<h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
<p><a class="reference internal" href="prd.html"><em>prd</em></a>, <a class="reference internal" href="temper.html"><em>temper</em></a>, <a class="reference internal" href="fix_langevin.html"><em>fix langevin</em></a>, <a class="reference internal" href="fix_viscous.html"><em>fix viscous</em></a></p>
<p><strong>Default:</strong> none</p>
<hr class="docutils" />
<p id="henkelman1"><strong>(Henkelman1)</strong> Henkelman and Jonsson, J Chem Phys, 113, 9978-9985 (2000).</p>
<p id="henkelman2"><strong>(Henkelman2)</strong> Henkelman, Uberuaga, Jonsson, J Chem Phys, 113,
9901-9904 (2000).</p>
<p id="nakano"><strong>(Nakano)</strong> Nakano, Comp Phys Comm, 178, 280-289 (2008).</p>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright .
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'15 May 2015 version',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2/js/lightbox.min.js"></script>
<script type="text/javascript" src="_static/sphinxcontrib-images/LightBox2/lightbox2-customize/jquery-noconflict.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
\ No newline at end of file