mstk.wrapper.GMX

class mstk.wrapper.GMX(gmx_bin, gmx_mdrun=None, version=None)

Wrapper for GROAMCS for pre-processing, running and post-processing MD simulations.

GROMACS version 2016 is recommended and has been tested thoroughly. Though this wrapper support both version 2016, 2018 and 2019.

It’s better to compile GROMACS in two binaries. One is the normal gmx binary without any acceleration. This is used for pre- and post-processing, which normally run on the front node of a HPC. The other one is the mdrun binary with full accelerations through MPI, OpenMP, GPU, etc… This will be submitted to Scheduler to run on the compute node of a HPC. Refer to GROMACS documentation for the compiling options.

If gmx_bin and gmx_mdrun are provided separately (recommended), you should make sure that they have the same version.

Parameters:

  • gmx_bin (str) – Path of the serial version gmx binary executable.

  • gmx_mdrun (str, optional) – Path of the parallel/gpu version mdrun binary executable. If not provided, gmx_bin will be used also for mdrun.

  • version (str, optional) – The version of GROMACS, e.g. 2016.6, 2019.6. If not specified, then gmx_bin will be called to check the version. In this case, make sure gmx_bin is available on this machine.

version
Type:

str

majorversion
Type:

str

Methods

__init__(gmx_bin[, gmx_mdrun, version])

density(trj, tpr[, xvg, group, begin, end, ...])

Execute gmx density to calculate the density profile in z direction on a trajectory.

diffusion(xtc, tpr[, group, mol, begin, ...])

Calculate the diffusion coefficient from a trajectory file by calling gmx msd.

energy(edr, properties[, begin, end, ...])

Execute gmx energy program on a edr file.

extend_tpr(tpr, extend[, silent])

Modify the nsteps record in a tpr file by calling gmx convert-tpr for extending simulation.

generate_gpu_multidir_cmds(dirs, commands, ...)

Generate commands for performing multidir simulation with GROMACS.

generate_top(itp, molecules, numbers)

Generate a topol file that includes a existent itp file.

generate_top_for_hvap(top, top_out)

Generate a new topol file for calculating the heat of vaporization from existent topol file for bulk simulation.

get_box(edr[, begin])

Extract the average box size from a edr file by calling gmx energy program.

get_fluct_props(edr[, begin, end])

Get thermal expansion and compressibility from a edr file using fluctuation of enthalpy, volume.

get_properties_stderr(edr, properties[, ...])

Extract properties from a edr file by calling gmx energy program.

get_property_stderr(edr, prop[, begin, end])

Extract the average value and standard error of a property from a edr file by calling gmx energy program.

get_top_mol_numbers(top)

Get the name and number of molecules in a topol file from the [ molecules ] section.

grompp([mdp, gro, top, tpr_out, cpt, ...])

Run gmx grompp directly or generate the command for gmx grompp.

mdrun([name, nprocs, n_omp, rerun, extend, ...])

Run mdrun directly or generate the command for mdrun.

modify_lj96(itp_files, top_files, mdp_files, ...)

Convert the current simulation files for LJ-12-6 vdW form into LJ-9-6 form.

modify_top_mol_numbers(top, numbers)

Modify the number of molecules in a topol file at the [ molecules ] section.

pdb2gro(pdb, gro_out, box[, silent])

Convert a PDB file to GRO file by calling gmx editconf.

prepare_mdp_from_template(template[, ...])

Generate MDP control script from template library for running GROMACS simulation.

replicate_gro(gro, top, nbox[, silent])

Enlarge a GRO box by replicate it with gmx genconf.

scale_box(gro, gro_out, new_box)

Scale GRO box to desired size.

select_com(tpr[, resname, ndx_out])

Create an index file of the centers of mass of each molecule by calling gmx select.

traj_com(xtc, tpr[, trj_out, begin, end, silent])

Generate a trajectory of the centers of mass of molecules in a trajectory.

velacc(trr[, tpr, group, begin, xvg_out, silent])

