Net simulation pandapipes package

Advanced Plots for DistrictHeatingSim

Funktionsfähige erweiterte Plot-Funktionen für pandapipes Netzwerke. Diese Version umgeht die API-Limitierungen der pandapipes Collection-Funktionen und bietet robuste, produktionsreife Plotting-Alternativen.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

Features:

  • Druckverteilungsplots mit Statistiken

  • Temperaturverteilungsplots

  • Geschwindigkeitsanalyse

  • Druckprofile

  • Interaktive Dashboards

  • Drop-in Ersatz für config_plot

districtheatingsim.net_simulation_pandapipes.advanced_plots.create_pressure_plot(net, ax: Axes | None = None, show_colorbar: bool = True)[source]

Pressure distribution plot with data-driven colors and statistics.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with simulation results

  • ax (Optional[plt.Axes]) – Matplotlib axis, creates new if None

  • show_colorbar (bool) – Display pressure colorbar, defaults to True

Returns:

Matplotlib axis with pressure plot

Return type:

plt.Axes

Note

Blue (low pressure) to red (high pressure). Plots junctions, pipes, consumers, pumps. Includes pressure range statistics.

districtheatingsim.net_simulation_pandapipes.advanced_plots.create_temperature_plot(net, ax: Axes | None = None)[source]

Temperature distribution plot with data-driven colors and statistics.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with simulation results

  • ax (Optional[plt.Axes]) – Matplotlib axis, creates new if None

Returns:

Matplotlib axis with temperature plot

Return type:

plt.Axes

Note

Plasma colormap (blue=cold, red=hot). Converts Kelvin to Celsius. Shows temperature range statistics.

districtheatingsim.net_simulation_pandapipes.advanced_plots.create_velocity_plot(net, ax: Axes | None = None)[source]

Velocity distribution plot for pipe flow analysis.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with simulation results

  • ax (Optional[plt.Axes]) – Matplotlib axis, creates new if None

Returns:

Matplotlib axis with velocity plot

Return type:

plt.Axes

Note

Viridis colormap (green=low, yellow=high). Plots pipe velocities with colorbar. Includes velocity range statistics.

districtheatingsim.net_simulation_pandapipes.advanced_plots.create_pressure_profile(net, ax: Axes | None = None)[source]

Pressure profile along network path showing pressure drop.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with simulation results

  • ax (Optional[plt.Axes]) – Matplotlib axis, creates new if None

Returns:

Matplotlib axis with pressure profile

Return type:

plt.Axes

Note

Distance vs pressure plot. Shows total pressure drop statistics.

districtheatingsim.net_simulation_pandapipes.advanced_plots.create_comparison_dashboard(net, figsize=(16, 12))[source]

Comprehensive analysis dashboard with 4 plot types.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with simulation results

  • figsize (tuple) – Figure size tuple (width, height), defaults to (16, 12)

Returns:

Figure and axes array (2x2)

Return type:

Tuple[plt.Figure, np.ndarray]

Note

4 subplots: topology, pressure profile, pressure distribution, temperature distribution. Includes network statistics text box.

districtheatingsim.net_simulation_pandapipes.advanced_plots.get_network_statistics(net)[source]

Extract network statistics as formatted text string.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network

Returns:

Formatted statistics string

Return type:

str

Note

Returns junction count, pipe count, consumer count, total load [kW], pressure range [bar].

districtheatingsim.net_simulation_pandapipes.advanced_plots.enhanced_config_plot(net, ax, plot_mode='traditional', **kwargs)[source]

Enhanced config_plot replacement with multiple visualization modes.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network to visualize

  • ax (matplotlib.axes.Axes) – Matplotlib axis for plotting

  • plot_mode (str) – Mode: ‘traditional’, ‘pressure’, ‘temperature’, ‘velocity’, ‘dashboard’

  • **kwargs – Additional arguments for plotting functions

Returns:

Matplotlib axis (or figure for dashboard mode)

Return type:

plt.Axes

Note

Drop-in replacement for config_plot. Dashboard mode returns new figure.

Config Plot Module

This module provides comprehensive visualization capabilities for district heating network analysis and presentation.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

It combines pandapipes network plotting with interactive features, contextual basemaps, and detailed component annotations to create professional-quality network visualizations for engineering analysis and stakeholder presentations.

The module supports various basemap providers, interactive hover annotations, and customizable component visibility to accommodate different visualization needs from technical analysis to public presentations. It integrates seamlessly with matplotlib and geographic visualization libraries for enhanced spatial context.

districtheatingsim.net_simulation_pandapipes.config_plot.config_plot(net, ax: Axes, show_junctions: bool = True, show_pipes: bool = True, show_heat_consumers: bool = True, show_pump: bool = True, show_plot: bool = False, show_basemap: bool = True, map_type: str = 'OSM', show_all_annotations: bool = False) → None[source]

Interactive pandapipes network visualization with hover annotations and basemaps.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with topology and simulation results

  • ax (matplotlib.axes.Axes) – Matplotlib axis for rendering

  • show_junctions (bool) – Display junctions with pressure/temperature, defaults to True

  • show_pipes (bool) – Display pipes with flow rates/velocities, defaults to True

  • show_heat_consumers (bool) – Display heat consumers with demand info, defaults to True

  • show_pump (bool) – Display circulation pumps, defaults to True

  • show_plot (bool) – Immediately display with plt.show(), defaults to False

  • show_basemap (bool) – Include contextual basemap, defaults to True

  • map_type (str) – Basemap type: “OSM”, “Satellite”, “Topology”, defaults to “OSM”

  • show_all_annotations (bool) – Force all annotations visible, defaults to False

