Committor simulations

Committor simulations#

The aimmd.distributed contains a class to perform committor simulations for an arbitrary number of configurations and trials in parallel. The CommittorSimulation allows to perform committor trials in one direction only, or optionally, will also perform for every trial a propagation with inverted momenta at the shooting point. This feature can be particularly useful to generate initial transitions as input for a transition path sampling simulation.

The input configurations for the CommittorSimulation are expected to be wrapped as CommittorConfiguration dataclasses. The MD engine and other propagation options for the trials are defined (potentially on a per-configuration basis) via the dataclass CommittorEngineSpec. Note that a number of options to the CommittorSimulation can be specified on a per-configuration basis (in addition to the CommittorEngineSpec), enabling users to easily bundle multiple related committor simulations into CommittorSimulation, e.g., using different temperatures, pressures, or even slightly different (or very different, but this is not recommended except if you are way too organized, and then you would not [dare to] do it…) molecular systems. See the docstring of the CommittorSimulation for more.

See also

The example notebook on the CommittorSimulation, which shows how to perform a committor simulation on capped alanine dipeptide.

class aimmd.distributed.CommittorConfiguration(trajectory: Trajectory, index: int, name: str | None = None)#

Specify configurations for CommittorSimulation

Parameters:

  • trajectory (asyncmd.Trajectory) – The trajectory on which the configuration lies.

  • index (int) – The index of the configuration in the trajectory.

  • name (str | None) – An optional name used to identify the configuration.

class aimmd.distributed.CommittorEngineSpec(engine_cls: type[MDEngine], engine_kwargs: dict[str, Any], walltime_per_part: float, max_steps: int | None = None, full_precision_traj_type: str = 'trr')#

Specify MDEngine and other propagation options for CommittorSimulation.

Parameters:

  • engine_cls (type[asyncmd.mdengine.MDEngine]) – The MD engine class to use (uninitialized).

  • engine_kwargs (dict[str, Any]) – A dictionary with keyword arguments that can be used to initialize the MD engine.

  • walltime_per_part (float) – MD propagation will be split in parts of walltime, measured in hours.

  • max_steps (int) – The maximum number of integration steps to perform without reaching a state, i.e. upper cutoff for uncommitted trials.

  • full_precision_traj_type (str) – The trajectory type for the full precision trajectories used by this engine. Will be used as file-ending for the shooting points. Note: Must be a format that stores velocities and coordinates! By default “trr”.

output_traj_type#

The (potentially lossy) output trajectory type of the engine, will be inferred automatically from engine_cls and engine_kwargs. Note: Only needs to store coordinates (no velocities).

Type:

str

class aimmd.distributed.CommittorSimulation(workdir: str, configurations: list[CommittorConfiguration], *, states: list[TrajectoryFunctionWrapper], temperature: float | list[float], committor_engine_spec: CommittorEngineSpec | list[CommittorEngineSpec], two_way: bool | list[bool] = False, **kwargs: dict)#

Run committor simulation for multiple configurations in parallel.

Given a list of configurations (as CommittorConfiguration) and a list of states propagate trajectories until any of the states is reached. Writes out the concatenated trajectory from the starting configuration to the first state reached. If two_way is True, trials will also be performed with inverted momenta, i.e. backward. For these trials concatenated output trajectories will also be written, but additionally transition trajectories are written out if the forward and backward propagation of the same trial end in different states. The transition will be ordered going from the lower index state to the higher index state. The results/states reached for forward and backward trials are stored and returned separately due to the correlation in outcomes between forward and backward trials.

This class will create the following directory path for each trial, with $CONF_DIR_NAME either conf_$CONF_NUM or the name of the configuration, and $CONF_NUM and $TRIAL_NUM the indices of the configuration and trial, respectively: $WORKDIR/$CONF_DIR_NAME/trial_$TRIAL_NUM. Inside of each trial directory will be the shooting points and concatenated output trajectories and a directory for each the forward and the backward propagation, respectively.

All attributes and properties can be set at initialization by passing keyword arguments with their name.

Note, that the CommittorSimulation allows to vary some of the simulation parameters on a per configuration basis. These can be either a list of values (length must then be equal to the number of configurations) or a single value. This means you can simulate systems differing in the number of molecules, at different pressures, or at different temperatures (by using different CommittorEngineSpec) and even perform two way trials only for a selected subset of configurations (e.g. the ones you expect to be a transition state).

Parameters:

  • workdir (str) – The working directory of the simulation.

  • configurations (list[CommittorConfiguration]) – List of input configurations to perform committor simulation for.

  • states (list[asyncmd.trajectory.functionwrapper.TrajectoryFunctionWrapper]) – List of states (stopping conditions) for the trial propagation.

  • temperature (float | list[float]) – Temperature used to draw random Maxwell-Boltzmann velocities. Measured in degree Kelvin. Can vary on a per-configuration basis or be the same for all configurations. Note: It is the users responsibility to ensure that the temperature and other temperatures potentially passed via committor_engine_spec (e.g. for thermostats in the MD engine) agree!

  • committor_engine_spec (CommittorEngineSpec | list[CommittorEngineSpec]) – Description/Specification of the MD engine (including parameters) used in the trial propagation. See CommittorEngineSpec for what is included. Can vary on a per-configuration basis.

  • two_way (bool | list[bool], optional) – Whether to perform two way trials, by default False. Can vary on a per-configuration basis or be the same for all configurations.

