uesgraphs.systemmodels.utilities

This module collects utilities and convenience functions for model generation

Functions

build_flow_paths(graph, supply_nodes, ...)	Build flow paths from each supply node to reachable demand nodes.
create_model(name, save_at, graph, ...[, ...])	Generic model generation for setup defined through the parameters
estimate_fac(graph[, u_form_distance, ...])	Calculate fac for all pipes based on m_flow_nominal
estimate_m_flow_demand_based(graph[, ...])	Estimates mass flow for each edge by calculating flows at demand nodes and propagating backwards.
estimate_m_flow_nominal(graph, dT_design, ...)	DEPRECATED: Use estimate_m_flow_demand_based instead.
estimate_m_flow_nominal_tablebased(graph, ...)	Calculate m_flow_nominal based on the pipe diameter.
get_inner_diameter_from_DN(dn_value[, ...])	Quick lookup for inner diameter based on DN value only.
get_pipe_catalog_DN_m_flow(graph, ...[, robust])	Assign pipe diameters to edges based on mass flow and catalog data.
load_pipe_catalog([catalog_name, custom_path])	Load pipe catalog data from CSV file in the data/pipe_catalogs directory.
load_system_model_from_json(filepath)	Load a SystemModelHeating object from a JSON file, respecting the constructor's signature.
prepare_graph(graph, T_supply, p_supply, ...)	Adds data for model generation to the uesgraph
save_system_model_to_json(model, filepath)	Save a SystemModelHeating object to a JSON file with comprehensive attribute capturing.
set_up_logger(name[, log_dir, level])	Set up a file-based logger with timestamp and detailed formatting.
size_hydronic_network(graph[, m_flow_key, ...])

uesgraphs.systemmodels.utilities.set_up_logger(name, log_dir=None, level=20)

Set up a file-based logger with timestamp and detailed formatting.

Parameters:

• name (str) – Logger name, used for log file naming

• log_dir (str, optional) – Directory for log files. If None, uses system temp directory

• level (int, optional) – Logging level (default: INFO for detailed mass flow logging)

Returns:

Configured logger instance writing to timestamped file

Return type:

logging.Logger

uesgraphs.systemmodels.utilities.prepare_graph(graph, T_supply, p_supply, T_return, p_return, dT_design, m_flow_nominal=None, dp_nominal=None, dT_building=None, T_supply_building=None, cop_nominal=None, T_con_nominal=None, T_eva_nominal=None, dTEva_nominal=None, dTCon_nominal=None)

Adds data for model generation to the uesgraph

Parameters:

• graph (uesgraphs.uesgraph.UESGraph) – Network graph with all data for the model

• T_supply (list) – Design supply temperature in K

• p_supply (float) – Prescribed supply pressure in Pa

• T_return (float) – Design return temperature in K

• p_return (float) – Prescribed return pressure in Pa

• dT_design (float) – Design temperature difference over substation in K

• m_flow_nominal (float) – Nominal mass flow rate in kg/s

• dp_nominal (float) – Nominal pressure drop over the substation in Pa

• dT_building (float) – Prescribed temperature difference for the building heating system in K

• T_supply_building (float) – Supply temperature of the building heating system in K

• cop_nominal (float) – A nominal COP for substations that use a heat pump

• T_con_nominal (float) – Nominal condenser temperature of heat pump

• T_eva_nominal (float) – Nominal evaporator temperature of heat pump

• dTEva_nominal (float (default -10 K)) – Nominal temperature difference at heat pump evaporator

• dTCon_nominal (float (default 10 K)) – Nominal temperature difference at heat pump condenser

uesgraphs.systemmodels.utilities.create_model(name, save_at, graph, stop_time, timestep, model_supply, model_demand, model_pipe, model_medium, model_ground, T_nominal, p_nominal, solver=None, tolerance=1e-05, params_kusuda=None, fraction_glycol=None, pressure_control_supply=None, pressure_control_dp=None, pressure_control_building=None, pressure_control_p_max=None, pressure_control_k=None, pressure_control_ti=None, t_ground_prescribed=None, short_pipes_static=None, meta_data=None, logger=None)

Generic model generation for setup defined through the parameters

Parameters:

• name (str) – Name of the model (First character will be capitalized, cannot start with digit)

• save_at (str) – Directory where to store the generated model package

• graph (uesgraphs.uesgraph.UESGraph) – Network graph with all necessary data for model generation

• stop_time (int) – Stop time of the simulation in seconds

• timestep (int) – Timestep of the simulation in seconds

• model_supply (str) – One of the supply models supported by uesmodels

• model_demand (str) – One of the demand models supported by uesmodels

• model_pipe (str) – One of the pipe models supported by uesmodels

• model_medium (str) – One of the medium models supported by uesmodels

• model_ground (str) – One of the ground models supported by uesmodels

• T_nominal (float) – Nominal temperature for model initialization in K

• p_nominal (float) – Nominal pressure for model initialization in Pa

• solver (str) – Solver to use in dymola

