(Abstract) Base Classes

class aimmd.distributed.pathmovers.PathMover(*, modelstore=None, sampler_idx: int | None = None, **kwargs)

Abstract base class defining the API for all PathMover.

This PathMover can optionally use a model in the trial generation, e.g., to bias the selection of shooting points. This is controlled via the trial_generation_uses_model attribute (by default True).

If a model is used, this class takes care of saving and retrieving the model state to ensure the same reaction coordinate model is used for the whole trial, i.e., SP selection and accept/reject/ensemble weight assignment). To save unnecessary saves of unneeded models, no saving is performed when trial_generation_uses_model is False.

delete_model(step_num: int) → None

Delete the stored model for a given step_num.

Parameters:

step_num (int) – The step number in the MC chain to delete the model for.

Raises:

RuntimeError – If modelstore is None.

abstractmethod async generate_move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Abstract method to be implemented in subclasses. Will be called by move().

This method must perform the actual move in path space using the given copy of the model, while all model saving/copying is performed in move(). This method will be passed in the copy of the model to use for the whole remainder of the step.

Note that all movers should be able to continue an interrupted step. At least if their steps are computationally expensive, otherwise it might be ok to cleanup and start a new step from scratch when continuation is True, but then the mover might have to clean up files from a previous run of the same mover in the same workdir.

get_model(step_num: int) → RCModelAsyncMixin

Load the stored model for given step_num.

Parameters:

step_num (int) – The step number in the MC chain.

Returns:

The loaded model used for the given step_num.

Return type:

RCModelAsyncMixin

Raises:

RuntimeError – If modelstore is None.

async move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Perform a move in the MC chain, i.e. generate a new MCstep.

Note: Subclasses should overwrite the generate_move() method, to enable reuse of the same save/delete logic for every (model-dependant) pathmover.

Parameters:

• instep (MCstep) – The input MCstep, i.e. the previous step in the MC chain.

• 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 reaction coordinate model to use during the step.

Returns:

The newly generated MCstep.

Return type:

MCstep

store_model(model: RCModelAsyncMixin, step_num: int) → None

Store the given model for step_num.

Parameters:

• model (RCModelAsyncMixin) – The model to store.

• step_num (int) – The step number in the MC chain, i.e. the number of steps performed in the sampler performing this step.

Raises:

RuntimeError – If modelstore is None.

class aimmd.distributed.pathmovers.ShootingPathMover(states, md_engine_spec: MDEngineSpec, *, sp_selector_cls: type[SPSelector], sp_selector_kwargs: dict | None, **kwargs)

Base for all shooting PathMover.

Contains common methods to provide the shooting point(s).

Parameters:

• states (list[asyncmd.trajectory.functionwrapper.TrajectoryFunctionWrapper]) – State functions (stopping conditions) to use, passed to Propagator.

• md_engine_spec (MDEngineSpec) – Description/Specification of the MD engine (including parameters) used in the trial propagation. See MDEngineSpec for what is included.

• sp_selector_cls (type[SPSelector]) – The class of the shooting point selector to use for providing the (forward) SPs. Note that an uninitialized class is required.

• sp_selector_kwargs (dict | None) – Dictionary with keyword arguments used to initialize the shooting point selector. Can be None, in which case no arguments will be used when initializing the SP selector.

abstractmethod build_frame_extractors() → tuple[FrameExtractor, FrameExtractor | None]

Initialize and return the forward and (optionally) backward frame extractors.

Returns:

The forward and the backward frame extractor.

Return type:

tuple[FrameExtractor, FrameExtractor | None]

abstractmethod build_propagators() → Sequence[ConditionalTrajectoryPropagator | InPartsTrajectoryPropagator]

Initialize and return the trajectory propagators for this PathMover.

Returns:

List of forward and (optionally) backward propagators. In this order.

Return type:

list[_TrajectoryPropagator]

delete_model(step_num: int) → None

Delete the stored model for a given step_num.

Parameters:

step_num (int) – The step number in the MC chain to delete the model for.

Raises:

RuntimeError – If modelstore is None.

abstractmethod async generate_move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Abstract method to be implemented in subclasses. Will be called by move().

This method must perform the actual move in path space using the given copy of the model, while all model saving/copying is performed in move(). This method will be passed in the copy of the model to use for the whole remainder of the step.

