<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>
<pre class="literal-block">
variable foo python myMultiply
python myMultiply return v_foo format f file funcs.py
</pre>
<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
<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
<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 <a class="reference internal" href="Section_python.html"><span class="doc">Section python</span></a>. 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
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>.