uesgraphs.systemmodels_pp package

Submodules

uesgraphs.systemmodels_pp.systemmodelheating module

This module includes the uesgraph to write a pandapipes model and simulation

uesgraphs.systemmodels_pp.systemmodelheating.set_up_logger(name, log_dir=None, level=40)[source]

Sets up a configured logger with file handler.

Creates a logger with specified name and logging level. Log files are stored in a directory with timestamp in filename. If no directory is specified, the system’s temporary directory is used.

Parameters:

  • name (str) – Name of the logger, also used for filename

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

  • level (int, optional) – Logging level (e.g. logging.ERROR, logging.INFO). Defaults to logging.ERROR

Returns:

Configured logger object

Return type:

logging.Logger

Example

>>> logger = set_up_logger("my_app", "/var/log", logging.INFO)
>>> logger.info("Application started")

Notes

  • Log filename format: {name}_{YYYYMMDD_HHMMSS}.log

  • Log entry format: time - logger_name - [file:line] - level - message

uesgraphs.systemmodels_pp.systemmodelheating.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

class uesgraphs.systemmodels_pp.systemmodelheating.SystemModelHeating(stop_time, start_time, timestep, network_type='heating', logger=None)[source]

Bases: UESGraph

Writes pandapipes model for system models from uesgraphs information

While a uesgraph object uses edges and nodes to describe the network topology, the pandapipes model uses junctions and pipes. Therefore, each node in the uesgraph is represented by two junctions in the pandapipes model (supply and return). At the current stage, only heating networks are supported.

stop_time

Stop time for simulation in seconds

Type:

float

timestep

Timestep for simulation in seconds

Type:

float

timesteps

Number of timesteps for simulation calculated from ‘timestep’ and ‘stop_time’

Type:

int

graph["T_ground"]

Ground temperature in Kelvin

Type:

list

pp_network

Pandapipes network object

Type:

pp.net

__init__(stop_time, start_time, timestep, network_type='heating', logger=None)[source]

Constructor for UESGraph class.

import_nodes_from_uesgraph(uesgraph_input, logger=None)[source]

Imports nodes from UESGraph into pandapipes junctions.

Parameters:

  • uesgraph_input (uesgraphs.uesgraph.UESGraph object) – At current stage, this uesgraph should contain only 1 network of 1 type that is indexed in the corrsponding nodelist as ‘default’

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

Returns:

Tuple containing: - junction_ids: Mapping of uesgraph node IDs to pandapipes junction IDs - heat_source_id: ID of the heat source junction - heat_source_r_id: ID of the heat source return junction

Return type:

Tuple[dict, int, int]

import_edges_from_uesgraph(uesgraph_input, junction_ids, logger=None)[source]

Imports edges from UESGraph into pandapipes pipes.

Parameters:

  • uesgraph_input (uesgraphs.uesgraph.UESGraph object) – At current stage, this uesgraph should contain only 1 network of 1 type that is indexed in the corrsponding nodelist as ‘default’

  • junction_ids (dict) – Mapping of uesgraph node IDs to pandapipes junction IDs

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

Returns:

Tuple containing: - pipe_list: List of pipes with their details

Return type:

Tuple[list, dict]

import_from_uesgraph(uesgraph_input, logger=None)[source]

Imports full UESGraph into pandapipes model.

Parameters:

  • uesgraph_input (uesgraphs.uesgraph.UESGraph object) – At current stage, this uesgraph should contain only 1 network of 1 type that is indexed in the corrsponding nodelist as ‘default’

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

Returns:

Tuple containing: - junction_ids: Mapping of uesgraph node IDs to pandapipes junction IDs - pipe_list: List of pipes with their details - heat_source_id: ID of the heat source junction - heat_source_r_id: ID of the heat source return junction

Return type:

Tuple[dict, list, dict, int, int]

find_pipe_parameter(inner_diameter: float)[source]

Finds the insulation thickness for a given inner diameter of the pipe.

Uses a lookup table based on standard district heating pipe dimensions for insulation class 3 according to district heating planning handbook.

Parameters:

(float) (inner_diameter) –

Returns:

Tuple[float, float]

Return type:

Inner diameter in meters, insulation thickness in meters

Note

If the exact pipe diameter is not in the reference table, the closest size will be selected.

estimate_xi(l_pipe: float)[source]

Estimates the total loss coefficient for a pipe based on its length.

Calculates pressure losses from: - 90° elbows (approx. every 25m a U-form with 4x90° elbows) - Tee junctions (flow separation and association at ends) - Installed slide valves

Parameters:

l_pipe (float) – Length of the pipe in meters

Returns:

float

Return type:

Total loss coefficient (xi) for the pipe

References

  • Horlacher2016, Rohrleitungen 2 (S.519-521)

  • Boehmer Fernwärme documentation (S.46)

run_test_simulation(logger=None)[source]

Does a test simulation of the pandapipes network to check if it runs without errors.

Parameters:

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

Raises:

Exception – If the test simulation fails

pipe_order(pipe_list, heat_source_ids, heat_source_r_ids, logger=None)[source]
calculate_temperature_pipe_profile_implicit(T_in, T_prev, mdot, cp, alpha, d_in, T_ground, dx, dt, rho, sections)[source]

This function calculates with an implicit euler scheme the temperature distribution within one pipe.

Parameters:

  • (float) (rho) –

  • (list) (T_prev) –

  • (float) –

  • (float) –

  • (float) –

  • (float) –

  • (float) –

  • (float) –

  • (float) –

  • (float) –

  • (int) (sections) –

Returns:

list

Return type:

Temperature distrubtion list in the pipe for the next time step

mix_junction_temperatures(pp_network, pipe_temp_history, pipe_subset, logger=None)[source]

This function calculates a mixing temperature if two pipes flow into one pipe.

Parameters:

  • pp_network (pandapipes-network) – Pandapipes network

  • pipe_temp_history (dict) – Temperatures of pipes to different time steps

  • pipe_subset (list) – Pipes that are used to find the inflowing pipes

Return type:

—

init_output_writer(log_variables)[source]
log_current_state(pp_network, output_data, log_variables, current_time)[source]
write_results_to_csv(output_data, log_variables, base_folder)[source]
run_timeseries_dpp(pipe_list, heat_source_ids, heat_source_r_ids, save_at, logger=None)[source]

This function runs the dynamic simulation of the pandapipes network and logs the results.

Parameters:

  • pipe_list (list) – List of pipes with their details

  • heat_source_ids (list) – List of heat source junction IDs

  • heat_source_r_ids (list) – List of heat source return junction IDs

  • save_at (str) – Folder path to save the results

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

Return type:

—

resample_profile_constant(df, factor)[source]

duplicate each row in the dataframe factor times to resample the profile with a constant value.

df: DataFrame with timesteps as index factor: int, number of times each row should be duplicated

run_timeseries_spp(save_at, mode, logger=None)[source]

Does timeseries calculation of the pandapipes network and saves the results in save_at.

Parameters:

  • save_at (str) – Path where the results will be saved

  • mode (str) – Mode of the simulation, either “static” for static simulation or “transient” for transient pandapipes simulation.

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

Raises:

Exception – If the timeseries simulation fails

uesgraphs.systemmodels_pp.utilities module

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

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