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 | type[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 trajectories.

• engine (MDEngine | type[MDEngine]) – The engine that produced the trajectories (or one from the same class and with similar init args). Note that it is also possible to pass an uninitialized engine class, but then the default trajectory output type will be returned.

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, engine: MDEngine | type[MDEngine]) → 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 “.”).

• engine (MDEngine | type[MDEngine]) – The engine or engine class that produced the file parts.

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 preceding “.”).

Returns:

Ordered list of filepaths for files with given ending.

Return type:

list[str]