BioSimSpace.FreeEnergy.Relative

class BioSimSpace.FreeEnergy.Relative(system, protocol=None, work_dir=None, engine=None, setup_only=False, property_map={}, **kwargs)

Class for configuring and running relative free-energy perturbation simulations.

__init__(system, protocol=None, work_dir=None, engine=None, setup_only=False, property_map={}, **kwargs)

Constructor.

Parameters:

• system (System) – The molecular system for the perturbation leg. This must contain a single perturbable molecule and is assumed to have already been equilibrated.

• protocol (Protocol.FreeEnergyMinimisation, Protocol.FreeEnergyEquilibration, Protocol.FreeEnergyProduction) – The simulation protocol.

• reference_system (System) – A reference system to use for position restraints.

• work_dir (str) – The working directory for the free-energy perturbation simulation.

• engine (str) – The molecular dynamics engine used to run the simulation. Available options are “GROMACS”, or “SOMD”. If this argument is omitted then BioSimSpace will choose an appropriate engine for you.

• setup_only (bool) – Whether to only support simulation setup. If True, then no simulation processes objects will be created, only the directory hierarchy and input files to run a simulation externally. This can be useful when you don’t intend to use BioSimSpace to run the simulation. Note that a ‘work_dir’ must also be specified.

• property_map (dict) – A dictionary that maps system “properties” to their user defined values. This allows the user to refer to properties with their own naming scheme, e.g. { “charge” : “my-charge” }

• kwargs (dict) – Additional keyword arguments to pass to the underlying Process objects.

Methods

__init__(system[, protocol, work_dir, ...])	Constructor.
analyse(work_dir[, estimator, method])	Analyse existing free-energy data from a simulation working directory.
checkOverlap(overlap[, threshold])	Check the overlap of an FEP leg.
difference(pmf[, pmf_ref])	Compute the relative free-energy difference between two perturbation legs, or between the end states of a single leg.
getData([name, file_link, work_dir])	Return a link to a zip file containing the data files required for post-simulation analysis.
kill(index)	Kill a process for a specific lambda window.
killAll()	Kill any running processes for all lambda windows.
run([serial])	Run the simulation.
wait()	Wait for the simulation to finish.
workDir()	Return the working directory.

static analyse(work_dir, estimator='MBAR', method='alchemlyb', **kwargs)

Analyse existing free-energy data from a simulation working directory.

Parameters:

• work_dir (str) – The working directory for the simulation.

• estimator (str) – The estimator to use for the free-energy analysis. (“MBAR” or “TI”)

• method (str) – The method to use for the free-energy analysis. (“alchemlyb” or “native”)

Returns:

• pmf ([(float, Energy, Energy)]) – The potential of mean force (PMF). The data is a list of tuples, where each tuple contains the lambda value, the PMF, and the standard error.

• overlap (np.matrix, None) – The overlap matrix. This gives the overlap between each lambda window. This parameter is only computed when available for the specified estimator and engine, otherwise None will be returned.

static checkOverlap(overlap, threshold=0.03)

Check the overlap of an FEP leg.

Parameters:

• overlap (numpy.matrix) – The overlap matrix. This gives the overlap between lambda windows.

• threshold (float) – The threshold value used to check the off-diagonals.

Returns:

• is_okay (boolean) – True if the overlap is okay, False if any off-diagonals are less than the threshold value.

• num_low (int) – The number of off-diagonals that are less than the threshold value.

static difference(pmf, pmf_ref=None)

Compute the relative free-energy difference between two perturbation legs, or between the end states of a single leg.

Parameters:

• pmf ([(float, Energy, Energy)]) – The potential of mean force (PMF) of interest. The data is a list of tuples, where each tuple contains the lambda value, the PMF, and the standard error.

• pmf_ref ([(float, Energy, Energy)]) – The reference potential of mean force (PMF). The data is a list of tuples, where each tuple contains the lambda value, the PMF, and the standard error.

Returns:

free_energy – The relative free-energy difference and its associated error.

Return type:

(Energy, Energy)

getData(name='data', file_link=False, work_dir=None)

Return a link to a zip file containing the data files required for post-simulation analysis.

Parameters:

• name (str) – The name of the zip file.

• file_link (bool) – Whether to return a FileLink when working in Jupyter.

• work_dir (str) – The working directory for the free-energy perturbation simulation.

Returns:

output – A path, or file link, to an archive of the process input.

Return type:

str, IPython.display.FileLink

kill(index)

Kill a process for a specific lambda window.

Parameters:

index (int) – The index of the lambda window.

killAll()

Kill any running processes for all lambda windows.

run(serial=True)

Run the simulation.

Parameters:

serial (bool) – Whether to run the individual processes for the lambda windows in serial.

wait()

Wait for the simulation to finish.

workDir()

Return the working directory.

Returns:

work_dir – The path of the working directory.

Return type:

str