Calculte the velocity auto correlation of atoms in a trajectory by calling gmx velacc.
grompp(mdp='grompp.mdp', gro='conf.gro', top='topol.top', tpr_out='md.tpr', cpt=None, maxwarn=3, silent=False, get_cmd=False)

Run gmx grompp directly or generate the command for gmx grompp.

Refer to GROMACS documentation for details.

Parameters:

  • mdp (str) –

  • gro (str) –

  • top (str) –

  • tpr_out (str) –

  • cpt (str) –

  • maxwarn (int) –

  • silent (bool) – If set to True and get_cmd set to False, then gmx grompp will be executed silently, without output on screen.

  • get_cmd (bool) – If set to True, the command for running gmx grompp will be returned, which can be feed into Scheduler. If set to False, gmx grompp will be executed.

Returns:

command – If get_cmd set to True, will return the command for running gmx grompp. If get_cmd set to False, will return None.

Return type:

str or None

mdrun(name='md', nprocs=1, n_omp=None, rerun=None, extend=False, silent=False, get_cmd=False)

Run mdrun directly or generate the command for mdrun.

mdrun will use both MPI and OpenMP for hybrid parallelization.

Refer to GROMACS documentation for details.

Parameters:

  • name (str) – Argument for mdrun -deffnm

  • nprocs (int) – Number of CPU cores to use

  • n_omp (int, optional) – Number of OpenMP threads to use. If not set, will be determined automatically from nprocs.

  • rerun (str, optional) – If an XTC or TRR file privided, will perform mdrun -rerun on the trajectory.

  • extend (bool) – If set to True, will perform mdrun -cpi on the checkpoint. A checkpoint named name.cpt should be avaiable in the current directory.

  • silent (bool) – If set to True and get_cmd set to False, then mdrun will be executed silently, without output on screen.

  • get_cmd (bool) – If set to True, the command for running mdrun will be returned, which can be feed into Scheduler. If set to False, mdrun will be executed.

Returns:

command – If get_cmd set to True, will return the command for running mdrun. If get_cmd set to False, will return None.

Return type:

str or None

prepare_mdp_from_template(template, mdp_out='grompp.mdp', T=298, P=1, nsteps=10000, dt=0.001, TANNEAL=800, nstenergy=100, nstxout=0, nstvout=0, nstxtcout=10000, xtcgrps='System', restart=False, tcoupl='langevin', pcoupl='parrinello-rahman', constraints='h-bonds', ppm=0, dielectric=None)

Generate MDP control script from template library for running GROMACS simulation.

Refer to GROMACS documentation for the meaning of parameteres.

The coupling time constant are determined automatically from dt, tcoupl and pcoupl. The neighbour list update frequency is determined automatically from dt.

Parameters:

  • template (str) – File name of the template to use. Take a look of the template directory to get available choices.

  • mdp_out (str) –

  • T (float) –

  • P (float) –

  • nsteps (int) –

  • dt (float) –

  • TANNEAL (float, optional) – The temperature for annealing. This argument should be used together with template t_nvt_anneal.mdp It is ignored for other templates.

  • nstenergy (int) –

  • nstxout (int) –

  • nstvout (int) –

  • nstxtcout (int) –

  • xtcgrps (int) –

  • restart (bool) – If set to True, grompp will not generated velocity.

  • tcoupl (['langevin', 'v-rescale', 'nose-hoover']) –

  • pcoupl (['parrinello-rahman', 'berendsen']) –

  • constraints (['h-bonds', 'none', 'all-bonds']) –

  • ppm (float, optional) – The cosine acceleration strength for periodic perturbation simulation. This argument should be used together with template t_npt_ppm.mdp It is ignored for other templates.

  • dielectric (float, optional) –

energy(edr, properties, begin=0, end=None, fluct_props=False, get_cmd=False)

Execute gmx energy program on a edr file.

Refer to the GROMACS documentation for details.

