Frame extraction and trajectory concatenation

Frame extraction and trajectory concatenation#

FrameExtractors#

The module asyncmd.trajectory.convert contains a number of classes to extract arbitrary frames from Trajectory objects to easily (re)initialize MD simulations from these configurations. All FrameExtractor subclasses share a common interface and differ only in the modification applied to the configuration before writing it out. The user-facing (instantiable FrameExtractor classes) are all (re)exported to the asyncmd.trajectory module for more convenient importing. Currently implemented are:

Implementing your own FrameExtractor subclass with a custom modification is as easy as subclassing the abstract base class FrameExtractor and overwriting its FrameExtractor.apply_modification method.

Note

All FrameExtractor subclasses have an async version of their function doing the work (FrameExtractor.extract vs FrameExtractor.extract_async). The awaitable version does exactly the same as its sync counterpart, just that it does so in a separate thread.

See also

The example notebook on FrameExtractors. It also contains a basic example on how to write your own FrameExtractor subclass.

class asyncmd.trajectory.convert.FrameExtractor(*, mda_transformations: list[Callable] | None = None, mda_transformations_setup_func: Callable | None = None)#

Abstract base class for FrameExtractors.

Implements the extract method which is common in all FrameExtractors. Subclasses only need to implement apply_modification which is called by extract to modify the frame just before writing it out.

Initialize a FrameExtractor.

Parameters:

  • mda_transformations (list of callables, optional) – If given will be added as a list of transformations to the MDAnalysis universe as universe.trajectory.add_transformation(*mda_transformations). See the mda_transformations_setup_func argument if your transformations need additional universe-dependant arguments, e.g. atomgroups from the universe. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

  • mda_transformations_setup_func (callable, optional) – If given will be called to attach user-defined MDAnalysis transformations to the universe. The function must take a universe as argument and return the universe with attached transformations. I.e. it is expected that the function calls universe.trajectory.add_transformations(*list_of_trafos) after defining list_of_trafos (potentially depending on the universe or atomgroups therein) and then finally returns the universe with trafos. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

abstractmethod apply_modification(universe: Universe, ts: Timestep)#

Apply modification to selected frame (timestep/universe).

This function will be called when the current timestep is at the chosen frame index and is expected to apply the subclass specific modifications to the frame via modifying the mdanalysis timestep and universe objects inplace. After this function finishes the frame is written out, i.e. with any potential modifications applied. No return value is expected or considered from this method, the modifications of the timestep/universe are nonlocal anyway.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – The mdanalysis universe associated with the trajectory.

  • ts (MDAnalysis.coordinates.base.Timestep) – The mdanalysis timestep of the frame to extract.

extract(outfile: str, traj_in: Trajectory, idx: int, *, struct_out: str | None = None, overwrite: bool = False) → Trajectory#

Extract a single frame from given trajectory and write it out.

Parameters:

  • outfile (str) – Absolute or relative path to the output trajectory. Expected to be with file ending, e.g. “traj.trr”.

  • traj_in (Trajectory) – Input trajectory from which we will extract the frame at idx.

  • idx (int) – Index of the frame to extract in traj_in.

  • struct_out (str, optional) – None, or absolute or relative path to a structure file, by default None. If not None we will use the given file as structure file for the returned trajectory object, else we use the structure file of traj_in.

  • overwrite (bool, optional) – Whether to overwrite outfile if it exists, by default False.

Returns:

Trajectory object holding a trajectory with the extracted frame.

Return type:

Trajectory

Raises:

  • FileExistsError – If outfile exists and overwrite=False.

  • FileNotFoundError – If struct_out is given but does not exist.

async extract_async(outfile: str, traj_in: Trajectory, idx: int, *, struct_out: str | None = None, overwrite: bool = False) → Trajectory#

Extract a single frame from given trajectory and write it out.

Parameters:

  • outfile (str) – Absolute or relative path to the output trajectory. Expected to be with file ending, e.g. “traj.trr”.

  • traj_in (Trajectory) – Input trajectory from which we will extract the frame at idx.

  • idx (int) – Index of the frame to extract in traj_in.

  • struct_out (str, optional) – None, or absolute or relative path to a structure file, by default None. If not None we will use the given file as structure file for the returned trajectory object, else we use the structure file of traj_in.

  • overwrite (bool, optional) – Whether to overwrite outfile if it exists, by default False.

Returns:

Trajectory object holding a trajectory with the extracted frame.

Return type:

Trajectory

Raises:

  • FileExistsError – If outfile exists and overwrite=False.

  • FileNotFoundError – If struct_out is given but does not exist.

