789 lines
61 KiB
HTML
789 lines
61 KiB
HTML
<!DOCTYPE html>
|
||
<html class="writer-html5" lang="en" >
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||
<title>python command — LAMMPS documentation</title>
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/sphinx-design.min.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/css/lammps.css" type="text/css" />
|
||
<link rel="shortcut icon" href="_static/lammps.ico"/>
|
||
<link rel="canonical" href="https://docs.lammps.org/python.html" />
|
||
<!--[if lt IE 9]>
|
||
<script src="_static/js/html5shiv.min.js"></script>
|
||
<![endif]-->
|
||
|
||
<script src="_static/jquery.js?v=5d32c60e"></script>
|
||
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
|
||
<script src="_static/documentation_options.js?v=5929fcd5"></script>
|
||
<script src="_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
<script src="_static/design-tabs.js?v=f930bc37"></script>
|
||
<script async="async" src="_static/mathjax/es5/tex-mml-chtml.js?v=cadf963e"></script>
|
||
<script src="_static/js/theme.js"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="quit command" href="quit.html" />
|
||
<link rel="prev" title="processors command" href="processors.html" />
|
||
</head>
|
||
|
||
<body class="wy-body-for-nav">
|
||
<div class="wy-grid-for-nav">
|
||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||
<div class="wy-side-scroll">
|
||
<div class="wy-side-nav-search" >
|
||
|
||
|
||
|
||
<a href="Manual.html">
|
||
|
||
<img src="_static/lammps-logo.png" class="logo" alt="Logo"/>
|
||
</a>
|
||
<div class="lammps_version">Version: <b>19 Nov 2024</b></div>
|
||
<div class="lammps_release">git info: </div>
|
||
<div role="search">
|
||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
|
||
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="Intro.html">1. Introduction</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Install.html">2. Install LAMMPS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Build.html">3. Build LAMMPS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Run_head.html">4. Run LAMMPS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Commands.html">5. Commands</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Packages.html">6. Optional packages</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Speed.html">7. Accelerate performance</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Howto.html">8. Howto discussions</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Examples.html">9. Example scripts</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Tools.html">10. Auxiliary tools</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Errors.html">11. Errors</a></li>
|
||
</ul>
|
||
<p class="caption" role="heading"><span class="caption-text">Programmer Guide</span></p>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="Library.html">1. LAMMPS Library Interfaces</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Python_head.html">2. Use Python with LAMMPS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Modify.html">3. Modifying & extending LAMMPS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Developer.html">4. Information for Developers</a></li>
|
||
</ul>
|
||
<p class="caption" role="heading"><span class="caption-text">Command Reference</span></p>
|
||
<ul class="current">
|
||
<li class="toctree-l1 current"><a class="reference internal" href="commands_list.html">Commands</a><ul class="current">
|
||
<li class="toctree-l2"><a class="reference internal" href="angle_coeff.html">angle_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="angle_style.html">angle_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="angle_write.html">angle_write command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="atom_modify.html">atom_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="atom_style.html">atom_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="balance.html">balance command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="bond_coeff.html">bond_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="bond_style.html">bond_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="bond_write.html">bond_write command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="boundary.html">boundary command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="change_box.html">change_box command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="clear.html">clear command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="comm_modify.html">comm_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="comm_style.html">comm_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="compute.html">compute command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="compute_modify.html">compute_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="create_atoms.html">create_atoms command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="create_bonds.html">create_bonds command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="create_box.html">create_box command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="delete_atoms.html">delete_atoms command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="delete_bonds.html">delete_bonds command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dielectric.html">dielectric command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dihedral_coeff.html">dihedral_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dihedral_style.html">dihedral_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dihedral_write.html">dihedral_write command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dimension.html">dimension command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="displace_atoms.html">displace_atoms command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="dynamical_matrix.html">dynamical_matrix command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="echo.html">echo command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="fix.html">fix command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="fix_modify.html">fix_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="fitpod_command.html">fitpod command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="geturl.html">geturl command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="group.html">group command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="group2ndx.html">group2ndx command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="group2ndx.html#ndx2group-command">ndx2group command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="hyper.html">hyper command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="if.html">if command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="improper_coeff.html">improper_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="improper_style.html">improper_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="include.html">include command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="info.html">info command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="jump.html">jump command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="kim_commands.html">kim command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="kspace_modify.html">kspace_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="kspace_style.html">kspace_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="label.html">label command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="labelmap.html">labelmap command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="lattice.html">lattice command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="log.html">log command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="mass.html">mass command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="mdi.html">mdi command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_modify.html">min_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_spin.html">min_style spin command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_spin.html#min-style-spin-cg-command">min_style spin/cg command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_spin.html#min-style-spin-lbfgs-command">min_style spin/lbfgs command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html">min_style cg command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-hftn-command">min_style hftn command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-sd-command">min_style sd command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-quickmin-command">min_style quickmin command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-fire-command">min_style fire command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-spin-command"><span class="xref std std-doc">min_style spin</span> command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-spin-cg-command"><span class="xref std std-doc">min_style spin/cg</span> command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="min_style.html#min-style-spin-lbfgs-command"><span class="xref std std-doc">min_style spin/lbfgs</span> command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="minimize.html">minimize command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="molecule.html">molecule command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="neb.html">neb command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="neb_spin.html">neb/spin command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="neigh_modify.html">neigh_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="neighbor.html">neighbor command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="newton.html">newton command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="next.html">next command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="package.html">package command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="pair_coeff.html">pair_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="pair_modify.html">pair_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="pair_style.html">pair_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="pair_write.html">pair_write command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="partition.html">partition command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="plugin.html">plugin command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="prd.html">prd command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="print.html">print command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="processors.html">processors command</a></li>
|
||
<li class="toctree-l2 current"><a class="current reference internal" href="#">python command</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#syntax">Syntax</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#description">Description</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#restrictions">Restrictions</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#related-commands">Related commands</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#default">Default</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="quit.html">quit command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="read_data.html">read_data command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="read_dump.html">read_dump command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="read_restart.html">read_restart command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="region.html">region command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="replicate.html">replicate command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="rerun.html">rerun command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="reset_atoms.html">reset_atoms command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="reset_timestep.html">reset_timestep command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="restart.html">restart command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="run.html">run command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="run_style.html">run_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="set.html">set command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="shell.html">shell command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="special_bonds.html">special_bonds command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="suffix.html">suffix command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="tad.html">tad command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="temper.html">temper command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="temper_grem.html">temper/grem command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="temper_npt.html">temper/npt command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="thermo.html">thermo command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="thermo_modify.html">thermo_modify command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="thermo_style.html">thermo_style command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="third_order.html">third_order command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="timer.html">timer command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="timestep.html">timestep command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="uncompute.html">uncompute command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="undump.html">undump command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="unfix.html">unfix command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="units.html">units command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="variable.html">variable command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="velocity.html">velocity command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="write_coeff.html">write_coeff command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="write_data.html">write_data command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="write_dump.html">write_dump command</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="write_restart.html">write_restart command</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="fixes.html">Fix Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="computes.html">Compute Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="pairs.html">Pair Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="bonds.html">Bond Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="angles.html">Angle Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="dihedrals.html">Dihedral Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="impropers.html">Improper Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="dumps.html">Dump Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="fix_modify_atc_commands.html">fix_modify AtC commands</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="Bibliography.html">Bibliography</a></li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
|
||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||
<a href="Manual.html">LAMMPS</a>
|
||
</nav>
|
||
|
||
<div class="wy-nav-content">
|
||
<div class="rst-content style-external-links">
|
||
<div role="navigation" aria-label="Page navigation">
|
||
<ul class="wy-breadcrumbs">
|
||
<li><a href="Manual.html" class="icon icon-home" aria-label="Home"></a></li>
|
||
<li class="breadcrumb-item"><a href="commands_list.html">Commands</a></li>
|
||
<li class="breadcrumb-item active">python command</li>
|
||
<li class="wy-breadcrumbs-aside">
|
||
<a href="https://www.lammps.org"><img src="_static/lammps-logo.png" width="64" height="16" alt="LAMMPS Homepage"></a> | <a href="Commands_all.html">Commands</a>
|
||
</li>
|
||
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
|
||
<a href="processors.html" class="btn btn-neutral float-left" title="processors command" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="quit.html" class="btn btn-neutral float-right" title="quit command" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||
</div>
|
||
<hr/>
|
||
</div>
|
||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||
<div itemprop="articleBody">
|
||
|
||
<p><span class="math notranslate nohighlight">\(\renewcommand{\AA}{\text{Å}}\)</span></p>
|
||
<section id="python-command">
|
||
<span id="index-0"></span><h1>python command<a class="headerlink" href="#python-command" title="Link to this heading"></a></h1>
|
||
<section id="syntax">
|
||
<h2>Syntax<a class="headerlink" href="#syntax" title="Link to this heading"></a></h2>
|
||
<div class="highlight-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="w"> </span><span class="n">mode</span><span class="w"> </span><span class="n">keyword</span><span class="w"> </span><span class="n">args</span><span class="w"> </span><span class="n">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<ul>
|
||
<li><p>mode = <em>source</em> or name of Python function</p>
|
||
<p>if mode is <em>source</em>:</p>
|
||
<pre class="literal-block">keyword = <em>here</em> or name of a <em>Python file</em>
|
||
<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>Python file</em> = name of a file with Python code which will be executed immediately</pre>
|
||
</li>
|
||
<li><p>if <em>mode</em> is the name of a Python function, one or more keywords with/without arguments must be appended</p>
|
||
<pre class="literal-block">keyword = <em>invoke</em> or <em>input</em> or <em>return</em> or <em>format</em> or <em>length</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 the return value of the Python 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>length</em> arg = Nlen
|
||
Nlen = max length of string returned from Python function
|
||
<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>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="examples">
|
||
<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
|
||
<div class="highlight-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="w"> </span><span class="n">pForce</span><span class="w"> </span><span class="n">input</span><span class="w"> </span><span class="m">2</span><span class="w"> </span><span class="n">v_x</span><span class="w"> </span><span class="m">20.0</span><span class="w"> </span><span class="n">return</span><span class="w"> </span><span class="n">v_f</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">fff</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="n">force.py</span>
|
||
<span class="k">python</span><span class="w"> </span><span class="n">pForce</span><span class="w"> </span><span class="n">invoke</span>
|
||
|
||
<span class="k">python</span><span class="w"> </span><span class="n">factorial</span><span class="w"> </span><span class="n">input</span><span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="n">myN</span><span class="w"> </span><span class="n">return</span><span class="w"> </span><span class="n">v_fac</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">ii</span><span class="w"> </span><span class="n">here</span><span class="w"> </span><span class="s">"""</span>
|
||
<span class="s">def factorial(n):</span>
|
||
<span class="s"> if n == 1: return n</span>
|
||
<span class="s"> return n * factorial(n-1)</span>
|
||
<span class="s"> """</span>
|
||
|
||
<span class="k">python</span><span class="w"> </span><span class="n">loop</span><span class="w"> </span><span class="n">input</span><span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="n">SELF</span><span class="w"> </span><span class="n">return</span><span class="w"> </span><span class="n">v_value</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">pf</span><span class="w"> </span><span class="n">here</span><span class="w"> </span><span class="s">"""</span>
|
||
<span class="s">def loop(lmpptr,N,cut0):</span>
|
||
<span class="s"> from lammps import lammps</span>
|
||
<span class="s"> lmp = lammps(ptr=lmpptr)</span>
|
||
|
||
<span class="s"> # loop N times, increasing cutoff each time</span>
|
||
|
||
<span class="s"> for i in range(N):</span>
|
||
<span class="s"> cut = cut0 + i*0.1</span>
|
||
<span class="s"> lmp.set_variable("</span><span class="n">cut</span><span class="s">",cut) # set a variable in LAMMPS</span>
|
||
<span class="s"> lmp.command("</span><span class="n">pair_style</span><span class="w"> </span><span class="n">lj</span><span class="o">/</span><span class="n">cut</span><span class="w"> </span><span class="nv">${cut}</span><span class="s">") # LAMMPS commands</span>
|
||
<span class="s"> lmp.command("</span><span class="n">pair_coeff</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="m">1.0</span><span class="w"> </span><span class="m">1.0</span><span class="s">")</span>
|
||
<span class="s"> lmp.command("</span><span class="n">run</span><span class="w"> </span><span class="m">100</span><span class="s">")</span>
|
||
<span class="s">"""</span>
|
||
|
||
<span class="k">python</span><span class="w"> </span><span class="n">source</span><span class="w"> </span><span class="n">funcdef.py</span>
|
||
|
||
<span class="k">python</span><span class="w"> </span><span class="n">source</span><span class="w"> </span><span class="n">here</span><span class="w"> </span><span class="s">"from lammps import lammps"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="description">
|
||
<h2>Description<a class="headerlink" href="#description" title="Link to this heading"></a></h2>
|
||
<p>The <em>python</em> command allows interfacing LAMMPS with an embedded Python
|
||
interpreter and enables either executing arbitrary python code in that
|
||
interpreter, registering a Python function for future execution (as a
|
||
python style variable, from a fix interfaced with python, or for direct
|
||
invocation), or invoking such a previously registered function.</p>
|
||
<p>Arguments, including LAMMPS variables, can be passed to the function
|
||
from the LAMMPS input script and a value returned by the Python function
|
||
assigned 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
|
||
registered. 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 with their result 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 the
|
||
<a class="reference internal" href="Python_head.html"><span class="doc">Use Python with LAMMPS</span></a> section of the
|
||
documentation. There also is an <code class="docutils literal notranslate"><span class="pre">examples/python</span></code> directory which
|
||
illustrates use of the python command.</p>
|
||
<hr class="docutils" />
|
||
<p>The first argument of the <em>python</em> command is either the <em>source</em>
|
||
keyword or the name of a Python function. This defines the mode
|
||
of the python command.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 22Dec2022.</span></p>
|
||
</div>
|
||
<p>If the <em>source</em> keyword is used, it is followed by either a file name or
|
||
the <em>here</em> keyword. No other keywords can be used. The <em>here</em> keyword
|
||
is followed by a string with python commands, either on a single line
|
||
enclosed in quotes, or as multiple lines enclosed in triple quotes.
|
||
These Python commands will be passed to the python interpreter and
|
||
executed immediately without registering a Python function for future
|
||
execution. The code will be loaded into and run in the “main” module of
|
||
the Python interpreter. This allows running arbitrary Python code at
|
||
any time while processing the LAMMPS input file. This can be used to
|
||
pre-load Python modules, initialize global variables, define functions
|
||
or classes, or perform operations using the python programming language.
|
||
The Python code will be executed in parallel on all MPI processes. No
|
||
arguments can be passed.</p>
|
||
<p>In all other cases, the first argument is the name of a Python function
|
||
that will be registered with LAMMPS for future execution. The function
|
||
may already be defined (see <em>exists</em> keyword) or must be 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 <em>python</em> command must have registered the Python function
|
||
referenced by this command. This invokes the Python function with the
|
||
previously defined arguments and the return value is 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 can convert into a reference to LAMMPS
|
||
itself using the <a class="reference internal" href="Python_module.html"><span class="doc">LAMMPS Python module</span></a>. 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 returning a scalar or a string can be used,
|
||
as defined by the <a class="reference internal" href="variable.html"><span class="doc">variable</span></a> command. The <em>format</em>
|
||
keyword must be used to set the type of data that is passed to Python.
|
||
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>Python function name</em> first argument of
|
||
the <em>python</em> command. For example these two commands would be
|
||
consistent:</p>
|
||
<div class="highlight-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">variable </span><span class="nv nv-Identifier">foo</span><span class="w"> </span><span class="n">python</span><span class="w"> </span><span class="n">myMultiply</span>
|
||
<span class="k">python</span><span class="w"> </span><span class="n">myMultiply</span><span class="w"> </span><span class="n">return</span><span class="w"> </span><span class="n">v_foo</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">f</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="n">funcs.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. Afterwards, the variable ‘foo’ is associated with
|
||
the Python function ‘myMultiply’.</p>
|
||
<p>The <em>format</em> keyword must be used if the <em>input</em> or <em>return</em> keywords
|
||
are 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>If the <em>return</em> keyword is used and the <em>format</em> keyword specifies the
|
||
output as a string, then the default maximum length of that string is
|
||
63 characters (64-1 for the string terminator). If you want to return
|
||
a longer string, the <em>length</em> keyword can be specified with its <em>Nlen</em>
|
||
value set to a larger number (the code allocates space for Nlen+1 to
|
||
include the string terminator). If the Python function generates a
|
||
string longer than the default 63 or the specified <em>Nlen</em>, it will be
|
||
truncated.</p>
|
||
<hr class="docutils" />
|
||
<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
|
||
containing Python code, which should end with a “.py” suffix. The code
|
||
will be immediately loaded into and run in the “main” module of the
|
||
Python interpreter. The Python code will be executed in parallel on all
|
||
MPI processes. 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 the
|
||
<a class="reference internal" href="Commands_parse.html"><span class="doc">Commands parse</span></a> doc page, 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 with the given name has already
|
||
been executed, for example by a <em>python source</em> command or in the same
|
||
file that was used previously with the <em>file</em> keyword.</p>
|
||
<p>Note that the Python code that is loaded and run must contain a function
|
||
with the specified function name. To operate properly when later
|
||
invoked, 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. <code class="docutils literal notranslate"><span class="pre">__name__</span> <span class="pre">==</span> <span class="pre">'__main__'</span></code>.
|
||
The code can define global variables, define global functions, define
|
||
classes or execute 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 register the other functions
|
||
that were previously loaded with LAMMPS.</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-python notranslate"><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>
|
||
|
||
<span class="k">def</span><span class="w"> </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>The variable ‘nsteplast’ stores the previous timestep the function was
|
||
invoked (passed as an argument to the function). The variable
|
||
‘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 from within the local context of the function.</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 or other statement creating output to the
|
||
screen 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. When loading
|
||
the LAMMPS Python module into the embedded Python interpreter, it is
|
||
possible to pass the pointer to the current LAMMPS class instance and
|
||
via the Python interface to the LAMMPS library interface, it is possible
|
||
to determine the MPI rank of the current process and thus adapt the
|
||
Python code so that output will only appear on MPI rank 0. The
|
||
following LAMMPS input demonstrates how this could be done. The text
|
||
‘Hello, LAMMPS!’ should be printed only once, even when running LAMMPS
|
||
in parallel.</p>
|
||
<div class="highlight-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="w"> </span><span class="n">python_hello</span><span class="w"> </span><span class="n">input</span><span class="w"> </span><span class="m">1</span><span class="w"> </span><span class="n">SELF</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">p</span><span class="w"> </span><span class="n">here</span><span class="w"> </span><span class="s">"""</span>
|
||
<span class="s">def python_hello(handle):</span>
|
||
<span class="s"> from lammps import lammps</span>
|
||
<span class="s"> lmp = lammps(ptr=handle)</span>
|
||
<span class="s"> me = lmp.extract_setting('world_rank')</span>
|
||
<span class="s"> if me == 0:</span>
|
||
<span class="s"> print('Hello, LAMMPS!')</span>
|
||
<span class="s">"""</span>
|
||
|
||
<span class="k">python</span><span class="w"> </span><span class="n">python_hello</span><span class="w"> </span><span class="n">invoke</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>If your Python code loads Python 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 ensure 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-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="n">handle</span><span class="p">,</span><span class="o">...</span><span class="p">):</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">lammps</span><span class="w"> </span><span class="kn">import</span> <span class="n">lammps</span>
|
||
<span class="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">handle</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 (‘handle’ in this case)
|
||
which corresponds to SELF in the <em>python</em> command. The first line of
|
||
the function imports the <a class="reference internal" href="Python_module.html"><span class="doc">“lammps” Python module</span></a>.
|
||
The second line creates a Python object <code class="docutils literal notranslate"><span class="pre">lmp</span></code> which wraps the instance
|
||
of LAMMPS that called the function. The ‘ptr=handle’ argument is what
|
||
makes that happen. The third 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-none notranslate"><div class="highlight"><pre><span></span>Hello from inside Python
|
||
</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>The <a class="reference internal" href="Python_head.html"><span class="doc">Use Python with LAMMPS</span></a> page 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 <code class="docutils literal notranslate"><span class="pre">examples/python/in.python</span></code> script
|
||
which loads and runs the following function from <code class="docutils literal notranslate"><span class="pre">examples/python/funcs.py</span></code>:</p>
|
||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </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="p">(</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="p">)</span>
|
||
<span class="kn">from</span><span class="w"> </span><span class="nn">lammps</span><span class="w"> </span><span class="kn">import</span> <span class="n">lammps</span>
|
||
<span class="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>
|
||
|
||
<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 command</span>
|
||
<span class="c1">#lmp.command("pair_style lj/cut %d" % cut) # LAMMPS command option</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="p">(</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="p">)</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-LAMMPS notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="w"> </span><span class="n">loop</span><span class="w"> </span><span class="n">input</span><span class="w"> </span><span class="m">4</span><span class="w"> </span><span class="m">10</span><span class="w"> </span><span class="m">1.0</span><span class="w"> </span><span class="o">-</span><span class="m">4.0</span><span class="w"> </span><span class="n">SELF</span><span class="w"> </span><span class="n">format</span><span class="w"> </span><span class="n">iffp</span><span class="w"> </span><span class="n">file</span><span class="w"> </span><span class="n">funcs.py</span>
|
||
<span class="k">python</span><span class="w"> </span><span class="n">loop</span><span class="w"> </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 threshold 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 preceding lines, to have Python insert the value
|
||
into the LAMMPS command string.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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 evaluated. 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>
|
||
<p>The same applies to Python functions called during a simulation run at
|
||
each time step using <a class="reference internal" href="fix_python_invoke.html"><span class="doc">fix python/invoke</span></a>.</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-none notranslate"><div class="highlight"><pre><span></span>Could not process Python file
|
||
Could not process Python string
|
||
</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-none notranslate"><div class="highlight"><pre><span></span>Python function evaluation failed
|
||
</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-python notranslate"><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-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">exceptions</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"Inside simple function"</span><span class="p">)</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="k">as</span> <span class="n">e</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"FOO error:"</span><span class="p">,</span> <span class="n">e</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>then you will get this message printed to the screen:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>FOO error: local variable 'foo' referenced before assignment
|
||
</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>
|
||
</section>
|
||
<hr class="docutils" />
|
||
<section id="restrictions">
|
||
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Link to this heading"></a></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="Build_package.html"><span class="doc">Build package</span></a> page 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 load the <a class="reference internal" href="Python_module.html"><span class="doc">“lammps” Python module</span></a> 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 on the <a class="reference internal" href="Python_head.html"><span class="doc">Python</span></a> doc page.
|
||
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>Another limitation of calling back to Python from the LAMMPS module
|
||
using the <em>python</em> command in a LAMMPS input is that both, the Python
|
||
interpreter and LAMMPS, must be linked to the same Python runtime as a
|
||
shared library. If the Python interpreter is linked to Python
|
||
statically (which seems to happen with Conda) then loading the shared
|
||
LAMMPS library will create a second python “main” module that hides the
|
||
one from the Python interpreter and all previous defined function and
|
||
global variables will become invisible.</p>
|
||
</section>
|
||
<section id="related-commands">
|
||
<h2>Related commands<a class="headerlink" href="#related-commands" title="Link to this heading"></a></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>, <a class="reference internal" href="fix_python_invoke.html"><span class="doc">fix python/invoke</span></a></p>
|
||
</section>
|
||
<section id="default">
|
||
<h2>Default<a class="headerlink" href="#default" title="Link to this heading"></a></h2>
|
||
<p>none</p>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
|
||
<a href="processors.html" class="btn btn-neutral float-left" title="processors command" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
|
||
<a href="quit.html" class="btn btn-neutral float-right" title="quit command" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
|
||
</div>
|
||
|
||
<hr/>
|
||
|
||
<div role="contentinfo">
|
||
<p>© Copyright 2003-2025 Sandia Corporation.</p>
|
||
</div>
|
||
|
||
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
|
||
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
|
||
provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
||
|
||
|
||
</footer>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
</div>
|
||
<script>
|
||
jQuery(function () {
|
||
SphinxRtdTheme.Navigation.enable(false);
|
||
});
|
||
</script>
|
||
|
||
</body>
|
||
</html> |