Gromacs engines

Gromacs engines#

The asyncmd.gromacs module contains all classes and functions to control gromacs engines from python. Most notably the MDP (which provides a dictionary-like interface to read, modify and write gromacs mdp files), and the two gromacs engines GmxEngine and SlurmGmxEngine which share most of their interface with the important difference that the SlurmGmxEngine submits all MD simulations via slurm while the GmxEngine runs locally on the same machine as the python process.

MD parameter (`mdp`) file manipulation#

class asyncmd.gromacs.MDP(original_file: str)#

Parse, modify and write gromacs .mdp files.

Make all options set in a given mdp file available via a dictionary of option, list of values pairs. Includes automatic types for known options and keeps track if any options have been changed compared to the original file.

Initialize a LineBasedMDConfig.

Parameters:: original_file (str) – Path to original config file (absolute or relative).

property original_file: str#

Return the original config file this LineBasedMDConfig parsed.

Returns:: Path to the original file.
Return type:: str

property changed: bool#

Indicate if the current configuration differs from original_file.

Returns:: Whether we changed the configuration w.r.t. original_file.
Return type:: bool

parse()#: Parse the current self.original_file to update own state.

write(outfile: str, overwrite: bool = False) → None#

Write current configuration to outfile.

Parameters:

outfile (str) – Path to outfile (relative or absolute).
overwrite (bool, optional) – If True overwrite existing files, by default False.

Raises:

ValueError – Raised when overwrite=False but outfile exists.

Run MD locally#

class asyncmd.gromacs.GmxEngine(mdconfig: MDP, gro_file: str, top_file: str, *, ndx_file: str | None = None, **kwargs)#

Steer gromacs molecular dynamics simulation from python.

An async/await enabled wrapper around gromacs grompp and gromacs mdrun. Please use the power of concurrent execution of computationally bound subprocesses responsibly…or crash your workstation ;) The SlurmGmxEngine alleviates this problem somewhat by submitting the (computationally expensive) mdruns via SLURM…in that case please have in mind that your colleagues might also want to use the cluster, and also that someone might have set a job/submission limit :)

grompp_executable#

Name or path to the grompp executable, by default “gmx grompp”.

Type:: str

mdrun_executable#

Name or path to the mdrun executable, by default “gmx mdrun”.

Type:: str

grompp_extra_args#

Can be used to pass extra command line arguments to grompp calls, e.g. “-maxwarn 1”. Will simply be appended to the end of the command after a separating space.

Type:: str

mdrun_extra_args#

Can be used to pass extra command line arguments to mdrun calls, e.g. “-ntomp 8”. Will simply be appended to the end of the command after a separating space.

Type:: str

output_traj_type#

Sets the trajectory type (ending) this engine returns/looks for. Note that we simply ignore all other trajectories, i.e. depending on the MDP settings we will still write xtc and trr, but return only the trajectories with matching ending.

Type:: str

mdrun_time_conversion_factor#

When running gmx mdrun with a given time_limit, run it for mdrun_time_conversion_factor * time_limit. This option is relevant only for the SlurmGmxEngine and here ensures that gmx mdrun finishes during the slurm time limit (which will be set to time_limit). The default value for the SlurmGmxEngine is 0.99.

Type:: float

Initialize a GmxEngine.

Note that all attributes can be set at initialization by passing keyword arguments with their name, e.g. mdrun_extra_args="-ntomp 2" to instruct gromacs to use 2 openMP threads.

Parameters:

mdconfig (MDP) – The molecular dynamics parameters.
gro_file (str) – Absolute or relative path to a gromacs structure file.
top_file (str) – Absolute or relative path to a gromacs topology (.top) file.
ndx_file (str or None) – Optional, absolute or relative path to a gromacs index file.

async apply_constraints(conf_in: Trajectory, conf_out_name: str, *, workdir: str = '.') → Trajectory#

Apply constraints to given configuration.

Parameters:

conf_in (Trajectory) – A (one-frame) trajectory, only the first frame will be used.
conf_out_name (str) – Output path for the constrained configuration.
workdir (str) – Working directory for the constraint engine, by default “.”, a subfolder with random name will be created.

Returns:

The constrained configuration.

Return type:

Trajectory

async generate_velocities(conf_in: Trajectory, conf_out_name: str, *, workdir: str = '.') → Trajectory#

