Energy Parser

Parser for GROMACS (.edr) and LAMMPS (.log, .lammps) energy files.

class kbkit.io.energy.EnergyFormat(*values)

Bases: Enum

Formatting for various energy types.

LAMMPS = 1

GROMACS = 2

class kbkit.io.energy.EnergyParser(path: str | Path)

Bases: object

Interface for extracting energy properties from GROMACS .edr and LAMMPS .log/.lammps files.

Wraps MDAnalysis to provide access to available properties in .edr file. Extracts data from .lammps via lammps_logfile and .log via pandas. Supports additional properties, configurational_enthalpy and fluctuation properties (heat capacity and isothermal compressibility). Note that the fluctuation properties return a float object rather than a timeseries.

LAMMPS_to_GMX: ClassVar = {'Density': 'density', 'KinEng': 'kinetic en.', 'PotEng': 'potential', 'Press': 'pressure', 'Step': 'step', 'Temp': 'temperature', 'TotEng': 'total energy', 'Volume': 'volume'}

GROMACS_UNITS: ClassVar = {'density': 'kg/m^3', 'enthalpy': 'kJ/mol', 'kinetic en.': 'kJ/mol', 'potential': 'kJ/mol', 'pressure': 'bar', 'step': '', 'temperature': 'K', 'time': 'ps', 'total energy': 'kJ/mol', 'volume': 'nm^3'}

LAMMPS_UNITS: ClassVar = {'density': 'g/cm^3', 'enthalpy': 'kcal/mol', 'potential': 'kcal/mol', 'pressure': 'atm', 'step': '', 'temperature': 'K', 'time': 'ps', 'total energy': 'kcal/mol', 'volume': 'angstrom^3'}

DEFAULT_UNITS: ClassVar = {'cp': 'kJ/mol/K', 'cv': 'kJ/mol/K', 'density': 'kg/m^3', 'enthalpy': 'kJ/mol', 'isothermal-compressibility': '1/kPa', 'kinetic en.': 'kJ/mol', 'molar-volume': 'cm^3/mol', 'number-density': 'molecule/nm^3', 'potential': 'kJ/mol', 'pressure': 'kPa', 'step': '', 'temperature': 'K', 'time': 'ps', 'total energy': 'kJ/mol', 'volume': 'nm^3'}

FLUCT_PROPS: ClassVar = ('cp', 'cv', 'isothermal-compressibility')

property units: dict[str, str]

Returns a dictionary mapping properties to their units.

property data: dict[str, ndarray]

Extract energy data.

available_properties() → list[str]

Return a list of available energy properties in the .edr file(s).

Returns:

Sorted list of property names in .edr files.

Return type:

list[str]

get(name: str, start: int = 0, units: str | None = None) → ndarray

Extract time series data for a given property.

Parameters:

• name (str) – Property name to extract (e.g., “potential”, “temperature”).

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Returns property in desired units. If empty, used default values (See units()).

Returns:

• np.ndarray – Array of values.

• .. note:: – Filters data based on start_time for reproducibility.

molar_volume(nmol: int, volume: float = 0, start: int = 0, units: str | None = None) → ndarray | float

Calculate molar volume of a simulation.

If ensemble is NVT, i.e., volume is not accessible in .edr file, an input volume is required (i.e., read from bottom of .gro file in SystemProperties).

Parameters:

• nmol (int) – Number of total molecules in system.

• volume (float, optional) – Simulation box volume.

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. Defaults to pyedr units (kJ/mol).

Returns:

Molar volume of molecular simulation.

Return type:

np.ndarray

configurational_enthalpy(volume: float | None = None, start: int = 0, units: str | None = None) → ndarray

Calculate configurational enthalpy from potential energy. Not normalized to molecule number in simulation.

If ensemble is NVT, i.e., volume is not accessible in .edr file, an input volume is required (i.e., read from bottom of .gro file in SystemProperties).

Parameters:

• volume (float, optional) – Simulation box volume (units: nm:math:^3).

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. (default: kJ/mol).

Returns:

Enthalpy of molecular simulation.

Return type:

np.ndarray

Notes

Enthalpy, \(H\), is calculated from potential energy (\(U\)) according to:

\[H = U + pV\]

where:

• \(p\) is pressure

• \(V\) is volume

molar_enthalpy(nmol: int, volume: float = 0, start: int = 0, units: str | None = None) → ndarray

Calculate molar enthalpy. Configurational enthalpy is normalized to the total molecule number in simulation.

Parameters:

• nmol (int) – Number of total molecules in system.

• volume (float, optional) – Simulation box volume (units: nm:math:^3).

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. (default: kJ/mol).

Returns:

Configurational enthalpy normalized by the total number of molecules.

Return type:

np.ndarray

See also

configurational_enthalpy()

heat_capacity_cp(nmol: int, volume: float | None = None, start: int = 0, units: str | None = None) → float

Calculate molar constant pressure heat capacity from configurational_enthalpy(). Heat capacity is normalized to the total number of molecules in simulation.

Parameters:

• nmol (int) – Number of total molecules in system.

• volume (float, optional) – Simulation box volume (units: nm:math:^3).

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. (default: kJ/mol).

Returns:

Constant pressure heat capacity.

Return type:

float

Notes

Constant pressure heat capacity, \(c_p\) is calculated according to:

\[\begin{split}\begin{aligned} c_p &= \frac{\langle H^2 \rangle - \langle H \rangle ^2}{k_B T^2} \\ &= \frac{\sigma_H^2}{k_B T^2} \end{aligned}\end{split}\]

where:

• \(\langle H^2 \rangle - \langle H \rangle ^2\) is the variance of the enthalpy (also writted as \(\sigma_H^2\))

• \(k_B\) is Boltzmann constant

• \(T\) is absolute temperature

heat_capacity_cv(nmol: int, start: int = 0, units: str | None = None) → float

Calculate molar constant volume heat capacity. Heat capacity is normalized to the total number of molecules in simulation.

Parameters:

• nmol (int) – Number of total molecules in system.

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. Defaults to pyedr units (kJ/mol).

Returns:

Constant volume heat capacity.

Return type:

float

Notes

Constant volume heat capacity, \(c_v\) is calculated according to:

\[\begin{split}\begin{aligned} c_v &= \frac{\langle U^2 \rangle - \langle U \rangle ^2}{k_B T^2} \\ &= \frac{\sigma_U^2}{k_B T^2} \end{aligned}\end{split}\]

where:

• \(\langle U^2 \rangle - \langle U \rangle ^2\) is the variance of the potential (also writted as \(\sigma_U^2\))

• \(k_B\) is Boltzmann constant

• \(T\) is absolute temperature

isothermal_compressibility(start: int = 0, units: str | None = None) → float

Isothermal compressibility.

Parameters:

• start (int, optional) – Starting point for when data should be used. GROMACS: time (ps), LAMMPS: timestep (i.e., for 1 fs steps, start=1000–start at 1 ps).

• units (str, optional) – Desired output units. Defaults to pyedr units (kJ/mol).

Returns:

Isothermal compressibility.

Return type:

float