Note

Interactive hover annotations, distance-based visibility. Requires geodata and internet for basemap tiles. Annotations: junctions (pressure/temp), pipes (flow/velocity), consumers (demand), pumps (pressure lift).

Controllers Module

This module provides specialized controllers for district heating network operation using the pandapipes framework.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

It implements advanced control strategies for pressure management, temperature regulation, and system optimization to ensure efficient and reliable network operation under varying load conditions.

The controllers integrate with pandapower’s control system architecture and support both steady-state and time-series simulations. They handle complex control scenarios including bad point pressure control, minimum temperature enforcement, and multi-producer coordination in district heating systems.

class districtheatingsim.net_simulation_pandapipes.controllers.BadPointPressureLiftController(net, circ_pump_pressure_idx: int = 0, target_dp_min_bar: float = 1.0, tolerance: float = 0.2, proportional_gain: float = 0.2, min_plift: float = 1.5, min_pflow: float = 3.5, **kwargs)[source]

Bases: BasicCtrl

Differential pressure controller maintaining adequate pressure at network’s worst point.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • circ_pump_pressure_idx (int) – Main circulation pump index, defaults to 0

  • target_dp_min_bar (float) – Target minimum pressure difference [bar], defaults to 1.0

  • tolerance (float) – Pressure difference tolerance [bar], defaults to 0.2

  • proportional_gain (float) – Proportional gain factor, defaults to 0.2

  • min_plift (float) – Minimum pump lift during standby [bar], defaults to 1.5

  • min_pflow (float) – Minimum flow pressure during standby [bar], defaults to 3.5

  • **kwargs – Additional arguments for base controller

Variables:

  • iteration (int) – Current iteration counter

  • dp_min (float) – Current minimum pressure difference [bar]

  • heat_consumer_idx (int) – Index of worst point consumer

Note

German “Differenzdruckregelung im Schlechtpunkt”. Identifies worst point (lowest Δp) among active consumers, applies proportional control to pump pressures. Standby mode with minimal circulation when all demands zero. Updates bad point dynamically each step.

__init__(net, circ_pump_pressure_idx: int = 0, target_dp_min_bar: float = 1.0, tolerance: float = 0.2, proportional_gain: float = 0.2, min_plift: float = 1.5, min_pflow: float = 3.5, **kwargs)[source]
calculate_worst_point(net) → Tuple[float, int][source]

Find heat consumer with lowest pressure difference among active consumers.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network with current simulation results

Returns:

(dp_min, idx_min) - minimum pressure difference [bar] and consumer index

Return type:

Tuple[float, int]

Note

Returns (0, -1) if no active consumers. Only considers consumers with qext_w != 0.

time_step(net, time_step: int) → int[source]

Reset controller state and recalculate worst point for new time step.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • time_step (int) – Current simulation time step index

Returns:

Current time step (pass-through)

Return type:

int

Note

Resets iteration counter to 0, recalculates worst point location.

is_converged(net) → bool[source]

Check convergence: standby or pressure within tolerance.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network with current simulation results

Returns:

True if converged, False otherwise

Return type:

bool

Note

Converged if: all qext_w == 0 (standby) OR |current_dp - target_dp| < tolerance

control_step(net) → None[source]

Adjust pump pressures based on pressure difference error at worst point.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network to control

Note

Standby mode if all qext_w == 0 (sets min_plift/min_pflow). Otherwise applies proportional control: error = target_dp - current_dp, adjustment = error × gain.

class districtheatingsim.net_simulation_pandapipes.controllers.MinimumSupplyTemperatureController(net, heat_consumer_idx: int, min_supply_temperature: float = 65.0, tolerance: float = 2.0, max_iterations: int = 100, temperature_adjustment_step: float = 1.0, debug: bool = False, **kwargs)[source]

Bases: BasicCtrl

Controller maintaining minimum supply temperatures at heat consumers via return temperature adjustment.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • heat_consumer_idx (int) – Index of heat consumer to control

  • min_supply_temperature (float) – Minimum required supply temperature [°C], defaults to 65.0

  • tolerance (float) – Temperature tolerance for convergence [°C], defaults to 2.0

  • max_iterations (int) – Maximum iterations per time step, defaults to 100

  • temperature_adjustment_step (float) – Temperature adjustment step [°C], defaults to 1.0

  • debug (bool) – Enable debug output, defaults to False

  • **kwargs – Additional arguments for base controller

Variables:

  • data_source (Optional[Any]) – External time-varying temperature setpoints

  • iteration (int) – Current iteration counter

  • previous_temperatures (List[float]) – Temperature history for weighted averaging

  • standard_return_temperature (float) – Original return temperature setpoint

Note

Critical for cold networks with heat pumps. Monitors supply temperature, adjusts return temperature setpoint to increase supply (higher return → higher mass flow → higher supply). Uses weighted averaging for stability. Supports time-varying requirements via data_source.

__init__(net, heat_consumer_idx: int, min_supply_temperature: float = 65.0, tolerance: float = 2.0, max_iterations: int = 100, temperature_adjustment_step: float = 1.0, debug: bool = False, **kwargs)[source]
time_step(net, time_step: int) → int[source]

Reset controller and update temperature setpoints for new time step.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • time_step (int) – Current simulation time step index

Returns:

Current time step (pass-through)

Return type:

int

Note