• tolerance (float) – Solver tolerance to store in the model

• params_kusuda (dict) – Kusuda ground model parameters. Default values are for Aachen taken from TRY file

• fraction_glycol (float) – Value between 0 (100 % water) and 0.6 (60 % glycol) for the medium in the network

• pressure_control_supply (str) – Name of supply to control the pressure in the network

• pressure_control_dp (float) – Pressure difference to be held at reference building

• pressure_control_building (str) – Name of the reference building for the network. For default ‘max_distance’, the building with the greatest distance from the supply unit will be chosen

• pressure_control_p_max (float) – Maximum pressure allowed for the pressure controller

• pressure_control_k (int) – gain of controller

• pressure_control_ti (int) – time constant for integrator block

• t_ground_prescribed (list) – List of ground temperatures for every time step when using model_ground=”t_ground_table”

• short_pipes_static (float) – The float value specifies the length of pipes considered short. If a pipe length is smaller than the value for short_pipes_static, a static pipe model will be used for it.

• meta_data (dict) – Dictionary with meta data

• logger (logging.Logger, optional) – Logger instance for debugging

uesgraphs.systemmodels.utilities.save_system_model_to_json(model, filepath)

Save a SystemModelHeating object to a JSON file with comprehensive attribute capturing.

Parameters:

• model – SystemModelHeating - The model to save

• filepath – str - Path where the JSON file should be saved

Returns:

str - Path to the saved file

uesgraphs.systemmodels.utilities.load_system_model_from_json(filepath)

Load a SystemModelHeating object from a JSON file, respecting the constructor’s signature.

Parameters:

filepath – str - Path to the JSON file

Returns:

SystemModelHeating - The reconstructed model

uesgraphs.systemmodels.utilities.estimate_fac(graph, u_form_distance=25, n_gate_valve=2.0)

Calculate fac for all pipes based on m_flow_nominal

Parameters:

• graph (uesgraphs.uesgraph.UESGraph) – Graph of the network

• u_form_distance (int) – distance between U-form for thermal stress of pipes. Default: every 25m one U-Form is added

• n_gate_valve (float) – number of gate valves per pipe. For average values, n_gate_valve is a float. Default: 2 Gate valves per pipe.

Returns:

graph – Graph of the network

Return type:

uesgraphs.uesgraph.UESGraph

uesgraphs.systemmodels.utilities.estimate_m_flow_nominal(graph, dT_design, network_type, cp=4184)

DEPRECATED: Use estimate_m_flow_demand_based instead.

This function is maintained for backward compatibility and will be removed in version X.Y.Z.

Calculate all design mass flows based on nominal loads for each edge.

Parameters:

• graph (uesgraphs.uesgraph.UESGraph) – Graph of the network

• dT_design (float) – Design temperature difference between supply and return in K

• network_type (str) – {‘heating’, ‘cooling’}

• cp (float) – Specific heat capacity of fluid in the network

Returns:

graph – Graph of the network

Return type:

uesgraphs.uesgraph.UESGraph

uesgraphs.systemmodels.utilities.estimate_m_flow_nominal_tablebased(graph, network_type)

Calculate m_flow_nominal based on the pipe diameter.

This function calculates the m_flow_nominal based on the pipe diameter and according to the isoplus table for suggested m_flows for specific pipe diameters with a average pressure loss of 70 Pa/m. Link: http://www.isoplus.de/fileadmin/user_upload/downloads/documents/germany/Catalogue_German/Kapitel_2_Starre_Verbundsysteme.pdf page 9

Parameters:

• graph (uesgraphs.uesgraph.UESGraph) – Graph of the network

• network_type (str) – {‘heating’, ‘cooling’}

Returns:

graph – Graph of the network

Return type:

uesgraphs.uesgraph.UESGraph

uesgraphs.systemmodels.utilities.size_hydronic_network(graph: Any, m_flow_key=None, catalog=None, dT_attribute: str = 'dT_Network', network_type: str = 'heating', demand_attribute: str = 'input_heat', load_scenario: str = 'peak_load', cp: float = 4184, logger: Logger | None = None) → Any

uesgraphs.systemmodels.utilities.estimate_m_flow_demand_based(graph: Any, network_type: str = 'heating', demand_attribute: str = 'input_heat', load_scenario: str = 'peak_load', cp: float = 4184, dT_attribute: str = 'dT_Network', logger: Logger | None = None) → Any

Estimates mass flow for each edge by calculating flows at demand nodes and propagating backwards.

This function implements a physically correct approach where mass flows are calculated at each demand node based on their specific load and temperature difference, then aggregated backwards through the network following mass conservation principles.

Parameters:

• graph (UESGraph or nx.Graph) – The graph representing the network with nodelist_building attribute.

• network_type (str, optional) – Type of network, default is “heating”. Must be “heating” or “cooling”.

• demand_attribute (str, optional) – Attribute name containing load values in demand nodes, default is “input_heat”.

• load_scenario (str, optional) – Load scenario for calculation, default is “peak_load”. Options: “peak_load” (maximum value) or “average_load” (mean value).

