Propagation of MD in segments and/or until a condition is fulfilled

Propagation of MD in segments and/or until a condition is fulfilled#

Another notable part of the asyncmd.trajectory module are the InPartsTrajectoryPropagator and the ConditionalTrajectoryPropagator, which can both be used to propagate trajectories in chunks of a given walltime. While the former is used to propagate a trajectory until a given total number of integration steps is reached, the later one can be used to propagate a trajectory until any of the given user-supplied conditions are fulfilled.

The InPartsTrajectoryPropagator is intended to make it possible to run MD simulations for walltimes longer than the queuing limit and to make full use of backfilling.

While it also enables running MD simulations longer than the queuing limit and makes full use of backfilling by splitting the MD into segments (similar to the InPartsTrajectoryPropagator), the ConditionalTrajectoryPropagator is especially useful for path sampling and committor simulations. In this case the conditions would be the state functions, but it can be used in general for any situation where the time integration should be stopped on given criteria (as opposed to after a fixed number of integration steps or when a given walltime is reached). There is also a handy function to create a transition, i.e. a trajectory that connects to (different) conditions from two conditional propagation runs ending in different conditions, the construct_tp_from_plus_and_minus_traj_segments function. It is most likely useful for users implementing some form of path sampling.

See also

The example notebooks on the InPartsTrajectoryPropagator and the ConditionalTrajectoryPropagator

Propagation in segments#

class asyncmd.trajectory.InPartsTrajectoryPropagator(n_steps: int, *, engine_cls: type[MDEngine], engine_kwargs: dict[str, Any], walltime_per_part: float)#

Propagate a trajectory in parts of walltime until given number of steps.

Useful to make full use of backfilling with short(ish) simulation jobs and also to run simulations that are longer than the timelimit.

Initialize an InPartTrajectoryPropagator.

Parameters:

  • n_steps (int) – Number of integration steps to do in total.

  • engine_cls (asyncmd.mdengine.MDEngine) – Class of the MD engine to use, uninitialized!

  • engine_kwargs (dict) – Dictionary of key word arguments to initialize the MD engine.

  • walltime_per_part (float) – Walltime per trajectory segment, in hours.

async cut_and_concatenate(trajs: list[Trajectory], tra_out: str, **concatenate_kwargs) → Trajectory | None#

Cut and concatenate the trajectory until it has length n_steps.

Take a list of trajectory segments and form one continuous trajectory containing n_steps integration steps. The expected input is a list of trajectories, e.g. the output of the propagate() method. Returns None if self.n_steps is zero.

Parameters:

  • trajs (list[Trajectory]) – Trajectory segments to cut and concatenate.

  • tra_out (str) – Absolute or relative path for the concatenated output trajectory.

  • concatenate_kwargs (dict) –

    All (other) keyword arguments will be passed as is to the TrajectoryConcatenator.concatenate() method. These include, e.g.,

    • struct_outstr, optional

      Absolute or relative path to the output structure file, if None we will use the structure file of the first traj, by default None.

    • overwritebool, optional

      Whether we should overwrite tra_out if it exists, by default False.

Returns:

traj_out – The concatenated output trajectory.

Return type:

asyncmd.Trajectory

Raises:

ValueError – If the given trajectories are to short to create a trajectory containing n_steps integration steps

async propagate(starting_configuration: Trajectory, workdir: str, deffnm: str, *, continuation: bool = False) → list[Trajectory]#

Propagate the trajectory until self.n_steps integration are done.

Return a list of trajectory segments and the first condition fulfilled.

Parameters:

  • starting_configuration (asyncmd.Trajectory) – The configuration (including momenta) to start MD from.

  • workdir (str) – Absolute or relative path to the working directory.

  • deffnm (str) – MD engine deffnm for trajectory parts and other files.

  • continuation (bool, optional) – Whether we are continuing a previous MD run (with the same deffnm and working directory), by default False. Note that when doing continuations and n_steps is lower than the number of steps done already found in the directory, we still return all trajectory parts (i.e. potentially too much). cut_and_concatenate() can return a trimmed subtrajectory.

Returns:

traj_segments – List of trajectory (segments), ordered in time.

Return type:

list[Trajectory]

async propagate_and_concatenate(starting_configuration: Trajectory, workdir: str, deffnm: str, *, tra_out: str, continuation: bool = False, **concatenate_kwargs) → Trajectory | None#

Chain propagate() and cut_and_concatenate() methods.

Parameters:

  • starting_configuration (asyncmd.Trajectory) – The configuration (including momenta) to start MD from.

  • workdir (str) – Absolute or relative path to the working directory.

  • deffnm (str) – MD engine deffnm for trajectory parts and other files.

  • tra_out (str) – Absolute or relative path for the concatenated output trajectory.

  • continuation (bool, optional) – Whether we are continuing a previous MD run (with the same deffnm and working directory), by default False.

  • concatenate_kwargs (dict) –

    All (other) keyword arguments will be passed as is to the TrajectoryConcatenator.concatenate() method. These include, e.g.,

    • struct_outstr, optional

      Absolute or relative path to the output structure file, if None we will use the structure file of the first traj, by default None.

    • overwritebool, optional

      Whether we should overwrite tra_out if it exists, by default False.