Generate random Maxwell-Boltzmann velocities for given configuration.

This also applies constraints to the configuration (as gromacs does when generating velocities).

Parameters:

conf_in (Trajectory) – A (one-frame) trajectory, only the first frame will be used.
conf_out_name (str) – Output path for the velocity randomized configuration.
workdir (str) – Working directory for the constraint engine, by default “.”, a subfolder with random name will be created.

Returns:

The configuration with random velocities and constraints enforced.

Return type:

Trajectory

async prepare(starting_configuration: Trajectory | None | str, workdir: str, deffnm: str) → None#

Prepare a fresh simulation (starting with part0001).

Can also be used to continue a simulation from a checkpoint file with matching name (‘deffnm.cpt’). In that case, the ‘simulation-part’ mdp option must match the number of the next part to be generated, e.g. it must be 2 if the last part generated was part0001. The previously generated trajectory files do not need to exist. If ‘simulation-part’ is not set and previous trajectories are found an error is raised.

Parameters:

starting_configuration (Trajectory or None or str) – A (trr) trajectory of which we take the first frame as starting configuration (including velocities) or None, then the initial configuration is the gro-file. Can also be a str, then it is assumed to be the path to a trr, cpt, or tng (i.e. a full precision trajectory) and will be passed directly to grompp.
workdir (str) – Absolute or relative path to an existing directory to use as working directory.
deffnm (str) – The name (prefix) to use for all files.

async prepare_from_files(workdir: str, deffnm: str) → None#

Prepare continuation run starting from the last part found in workdir.

Expects the checkpoint file and last trajectory part to exist, will (probably) fail otherwise.

Parameters:

workdir (str) – Absolute or relative path to an existing directory to use as working directory.
deffnm (str) – The name (prefix) to use for all files.

async run(nsteps: int | None = None, walltime: float | None = None, steps_per_part: bool = False) → Trajectory | None#

Run simulation for specified number of steps or/and a given walltime.

Note that you can pass both nsteps and walltime and the simulation will stop on the condition that is reached first.

Return None if no integration is needed because nsteps integration steps have already been performed.

Parameters:

nsteps (int or None) – Integration steps to run for either in total [as measured since the last call to self.prepare()] or in the newly generated trajectory part, see also the steps_per_part argument.
walltime (float or None) – (Maximum) walltime in hours, None means unlimited.
steps_per_part (bool) – If True nsteps are the steps to do in the new trajectory part, else the total number of steps since the last call to prepare() are counted, default False.

async run_steps(nsteps: int, steps_per_part: bool = False) → Trajectory | None#

Run simulation for specified number of steps.

Return None if no integration is needed because nsteps integration steps have already been performed.

Parameters:

nsteps (int or None) – Integration steps to run for either in total [as measured since the last call to self.prepare()] or in the newly generated trajectory part, see also the steps_per_part argument.
steps_per_part (bool) – If True nsteps are the steps to do in the new trajectory part, else the total number of steps since the last call to prepare() are counted, default False.

async run_walltime(walltime: float, max_steps: int | None = None) → Trajectory | None#

Run simulation for a given walltime.

Return None if no integration is needed because max_steps integration steps have already been performed.

Parameters:

walltime (float or None) – (Maximum) walltime in hours.
max_steps (int | None, optional) – If not None, terminate when max_steps integration steps are reached in total, also if this is before walltime is reached. By default None.

property current_trajectory: Trajectory | None#

Return the last finished trajectory (part).

Returns:: Last complete trajectory produced by this engine.
Return type:: Trajectory

property deffnm: str | None#: The deffnm this engine uses. None before a call to any prepare method.

property dt: float#: Integration timestep in ps.

property frames_done: int#

Number of frames produced since last call to prepare().

NOTE: frames != steps / nstout See the steps_done docstring for more.

property gro_file: str#: The (path to the) gro file this engine uses/used to call grompp.

property mdconfig: MDP#: The configuration of this engine as a MDP object.

property mdp: MDP#: The configuration of this engine as a MDP object.

property ndx_file: str | None#: The (path to the) ndx file this engine uses/used to call grompp.

property nstout: int#: Smallest output frequency for current output_traj_type.

property simulation_part: int#: Return the current simulation_part number.

property steps_done: int#

