Gromacs parsing

Parsers for extracting alchemical data from Gromacs output files.

The parsers featured in this module are constructed to properly parse XVG files containing Hamiltonian differences (for obtaining reduced potentials, \(u_{nk}\)) and/or Hamiltonian derivatives (for obtaining gradients, \(\frac{dH}{d\lambda}\)). To produce such a file from an existing EDR energy file, use gmx energy -f <.edr> -odh dhdl.xvg with your installation of Gromacs.

If you wish to use FEP-based estimators such as MBAR that require reduced potentials for all lambda states in the alchemical leg, you will need to use these MDP options:

calc-lambda-neighbors = -1     ; calculate Delta H values for all other lambda windows
dhdl-print-energy = potential  ; total potential energy of system included

In addition, the full set of lambda states for the alchemical leg should be explicitly specified in the fep-lambdas option (or coul-lambdas, vdw-lambdas, etc.), since this is what Gromacs uses to determine what lambda values to calculate \(\Delta H\) values for.

To use TI-based estimators that require gradients, you will need to include these options:

dhdl-derivatives = yes         ; write derivatives of Hamiltonian with respect to lambda

Additionally, the parsers can properly parse XVG files (containing Hamiltonian differences and/or Hamiltonian derivatives) produced during expanded ensemble simulations. To produce such a file during the simulation, use gmx mdrun -deffnm <name> -dhdl dhdl.xvg with your installation of Gromacs. To run an expanded ensemble simulation you will need to use the following MDP option:

free_energy = expanded        ; turns on expanded ensemble simulation, lambda state becomes a dynamic variable

API Reference

This submodule includes these parsing functions:

alchemlyb.parsing.gmx.extract_dHdl(xvg, T, filter=True)

Return gradients dH/dl from a Hamiltonian differences XVG file.

Parameters:

  • xvg (str) – Path to XVG file to extract data from.

  • T (float) – Temperature in Kelvin the simulations sampled.

  • filter (bool) – Filter out the lines that cannot be parsed. Such as rows with incorrect number of Columns and incorrectly formatted numbers (e.g. 123.45.67, nan or -).

Returns:

dH/dl – dH/dl as a function of time for this lambda window.

Return type:

Series

Note

Previous versions of alchemlyb (<0.5.0) used the GROMACS value of the molar gas constant of \(R = 8.3144621 \times 10^{−3}\, \text{kJ}\cdot\text{mol}^{-1}\cdot\text{K}^{-1}\) instead of the scipy value scipy.constants.R in scipy.constants (see alchemlyb.postprocessors.units). The relative difference between the two values is \(6 \times 10^{-8}\).

Therefore, results in \(kT\) for GROMACS data will differ between alchemlyb ≥0.5.0 and previous versions; the relative difference is on the order of \(10^{-7}\) for typical cases.

Changed in version 0.5.0: The scipy.constants is used for parsers instead of the constants used by the corresponding MD engine. This leads to slightly different results for GROMACS input compared to previous versions of alchemlyb.

Changed in version 0.7.0: The keyword filter is implemented to ignore the line that cannot be parsed and is turned on by default.

alchemlyb.parsing.gmx.extract_u_nk(xvg, T, filter=True)

Return reduced potentials u_nk from a Hamiltonian differences XVG file.

Parameters:

  • xvg (str) – Path to XVG file to extract data from.

  • T (float) – Temperature in Kelvin the simulations sampled.

  • filter (bool) – Filter out the lines that cannot be parsed. Such as rows with incorrect number of Columns and incorrectly formatted numbers (e.g. 123.45.67, nan or -).

Returns:

u_nk – Potential energy for each alchemical state (k) for each frame (n).

Return type:

DataFrame

Note

Previous versions of alchemlyb (<0.5.0) used the GROMACS value of the molar gas constant of \(R = 8.3144621 \times 10^{−3}\, \text{kJ}\cdot\text{mol}^{-1}\cdot\text{K}^{-1}\) instead of the scipy value scipy.constants.R in scipy.constants (see alchemlyb.postprocessors.units). The relative difference between the two values is \(6 \times 10^{-8}\).

Therefore, results in \(kT\) for GROMACS data will differ between alchemlyb ≥0.5.0 and previous versions; the relative difference is on the order of \(10^{-7}\) for typical cases.

Changed in version 0.5.0: The scipy.constants is used for parsers instead of the constants used by the corresponding MD engine. This leads to slightly different results for GROMACS input compared to previous versions of alchemlyb.

Changed in version 0.7.0: The keyword filter is implemented to ignore the line that cannot be parsed and is turned on by default.

alchemlyb.parsing.gmx.extract(xvg, T, filter=True)

Return reduced potentials u_nk and gradients dH/dl from a Hamiltonian differences XVG file.

Parameters:

  • xvg (str) – Path to XVG file to extract data from.

  • T (float) – Temperature in Kelvin the simulations sampled.

  • filter (bool) – Filter out the lines that cannot be parsed. Such as rows with incorrect number of Columns and incorrectly formatted numbers (e.g. 123.45.67, nan or -).

Returns:

A dictionary with keys of ‘u_nk’, which is a pandas DataFrame of potential energy for each alchemical state (k) for each frame (n), and ‘dHdl’, which is a Series of dH/dl as a function of time for this lambda window.

Return type:

Dict

Added in version 1.0.0.