git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14950 f3b2605a-c512-4ea7-a41b-209d697bcdaa

doc/src/fix_external.txt

@@ -0,0 +1,154 @@
+"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 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 {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.
+
+The name of the public force array provided by the FixExternal
+class is
+
+double **fexternal; :pre
+
+It is allocated by the FixExternal class as an (N,3) array where N is
+the number of atoms owned by a processor.  The 3 corresponds to the
+fx, fy, fz components of force.
+
+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 fexternal,
+etc.
+
+:line
+
+To use this fix during energy minimization, the energy corresponding
+to the added forces must also be set so as to be consistent with the
+added forces.  Otherwise the minimization will not converge correctly.
+
+This can be done from the external driver by calling this public
+method of the FixExternal class:
+
+void set_energy(double eng); :pre
+
+where eng is the potential energy.  Eng is an extensive quantity,
+meaning it should be the sum over per-atom energies of all affected
+atoms.  It should also be provided in "energy units"_units.html
+consistent with the simulation.  See the details below for how to
+insure this energy setting is used appropriately in a minimization.
+
+:line
+
+[Restart, fix_modify, output, run start/stop, minimize info:]
+
+No information about this fix is written to "binary restart
+files"_restart.html.  
+
+The "fix_modify"_fix_modify.html {energy} 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 "thermodynamic
+output"_thermo_style.html.  This is a fictitious quantity but is
+needed so that the "minimize"_minimize.html 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.
+
+This fix computes a global scalar which can be accessed by various
+"output commands"_Section_howto.html#howto_15.  The scalar is the
+potential energy discussed above.  The scalar stored by this fix
+is "extensive".
+
+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. 
+
+NOTE: 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
+"fix_modify"_fix_modify.html {energy} option for this fix.
+
+[Restrictions:] none
+
+[Related commands:] none
+
+[Default:] none