Returns:

traj_out – The concatenated output trajectory.

Return type:

asyncmd.Trajectory

async remove_parts(workdir: str, deffnm: str, *, file_endings_to_remove: list[str] | None = None, remove_mda_offset_and_lock_files: bool = True, remove_asyncmd_npz_caches: bool = True) → None#

Remove all $deffnm.part$num.$file_ending files for file_endings.

Can be useful to clean the workdir from temporary files if e.g. only the concatenate trajectory is of interest (like in TPS).

Parameters:

  • workdir (str) – The directory to clean.

  • deffnm (str) – The deffnm that the files we clean must have.

  • file_endings_to_remove (list[str] | None, optional) – The strings in the list file_endings_to_remove indicate which file endings to remove. The ‘special’ string “trajectories” will be translated to the file ending of the trajectories the engine produces, i.e. engine.output_traj_type. E.g. passing file_endings_to_remove=["trajectories", "log"] will result in removal of trajectory parts and the log files. If you add “edr” to the list we would also remove the edr files. By default, i.e., if None the list will be [“trajectories”, “log”].

  • remove_mda_offset_and_lock_files (bool, optional) – Whether to remove any (hidden) offset and lock files generated by MDAnalysis associated with the removed trajectory files (if they exist). By default True.

  • remove_asyncmd_npz_caches (bool, optional) – Whether to remove any (hidden) npz cache files generated by asyncmd associated with the removed trajectory files (if they exist). By default True.

Propagation until arbitrary conditions are fulfilled#

class asyncmd.trajectory.ConditionalTrajectoryPropagator(conditions, *, engine_cls: type[MDEngine], engine_kwargs: dict[str, Any], walltime_per_part: float, max_steps: int | None = None, max_frames: int | None = None)#

Propagate a trajectory until any of the given conditions is fulfilled.

This class propagates the trajectory using a given MD engine (class) in small chunks (chunksize is determined by walltime_per_part) and checks after every chunk is done if any condition has been fulfilled. It then returns a list of trajectory parts and the index of the condition first fulfilled. It can also concatenate the parts into one trajectory, which then starts with the starting configuration and ends with the frame fulfilling the condition.

Notes

We assume that every condition function returns a list/ a 1d array with True or False for each frame, i.e. if we fulfill condition at any given frame. We assume non-overlapping conditions, i.e. a configuration can not fulfill two conditions at the same time, it is the users responsibility to ensure that their conditions are sane.

Initialize a ConditionalTrajectoryPropagator.

Parameters:

  • conditions (list[callable], usually list[TrajectoryFunctionWrapper]) – List of condition functions, usually wrapped function for asynchronous application, but can be any callable that takes a asyncmd.Trajectory and returns an array of True and False values (one value per frame).

  • engine_cls (asyncmd.mdengine.MDEngine) – Class of the MD engine to use, uninitialized!

  • engine_kwargs (dict) – Dictionary of key word arguments to initialize the MD engine.

  • walltime_per_part (float) – Walltime per trajectory segment, in hours.

  • max_steps (int, optional) – Maximum number of integration steps to do before stopping the simulation because it did not commit to any condition, by default None. Takes precedence over max_frames if both given.

  • max_frames (int, optional) – Maximum number of frames to produce before stopping the simulation because it did not commit to any condition, by default None.

Notes

max_steps and max_frames are redundant since max_steps = max_frames * output_frequency, if both are given max_steps takes precedence.

async cut_and_concatenate(trajs: list[Trajectory], tra_out: str, **concatenate_kwargs) → tuple[Trajectory, int]#

Cut and concatenate the trajectory until the first condition is True.

Take a list of trajectory segments and form one continuous trajectory until the first frame that fulfills any condition. The first frame in that fulfills any condition is included in the trajectory. The expected input is a list of trajectories, e.g. the output of the propagate() method.

Parameters:

  • trajs (list[Trajectory]) – Trajectory segments to cut and concatenate.

  • tra_out (str) – Absolute or relative path for the concatenated output trajectory.

  • concatenate_kwargs (dict) –

    All (other) keyword arguments will be passed as is to the TrajectoryConcatenator.concatenate() method. These include, e.g.,

    • struct_outstr, optional

      Absolute or relative path to the output structure file, if None we will use the structure file of the first traj, by default None.

    • overwritebool, optional

      Whether we should overwrite tra_out if it exists, by default False.

Returns:

(traj_out, idx_of_condition_fulfilled) – The concatenated output trajectory from starting configuration until the first condition is True and the index to the condition function in conditions.

Return type:

(Trajectory, int)

async propagate(starting_configuration: Trajectory, workdir: str, deffnm: str, *, continuation: bool = False) → tuple[list[Trajectory], int]#

Propagate the trajectory until any condition is fulfilled.

Return a list of trajectory segments and the first condition fulfilled.

Parameters:

  • starting_configuration (Trajectory) – The configuration (including momenta) to start MD from.

  • workdir (str) – Absolute or relative path to the working directory.

  • deffnm (str) – MD engine deffnm for trajectory parts and other files.

  • continuation (bool, optional) – Whether we are continuing a previous MD run (with the same deffnm and working directory), by default False.

