From 93f6033061261b7165151d66e54d8a83e220ba1a Mon Sep 17 00:00:00 2001
From: Richard Berger <richard.berger@temple.edu>
Date: Thu, 11 May 2017 23:45:49 -0400
Subject: [PATCH] Add documentation about fix python

---
 doc/src/Section_python.txt |  3 +-
 doc/src/fix_python.txt     | 75 ++++++++++++++++++++++++++++++++++++++
 doc/src/fixes.txt          |  1 +
 doc/src/python.txt         |  5 ++-
 4 files changed, 82 insertions(+), 2 deletions(-)
 create mode 100644 doc/src/fix_python.txt

diff --git a/doc/src/Section_python.txt b/doc/src/Section_python.txt
index 8bdd101b3d..5d366f6b6c 100644
--- a/doc/src/Section_python.txt
+++ b/doc/src/Section_python.txt
@@ -155,7 +155,8 @@ commands.
 See the "python"_python.html doc page and the "variable"_variable.html
 doc page for its python-style variables for more info, including
 examples of Python code you can write for both pure Python operations
-and callbacks to LAMMPS.
+and callbacks to LAMMPS. See "fix python"_fix_python.html to learn about
+possibilities to execute Python code during each time step.
 
 To run pure Python code from LAMMPS, you only need to build LAMMPS
 with the PYTHON package installed:
diff --git a/doc/src/fix_python.txt b/doc/src/fix_python.txt
new file mode 100644
index 0000000000..f69ff41bfa
--- /dev/null
+++ b/doc/src/fix_python.txt
@@ -0,0 +1,75 @@
+"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 python command :h3
+
+[Syntax:]
+
+fix ID group-ID python callback function_name :pre
+
+ID, group-ID are ignored by this fix :ulb,l
+python = style name of this fix command :l
+callback = {post_force} or {end_of_step} :l
+  {post_force} = callback after force computations on atoms
+  {end_of_step} = callback after each time step :pre
+:ule
+
+[Examples:]
+
+python post_force_callback here """
+from lammps import lammps :pre
+
+def post_force_callback(lammps_ptr, vflag):
+    lmp = lammps(ptr=lammps_ptr)
+    # access LAMMPS state using Python interface
+""" :pre
+
+python end_of_step_callback here """
+def end_of_step_callback(lammps_ptr):
+    lmp = lammps(ptr=lammps_ptr)
+    # access LAMMPS state using Python interface
+""" :pre
+
+fix pf  all python post_force post_force_callback
+fix eos all python end_of_step end_of_step_callback :pre
+
+[Description:]
+
+This fix allows you to call a Python function during a simulation run.
+The callback is either executed after forces have been applied to atoms
+or at the end of each time step.
+
+Callback functions must be declared in the global scope of the
+active Python interpreter. This can either be done by defining it
+inline using the python command or by importing functions from other
+Python modules. If LAMMPS is driven using the library interface from
+Python, functions defined in the driving Python interpreter can also
+be executed.
+
+Each callback is given a pointer object as first argument. This can be
+used to initialize an instance of the lammps Python interface, which
+gives access to the LAMMPS state from Python.
+
+IMPORTANT NOTE: While you can access the state of LAMMPS via library functions
+from these callbacks, trying to execute input script commands will in the best
+case not work or in the worst case result in undefined behavior.
+
+[Restrictions:]
+
+This fix is part of the PYTHON package.  It is only enabled if
+LAMMPS was built with that package.  See the "Making
+LAMMPS"_Section_start.html#start_3 section for more info.
+
+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.
+
+[Related commands:]
+
+"python command"_python.html
diff --git a/doc/src/fixes.txt b/doc/src/fixes.txt
index e8777d4113..ce73ed99e3 100644
--- a/doc/src/fixes.txt
+++ b/doc/src/fixes.txt
@@ -111,6 +111,7 @@ Fixes :h1
    fix_press_berendsen
    fix_print
    fix_property_atom
+   fix_python
    fix_qbmsst
    fix_qeq
    fix_qeq_comb
diff --git a/doc/src/python.txt b/doc/src/python.txt
index 748d01c2ae..e00b90234c 100644
--- a/doc/src/python.txt
+++ b/doc/src/python.txt
@@ -405,6 +405,9 @@ 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.
 
+The same applies to Python functions called during a simulation run at
+each time step using "fix python"_fix_python.html.
+
 :line
 
 If you run Python code directly on your workstation, either
@@ -490,6 +493,6 @@ different source files, problems may occur.
 
 [Related commands:]
 
-"shell"_shell.html, "variable"_variable.html
+"shell"_shell.html, "variable"_variable.html, "fix python"_fix_python.html
 
 [Default:] none