forked from lijiext/lammps
640 lines
39 KiB
HTML
640 lines
39 KiB
HTML
|
|
|
|
<!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>python command — LAMMPS 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 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>python command</li>
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="http://lammps.sandia.gov">Website</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-command">
|
|
<span id="index-0"></span><h1>python command</h1>
|
|
<div class="section" id="syntax">
|
|
<h2>Syntax</h2>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">func</span> <span class="n">keyword</span> <span class="n">args</span> <span class="o">...</span>
|
|
</pre></div>
|
|
</div>
|
|
<ul class="simple">
|
|
<li>func = name of Python function</li>
|
|
<li>one or more keyword/args pairs must be appended</li>
|
|
</ul>
|
|
<pre class="literal-block">
|
|
keyword = <em>invoke</em> or <em>input</em> or <em>return</em> or <em>format</em> or <em>file</em> or <em>here</em> or <em>exists</em>
|
|
<em>invoke</em> arg = none = invoke the previously defined Python function
|
|
<em>input</em> args = N i1 i2 ... iN
|
|
N = # of inputs to function
|
|
i1,...,iN = value, SELF, or LAMMPS variable name
|
|
value = integer number, floating point number, or string
|
|
SELF = reference to LAMMPS itself which can be accessed by Python function
|
|
variable = v_name, where name = name of LAMMPS variable, e.g. v_abc
|
|
<em>return</em> arg = varReturn
|
|
varReturn = v_name = LAMMPS variable name which return value of function will be assigned to
|
|
<em>format</em> arg = fstring with M characters
|
|
M = N if no return value, where N = # of inputs
|
|
M = N+1 if there is a return value
|
|
fstring = each character (i,f,s,p) corresponds in order to an input or return value
|
|
'i' = integer, 'f' = floating point, 's' = string, 'p' = SELF
|
|
<em>file</em> arg = filename
|
|
filename = file of Python code, which defines func
|
|
<em>here</em> arg = inline
|
|
inline = one or more lines of Python code which defines func
|
|
must be a single argument, typically enclosed between triple quotes
|
|
<em>exists</em> arg = none = Python code has been loaded by previous python command
|
|
</pre>
|
|
</div>
|
|
<div class="section" id="examples">
|
|
<h2>Examples</h2>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">pForce</span> <span class="nb">input</span> <span class="mi">2</span> <span class="n">v_x</span> <span class="mf">20.0</span> <span class="k">return</span> <span class="n">v_f</span> <span class="nb">format</span> <span class="n">fff</span> <span class="n">file</span> <span class="n">force</span><span class="o">.</span><span class="n">py</span>
|
|
<span class="n">python</span> <span class="n">pForce</span> <span class="n">invoke</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">factorial</span> <span class="nb">input</span> <span class="mi">1</span> <span class="n">myN</span> <span class="k">return</span> <span class="n">v_fac</span> <span class="nb">format</span> <span class="n">ii</span> <span class="n">here</span> <span class="s2">"""</span>
|
|
<span class="s2">def factorial(n):</span>
|
|
<span class="s2"> if n == 1: return n</span>
|
|
<span class="s2"> return n * factorial(n-1)</span>
|
|
<span class="s2"> """</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">loop</span> <span class="nb">input</span> <span class="mi">1</span> <span class="n">SELF</span> <span class="k">return</span> <span class="n">v_value</span> <span class="nb">format</span> <span class="o">-</span><span class="n">f</span> <span class="n">here</span> <span class="s2">"""</span>
|
|
<span class="s2">def loop(lmpptr,N,cut0):</span>
|
|
<span class="s2"> from lammps import lammps</span>
|
|
<span class="s2"> lmp = lammps(ptr=lmpptr)</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># loop N times, increasing cutoff each time</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">N</span><span class="p">):</span>
|
|
<span class="n">cut</span> <span class="o">=</span> <span class="n">cut0</span> <span class="o">+</span> <span class="n">i</span><span class="o">*</span><span class="mf">0.1</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">set_variable</span><span class="p">(</span><span class="s2">"cut"</span><span class="p">,</span><span class="n">cut</span><span class="p">)</span> <span class="c1"># set a variable in LAMMPS</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"pair_style lj/cut $</span><span class="si">{cut}</span><span class="s2">"</span><span class="p">)</span> <span class="c1"># LAMMPS commands</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"pair_coeff * * 1.0 1.0"</span><span class="p">)</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"run 100"</span><span class="p">)</span>
|
|
<span class="s2">"""</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="description">
|
|
<h2>Description</h2>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">It is not currently possible to use the <a class="reference internal" href="#"><span class="doc">python</span></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>Define a Python function or execute a previously defined function.
|
|
Arguments, including LAMMPS variables, can be passed to the function
|
|
from the LAMMPS input script and a value returned by the Python
|
|
function to a LAMMPS variable. The Python code for the function can
|
|
be included directly in the input script or in a separate Python file.
|
|
The function can be standard Python code or it can make “callbacks” to
|
|
LAMMPS through its library interface to query or set internal values
|
|
within LAMMPS. This is a powerful mechanism for performing complex
|
|
operations in a LAMMPS input script that are not possible with the
|
|
simple input script and variable syntax which LAMMPS defines. Thus
|
|
your input script can operate more like a true programming language.</p>
|
|
<p>Use of this command requires building LAMMPS with the PYTHON package
|
|
which links to the Python library so that the Python interpreter is
|
|
embedded in LAMMPS. More details about this process are given below.</p>
|
|
<p>There are two ways to invoke a Python function once it has been
|
|
defined. One is using the <em>invoke</em> keyword. The other is to assign
|
|
the function to a <a class="reference internal" href="variable.html"><span class="doc">python-style variable</span></a> defined in
|
|
your input script. Whenever the variable is evaluated, it will
|
|
execute the Python function to assign a value to the variable. Note
|
|
that variables can be evaluated in many different ways within LAMMPS.
|
|
They can be substituted for directly in an input script. Or they can
|
|
be passed to various commands as arguments, so that the variable is
|
|
evaluated during a simulation run.</p>
|
|
<p>A broader overview of how Python can be used with LAMMPS is
|
|
given in <a class="reference internal" href="Section_python.html"><span class="doc">Section python</span></a>. There is an
|
|
examples/python directory which illustrates use of the python
|
|
command.</p>
|
|
<hr class="docutils" />
|
|
<p>The <em>func</em> setting specifies the name of the Python function. The
|
|
code for the function is defined using the <em>file</em> or <em>here</em> keywords
|
|
as explained below.</p>
|
|
<p>If the <em>invoke</em> keyword is used, no other keywords can be used, and a
|
|
previous python command must have defined the Python function
|
|
referenced by this command. This invokes the Python function with the
|
|
previously defined arguments and return value processed as explained
|
|
below. You can invoke the function as many times as you wish in your
|
|
input script.</p>
|
|
<p>The <em>input</em> keyword defines how many arguments <em>N</em> the Python function
|
|
expects. If it takes no arguments, then the <em>input</em> keyword should
|
|
not be used. Each argument can be specified directly as a value,
|
|
e.g. 6 or 3.14159 or abc (a string of characters). The type of each
|
|
argument is specified by the <em>format</em> keyword as explained below, so
|
|
that Python will know how to interpret the value. If the word SELF is
|
|
used for an argument it has a special meaning. A pointer is passed to
|
|
the Python function which it converts into a reference to LAMMPS
|
|
itself. This enables the function to call back to LAMMPS through its
|
|
library interface as explained below. This allows the Python function
|
|
to query or set values internal to LAMMPS which can affect the
|
|
subsequent execution of the input script. A LAMMPS variable can also
|
|
be used as an argument, specified as v_name, where “name” is the name
|
|
of the variable. Any style of LAMMPS variable can be used, as defined
|
|
by the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command. Each time the Python
|
|
function is invoked, the LAMMPS variable is evaluated and its value is
|
|
passed to the Python function.</p>
|
|
<p>The <em>return</em> keyword is only needed if the Python function returns a
|
|
value. The specified <em>varReturn</em> must be of the form v_name, where
|
|
“name” is the name of a python-style LAMMPS variable, defined by the
|
|
<a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command. The Python function can return a
|
|
numeric or string value, as specified by the <em>format</em> keyword.</p>
|
|
<p>As explained on the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> doc page, the definition
|
|
of a python-style variable associates a Python function name with the
|
|
variable. This must match the <em>func</em> setting for this command. For
|
|
exampe these two commands would be self-consistent:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">variable</span> <span class="n">foo</span> <span class="n">python</span> <span class="n">myMultiply</span>
|
|
<span class="n">python</span> <span class="n">myMultiply</span> <span class="k">return</span> <span class="n">v_foo</span> <span class="nb">format</span> <span class="n">f</span> <span class="n">file</span> <span class="n">funcs</span><span class="o">.</span><span class="n">py</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The two commands can appear in either order in the input script so
|
|
long as both are specified before the Python function is invoked for
|
|
the first time.</p>
|
|
<p>The <em>format</em> keyword must be used if the <em>input</em> or <em>return</em> keyword
|
|
is used. It defines an <em>fstring</em> with M characters, where M = sum of
|
|
number of inputs and outputs. The order of characters corresponds to
|
|
the N inputs, followed by the return value (if it exists). Each
|
|
character must be one of the following: “i” for integer, “f” for
|
|
floating point, “s” for string, or “p” for SELF. Each character
|
|
defines the type of the corresponding input or output value of the
|
|
Python function and affects the type conversion that is performed
|
|
internally as data is passed back and forth between LAMMPS and Python.
|
|
Note that it is permissible to use a <a class="reference internal" href="variable.html"><span class="doc">python-style variable</span></a> in a LAMMPS command that allows for an
|
|
equal-style variable as an argument, but only if the output of the
|
|
Python function is flagged as a numeric value (“i” or “f”) via the
|
|
<em>format</em> keyword.</p>
|
|
<p>Either the <em>file</em>, <em>here</em>, or <em>exists</em> keyword must be used, but only
|
|
one of them. These keywords specify what Python code to load into the
|
|
Python interpreter. The <em>file</em> keyword gives the name of a file,
|
|
which should end with a ”.py” suffix, which contains Python code. The
|
|
code will be immediately loaded into and run in the “main” module of
|
|
the Python interpreter. Note that Python code which contains a
|
|
function definition does not “execute” the function when it is run; it
|
|
simply defines the function so that it can be invoked later.</p>
|
|
<p>The <em>here</em> keyword does the same thing, except that the Python code
|
|
follows as a single argument to the <em>here</em> keyword. This can be done
|
|
using triple quotes as delimiters, as in the examples above. This
|
|
allows Python code to be listed verbatim in your input script, with
|
|
proper indentation, blank lines, and comments, as desired. See
|
|
<a class="reference internal" href="Section_commands.html#cmd-2"><span class="std std-ref">Section 3.2</span></a>, for an explanation of how
|
|
triple quotes can be used as part of input script syntax.</p>
|
|
<p>The <em>exists</em> keyword takes no argument. It means that Python code
|
|
containing the required Python function defined by the <em>func</em> setting,
|
|
is assumed to have been previously loaded by another python command.</p>
|
|
<p>Note that the Python code that is loaded and run must contain a
|
|
function with the specified <em>func</em> name. To operate properly when
|
|
later invoked, the the function code must match the <em>input</em> and
|
|
<em>return</em> and <em>format</em> keywords specified by the python command.
|
|
Otherwise Python will generate an error.</p>
|
|
<hr class="docutils" />
|
|
<p>This section describes how Python code can be written to work with
|
|
LAMMPS.</p>
|
|
<p>Whether you load Python code from a file or directly from your input
|
|
script, via the <em>file</em> and <em>here</em> keywords, the code can be identical.
|
|
It must be indented properly as Python requires. It can contain
|
|
comments or blank lines. If the code is in your input script, it
|
|
cannot however contain triple-quoted Python strings, since that will
|
|
conflict with the triple-quote parsing that the LAMMPS input script
|
|
performs.</p>
|
|
<p>All the Python code you specify via one or more python commands is
|
|
loaded into the Python “main” module, i.e. __main__. The code can
|
|
define global variables or statements that are outside of function
|
|
definitions. It can contain multiple functions, only one of which
|
|
matches the <em>func</em> setting in the python command. This means you can
|
|
use the <em>file</em> keyword once to load several functions, and the
|
|
<em>exists</em> keyword thereafter in subsequent python commands to access
|
|
the other functions previously loaded.</p>
|
|
<p>A Python function you define (or more generally, the code you load)
|
|
can import other Python modules or classes, it can make calls to other
|
|
system functions or functions you define, and it can access or modify
|
|
global variables (in the “main” module) which will persist between
|
|
successive function calls. The latter can be useful, for example, to
|
|
prevent a function from being invoke multiple times per timestep by
|
|
different commands in a LAMMPS input script that access the returned
|
|
python-style variable associated with the function. For example,
|
|
consider this function loaded with two global variables defined
|
|
outside the function:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">nsteplast</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span>
|
|
<span class="n">nvaluelast</span> <span class="o">=</span> <span class="mi">0</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">expensive</span><span class="p">(</span><span class="n">nstep</span><span class="p">):</span>
|
|
<span class="k">global</span> <span class="n">nsteplast</span><span class="p">,</span><span class="n">nvaluelast</span>
|
|
<span class="k">if</span> <span class="n">nstep</span> <span class="o">==</span> <span class="n">nsteplast</span><span class="p">:</span> <span class="k">return</span> <span class="n">nvaluelast</span>
|
|
<span class="n">nsteplast</span> <span class="o">=</span> <span class="n">nstep</span>
|
|
<span class="c1"># perform complicated calculation</span>
|
|
<span class="n">nvalue</span> <span class="o">=</span> <span class="o">...</span>
|
|
<span class="n">nvaluelast</span> <span class="o">=</span> <span class="n">nvalue</span>
|
|
<span class="k">return</span> <span class="n">nvalue</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Nsteplast stores the previous timestep the function was invoked
|
|
(passed as an argument to the function). Nvaluelast stores the return
|
|
value computed on the last function invocation. If the function is
|
|
invoked again on the same timestep, the previous value is simply
|
|
returned, without re-computing it. The “global” statement inside the
|
|
Python function allows it to overwrite the global variables.</p>
|
|
<p>Note that if you load Python code multiple times (via multiple python
|
|
commands), you can overwrite previously loaded variables and functions
|
|
if you are not careful. E.g. if the code above were loaded twice, the
|
|
global variables would be re-initialized, which might not be what you
|
|
want. Likewise, if a function with the same name exists in two chunks
|
|
of Python code you load, the function loaded second will override the
|
|
function loaded first.</p>
|
|
<p>It’s important to realize that if you are running LAMMPS in parallel,
|
|
each MPI task will load the Python interpreter and execute a local
|
|
copy of the Python function(s) you define. There is no connection
|
|
between the Python interpreters running on different processors.
|
|
This implies three important things.</p>
|
|
<p>First, if you put a print statement in your Python function, you will
|
|
see P copies of the output, when running on P processors. If the
|
|
prints occur at (nearly) the same time, the P copies of the output may
|
|
be mixed together. Welcome to the world of parallel programming and
|
|
debugging.</p>
|
|
<p>Second, if your Python code loads modules that are not pre-loaded by
|
|
the Python library, then it will load the module from disk. This may
|
|
be a bottleneck if 1000s of processors try to load a module at the
|
|
same time. On some large supercomputers, loading of modules from disk
|
|
by Python may be disabled. In this case you would need to pre-build a
|
|
Python library that has the required modules pre-loaded and link
|
|
LAMMPS with that library.</p>
|
|
<p>Third, if your Python code calls back to LAMMPS (discussed in the
|
|
next section) and causes LAMMPS to perform an MPI operation requires
|
|
global communication (e.g. via MPI_Allreduce), such as computing the
|
|
global temperature of the system, then you must insure all your Python
|
|
functions (running independently on different processors) call back to
|
|
LAMMPS. Otherwise the code may hang.</p>
|
|
<hr class="docutils" />
|
|
<p>Your Python function can “call back” to LAMMPS through its
|
|
library interface, if you use the SELF input to pass Python
|
|
a pointer to LAMMPS. The mechanism for doing this in your
|
|
Python function is as follows:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">foo</span><span class="p">(</span><span class="n">lmpptr</span><span class="p">,</span><span class="o">...</span><span class="p">):</span>
|
|
<span class="kn">from</span> <span class="nn">lammps</span> <span class="k">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><span class="n">ptr</span><span class="o">=</span><span class="n">lmpptr</span><span class="p">)</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s1">'print "Hello from inside Python"'</span><span class="p">)</span>
|
|
<span class="o">...</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The function definition must include a variable (lmpptr in this case)
|
|
which corresponds to SELF in the python command. The first line of
|
|
the function imports the Python module lammps.py in the python dir of
|
|
the distribution. The second line creates a Python object “lmp” which
|
|
wraps the instance of LAMMPS that called the function. The
|
|
“ptr=lmpptr” argument is what makes that happen. The thrid line
|
|
invokes the command() function in the LAMMPS library interface. It
|
|
takes a single string argument which is a LAMMPS input script command
|
|
for LAMMPS to execute, the same as if it appeared in your input
|
|
script. In this case, LAMMPS should output</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Hello</span> <span class="kn">from</span> <span class="nn">inside</span> <span class="n">Python</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>to the screen and log file. Note that since the LAMMPS print command
|
|
itself takes a string in quotes as its argument, the Python string
|
|
must be delimited with a different style of quotes.</p>
|
|
<p><a class="reference internal" href="Section_python.html#py-7"><span class="std std-ref">Section 11.7</span></a> describes the syntax for how
|
|
Python wraps the various functions included in the LAMMPS library
|
|
interface.</p>
|
|
<p>A more interesting example is in the examples/python/in.python script
|
|
which loads and runs the following function from examples/python/funcs.py:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">loop</span><span class="p">(</span><span class="n">N</span><span class="p">,</span><span class="n">cut0</span><span class="p">,</span><span class="n">thresh</span><span class="p">,</span><span class="n">lmpptr</span><span class="p">):</span>
|
|
<span class="nb">print</span> <span class="s2">"LOOP ARGS"</span><span class="p">,</span><span class="n">N</span><span class="p">,</span><span class="n">cut0</span><span class="p">,</span><span class="n">thresh</span><span class="p">,</span><span class="n">lmpptr</span>
|
|
<span class="kn">from</span> <span class="nn">lammps</span> <span class="k">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><span class="n">ptr</span><span class="o">=</span><span class="n">lmpptr</span><span class="p">)</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>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">N</span><span class="p">):</span>
|
|
<span class="n">cut</span> <span class="o">=</span> <span class="n">cut0</span> <span class="o">+</span> <span class="n">i</span><span class="o">*</span><span class="mf">0.1</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">lmp</span><span class="o">.</span><span class="n">set_variable</span><span class="p">(</span><span class="s2">"cut"</span><span class="p">,</span><span class="n">cut</span><span class="p">)</span> <span class="c1"># set a variable in LAMMPS</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"pair_style lj/cut $</span><span class="si">{cut}</span><span class="s2">"</span><span class="p">)</span> <span class="c1"># LAMMPS command</span>
|
|
<span class="c1">#lmp.command("pair_style lj/cut %d" % cut) # LAMMPS command option</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"pair_coeff * * 1.0 1.0"</span><span class="p">)</span> <span class="c1"># ditto</span>
|
|
<span class="n">lmp</span><span class="o">.</span><span class="n">command</span><span class="p">(</span><span class="s2">"run 10"</span><span class="p">)</span> <span class="c1"># ditto</span>
|
|
<span class="n">pe</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="s2">"thermo_pe"</span><span class="p">,</span><span class="mi">0</span><span class="p">,</span><span class="mi">0</span><span class="p">)</span> <span class="c1"># extract total PE from LAMMPS</span>
|
|
<span class="nb">print</span> <span class="s2">"PE"</span><span class="p">,</span><span class="n">pe</span><span class="o">/</span><span class="n">natoms</span><span class="p">,</span><span class="n">thresh</span>
|
|
<span class="k">if</span> <span class="n">pe</span><span class="o">/</span><span class="n">natoms</span> <span class="o"><</span> <span class="n">thresh</span><span class="p">:</span> <span class="k">return</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>with these input script commands:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">loop</span> <span class="nb">input</span> <span class="mi">4</span> <span class="mi">10</span> <span class="mf">1.0</span> <span class="o">-</span><span class="mf">4.0</span> <span class="n">SELF</span> <span class="nb">format</span> <span class="n">iffp</span> <span class="n">file</span> <span class="n">funcs</span><span class="o">.</span><span class="n">py</span>
|
|
<span class="n">python</span> <span class="n">loop</span> <span class="n">invoke</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This has the effect of looping over a series of 10 short runs (10
|
|
timesteps each) where the pair style cutoff is increased from a value
|
|
of 1.0 in distance units, in increments of 0.1. The looping stops
|
|
when the per-atom potential energy falls below a threshhold of -4.0 in
|
|
energy units. More generally, Python can be used to implement a loop
|
|
with complex logic, much more so than can be created using the LAMMPS
|
|
<a class="reference internal" href="jump.html"><span class="doc">jump</span></a> and <a class="reference internal" href="if.html"><span class="doc">if</span></a> commands.</p>
|
|
<p>Several LAMMPS library functions are called from the loop function.
|
|
Get_natoms() returns the number of atoms in the simulation, so that it
|
|
can be used to normalize the potential energy that is returned by
|
|
extract_compute() for the “thermo_pe” compute that is defined by
|
|
default for LAMMPS thermodynamic output. Set_variable() sets the
|
|
value of a string variable defined in LAMMPS. This library function
|
|
is a useful way for a Python function to return multiple values to
|
|
LAMMPS, more than the single value that can be passed back via a
|
|
return statement. This cutoff value in the “cut” variable is then
|
|
substituted (by LAMMPS) in the pair_style command that is executed
|
|
next. Alternatively, the “LAMMPS command option” line could be used
|
|
in place of the 2 preceeding lines, to have Python insert the value
|
|
into the LAMMPS command string.</p>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">When using the callback mechanism just described, recognize that
|
|
there are some operations you should not attempt because LAMMPS cannot
|
|
execute them correctly. If the Python function is invoked between
|
|
runs in the LAMMPS input script, then it should be OK to invoke any
|
|
LAMMPS input script command via the library interface command() or
|
|
file() functions, so long as the command would work if it were
|
|
executed in the LAMMPS input script directly at the same point.</p>
|
|
</div>
|
|
<p>However, a Python function can also be invoked during a run, whenever
|
|
an associated LAMMPS variable it is assigned to is evaluted. If the
|
|
variable is an input argument to another LAMMPS command (e.g. <a class="reference internal" href="fix_setforce.html"><span class="doc">fix setforce</span></a>), then the Python function will be invoked
|
|
inside the class for that command, in one of its methods that is
|
|
invoked in the middle of a timestep. You cannot execute arbitrary
|
|
input script commands from the Python function (again, via the
|
|
command() or file() functions) at that point in the run and expect it
|
|
to work. Other library functions such as those that invoke computes
|
|
or other variables may have hidden side effects as well. In these
|
|
cases, LAMMPS has no simple way to check that something illogical is
|
|
being attempted.</p>
|
|
<hr class="docutils" />
|
|
<p>If you run Python code directly on your workstation, either
|
|
interactively or by using Python to launch a Python script stored in a
|
|
file, and your code has an error, you will typically see informative
|
|
error messages. That is not the case when you run Python code from
|
|
LAMMPS using an embedded Python interpreter. The code will typically
|
|
fail silently. LAMMPS will catch some errors but cannot tell you
|
|
where in the Python code the problem occurred. For example, if the
|
|
Python code cannot be loaded and run because it has syntax or other
|
|
logic errors, you may get an error from Python pointing to the
|
|
offending line, or you may get one of these generic errors from
|
|
LAMMPS:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Could</span> <span class="ow">not</span> <span class="n">process</span> <span class="n">Python</span> <span class="n">file</span>
|
|
<span class="n">Could</span> <span class="ow">not</span> <span class="n">process</span> <span class="n">Python</span> <span class="n">string</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>When the Python function is invoked, if it does not return properly,
|
|
you will typically get this generic error from LAMMPS:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Python</span> <span class="n">function</span> <span class="n">evaluation</span> <span class="n">failed</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Here are three suggestions for debugging your Python code while
|
|
running it under LAMMPS.</p>
|
|
<p>First, don’t run it under LAMMPS, at least to start with! Debug it
|
|
using plain Python. Load and invoke your function, pass it arguments,
|
|
check return values, etc.</p>
|
|
<p>Second, add Python print statements to the function to check how far
|
|
it gets and intermediate values it calculates. See the discussion
|
|
above about printing from Python when running in parallel.</p>
|
|
<p>Third, use Python exception handling. For example, say this statement
|
|
in your Python function is failing, because you have not initialized the
|
|
variable foo:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">foo</span> <span class="o">+=</span> <span class="mi">1</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>If you put one (or more) statements inside a “try” statement,
|
|
like this:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">exceptions</span>
|
|
<span class="nb">print</span> <span class="s2">"Inside simple function"</span>
|
|
<span class="k">try</span><span class="p">:</span>
|
|
<span class="n">foo</span> <span class="o">+=</span> <span class="mi">1</span> <span class="c1"># one or more statements here</span>
|
|
<span class="k">except</span> <span class="ne">Exception</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span>
|
|
<span class="nb">print</span> <span class="s2">"FOO error:"</span><span class="p">,</span><span class="n">e</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>then you will get this message printed to the screen:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">FOO</span> <span class="n">error</span><span class="p">:</span> <span class="n">local</span> <span class="n">variable</span> <span class="s1">'foo'</span> <span class="n">referenced</span> <span class="n">before</span> <span class="n">assignment</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>If there is no error in the try statements, then nothing is printed.
|
|
Either way the function continues on (unless you put a return or
|
|
sys.exit() in the except clause).</p>
|
|
</div>
|
|
<hr class="docutils" />
|
|
<div class="section" id="restrictions">
|
|
<h2>Restrictions</h2>
|
|
<p>This command is part of the PYTHON package. It is only enabled if
|
|
LAMMPS was built with that package. See the <a class="reference internal" href="Section_start.html#start-3"><span class="std std-ref">Making LAMMPS</span></a> section for more info.</p>
|
|
<p>Building LAMMPS with the PYTHON package will link LAMMPS with the
|
|
Python library on your system. Settings to enable this are in the
|
|
lib/python/Makefile.lammps file. See the lib/python/README file for
|
|
information on those settings.</p>
|
|
<p>If you use Python code which calls back to LAMMPS, via the SELF input
|
|
argument explained above, there is an extra step required when
|
|
building LAMMPS. LAMMPS must also be built as a shared library and
|
|
your Python function must be able to to load the Python module in
|
|
python/lammps.py that wraps the LAMMPS library interface. These are
|
|
the same steps required to use Python by itself to wrap LAMMPS.
|
|
Details on these steps are explained in <span class="xref doc">Section python</span>. Note that it is important that the
|
|
stand-alone LAMMPS executable and the LAMMPS shared library be
|
|
consistent (built from the same source code files) in order for this
|
|
to work. If the two have been built at different times using
|
|
different source files, problems may occur.</p>
|
|
<p>As described above, you can use the python command to invoke a Python
|
|
function which calls back to LAMMPS through its Python-wrapped library
|
|
interface. However you cannot do the opposite. I.e. you cannot call
|
|
LAMMPS from Python and invoke the python command to “callback” to
|
|
Python and execute a Python function. LAMMPS will generate an error
|
|
if you try to do that. Note that we think there actually should be a
|
|
way to do that, but haven’t yet been able to figure out how to do it
|
|
successfully.</p>
|
|
</div>
|
|
<div class="section" id="related-commands">
|
|
<h2>Related commands</h2>
|
|
<p><a class="reference internal" href="shell.html"><span class="doc">shell</span></a>, <a class="reference internal" href="variable.html"><span class="doc">variable</span></a></p>
|
|
<p><strong>Default:</strong> none</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
<footer>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2013 Sandia Corporation.
|
|
</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:'',
|
|
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="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></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> |