a3fe.run.Calculation

class a3fe.run.Calculation(equil_detection: str = 'multiwindow', runtime_constant: float | None = 0.0005, relative_simulation_cost: float = 1, ensemble_size: int = 5, input_dir: str | None = None, base_dir: str | None = None, stream_log_level: int = 20, slurm_config: SlurmConfig | None = None, analysis_slurm_config: SlurmConfig | None = None, engine_config: _EngineConfig | None = None, engine_type: EngineType = EngineType.SOMD, update_paths: bool = True)[source]

Class to set up and run an entire ABFE calculation, consisting of two legs (bound and unbound) and multiple stages.

Attributes:

delta_g
delta_g_er
equil_time: The equilibration time, per member of the ensemble, in ns, for the and any sub-simulation runners.
equilibrated
failed_simulations: The failed sub-simulation runners
input_dir: The input directory for the simulation runner.
is_complete
legs
output_dir
prep_stage
running
stream_log_level: The log level for the stream handler.
tot_gpu_time
tot_simtime

Methods

`analyse`([slurm, run_nos, subsampling, ...])	Analyse the simulation runner and any sub-simulations, and return the overall free energy change.
`analyse_convergence`([slurm, run_nos, mode, ...])	Get a timeseries of the total free energy change of the sub-simulation runner against total simulation time.
`clean`([clean_logs])	Clean the simulation runner by deleting all files with extensions matching self.__class__.run_files in the base and output dirs, and resetting the total runtime to 0.
`get_optimal_lam_vals`([simtime, er_type, ...])	Determine the optimal lambda windows for each stage of the calculation by running short simulations at each lambda value and analysing them.
`get_results_df`([save_csv, add_sub_sim_runners])	Return the results in dataframe format
`recursively_get_attr`(attr)	Get the values of the attribute for the simulation runner and any sub-simulation runners.
`recursively_set_attr`(attr, value[, force, ...])	Set the attribute to the value for the simulation runner and any sub-simulation runners.
`reset`([reset_sub_sims])	Reset all attributes changed by the runtime algorithms to their default values.
`run`([run_nos, adaptive, runtime, ...])	Run all stages and perform analysis once finished.
`save`()	Save the current state of the simulation object to a pickle file.
`set_equilibration_time`(equil_time)	Set the equilibration time for the simulation runner and any sub-simulation runners.
`setup`([sysprep_config])	Set up the calculation.
`update_engine_config_option`(option, value)	Update an option in the engine configuration file.
`update_paths`(old_sub_path, new_sub_path)	Replace the old sub-path with the new sub-path in the base, input, and output directory paths.

get_tot_gpu_time
get_tot_simtime
is_equilibrated
kill
lighten
wait

__init__(equil_detection: str = 'multiwindow', runtime_constant: float | None = 0.0005, relative_simulation_cost: float = 1, ensemble_size: int = 5, input_dir: str | None = None, base_dir: str | None = None, stream_log_level: int = 20, slurm_config: SlurmConfig | None = None, analysis_slurm_config: SlurmConfig | None = None, engine_config: _EngineConfig | None = None, engine_type: EngineType = EngineType.SOMD, update_paths: bool = True) → None[source]

Instantiate a calculation based on files in the input dir. If calculation.pkl exists in the base directory, the calculation will be loaded from this file and any arguments supplied will be overwritten.

Parameters:

equil_detection (str, Optional, default: “multiwindow”) – Method to use for equilibration detection. Options are: - “multiwindow”: Use the multiwindow paired t-test method to detect equilibration.

