uesgraphs.systemmodels_pp.utilities

This module collects the functions for creating a pandapipes model from a UESGraph and simulating it.

Functions

assign_csv_data_to_uesgraph(uesgraph_input, ...)

Reads CSV-pandapipes results (Junctions & Pipes) and saves them as Pandas Series in UESGraph.

assign_demand_data(uesgraph, input_paths_dict)

Assigns energy demand data to buildings in a UES (Urban Energy Systems) graph.

create_model(name, save_at, graph, ...[, ...])

Generic model generation for setup defined through the parameters

generate_simulation_model(uesgraph, ...[, ...])

Generate pandapipes simulation model using Excel-based parameter system.

load_component_parameters(excel_path, ...)

Load component parameters from an Excel file.

load_ground_temp_data(ground_temp_path)

load_simulation_settings_from_excel(excel_path)

Load simulation settings from Excel 'Simulation' sheet.

save_setup_params_to_csv(setup_params, ...)

Save simulation setup parameters to a CSV file.

set_up_file_logger(name[, log_dir, level])

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

set_up_logger(name[, log_dir, level])

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

uesgraph_to_pandapipes(uesgraph, ...[, ...])

Convert an Urban Energy System Graph (UESGraph) to pandapipes model and simulate it.

validate_paths(paths)

Validate if the provided file and directory paths exist.
uesgraphs.systemmodels_pp.utilities.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

uesgraphs.systemmodels_pp.utilities.set_up_logger(name, log_dir=None, level=20)[source]

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_pp.utilities.assign_csv_data_to_uesgraph(uesgraph_input, base_folder, mappings, supply_type=None, logger=None)[source]

Reads CSV-pandapipes results (Junctions & Pipes) and saves them as Pandas Series in UESGraph.

base_folder must have these folders: - res_junction/ - res_pipe/

Files and the names in the graph: res_junction/p_bar.csv → pressure res_junction/t_k.csv → temperature res_pipe/mdot_from_kg_per_s.csv → mflow res_pipe/v_mean_m_per_s.csv → velocity

Parameters:

  • uesgraph_input (uesgraphs.uesgraph.UESGraph object) – UESGraph to assign the data to

  • base_folder (str) – Folder where the CSV results are stored

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

Returns:

UESGraph with assigned data

Return type:

uesgraphs.uesgraph.UESGraph object

uesgraphs.systemmodels_pp.utilities.create_model(name, save_at, graph, start_time, stop_time, timestep, mode, t_ground_prescribed=None, logger=None)[source]

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 results

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

  • start_time (int) – Start time of the simulation in seconds

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

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

  • t_ground_prescribed (list) – List of ground temperatures for every time step

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

Returns:

  • new_model (spp.SystemModelHeating) – Generated system model

  • graph (uesgraphs.uesgraph.UESGraph) – Graph of the network with assigned simulation results

uesgraphs.systemmodels_pp.utilities.uesgraph_to_pandapipes(uesgraph, simplification_level, workspace, sim_setup_path, input_heating, input_dhw, input_cooling, ground_temp_path, logger=None, log_level=10)[source]

Convert an Urban Energy System Graph (UESGraph) to pandapipes model and simulate it.

This function processes a UESGraph, applies simplification, adds demand data, and generates the pandapipes results based on simulation parameters.

Parameters:

uesgraphUESGraph object or str

The UESGraph object or path to a JSON file containing the UESGraph data

simplification_levelint

Level of simplification to apply to the UESGraph (higher = more simplified)

workspacestr or Path

Directory path where output files will be saved

sim_setup_pathstr or Path

Path to the simulation setup configuration file

input_heatingstr or Path

Path to heating demand data

input_dhwstr or Path

Path to domestic hot water demand data

input_coolingstr or Path

Path to cooling demand data

ground_temp_pathstr or Path

Path to ground temperature data file

loggerlogging.Logger, optional

Logger instance. If None, creates a new file logger in temp directory

log_levelint, optional

Logging level (default is logging.DEBUG). Only used if logger is None

Returns:

—

Raises:

FileNotFoundError: If required files are missing ValueError: If uesgraph parameter is invalid Exception: For various processing errors with detailed messages

uesgraphs.systemmodels_pp.utilities.load_simulation_settings_from_excel(excel_path, logger=None)[source]

