a3fe.run._simulation_runner

Abstract base class for simulation runners.

Classes

SimulationRunner([base_dir, input_dir, ...])

An abstract base class for simulation runners.

class a3fe.run._simulation_runner.SimulationRunner(base_dir: str | None = None, input_dir: str | None = None, output_dir: str | None = None, slurm_config: SlurmConfig | None = None, analysis_slurm_config: SlurmConfig | None = None, engine_config: _EngineConfig | None = None, engine_type: EngineType = EngineType.SOMD, stream_log_level: int = 20, dg_multiplier: int = 1, ensemble_size: int = 5, update_paths: bool = True, dump: bool = True)

An abstract base class for simulation runners. Note that self._sub_sim_runners (a list of SimulationRunner objects controlled by the current SimulationRunner) must be set in order to use methods such as run()

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.

output_dir

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

get_tot_gpu_time
get_tot_simtime
is_equilibrated
kill
lighten
run
setup
wait

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

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.

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.