<spanid="index-0"></span><h1>fix external command<aclass="headerlink"href="#fix-external-command"title="Permalink to this headline">¶</a></h1>
<divclass="section"id="syntax">
<h2>Syntax<aclass="headerlink"href="#syntax"title="Permalink to this headline">¶</a></h2>
<divclass="highlight-python"><divclass="highlight"><pre>fix ID group-ID external mode args
</pre></div>
</div>
<ulclass="simple">
<li>ID, group-ID are documented in <aclass="reference internal"href="fix.html"><em>fix</em></a> command</li>
<li>external = style name of this fix command</li>
<li>mode = <em>pf/callback</em> or <em>pf/array</em></li>
</ul>
<preclass="literal-block">
<em>pf/callback</em> args = Ncall Napply
Ncall = make callback every Ncall steps
Napply = apply callback forces every Napply steps
<em>pf/array</em> args = Napply
Napply = apply array forces every Napply steps
</pre>
</div>
<divclass="section"id="examples">
<h2>Examples<aclass="headerlink"href="#examples"title="Permalink to this headline">¶</a></h2>
<divclass="highlight-python"><divclass="highlight"><pre>fix 1 all external pf/callback 1 1
fix 1 all external pf/callback 100 1
fix 1 all external pf/array 10
</pre></div>
</div>
</div>
<divclass="section"id="description">
<h2>Description<aclass="headerlink"href="#description"title="Permalink to this headline">¶</a></h2>
<p>This fix allows external programs that are running LAMMPS through its
<aclass="reference internal"href="Section_howto.html#howto-19"><span>library interface</span></a> to modify certain
LAMMPS properties on specific timesteps, similar to the way other
fixes do. The external driver can be a <aclass="reference internal"href="Section_howto.html#howto-19"><span>C/C++ or Fortran program</span></a> or a <aclass="reference internal"href="Section_python.html"><em>Python script</em></a>.</p>
<hrclass="docutils"/>
<p>If mode is <em>pf/callback</em> then the fix will make a callback every
<em>Ncall</em> timesteps or minimization iterations to the external program.
The external program computes forces on atoms by setting values in an
array owned by the fix. The fix then adds these forces to each atom
in the group, once every <em>Napply</em> steps, similar to the way the <aclass="reference internal"href="fix_addforce.html"><em>fix addforce</em></a> command works. Note that if <em>Ncall</em>>
<em>Napply</em>, the force values produced by one callback will persist, and
be used multiple times to update atom forces.</p>
<p>The callback function “foo” is invoked by the fix as:</p>
<divclass="highlight-python"><divclass="highlight"><pre>foo(void *ptr, bigint timestep, int nlocal, int *ids, double **x, double **fexternal);
</pre></div>
</div>
<p>The arguments are as follows:</p>
<ulclass="simple">
<li>ptr = pointer provided by and simply passed back to external driver</li>
<li>timestep = current LAMMPS timestep</li>
<li>nlocal = # of atoms on this processor</li>
<li>ids = list of atom IDs on this processor</li>
<li>x = coordinates of atoms on this processor</li>
<li>fexternal = forces to add to atoms on this processor</li>
</ul>
<p>Note that timestep is a “bigint” which is defined in src/lmptype.h,
typically as a 64-bit integer.</p>
<p>Fexternal are the forces returned by the driver program.</p>
<p>The fix has a set_callback() method which the external driver can call
to pass a pointer to its foo() function. See the
couple/lammps_quest/lmpqst.cpp file in the LAMMPS distribution for an
example of how this is done. This sample application performs
classical MD using quantum forces computed by a density functional
<h2>Restart, fix_modify, output, run start/stop, minimize info<aclass="headerlink"href="#restart-fix-modify-output-run-start-stop-minimize-info"title="Permalink to this headline">¶</a></h2>
<p>No information about this fix is written to <aclass="reference internal"href="restart.html"><em>binary restart files</em></a>.</p>
<p>The <aclass="reference internal"href="fix_modify.html"><em>fix_modify</em></a><em>energy</em> option is supported by this
fix to add the potential “energy” set by the external driver to the
system’s potential energy as part of <aclass="reference internal"href="thermo_style.html"><em>thermodynamic output</em></a>. This is a fictitious quantity but is
needed so that the <aclass="reference internal"href="minimize.html"><em>minimize</em></a> command can include the
forces added by this fix in a consistent manner. I.e. there is a
decrease in potential energy when atoms move in the direction of the
added force.</p>
<p>This fix computes a global scalar which can be accessed by various
<aclass="reference internal"href="Section_howto.html#howto-15"><span>output commands</span></a>. The scalar is the
potential energy discussed above. The scalar stored by this fix
is “extensive”.</p>
<p>No parameter of this fix can be used with the <em>start/stop</em> keywords of
the <aclass="reference internal"href="run.html"><em>run</em></a> command.</p>
<p>The forces due to this fix are imposed during an energy minimization,
invoked by the <aclass="reference internal"href="minimize.html"><em>minimize</em></a> command.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">If you want the fictitious potential energy associated with the
added forces to be included in the total potential energy of the
system (the quantity being minimized), you MUST enable the
<aclass="reference internal"href="fix_modify.html"><em>fix_modify</em></a><em>energy</em> option for this fix.</p>
</div>
</div>
<divclass="section"id="restrictions">
<h2>Restrictions<aclass="headerlink"href="#restrictions"title="Permalink to this headline">¶</a></h2>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.