Error in ExternalPerturbationLangevinIntegrator protocol_work handling

The ExternalPerturbationLangevinIntegrator doesn’t handle the protocol work correctly for the first step because the first time add_integrator steps is called the “protocol_work” variable is still set to 0. https://github.com/choderalab/openmmtools/blob/master/openmmtools/integrators.py#L1547-L1551

Here’s a short code snippet that reproduces the error:

from simtk import unit, openmm
from openmmtools import testsystems
from openmmtools.integrators import ExternalPerturbationLangevinIntegrator
testsystem = testsystems.AlanineDipeptideVacuum()
temperature = 300.0*unit.kelvin
md_integrator = ExternalPerturbationLangevinIntegrator()
md_simulation = openmm.app.simulation.Simulation(topology=testsystem.topology, system=testsystem.system, integrator=md_integrator)
md_simulation.context.setPositions(testsystem.positions)
md_simulation.context.setVelocitiesToTemperature(temperature)
nstepsMD = 10
niter = 4
for iter in range(niter):
    print('BEFORE step')
    print('protocol_work', md_integrator.getGlobalVariableByName('protocol_work'))
    md_simulation.step(nstepsMD)
    print('AFTER')
    print('protocol_work', md_integrator.getGlobalVariableByName('protocol_work'))

Output:

('BEFORE step')
('total', 0.0)
AFTER
('total', -88.08856348693371)
('BEFORE step')
('total', -88.08856348693371)
AFTER
('total', -88.08856348693371)

[jchodera]

I think it’s actually totally reasonable to discuss what the appropriate logical way for people to use these integrators should be, especially after getting some feedback from external users. If we want people to use these methods, find them convenient, and make few errors in doing so, ensuring we’ve presented them in the right way is not a waste of time.

• At the very least, the naming conventions need to make clear the difference between NonequilibriumLangevinIntegrator and ExternalPerturbationLangevinIntegrator. Both are nonequilibrium integrators, but they handle the Hamiltonian updates differently.
• @bas-rustenburg even got the name of ExternalPerturbationLangevinIntegrator wrong in his talk today, so naming could clearly benefit from some refinement
• Classes are meant to encapsulate related functionality into a single convenient place. Considerations of code complexity are somewhat secondary if we’re only talking about a few lines.
• Moving the work tracking code to another function of NonequilibriumIntegrator also maintains encapsulation of the relevant code into separate function modules, and in fact would reduce code duplication. All one would need to do in updateProtocolWork(context) would be to add

self.addComputeGlobal("old_pe", "energy") # update old enrgy
self.addComputeGlobal("protocol_work", "(old_pe - new_pe)")

and make sure measure_shadow_work is True.

We can discuss more when I get back.

[bas-rustenburg]

The updateProtocolWork method could work. I have no need for it, but if someone else wants to implement that, please go ahead. I’d prefer to keep the ExternalPerturbationLangevinIntegrator as a separate class though, so please DO NOT unify it with the NonEquilibriumLangevinIntegrator.

I don’t know why this keeps coming up in these discussions. All-in-one Integrators are not a useful concept, and we need to stop discussing that as an option already every time we need a new feature. We made it easy to subclass exactly because we don’t want complexity to sneak into the code. It’ll make it that much harder to optimize for people’s individual needs, and will complicate the base usage. Suddenly everyone would have to add things like wanting 0 switching steps for a NonEquilibrium trajectory where I’m not even looking to use Nonequilibrium. Just make a new subclass that has the new feature we need.