Alchemical Transfer Method

[mb2055]

This PR adds functionality for creating, running and analysing RBFE calculations using the Alchemical Transfer Method (AToM).

Functionality is contained in a pair of key locations and is as follows:

• BioSimSpace.FreeEnergy.AToM is a class that facilitates the creation of AToM-compatible systems, the use of the BioSimSpace runner to run full sets of production simulations, and analysis using UWHAM.
  • Users can pass a set of three BioSimSpace molecules, and use ...AToM.prepare() to create an AToM-compatible system. Users can pass a vector to the prepare function that defines the displacement of the free ligand relative to the bound ligand. If this vector is not provided a best-fit vector will be automatically calculated.
  • The choice of rigid core atoms, which define the alignment of the two ligands and are vital to the stability of simulations, can be tricky. To aid in the choice of these atoms the AToM class includes a helper function called viewRigidCores which allows the user to view their choice of rigid core atoms within a notebook.
• BioSimSpace.Protocol.AToM{} contains a series of protocols for minimisation, equilibration and annealing of AToM systems. Equilibration and annealing protocols allow users to manually set the large number of constants and lambda-dependent values used in AToM simulations, any that are not set have sane defaults chosen for them.
  • BioSimSpace.Protocol.AToMEquilibration allows the user to run with or without the ATMForce present, simply by setting use_atm_force.
  • BioSimSpace.Protocol.AToMAnnealing allows the user to anneal any number of the lambda-dependent values, these are set through a dictionary. If not set the system is annealed from lambda1,lambda2 = 0 to lambda1,lambda2 = 0.5.
  • AToM production protocols are highly sensitive to starting structure, as such its vital that care it taken in the minimisation, equilibration and annealing of systems. As a rule of thumb the protocol used should be Minimisation->Equilibration without ATMForce -> annealing to lambda1,lambda2=0.5 -> equilibration with ATMForce with lamdba1,lambda2 = 0.5. Any systems in which instability is experienced in systems with direction=-1 should be addressed by increasing the runtime of post-annealing equilibration.
• Once production simulations have been run (either externally or using BioSimSpace.FreeEnergy.AToM.run()) analysis can be performed using BioSimSpace.FreeEnergy.AToM.analyse() - this uses an internal UWHAM implementation to find the overall ddg.

Very roughly, a full start to finish AToM run would look like this:

import BioSimSpace as BSS

lig1 = BSS.IO.readMolecules({ligand1 files})[0]
lig2 = BSS.IO.readMolecules({ligand2 files})[0]
prot = BSS.IO.readMolecules({protein files})[0]

AToM = BSS.FreeEnergy.AToM(protein = prot, ligand1 = lig1, ligand2 = lig2)
AToM_system, data = AToM.prepare(
    ligand1_rigid_core=[a, b, c],
    ligand2_rigid_core=[d, e, f],
    displacement="20A",
)
...
#### solvate AToM_system ####
...
min_protocol = BSS.Protocol.AToMMinimisation(data, {options})
minimise = BSS.Process.OpenMM(AToM_system, min_protocol)
minimise.start()
minimise.wait()
minimised = minimise.getSystem()
...
#### now do equilibration, annealing and ATM equilibration, API same as minimisation, 
#### setting the required options) ####
...
production_atm = BSS.Protocol.AToMProduction(
    data=data,
    {options}
)
production = AToM.run(
    {minimised and equilibrated AToM_system},
    production_atm,
    work_dir = {output directory},
)
production.wait()

BSS.FreeEnergy.Analyse({output directory})

This PR also includes (hopefully) full API docs, as well as a brief summary of AToM within the docs for BioSimSpace.FreeEnergy.

---

• I confirm that I have merged the latest version of devel into this branch before issuing this pull request (e.g. by running git pull origin devel): [y/n]
• I confirm that I have added a test for any new functionality in this pull request: [y/n]
• I confirm that I have added documentation (e.g. a new tutorial page or detailed guide) for any new functionality in this pull request: [y/n]
• I confirm that I have permission to release this code under the GPL3 license: [y/n]

Suggested reviewers:

@lohedges

[lohedges]

Many thanks for this heroic effort, @mb2055. Things are looking really good and the new tutorial is great.

[lohedges]

This still isn't resolved, but I don't see any easy way to do it given the state stored by the AToM class. Perhaps it's easiest to leave like this, since it is similar to the logic for the MD and Metadynamics modules. (Just a bit confusing if you're used to the FreeEnergy.Relative API. I'll have think before merging.