Number of integration steps done since last call to prepare().

NOTE: steps != frames * nstout Some remarks on the relation between frames_done and steps_done: Usually (when passing nsteps to run()) frames_done will be equal to steps_done/nstout + 1 because the initial/final configuration will be written twice (since then the first/last step is always an output step) However as soon as we run for a specific walltime (without specifying nsteps) stuff gets complicated, then gromacs can potentially stop at every neighbor search step (where it also can/will write a checkpoint). If that step is not a trajectory output step, no output will be written to the traj and then the plus 1 rule for the double written initial/final configuration is off (since it will then be a ‘normal’ configuration written just once). If however the neighbor search and trajectory output fall together on the same step the configuration will be written twice (as with nsteps specified).

property time_done: float#

Integration time since last call to prepare in ps.

Takes into account ‘tinit’ from the .mdp file if set.

property top_file: str#: The (path to the) top file this engine uses/used to call grompp.

property tpr_file: str | None#

The (path to the) tpr file this engine uses to call gmx mdrun.

None before a call to any prepare method.

property workdir: str#: The current working directory of the engine.

Submit MD via slurm#

class asyncmd.gromacs.SlurmGmxEngine(mdconfig: MDP, gro_file: str, top_file: str, *, ndx_file: str | None = None, sbatch_script: str, sbatch_options: dict[str, str] | None = None, **kwargs)#

Steer gromacs molecular dynamics simulation from python.

grompp_executable#

Name or path to the grompp executable, by default “gmx grompp”.

Type:: str

mdrun_executable#

Name or path to the mdrun executable, by default “gmx mdrun”.

Type:: str

grompp_extra_args#

Can be used to pass extra command line arguments to grompp calls, e.g. “-maxwarn 1”. Will simply be appended to the end of the command after a separating space.

Type:: str

mdrun_extra_args#

Can be used to pass extra command line arguments to mdrun calls, e.g. “-ntomp 8”. Will simply be appended to the end of the command after a separating space.

Type:: str

output_traj_type#

Type:: str

mdrun_time_conversion_factor#

Type:: float

Initialize a SlurmGmxEngine.

Parameters:

