Abstract Base Classes for Shooting Point Selectors

Abstract Base Classes for Shooting Point Selectors#

class aimmd.distributed.spselectors.SPSelector#

Abstract base class for shooting point selectors.

Initialize a SPSelector.

abstractmethod async pick(outfile: str, frame_extractor: FrameExtractor, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin, trajectory: Trajectory | None = None) → Trajectory#

Pick and return a snapshot to shot from.

abstractmethod async probability(snapshot: Trajectory, trajectory: Trajectory, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → float#

Return the proposal probability for the given snapshot.

class aimmd.distributed.spselectors.RCModelSPSelector(scale: float, distribution: str, *, density_adaptation_params: DensityAdaptionParameters | None = None, f_sel: Callable | None = None)#

Select SPs biased towards the transition state according to a RCModel.

Baseclass for both, selection of SPs from a given in-trajectory (i.e. a TP) and selection of SPs from a predefined ensemble of configurations (i.e. an equilibrium ensemble). This class provides the functions to calculate the (unnormalized) selection biases for the configurations in trajectories according to the RCModels prediction under a given selection distribution. The input to the distribution is the models z_sel, which corresponds to the log-committor q in the two-state case, and is in any case always 0 at the transition state ensemble. It supports the use of density adaptation, i.e. it can optionally take into account a flattening factor correcting for the density of configurations along the predicted committor using various schemes. See also the DensityAdaptionParameters for more.

Note that this class is an ABC, i.e. it can not be instantiated because it is missing two required methods pick_snapshot and probability.

Initialize a RCModelSPSelector.

Parameters:

  • scale (float) – Scale of the distribution, smaller values result in a more peaked selection of shooting points around the predicted transition state. For the Lorentzian distribution scale = gamma, while for the Gaussian distribution scale = 2 * sigma**2.

  • distribution (str) – A string indicating the distribution to use when selecting SPs around the transition state, can be “lorentzian”, “gaussian”, “uniform_phi”, “uniform”, or “custom” (see also f_sel).

  • density_adaptation_params (DensityAdaptionParameters or None) – Parameters for density adaption, which includes an additional correction factor to flatten the density of potential SP configurations along the predicted committor. See also the DensityAdaptionParameters for more. If set to None, no density adaption will be performed.

  • f_sel (Callable or None, optional) – If given, sets the shooting point selection distribution function to any Callable taking a single np.array of shape (n_frames,) and returning an array of the same shape containing bias weights. Note that, in this case distribution will be ignored and set to “custom”.

async biases(trajectory: Trajectory, model: RCModelAsyncMixin, exclude_frames: int = 0) → ndarray[Any, dtype[floating]]#

Return array with bias values for each configuration in trajectory.

Note that the returned array is shorter than trajectory if exclude_frames > 0, because then the first and last exclude_frames frames will be discarded.

Parameters:

  • trajectory (Trajectory) – The trajectory to calculate bias values for.

  • model (RCModelAsyncMixin) – The reaction coordinate model from which the biases are calculated.

  • exclude_frames (int) – How many frames to exclude at the start and end of the trajectory, e.g., if exclude_frames=2 we exclude the first and last 2 frames, by default 0.

Returns:

One dimensional array (of the same length as trajectory - 2 * exclude_frames) with the bias values.

Return type:

npt.NDArray[np.floating]

async pick(outfile: str, frame_extractor: FrameExtractor, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin, trajectory: Trajectory | None = None) → Trajectory#

Pick and return a snapshot to shot from.

abstractmethod async pick_snapshot(outfile: str, frame_extractor: FrameExtractor, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin, trajectory: Trajectory | None = None) → Trajectory#

Subclasses must implement this to pick/select a shooting snapshot.

Parameters:

  • outfile (str) – The filename of the selected snapshot to write out.

  • frame_extractor (FrameExtractor) – The FrameExtractor class that will be used to extract the selected snapshot.

  • simstate_info (PathSamplingSimStateInfo) – Dataclass carrying the current state of the pathsampling simulation and information about the current step, e.g. the step_num, workdir.

  • model (RCModelAsyncMixin) – The committor model to use to select the snapshot.

  • trajectory (Trajectory | None, optional) – An optional input trajectory to select the snapshot from, e.g. an input transition path. Can be None for example when selecting from a pregenerated reservoir of configurations, by default None.

Returns:

The selected shooting snapshot.

Return type:

Trajectory

abstractmethod async probability(snapshot: Trajectory, trajectory: Trajectory, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → float#

Return the proposal probability for the given snapshot.

async sum_bias(trajectory: Trajectory, model: RCModelAsyncMixin, exclude_frames: int = 0) → floating#

Return the sum of all selection biases for trajectory under model.

Parameters:

  • trajectory (Trajectory) – The trajectory over which the bias values are summed.

  • model (RCModelAsyncMixin) – The reaction coordinate model used to calculate the biases.

  • exclude_frames (int) – How many frames to exclude at the start and end of the trajectory, e.g., if exclude_frames=2 we exclude the first and last 2 frames, by default 0.

Returns:

The sum of all bias values on trajectory under model.

Return type:

float

property distribution: str#

Return/set the shooting point selection distribution f_sel(z).

Can be either “lorentzian”, “gaussian”, “uniform_phi”, or “uniform”. For “lorentzian” f_sel(z) = scale / (scale**2 + z**2). For “gaussian” f_sel(z) = exp(-z**2 / scale). For “uniform_phi” f_sel(z) = exp(-z) / (1 + exp(-z))**2 , resulting in a uniform selection weight along the committor phi = 1 / (1 + exp(-z)). For “uniform” f_sel(z) = 1, resulting in a selection that favours points close to the states, f_sel(phi) = 1 / (phi - phi**2).

property f_sel: Callable#

Return/set the shooting point selection distribution function directly.

The function must take a single argument z (a np.array with shape=(n_frames,)) and return a np.array of the same shape as z containing the (unnormalized) bias weights.

property scale: float#

Return/set scale of the shooting point selection distribution.