Utility functions for common operations related to MD usage

asyncmd comes with a number of (hopefully) useful utility functions related to MD usage. These functions are available on a general (engine-agnostic) level in asyncmd.utils and have their engine-specific implementations in the respective submodule for the engine, e.g., asyncmd.gromacs.utils for the gromacs engines. The engine-agnostic versions have an additional call argument, the engine-class, to be able to dispatch to the correct engine submodule function. If you know which engine-classes you will be using, you can directly use the respective engine-specific implementation. However, if you intend to write engine-class agnostic code (e.g. to let users pass an engine class), you should use the engine-agnostic versions.

Engine-agnostic versions

asyncmd.utils.ensure_mdconfig_options(mdconfig: MDConfig, genvel: str = 'no', continuation: str = 'yes') → MDConfig

Ensure that some commonly used mdconfig options have the given values.

NOTE: Modifies the MDConfig inplace and returns it.

Parameters:

• mdconfig (MDConfig) – Config object for which values should be ensured.

• genvel (str, optional) – Whether to generate velocities from a Maxwell-Boltzmann distribution (“yes” or “no”), by default “no”.

• continuation (str, optional) – Whether to apply constraints to the initial configuration (“yes” or “no”), by default “yes”

Returns:

Reference to input config object with values for options as given.

Return type:

MDConfig

Raises:

ValueError – If the MDConfig belongs to an unknown subclass not dispatchable to any specific engine submodule.

asyncmd.utils.nstout_from_mdconfig(mdconfig: MDConfig, output_traj_type: str) → int

Return output step for given mdconfig and output_traj_type.

Parameters:

• mdconfig (MDConfig) – An engine specific subclass of MDConfig.

• output_traj_type (str) – The output trajectory type for which we want the output frequency.

Returns:

(Smallest) output step in integration steps.

Return type:

int

Raises:

ValueError – Raised when the MDConfig subclass is not known.

async asyncmd.utils.get_all_traj_parts(folder: str, deffnm: str, engine: MDEngine) → list[Trajectory]

List all trajectories in folder by given engine class with given deffnm.

Parameters:

• folder (str) – Absolute or relative path to a folder.

• deffnm (str) – deffnm used by the engines simulation run from which we want the trajs.

• engine (MDEngine) – The engine that produced the trajectories (or one from the same class and with similar init args)

Returns:

All trajectory parts from folder that match deffnm and engine in order.

Return type:

list[Trajectory]

Raises:

ValueError – Raised when the engine class is unknown.

async asyncmd.utils.get_all_file_parts(folder: str, deffnm: str, file_ending: str) → list[str]

Find and return all files with given ending produced by a MDEngine.

NOTE: This returns only the parts that exist in ascending order.

Parameters:

• folder (str) – Path to a folder to search for trajectory parts.

• deffnm (str) – deffnm (prefix of filenames) used in the simulation.

• file_ending (str) – File ending of the requested filetype (with or without preceding “.”).

Returns:

Ordered list of filepaths for files with given ending.

Return type:

list[str]

Gromacs-specific versions

asyncmd.gromacs.utils.ensure_mdp_options(mdp: MDP, genvel: str = 'no', continuation: str = 'yes') → MDP

Ensure that some commonly used mdp options have the given values.

NOTE: Modifies the MDP inplace and returns it.

Parameters:

• mdp (MDP) – Config object for which values should be ensured.

• genvel (str, optional) – Value for genvel option (“yes” or “no”), by default “no”.

• continuation (str, optional) – Value for continuation option (“yes” or “no”), by default “yes”.

Returns:

Reference to input config object with values for options as given.

Return type:

MDP

asyncmd.gromacs.utils.nstout_from_mdp(mdp: MDP, traj_type: str = 'TRR') → int

Get minimum number of steps between outputs for trajectories from MDP.

Parameters:

• mdp (MDP) – Config object from which the output step should be read.

• traj_type (str, optional) – Trajectory format for which output step should be read, “XTC” or “TRR”, by default “TRR”.

Returns:

Minimum number of steps between two writes.

Return type:

int

Raises:

• ValueError – Raised when an unknown trajectory format traj_type is given.

• ValueError – Raised when the given MDP would result in no output for the given trajectory format traj_type.

async asyncmd.gromacs.utils.get_all_traj_parts(folder: str, deffnm: str, traj_type: str = 'TRR') → list[Trajectory]

Find and return a list of trajectory parts produced by a GmxEngine.

NOTE: This returns only the parts that exist in ascending order.

Parameters:

• folder (str) – path to a folder to search for trajectory parts

• deffnm (str) – deffnm (prefix of filenames) used in the simulation

• traj_type (str, optional) – Trajectory file ending(“XTC”, “TRR”, “TNG”, …), by default “TRR”

Returns:

Ordered list of all trajectory parts with given deffnm and type.

Return type:

list[Trajectory]

async asyncmd.gromacs.utils.get_all_file_parts(folder: str, deffnm: str, file_ending: str) → list[str]

Find and return all files with given ending produced by GmxEngine.

NOTE: This returns only the parts that exist in ascending order.

Parameters:

• folder (str) – Path to a folder to search for trajectory parts.

• deffnm (str) – deffnm (prefix of filenames) used in the simulation.

• file_ending (str) – File ending of the requested filetype (with or without preceeding “.”).

Returns:

Ordered list of filepaths for files with given ending.

Return type:

list[str]