Note that all movers should be able to continue an interrupted step. At least if their steps are computationally expensive, otherwise it might be ok to cleanup and start a new step from scratch when continuation is True, but then the mover might have to clean up files from a previous run of the same mover in the same workdir.

get_model(step_num: int) → RCModelAsyncMixin

Load the stored model for given step_num.

Parameters:

step_num (int) – The step number in the MC chain.

Returns:

The loaded model used for the given step_num.

Return type:

RCModelAsyncMixin

Raises:

RuntimeError – If modelstore is None.

async get_or_generate_sp_bw(workdir: str, fw_sp: Trajectory) → tuple[Trajectory, bool]

Generate or retrieve existing backward shooting point.

Parameters:

• workdir (str) – The working directory to which the shooting point will be written or from which it will be retrieved.

• fw_sp (Trajectory) – The forward shooting point from which the backward shooting point will be generated.

Returns:

bw_sp, file_exists: The shooting point and whether it existed.

Return type:

tuple[Trajectory, bool]

Raises:

RuntimeError – If no backward frame extractor is defined, i.e., if self._frame_extractor_bw is None.

async get_or_generate_sp_fw(*, instep: MCstep, simstate_info: PathSamplingSimStateInfo, model: RCModelAsyncMixin) → tuple[Trajectory, bool]

Generate or retrieve existing forward shooting point.

Parameters:

• instep (MCstep) – The input MC step.

• 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 reaction coordinate model to use to select the shooting point.

Returns:

fw_sp, file_exists: The shooting point and whether it existed.

Return type:

tuple[Trajectory, bool]

async get_or_generate_sps(*, instep: MCstep, simstate_info: PathSamplingSimStateInfo, model: RCModelAsyncMixin) → tuple[Trajectory, Trajectory] | Trajectory

Generate or retrieve shooting points for both directions.

Returns a tuple (fw_sp, bw_sp) if both forward and backward frame extractor are defined, otherwise, if only the forward frame extractor is defined only the forward shooting point is returned.

Warn if continuation is True but the shooting point(s) do not exist.

Parameters:

• instep (MCstep) – The input MC step.

• 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 reaction coordinate model to use to select the shooting point.

Returns:

Either a tuple of (forward shooting point, backward shooting point) or the forward shooting point, depending on if frame extractors for both directions are defined or not.

Return type:

tuple[Trajectory, Trajectory] | Trajectory

async move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Perform a move in the MC chain, i.e. generate a new MCstep.

Note: Subclasses should overwrite the generate_move() method, to enable reuse of the same save/delete logic for every (model-dependant) pathmover.

Parameters:

• instep (MCstep) – The input MCstep, i.e. the previous step in the MC chain.

• 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 reaction coordinate model to use during the step.

Returns:

The newly generated MCstep.

Return type:

MCstep

store_model(model: RCModelAsyncMixin, step_num: int) → None

Store the given model for step_num.

Parameters:

• model (RCModelAsyncMixin) – The model to store.

• step_num (int) – The step number in the MC chain, i.e. the number of steps performed in the sampler performing this step.

Raises:

RuntimeError – If modelstore is None.

class aimmd.distributed.pathmovers.RandomVelocitiesShootingPathMover(states, md_engine_spec: MDEngineSpec, temperature: float, *, sp_selector_cls: type[SPSelector], sp_selector_kwargs: dict | None, **kwargs)

(Abstract) base class for ShootingPathMover using random velocities at the shooting point.

Sets the frame extractors to RandomVelocitiesFrameExtractor for forward and InvertedVelocitiesFrameExtractor for backward direction.

Parameters:

• states (list[asyncmd.trajectory.functionwrapper.TrajectoryFunctionWrapper]) – State functions (stopping conditions) to use, passed to Propagator.

• md_engine_spec (MDEngineSpec) – Description/Specification of the MD engine (including parameters) used in the trial propagation. See MDEngineSpec for what is included.

• temperature (float) – Temperature in degree K (used for velocity randomization).

• sp_selector_cls (type[SPSelector]) – The class of the shooting point selector to use for providing the (forward) SPs. Note that an uninitialized class is required.

• sp_selector_kwargs (dict | None) – Dictionary with keyword arguments used to initialize the shooting point selector. Can be None, in which case no arguments will be used when initializing the SP selector.