Raises:

ValueError – If multiple CommittorConfiguration have the same given name, i.e. the configurations passed would lead to non-unique directory names.

async add_missing_backward_trials(n_max_concurrent: int | None = None) → None#

Add potentially missing backward trials, if two_way has been modified.

Parameters:

n_max_concurrent (int | None, optional) – How many trials to run concurrently at maximum. None means unlimited, by default None.

async reinitialize_from_workdir(overwrite: bool = True, n_max_concurrent: int | None = None) → None#

Reassess all trials in workdir and populate states_reached counters.

Possibly extend trials if no state has been reached yet and also add potentially missing backward trials. Can be used to extend (or shorten) a simulation with modified states or to recover after a crash.

Parameters:

  • overwrite (bool, optional) – Whether to overwrite potentially existing output trajectories, e.g. trajectory_to_state, by default True.

  • n_max_concurrent (int | None, optional) – How many trials to run concurrently at maximum. None means unlimited, by default None.

async run(trials_per_configuration: int, n_max_concurrent: int | None = None) → None#

Run trials_per_configuration additional committor trials for each configuration.

Parameters:

  • trials_per_configuration (int) – Number of additional trial runs to perform per configuration.

  • n_max_concurrent (int | None, optional) – How many trials to run concurrently at maximum. None means unlimited, by default None.

property committor_engine_spec: CommittorEngineSpec | list[CommittorEngineSpec]#

Specification(s) of the MD engines used for the trial propagation.

property configurations: list[CommittorConfiguration]#

List of input configurations to perform committor simulation for.

property directory_backward: str#

The directory name used for the backward propagation.

property directory_configuration_prefix: str#

The prefix for the configuration directories, used only for un-named configurations. The directory name will be $DIRECTORY_CONFIGURATION_PREFIX_$CONF_NUM.

property directory_forward: str#

The directory name used for the forward propagation.

property directory_trial_prefix: str#

The prefix for the trial directories, the directory name will be $DIRECTORY_TRIAL_PREFIX_$TRIAL_NUM.

property fileout_deffnm_engine: str#

The deffnm used for the MD engines in trial propagation.

property fileout_initial_configuration: str#

The filename for the initial configuration (including velocities) for the forward trial to be written to each trial directory.

Note: Without fileending, because the file-ending defined in committor_engine_spec will be added.

property fileout_initial_configuration_backward: str#

The filename for the initial configuration (including velocities) for the backward trial to be written to each trial directory.

Note: Without fileending, because the file-ending defined in committor_engine_spec will be added.

property fileout_trajectory_to_state: str#

The filename for the output trajectories to the forward state to be written to each trial directory.

Note: Without fileending, the fileending will be inferred from the respective committor engine specification.

property fileout_trajectory_to_state_backward: str#

The filename for the output trajectories to the backward state to be written to each trial directory.

Note: Without fileending, the fileending will be inferred from the respective committor engine specification.

property fileout_transition_trajectory: str#

The filename for the output transition trajectories to be written to the trial directories.

Note: Without fileending, the fileending will be inferred from the respective committor engine specification.

property max_retries_on_crash: int#

Maximum number of retries (per trial) in case of MD engine crash.

Note: After max_retries is reached the error will be raised!

property max_retries_on_max_steps: int#

Maximum number of retries (per trial) in case of max_steps reached.

Note: If no state is reached after max_retries + 1 tries, the trial will have state_reached=None and simply not be included in the state_reached properties. No error will be raised!

property states: list[TrajectoryFunctionWrapper]#

List of states (stopping conditions) for trial propagation.

property states_reached: ndarray#

Return states_reached per configuration (i.e. summed over trials). These are only the results of the forward propagation.

Return states_reached as a np.array with shape (n_conf, n_states), where the entries give the counts of states reached for a given configuration.

property states_reached_backward: ndarray#

Return states_reached per configuration (i.e. summed over trials). These are only the results of the backward propagation.

Return states_reached as a np.array with shape (n_conf, n_states), where the entries give the counts of states reached for a given configuration.

property states_reached_per_trial: ndarray#

Return states_reached per configuration (i.e. summed over trials). These are only the results of the forward propagation.

Return states_reached as a np.array with shape (n_conf, n_states), where the entries give the counts of states reached for a given configuration.

property states_reached_per_trial_backward: ndarray#

Return states_reached per configuration (i.e. summed over trials). These are only the results of the backward propagation.

Return states_reached as a np.array with shape (n_conf, n_states), where the entries give the counts of states reached for a given configuration.

property temperature: float | list[float]#

Temperature(s) used to generate Maxwell-Boltzmann velocities, in Kelvin.

property trajectories_to_state#

Return all forward trajectories until a state generated so far.

The return value is a list of lists, the outer list corresponds to configurations, the inner lists to the trials.

property trajectories_to_state_backward#

Return all backward trajectories until a state generated so far.

The return value is a list of lists, the outer list corresponds to configurations, the inner lists to the trials.

property transition_trajectories: list[list[Trajectory]]#

Return all transition trajectories generated so far.

A transition is defined as a trajectory that connects two different states.

The return value is a list of lists, the outer list corresponds to configurations, the inner lists to the trials. The inner lists may be empty if no transitions exist for a particular configuration.

property trial_counter: int#

Return the number of trials done per configuration.

property two_way: bool | list[bool]#

Whether to perform two way trials.

property workdir: str#

Toplevel working directory of this simulation.

Contents