The role of lambda in BioSimSpace.Protocol.FreeEnergy

[xiki-tempula]

trafficstars

My initial understanding of the lambda and lambda_vals in BioSimSpace.Protocol.FreeEnergy is that for one free energy transformation which has 10 windows, we would have 10 BioSimSpace.Protocol.FreeEnergy, where they share the same lambda_vals but different lambda, where each lambda corresponds to a different window.

However, in https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/FreeEnergy/_relative.py#L762, it seems that we are just looping over the lambda_vals to create different windows.

If we are just looping over the lambda_vals, do we really need to set the lambda? Can we just set the lambda_vals in BioSimSpace.Protocol.FreeEnergy and then loop over it? Sorry, I have just started to work on the code so I might have missed something.

[lohedges]

Hi there,

No you're not missing anything. The issue is providing the user with the flexibility of running a single lambda window, e.g:

protocol = BSS.Protocol.FreeEnergy(lambda=0)

# Run a single window at lambda = 0.
process = BSS.Process.Gromacs(system, protocol)

and also having a higher-level interface to set-up and run an entire FEP simulation.

protocol = BSS.Protocol.FreeEnergy()

# Set up an FEP simulation for an entire leg, i.e. all lambda windows.
freenrg = BSS.FreeEnergy.Relative(system, protocol)

The protocol was originally written with the intention of being used for a single lambda window, hence the requirement for a lambda value. As noted, this isn't strictly needed when using the high-level BioSimSpace.FreeEnergy.Relative class, but I just re-used the same protocol at the time for convenience. (Rather than creating another protocol that was identical, other than not having a lambda attribute.)

You might stumble across other cases where the interface seems a bit strange and their appears to be some redundancy. This is one of the challenges when offering high-level convenience wrappers, while still providing lower-level functionality for power users who want to do things in a specific way. Quite often you might find that there are multiple ways to achieve the same thing.

As always, these approaches are still open for discussion and I would be happy to refine things given feedback and understanding of how things are being used in practice.

Thanks for your question.

[xiki-tempula]

@lohedges Thanks for the explanation. Another question, I wonder why do you copy the files, change something and then spawn the process manually in here https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/FreeEnergy/_relative.py#L819-L865 Instead of just reuse the https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/FreeEnergy/_relative.py#L753-L755

I mean like

first_process = _Process.Gromacs(protocal)

for lambda in lambda_values:
    protocal.set_Lambda(lambda)
    new_process = _Process.Gromacs(protocal)

[lohedges]

This is a hack for quickly setting up multiple processes that happen to share an identical input system, differing only by a single entry in their configuration file. If you set them up one-by-one using the usual process = BSS.Process.Gromacs(system, protocol, ...) approach then you end up re-generating the input files for each process, which can be slow for large protein ligand complexes.

In fact, most people don't actually use BioSimSpace to directly run the simulations since it is quite inflexible at present, so they make use of the setup_only=True option, which doesn't actually accumulate and store any process objects for the different windows.

In your example code:

new_process = _Process.Gromacs(protocal)

This isn't a valid way to instantiate a process object.

[xiki-tempula]

@lohedges Thanks. The issue that I'm having is that I noticed that init-lambda-state was not set properly if I only config it in https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/Process/_gromacs.py#L569 Then I noticed that it is configured again in https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/FreeEnergy/_relative.py#L825 So I think it would be nice if all the configuration of init-lambda-state is done in one place to avoid changing it is one place which makes it incompatible with the other place.

[lohedges]

Yes, I see, that wasn't a consideration at the time. I imagine this hack can be consumed into BioSimSpace.Process, i.e. by adding some hidden functionality to clone a process and update attributes such as the config, working directory, etc. That way the same setConfig functionality should be called in both cases.

[xiki-tempula]

@lohedges Thanks for the explanation. I will just change the init-lambda-state in https://github.com/michellab/BioSimSpace/blob/devel/python/BioSimSpace/FreeEnergy/_relative.py#L825 and probably comeback to it when I got the whole pipeline up and running.