BioSimSpace.FreeEnergy.Relative

class BioSimSpace.FreeEnergy.Relative(system, protocol=None, work_dir=None, engine=None, setup_only=False, ignore_warnings=False, show_errors=True, property_map={})

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

__init__(system, protocol=None, work_dir=None, engine=None, setup_only=False, ignore_warnings=False, show_errors=True, property_map={})

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.FreeEnergy, The simulation protocol.) –

  • 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.

  • ignore_warnings (bool) – Whether to ignore warnings when generating the binary run file. This option is specific to GROMACS and will be ignored when a different molecular dynamics engine is chosen.

  • show_errors (bool) – Whether to show warning/error messages when generating the binary run file. This option is specific to GROMACS and will be ignored when a different molecular dynamics engine is chosen.

  • 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” }

Methods

__init__(system[, protocol, work_dir, …])

Constructor.

analyse(work_dir)

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

difference(pmf, pmf_ref)

Compute the relative free-energy difference between two perturbation legs.

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)

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

Parameters

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

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 ([ [ float, float, … ] ]) – The overlap matrix. This gives the overlap between each lambda window. This parameter is only computed for the SOMD engine and will be None when GROMACS is used.

static difference(pmf, pmf_ref)

Compute the relative free-energy difference between two perturbation legs.

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