build_frame_extractors() → tuple[FrameExtractor, FrameExtractor]

Initialize and return the forward and backward frame extractors.

Returns:

RandomVelocitiesFrameExtractor and InvertedVelocitiesFrameExtractor

Return type:

tuple[FrameExtractor, FrameExtractor]

abstractmethod build_propagators() → Sequence[ConditionalTrajectoryPropagator | InPartsTrajectoryPropagator]

Initialize and return the trajectory propagators for this PathMover.

Returns:

List of forward and (optionally) backward propagators. In this order.

Return type:

list[_TrajectoryPropagator]

delete_model(step_num: int) → None

Delete the stored model for a given step_num.

Parameters:

step_num (int) – The step number in the MC chain to delete the model for.

Raises:

RuntimeError – If modelstore is None.

abstractmethod async generate_move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Abstract method to be implemented in subclasses. Will be called by move().

This method must perform the actual move in path space using the given copy of the model, while all model saving/copying is performed in move(). This method will be passed in the copy of the model to use for the whole remainder of the step.

Note that all movers should be able to continue an interrupted step. At least if their steps are computationally expensive, otherwise it might be ok to cleanup and start a new step from scratch when continuation is True, but then the mover might have to clean up files from a previous run of the same mover in the same workdir.

get_model(step_num: int) → RCModelAsyncMixin

Load the stored model for given step_num.

Parameters:

step_num (int) – The step number in the MC chain.

Returns:

The loaded model used for the given step_num.

Return type:

RCModelAsyncMixin

Raises:

RuntimeError – If modelstore is None.

async get_or_generate_sp_bw(workdir: str, fw_sp: Trajectory) → tuple[Trajectory, bool]

Generate or retrieve existing backward shooting point.

Parameters:

• workdir (str) – The working directory to which the shooting point will be written or from which it will be retrieved.

• fw_sp (Trajectory) – The forward shooting point from which the backward shooting point will be generated.

Returns:

bw_sp, file_exists: The shooting point and whether it existed.

Return type:

tuple[Trajectory, bool]

Raises:

RuntimeError – If no backward frame extractor is defined, i.e., if self._frame_extractor_bw is None.

async get_or_generate_sp_fw(*, instep: MCstep, simstate_info: PathSamplingSimStateInfo, model: RCModelAsyncMixin) → tuple[Trajectory, bool]

Generate or retrieve existing forward shooting point.

Parameters:

• instep (MCstep) – The input MC step.

• 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 reaction coordinate model to use to select the shooting point.

Returns:

fw_sp, file_exists: The shooting point and whether it existed.

Return type:

tuple[Trajectory, bool]

async get_or_generate_sps(*, instep: MCstep, simstate_info: PathSamplingSimStateInfo, model: RCModelAsyncMixin) → tuple[Trajectory, Trajectory] | Trajectory

Generate or retrieve shooting points for both directions.

Returns a tuple (fw_sp, bw_sp) if both forward and backward frame extractor are defined, otherwise, if only the forward frame extractor is defined only the forward shooting point is returned.

Warn if continuation is True but the shooting point(s) do not exist.

Parameters:

• instep (MCstep) – The input MC step.

• 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 reaction coordinate model to use to select the shooting point.

Returns:

Either a tuple of (forward shooting point, backward shooting point) or the forward shooting point, depending on if frame extractors for both directions are defined or not.

Return type:

tuple[Trajectory, Trajectory] | Trajectory

async move(instep: MCstep, simstate_info: PathSamplingSimStateInfo, *, model: RCModelAsyncMixin) → MCstep

Perform a move in the MC chain, i.e. generate a new MCstep.

Note: Subclasses should overwrite the generate_move() method, to enable reuse of the same save/delete logic for every (model-dependant) pathmover.

Parameters:

• instep (MCstep) – The input MCstep, i.e. the previous step in the MC chain.

• 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 reaction coordinate model to use during the step.

Returns:

The newly generated MCstep.

Return type:

MCstep

store_model(model: RCModelAsyncMixin, step_num: int) → None

Store the given model for step_num.

Parameters:

• model (RCModelAsyncMixin) – The model to store.

• step_num (int) – The step number in the MC chain, i.e. the number of steps performed in the sampler performing this step.

Raises:

RuntimeError – If modelstore is None.