Parameters:

  • edr (str) –

  • properties (list of str) – The properties to be extracted. It corresponds to the input when calling gmx_energy manually. But instead of input one by one joined by Enter, the properties are provided in a list here.

  • begin (float) –

  • end (float, optional) –

  • fluct_props (bool) –

  • get_cmd (bool) –

Returns:

out – If set to True, the command for running gmx energy will be returned. If set to False, gmx energy will be executed silently and the output will be returned directly without cleanup.

Return type:

str

get_fluct_props(edr, begin=0, end=None)

Get thermal expansion and compressibility from a edr file using fluctuation of enthalpy, volume.

Parameters:

  • edr (str) –

  • begin (float) –

  • end (float, optional) –

Returns:

  • expansion (float)

  • compressibility (float)

get_properties_stderr(edr, properties, begin=0, end=None)

Extract properties from a edr file by calling gmx energy program. The difference between this method and energy() is that, energy() will return the raw output string without any cleanup, while this method will extract the values and standard errors from the output and return only the results.

Parameters:

  • edr (str) –

  • properties (list of str) –

  • begin (float) –

  • end (float, optional) –

Returns:

results – Each element of this list is a tuple of two floats, which are average value and standard error of each property.

Return type:

list of tuple of float

get_property_stderr(edr, prop, begin=0, end=None)

Extract the average value and standard error of a property from a edr file by calling gmx energy program.

Parameters:

  • edr (str) –

  • prop (str) –

  • begin (float) –

  • end (float, optional) –

Returns:

  • average (float)

  • stderr (float)

get_box(edr, begin=0)

Extract the average box size from a edr file by calling gmx energy program.

Only rectangular box is supported.

Parameters:

  • edr (str) –

  • begin (float) –

Returns:

  • lx (float)

  • ly (float)

  • lz (float)

density(trj, tpr, xvg='density.xvg', group='System', begin=0, end=None, center=False, silent=False, get_cmd=False)

Execute gmx density to calculate the density profile in z direction on a trajectory.

Refer to GROMACS documentation for details.

Parameters:

  • trj (str) –

  • tpr (str) –

  • xvg (str) –

  • group (str) –

  • begin (float) –

  • end (float, optional) –

  • center (bool) –

  • silent (bool) – If set to True and get_cmd set to False, then gmx density will be executed silently, without output on screen.

  • get_cmd (bool) – If set to True, the command for running gmx density will be returned, which can be feed into Scheduler. If set to False, gmx density will be executed.

Returns:

command – If get_cmd set to True, will return the command for running gmx_density. If get_cmd set to False, will return None.

Return type:

str or None

static scale_box(gro, gro_out, new_box)

Scale GRO box to desired size.

The coordinate of all atoms are scaled, while the velocities are not modified. Only rectangular box is supported.

Parameters:

  • gro (str) –

  • gro_out (str) –

  • new_box (list of float) – The lengths of the desired rectangular box.

static generate_top(itp, molecules, numbers)

Generate a topol file that includes a existent itp file.

Parameters:

  • itp (str) –

  • molecules (list of str) – Name of molecules in the system

  • numbers (list of int) – Number of these molecules in the system

static get_top_mol_numbers(top)

Get the name and number of molecules in a topol file from the [ molecules ] section.

Parameters:

top (str) –

Returns:

mol_numbers – Each element is a tuple containing a str and a int, which are the name and number of each molecule specie.

Return type:

list of tuple

static modify_top_mol_numbers(top, numbers)

Modify the number of molecules in a topol file at the [ molecules ] section.

The length of numbers must be equal to the original length of numbers in the topol file. Otherwise, an Exception will be raised.

Parameters:

  • top (str) –

  • numbers (list of int) –

replicate_gro(gro, top, nbox, silent=True)

Enlarge a GRO box by replicate it with gmx genconf.

The numbers of molecules in the topol file will be updated accordingly.

Parameters:

  • gro (str) –

  • top (str) –

  • nbox (list of int) – Three element denotes the number of replicates in x, y and z directions.

  • silent (bool) –

pdb2gro(pdb, gro_out, box, silent=False)

Convert a PDB file to GRO file by calling gmx editconf.