Resets iteration counter and temperature history. Stores/restores standard return temperature. Updates min_supply_temperature from data_source if available.

get_weighted_average_temperature() → float | None[source]

Calculate weighted average of recent supply temperatures for stability.

Returns:

Weighted average temperature [°C], or None if no history

Return type:

Optional[float]

Note

Linear weighting: recent values weighted more heavily. Prevents oscillations.

control_step(net) → None[source]

Adjust return temperature to ensure minimum supply temperature.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network to control

Note

Standby mode if all qext_w == 0. Uses weighted averaging for stability. Increases return temp if supply < minimum (higher return → higher mass flow → higher supply).

is_converged(net) → bool[source]

Check convergence: standby, temperature met and stable, or max iterations.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network with current simulation results

Returns:

True if converged, False otherwise

Return type:

bool

Note

Converged if: all qext_w == 0 (standby) OR (supply >= minimum AND change < tolerance) OR max iterations reached. Maintains temperature history for weighted averaging.

Interactive Network Plot Module

Modern interactive visualization for pandapipes district heating networks using Plotly.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

Features:

  • Interactive hover tooltips with detailed component information

  • Click events for component selection and inspection

  • Color-coded visualization of any network parameter

  • Multiple basemap options (OSM, Satellite, Topology)

  • Layer visibility controls

  • Dynamic parameter selection

  • Export capabilities (HTML, PNG)

class districtheatingsim.net_simulation_pandapipes.interactive_network_plot.InteractiveNetworkPlot(net, crs: str = 'EPSG:25833')[source]

Bases: object

Interactive Plotly-based network visualization with advanced features.

Variables:

  • net (pandapipes.pandapipesNet) – Pandapipes network to visualize

  • crs (str) – Coordinate reference system

  • fig (Optional[go.Figure]) – Plotly figure object

  • available_parameters (Dict[str, List[str]]) – Available parameters per component type

Note

Color-coded parameter visualization, hover tooltips, click events, multiple basemap options for comprehensive network analysis.

__init__(net, crs: str = 'EPSG:25833')[source]

Initialize interactive network plot.

Parameters:

  • net (pandapipes.pandapipesNet) – Network to visualize

  • crs (str) – Coordinate reference system, defaults to “EPSG:25833”

create_interactive_plot_with_controls(basemap_style: str = 'carto-positron', colorscale: str = 'Viridis') → Figure[source]

Create interactive plot with dropdown controls for parameter selection.

Parameters:

  • basemap_style (str) – Mapbox style: ‘open-street-map’, ‘carto-positron’, ‘white-bg’, ‘satellite’

  • colorscale (str) – Plotly colorscale name, defaults to ‘Viridis’

Returns:

Interactive Plotly figure with dropdown controls

Return type:

go.Figure

Note

Pre-generates all visualizations for dropdown functionality in standalone HTML.

create_plot_for_parameter(component_type: str, parameter: str, basemap_style: str = 'carto-positron', colorscale: str = 'Viridis') → Figure[source]

Create plot for specific parameter visualization (on-demand loading).

Parameters:

  • component_type (str) – Component type: ‘junction’, ‘pipe’, ‘heat_consumer’, ‘pump’, ‘flow_control’

  • parameter (str) – Parameter name to visualize

  • basemap_style (str) – Mapbox style, defaults to ‘carto-positron’

  • colorscale (str) – Plotly colorscale, defaults to ‘Viridis’

Returns:

Interactive plot for the specific parameter

Return type:

go.Figure

create_plot(parameter: str | None = None, component_type: str | None = None, show_junctions: bool = True, show_pipes: bool = True, show_heat_consumers: bool = True, show_pumps: bool = True, show_flow_controls: bool = True, basemap_style: str = 'open-street-map', colorscale: str = 'Viridis') → Figure[source]

Create interactive network plot with optional parameter visualization.

Parameters:

  • parameter (Optional[str]) – Parameter to visualize (e.g., ‘p_bar’, ‘v_mean_m_per_s’), optional

  • component_type (Optional[str]) – Component type: ‘junction’, ‘pipe’, ‘heat_consumer’, ‘pump’, optional

  • show_junctions (bool) – Show junction nodes, defaults to True

  • show_pipes (bool) – Show pipe connections, defaults to True

  • show_heat_consumers (bool) – Show heat consumers, defaults to True

  • show_pumps (bool) – Show circulation pumps, defaults to True

  • show_flow_controls (bool) – Show flow control components, defaults to True

  • basemap_style (str) – Mapbox style: ‘open-street-map’, ‘satellite’, ‘white-bg’, ‘carto-positron’

  • colorscale (str) – Plotly colorscale name, defaults to ‘Viridis’

Returns:

Interactive Plotly figure

Return type:

go.Figure

export_html(filename: str)[source]

Export plot to interactive HTML file.

Parameters:

filename (str) – Output HTML filename

export_png(filename: str, width: int = 1920, height: int = 1080)[source]

Export plot to PNG (requires kaleido package).

Parameters:

  • filename (str) – Output PNG filename

  • width (int) – Image width in pixels, defaults to 1920

  • height (int) – Image height in pixels, defaults to 1080

Network Generation Data Class Module

This module provides data structures for comprehensive district heating network simulation and analysis.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

It defines the core data classes used throughout the simulation workflow, including network configuration parameters, input/output data management, and result processing capabilities.

The module supports various network configurations including traditional hot water networks, cold networks with decentralized heat pumps, and hybrid systems with multiple heat generators. It handles time series data, temperature control strategies, and comprehensive result analysis with automatic calculation of key performance indicators.

