a3fe.run.Simulation

class a3fe.run.Simulation(lam: float, run_no: int, virtual_queue: VirtualQueue, 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]

Class to store information about a single SOMD simulation.

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: Whether the simulation has failed
failed_simulations: The failed sub-simulation runners
input_dir: The input directory for the simulation runner.
output_dir
running: Check if the simulation is still running, and update the running attribute accordingly.
slurm_file_base: Get the base name of the SLURM output file.
slurm_output_files: Get a list of all slurm output files for this simulation.
stream_log_level: The log level for the stream handler.
tot_gpu_time: Get the total simulation time in GPU hours
tot_simtime: Get the total simulation time in ns

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`()	Get the total simulation time in GPU hours
`get_tot_simtime`()	Get the total simulation time in ns
`kill`()	Kill the job.
`lighten`()	Lighten the simulation by deleting all restart and trajectory files.
`read_gradients`([equilibrated_only, endstate])	Read the gradients from the output file.
`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`([runtime])	Run a simulation.
`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

is_equilibrated
setup
wait

__init__(lam: float, run_no: int, virtual_queue: VirtualQueue, 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 Simulation object.

Parameters:

lam (float) – Lambda value for the simulation.
run_no (int) – Index of repeat for the simulation.
virtual_queue (VirtualQueue) – Virtual queue object to use for the simulation.
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 simulation. 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 simulation. 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 simulation 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, run_no, virtual_queue[, ...])	Initialise a Simulation 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`()	Get the total simulation time in GPU hours
`get_tot_simtime`()	Get the total simulation time in ns
`is_equilibrated`([run_nos])
`kill`()	Kill the job.
`lighten`()	Lighten the simulation by deleting all restart and trajectory files.
`read_gradients`([equilibrated_only, endstate])	Read the gradients from the output file.
`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`([runtime])	Run a simulation.
`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
`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`	Whether the simulation has failed
`failed_simulations`	The failed sub-simulation runners
`input_dir`	The input directory for the simulation runner.
`output_dir`
`required_input_files`
`run_files`
`running`	Check if the simulation is still running, and update the running attribute accordingly.
`runtime_attributes`
`slurm_file_base`	Get the base name of the SLURM output file.
`slurm_output_files`	Get a list of all slurm output files for this simulation.
`stream_log_level`	The log level for the stream handler.
`tot_gpu_time`	Get the total simulation time in GPU hours
`tot_simtime`	Get the total simulation time in ns

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: None: The equilibration time, per member of the ensemble, in ns, for the and any sub-simulation runners.

property failed: bool: Whether the simulation has failed

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

get_tot_gpu_time() → float[source]

Get the total simulation time in GPU hours

Returns:: tot_gpu_time – Total simulation time in GPU hours.
Return type:: float

get_tot_simtime() → float[source]

Get the total simulation time in ns

Returns:: tot_simtime – Total simulation time in ns.
Return type:: float

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

kill() → None[source]: Kill the job.

lighten() → None[source]: Lighten the simulation by deleting all restart and trajectory files.

read_gradients(equilibrated_only: bool = False, endstate: bool = False) → Tuple[ndarray, ndarray][source]

Read the gradients from the output file. These can be either the infiniesimal gradients at the given value of lambda, or the differences in energy between the end state Hamiltonians.

Parameters:

equilibrated_only (bool, Optional, default: False) – Whether to read the gradients from the equilibrated region of the simulation (True) or the whole simulation (False).
endstate (bool, Optional, default: False) – Whether to return the difference in energy between the end state Hamiltonians (True) or the infiniesimal gradients at the given value of lambda (False).

Returns:

times (np.ndarray) – Array of times, in ns.
grads (np.ndarray) – Array of gradients, in kcal/mol.

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

Run a simulation.

Parameters:: runtime (float, Optional, default: 2.5) – Runtime of simulation, in ns.
Return type:: None

property running: bool

Check if the simulation is still running, and update the running attribute accordingly. Also resubmit job if it has failed.

Returns:: self._running – True if the simulation is still running, False otherwise.
Return type:: bool

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 slurm_file_base: str: Get the base name of the SLURM output file.

property slurm_output_files: List[str]: Get a list of all slurm output files for this simulation.

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

property tot_gpu_time: float: Get the total simulation time in GPU hours

property tot_simtime: float: Get the total simulation time in ns

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[source]

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

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.