Load simulation settings from Excel ‘Simulation’ sheet.

Parameters:

  • excel_path (str or Path) – Path to Excel file containing simulation settings

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

Returns:

sim_params – Dictionary of simulation parameters

Return type:

dict

Raises:

ValueError – If required simulation parameters are missing

uesgraphs.systemmodels_pp.utilities.load_component_parameters(excel_path, component_type)[source]

Load component parameters from an Excel file.

Reads a specific sheet from an Excel file and returns parameters as a dictionary. Expected Excel structure: - Column A: Parameter (parameter names) - Column B: Value (parameter values)

Parameters:

  • excel_path (str or Path) – Path to the Excel file containing component parameters

  • component_type (str) – Type of component, must be one of: ‘pipes’, ‘supply’, ‘demands’, ‘simulation’ This determines which sheet to read from the Excel file

Returns:

Dictionary with parameter names as keys and their values Returns empty dict if sheet not found

Return type:

dict

Raises:

  • FileNotFoundError – If the Excel file does not exist

  • ValueError – If the component_type is not valid or Excel structure is incorrect

Examples

>>> params = load_component_parameters('parameters.xlsx', 'pipes')
>>> print(params['dp_nominal'])
0.10
uesgraphs.systemmodels_pp.utilities.generate_simulation_model(uesgraph, sim_name, sim_params, ground_temp_list, sim_model_dir, logger=None)[source]

Generate pandapipes simulation model using Excel-based parameter system.

This function assumes parameters are already assigned to uesgraph nodes/edges via the assign_*_parameters functions.

Parameters:

  • uesgraph (UESGraph) – Graph with pre-assigned parameters from Excel

  • sim_name (str) – Name of the simulation

  • sim_params (dict) – Simulation parameters from Excel ‘Simulation’ sheet

  • ground_temp_list (list) – Ground temperature data

  • sim_model_dir (str) – Directory to save pandapipes files

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

uesgraphs.systemmodels_pp.utilities.assign_demand_data(uesgraph, input_paths_dict, input_types=['heating', 'cooling', 'dhw'])[source]

Assigns energy demand data to buildings in a UES (Urban Energy Systems) graph.

This function reads demand profiles from CSV files and assigns them to building nodes in the graph. For buildings without specific demand data, it uses a fallback profile (dummy demand) based on the first building in the respective CSV file. The function can handle heating, cooling, and domestic hot water (DHW) demands.

Parameters:

  • uesgraph (ueesgraphs Graph) – The urban energy system graph containing building nodes.

  • input_paths_dict (dict) – Dictionary containing file paths for each demand type. Expected keys: ‘heating’, ‘cooling’, ‘dhw’.

  • input_types (list, optional) – List of demand types to process. Default is [“heating”, “cooling”, “dhw”].

Returns:

  • Updated UES graph with demand data assigned to building nodes

  • Message string containing information about the data assignment process

Return type:

tuple

Notes

Building nodes are updated with the following attributes:

  • input_heat: List of heating demand values

  • input_cool: List of cooling demand values

  • input_dhw: List of DHW demand values

  • max_demand_heating: Maximum combined heating/DHW demand

The function handles missing data by:

  1. Using a dummy profile if a building is not found in demand data

  2. Tracking which buildings exist in CSVs but not in the graph

uesgraphs.systemmodels_pp.utilities.validate_paths(paths)[source]

Validate if the provided file and directory paths exist.

Parameters:

pathslist

List of paths (strings or Path objects) to validate

Returns:

tuple

(existing_paths, missing_paths): Two lists containing the paths that exist and the paths that are missing, respectively

uesgraphs.systemmodels_pp.utilities.load_ground_temp_data(ground_temp_path)[source]
uesgraphs.systemmodels_pp.utilities.save_setup_params_to_csv(setup_params, sim_name, sim_model_dir)[source]

Save simulation setup parameters to a CSV file.

This function takes a single row from the simulation setup Excel file (as a dictionary) and saves it as a CSV file in a specified directory, with parameters as rows and their values as a single column.

Parameters:

setup_paramsdict

Dictionary containing simulation setup parameters (a single row from the Excel setup)

sim_namestr

Name of the current simulation, used for filename generation

sim_model_dirstr

Directory where to save the CSV file

Returns:

str

Path to the saved CSV file