class asyncmd.trajectory.NoModificationFrameExtractor(*, mda_transformations: list[Callable] | None = None, mda_transformations_setup_func: Callable | None = None)#

Extract a frame from a trajectory, write it out without modification.

Initialize a FrameExtractor.

Parameters:

  • mda_transformations (list of callables, optional) – If given will be added as a list of transformations to the MDAnalysis universe as universe.trajectory.add_transformation(*mda_transformations). See the mda_transformations_setup_func argument if your transformations need additional universe-dependant arguments, e.g. atomgroups from the universe. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

  • mda_transformations_setup_func (callable, optional) – If given will be called to attach user-defined MDAnalysis transformations to the universe. The function must take a universe as argument and return the universe with attached transformations. I.e. it is expected that the function calls universe.trajectory.add_transformations(*list_of_trafos) after defining list_of_trafos (potentially depending on the universe or atomgroups therein) and then finally returns the universe with trafos. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

apply_modification(universe: Universe, ts: Timestep)#

Apply no modification to the extracted frame.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – The mdanalysis universe associated with the trajectory.

  • ts (MDAnalysis.coordinates.base.Timestep) – The mdanalysis timestep of the frame to extract.

class asyncmd.trajectory.InvertedVelocitiesFrameExtractor(*, mda_transformations: list[Callable] | None = None, mda_transformations_setup_func: Callable | None = None)#

Extract a frame from a trajectory, write it out with inverted velocities.

Initialize a FrameExtractor.

Parameters:

  • mda_transformations (list of callables, optional) – If given will be added as a list of transformations to the MDAnalysis universe as universe.trajectory.add_transformation(*mda_transformations). See the mda_transformations_setup_func argument if your transformations need additional universe-dependant arguments, e.g. atomgroups from the universe. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

  • mda_transformations_setup_func (callable, optional) – If given will be called to attach user-defined MDAnalysis transformations to the universe. The function must take a universe as argument and return the universe with attached transformations. I.e. it is expected that the function calls universe.trajectory.add_transformations(*list_of_trafos) after defining list_of_trafos (potentially depending on the universe or atomgroups therein) and then finally returns the universe with trafos. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

apply_modification(universe: Universe, ts: Timestep)#

Invert all momenta of the extracted frame.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – The mdanalysis universe associated with the trajectory.

  • ts (MDAnalysis.coordinates.base.Timestep) – The mdanalysis timestep of the frame to extract.

class asyncmd.trajectory.RandomVelocitiesFrameExtractor(T: float, *, mda_transformations: list[Callable] | None = None, mda_transformations_setup_func: Callable | None = None)#

Extract a frame from a trajectory, write it out with randomized velocities.

T#

Temperature of the Maxwell-Boltzmann distribution for velocity generation, in Kelvin.

Type:

float

Initialize a RandomVelocitiesFrameExtractor.

Parameters:

  • T (float) – Temperature of the Maxwell-Boltzmann distribution, in Kelvin.

  • mda_transformations (list of callables, optional) – If given will be added as a list of transformations to the MDAnalysis universe as universe.trajectory.add_transformation(*mda_transformations). See the mda_transformations_setup_func argument if your transformations need additional universe-dependant arguments, e.g. atomgroups from the universe. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

  • mda_transformations_setup_func (callable, optional) – If given will be called to attach user-defined MDAnalysis transformations to the universe. The function must take a universe as argument and return the universe with attached transformations. I.e. it is expected that the function calls universe.trajectory.add_transformations(*list_of_trafos) after defining list_of_trafos (potentially depending on the universe or atomgroups therein) and then finally returns the universe with trafos. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

apply_modification(universe: Universe, ts: Timestep)#

Draw random Maxwell-Boltzmann velocities for extracted frame.

Parameters:

  • universe (MDAnalysis.core.universe.Universe) – The mdanalysis universe associated with the trajectory.

  • ts (MDAnalysis.coordinates.base.Timestep) – The mdanalysis timestep of the frame to extract.

Trajectory concatenation#

The asyncmd.trajectory.convert module furthermore contains a class to concatenate Trajectory segments, the TrajectoryConcatenator. Again, it is reexported in the asyncmd.trajectory module for convenient imports. It can be used to concatenate lists of trajectory segments in any order (and possibly with inverted momenta) by passing a list of trajectory segments and a list of tuples (slices) that specify the frames to use in the concatenated output trajectory. Note that this class gives you all customizability at the cost of complexity, if you just want to construct a transition from trajectory segments, the construct_tp_from_plus_and_minus_traj_segments function is most probably easier to use and what you want (it uses the TrajectoryConcatenator under the hood anyway).