class districtheatingsim.net_simulation_pandapipes.NetworkDataClass.SecondaryProducer(index: int, load_percentage: float, mass_flow: float | None = None)[source]

Bases: object

Secondary heat producer with mass flow control based on load percentage.

Variables:

  • index (int) – Unique producer index matching GeoJSON heat producer location

  • load_percentage (float) – Percentage of total network heat load [%]

  • mass_flow (Optional[float]) – Calculated mass flow [kg/s], set during preprocessing

Note

Load percentages across all secondary producers should not exceed 100%. Main producer handles remaining capacity. Extensible for additional parameters.

index: int
load_percentage: float
mass_flow: float | None = None
__init__(index: int, load_percentage: float, mass_flow: float | None = None) → None
class districtheatingsim.net_simulation_pandapipes.NetworkDataClass.NetworkGenerationData(import_type: str, network_geojson_path: str, heat_demand_json_path: str, netconfiguration: str, supply_temperature_control: str, max_supply_temperature_heat_generator: float, min_supply_temperature_heat_generator: float, max_air_temperature_heat_generator: float, min_air_temperature_heat_generator: float, flow_pressure_pump: float, lift_pressure_pump: float, min_supply_temperature_building_checked: bool, min_supply_temperature_building: float, fixed_return_temperature_heat_consumer_checked: bool, fixed_return_temperature_heat_consumer: float, dT_RL: float, building_temperature_checked: bool, pipetype: str, diameter_optimization_pipe_checked: bool, max_velocity_pipe: float, material_filter_pipe: str, k_mm_pipe: float, main_producer_location_index: int, secondary_producers: List[SecondaryProducer], COP_filename: str | None = None, TRY_filename: str | None = None, supply_temperature_buildings: ndarray | None = None, return_temperature_buildings: ndarray | None = None, supply_temperature_building_curve: ndarray | None = None, return_temperature_building_curve: ndarray | None = None, yearly_time_steps: ndarray | None = None, waerme_gebaeude_ges_W: ndarray | None = None, heizwaerme_gebaeude_ges_W: ndarray | None = None, ww_waerme_gebaeude_ges_W: ndarray | None = None, max_waerme_gebaeude_ges_W: ndarray | None = None, return_temperature_heat_consumer: ndarray | None = None, min_supply_temperature_heat_consumer: ndarray | None = None, waerme_hast_ges_W: ndarray | None = None, max_waerme_hast_ges_W: ndarray | None = None, strombedarf_hast_ges_W: ndarray | None = None, max_el_leistung_hast_ges_W: ndarray | None = None, waerme_hast_ges_kW: ndarray | None = None, strombedarf_hast_ges_kW: ndarray | None = None, waerme_ges_kW: ndarray | None = None, strombedarf_ges_kW: ndarray | None = None, net: Any | None = None, start_time_step: int | None = None, end_time_step: int | None = None, results_csv_filename: str | None = None, supply_temperature_heat_generator: float | ndarray | None = None, net_results: Dict[str, Any] | None = None, pump_results: Dict[str, Any] | None = None, plot_data: Dict[str, Any] | None = None, kpi_results: Dict[str, int | float | None] | None = None)[source]

Bases: object

Central data container for district heating network simulation and analysis.

Variables:

  • import_type (str) – Import method type (currently “geoJSON”)

  • network_geojson_path (str) – Path to unified GeoJSON file (Wärmenetz.geojson)

  • heat_demand_json_path (str) – Path to building heat demand JSON

  • netconfiguration (str) – Network type (“kaltes Netz”, “Niedertemperaturnetz”)

  • supply_temperature_control (str) – Control strategy (“Statisch”, “Gleitend”)

  • max_supply_temperature_heat_generator (float) – Maximum supply temperature [°C]

  • min_supply_temperature_heat_generator (float) – Minimum supply temperature for sliding control [°C]

  • max_air_temperature_heat_generator (float) – Maximum outdoor air temperature [°C]

  • min_air_temperature_heat_generator (float) – Design outdoor air temperature [°C]

  • flow_pressure_pump (float) – Pump outlet pressure [bar]

  • lift_pressure_pump (float) – Pump pressure lift [bar]

  • pipetype (str) – Standard pipe type designation

  • diameter_optimization_pipe_checked (bool) – Enable diameter optimization

  • max_velocity_pipe (float) – Maximum water velocity [m/s]

  • material_filter_pipe (str) – Pipe material filter

  • k_mm_pipe (float) – Pipe roughness [mm]

  • main_producer_location_index (int) – Main heat producer index in GeoJSON

  • secondary_producers (List[SecondaryProducer]) – List of secondary producers

  • net (Optional[Any]) – Pandapipes network object

  • pump_results (Optional[Dict[str, Any]]) – Structured pump simulation results

  • plot_data (Optional[Dict[str, Any]]) – Processed visualization data

  • kpi_results (Optional[Dict[str, Union[int, float, None]]]) – Key performance indicators

Note

Supports GeoJSON-based initialization, time series simulation, KPI calculation. Handles cold networks (heat pumps), static/sliding temperature control. Data flow: GeoJSON+JSON → initialization → simulation → results → KPIs.

