System Properties

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

class kbkit.systems.properties.SystemProperties(system_path: str | None = None, include: str = '', edr_path: str | None = None, top_path: str | None = None, gro_path: str | None = None, start_time: float = 0.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.

  • edr_path (str or Path, optional) – Path for an energy (.edr) file.

  • top_path (str or Path, optional) – Path for a topology (.top) file.

  • gro_path (str or Path, optional) – Path for a structure (.gro) file.

  • start_time (int, optional) – Default start time (in ps) for time-averaged properties.

Variables:

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

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

  • gro_paths (list[Path]) – List of paths to GROMACS structure 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.

static find_files(suffix: str, filepath: str | Path | None = None, system_path: str | Path | None = None, include: str = '', exclude: list[str] | None = None) → list[Path][source]

Get list of files with a given suffix in system directory.

Parameters:

  • suffix (str) – File type to search for. (i.e., .edr, .gro, .top)

  • filepath (str, optional) – Optional filepath to validate. Optional if system_path is included.

  • system_path (str, optional) – Parent path containing files. Optional if filepath is included.

  • include (str, optional) – String to filter files by. Will only incorporate if more than one file of the desired suffix is found.

  • exclude (list[str], optional) – String to exclude from valid files. Will only be searched if more than 1 files found after include filter.

Returns:

List of path objects containing files of desired suffix.

Return type:

list[Path]

property energy: list[EdrParser]

Setup EDR file parsers for all files in edr_paths.

Type:

list[EdrParser]

property topology: GroParser | TopParser

Setup Gro/Top parser.

Type:

GroParser | TopParser

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_time: int = 0) → TimeseriesPlotter[source]

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

Parameters:

start_time (int) – Initial time for plotting.

Returns:

Plotter instance for computing simulation energy properties.

Return type:

TimeseriesPlotter