Note

The TrajectoryConcatenator also has an async version of the function doing the work (TrajectoryConcatenator.concatenate vs TrajectoryConcatenator.concatenate respectively). Similar to the FrameExtractor subclasses, the awaitable versions does exactly the same as its sync counterpart.

class asyncmd.trajectory.TrajectoryConcatenator(invert_v_for_negative_step: bool = True, remove_double_frames: bool = True, *, mda_transformations: list[Callable] | None = None, mda_transformations_setup_func: Callable | None = None)#

Create concatenated trajectory from given trajectories and frames.

The concatenate method takes a list of trajectories plus a list of slices and returns one trajectory containing only the selected frames in the order specified by the slices. Velocities are automatically inverted if the step of a slice is negative, this can be controlled via the invert_v_for_negative_step attribute. Double frames are also automatically removed, which can be controlled via the remove_double_frames attribute. We assume that all trajs have the same structure file and attach the structure of the first traj if not told otherwise. Note that you can pass MDAnalysis transformations to this class to transform your trajectories on-the-fly, see the mda_transformations and mda_transformations_setup_func arguments to __init__().

invert_v_for_negative_step#

Whether to invert all momenta for segments with negative stride.

Type:

bool

remove_double_frames#

Whether we should (try to) remove double frames from the concatenated output trajectory. Note that a simple heuristic is used to determine double frames, frames count as double if the integration time is the same for both frames.

Type:

bool

Initialize a TrajectoryConcatenator.

Parameters:

  • invert_v_for_negative_step (bool, optional) – Whether to invert all momenta for segments with negative stride, by default True.

  • remove_double_frames (bool, optional) – Whether we should (try to) remove double frames from the concatenated output trajectory, by default True.

  • mda_transformations (list of callables, optional) – If given will be added as a list of transformations to the MDAnalysis universe as universe.trajectory.add_transformation(*mda_transformations). See the mda_transformations_setup_func argument if your transformations need additional universe-dependant arguments, e.g. atomgroups from the universe. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

  • mda_transformations_setup_func (callable, optional) – If given will be called to attach user-defined MDAnalysis transformations to the universe. The function must take a universe as argument and return the universe with attached transformations. I.e. it is expected that the function calls universe.trajectory.add_transformations(*list_of_trafos) after defining list_of_trafos (potentially depending on the universe or atomgroups therein) and then finally returns the universe with trafos. See https://docs.mdanalysis.org/stable/documentation_pages/trajectory_transformations.html for more on MDAnalysis transformations.

concatenate(trajs: list[Trajectory], slices: list[tuple], tra_out: str, *, struct_out: str | None = None, overwrite: bool = False) → Trajectory#

Create concatenated trajectory from given trajectories and frames.

Parameters:

  • trajs (list[Trajectory]) – List of asyncmd.Trajectory objects to concatenate.

  • slices (list[tuple]) – List of tuples (start, stop, step) specifing the slices of the trajectories to take. Must be of len(trajs).

  • tra_out (str) – Output trajectory filepath, absolute or relativ to current working directory.

  • struct_out (str or None, optional) – Output structure filepath, if None we will take the structure file of the first trajectory in trajs, by default None.

  • overwrite (bool, optional) – Whether we should overwrite existing output trajectories, by default False.

Returns:

The concatenated output trajectory.

Return type:

Trajectory

Raises:

  • FileExistsError – If tra_out exists and overwrite=False.

  • FileNotFoundError – If struct_out given but the file is not accessible.

async concatenate_async(trajs: list[Trajectory], slices: list[tuple], tra_out: str, *, struct_out: str | None = None, overwrite: bool = False) → Trajectory#

Create concatenated trajectory from given trajectories and frames.

Parameters:

  • trajs (list[Trajectory]) – List of asyncmd.Trajectory objects to concatenate.

  • slices (list[tuple]) – List of tuples (start, stop, step) specifing the slices of the trajectories to take. Must be of len(trajs).

  • tra_out (str) – Output trajectory filepath, absolute or relativ to current working directory.

  • struct_out (str or None, optional) – Output structure filepath, if None we will take the structure file of the first trajectory in trajs, by default None.

  • overwrite (bool, optional) – Whether we should overwrite existing output trajectories, by default False.

Returns:

The concatenated output trajectory.

Return type:

Trajectory

Raises:

  • FileExistsError – If tra_out exists and overwrite=False.

  • FileNotFoundError – If struct_out given but the file is not accessible.