Returns:

(traj_segments, idx_of_condition_fulfilled) – List of trajectory (segments), the last entry is the one on which the first condition is fulfilled at some frame, the integer is the index to the condition function in conditions.

Return type:

(list[Trajectory], int)

Raises:

MaxStepsReachedError – When the defined maximum number of integration steps/trajectory frames has been reached.

async propagate_and_concatenate(starting_configuration: Trajectory, workdir: str, deffnm: str, *, tra_out: str, continuation: bool = False, **concatenate_kwargs) → tuple[Trajectory, int]#

Chain propagate() and cut_and_concatenate() methods.

Parameters:

  • starting_configuration (Trajectory) – The configuration (including momenta) to start MD from.

  • workdir (str) – Absolute or relative path to the working directory.

  • deffnm (str) – MD engine deffnm for trajectory parts and other files.

  • tra_out (str) – Absolute or relative path for the concatenated output trajectory.

  • continuation (bool, optional) – Whether we are continuing a previous MD run (with the same deffnm and working directory), by default False.

  • concatenate_kwargs (dict) –

    All (other) keyword arguments will be passed as is to the TrajectoryConcatenator.concatenate() method. These include, e.g.,

    • struct_outstr, optional

      Absolute or relative path to the output structure file, if None we will use the structure file of the first traj, by default None.

    • overwritebool, optional

      Whether we should overwrite tra_out if it exists, by default False.

Returns:

(traj_out, idx_of_condition_fulfilled) – The concatenated output trajectory from starting configuration until the first condition is True and the index to the condition function in conditions.

Return type:

(Trajectory, int)

Raises:

MaxStepsReachedError – When the defined maximum number of integration steps/trajectory frames has been reached in propagate().

async remove_parts(workdir: str, deffnm: str, *, file_endings_to_remove: list[str] | None = None, remove_mda_offset_and_lock_files: bool = True, remove_asyncmd_npz_caches: bool = True) → None#

Remove all $deffnm.part$num.$file_ending files for file_endings.

Can be useful to clean the workdir from temporary files if e.g. only the concatenate trajectory is of interest (like in TPS).

Parameters:

  • workdir (str) – The directory to clean.

  • deffnm (str) – The deffnm that the files we clean must have.

  • file_endings_to_remove (list[str] | None, optional) – The strings in the list file_endings_to_remove indicate which file endings to remove. The ‘special’ string “trajectories” will be translated to the file ending of the trajectories the engine produces, i.e. engine.output_traj_type. E.g. passing file_endings_to_remove=["trajectories", "log"] will result in removal of trajectory parts and the log files. If you add “edr” to the list we would also remove the edr files. By default, i.e., if None the list will be [“trajectories”, “log”].

  • remove_mda_offset_and_lock_files (bool, optional) – Whether to remove any (hidden) offset and lock files generated by MDAnalysis associated with the removed trajectory files (if they exist). By default True.

  • remove_asyncmd_npz_caches (bool, optional) – Whether to remove any (hidden) npz cache files generated by asyncmd associated with the removed trajectory files (if they exist). By default True.

property conditions: FlagChangeList#

List of (wrapped) condition functions.

Note

The function below is an alias for/imported from

asyncmd.trajectory.propagate.construct_tp_from_plus_and_minus_traj_segments()#

Note: It is recommended/preferred to use asyncmd.trajectory.construct_tp_from_plus_and_minus_traj_segments().

async asyncmd.trajectory.construct_tp_from_plus_and_minus_traj_segments(*, minus_trajs: list[Trajectory], minus_state: int, plus_trajs: list[Trajectory], plus_state: int, state_funcs: list[TrajectoryFunctionWrapper], tra_out: str, **concatenate_kwargs) → Trajectory#

Construct a continuous TP from plus and minus segments until states.

This is used e.g. in TwoWay TPS or if you try to get TPs out of a committor simulation. Note, that this inverts all velocities on the minus segments.

Parameters:

  • minus_trajs (list[Trajectory]) – Trajectories that go “backward in time”, these are going to be inverted

  • minus_state (int) – Index (in state_funcs) of the first state reached on minus trajs.

  • plus_trajs (list[Trajectory]) – Trajectories that go “forward in time”, these are taken as is.

  • plus_state (int) – Index (in state_funcs) of the first state reached on plus trajs.

  • state_funcs (list[TrajectoryFunctionWrapper]) – List of wrapped state functions, the indices to the states must match the minus and plus state indices!

  • tra_out (str) – Absolute or relative path to the output trajectory file.

  • concatenate_kwargs (dict) –

    All (other) keyword arguments will be passed as is to the TrajectoryConcatenator.concatenate() method. These include, e.g.,

    • struct_outstr, optional

      Absolute or relative path to the output structure file, if None we will use the structure file of the first minus_traj, by default None.

    • overwritebool, optional

      Whether we should overwrite tra_out if it exists, by default False.

Returns:

The constructed transition.

Return type:

Trajectory