Merge pull request #165 from choderalab/external_perturbation_fix

Simplifying NCMC with ExternalPerturbationLangevinIntegrator

openmmtools/integrators.py

@@ -1520,7 +1520,20 @@ def reset_integrator(self):
 
 
 class ExternalPerturbationLangevinIntegrator(LangevinIntegrator):
-    """LangevinSplittingIntegrator that accounts for external perturbations and tracks protocol work."""
+    """
+    LangevinSplittingIntegrator that accounts for external perturbations and tracks protocol work. An example of an
+    external perturbation could be changing the forcefield parameters via
+
+    > force.setParticleParameters(...)
+    > force.updateParametersInContext(context)
+
+    where force is an instance of openmm's force class. The externally performed protocol work is accumulated in the
+    "protocol_work" global variable. This variable can be re-initialized with
+
+    > integrator.setGlobalVariableByName("first_step", 0)
+
+    where integrator is an instance of ExternalPerturbationLangevinIntegrator.
+    """
 
     def __init__(self,
                  splitting="V R O R V",
@@ -1551,6 +1564,7 @@ def add_integrator_steps(self, splitting, measure_shadow_work, measure_heat, ORV
         self.beginIfBlock("first_step < 1")
         self.addComputeGlobal("first_step", "1")
         self.addComputeGlobal("unperturbed_pe", "energy")
+        self.addComputeGlobal("protocol_work", "0.0")
         self.endBlock()
         self.addComputeGlobal("protocol_work", "protocol_work + (perturbed_pe - unperturbed_pe)")
         super(ExternalPerturbationLangevinIntegrator, self).add_integrator_steps(splitting, measure_shadow_work, measure_heat, ORV_counts, force_group_nV, mts)