System Properties

Unified interface for extracting molecular and system-level properties from GROMACS input files.

class kbkit.systems.properties.SystemProperties(path: str | None = None, include: str = '', energy: str | None = None, topology: str | None = None, start: int = 0)[source]

Bases: object

Interface for accessing thermodynamic and structural properties of a GROMACS system.

Combines topology (.top), structure (.gro), and energy (.edr) files into a unified property accessor. Supports alias resolution, unit conversion, and ensemble-aware file discovery.

Parameters:

  • system_path (str or Path, optional) – Path to the system directory containing GROMACS files.

  • include (str, optional) – String to include in file name for valid file. Only used if multiple files are found with the same suffix.

  • energy (str or Path, optional) – Path for an energy file. Supported filetypes: “.edr”, “.log”, “.lammps”

  • topology (str or Path, optional) – Path for a topology file. Supported filetypes: “.top”, “.gro”, “.lmp”

  • 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).

Variables:

  • energy (list[Path]) – List of paths to energy files.

  • topology (list[Path]) – List of paths to topology files.

  • note:: (..) –

    • Defaults to looking at files/paths directly specified.

    • If files are not specified or do not exist, a system_path is required to locate the files with necessary suffix.

property energy: list[EnergyParser]

Setup Energy file parsers for all files in energy_files.

Type:

list[EnergyParser]

property topology: TopologyParser

Setup Topology parser.

Type:

TopologyParser

property topology_properties: list[str]

Get list of accessible topology properties.

Type:

list[str]

get(name: str, units: str | None = None, avg: bool = True, time_series: bool = False) → Any[source]

Master function for getting any property from energy or topology files.

Parameters:

  • name (str) – Name for the property to extract.

  • units (str, optional) – Units to convert energy properties to. If not specified, default units from pyedr will be used.

  • avg (bool, optional) – Returns averaged property if True (default: True). Otherwise returns array of values.

  • time_series (bool, optional) – Returns both times and values if True (default: False).

Returns:

Topology or energy property in desired units.

Return type:

float | np.ndarray | list[np.ndarray]

timeseries_plotter(start: int = 0) → TimeseriesPlotter[source]

Create a TimeseriesPlotter for visualizing time series data for a given system.

Parameters:

start (int) – Initial time for plotting.

Returns:

Plotter instance for computing simulation energy properties.

Return type:

TimeseriesPlotter