import_type: str
network_geojson_path: str
heat_demand_json_path: str
netconfiguration: str
supply_temperature_control: str
max_supply_temperature_heat_generator: float
min_supply_temperature_heat_generator: float
max_air_temperature_heat_generator: float
min_air_temperature_heat_generator: float
flow_pressure_pump: float
lift_pressure_pump: float
min_supply_temperature_building_checked: bool
min_supply_temperature_building: float
fixed_return_temperature_heat_consumer_checked: bool
fixed_return_temperature_heat_consumer: float
dT_RL: float
building_temperature_checked: bool
pipetype: str
diameter_optimization_pipe_checked: bool
max_velocity_pipe: float
material_filter_pipe: str
k_mm_pipe: float
main_producer_location_index: int
secondary_producers: List[SecondaryProducer]
COP_filename: str | None = None
TRY_filename: str | None = None
supply_temperature_buildings: ndarray | None = None
return_temperature_buildings: ndarray | None = None
supply_temperature_building_curve: ndarray | None = None
return_temperature_building_curve: ndarray | None = None
yearly_time_steps: ndarray | None = None
waerme_gebaeude_ges_W: ndarray | None = None
heizwaerme_gebaeude_ges_W: ndarray | None = None
ww_waerme_gebaeude_ges_W: ndarray | None = None
max_waerme_gebaeude_ges_W: ndarray | None = None
return_temperature_heat_consumer: ndarray | None = None
min_supply_temperature_heat_consumer: ndarray | None = None
waerme_hast_ges_W: ndarray | None = None
max_waerme_hast_ges_W: ndarray | None = None
strombedarf_hast_ges_W: ndarray | None = None
max_el_leistung_hast_ges_W: ndarray | None = None
waerme_hast_ges_kW: ndarray | None = None
strombedarf_hast_ges_kW: ndarray | None = None
waerme_ges_kW: ndarray | None = None
strombedarf_ges_kW: ndarray | None = None
net: Any | None = None
start_time_step: int | None = None
end_time_step: int | None = None
results_csv_filename: str | None = None
supply_temperature_heat_generator: float | ndarray | None = None
net_results: Dict[str, Any] | None = None
pump_results: Dict[str, Any] | None = None
plot_data: Dict[str, Any] | None = None
kpi_results: Dict[str, int | float | None] | None = None
calculate_results() → Dict[str, int | float | None][source]

Calculate network KPIs including heat density, losses, and pump consumption.

Returns:

Dict with KPIs (Anzahl angeschlossene Gebäude, Jahresgesamtwärmebedarf [MWh/a], max. Heizlast [kW], Trassenlänge [m], Wärmebedarfsdichte [MWh/(a*m)], Anschlussdichte [kW/m], Jahreswärmeerzeugung [MWh], Pumpenstrom [MWh], Verteilverluste [MWh], rel. Verteilverluste [%])

Return type:

Dict[str, Union[int, float, None]]

Note

Density = demand/length. Losses = generation - demand. Pump power from mass flow and Δp. Network length divided by 2 (supply+return). Requires net, pump_results, waerme_ges_kW.

prepare_plot_data() → None[source]

Structure simulation results for visualization with labels, axes, and time alignment.

Note

Creates plot_data dict with entries: data (numpy array), label (string), axis (left/right), time (array). Includes heat demand, electrical data (cold networks), producer data (heat generation, mass flow, pressures, temperatures). Indexed by variable name and producer number.

to_dict() → Dict[str, Any][source]

Serialize network data including KPIs for saving.

Returns:

Dictionary with all object attributes including kpi_results

Return type:

Dict[str, Any]

classmethod from_dict(data: Dict[str, Any]) → NetworkGenerationData[source]

Deserialize network data from saved dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary with serialized network data

Returns:

Reconstructed NetworkGenerationData object with KPIs

Return type:

NetworkGenerationData

__init__(import_type: str, network_geojson_path: str, heat_demand_json_path: str, netconfiguration: str, supply_temperature_control: str, max_supply_temperature_heat_generator: float, min_supply_temperature_heat_generator: float, max_air_temperature_heat_generator: float, min_air_temperature_heat_generator: float, flow_pressure_pump: float, lift_pressure_pump: float, min_supply_temperature_building_checked: bool, min_supply_temperature_building: float, fixed_return_temperature_heat_consumer_checked: bool, fixed_return_temperature_heat_consumer: float, dT_RL: float, building_temperature_checked: bool, pipetype: str, diameter_optimization_pipe_checked: bool, max_velocity_pipe: float, material_filter_pipe: str, k_mm_pipe: float, main_producer_location_index: int, secondary_producers: List[SecondaryProducer], COP_filename: str | None = None, TRY_filename: str | None = None, supply_temperature_buildings: ndarray | None = None, return_temperature_buildings: ndarray | None = None, supply_temperature_building_curve: ndarray | None = None, return_temperature_building_curve: ndarray | None = None, yearly_time_steps: ndarray | None = None, waerme_gebaeude_ges_W: ndarray | None = None, heizwaerme_gebaeude_ges_W: ndarray | None = None, ww_waerme_gebaeude_ges_W: ndarray | None = None, max_waerme_gebaeude_ges_W: ndarray | None = None, return_temperature_heat_consumer: ndarray | None = None, min_supply_temperature_heat_consumer: ndarray | None = None, waerme_hast_ges_W: ndarray | None = None, max_waerme_hast_ges_W: ndarray | None = None, strombedarf_hast_ges_W: ndarray | None = None, max_el_leistung_hast_ges_W: ndarray | None = None, waerme_hast_ges_kW: ndarray | None = None, strombedarf_hast_ges_kW: ndarray | None = None, waerme_ges_kW: ndarray | None = None, strombedarf_ges_kW: ndarray | None = None, net: Any | None = None, start_time_step: int | None = None, end_time_step: int | None = None, results_csv_filename: str | None = None, supply_temperature_heat_generator: float | ndarray | None = None, net_results: Dict[str, Any] | None = None, pump_results: Dict[str, Any] | None = None, plot_data: Dict[str, Any] | None = None, kpi_results: Dict[str, int | float | None] | None = None) → None

