a3fe.run.LamWindow

class a3fe.run.LamWindow(lam: float, virtual_queue: VirtualQueue, lam_val_weight: float | None = None, block_size: float = 1, equil_detection: str = 'multiwindow', slurm_equil_detection: bool = True, gradient_threshold: float | None = None, runtime_constant: float | None = 0.0005, relative_simulation_cost: float = 1, ensemble_size: int = 5, base_dir: str | None = None, input_dir: str | None = None, output_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]

A class to hold and manipulate a set of SOMD simulations at a given lambda value.

Attributes:

delta_g
delta_g_er
equil_time: The equilibration time in ns, per run.
equilibrated: Whether equilibration has been achieved.
failed_simulations: The failed simulations
input_dir: The input directory for the simulation runner.
legs
output_dir
running
sims
stream_log_level: The log level for the stream handler.
tot_gpu_time
tot_simtime

Methods

`analyse`()	Analyse the simulation runner and any sub-simulations, and return the overall free energy change.
`analyse_convergence`()	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_results_df`([save_csv, add_sub_sim_runners])	Return the results in dataframe format
`get_tot_gpu_time`([run_nos])	Get the total GPU time for all specified runs, in GPU hours.
`get_tot_simtime`([run_nos])	Get the total simulation time for all specified runs, in ns.
`is_equilibrated`([run_nos])	Check if the ensemble of simulations at the lambda window is equilibrated, based on the run numbers specified and the equilibration detection method.
`kill`()	Kill all simulations at the lambda value.
`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, runtime])	Run all simulations at the lambda value.
`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.
`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.

lighten
setup
wait

__init__(lam: float, virtual_queue: VirtualQueue, lam_val_weight: float | None = None, block_size: float = 1, equil_detection: str = 'multiwindow', slurm_equil_detection: bool = True, gradient_threshold: float | None = None, runtime_constant: float | None = 0.0005, relative_simulation_cost: float = 1, ensemble_size: int = 5, base_dir: str | None = None, input_dir: str | None = None, output_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]

Initialise a LamWindow object.

Parameters:

lam (float) – Lambda value for the simulation.
virtual_queue (VirtualQueue) – VirtualQueue object to use for submitting jobs.
lam_val_weight (float, Optional, default: None) – Weight to use for this lambda value in the free energy calculation (e.g. from Trapezoidal rule).
block_size (float, Optional, default: 1) – Size of the blocks to use for equilibration detection, in ns. Only used for the block gradient equilibration detection method.
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. - “block_gradient”: Use the gradient of the block averages to detect equilibration. - “chodera”: Use Chodera’s method to detect equilibration.
slurm_equil_detection (bool, Optional, default: True) – Whether to use SLURM to run the equilibration detection MBAR calculations.
gradient_threshold (float, Optional, default: None) – The threshold for the absolute value of the gradient, in kcal mol-1 ns-1, below which the simulation is considered equilibrated. If None, no theshold is set and the simulation is equilibrated when the gradient passes through 0. A sensible value appears to be 0.5 kcal mol-1 ns-1. Only required when the equilibration detection method is “block_gradient”.
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 at this lambda value.
base_dir (str, Optional, default: None) – Path to the base directory. 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 will be set to “current_working_directory/input”.
output_dir (str, Optional, default: None) – Path to directory to store output files from the simulations. If None, this will be set to “current_working_directory/output”.
stream_log_level (int, Optional, default: logging.INFO) – Logging level to use for the steam file handlers for the Ensemble 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__`(lam, virtual_queue[, ...])	Initialise a LamWindow object.
`analyse`()	Analyse the simulation runner and any sub-simulations, and return the overall free energy change.
`analyse_convergence`()	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_results_df`([save_csv, add_sub_sim_runners])	Return the results in dataframe format
`get_tot_gpu_time`([run_nos])	Get the total GPU time for all specified runs, in GPU hours.
`get_tot_simtime`([run_nos])	Get the total simulation time for all specified runs, in ns.
`is_equilibrated`([run_nos])	Check if the ensemble of simulations at the lambda window is equilibrated, based on the run numbers specified and the equilibration detection method.
`kill`()	Kill all simulations at the lambda value.
`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, runtime])	Run all simulations at the lambda value.
`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`()
`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_detection_methods`
`equil_time`	The equilibration time in ns, per run.
`equilibrated`	Whether equilibration has been achieved.
`failed_simulations`	The failed simulations
`input_dir`	The input directory for the simulation runner.
`legs`
`output_dir`
`run_files`
`running`
`runtime_attributes`
`sims`
`stream_log_level`	The log level for the stream handler.
`tot_gpu_time`
`tot_simtime`

analyse() → None[source]

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() → None[source]

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 | None: The equilibration time in ns, per run.

property equilibrated: bool: Whether equilibration has been achieved.

property failed_simulations: List[SimulationRunner]: The failed simulations

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

get_tot_gpu_time(run_nos: List[int] | None = None) → float[source]

Get the total GPU time for all specified runs, in GPU hours.

Parameters:: run_nos (List[int], Optional, default: None) – The run numbers to use for MBAR. If None, all runs will be used.
Returns:: tot_gpu_time – Total GPU time, in GPU hours.
Return type:: float

get_tot_simtime(run_nos: List[int] | None = None) → float[source]

Get the total simulation time for all specified runs, in ns.

Parameters:: run_nos (List[int], Optional, default: None) – The run numbers to use for MBAR. If None, all runs will be used.
Returns:: tot_simtime – Total simulation time, in ns.
Return type:: float

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

is_equilibrated(run_nos: List[int] | None = None) → bool[source]

Check if the ensemble of simulations at the lambda window is equilibrated, based on the run numbers specified and the equilibration detection method. Store the equilibration status and time in private variables if so.

Parameters:: run_nos (List[int], Optional, default: None) – The run numbers to equilibration detection. If None, all runs will be used.
Returns:: equilibrated – True if the simulation is equilibrated, False otherwise.
Return type:: bool

kill() → None[source]: Kill all simulations at the lambda value.

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, runtime: float = 2.5) → None[source]

Run all simulations at the lambda value.

Parameters:

run_nos (List[int], Optional, default: None) – List of run numbers to run. If None, all simulations are run.
runtime (float, Optional, default: 2.5) – Runtime of simulation, in ns.

Return type:

None

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

set_equilibration_time(equil_time: float) → None[source]

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.

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.