Syntax:
fix ID group-ID external mode args
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
Examples:
fix 1 all external pf/callback 1 1 fix 1 all external pf/callback 100 1 fix 1 all external pf/array 10
Description:
This fix allows external programs that are running LAMMPS through its library interface 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 or a Python script.
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 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);
The arguments are as follows:
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.
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 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 command, it could retrieve atom coordinates from LAMMPS, compute forces, set values in the fix external array, etc.
Restart, fix_modify, output, run start/stop, minimize info:
No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command.
The forces due to this fix are imposed during an energy minimization, invoked by the minimize 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