mdconfig (MDP) – The molecular dynamics parameters.
gro_file (str) – Absolute or relative path to a gromacs structure file.
top_file (str) – Absolute or relative path to a gromacs topology (.top) file.
sbatch_script (str) –
Absolute or relative path to a slurm sbatch script or a string with the content of the sbatch script. Note that the submission script must contain the following placeholders (see also the examples folder):
- {mdrun_cmd} : Replaced by the command to run mdrun
ndx_file (str or None) – Optional, absolute or relative path to a gromacs index file.
sbatch_options (dict or None) – Dictionary of sbatch options, keys are long names for options, values are the corresponding values. The keys/long names are given without the dashes, e.g. to specify --mem=1024 the dictionary needs to be {"mem": "1024"}. To specify options without values use keys with empty strings as values, e.g. to specify --contiguous the dictionary needs to be {"contiguous": ""}. See the SLURM documentation for a full list of sbatch options (https://slurm.schedmd.com/sbatch.html). Note: This argument is passed as is to the SlurmProcess in which the computation is performed. Each call to the engines run method triggers the creation of a new asyncmd.slurm.SlurmProcess and will use the then current sbatch_options.
keyword (Note that all attributes can be set at initialization by passing)
name (arguments with their)
instruct (e.g. mdrun_extra_args="-ntomp 2" to)
threads. (gromacs to use 2 openMP)

async apply_constraints(conf_in: Trajectory, conf_out_name: str, *, workdir: str = '.') → Trajectory#

Apply constraints to given configuration.

Parameters:

conf_in (Trajectory) – A (one-frame) trajectory, only the first frame will be used.
conf_out_name (str) – Output path for the constrained configuration.
workdir (str) – Working directory for the constraint engine, by default “.”, a subfolder with random name will be created.

Returns:

The constrained configuration.

Return type:

Trajectory

async generate_velocities(conf_in: Trajectory, conf_out_name: str, *, workdir: str = '.') → Trajectory#

Generate random Maxwell-Boltzmann velocities for given configuration.

This also applies constraints to the configuration (as gromacs does when generating velocities).

Parameters:

conf_in (Trajectory) – A (one-frame) trajectory, only the first frame will be used.
conf_out_name (str) – Output path for the velocity randomized configuration.
workdir (str) – Working directory for the constraint engine, by default “.”, a subfolder with random name will be created.

Returns:

The configuration with random velocities and constraints enforced.

Return type:

Trajectory

async prepare(starting_configuration: Trajectory | None | str, workdir: str, deffnm: str) → None#

Prepare a fresh simulation (starting with part0001).

Parameters:

starting_configuration (Trajectory or None or str) – A (trr) trajectory of which we take the first frame as starting configuration (including velocities) or None, then the initial configuration is the gro-file. Can also be a str, then it is assumed to be the path to a trr, cpt, or tng (i.e. a full precision trajectory) and will be passed directly to grompp.
workdir (str) – Absolute or relative path to an existing directory to use as working directory.
deffnm (str) – The name (prefix) to use for all files.

async prepare_from_files(workdir: str, deffnm: str) → None#

Prepare continuation run starting from the last part found in workdir.

Expects the checkpoint file and last trajectory part to exist, will (probably) fail otherwise.

Parameters:

workdir (str) – Absolute or relative path to an existing directory to use as working directory.
deffnm (str) – The name (prefix) to use for all files.

async run(nsteps: int | None = None, walltime: float | None = None, steps_per_part: bool = False) → Trajectory | None#

Run simulation for specified number of steps or/and a given walltime.

Note that you can pass both nsteps and walltime and the simulation will stop on the condition that is reached first.

Return None if no integration is needed because nsteps integration steps have already been performed.

Parameters:

nsteps (int or None) – Integration steps to run for either in total [as measured since the last call to self.prepare()] or in the newly generated trajectory part, see also the steps_per_part argument.
walltime (float or None) – (Maximum) walltime in hours, None means unlimited.
steps_per_part (bool) – If True nsteps are the steps to do in the new trajectory part, else the total number of steps since the last call to prepare() are counted, default False.

async run_steps(nsteps: int, steps_per_part: bool = False) → Trajectory | None#

Run simulation for specified number of steps.

Return None if no integration is needed because nsteps integration steps have already been performed.

Parameters:

nsteps (int or None) – Integration steps to run for either in total [as measured since the last call to self.prepare()] or in the newly generated trajectory part, see also the steps_per_part argument.
steps_per_part (bool) – If True nsteps are the steps to do in the new trajectory part, else the total number of steps since the last call to prepare() are counted, default False.

async run_walltime(walltime: float, max_steps: int | None = None) → Trajectory | None#

Run simulation for a given walltime.

Return None if no integration is needed because max_steps integration steps have already been performed.

Parameters:

walltime (float or None) – (Maximum) walltime in hours.
max_steps (int | None, optional) – If not None, terminate when max_steps integration steps are reached in total, also if this is before walltime is reached. By default None.

property current_trajectory: Trajectory | None#

Return the last finished trajectory (part).

Returns:: Last complete trajectory produced by this engine.
Return type:: Trajectory

property deffnm: str | None#: The deffnm this engine uses. None before a call to any prepare method.

property dt: float#: Integration timestep in ps.

property frames_done: int#

Number of frames produced since last call to prepare().

NOTE: frames != steps / nstout See the steps_done docstring for more.

property gro_file: str#: The (path to the) gro file this engine uses/used to call grompp.

property mdconfig: MDP#: The configuration of this engine as a MDP object.

property mdp: MDP#: The configuration of this engine as a MDP object.

property ndx_file: str | None#: The (path to the) ndx file this engine uses/used to call grompp.

property nstout: int#: Smallest output frequency for current output_traj_type.

property simulation_part: int#: Return the current simulation_part number.

property steps_done: int#

Number of integration steps done since last call to prepare().

property time_done: float#

Integration time since last call to prepare in ps.

Takes into account ‘tinit’ from the .mdp file if set.

property top_file: str#: The (path to the) top file this engine uses/used to call grompp.

property tpr_file: str | None#

The (path to the) tpr file this engine uses to call gmx mdrun.

None before a call to any prepare method.

property workdir: str#: The current working directory of the engine.

Gromacs engines

Contents

Gromacs engines#

MD parameter (mdp) file manipulation#

Run MD locally#

Submit MD via slurm#

MD parameter (`mdp`) file manipulation#