• cp (float, optional) – Specific heat capacity of the fluid in J/(kg*K), default is 4184.

• dT_attribute (str) – Node attribute name for temperature difference values in Kelvin. Must be present in all demand nodes with positive numeric values. Used for individual mass flow calculations at each demand node.

• logger (logging.Logger, optional) – Logger instance for logging messages. If None, creates a default logger.

Returns:

graph – Input graph with additional edge attributes: - m_flow_{load_scenario}: Mass flow rate in kg/s for each edge - contributing_demands_{load_scenario}: List of demand nodes contributing to edge flow - supply_attribution_{load_scenario}: Dictionary showing which supply serves which demands

Return type:

UESGraph or nx.Graph

Raises:

• TypeError – If graph does not have required nodelist_building attribute.

• ValueError – If network_type or load_scenario parameters are invalid. If no supply or demand nodes are found. If required node attributes are missing.

uesgraphs.systemmodels.utilities.build_flow_paths(graph: Any, supply_nodes: List[Any], demand_nodes: List[Any], logger: Logger) → Dict[Tuple[Any, Any], List[Tuple[Any, Any]]]

Build flow paths from each supply node to reachable demand nodes.

This function identifies all supply-demand pairs that are connected and determines the shortest path between them, converting paths to edge lists.

Parameters:

• graph (UESGraph or nx.Graph) – Network graph

• supply_nodes (List[Any]) – List of supply node identifiers

• demand_nodes (List[Any]) – List of demand node identifiers

• logger (logging.Logger) – Logger for status messages

Returns:

Dictionary mapping (supply, demand) tuples to lists of edges in the flow path

Return type:

Dict[Tuple[Any, Any], List[Tuple[Any, Any]]]

uesgraphs.systemmodels.utilities.get_pipe_catalog_DN_m_flow(graph, pipe_catalog: DataFrame, logger: Logger, mass_flow_key: str, dn_key: str, diameter_key: str, robust: bool = True) → None

Assign pipe diameters to edges based on mass flow and catalog data.

Parameters:

• graph (Graph) – Network graph with edges containing mass flow data

• pipe_catalog (pd.DataFrame) – Catalog with columns: DN, inner_diameter, mass_flow_min, mass_flow_max

• logger (logging.Logger) – Logger instance

• mass_flow_key (str) – Edge attribute containing mass flow [kg/s]

• dn_key (str) – Edge attribute to store DN (default: “DN”)

• diameter_key (str) – Edge attribute to store diameter [m] (default: “diameter”)

• robust (bool) – If True, selects next larger pipe when no exact match (default: True)

uesgraphs.systemmodels.utilities.load_pipe_catalog(catalog_name: str = 'isoplus', custom_path: str | None = None) → DataFrame

Load pipe catalog data from CSV file in the data/pipe_catalogs directory.

This function loads manufacturer pipe catalog data containing pipe dimensions and flow capacities for different nominal diameters (DN). The catalog files are expected to be located in the data/pipe_catalogs subdirectory relative to the systemmodels module.

Parameters:

catalog_name (str, optional) – Name of the pipe catalog to load (default: “isoplus”) The function will look for a file named “{catalog_name}.csv”

Returns:

DataFrame containing pipe catalog data with columns: - DN: Nominal diameter [designated, e.g. DN20] - wall_thickness: Pipe wall thickness [m] - inner_diameter: Inner pipe diameter [m] - mass_flow_min: Minimum mass flow capacity [kg/s] - mass_flow_max: Maximum mass flow capacity [kg/s]

Return type:

pd.DataFrame

Raises:

• FileNotFoundError – If the specified catalog file does not exist

• ValueError – If the catalog file exists but contains invalid data structure

Examples

>>> catalog = load_pipe_catalog("isoplus")
>>> print(catalog.columns.tolist())
['DN', 'wall_thickness', 'inner_diameter', 'mass_flow_min', 'mass_flow_max']

>>> # Load different catalog (if available)
>>> rehau_catalog = load_pipe_catalog("rehau")

Notes

The CSV files can contain comment lines starting with ‘#’ which will be automatically ignored during loading. This allows for metadata and source information to be stored directly in the catalog files.

The function expects the catalog files to be located at: {module_directory}/uesgraphs/data/pipe_catalogs/{catalog_name}.csv

uesgraphs.systemmodels.utilities.get_inner_diameter_from_DN(dn_value, catalog_name='isoplus', custom_path: str | None = None)

Quick lookup for inner diameter based on DN value only.

Simplified version for imports that only have DN information (like GeoJSON) without mass flow data.

Parameters:

• dn_value (int or float) – Nominal diameter (DN)

• catalog_name (str) – Pipe catalog to use (default: “isoplus”)

• custom_path (str, optional) – Custom path to the catalog file if not using the default location.

Returns:

Inner diameter in meters, or None if not found

Return type:

float

Notes

For more sophisticated selection based on mass flow, use get_pipe_catalog_DN_m_flow() instead.