This is applied on a per-stage basis.
- “chodera”: Use Chodera’s method to detect equilibration.
runtime_constant (float, Optional, default: 0.0005) – The runtime_constant (kcal**2 mol**-2 ns*-1) only affects behaviour if running adaptively, and must be supplied if running adaptively. This is used to calculate how long to run each simulation for based on the current uncertainty of the per-window free energy estimate, as discussed in the docstring of the run() method.
relative_simlation_cost (float, Optional, default: 1) – The relative cost of the simulation for a given runtime. This is used to calculate the predicted optimal runtime during adaptive simulations. The recommended use is to set this to 1 for the bound leg and to (speed of bound leg / speed of free leg) for the free leg.
ensemble_size (int, Optional, default: 5) – Number of simulations to run in the ensemble.
base_dir (str, Optional, default: None) – Path to the base directory in which to set up the legs and stages. If None, this is set to the current working directory.
input_dir (str, Optional, default: None) – Path to directory containing input files for the simulations. If None, this is set to current_working_directory/input.
stream_log_level (int, Optional, default: logging.INFO) – Logging level to use for the steam file handlers for the calculation object and its child objects.
slurm_config (SlurmConfig, default: None) – Configuration for the SLURM job scheduler. If None, the default partition is used.
analysis_slurm_config (SlurmConfig, default: None) – Configuration for the SLURM job scheduler for the analysis. This is helpful e.g. if you want to submit analysis to the CPU partition, but the main simulation to the GPU partition. If None,
engine_config (EngineConfig, default: None) – Configuration for the engine. If None, the default configuration is used.
engine_type (EngineType, default: EngineType.SOMD) – The type of engine to use for the production simulations.
update_paths (bool, Optional, default: True) – If True, if the simulation runner is loaded by unpickling, then update_paths() is called.

Return type:

None

Methods

`__init__`([equil_detection, ...])	Instantiate a calculation based on files in the input dir.
`analyse`([slurm, run_nos, subsampling, ...])	Analyse the simulation runner and any sub-simulations, and return the overall free energy change.
`analyse_convergence`([slurm, run_nos, mode, ...])	Get a timeseries of the total free energy change of the sub-simulation runner against total simulation time.
`clean`([clean_logs])	Clean the simulation runner by deleting all files with extensions matching self.__class__.run_files in the base and output dirs, and resetting the total runtime to 0.
`get_optimal_lam_vals`([simtime, er_type, ...])	Determine the optimal lambda windows for each stage of the calculation by running short simulations at each lambda value and analysing them.
`get_results_df`([save_csv, add_sub_sim_runners])	Return the results in dataframe format
`get_tot_gpu_time`([run_nos])
`get_tot_simtime`([run_nos])
`is_equilibrated`([run_nos])
`kill`()
`lighten`([clean_logs])
`recursively_get_attr`(attr)	Get the values of the attribute for the simulation runner and any sub-simulation runners.
`recursively_set_attr`(attr, value[, force, ...])	Set the attribute to the value for the simulation runner and any sub-simulation runners.
`reset`([reset_sub_sims])	Reset all attributes changed by the runtime algorithms to their default values.
`run`([run_nos, adaptive, runtime, ...])	Run all stages and perform analysis once finished.
`save`()	Save the current state of the simulation object to a pickle file.
`set_equilibration_time`(equil_time)	Set the equilibration time for the simulation runner and any sub-simulation runners.
`setup`([sysprep_config])	Set up the calculation.
`update_engine_config_option`(option, value)	Update an option in the engine configuration file.
`update_paths`(old_sub_path, new_sub_path)	Replace the old sub-path with the new sub-path in the base, input, and output directory paths.
`wait`()

Attributes

`class_count`
`delta_g`
`delta_g_er`
`equil_time`	The equilibration time, per member of the ensemble, in ns, for the and any sub-simulation runners.
`equilibrated`
`failed_simulations`	The failed sub-simulation runners
`input_dir`	The input directory for the simulation runner.
`is_complete`
`legs`
`output_dir`
`prep_stage`
`required_input_files`
`run_files`
`running`
`runtime_attributes`
`stream_log_level`	The log level for the stream handler.
`tot_gpu_time`
`tot_simtime`

analyse(slurm: bool = True, run_nos: List[int] | None = None, subsampling=False, fraction: float = 1, plot_rmsds: bool = False) → Tuple[ndarray, ndarray]

Analyse the simulation runner and any sub-simulations, and return the overall free energy change.

Parameters:

slurm (bool, optional, default=True) – Whether to use slurm for the analysis.
run_nos (List[int], Optional, default=None) – A list of the run numbers to analyse. If None, all runs are analysed.
subsampling (bool, optional, default=False) – If True, the free energy will be calculated by subsampling using the methods contained within pymbar.
fraction (float, optional, default=1) – The fraction of the data to use for analysis. For example, if fraction=0.5, only the first half of the data will be used for analysis. If fraction=1, all data will be used. Note that unequilibrated data is discarded from the beginning of simulations in all cases.
plot_rmsds (bool, optional, default=False) – Whether to plot RMSDS. This is slow and so defaults to False.