Parameters:

  • pdb (str) –

  • gro_out (str) –

  • box (list of float) – The size of rectangular box.

  • silent (bool) –

velacc(trr, tpr=None, group=None, begin=0, xvg_out='velacc', silent=False)

Calculte the velocity auto correlation of atoms in a trajectory by calling gmx velacc.

Refer to GROMACS documentation for details.

Parameters:

  • trr (str) –

  • tpr (str) –

  • group (str) –

  • begin (float) –

  • xvg_out (str) –

  • silent (bool) –

diffusion(xtc, tpr, group='System', mol=False, begin=0, end=None, xvg_out='msd.xvg', beginfit=-1, endfit=-1)

Calculate the diffusion coefficient from a trajectory file by calling gmx msd.

Refer to GROMACS documentation for details.

Parameters:

  • xtc (str) –

  • tpr (str) –

  • group (str) –

  • mol (bool) –

  • begin (float) –

  • end (float, optional) –

  • xvg_out (str) –

  • beginfit (float, optional) –

  • endfit (str, optional) –

Returns:

  • diffusion (float) – Diffusion coefficient in unit of cm^2/s.

  • stderr (float) – Standard error.

traj_com(xtc, tpr, trj_out='com.xtc', begin=0, end=0, silent=False)

Generate a trajectory of the centers of mass of molecules in a trajectory.

It calls select_com() to create a index file of the centers of mass of all molecules. Then gmx traj is called to calculate the positions of each center of mass and output the trajectory.

Refer to the GROMACS documentation for details.

Parameters:

  • xtc (str) –

  • tpr (str) –

  • trj_out (str) –

  • begin (float) –

  • end (float) –

  • silent (bool) –

select_com(tpr, resname='all', ndx_out='com.ndx')

Create an index file of the centers of mass of each molecule by calling gmx select.

Refer to GROAMCS documentation for details.

Parameters:

  • tpr (str) –

  • resname (str) –

  • ndx_out (str) –

static generate_top_for_hvap(top, top_out)

Generate a new topol file for calculating the heat of vaporization from existent topol file for bulk simulation.

Essentially, this will add a [ exclusion ] section in the topol file for each molecule. All intra-molecular interactions will be excluded. With this modified topol file, gmx mdrun -rerun on the bulk trajectory will calculate only the inter-molecular energies, which is approximately the cohesive energy.

Parameters:

  • top (str) –

  • top_out (str) –

extend_tpr(tpr, extend, silent=False)

Modify the nsteps record in a tpr file by calling gmx convert-tpr for extending simulation.

Refer to GROMACS documentation for details.

Parameters:

  • tpr (str) –

  • extend (float) –

  • silent (bool) –

generate_gpu_multidir_cmds(dirs, commands, n_parallel, n_gpu=0, n_omp=None, n_procs=None)

Generate commands for performing multidir simulation with GROMACS.

multidir simulation enables several similar simulations being run at the same time in different directories. This is a powerful feature allowing for much better utilization of GPU resources.

Parameters:

  • dirs (list of str) –

  • commands (list of str) –

  • n_parallel (int) –

  • n_gpu (int, optional) –

  • n_omp (int, optional) – Set n_omp in most case. When n_procs is set, n_omp will have no effect.

  • n_procs (int, optional) –

Returns:

commands_list

Return type:

list of list of str

static modify_lj96(itp_files, top_files, mdp_files, xvg_files)

Convert the current simulation files for LJ-12-6 vdW form into LJ-9-6 form.

This is a trick to simplify the exporting of LJ-9-6 vdW form in GROMACS.

Parameters:

  • itp_files (None or list of str) – The itp files to be modified. If not set, all the itp files in the current directory will be modified.

  • top_files (None or list of str) – The top files to be modified. If not set, all the top files in the current directory will be modified.

  • mdp_files (None or list of str) – The mdp files to be modified. If not set, all the mdp files in the current directory will be modified.

  • xvg_files (list of str) – The xvg files to be generated. They contain the tabulated LJ-9-6 potential and force.