Pandapipes Network Initialization Module

This module provides comprehensive network initialization capabilities for district heating systems using GeoJSON-based geographic data.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

It handles the complete workflow from GeoJSON data processing to pandapipes network creation, including heat demand integration, temperature calculation, and multi-producer system configuration.

The module supports various network configurations including traditional hot water networks, cold networks with decentralized heat pumps, and hybrid systems with multiple heat generators. It automatically processes building heat demands, calculates temperature requirements, and creates appropriate network topologies with proper controller configurations.

districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson.initialize_geojson(NetworkGenerationData) → Any[source]

Initialize district heating network from unified GeoJSON and heat demand data.

Parameters:

NetworkGenerationData (object) – Configuration with network_geojson_path, heat_demand_json_path, temperatures, pipe specs, producer config

Returns:

Updated NetworkGenerationData with initialized net, time series, mass flows, building data

Return type:

Any

Raises:

Note

Loads unified GeoJSON (Wärmenetz.geojson), processes heat demands, validates temperatures. Handles cold networks (COP calculation), applies 2% min load. Calculates mass flows (main: total demand/ΔT, secondary: percentage-based). Creates complete pandapipes network.

districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson.get_line_coords_and_lengths(gdf: GeoDataFrame) → Tuple[List[List[Tuple]], List[float]][source]

Extract coordinates and lengths from LineString geometries.

Parameters:

gdf (gpd.GeoDataFrame) – GeoDataFrame with LineString geometries (flow/return lines)

Returns:

(all_line_coords, all_line_lengths) - coordinate sequences and lengths

Return type:

Tuple[List[List[Tuple]], List[float]]

Note

Only processes LineString geometries, skips others with warning. Uses GeoPandas length property for geodetic calculation.

districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson.get_all_point_coords_from_line_cords(all_line_coords: List[List[Tuple]]) → List[Tuple][source]

Extract unique point coordinates for network junction creation.

Parameters:

all_line_coords (List[List[Tuple]]) – List of coordinate sequences [(x1,y1), (x2,y2), …]

Returns:

Unique point coordinates (x, y) for junction locations

Return type:

List[Tuple]

Note

Removes duplicates using set operations. Order not guaranteed. Essential for proper network topology without duplicate junctions.

districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson.create_network(gdf_dict: Dict[str, GeoDataFrame], consumer_dict: Dict[str, Any], pipe_dict: Dict[str, Any], producer_dict: Dict[str, Any]) → pandapipesNet[source]

Create complete pandapipes network with junctions, pipes, consumers, and producers.

Parameters:

  • gdf_dict (Dict[str, gpd.GeoDataFrame]) – GeoDataFrames with keys flow_line, return_line, heat_consumer, heat_producer

  • consumer_dict (Dict[str, Any]) – Heat consumer config (qext_w, min_supply_temperature_heat_consumer, return_temperature_heat_consumer)

  • pipe_dict (Dict[str, Any]) – Pipe config (pipetype, v_max_pipe, material_filter, pipe_creation_mode, k_mm)

  • producer_dict (Dict[str, Any]) – Producer config (supply_temperature, pressures, main_producer_location_index, secondary_producers)

Returns:

Complete pandapipes network with optimized diameters and controllers

Return type:

pp.pandapipesNet

Note

Steps: 1) junctions from coords, 2) pipes (supply/return), 3) heat consumers, 4) producers (main=circ_pump_pressure, secondary=circ_pump_mass), 5) pipeflow, 6) controllers, diameter optimization. Corrects flow directions automatically.

Pandapipes time series simulation for district heating networks including controller updates, temperature control, and result processing.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.update_heat_consumer_qext_controller(net, qext_w_profiles: List[ndarray], time_steps: range, start: int, end: int) → None[source]

Update external heat demand controllers with time-dependent profiles.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with controllers

  • qext_w_profiles (List[np.ndarray]) – List of heat demand profiles for each consumer [W]

  • time_steps (range) – Time steps for simulation period

  • start (int) – Start index for slicing profiles

  • end (int) – End index for slicing profiles

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.update_heat_consumer_temperature_controller(net, min_supply_temperature_heat_consumer: ndarray | List, time_steps: range, start: int, end: int) → None[source]

Update minimum supply temperature controllers with static or time-dependent profiles.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • min_supply_temperature_heat_consumer (Union[np.ndarray, List]) – Min supply temperature profiles [°C]

  • time_steps (range) – Time steps range

  • start (int) – Start index for slicing

  • end (int) – End index for slicing

Note

Handles both scalar (static) and array (dynamic) temperature requirements.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.update_heat_consumer_return_temperature_controller(net, return_temperature_heat_consumer: ndarray | List, time_steps: range, start: int, end: int) → None[source]

Update return temperature controllers with static or dynamic profiles.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • return_temperature_heat_consumer (Union[np.ndarray, List]) – Return temperature profiles [°C]

  • time_steps (range) – Time steps range

  • start (int) – Start index for slicing

  • end (int) – End index for slicing

Note

