uesgraphs.analyze

UESGraphs Analysis Module

Enhanced analysis capabilities for district heating networks.

Main Functions: - assign_data_pipeline(): Full pipeline for simulation data assignment - process_simulation_result(): Process .mat/.parquet files - prepare_DataFrame(): Add datetime indexing and filtering

Quick Start: ```python from uesgraphs.analysis import assign_data_pipeline from datetime import datetime

# Assign simulation data to network graph_with_data = assign_data_pipeline(

graph=graph, simulation_data_path=”results.mat”, start_date=datetime(2024, 1, 1), end_date=datetime(2024, 1, 7), time_interval=”15min”, system_model_path=”system_model.json”

)

uesgraphs.analyze.assign_data_pipeline(graph: UESGraph, simulation_data_path: str | Path, start_date: datetime, end_date: datetime, time_interval: str, MASK: Dict[str, str] | None = None, aixlib_version: str = '2.1.0', system_model_path: str | Path | None = None, node_to_port_mapping: Dict | None = None, logger: Logger | None = None) → UESGraph[source]

Assign simulation data to a UESGraph network.

This function processes simulation results and assigns time series data to network components (nodes and edges). It supports two modes:

  1. Full assignment (with node data): Requires either node_to_port_mapping or system_model_path to map simulation variables to graph nodes

  2. Edge-only assignment: When no mapping is available, only assigns data to edges (mass flows, pressure drops)

Parameters:

  • graph – UESGraph instance to assign data to

  • simulation_data_path – Path to simulation results (.mat or .parquet)

  • start_date – Start date for data processing

  • end_date – End date for data processing

  • time_interval – Time interval for resampling (e.g., “15min”, “1H”) No default - user must specify explicitly

  • MASK – Custom variable name masks. If None, uses AixLib standard masks

  • aixlib_version – AixLib version for standard masks (default: “2.1.0”)

  • system_model_path – Path to system model JSON (for creating port mapping)

  • node_to_port_mapping – Pre-computed mapping from nodes to simulation ports

  • logger – Logger instance. If None, creates a new file logger

Returns:

UESGraph instance with assigned simulation data

Raises:

  • FileNotFoundError – If simulation_data_path doesn’t exist

  • ValueError – If graph has no name set or data validation fails

  • KeyError – If required simulation variables are missing

Notes

  • Either node_to_port_mapping OR system_model_path is required for full data assignment including nodes

  • If both are None, only edge data (mass flows) will be assigned

  • Graph must have a name set in graph.graph[“name”]

Example

>>> import uesgraphs as ug
>>> from datetime import datetime
>>>
>>> # Load your network
>>> graph = ug.UESGraph()
>>> graph.from_json("network.json", network_type="heating")
>>> graph.graph["name"] = "my_network"
>>>
>>> # Assign simulation data
>>> graph_with_data = assign_data_pipeline(
...     graph=graph,
...     simulation_data_path="results.mat",
...     start_date=datetime(2024, 1, 1),
...     end_date=datetime(2024, 1, 7),
...     time_interval="15min",
...     system_model_path="system_model.json"
... )
>>>
>>> # With custom masks
>>> custom_masks = {
...     "m_flow": "custom.pipe{pipe_code}.flow",
...     "p_a": "custom.pipe{pipe_code}.pressure_in",
...     "p_b": "custom.pipe{pipe_code}.pressure_out"
... }
>>> graph_with_data = assign_data_pipeline(
...     graph=graph,
...     simulation_data_path="results.mat",
...     start_date=datetime(2024, 1, 1),
...     end_date=datetime(2024, 1, 7),
...     time_interval="1H",
...     MASK=custom_masks
... )
uesgraphs.analyze.process_simulation_result(file_path: str, filter_list: List[str], chunk_size: int = 100000, logger=None) → Generator[DataFrame, None, None][source]

Process a parquet file in chunks to reduce memory usage.

Parameters:

  • file_path – Path to the parquet file

  • filter_list – List of column patterns to filter

  • chunk_size – Number of rows to process at once

  • logger – Optional logger instance

Yields:

pd.DataFrame – Processed chunks of the parquet file

uesgraphs.analyze.prepare_DataFrame(df, base_date=datetime.datetime(2024, 1, 1, 0, 0), time_interval='15min', start_date=None, end_date=None, logger=None) → DataFrame[source]

Prepare a DataFrame with a datetime index using customizable parameters.

Parameters:

dfpandas.DataFrame

The DataFrame to be processed

base_datedatetime, optional

The starting date for the index (default: 2024-01-01)

time_intervalstr, optional

Frequency of the time intervals (e.g., ‘15min’, ‘1h’, ‘30min’, default: ‘15min’)

start_datedatetime, optional

If provided, slice the DataFrame from this date (inclusive)

end_datedatetime, optional

If provided, slice the DataFrame until this date (inclusive)

loggerlogging.Logger, optional

Logger instance for logging operations

Returns:

DataFrame: A DataFrame containing the data from the parquet file for the specified time period.

uesgraphs.analyze.loadsim(fname, constants_only=False)[source]

Load Dymola® or OpenModelica simulation results.

Arguments:

  • fname: Name of the results file, including the path

    The file extension (‘.mat’) is optional.

  • constants_only: True to load only the variables from the first data matrix

    The first data matrix usually contains all of the constants, parameters, and variables that don’t vary. If only that information is needed, it may save resources to set constants_only to True.

Returns: An instance of dict

uesgraphs.analyze.mat_to_pandas(fname='dsres.mat', names=None, aliases=None, with_unit=True, constants_only=False)[source]

Return a pandas.DataFrame with values from selected variables for the given .mat file.

The index is time. The column headings indicate the variable names and units.

Parameters:

  • fname (str) – The mat file to load.

  • names (list) – If None (default), then all variables are included.

  • aliases (dict) –

    Dictionary of aliases for the variable names

    The keys are the “official” variable names from the Modelica model and the values are the names as they should be included in the column headings. Any variables not in this list will not be aliased. Any unmatched aliases will not be used.

  • with_unit (bool) –

    Boolean to determine format of keys. Default value is True.

    If set to True, the unit will be added to the key. As not all modelica- result files export the unit information, using with_unit=True can lead to errors.

  • constants_only (bool) – The first data matrix usually contains all of the constants, parameters, and variables that don’t vary. If only that information is needed, it may save resources to set constants_only to True.

uesgraphs.analyze.mat_to_parquet(save_as, fname='dsres.mat', names=None, aliases=None, with_unit=True, constants_only=False)[source]
uesgraphs.analyze.map_system_model_to_uesgraph(graph_sysm, uesgraph)[source]

Maps each node in the UES graph to its corresponding ports in the system model graph.

This function handles the transformation between two different graph representations: 1. UES graph: Models the physical network where pipes are edges and junctions are nodes 2. System model graph: Models the simulation components where pipes are nodes and

connections between pipes are edges

Parameters:
Returns:

Mapping from UES graph node IDs to lists of corresponding system model ports

Return type:

dict

Raises:

ValueError – If a non-building node has only one pipe connection (open end)

uesgraphs.analyze.set_up_terminal_logger(name: str, level: int = 20) → Logger[source]

Set up a simple console-only logger for small functions.

Parameters:

  • name – Logger name

  • level – Logging level (default: INFO)

Returns:

Configured console logger

uesgraphs.analyze.set_up_file_logger(name: str, log_dir: str | None = None, level: int = 40) → Logger[source]

Set up a full file+console logger for major functions.

Parameters:

  • name – Logger name

  • log_dir – Directory for log files (default: temp directory)

  • level – Logging level (default: ERROR)

Returns:

Configured file+console logger