"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)
:link(ld,Manual.html)
:link(lc,Section_commands.html#comm)

:line

fix external command :h3

[Syntax:]

fix ID group-ID external mode args :pre

ID, group-ID are documented in "fix"_fix.html command :ulb,l
external = style name of this fix command :l
mode = {pf/callback} or {pf/array} :l
  {pf/callback} args = Ncall Napply
    Ncall = make callback every Ncall steps
    Napply = apply callback forces every Napply steps
  {pf/array} args = Napply
    Napply = apply array forces every Napply steps :pre
:ule

[Examples:]

fix 1 all external pf/callback 1 1
fix 1 all external pf/callback 100 1
fix 1 all external pf/array 10 :pre

[Description:]

This fix allows external programs that are running LAMMPS through its
"library interface"_Section_howto.html#howto_19 to modify certain
LAMMPS properties on specific timesteps, similar to the way other
fixes do.  The external driver can be a "C/C++ or Fortran
program"_Section_howto.html#howto_19 or a "Python
script"_Section_python.html.

:line

If mode is {pf/callback} then the fix will make a callback every
{Ncall} timesteps or minimization iteration 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 {Napply} steps, similar to the way the "fix
addforce"_fix_addforce.html command works.  Note that if {Ncall} >
{Napply}, the force values produced by one callback will persist, and
be used multiple times to update atom forces.

The callback function "foo" is invoked by the fix as:

foo(void *ptr, bigint timestep, int nlocal, int *ids, double **x, double **fexternal); :pre

The arguments are as follows:

ptr = pointer provided by and simply passed back to external driver
timestep = current LAMMPS timestep
nlocal = # of atoms on this processor
ids = list of atom IDs on this processor
x = coordinates of atoms on this processor
fexternal = forces to add to atoms on this processor :ul

Note that timestep is a "bigint" which is defined in src/lmptype.h,
typically as a 64-bit integer.

Fexternal are the forces returned by the driver program.

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
code "Quest"_quest.

:link(quest,http://dft.sandia.gov/Quest)

:line

If mode is {pf/array} then the fix simply stores force values in an
array.  The fix adds these forces to each atom in the group, once
every {Napply} steps, similar to the way the "fix
addforce"_fix_addforce.html command works.

It is up to the external program to set the values in this array to
the desired quantities, as often as desired.  For example, the driver
program might perform an MD run in stages of 1000 timesteps each.  In
between calls to the LAMMPS "run"_run.html command, it could retrieve
atom coordinates from LAMMPS, compute forces, set values in the fix
external array, etc.

:line

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart
files"_restart.html.  None of the "fix_modify"_fix_modify.html options
are relevant to this fix.  No global or per-atom quantities are stored
by this fix for access by various "output
commands"_Section_howto.html#howto_15.  No parameter of this fix can
be used with the {start/stop} keywords of the "run"_run.html command.

The forces due to this fix are imposed during an energy minimization,
invoked by the "minimize"_minimize.html command.  However, LAMMPS
knows nothing about the energy associated with these forces.  So you
should perform the minimization based on a force tolerance, not an
energy tolerance.

[Restrictions:] none

[Related commands:] none

[Default:] none