Returns:

dg_overall (np.ndarray) – The overall free energy change for each of the ensemble size repeats.
er_overall (np.ndarray) – The overall error for each of the ensemble size repeats.

analyse_convergence(slurm: bool = False, run_nos: List[int] | None = None, mode: str = 'cumulative', fraction: float = 1, equilibrated: bool = True) → Tuple[ndarray, ndarray]

Get a timeseries of the total free energy change of the sub-simulation runner against total simulation time. Also plot this. Keep this separate from analyse as it is expensive to run.

Parameters:

slurm (bool, optional, default=False) – Whether to use slurm for the analysis.
run_nos (List[int], Optional, default=None) – A list of the run numbers to analyse. If None, all runs are analysed.
mode (str, optional, default=”cumulative”) – “cumulative” or “block”. The type of averaging to use. In both cases, 20 MBAR evaluations are performed.
fraction (float, optional, default=1) – The fraction of the data to use for analysis. For example, if fraction=0.5, only the first half of the data will be used for analysis. If fraction=1, all data will be used. Note that unequilibrated data is discarded from the beginning of simulations in all cases.
equilibrated (bool, optional, default=True) – Whether to analyse only the equilibrated data (True) or all data (False)

Returns:

fracts (np.ndarray) – The fraction of the total (equilibrated) simulation time for each value of dg_overall.
dg_overall (np.ndarray) – The overall free energy change for the {self.__class__.__name__} for each value of total (equilibrated) simtime for each of the ensemble size repeats.

clean(clean_logs=False) → None

Clean the simulation runner by deleting all files with extensions matching self.__class__.run_files in the base and output dirs, and resetting the total runtime to 0.

Parameters:: clean_logs (bool, default=False) – If True, also delete the log files.

property equil_time: float: The equilibration time, per member of the ensemble, in ns, for the and any sub-simulation runners.

property failed_simulations: List[SimulationRunner]: The failed sub-simulation runners

get_optimal_lam_vals(simtime: float = 0.1, er_type: str = 'root_var', delta_er: float = 2, set_relative_sim_cost: bool = True, reference_sim_cost: float = 0.21, run_nos: List[int] = [1]) → None[source]

Determine the optimal lambda windows for each stage of the calculation by running short simulations at each lambda value and analysing them. This also sets the relative_simulation_effieciency of the free leg simulation runners (relative to the bound leg, which is set to 1).

Parameters:

simtime (float, Optional, default: 0.1) – The length of the short simulations to run, in ns.
er_type (str, optional, default=”root_var”) – Whether to integrate the standard error of the mean (“sem”) or root variance of the gradients (“root_var”) to calculate the optimal lambda values.
delta_er (float, default=2) – If er_type == “root_var”, the desired integrated root variance of the gradients between each lambda value, in kcal mol^(-1). If er_type == “sem”, the desired integrated standard error of the mean of the gradients between each lambda value, in kcal mol^(-1) ns^(1/2). A sensible default for root_var is 2 kcal mol-1, and 0,1 kcal mol-1 ns^(1/2) for sem. This is referred to as ‘thermodynamic speed’ in the publication.
set_relative_sim_cost (bool, optional, default=True) – Whether to recursively set the relative simulation cost for the leg and all sub simulation runners according to the mean simulation cost of the leg.
reference_sim_cost (float, optional, default=0.16) – The reference simulation cost to use if set_relative_sim_cost is True, in hr / ns. The default of 0.21 is the average bound leg simulation cost from a test set of ligands of a range of system sizes on RTX 2080s. This is used to set the relative simulation cost according to average_sim_cost / reference_sim_cost.
run_nos (List[int], optional, default=[1]) – The run numbers to use for the calculation. Only 1 is run by default, so by default we only analyse 1. If using delta_er == “sem”, more than one run must be specified.

Return type:

None

get_results_df(save_csv: bool = True, add_sub_sim_runners: bool = True) → DataFrame

Return the results in dataframe format

Parameters:

save_csv (bool, optional, default=True) – Whether to save the results as a csv file
add_sub_sim_runners (bool, optional, default=True) – Whether to show the results from the sub-simulation runners.

Returns:

results_df – A dataframe containing the results

Return type:

pd.DataFrame

property input_dir: str: The input directory for the simulation runner.

recursively_get_attr(attr: str) → Dict[SimulationRunner, Any]

Get the values of the attribute for the simulation runner and any sub-simulation runners. If the attribute is not present for a sub-simulation runner, None is returned.

Parameters:: attr (str) – The name of the attribute to get the values of.
Returns:: attr_values – A dictionary of the attribute values for the simulation runner and any sub-simulation runners.
Return type:: Dict[SimulationRunner, Any]

recursively_set_attr(attr: str, value: Any, force: bool = False, silent: bool = False) → None

Set the attribute to the value for the simulation runner and any sub-simulation runners.

Parameters:

attr (str) – The name of the attribute to set the values of.
value (Any) – The value to set the attribute to.
force (bool, default=False) – If True, set the attribute even if it doesn’t exist.
silent (bool, default=False) – If True, don’t log the setting of the attribute or raise any warnings.

reset(reset_sub_sims: bool = True) → None

Reset all attributes changed by the runtime algorithms to their default values.

Parameters:: reset_sub_sims (bool, default=True) – If True, also reset any sub-simulation runners.

run(run_nos: List[int] | None = None, adaptive: bool = True, runtime: float | None = None, runtime_constant: float | None = None, parallel: bool = True) → None[source]

Run all stages and perform analysis once finished. If running adaptively, cycles of short runs then optimal runtime estimation are performed, where the optimal runtime is estimated according to

\[t_{\mathrm{Optimal, k}} = \sqrt{\frac{t_{\mathrm{Current}, k}}{C}}\sigma_{\mathrm{Current}}(\Delta \widehat{F}_k)\]

where: - \(t_{\mathrm{Optimal, k}}\) is the calculated optimal runtime for lambda window \(k\) - \(t_{\mathrm{Current}, k}\) is the current runtime for lambda window \(k\) - \(C\) is the runtime constant - \(\sigma_{\mathrm{Current}}(\Delta \widehat{F}_k)\) is the current uncertainty in the free energy change contribution for lambda window \(k\). This is estimated from inter-run deviations. - \(\Delta \widehat{F}_k\) is the free energy change contribution for lambda window \(k\)

Parameters:

run_nos (List[int], Optional, default: None) – List of run numbers to run. If None, all runs will be run.
adaptive (bool, Optional, default: True) – If True, the stages will run until the simulations are equilibrated and perform analysis afterwards. If False, the stages will run for the specified runtime and analysis will not be performed.
runtime (float, Optional, default: None) – If adaptive is False, runtime must be supplied and stage will run for this number of nanoseconds.
runtime_constant (float, Optional, default: None) – The runtime_constant (kcal**2 mol**-2 ns*-1) only affects behaviour if running adaptively. This is used to calculate how long to run each simulation for based on the current uncertainty of the per-window free energy estimate.
parallel (bool, Optional, default: True) – If True, the stages will run in parallel. If False, the stages will run sequentially.

Return type:

None

save() → None: Save the current state of the simulation object to a pickle file.

set_equilibration_time(equil_time: float) → None

Set the equilibration time for the simulation runner and any sub-simulation runners.

Parameters:: equil_time (float) – The equilibration time to set, in ns per run per lambda window.

setup(sysprep_config: _BaseSystemPreparationConfig | None = None) → None[source]

Set up the calculation. This involves parametrising, equilibrating, and deriving restraints for the bound leg. Most of the work is done by the Leg class.

Parameters:: sysprep_config (BaseSystemPreparationConfig, optional, default = None) – The system preparation configuration to use for all legs. The required legs and stages will be determined from this configuration. If None, the default configuration is used.

property stream_log_level: int: The log level for the stream handler.

update_engine_config_option(option: str, value: str) → None: Update an option in the engine configuration file.

update_paths(old_sub_path: str, new_sub_path: str) → None

Replace the old sub-path with the new sub-path in the base, input, and output directory paths.

Parameters:

old_sub_path (str) – The old sub-path to replace.
new_sub_path (str) – The new sub-path to replace the old sub-path with.