Automatically converts temperatures from °C to K (adds 273.15).

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.update_secondary_producer_controller(net, secondary_producers: List[Any], time_steps: range, start: int, end: int) → None[source]

Update secondary producer mass flow controllers for time series simulation.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • secondary_producers (List[Any]) – List of producer configs with index and mass_flow

  • time_steps (range) – Time steps range

  • start (int) – Start index for slicing

  • end (int) – End index for slicing

Note

Updates both circ_pump_mass and flow_control controllers for each producer.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.update_heat_generator_supply_temperature_controller(net, supply_temperature: ndarray, time_steps: range, start: int, end: int) → None[source]

Update supply temperature controllers for heat generators with time-dependent profiles.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • supply_temperature (np.ndarray) – Supply temperature profile [°C]

  • time_steps (range) – Time steps range

  • start (int) – Start index for slicing

  • end (int) – End index for slicing

Note

Converts °C to K, updates both circ_pump_pressure and circ_pump_mass controllers.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.create_log_variables(net) → List[Tuple[str, str]][source]

Create list of variables to log during time series simulation.

Parameters:

net (pandapipes.pandapipesNet) – Pandapipes network to analyze for available components

Returns:

List of (table_name, variable_name) tuples to log

Return type:

List[Tuple[str, str]]

Note

Logs junction pressures/temperatures, heat consumer data, and conditionally circ_pump_mass.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.time_series_preprocessing(NetworkGenerationData) → Any[source]

Preprocess time series data including temperature control and COP calculations.

Parameters:

NetworkGenerationData (object) – Network data with simulation parameters and profiles

Returns:

Updated NetworkGenerationData with preprocessed time series

Return type:

Any

Note

Implements static/sliding temperature control, COP calculations for cold networks, applies 2% minimum load, calculates secondary producer mass flows. Converts W to kW.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.thermohydraulic_time_series_net(NetworkGenerationData) → Any[source]

Run thermohydraulic time series simulation with controller updates.

Parameters:

NetworkGenerationData (object) – Network data with preprocessed model and parameters

Returns:

Updated NetworkGenerationData with simulation results and pump operations

Return type:

Any

Note

Runs bidirectional simulation with iter=100, alpha=0.5. Updates all controllers (heat demand, temperatures, secondary producers). Logs junction, heat consumer, and pump data.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.simplified_time_series_net(NetworkGenerationData) → Any[source]

Run simplified time series by scaling design state with building heat demand.

Parameters:

NetworkGenerationData (object) – Network data with design state from initialization

Returns:

Updated NetworkGenerationData with scaled load profiles

Return type:

Any

Note

No pipeflow calculation. Uses design state from net.res_*, scales with demand. Constant temperatures/pressures from design. Losses scaled proportionally. Much faster than thermohydraulic_time_series_net.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.calculate_results(net, net_results: Dict, cp_kJ_kgK: float = 4.2) → Dict[str, Dict[int, Dict[str, ndarray]]][source]

Process and structure raw simulation results from pandapipes.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with component definitions

  • net_results (Dict) – Raw results dictionary from time series simulation

  • cp_kJ_kgK (float) – Specific heat capacity of water [kJ/kg·K], defaults to 4.2

Returns:

Structured results dict: {producer_type: {index: {parameter: time_series}}}

Return type:

Dict[str, Dict[int, Dict[str, np.ndarray]]]

Note

Converts K→°C, calculates heat from mass flow and ΔT. Parameters: mass_flow, flow_pressure, return_pressure, deltap, return_temp, flow_temp, qext_kW. Handles circ_pump_pressure (main) and circ_pump_mass (secondary).

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.save_results_csv(time_steps: ndarray, total_heat_KW: ndarray, strom_wp_kW: ndarray, pump_results: Dict, filename: str) → None[source]

Export simulation results to CSV file with German column headers.

Parameters:

  • time_steps (np.ndarray) – Time step array

  • total_heat_KW (np.ndarray) – Building heat demand time series [kW]

  • strom_wp_kW (np.ndarray) – Heat pump electrical consumption [kW]

  • pump_results (Dict) – Structured pump results from calculate_results

  • filename (str) – Output CSV file path

Note

Semicolon-separated CSV with German column names. Includes Zeit, Gesamtwärmebedarf_Gebäude_kW, pump data (Wärmeerzeugung, Massenstrom, Delta p, temperatures, pressures). UTF-8-sig encoding.

districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation.import_results_csv(filename: str) → Tuple[ndarray, ndarray, ndarray, Dict][source]

Import simulation results from CSV file created by save_results_csv.

Parameters:

filename (str) – Input CSV file path

Returns:

(time_steps, total_heat_KW, strom_wp_kW, pump_results)

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, Dict]

Raises:

  • FileNotFoundError – If CSV file cannot be found

  • pd.errors.ParserError – If CSV format is invalid

  • KeyError – If required columns are missing

Note

Parses German semicolon-separated CSV. Reconstructs pump_results dict structure. Converts dtypes to datetime64/float64. Returns time_steps as datetime, heat/power as kW arrays, pump_results matching calculate_results.

Pandapipes network utility functions for district heating simulation, optimization, and analysis including heat pump calculations, controller creation, and diameter optimization.

author:

Dipl.-Ing. (FH) Jonas Pfeiffer

districtheatingsim.net_simulation_pandapipes.utilities.validate_minimum_pressure_difference(net, target_dp_min_bar: float = 1.0, verbose: bool = True) → Tuple[bool, List[Dict[str, Any]]][source]

Validate that all heat consumers meet minimum pressure difference requirements.

Parameters:

  • net (pandapipes.pandapipesNet) – Network with current pipeflow results

  • target_dp_min_bar (float) – Minimum required pressure difference [bar]

  • verbose (bool) – Print detailed warnings for violations

Returns:

(all_ok, violations) - True if all consumers meet requirements, list of violations

Return type:

Tuple[bool, List[Dict[str, Any]]]

Note

Design validation only - does NOT modify pump parameters like BadPointPressureLiftController.

districtheatingsim.net_simulation_pandapipes.utilities.COP_WP(VLT_L: float | ndarray, QT: float | ndarray, values: ndarray | None = None) → Tuple[ndarray, ndarray][source]

Calculate heat pump Coefficient of Performance (COP) based on supply and source temperatures.

Parameters:

  • VLT_L (Union[float, np.ndarray]) – Supply temperature(s) for heat pump [°C]

  • QT (Union[float, np.ndarray]) – Source temperature(s) for heat pump [°C]

  • values (Optional[np.ndarray]) – Heat pump performance data matrix (default loads from CSV)

Returns:

(COP values [-], adjusted supply temperatures [°C])

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

Note

Technical constraints: max temp lift 75°C (VLT_L ≤ QT + 75°C), min supply temp 35°C.

districtheatingsim.net_simulation_pandapipes.utilities.create_controllers(net, qext_w: ndarray, supply_temperature_heat_generator: float, min_supply_temperature_heat_consumer: ndarray | None, return_temperature_heat_consumer: ndarray, secondary_producers: List[Dict[str, Any]] | None = None)[source]

Create comprehensive control systems for district heating network operation.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network object

  • qext_w (np.ndarray) – External heat demand values for each consumer [W]

  • supply_temperature_heat_generator (float) – Supply temperature setpoint for main generator [°C]

  • min_supply_temperature_heat_consumer (Optional[np.ndarray]) – Minimum required supply temperatures [°C] (None if no constraints)

  • return_temperature_heat_consumer (np.ndarray) – Return temperature setpoints for consumers [°C]

  • secondary_producers (Optional[List[Dict[str, Any]]]) – List of secondary producer objects with index, mass_flow, load_percentage

Returns:

Network with all controllers added

Return type:

pandapipes.pandapipesNet

Note

Controllers include heat consumer demand, temperature regulation, secondary producers, and pressure management.

districtheatingsim.net_simulation_pandapipes.utilities.correct_flow_directions(net) → pandapipesNet[source]

Correct hydraulic flow directions by analyzing velocities and swapping junction connections.

Parameters:

net (pandapipes.pandapipesNet) – Network with potentially incorrect flow directions

Returns:

Network with corrected flow directions

Return type:

pp.pandapipesNet

Note

Identifies pipes with negative velocities and swaps from_junction/to_junction for proper flow representation.

districtheatingsim.net_simulation_pandapipes.utilities.optimize_diameter_parameters(net, element: str = 'pipe', v_max: float = 2.0, dx: float = 0.001, safety_factor: float = 1.5) → pandapipesNet[source]

Optimize network element diameters to meet maximum velocity constraints using continuous adjustment.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network to optimize

  • element (str) – Network element type (default ‘pipe’)

  • v_max (float) – Maximum allowable velocity [m/s]

  • dx (float) – Diameter adjustment step size [m]

  • safety_factor (float) – Safety factor applied to v_max

Returns:

Network with optimized diameters

Return type:

pp.pandapipesNet

Note

Iteratively adjusts diameters with step size dx. Effective v_max = v_max / safety_factor.

districtheatingsim.net_simulation_pandapipes.utilities.init_diameter_types(net, v_max_pipe: float = 1.0, material_filter: str = 'KMR', k: float = 0.1) → pandapipesNet[source]

Initialize pipe diameters using standard pipe types based on velocity requirements.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network to initialize

  • v_max_pipe (float) – Maximum allowable velocity in pipes [m/s]

  • material_filter (str) – Pipe material filter for standard types

  • k (float) – Pipe roughness coefficient [mm]

Returns:

Network with initialized standard pipe types

Return type:

pp.pandapipesNet

Note

Selects closest available standard type from filtered catalog based on required diameter.

districtheatingsim.net_simulation_pandapipes.utilities.optimize_diameter_types(net, v_max: float = 1.0, material_filter: str = 'KMR', k: float = 0.1) → pandapipesNet[source]

Optimize pipe diameters using discrete standard pipe types through iterative adjustment.

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network to optimize

  • v_max (float) – Maximum allowable velocity [m/s]

  • material_filter (str) – Pipe material filter for standard types

  • k (float) – Pipe surface roughness [mm]

Returns:

Network with optimized standard pipe types

Return type:

pp.pandapipesNet

Note

Iteratively adjusts standard types: upsize pipes exceeding v_max, attempt downsizing below v_max.

districtheatingsim.net_simulation_pandapipes.utilities.export_net_geojson(net, filename: str) → dict[source]

Export pandapipes network data to unified GeoJSON format (Version 2.0).

Parameters:

  • net (pandapipes.pandapipesNet) – Pandapipes network with topology, geodata, and component properties

  • filename (str) – Output file path for GeoJSON export

Returns:

Feature counts {‘flow’: int, ‘return’: int, ‘building’: int, ‘generator’: int}

Return type:

dict

Note

Creates single file with flow/return lines, building connections, and generator connections.