Functionality examples

This section contains practical examples demonstrating the usage of DistrictHeatingSim.

Getting Started Examples

Geocoding Example

01_example_geocoding.py

"""
Filename: 01_example_geocoding.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-18
Description: This script runs the geocoding process on a given CSV file containing addresses.
The script imports the `process_data` function from the `geocodingETRS89` module
within the `districtheatingsim` package and executes it with the specified CSV file.
Usage:
    Run this script directly to process the addresses in the "data/data_ETRS89.csv" file.
Functions:
    process_data(file_path: str) -> None
        Processes the geocoding of addresses from the given CSV file.
Example:
    $ python 01_geocoding.py
"""

import pandas as pd
import traceback

from districtheatingsim.geocoding.geocoding import process_data

if __name__ == '__main__':
    try:
        print("Running the geocoding script.")

        example_data_path = "examples/data/data_ETRS89.csv"

        print(f"Using example data from {example_data_path}.")

        example_data = pd.read_csv(example_data_path, sep=';')

        print("Example data:")
        print(example_data)

        process_data(example_data_path)

        geocode_data = pd.read_csv(example_data_path, sep=';')

        print("Geocoded data:")
        print(geocode_data)

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

This example demonstrates how to geocode addresses to coordinates.

Import OSM Data Example

02_example_import_osm_data_geojson.py

"""
Filename: 02_example_import_osm_data_geojson.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-18
Description: This script runs the OSM data import process to download street and building data.
The script imports the `build_query`, `download_data`, and `save_to_file` functions
from the `import_osm_data_geojson` module within the `districtheatingsim.osm` package
and executes them to download and save the OSM data.
Usage:
    Run this script directly to download and save the OSM data.
Functions:
    osm_street_query() -> None
        Downloads and saves OSM street data.
    osm_building_query() -> None
        Downloads and saves OSM building data.
Example:
    $ python 02_import_osm_data_geojson.py

"""

import traceback

from districtheatingsim.osm.import_osm_data_geojson import build_query, download_data, save_to_file

### OSM-Download von Straßendaten ###
def osm_street_query():
    city_name = "Görlitz"
    tags = [
            ("highway", "primary"),
            ("highway", "secondary"),
            ("highway", "tertiary"),
            ("highway", "residential"),
            ("highway", "living_street"),
            {"highway", "service"}
        ]
    element_type = "way"

    query = build_query(city_name, tags, element_type)
    geojson_data = download_data(query, element_type)
    geojson_file_name = "examples\data\osm_street_data.geojson"

    save_to_file(geojson_data, geojson_file_name)
    print("Speichern der OSM-Straßendaten erfolgreich abgeschlossen.")

### OSM-Download von Gebäudedaten ###
def osm_building_query():
    city_name = "Zittau"
    tags = None
    element_type = "building"

    query = build_query(city_name, tags, element_type)
    geojson_data = download_data(query, element_type)
    geojson_file_name = "examples\data\osm_building_data.geojson"

    save_to_file(geojson_data, geojson_file_name)
    print("Speichern der OSM-Gebäudedaten erfolgreich abgeschlossen.")

if __name__ == '__main__':
    try:
        print("Running the OSM data import script.")

        osm_street_query()
        osm_building_query()

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

This example shows how to import OpenStreetMap data in GeoJSON format.

Heat Demand Examples

Simple Heat Requirement

03_example_simple_heat_requirement.py

"""
Filename: 03_example_heat_requirement.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-19
Description: Contains the heat requirement functions necessary to calculate the heat requirement of a building.
Usage:
    Run this script directly to calculate the heat requirement of a building.
Functions:
    VDI4655() -> None
        Calculates the heat requirement according to VDI 4655.
    BDEW() -> None
        Calculates the heat requirement according to BDEW.
Example:
    $ python simple_heat_requirement_test.py

"""

import traceback
import numpy as np
import matplotlib.pyplot as plt

from districtheatingsim.heat_requirement import heat_requirement_BDEW
from districtheatingsim.heat_requirement import heat_requirement_VDI4655

# Berechnung mit VDI 4655 (Referenzlastprofile)
def VDI4655(TRY_filename):
    YEU_heating_kWh = 20000
    YEU_hot_water_kWh = 4000
    YEU_electricity_kWh = 10000
    building_type = "MFH"

    # folgendes wird statisch gesetzt, muss in Zukunft noch in config-Datei ausgelagert werden oder im UI einstellbar sein
    year = 2021 # Jahr, für das die Berechnung durchgeführt wird (für VDI 4655, BDEW)
    holidays = np.array(["2021-01-01", "2021-04-02", "2021-04-05", "2021-05-01", "2021-05-24", "2021-05-13", 
                         "2021-06-03", "2021-10-03", "2021-11-01", "2021-12-25", "2021-12-26"]).astype('datetime64[D]') # Feiertage in Deutschland 2021 (ohne Wochenenden) als datetime64[D]-Array (YYYY-MM-DD) für VDI 4655
    climate_zone = "9"  # Klimazone 9: Deutschland (VDI 4655)
    number_people_household = 2  # Anzahl der Personen im Haushalt (VDI 4655)

    time_15min, total_heat_kW, heating_kW, hot_water_kW, temperature, electricity_kW = heat_requirement_VDI4655.calculate(YEU_heating_kWh, YEU_hot_water_kWh, YEU_electricity_kWh, building_type, number_people_household, year, climate_zone, TRY_filename, holidays)

    print("Ergebnisse VDI 4655")
    print(f"Zeitschritte: {time_15min}")
    print(f"Strombedarf: {electricity_kW}")    
    print(f"Wärmebedarf Heizung: {heating_kW}")
    print(f"Wärmebedarf Warmwasser: {hot_water_kW}")
    print(f"Wärmebedarf Gesamt: {total_heat_kW}")
    print(f"Temperaturen: {temperature}")

    # Plotting
    fig, ax1 = plt.subplots(figsize=(10, 5))

    ax2 = ax1.twinx()
    ax1.plot(time_15min, total_heat_kW, 'g-', label="Gesamt", linewidth=0.5)
    ax1.plot(time_15min, heating_kW, 'b-', label="Heizung", linewidth=0.5)
    ax1.plot(time_15min, hot_water_kW, 'r-', label="Warmwasser", linewidth=0.5)
    ax1.plot(time_15min, electricity_kW, 'm-', label="Strombedarf", linewidth=0.5)
    
    # temperature is hourly, so we need to repeat the values for the 15min intervals
    temperature = np.repeat(temperature, 4)
    ax2.plot(time_15min, temperature, 'k-', label="Außentemperatur", linewidth=0.5)

    ax1.set_xlabel("Zeitschritte")
    ax1.set_ylabel("Wärmebedarf (kW)")
    ax2.set_ylabel("Temperatur (°C)")

    ax1.legend(loc='upper left')
    ax2.legend(loc='upper right')

# Berechnung nach BDEW
def BDEW(TRY_filename):
    YEU_heating_kWh = 20000
    building_type = "HMF"
    subtype = "03"
    real_ww_share = 0.3

    year = 2021

    hourly_intervals, hourly_heat_demand_total_normed, hourly_heat_demand_heating_normed, hourly_heat_demand_warmwater_normed, hourly_temperature = heat_requirement_BDEW.calculate(YEU_heating_kWh, building_type, subtype, TRY_filename, year, real_ww_share)

    print("Ergebnisse BDEW")
    print(f"Zeitschritte: {hourly_intervals}")
    print(f"Wärmebedarf Gesamt: {hourly_heat_demand_total_normed}") 
    print(f"Wärmebedarf Heizung: {hourly_heat_demand_heating_normed}")
    print(f"Wärmebedarf Warmwasser: {hourly_heat_demand_warmwater_normed}")  
    print(f"Temperaturen: {hourly_temperature}")

    # Plotting
    fig, ax1 = plt.subplots(figsize=(10, 5))

    ax2 = ax1.twinx()
    ax1.plot(hourly_intervals, hourly_heat_demand_total_normed, 'g-', label="Gesamt", linewidth=0.5)
    ax1.plot(hourly_intervals, hourly_heat_demand_heating_normed, 'b-', label="Heizung", linewidth=0.5)
    ax1.plot(hourly_intervals, hourly_heat_demand_warmwater_normed, 'r-', label="Warmwasser", linewidth=0.5)
    ax2.plot(hourly_intervals, hourly_temperature, 'k-', label="Außentemperatur", linewidth=0.5)

    ax1.set_xlabel("Zeitschritte")
    ax1.set_ylabel("Wärmebedarf (kW)")
    ax2.set_ylabel("Temperatur (°C)")

    ax1.legend(loc='upper left')
    ax2.legend(loc='upper right')

if __name__ == '__main__':
    try:
        print("Running the heat requirement script.")

        TRY_filename = "src/districtheatingsim/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat"
        
        VDI4655(TRY_filename)
        BDEW(TRY_filename)

        plt.show()

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

Basic heat demand calculation example.

Data-driven Heat Requirement

04_example_data_heat_requirement.py

"""
Filename: 04_example_data_heat_requirement.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-19
Description: Contains the heat requirement functions necessary to calculate the heat requirement of a building.
Usage:
    Run this script directly to calculate the heat requirement of a building.
Functions:
    calculation() -> None
        Calculates the heat requirement according to the given data.
Example:
    $ python 04_example_data_heat_requirement.py

"""

import traceback
import matplotlib.pyplot as plt
import pandas as pd

from districtheatingsim.heat_requirement import heat_requirement_calculation_csv

def calculation(data, TRY, calc_method):
    yearly_time_steps, total_heat_W, heating_heat_W, warmwater_heat_W, max_heat_requirement_W, supply_temperature_curve, return_temperature_curve, hourly_air_temperatures = heat_requirement_calculation_csv.generate_profiles_from_csv(data, TRY, calc_method)
    
    print("Ergebnisse")
    print(f"Jährliche Zeitschritte: {yearly_time_steps}")
    print(f"Gesamtwärmebedarf: {total_heat_W}")
    print(f"Wärmebedarf für Heizung: {heating_heat_W}")
    print(f"Wärmebedarf für Warmwasser: {warmwater_heat_W}")
    print(f"Maximaler Wärmebedarf: {max_heat_requirement_W}")
    print(f"Vorlauftemperaturkurve: {supply_temperature_curve}")
    print(f"Rücklauftemperaturkurve: {return_temperature_curve}")
    print(f"Stündliche Außentemperaturen: {hourly_air_temperatures}")

    # Plotting each element as they are 2-dimensional arrays
    fig, axs = plt.subplots(3, 1, figsize=(10, 15))

    # Plot total heat requirement
    for i in range(total_heat_W.shape[0]):
        axs[0].plot(yearly_time_steps, total_heat_W[i, :], label=f"Gesamtwärmebedarf {i+1}")
    axs[0].set_xlabel("Zeitschritte")
    axs[0].legend()

    # Plot supply and return temperature curves
    for i in range(supply_temperature_curve.shape[0]):
        axs[1].plot(yearly_time_steps, supply_temperature_curve[i, :], label=f"Vorlauftemperatur {i+1}")
        axs[1].plot(yearly_time_steps, return_temperature_curve[i, :], label=f"Rücklauftemperatur {i+1}")
    axs[1].set_xlabel("Zeitschritte")
    axs[1].legend()

    # Plot hourly air temperatures
    axs[2].plot(yearly_time_steps, hourly_air_temperatures, label=f"Außentemperatur")
    axs[2].set_xlabel("Zeitschritte")
    axs[2].legend()

    plt.tight_layout()
    plt.show()

if __name__ == '__main__':
    try:
        print("Running the heat requirement script.")
        
        data = pd.read_csv("examples/data/data_ETRS89.csv", sep=";")
        TRY_filename = "src/districtheatingsim/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat"
        calc_method = "Datensatz"

        print(f"Data: {data}")

        # if data in column "Subtyp" is just one digit, add a leading zero
        data["Subtyp"] = data["Subtyp"].apply(lambda x: f"0{x}" if len(str(x)) == 1 else x)

        calculation(data, TRY_filename, calc_method)

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

Data-driven heat demand analysis example.

Network Design Examples

Network Generation

05_example_net_generation.py

"""
Filename: 05_example_net_generation_test.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-19
Description: Script for testing the net generation functions.
Usage: Run the script to generate a heat network based on the given inputs.
Functions:
    generate_and_export_layers(osm_street_layer_geojson_file_name, data_csv_file_name, coordinates, base_path, algorithm) -> None
        Generates and exports the heat network layers based on the given inputs.
Example:
    $ python 05_example_net_generation_test.py
"""

import geopandas as gpd
import matplotlib.pyplot as plt

from districtheatingsim.geocoding.geocoding import get_coordinates
from districtheatingsim.net_generation.import_and_create_layers import generate_and_export_layers
from districtheatingsim.net_generation.network_geojson_schema import NetworkGeoJSONSchema

### this is an example on how to use the net generation features ###
### Project-specific inputs ###

# Data csv file can be created with the 01_example_geocoding.py script
# therefore the data_csv_input_file_name is the output of the geocoding script
data_csv_file_name = "examples\data\data_ETRS89.csv"

# Street data is imported with the 02_example_import_osm_data_geojson.py script
# therefore the osm_street_layer_geojson_file_name is the output of the osm import script
#osm_street_layer_geojson_file_name = "examples\data\osm_street_data.geojson"
# "examples\data\streets.geojson" is a reduced version of the original data, faster loading
osm_street_layer_geojson_file_name = "examples\data\streets.geojson"

# Coordinates for the heat source is needed to generate the heat network
# The coordinates can be obtained from the geocoding script with an address input

"""
try:
    address = "Brückenstraße 10"
    city = "Görlitz"
    state = "Sachsen"
    country = "Deutschland"
    coordinates = [get_coordinates(f"{address}, {city}, {state}, {country}")]
    print(f"Coordinates: {coordinates}")
except Exception as e:
    print(f"Error getting coordinates: {e}")
    coordinates = [(499829.047722075, 5666164.624415245)]
    print(f"Using default coordinates: {coordinates}")
"""
coordinates = [(499829.047722075, 5666164.624415245)]
print(f"Using default coordinates: {coordinates}")

# Choose the algorithm to generate the network
# mode = "MST"
mode = "Advanced MST"
# mode = "OSMnx Steiner Tree"

base_path = "examples\data\Wärmenetz\Variante 1"
print(f"Starte die Generierung des Wärmenetzes in {base_path} mit dem Algorithmus {mode}...")

generate_and_export_layers(osm_street_layer_geojson_file_name, data_csv_file_name, coordinates, base_path, algorithm=mode)
print("Wärmenetz-Layer erfolgreich erstellt.")

# Load unified GeoJSON and extract layers for visualization

unified_geojson = NetworkGeoJSONSchema.import_from_file(f"{base_path}\Wärmenetz\Wärmenetz.geojson")
vorlauf, rücklauf, hast, erzeuger = NetworkGeoJSONSchema.split_to_legacy_format(unified_geojson)

print("Layer erfolgreich geladen.")

# Plotten der geographischen Daten
fig, ax = plt.subplots(figsize=(10, 10))  # Größe des Plots anpassen
hast.plot(ax=ax, color='green')  # Farbe und weitere Parameter anpassen
rücklauf.plot(ax=ax, color='blue')  # Farbe und weitere Parameter anpassen
vorlauf.plot(ax=ax, color='red')  # Farbe und weitere Parameter anpassen
erzeuger.plot(ax=ax, color='black')  # Farbe und weitere Parameter anpassen
plt.title('Wärmenetz')
plt.show()

Automated network topology generation example.

Simulation Examples

Simple Pandapipes Simulation

06_example_simple_pandapipes.py

"""
Filename: 06_example_simple_pandapipes.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-05-12
Description: Script for testing the pandapipes net simulation functions.
Usage: Run the script to generate a simple pandapipes network.

Example:
    $ python 06_example_simple_pandapipes.py
"""

# needs fixes due to updated functions

import logging

import matplotlib.pyplot as plt
import numpy as np
import traceback
import pandapipes as pp
import pandapipes.plotting as pp_plot

from districtheatingsim.net_simulation_pandapipes.config_plot import config_plot
from districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson import *
from districtheatingsim.net_simulation_pandapipes.utilities import *
from districtheatingsim.heat_requirement import heat_requirement_calculation_csv

# Initialize logging
logging.basicConfig(level=logging.INFO)

def test_heat_consumer_result_extraction():
    print("Running the heat consumer result extraction script.")
    # Create a simple pandapipes network
    net = pp.create_empty_network("net", add_stdtypes=False, fluid="water")

    juncs = pp.create_junctions(
        net,
        nr_junctions=6,
        pn_bar=5,
        tfluid_k=85+273.15,
        system=["flow"] * 3 + ["return"] * 3,
        geodata=[
            (0, 0),    # Junction 0 (Startpunkt)
            (10, 0),   # Junction 1 (Vorlauf)
            (20, 0),   # Junction 2 (Vorlauf)
            (20, -10), # Junction 3 (Rücklauf)
            (10, -10), # Junction 4 (Rücklauf)
            (0, -10),  # Junction 5 (Endpunkt Rücklauf)
        ],
        name=[
            "Junction 0",      # Junction 0
            "Junction 1", # Junction 1
            "Junction 2", # Junction 2
            "Junction 3", # Junction 3
            "Junction 4", # Junction 4
            "Junction 5"         # Junction 5
        ]
    )
    pp.create_pipes_from_parameters(net, juncs[[0, 1, 3, 4]], juncs[[1, 2, 4, 5]], k_mm=0.1, length_km=0.5,
                                            diameter_m=0.1022, system=["flow"] * 2 + ["return"] * 2, alpha_w_per_m2k=0.4,
                                            text_k=273.15, name=[
            "Flow Pipe 1",  # Pipe von Source zu Flow Node 1
            "Flow Pipe 2",  # Pipe von Flow Node 1 zu Flow Node 2
            "Return Pipe 1", # Pipe von Return Node 1 zu Return Node 2
            "Return Pipe 2"  # Pipe von Return Node 2 zu Sink
        ])
    pp.create_circ_pump_const_pressure(net, juncs[-1], juncs[0], 5, 2, 85+273.15, type='auto', name="Pump 1")
    pp.create_heat_consumer(net, juncs[1], juncs[4], treturn_k=60+273.15, qext_w=7500, name="Heat Consumer 1")
    pp.create_heat_consumer(net, juncs[2], juncs[3], treturn_k=77+273.15, qext_w=7500, name="Heat Consumer 2")

    pp.pipeflow(net, mode="bidirectional", iter=100)

    return net

def initialize_test_net(qext_w=np.array([500000, 200000]),
                        return_temperature=np.array([55, 60]),
                        supply_temperature=85, 
                        flow_pressure_pump=4,
                        lift_pressure_pump=1.5,
                        pipetype="KMR 100/250-2v",
                        v_max_m_s=1.5):
    print("Running the test network initialization script.")
    net = pp.create_empty_network(fluid="water")

    k = 0.1 # roughness defaults to 0.1

    suply_temperature_k = supply_temperature + 273.15
    return_temperature_k = return_temperature + 273.15

    # Junctions for pump
    j1 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 1", geodata=(0, 10))
    j2 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 2", geodata=(0, 0))

    # Junctions for connection pipes forward line
    j3 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 3", geodata=(10, 0))
    j4 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 4", geodata=(60, 0))

    # Junctions for heat exchangers
    j5 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 5", geodata=(85, 0))
    j6 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 6", geodata=(85, 10))
    
    # Junctions for connection pipes return line
    j7 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 7", geodata=(60, 10))
    j8 = pp.create_junction(net, pn_bar=1.05, tfluid_k=suply_temperature_k, name="Junction 8", geodata=(10, 10))

    pump1 = pp.create_circ_pump_const_pressure(net, j1, j2, p_flow_bar=flow_pressure_pump, plift_bar=lift_pressure_pump, 
                                               t_flow_k=suply_temperature_k, type="auto", name="pump1")

    pipe1 = pp.create_pipe(net, j2, j3, std_type=pipetype, length_km=0.01, k_mm=k, name="pipe1", sections=5, text_k=283)
    pipe2 = pp.create_pipe(net, j3, j4, std_type=pipetype, length_km=0.05, k_mm=k, name="pipe2", sections=5, text_k=283)
    pipe3 = pp.create_pipe(net, j4, j5, std_type=pipetype, length_km=0.025,k_mm=k, name="pipe3", sections=5, text_k=283)

    heat_cosnumer1 = pp.create_heat_consumer(net, from_junction=j5, to_junction=j6, loss_coefficient=0, qext_w=qext_w[0], 
                                             treturn_k=return_temperature_k[0], name="heat_consumer_1") # treturn_k=t when implemented in function
    

    heat_cosnumer2 = pp.create_heat_consumer(net, from_junction=j4, to_junction=j7, loss_coefficient=0, qext_w=qext_w[1], 
                                             treturn_k=return_temperature_k[1], name="heat_consumer_2") # treturn_k=t when implemented in function
    
    pipe4 = pp.create_pipe(net, j6, j7, std_type=pipetype, length_km=0.25, k_mm=k, name="pipe4", sections=5, text_k=283)
    pipe5 = pp.create_pipe(net, j7, j8, std_type=pipetype, length_km=0.05, k_mm=k, name="pipe5", sections=5, text_k=283)
    pipe6 = pp.create_pipe(net, j8, j1, std_type=pipetype, length_km=0.01, k_mm=k, name="pipe6", sections=5, text_k=283)

    pp.pipeflow(net, mode="bidirectional", iter=100)
    
    net = create_controllers(net, qext_w, supply_temperature, None, return_temperature, None)

    run_control(net, mode="bidirectional", iter=100)

    net = correct_flow_directions(net)
    net = init_diameter_types(net, v_max_pipe=v_max_m_s, material_filter="KMR", k=k)
    net = optimize_diameter_types(net, v_max=v_max_m_s, material_filter="KMR", k=k)

    return net


def initialize_complex_test_net(qext_w=np.array([20000, 15000, 10000, 25000]),
                                return_temperature=np.array([55, 60, 50, 65]),
                                supply_temperature=85,
                                flow_pressure_pump=4,
                                lift_pressure_pump=1.5,
                                pipetype="KMR 100/250-2v",
                                v_max_m_s=1.5):
    print("Running the complex test network initialization script.")
    net = pp.create_empty_network(fluid="water")
    
    k = 0.1  # roughness
    supply_temperature_k = supply_temperature + 273.15  # convert to Kelvin
    return_temperature_k = return_temperature + 273.15  # convert to Kelvin

    # Define junctions
    j1 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Pump Supply", geodata=(0, 0))
    j2 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Main Split Supply", geodata=(10, 0))
    j12 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Main Split Return", geodata=(10, 10))
    j13 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Pump Return", geodata=(0, 10))

    # Additional junctions for new branches
    j3 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer B Supply", geodata=(20, 0))
    j4 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer B Return", geodata=(20, 10))
    j5 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer C Supply", geodata=(30, 0))
    j6 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer C Return", geodata=(30, 10))

    # Pump
    pp.create_circ_pump_const_pressure(net, j13, j1, p_flow_bar=flow_pressure_pump, plift_bar=lift_pressure_pump, 
                                       t_flow_k=supply_temperature_k, type="auto", name="Main Pump")

    # Pipes for supply line
    pp.create_pipe(net, j1, j2, std_type=pipetype, length_km=0.02, k_mm=k, name="Main Pipe Supply")
    pp.create_pipe(net, j2, j3, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch B Pipe Supply")
    pp.create_pipe(net, j3, j5, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch C Pipe Supply")

    # Pipes for return line
    pp.create_pipe(net, j6, j4, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch C Pipe Return")
    pp.create_pipe(net, j4, j12, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch B Pipe Return")
    pp.create_pipe(net, j12, j13, std_type=pipetype, length_km=0.02, k_mm=k, name="Main Pipe Return")

    # Heat consumers
    pp.create_heat_consumer(net, from_junction=j2, to_junction=j12, qext_w=qext_w[0], treturn_k=return_temperature_k[0], name="Consumer A")
    pp.create_heat_consumer(net, from_junction=j3, to_junction=j4, qext_w=qext_w[1], treturn_k=return_temperature_k[1], name="Consumer B")
    pp.create_heat_consumer(net, from_junction=j5, to_junction=j6, qext_w=qext_w[2], treturn_k=return_temperature_k[2], name="Consumer C")

    # Simulate pipe flow
    pp.pipeflow(net, mode="bidirectional", iter=100, alpha=0.6)

    # Placeholder functions for additional processing
    net = create_controllers(net, qext_w, supply_temperature, None, return_temperature, None)

    run_control(net, mode="bidirectional", iter=100)

    net = correct_flow_directions(net)
    net = init_diameter_types(net, v_max_pipe=v_max_m_s, material_filter="KMR", k=k)
    net = optimize_diameter_types(net, v_max=v_max_m_s, material_filter="KMR", k=k)

    return net

def initialize_test_net_two_pumps(qext_w=np.array([50000, 20000]),
                                  return_temperature=np.array([60,55]),
                                  supply_temperature=85,
                                  flow_pressure_pump=4,
                                  lift_pressure_pump=1.5,
                                  pipetype="KMR 100/250-2v",
                                  v_max_m_s=1.5,
                                  mass_pump_mass_flow=0.5):
    print("Running the test network with two pumps initialization script.")
    net = pp.create_empty_network(fluid="water")

    ### get pipe properties
    k = 0.1

    supply_temperature_k = supply_temperature + 273.15  # convert to Kelvin
    return_temperature_k = return_temperature + 273.15  # convert to Kelvin

    # Junctions for pump
    j1 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 1", geodata=(0, 10))
    j2 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 2", geodata=(0, 0))

    # Junctions for connection pipes forward line
    j3 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 3", geodata=(10, 0))
    j4 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 4", geodata=(60, 0))

    # Junctions for heat exchangers
    j5 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 5", geodata=(85, 0))
    j6 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 6", geodata=(85, 10))
    
    # Junctions for connection pipes return line
    j7 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 7", geodata=(60, 10))
    j8 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 8", geodata=(10, 10))

    pump1 = pp.create_circ_pump_const_pressure(net, j1, j2, p_flow_bar=flow_pressure_pump,
                                               plift_bar=lift_pressure_pump, t_flow_k=supply_temperature_k,
                                               type="auto", name="pump1")

    pipe1 = pp.create_pipe(net, j2, j3, std_type=pipetype, length_km=0.01, k_mm=k, name="pipe1", sections=5, text_k=283)
    pipe2 = pp.create_pipe(net, j3, j4, std_type=pipetype, length_km=0.05, k_mm=k, name="pipe2", sections=5, text_k=283)
    pipe3 = pp.create_pipe(net, j4, j5, std_type=pipetype, length_km=0.025, k_mm=k, name="pipe3", sections=5, text_k=283)

    pp.create_heat_consumer(net, from_junction=j5, to_junction=j6, qext_w=qext_w[0], treturn_k=return_temperature_k[0], name="Consumer A")
    pp.create_heat_consumer(net, from_junction=j4, to_junction=j7, qext_w=qext_w[1], treturn_k=return_temperature_k[1], name="Consumer B")
    
    pipe4 = pp.create_pipe(net, j6, j7, std_type=pipetype, length_km=0.25, k_mm=k, name="pipe4", sections=5, text_k=283)
    pipe5 = pp.create_pipe(net, j7, j8, std_type=pipetype, length_km=0.05, k_mm=k, name="pipe5", sections=5, text_k=283)
    pipe6 = pp.create_pipe(net, j8, j1, std_type=pipetype, length_km=0.01, k_mm=k, name="pipe6", sections=5, text_k=283)
    
    ### here comes the part with the additional circ_pump_const_mass_flow ###
    # first of, the junctions
    j9 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 9", geodata=(100, 0))
    j10 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 10", geodata=(100, 10))
    j11 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Junction 11", geodata=(100, 5))

    pipe7 = pp.create_pipe(net, j5, j9, std_type=pipetype, length_km=0.05, k_mm=k, name="pipe7", sections=5, text_k=283)
    pipe8 = pp.create_pipe(net, j10, j6, std_type=pipetype, length_km=0.01, k_mm=k, name="pipe8", sections=5, text_k=283)

    pump2 = pp.create_circ_pump_const_mass_flow(net, j10, j11, p_flow_bar=flow_pressure_pump, mdot_flow_kg_per_s=mass_pump_mass_flow, 
                                                t_flow_k=supply_temperature_k, type="auto", name="pump2")
    
    flow_control_pump2 = pp.create_flow_control(net, j11, j9, controlled_mdot_kg_per_s=mass_pump_mass_flow)

    # Simulate pipe flow
    pp.pipeflow(net, mode="bidirectional", iter=100)

    # Placeholder functions for additional processing
    net = create_controllers(net, qext_w, supply_temperature, None, return_temperature, None)

    run_control(net, mode="bidirectional", iter=100)

    net = correct_flow_directions(net)
    net = init_diameter_types(net, v_max_pipe=v_max_m_s, material_filter="KMR", k=k)
    net = optimize_diameter_types(net, v_max=v_max_m_s, material_filter="KMR", k=k)

    return net

def test_profile_initiation():
    print("Running the test_profile_initiation function.")
        
    data = pd.read_csv("examples/data/data_ETRS89.csv", sep=";")
    TRY_filename = "src/districtheatingsim/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat"
    calc_method = "Datensatz"

    print(f"Data: {data}")

    # if data in column "Subtyp" is just one digit, add a leading zero
    data["Subtyp"] = data["Subtyp"].apply(lambda x: f"0{x}" if len(str(x)) == 1 else x)

    yearly_time_steps, total_heat_W, heating_heat_W, warmwater_heat_W, max_heat_requirement_W, supply_temperature_curve, \
        return_temperature_curve, hourly_air_temperatures = heat_requirement_calculation_csv.generate_profiles_from_csv(data, TRY_filename, calc_method)

    print("Initializing Net:")

    # qext_w is the max heat requirement in W
    qext_w = max_heat_requirement_W*5
    print(f"  → Max heat requirement (qext_w): {qext_w} W")
    # return_temperature is the return temperature in °C, same size as qext_w array
    # np.fill like qext_w with 55
    return_temperature = np.full_like(qext_w, 55)
    print(f"  → Return temperature: {return_temperature} °C")

    net = initialize_test_net(qext_w=qext_w, return_temperature=return_temperature)

    return net

def print_results(net):
    print(net.res_junction)
    print(net.res_pipe)
    print(net.res_heat_consumer)
    print(net.res_circ_pump_pressure)

if __name__ == "__main__":
    try:
        nets = [
            #test_heat_consumer_result_extraction(),
            initialize_test_net(),
            initialize_complex_test_net(),
            initialize_test_net_two_pumps(),
            test_profile_initiation()
            ]
        
        for net in nets:
            print_results(net)

            fig, ax = plt.subplots()
            config_plot(net, ax, show_junctions=True, show_pipes=True, show_heat_consumers=True, show_pump=True, show_plot=False)

        plt.show()

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

Basic pandapipes simulation example.

Time Series Simulation

07_example_timeseries_pandapipes.py

"""
Filename: 07_example_timeseries_pandapipes.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-05-12
Description: Script for testing the pandapipes net simulation functions.
Usage: Run the script to generate a simple pandapipes network.

Example:
    $ python 07_example_timeseries_pandapipes.py
"""

import traceback
import logging
# Initialize logging
logging.basicConfig(level=logging.INFO)

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

import pandapipes as pp
import pandapipes.plotting as pp_plot
from pandapipes.timeseries import run_time_series
from pandapower.timeseries import OutputWriter

from districtheatingsim.net_simulation_pandapipes.config_plot import config_plot
from districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson import *
from districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation import *
from districtheatingsim.net_simulation_pandapipes.utilities import *

from districtheatingsim.net_simulation_pandapipes.config_plot import config_plot

def initialize_test_net(qext_w=np.array([100000, 100000, 100000]),
                        return_temperature=np.array([55, 60, 50]),
                        supply_temperature=85,
                        flow_pressure_pump=4, 
                        lift_pressure_pump=1.5,
                        pipetype="KMR 100/250-2v",
                        v_max_m_s=1.5):
    print("Initializing test network...")
    # Initialize the pandapipes network
    net = pp.create_empty_network(fluid="water")
    
    k = 0.1  # roughness
    supply_temperature_k = supply_temperature + 273.15  # convert to Kelvin
    return_temperature_k = return_temperature + 273.15  # convert to Kelvin

    # Define junctions
    j1 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Pump Supply", geodata=(0, 0))
    j2 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Main Split Supply", geodata=(10, 0))
    j12 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Main Split Return", geodata=(10, 10))
    j13 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Pump Return", geodata=(0, 10))

    # Additional junctions for new branches
    j3 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer B Supply", geodata=(20, 0))
    j4 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer B Return", geodata=(20, 10))
    j5 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer C Supply", geodata=(30, 0))
    j6 = pp.create_junction(net, pn_bar=1.05, tfluid_k=supply_temperature_k, name="Consumer C Return", geodata=(30, 10))

    # Pump
    pp.create_circ_pump_const_pressure(net, j13, j1, p_flow_bar=flow_pressure_pump, plift_bar=lift_pressure_pump, 
                                       t_flow_k=supply_temperature_k, type="auto", name="Main Pump")

    # Pipes for supply line
    pp.create_pipe(net, j1, j2, std_type=pipetype, length_km=0.02, k_mm=k, name="Main Pipe Supply")
    pp.create_pipe(net, j2, j3, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch B Pipe Supply")
    pp.create_pipe(net, j3, j5, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch C Pipe Supply")

    # Pipes for return line
    pp.create_pipe(net, j12, j13, std_type=pipetype, length_km=0.02, k_mm=k, name="Main Pipe Return")
    pp.create_pipe(net, j4, j12, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch B Pipe Return")
    pp.create_pipe(net, j6, j4, std_type=pipetype, length_km=0.03, k_mm=k, name="Branch C Pipe Return")

    # Heat consumers
    pp.create_heat_consumer(net, from_junction=j2, to_junction=j12, qext_w=qext_w[0], treturn_k=return_temperature_k[0], name="Consumer A")
    pp.create_heat_consumer(net, from_junction=j3, to_junction=j4, qext_w=qext_w[1], treturn_k=return_temperature_k[1], name="Consumer B")
    pp.create_heat_consumer(net, from_junction=j5, to_junction=j6, qext_w=qext_w[2], treturn_k=return_temperature_k[2], name="Consumer C")

    # Simulate pipe flow
    pp.pipeflow(net, mode="bidirectional", iter=100)

    # Placeholder functions for additional processing
    net = create_controllers(net, qext_w, supply_temperature, None, return_temperature, None)

    run_control(net, mode="bidirectional", iter=100)

    net = correct_flow_directions(net)
    net = init_diameter_types(net, v_max_pipe=v_max_m_s, material_filter="KMR", k=k)
    net = optimize_diameter_types(net, v_max=v_max_m_s, material_filter="KMR", k=k)

    return net


def timeseries_test(net):
    print("Running time series test...")
    start = 0
    end = 8 # 8760 hours in a year

    # time steps with start and end
    time_steps = np.arange(start, end, 1)	# time steps in hours

    # yearly time steps with dates beginning at 01.01.2021 00:00:00
    yearly_time_steps = pd.date_range(start="2021-01-01 00:00:00", periods=end, freq="h")

    # np.random.seed() is used to make the random numbers predictable
    np.random.seed(0)
    # Generate more realistic heat demand profiles with smaller variations
    # Instead of 0-100kW, use 30-70kW to avoid extreme controller adjustments
    base_demand = np.array([50000, 60000, 40000])  # Base demand per consumer in W
    variation = 0.3  # ±30% variation
    
    qext_w_profiles = np.zeros((3, end))
    for i in range(3):
        # Generate random variations around base demand
        qext_w_profiles[i, :] = base_demand[i] * (1 + variation * (2 * np.random.random(end) - 1))
    
    print(f"qext_w_profiles shape: {qext_w_profiles.shape}")
    print(f"qext_w_profiles min: {np.min(qext_w_profiles):.0f} W, max: {np.max(qext_w_profiles):.0f} W")

    return_temperature = np.linspace(50, 60, end).reshape(1, -1).repeat(3, axis=0)  # Generate time-dependent return temperatures as a linear gradient
    if qext_w_profiles.shape != return_temperature.shape:
        raise ValueError("The shape of return_temperature_profiles must match the shape of qext_w_profiles.")
    supply_temperature = np.full_like(time_steps, 85)  # Supply temperature is constant
    print(f"supply_temperature: {supply_temperature}") # Structure is one-dimensional array with shape (n_time_steps,)
    
    print(net.controller)

    update_heat_consumer_qext_controller(net, qext_w_profiles, time_steps, start, end)
    update_heat_consumer_return_temperature_controller(net, return_temperature, time_steps, start, end)
    update_heat_generator_supply_temperature_controller(net, supply_temperature, time_steps, start, end)

    print(net)
    print(net.controller)
    print(net.heat_consumer)
    print(net.circ_pump_pressure)
    #print(net.res_controller)
    print(net.res_heat_consumer)
    print(net.res_circ_pump_pressure)

    # Log variables and run time series calculation
    log_variables = create_log_variables(net)
    ow = OutputWriter(net, time_steps, output_path=None, log_variables=log_variables)

    run_time_series.run_timeseries(net, time_steps, mode="bidirectional", iter=100, alpha=0.6)

    return yearly_time_steps, net, ow.np_results

def print_results(net):
    print(net)
    print(net.junction)
    print(net.pipe)
    print(net.heat_consumer)
    print(net.circ_pump_pressure)

    print(net.res_junction)
    print(net.res_pipe)
    print(net.res_heat_consumer)
    print(net.res_circ_pump_pressure)

def plot_time_series_results(yearly_time_steps, np_results, net):
    """
    Plot time series results for junction pressures, temperatures, and heat consumer data.
    
    Parameters
    ----------
    yearly_time_steps : pd.DatetimeIndex
        Time steps with dates
    np_results : dict
        Results dictionary from OutputWriter
    net : pandapipes.pandapipesNet
        The network object with junction names
    """
    print("\n" + "="*70)
    print("TIME SERIES RESULTS ANALYSIS")
    print("="*70)
    
    # Extract junction pressures
    if 'res_junction.p_bar' in np_results:
        p_bar = np_results['res_junction.p_bar']
        print(f"\nJunction Pressures Shape: {p_bar.shape}")
        print(f"Time steps: {p_bar.shape[0]}, Junctions: {p_bar.shape[1]}")
        
        # Plot junction pressures over time
        fig, ax = plt.subplots(figsize=(14, 6))
        for i in range(p_bar.shape[1]):
            junction_name = net.junction.at[i, 'name'] if 'name' in net.junction.columns else f"Junction {i}"
            ax.plot(yearly_time_steps, p_bar[:, i], label=junction_name, linewidth=1.5)
        
        ax.set_xlabel('Zeit', fontsize=12)
        ax.set_ylabel('Druck [bar]', fontsize=12)
        ax.set_title('Knotendruck im Zeitverlauf', fontsize=14, fontweight='bold')
        ax.legend(loc='best', fontsize=9)
        ax.grid(True, alpha=0.3)
        plt.tight_layout()
        plt.show()
        
        # Print statistics
        print("\nKnotendruck Statistik:")
        for i in range(p_bar.shape[1]):
            junction_name = net.junction.at[i, 'name'] if 'name' in net.junction.columns else f"Junction {i}"
            print(f"  {junction_name}:")
            print(f"    Min: {np.min(p_bar[:, i]):.3f} bar")
            print(f"    Max: {np.max(p_bar[:, i]):.3f} bar")
            print(f"    Mittelwert: {np.mean(p_bar[:, i]):.3f} bar")
    
    # Extract junction temperatures
    if 'res_junction.t_k' in np_results:
        t_k = np_results['res_junction.t_k']
        t_c = t_k - 273.15  # Convert to Celsius
        
        # Plot junction temperatures over time
        fig, ax = plt.subplots(figsize=(14, 6))
        for i in range(t_c.shape[1]):
            junction_name = net.junction.at[i, 'name'] if 'name' in net.junction.columns else f"Junction {i}"
            ax.plot(yearly_time_steps, t_c[:, i], label=junction_name, linewidth=1.5)
        
        ax.set_xlabel('Zeit', fontsize=12)
        ax.set_ylabel('Temperatur [°C]', fontsize=12)
        ax.set_title('Knotentemperatur im Zeitverlauf', fontsize=14, fontweight='bold')
        ax.legend(loc='best', fontsize=9)
        ax.grid(True, alpha=0.3)
        plt.tight_layout()
        plt.show()
    
    # Extract heat consumer results
    if 'res_heat_consumer.qext_w' in np_results:
        qext_w = np_results['res_heat_consumer.qext_w']
        qext_kw = qext_w / 1000  # Convert to kW
        
        # Plot heat demand over time
        fig, ax = plt.subplots(figsize=(14, 6))
        for i in range(qext_kw.shape[1]):
            consumer_name = net.heat_consumer.at[i, 'name'] if 'name' in net.heat_consumer.columns else f"Consumer {i}"
            ax.plot(yearly_time_steps, qext_kw[:, i], label=consumer_name, linewidth=1.5)
        
        # Plot total heat demand
        total_qext_kw = np.sum(qext_kw, axis=1)
        ax.plot(yearly_time_steps, total_qext_kw, label='Gesamt', linewidth=2.5, 
                color='black', linestyle='--')
        
        ax.set_xlabel('Zeit', fontsize=12)
        ax.set_ylabel('Wärmebedarf [kW]', fontsize=12)
        ax.set_title('Wärmebedarf im Zeitverlauf', fontsize=14, fontweight='bold')
        ax.legend(loc='best', fontsize=9)
        ax.grid(True, alpha=0.3)
        plt.tight_layout()
        plt.show()
        
        # Print statistics
        print("\nWärmebedarf Statistik:")
        for i in range(qext_kw.shape[1]):
            consumer_name = net.heat_consumer.at[i, 'name'] if 'name' in net.heat_consumer.columns else f"Consumer {i}"
            print(f"  {consumer_name}:")
            print(f"    Min: {np.min(qext_kw[:, i]):.1f} kW")
            print(f"    Max: {np.max(qext_kw[:, i]):.1f} kW")
            print(f"    Mittelwert: {np.mean(qext_kw[:, i]):.1f} kW")
        print(f"  Gesamt:")
        print(f"    Min: {np.min(total_qext_kw):.1f} kW")
        print(f"    Max: {np.max(total_qext_kw):.1f} kW")
        print(f"    Mittelwert: {np.mean(total_qext_kw):.1f} kW")
    
    # Print available result keys
    print("\nVerfügbare Ergebnis-Variablen:")
    for key in sorted(np_results.keys()):
        shape = np_results[key].shape if hasattr(np_results[key], 'shape') else 'N/A'
        print(f"  {key}: {shape}")
    
    print("="*70)


if __name__ == "__main__":
    try:
        net = initialize_test_net()

        fig1, ax1 = plt.subplots()
        
        config_plot(net=net, ax=ax1, show_junctions=True, show_pipes=True, 
                    show_heat_consumers=True, show_pump=True, show_plot=False, 
                    show_basemap=False, map_type="OSM")

        print_results(net)

        print("Test network initialized successfully."
              " Running time series simulation..." )
        

        yearly_time_steps, net, np_results = timeseries_test(net)

        print_results(net)

        print("\nAnalyzing time series results...")
        plot_time_series_results(yearly_time_steps, np_results, net)

        fig2, ax2 = plt.subplots()
        
        config_plot(net=net, ax=ax2, show_junctions=True, show_pipes=True, 
                    show_heat_consumers=True, show_pump=True, show_plot=False, 
                    show_basemap=False, map_type="OSM")

        plt.show()

    except Exception as e:
        print("An error occurred:")
        print(traceback.format_exc())
        raise e

Time series simulation with pandapipes.

Complex Time Series Analysis

08_example_complex_pandapipes_timeseries.py

"""
Filename: 08_example_complex_pandapipes_timeseries.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-01-12
Description: Script for testing the pandapipes net simulation functions. Aims to simulate a district heating network using GeoJSON files for the network layout and a JSON file for the building load profile. The script includes functions to create and initialize the network, perform time series calculations, and plot the results.
Usage: Run the script in the main directory of the repository.

Updated to work with the current NetworkGenerationData class structure.
"""

import matplotlib.pyplot as plt
import numpy as np

from districtheatingsim.net_simulation_pandapipes.pp_net_initialisation_geojson import *
from districtheatingsim.net_simulation_pandapipes.pp_net_time_series_simulation import *
from districtheatingsim.net_simulation_pandapipes.utilities import *

from districtheatingsim.net_simulation_pandapipes.config_plot import config_plot

from districtheatingsim.net_simulation_pandapipes.NetworkDataClass import NetworkGenerationData, SecondaryProducer

def plot(net, time_steps, qext_kW, strom_kW):
    """
    Plots the network data.

    Args:
        time_steps: Array of time steps.
        qext_kW: Array of external heat demand in kW.
        strom_kW: Array of power demand in kW.
    """
    fig, ax1 = plt.subplots()

    if np.sum(strom_kW) == 0:
        ax1.plot(time_steps, qext_kW, 'b-', label="Gesamtheizlast Gebäude in kW")

    if np.sum(strom_kW) > 0:
        ax1.plot(time_steps, qext_kW+strom_kW, 'b-', label="Gesamtheizlast Gebäude in kW")
        ax1.plot(time_steps, strom_kW, 'g-', label="Gesamtstrombedarf Wärmepumpen Gebäude in kW")

    ax1.set_xlabel("Zeit")
    ax1.set_ylabel("Leistung in kW", color='b')
    ax1.tick_params('y', colors='b')
    ax1.legend(loc='upper center')
    ax1.grid()

    fig, ax2 = plt.subplots()

    config_plot(net, ax2, show_junctions=True, show_pipes=True, show_heat_consumers=True, show_basemap=False, show_plot=True)

def print_net_results(net):
    print("Netzdaten:")
    print(f"Junctions: {net.junction}")
    print(f"Results Junctions: {net.res_junction}")
    print(f"Pipes: {net.pipe}")
    print(f"Results Pipes: {net.res_pipe}")
    print(f"Heat Consumers: {net.heat_consumer}")
    print(f"Results Heat Consumers: {net.res_heat_consumer}")
    print(f"Circ Pump Pressure: {net.circ_pump_pressure}")
    print(f"Results Circ Pump Pressure: {net.res_circ_pump_pressure}")
    if 'circ_pump_mass' in net:
        print(f"Circ Pump Mass: {net.circ_pump_mass}")
        print(f"Results Circ Pump Mass: {net.res_circ_pump_mass}")

if __name__ == "__main__":
    from districtheatingsim.net_generation.network_geojson_schema import NetworkGeoJSONSchema
    import tempfile
    
    # File paths - Load unified format
    unified_path = "examples/data/Wärmenetz/Variante 2/Wärmenetz.geojson"
    
    # Extract layers from unified format
    unified_geojson = NetworkGeoJSONSchema.import_from_file(unified_path)
    vorlauf_gdf, ruecklauf_gdf, hast_gdf, erzeuger_gdf = NetworkGeoJSONSchema.split_to_legacy_format(unified_geojson)
    
    # Save to temporary files for compatibility
    temp_dir = tempfile.mkdtemp()
    vorlauf_path = os.path.join(temp_dir, "vorlauf.geojson")
    ruecklauf_path = os.path.join(temp_dir, "ruecklauf.geojson")
    hast_path = os.path.join(temp_dir, "hast.geojson")
    erzeugeranlagen_path = os.path.join(temp_dir, "erzeuger.geojson")
    
    vorlauf_gdf.to_file(vorlauf_path, driver="GeoJSON")
    ruecklauf_gdf.to_file(ruecklauf_path, driver="GeoJSON")
    hast_gdf.to_file(hast_path, driver="GeoJSON")
    erzeuger_gdf.to_file(erzeugeranlagen_path, driver="GeoJSON")
    json_path = "examples/data/Gebäude Lastgang.json"
    
    # Optional external data files
    TRY_filename = "examples/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat"
    COP_filename = "examples/data/COP/Kennlinien WP.csv"

    # Network configuration parameters
    netconfiguration = "Niedertemperaturnetz"  # or "kaltes Netz"
    supply_temperature_control = "Statisch"  # or "Gleitend"
    
    # Temperature control parameters
    max_supply_temperature_heat_generator = 85.0  # °C
    min_supply_temperature_heat_generator = 70.0  # °C (for sliding control)
    max_air_temperature_heat_generator = 15.0     # °C
    min_air_temperature_heat_generator = -12.0    # °C
    
    # Pump parameters
    flow_pressure_pump = 4.0      # bar
    lift_pressure_pump = 1.5      # bar
    
    # Building temperature parameters
    min_supply_temperature_building_checked = False
    min_supply_temperature_building = None # 60.0  # °C
    fixed_return_temperature_heat_consumer_checked = False
    fixed_return_temperature_heat_consumer = None # 50.0  # °C
    dT_RL = 5.0  # K - temperature difference between heat consumer and net due to heat exchanger
    building_temperature_checked = False  # flag indicating if building temperatures are considered
    
    # Pipe parameters
    pipetype = "KMR 100/250-2v"  # type of pipe
    diameter_optimization_pipe_checked = True  # flag indicating if diameter optimization is checked
    max_velocity_pipe = 2.0  # m/s - maximum flow velocity in the pipes
    material_filter_pipe = "KMR"  # material filter for pipes
    k_mm_pipe = 0.1  # mm - roughness of the pipe
    
    # Producer configuration
    main_producer_location_index = 0  # index of the main producer location
    #secondary_producers = []  # list of secondary producers, can be empty or contain multiple producers
    secondary_producers = [
        SecondaryProducer(index=1, load_percentage=5.0)  # secondary producer with 5% load
    ]
    
    # Import type
    import_type = "geoJSON"  # currently only geoJSON

    # Create NetworkGenerationData object with all required parameters
    network_data = NetworkGenerationData(
        # Required input data paths
        import_type=import_type,
        flow_line_path=vorlauf_path,
        return_line_path=ruecklauf_path,
        heat_consumer_path=hast_path,
        heat_generator_path=erzeugeranlagen_path,
        heat_demand_json_path=json_path,
        
        # Network configuration data
        netconfiguration=netconfiguration,
        supply_temperature_control=supply_temperature_control,
        max_supply_temperature_heat_generator=max_supply_temperature_heat_generator,
        min_supply_temperature_heat_generator=min_supply_temperature_heat_generator,
        max_air_temperature_heat_generator=max_air_temperature_heat_generator,
        min_air_temperature_heat_generator=min_air_temperature_heat_generator,
        flow_pressure_pump=flow_pressure_pump,
        lift_pressure_pump=lift_pressure_pump,
        min_supply_temperature_building_checked=min_supply_temperature_building_checked,
        min_supply_temperature_building=min_supply_temperature_building,
        fixed_return_temperature_heat_consumer_checked=fixed_return_temperature_heat_consumer_checked,
        fixed_return_temperature_heat_consumer=fixed_return_temperature_heat_consumer,
        dT_RL=dT_RL,
        building_temperature_checked=building_temperature_checked,
        pipetype=pipetype,
        
        # Optimization variables
        diameter_optimization_pipe_checked=diameter_optimization_pipe_checked,
        max_velocity_pipe=max_velocity_pipe,
        material_filter_pipe=material_filter_pipe,
        k_mm_pipe=k_mm_pipe,
        
        # Producer configuration
        main_producer_location_index=main_producer_location_index,
        secondary_producers=secondary_producers,
        
        # Optional external data files
        COP_filename=COP_filename,
        TRY_filename=TRY_filename
    )

    # Initialize network from GeoJSON data
    network_data = initialize_geojson(network_data)      

    # Optimize pipe diameters if requested
    if network_data.diameter_optimization_pipe_checked:
        network_data.net = optimize_diameter_types(
            network_data.net, 
            network_data.max_velocity_pipe, 
            network_data.material_filter_pipe, 
            network_data.k_mm_pipe
        )
    
    # Set simulation time range
    network_data.start_time_step = 0
    network_data.end_time_step = 100
    
    # Preprocess time series data
    network_data = time_series_preprocessing(network_data)
    
    # Run thermohydraulic time series simulation
    network_data = thermohydraulic_time_series_net(network_data)

    print("Simulation erfolgreich abgeschlossen.")

    # Print network results
    print_net_results(network_data.net)
    
    # Calculate and display key performance indicators
    results = network_data.calculate_results()
    print("\nKennzahlen:")
    for key, value in results.items():
        if value is not None:
            if isinstance(value, float):
                print(f"{key}: {value:.2f}")
            else:
                print(f"{key}: {value}")
        else:
            print(f"{key}: Nicht verfügbar")
    
    # Prepare plot data
    network_data.prepare_plot_data()
    
    # Plot results
    plot(network_data.net, 
         network_data.yearly_time_steps[network_data.start_time_step:network_data.end_time_step], 
         network_data.waerme_ges_kW[network_data.start_time_step:network_data.end_time_step], 
         network_data.strombedarf_ges_kW[network_data.start_time_step:network_data.end_time_step])
    
    # Show additional plots using prepared plot data
    if network_data.plot_data:
        print("\nVerfügbare Plot-Daten:")
        for key in network_data.plot_data.keys():
            print(f"  - {key}")
        
        # Example: Plot heat demand over time
        heat_demand_data = network_data.plot_data["Gesamtwärmebedarf Wärmeübertrager"]
        fig, ax = plt.subplots(figsize=(12, 6))
        ax.plot(heat_demand_data['time'], heat_demand_data['data'], 'b-')
        ax.set_xlabel('Zeit')
        ax.set_ylabel(heat_demand_data['label'])
        ax.set_title('Wärmebedarf über Zeit')
        ax.grid(True)
        plt.show()

    plt.show()

Complex time series analysis example.

Energy Systems Examples

Heat Generators

09_example_heat_generators.py

"""
Filename: 09_example_heat_generators.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-07-12
Description: Script for testing the heat generator functions.

# Not up-to-date: This script is not up-to-date with the latest version of all heat generator classes.
"""

from districtheatingsim.heat_generators.solar_thermal import SolarThermal
from districtheatingsim.heat_generators.gas_boiler import GasBoiler
from districtheatingsim.heat_generators.biomass_boiler import BiomassBoiler
from districtheatingsim.heat_generators.chp import CHP
from districtheatingsim.heat_generators.waste_heat_pump import WasteHeatPump
from districtheatingsim.heat_generators.river_heat_pump import RiverHeatPump
from districtheatingsim.heat_generators.geothermal_heat_pump import Geothermal
from districtheatingsim.heat_generators.power_to_heat import PowerToHeat
from districtheatingsim.utilities.test_reference_year import import_TRY

import numpy as np

import matplotlib.pyplot as plt

def test_gas_boiler(Last_L, duration, economic_parameters, gBoiler=GasBoiler(name="Gas_Boiler_1",
                                                                             thermal_capacity_kW=200,
                                                                             spez_Investitionskosten=30, 
                                                                             Nutzungsgrad=0.9)):
    results = gBoiler.calculate(economic_parameters, duration, Last_L)
    
    print(f"Wärmemenge Gaskessel: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung Gaskessel: {results['Wärmeleistung_L']} kW")
    print(f"Brennstoffbedarf Gaskessel: {results['Brennstoffbedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten Gaskessel: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Gaskessel: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Gaskessel: {results['primärenergie']:.2f} MWh")

def test_power_to_heat(Last_L, duration, economic_parameters, PTH=PowerToHeat(name="PowerToHeat", 
                                                                              thermal_capacity_kW=1000, 
                                                                              spez_Investitionskosten=30, 
                                                                              Nutzungsgrad=0.98)):
    results = PTH.calculate(economic_parameters, duration, Last_L)

    print(f"Wärmemenge Power-to-Heat: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung Power-to-Heat: {results['Wärmeleistung_L']} kW")
    print(f"Strombedarf Power-to-Heat: {results['Strombedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten Power-to-Heat: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Power-to-Heat: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Power-to-Heat: {results['primärenergie']:.2f} MWh")

def test_biomass_boiler(Last_L, duartion, economic_parameters, bBoiler=BiomassBoiler(name="Biomasss_Boiler_1", thermal_capacity_kW=200, Größe_Holzlager=40, spez_Investitionskosten=200, spez_Investitionskosten_Holzlager=400, 
                                           Nutzungsgrad_BMK=0.8, min_Teillast=0.3, speicher_aktiv=False, Speicher_Volumen=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, 
                                           min_fill=0.2, max_fill=0.8, spez_Investitionskosten_Speicher=750, active=True, opt_BMK_min=0, opt_BMK_max=1000, opt_Speicher_min=0, 
                                           opt_Speicher_max=100)):
    results = bBoiler.calculate(economic_parameters, duartion, Last_L)
    
    print(f"Wärmemenge Biomassekessel: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung Biomassekessel: {results['Wärmeleistung_L']} kW")
    print(f"Brennstoffbedarf Biomassekessel: {results['Brennstoffbedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten Biomassekessel: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Biomassekessel: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Biomassekessel: {results['primärenergie']:.2f} MWh")
    print(f"Anzahl Starts Biomassekessel: {results['Anzahl_Starts']}")
    print(f"Betriebsstunden Biomassekessel: {results['Betriebsstunden']} h")
    print(f"Betriebsstunden pro Start Biomassekessel: {results['Betriebsstunden_pro_Start']:.2f} h")

def test_biomass_boiler_storage(Last_L, 
                                duration, 
                                economic_parameters, 
                                bBoiler=BiomassBoiler(name="Biomasss_Boiler_1", thermal_capacity_kW=200, 
                                                                     Größe_Holzlager=40, spez_Investitionskosten=200, 
                                                                     spez_Investitionskosten_Holzlager=400, 
                                                                     Nutzungsgrad_BMK=0.8, min_Teillast=0.3, 
                                                                     speicher_aktiv=True, Speicher_Volumen=20, 
                                                                     T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, 
                                                                     min_fill=0.2, max_fill=0.8, 
                                                                     spez_Investitionskosten_Speicher=750, active=True, 
                                                                     opt_BMK_min=0, opt_BMK_max=1000, opt_Speicher_min=0, 
                                                                     opt_Speicher_max=100)):

    results = bBoiler.calculate(economic_parameters, duration, Last_L)
    
    print(f"Wärmemenge Biomassekessel mit Speicher: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung Biomassekessel mit Speicher: {results['Wärmeleistung_L']} kW")
    print(f"Wärmeleistung Speicher Biomassekessel: {results['Wärmeleistung_Speicher_L']} kW")
    print(f"Brennstoffbedarf Biomassekessel mit Speicher: {results['Brennstoffbedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten Biomassekessel mit Speicher: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Biomassekessel mit Speicher: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Biomassekessel mit Speicher: {results['primärenergie']:.2f} MWh")
    print(f"Anzahl Starts Biomassekessel mit Speicher: {results['Anzahl_Starts']}")
    print(f"Betriebsstunden Biomassekessel mit Speicher: {results['Betriebsstunden']} h")
    print(f"Betriebsstunden pro Start Biomassekessel mit Speicher: {results['Betriebsstunden_pro_Start']:.2f} h")

def test_chp(Last_L, duration, economic_parameters, chp=CHP(name="BHKW", th_Leistung_kW=100, spez_Investitionskosten_GBHKW=1500, spez_Investitionskosten_HBHKW=1850, el_Wirkungsgrad=0.33, 
                                                                KWK_Wirkungsgrad=0.9, min_Teillast=0.7, speicher_aktiv=False, Speicher_Volumen_BHKW=20, T_vorlauf=90, T_ruecklauf=60, 
                                                                initial_fill=0.0, min_fill=0.2, max_fill=0.8, spez_Investitionskosten_Speicher=750, active=True, opt_BHKW_min=0, opt_BHKW_max=1000, 
                                                                opt_BHKW_Speicher_min=0, opt_BHKW_Speicher_max=100)):

    results = chp.calculate(economic_parameters, duration, Last_L)

    print(f"Wärmemenge BHKW: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung BHKW: {results['Wärmeleistung_L']} kW")
    print(f"Brennstoffbedarf BHKW: {results['Brennstoffbedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten BHKW: {results['WGK']:.2f} €/MWh")
    print(f"Strommenge BHKW: {results['Strommenge']:.2f} MWh")
    print(f"Stromleistung BHKW: {results['el_Leistung_L']} kW")
    print(f"Anzahl Starts BHKW: {results['Anzahl_Starts']}")
    print(f"Betriebsstunden BHKW: {results['Betriebsstunden']} h")
    print(f"Betriebsstunden pro Start BHKW: {results['Betriebsstunden_pro_Start']:.2f} h")
    print(f"spezifische CO2-Emissionen BHKW: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf BHKW: {results['primärenergie']:.2f} MWh")

def test_chp_storage(Last_L, duration, economic_parameters, chp=CHP(name="BHKW", th_Leistung_kW=100, spez_Investitionskosten_GBHKW=1500, spez_Investitionskosten_HBHKW=1850, el_Wirkungsgrad=0.33, 
                                                                        KWK_Wirkungsgrad=0.9, min_Teillast=0.7, speicher_aktiv=True, Speicher_Volumen_BHKW=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, 
                                                                        min_fill=0.2, max_fill=0.8, spez_Investitionskosten_Speicher=750, active=True, opt_BHKW_min=0, opt_BHKW_max=1000, 
                                                                        opt_BHKW_Speicher_min=0, opt_BHKW_Speicher_max=100)):

    results = chp.calculate(economic_parameters, duration, Last_L)
    
    print(f"Wärmemenge BHKW mit Speicher: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung BHKW mit Speicher: {results['Wärmeleistung_L']} kW")
    print(f"Wärmeleistung Speicher BHKW: {results['Wärmeleistung_Speicher_L']} kW")
    print(f"Brennstoffbedarf BHKW mit Speicher: {results['Brennstoffbedarf']:.2f} MWh")
    print(f"Wärmegestehungskosten BHKW mit Speicher: {results['WGK']:.2f} €/MWh")
    print(f"Strommenge BHKW mit Speicher: {results['Strommenge']:.2f} MWh")
    print(f"Stromleistung BHKW mit Speicher: {results['el_Leistung_L']} kW")
    print(f"Anzahl Starts BHKW mit Speicher: {results['Anzahl_Starts']}")
    print(f"Betriebsstunden BHKW mit Speicher: {results['Betriebsstunden']} h")
    print(f"Betriebsstunden pro Start BHKW mit Speicher: {results['Betriebsstunden_pro_Start']:.2f} h")
    print(f"spezifische CO2-Emissionen BHKW mit Speicher: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf BHKW mit Speicher: {results['primärenergie']:.2f} MWh")

def test_waste_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, wasteHeatPump=WasteHeatPump(name="Abwärmepumpe", Kühlleistung_Abwärme=50, Temperatur_Abwärme=30, spez_Investitionskosten_Abwärme=500, spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)):

    results = wasteHeatPump.calculate(economic_parameters, duration, Last_L, VLT_L=VLT_L, COP_data=COP_data)
    
    print(f"Wärmemenge Abwärme-WP: {results['Wärmemenge']:.2f} MWh")
    print(f"Strombedarf Abwärme-WP: {results['Strombedarf']:.2f} MWh")
    print(f"Wärmeleistung Abwärme-WP: {results['Wärmeleistung_L']} kW")
    print(f"elektrische Leistung Abwärme-WP: {results['el_Leistung_L']} kW")
    print(f"Wärmegestehungskosten Abwärme-WP: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Abwärme-WP: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Abwärme-WP: {results['primärenergie']:.2f} MWh")

def test_river_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, riverHeatPump=RiverHeatPump(name="Flusswärmepumpe", Wärmeleistung_FW_WP=200, Temperatur_FW_WP=10, dT=0, spez_Investitionskosten_Flusswasser=1000, spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)):   
    
    results = riverHeatPump.calculate(economic_parameters, duration, Last_L, VLT_L=VLT_L, COP_data=COP_data)
    
    print(f"Wärmemenge Fluss-WP: {results['Wärmemenge']:.2f} MWh")
    print(f"Strombedarf Fluss-WP: {results['Strombedarf']:.2f} MWh")
    print(f"Wärmeleistung Fluss-WP: {results['Wärmeleistung_L']} kW")
    print(f"elektrische Leistung Fluss-WP: {results['el_Leistung_L']} kW")
    print(f"Wärmegestehungskosten Fluss-WP: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Fluss-WP: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Fluss-WP: {results['primärenergie']:.2f} MWh")

def test_geothermal_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, geothermalHeatPump=Geothermal(name="Geothermie", Fläche=200, Bohrtiefe=100, Temperatur_Geothermie=10, spez_Bohrkosten=100, spez_Entzugsleistung=50, Vollbenutzungsstunden=2400, Abstand_Sonden=10, spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)):
    
    results = geothermalHeatPump.calculate(economic_parameters, duration, Last_L, VLT_L=VLT_L, COP_data=COP_data)

    print(f"Wärmemenge Geothermie-WP: {results['Wärmemenge']:.2f} MWh")
    print(f"Strombedarf Geothermie-WP: {results['Strombedarf']:.2f} MWh")
    print(f"Wärmeleistung Geothermie-WP: {results['Wärmeleistung_L']} kW")
    print(f"elektrische Leistung Geothermie-WP: {results['el_Leistung_L']} kW")
    print(f"Wärmegestehungskosten Geothermie-WP: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Geothermie-WP: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Geothermie-WP: {results['primärenergie']:.2f} MWh")

def test_solar_thermal(Last_L, duration, economic_parameters, VLT_L, RLT_L, TRY_data, time_steps, solarThermal=SolarThermal(name="Solarthermie", bruttofläche_STA=200, vs=20, Typ="Vakuumröhrenkollektor", 
                                                                                                            kosten_speicher_spez=750, kosten_fk_spez=430, kosten_vrk_spez=590, Tsmax=90, 
                                                                                                            Longitude=-14.4222, STD_Longitude=-15, Latitude=51.1676, East_West_collector_azimuth_angle=0, 
                                                                                                            Collector_tilt_angle=36, Tm_rl=60, Qsa=0, Vorwärmung_K=8, DT_WT_Solar_K=5, DT_WT_Netz_K=5, 
                                                                                                            opt_volume_min=0, opt_volume_max=200, opt_area_min=0, opt_area_max=2000)):

    results = solarThermal.calculate(economic_parameters, duration, Last_L, VLT_L=VLT_L, RLT_L=RLT_L, TRY_data=TRY_data, time_steps=time_steps)

    print(f"Wärmemenge Solarthermie: {results['Wärmemenge']:.2f} MWh")
    print(f"Wärmeleistung Solarthermie: {results['Wärmeleistung_L']} kW")
    print(f"Wärmegestehungskosten Solarthermie: {results['WGK']:.2f} €/MWh")
    print(f"spezifische CO2-Emissionen Solarthermie: {results['spec_co2_total']:.2f} tCO2/MWh")
    print(f"Primärenergiebedarf Solarthermie: {results['primärenergie']:.2f} MWh")
    print(f"Speicherladung Solarthermie: {results['Speicherladung_L']} kW")
    print(f"Speicherfüllstand Solarthermie: {results['Speicherfüllstand_L']} MWh")

if __name__ == "__main__":
    # Heat demand profile for one year (8760 hours)
    min_last = 50
    max_last = 400
    Last_L = np.random.randint(min_last, max_last, 8760).astype(float)

    # Duration
    duration = 1

    # Arrays for VLT and RLT, assuming constant values for the example
    VLT_L, RLT_L = np.full(8760, 80), np.full(8760, 55)

    # Load COP data from CSV file
    COP_data = np.genfromtxt("examples/data/COP/Kennlinien WP.csv", delimiter=';')

    # Filename for TRY data
    TRY_data = import_TRY("examples/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat")

    # Time steps for the simulation
    # Angaben zum zu betrchtende Zeitraum
    # Erstelle ein Array mit stündlichen Zeitwerten für ein Jahr
    start_date = np.datetime64('2019-01-01')
    end_date = np.datetime64('2020-01-01', 'D')  # Enddatum ist exklusiv, daher 'D' für Tage

    # Erstelle das Array mit stündlichen Zeitwerten für ein Jahr
    time_steps = np.arange(start_date, end_date, dtype='datetime64[h]')


    # Define economic parameters
    electricity_price = 150 # €/MWh
    gas_price = 70 # €/MWh
    wood_price = 60 # €/MWh
    q = 1.05
    r = 1.03
    T = 20
    BEW = "Nein"
    hourly_rate = 45

    economic_parameters = {
                "gas_price": gas_price,
                "electricity_price": electricity_price,
                "wood_price": wood_price,
                "capital_interest_rate": q,
                "inflation_rate": r,
                "time_period": T,
                "hourly_rate": hourly_rate,
                "subsidy_eligibility": BEW
            }
    
    # Test Gas Boiler
    gBoiler = GasBoiler(name="Gas_Boiler_1", thermal_capacity_kW=1000, spez_Investitionskosten=30, Nutzungsgrad=0.9)
    test_gas_boiler(Last_L, duration, economic_parameters, gBoiler)

    # Test Power to Heat
    PTH = PowerToHeat(name="PowerToHeat_1", thermal_capacity_kW=1000, spez_Investitionskosten=30, Nutzungsgrad=0.98)    
    test_power_to_heat(Last_L, duration, economic_parameters, PTH)

    # Test Biomass Boiler without storage
    bBoiler = BiomassBoiler(name="Biomasss_Boiler_1", thermal_capacity_kW=200, Größe_Holzlager=40, spez_Investitionskosten=200, 
                                           spez_Investitionskosten_Holzlager=400, Nutzungsgrad_BMK=0.8, min_Teillast=0.3, speicher_aktiv=False, 
                                           Speicher_Volumen=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, min_fill=0.2, max_fill=0.8, 
                                           spez_Investitionskosten_Speicher=750, active=True, opt_BMK_min=0, opt_BMK_max=1000, opt_Speicher_min=0, 
                                           opt_Speicher_max=100)
    test_biomass_boiler(Last_L, duration, economic_parameters, bBoiler)

    # Test Biomass Boiler with storage
    bBoiler_storage = BiomassBoiler(name="Biomasss_Boiler_1", thermal_capacity_kW=200, Größe_Holzlager=40, spez_Investitionskosten=200, 
                                                   spez_Investitionskosten_Holzlager=400, Nutzungsgrad_BMK=0.8, min_Teillast=0.3, speicher_aktiv=True, 
                                                   Speicher_Volumen=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, min_fill=0.2, max_fill=0.8, 
                                                   spez_Investitionskosten_Speicher=750, active=True, opt_BMK_min=0, opt_BMK_max=1000, opt_Speicher_min=0, 
                                                   opt_Speicher_max=100)
    test_biomass_boiler_storage(Last_L, duration, economic_parameters, bBoiler_storage)

    # Test CHP without storage
    CHP_1 = CHP(name="BHKW", th_Leistung_kW=100, spez_Investitionskosten_GBHKW=1500, spez_Investitionskosten_HBHKW=1850, el_Wirkungsgrad=0.33, 
                  KWK_Wirkungsgrad=0.9, min_Teillast=0.7, speicher_aktiv=False, Speicher_Volumen_BHKW=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, 
                  min_fill=0.2, max_fill=0.8, spez_Investitionskosten_Speicher=750, active=True, opt_BHKW_min=0, opt_BHKW_max=1000, opt_BHKW_Speicher_min=0, 
                  opt_BHKW_Speicher_max=100)    
    test_chp(Last_L, duration, economic_parameters, CHP_1)

    # Test CHP with storage
    CHP_storage = CHP(name="BHKW", th_Leistung_kW=100, spez_Investitionskosten_GBHKW=1500, spez_Investitionskosten_HBHKW=1850, el_Wirkungsgrad=0.33, 
                          KWK_Wirkungsgrad=0.9, min_Teillast=0.7, speicher_aktiv=True, Speicher_Volumen_BHKW=20, T_vorlauf=90, T_ruecklauf=60, initial_fill=0.0, 
                          min_fill=0.2, max_fill=0.8, spez_Investitionskosten_Speicher=750, active=True, opt_BHKW_min=0, opt_BHKW_max=1000, opt_BHKW_Speicher_min=0, 
                          opt_BHKW_Speicher_max=100)
    test_chp_storage(Last_L, duration, economic_parameters, CHP_storage)

    # Test Waste Heat Pump
    wasteHeatPump = WasteHeatPump(name="Abwärmepumpe", Kühlleistung_Abwärme=50, Temperatur_Abwärme=30, spez_Investitionskosten_Abwärme=500, 
                                             spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)
    test_waste_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, wasteHeatPump)

    # Test River Heat Pump
    riverHeatPump = RiverHeatPump(name="Flusswärmepumpe", Wärmeleistung_FW_WP=200, Temperatur_FW_WP=10, dT=0, spez_Investitionskosten_Flusswasser=1000, 
                                             spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)
    test_river_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, riverHeatPump) 

    # Test Geothermal Heat Pump
    geothermal_heat_pump = Geothermal(name="Geothermie", Fläche=200, Bohrtiefe=100, Temperatur_Geothermie=10, spez_Bohrkosten=100, spez_Entzugsleistung=50,
                                                Vollbenutzungsstunden=2400, Abstand_Sonden=10, spezifische_Investitionskosten_WP=1000, min_Teillast=0.2)
    test_geothermal_heat_pump(Last_L, duration, economic_parameters, VLT_L, COP_data, geothermal_heat_pump)

    # Test Solar Thermal
    solarThermal = SolarThermal(name="Solarthermie", bruttofläche_STA=200, vs=20, Typ="Vakuumröhrenkollektor", kosten_speicher_spez=750, kosten_fk_spez=430, kosten_vrk_spez=590, 
                                            Tsmax=90, Longitude=-14.4222, STD_Longitude=-15, Latitude=51.1676, East_West_collector_azimuth_angle=0, Collector_tilt_angle=36, Tm_rl=60, 
                                            Qsa=0, Vorwärmung_K=8, DT_WT_Solar_K=5, DT_WT_Netz_K=5, opt_volume_min=0, opt_volume_max=200, opt_area_min=0, opt_area_max=2000)
    test_solar_thermal(Last_L, duration, economic_parameters, VLT_L, RLT_L, TRY_data, time_steps, solarThermal)

Heat generator configuration and analysis.

Heat Generation Optimization

10_example_heat_generation_optimization.py

"""
Filename: 10_example_heat_generation_optimization.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-07-12
Description: Example for the optimization of a heat generator mix

Updated to match the latest version of all heat generator classes.
"""

from districtheatingsim.heat_generators.solar_thermal import SolarThermal
from districtheatingsim.heat_generators.gas_boiler import GasBoiler
from districtheatingsim.heat_generators.biomass_boiler import BiomassBoiler
from districtheatingsim.heat_generators.chp import CHP
from districtheatingsim.heat_generators.waste_heat_pump import WasteHeatPump
from districtheatingsim.heat_generators.river_heat_pump import RiverHeatPump
from districtheatingsim.heat_generators.geothermal_heat_pump import Geothermal
from districtheatingsim.heat_generators.power_to_heat import PowerToHeat
from districtheatingsim.heat_generators.energy_system import EnergySystem
from districtheatingsim.utilities.test_reference_year import import_TRY

import numpy as np
import matplotlib.pyplot as plt

def test_berechnung_erzeugermix(optimize=False, plot=True, opt_method="SLSQP"):
    # Lastgang, z.B. in kW, muss derzeitig für korrekte wirtschaftliche Betrachtung Länge von 8760 haben
    min_last = 50
    max_last = 400
    Last_L = np.random.randint(min_last, max_last, 8760).astype(float)

    # Load profile from csv file
    Last_L = np.genfromtxt("examples/data/Lastgang/Lastgang.csv", delimiter=';', skip_header=1)
    # 5 column
    Last_L = Last_L[:, 4]
    print(Last_L)

    # Wirtschaftliche Randbedingungen
    electricity_price = 150 # €/MWh - Updated to match 09 example
    gas_price = 70 # €/MWh
    wood_price = 60 # €/MWh - Updated to match 09 example

    q = 1.05
    r = 1.03
    T = 20
    BEW = "Nein"
    hourly_rate = 45

    # Arrays für Vor- und Rücklauftemperatur
    VLT_L, RLT_L = np.full(8760, 80), np.full(8760, 55)

    # Laden des COP-Kennfeldes
    COP_data = np.genfromtxt("examples/data/COP/Kennlinien WP.csv", delimiter=';')

    # Dateiname Testreferenzjahr für Wetterdaten, Dateiname muss ggf. angepasst werden
    TRY_data = import_TRY("examples/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat")

    # UPDATED: Technology definitions matching 09 example
    gBoiler = GasBoiler(
        name="Gas_Boiler_1", 
        thermal_capacity_kW=1000,  # Updated parameter name
        spez_Investitionskosten=30, 
        Nutzungsgrad=0.9
    )

    PTH = PowerToHeat(
        name="PowerToHeat_1", 
        thermal_capacity_kW=1000,  # Updated parameter name
        spez_Investitionskosten=30, 
        Nutzungsgrad=0.98  # Updated efficiency
    )

    bBoiler = BiomassBoiler(
        name="Biomass_Boiler_1", 
        thermal_capacity_kW=200, 
        Größe_Holzlager=40, 
        spez_Investitionskosten=200, 
        spez_Investitionskosten_Holzlager=400, 
        Nutzungsgrad_BMK=0.8, 
        min_Teillast=0.3, 
        speicher_aktiv=False, 
        Speicher_Volumen=20, 
        T_vorlauf=90, 
        T_ruecklauf=60, 
        initial_fill=0.0, 
        min_fill=0.2, 
        max_fill=0.8, 
        spez_Investitionskosten_Speicher=750, 
        active=True, 
        opt_BMK_min=0, 
        opt_BMK_max=1000, 
        opt_Speicher_min=0, 
        opt_Speicher_max=100
    )

    bBoiler_storage = BiomassBoiler(
        name="Biomass_Boiler_2", 
        thermal_capacity_kW=200, 
        Größe_Holzlager=40, 
        spez_Investitionskosten=200, 
        spez_Investitionskosten_Holzlager=400, 
        Nutzungsgrad_BMK=0.8, 
        min_Teillast=0.3, 
        speicher_aktiv=True,  # Updated: with storage
        Speicher_Volumen=20, 
        T_vorlauf=90, 
        T_ruecklauf=60, 
        initial_fill=0.0, 
        min_fill=0.2, 
        max_fill=0.8, 
        spez_Investitionskosten_Speicher=750, 
        active=True, 
        opt_BMK_min=0, 
        opt_BMK_max=1000, 
        opt_Speicher_min=0, 
        opt_Speicher_max=100
    )

    CHP_1 = CHP(
        name="BHKW_1", 
        th_Leistung_kW=100,  # Updated parameter name
        spez_Investitionskosten_GBHKW=1500, 
        spez_Investitionskosten_HBHKW=1850, 
        el_Wirkungsgrad=0.33, 
        KWK_Wirkungsgrad=0.9, 
        min_Teillast=0.7, 
        speicher_aktiv=False, 
        Speicher_Volumen_BHKW=20, 
        T_vorlauf=90, 
        T_ruecklauf=60, 
        initial_fill=0.0, 
        min_fill=0.2, 
        max_fill=0.8, 
        spez_Investitionskosten_Speicher=750, 
        active=True, 
        opt_BHKW_min=0, 
        opt_BHKW_max=1000, 
        opt_BHKW_Speicher_min=0, 
        opt_BHKW_Speicher_max=100
    )

    CHP_storage = CHP(
        name="BHKW_2", 
        th_Leistung_kW=100,  # Updated parameter name
        spez_Investitionskosten_GBHKW=1500, 
        spez_Investitionskosten_HBHKW=1850, 
        el_Wirkungsgrad=0.33, 
        KWK_Wirkungsgrad=0.9, 
        min_Teillast=0.7, 
        speicher_aktiv=True,  # Updated: with storage
        Speicher_Volumen_BHKW=20, 
        T_vorlauf=90, 
        T_ruecklauf=60, 
        initial_fill=0.0, 
        min_fill=0.2, 
        max_fill=0.8, 
        spez_Investitionskosten_Speicher=750, 
        active=True, 
        opt_BHKW_min=0, 
        opt_BHKW_max=1000, 
        opt_BHKW_Speicher_min=0, 
        opt_BHKW_Speicher_max=100
    )

    # UPDATED: Heat pump definitions matching 09 example
    wasteHeatPump = WasteHeatPump(
        name="Abwärmepumpe", 
        Kühlleistung_Abwärme=50, 
        Temperatur_Abwärme=30, 
        spez_Investitionskosten_Abwärme=500, 
        spezifische_Investitionskosten_WP=1000, 
        min_Teillast=0.2
    )

    riverHeatPump = RiverHeatPump(
        name="Flusswärmepumpe", 
        Wärmeleistung_FW_WP=200, 
        Temperatur_FW_WP=10, 
        dT=0, 
        spez_Investitionskosten_Flusswasser=1000, 
        spezifische_Investitionskosten_WP=1000, 
        min_Teillast=0.2
    )

    geothermal_heat_pump = Geothermal(
        name="Geothermie", 
        Fläche=200, 
        Bohrtiefe=100, 
        Temperatur_Geothermie=10, 
        spez_Bohrkosten=100, 
        spez_Entzugsleistung=50,
        Vollbenutzungsstunden=2400, 
        Abstand_Sonden=10, 
        spezifische_Investitionskosten_WP=1000, 
        min_Teillast=0.2
    )

    solarThermal = SolarThermal(
        name="Solarthermie", 
        bruttofläche_STA=200, 
        vs=20, 
        Typ="Vakuumröhrenkollektor", 
        kosten_speicher_spez=750, 
        kosten_fk_spez=430, 
        kosten_vrk_spez=590, 
        Tsmax=90, 
        Longitude=-14.4222, 
        STD_Longitude=-15, 
        Latitude=51.1676, 
        East_West_collector_azimuth_angle=0, 
        Collector_tilt_angle=36, 
        Tm_rl=60, 
        Qsa=0, 
        Vorwärmung_K=8, 
        DT_WT_Solar_K=5, 
        DT_WT_Netz_K=5, 
        opt_volume_min=0, 
        opt_volume_max=200, 
        opt_area_min=0, 
        opt_area_max=2000
    )

    # UPDATED: Technology selection - mix of different technologies
    tech_objects = [
        solarThermal,  # Solar thermal
        CHP_1,      # CHP with storage
        gBoiler,          # Gas boiler as backup
    ]

    # Time steps for simulation
    start_date = np.datetime64('2019-01-01')
    end_date = np.datetime64('2020-01-01', 'D')
    time_steps = np.arange(start_date, end_date, dtype='datetime64[h]')

    # UPDATED: Economic parameters matching 09 example
    economic_parameters = {
        "gas_price": gas_price,
        "electricity_price": electricity_price,
        "wood_price": wood_price,
        "capital_interest_rate": q,
        "inflation_rate": r,
        "time_period": T,
        "hourly_rate": hourly_rate,
        "subsidy_eligibility": BEW
    }

    # Optimization weights
    weights = {
        "WGK_Gesamt": 1.0,                    # Focus on cost optimization
        "specific_emissions_Gesamt": 0.1,     # Small weight for emissions
        "primärenergiefaktor_Gesamt": 0.0     # No weight for primary energy
    }

    # Create energy system
    energy_system = EnergySystem(
        time_steps=time_steps,
        load_profile=Last_L,
        VLT_L=VLT_L,
        RLT_L=RLT_L,
        TRY_data=TRY_data,
        COP_data=COP_data,
        economic_parameters=economic_parameters,
    )

    # Add technologies to the system
    for tech in tech_objects:
        energy_system.add_technology(tech)

    # Calculate the initial energy mix
    system_results = energy_system.calculate_mix()
    print("=== Initial Energy Mix Results ===")
    print(f"Technologies: {system_results['techs']}")
    print(f"Energy mix shares: {system_results['Anteile']}")
    print(f"Heat generation costs: {system_results['WGK_Gesamt']:.2f} €/MWh")
    print(f"Specific emissions: {system_results.get('specific_emissions_Gesamt', 'N/A'):.3f} tCO2/MWh")
    print(f"Primary energy factor: {system_results.get('primärenergiefaktor_Gesamt', 'N/A'):.3f}")

    if plot:
        print("\nGenerating initial plots...")
        fig1 = plt.figure(figsize=(12, 8))
        energy_system.plot_stack_plot(fig1)
        fig1.suptitle('Initial Energy Mix - Stack Plot')
        
        fig2 = plt.figure(figsize=(10, 8))
        energy_system.plot_pie_chart(fig2)
        fig2.suptitle('Initial Energy Mix - Pie Chart')

    # Perform optimization if requested
    if optimize:
        print(f"\n=== Starting Optimization with {opt_method} ===")
        
        if opt_method == "SLSQP":
            print("Optimizing mix with SLSQP...")
            optimized_energy_system = energy_system.optimize_mix(weights, num_restarts=5)
        else:
            print(f"Unknown optimization method: {opt_method}")
            return
            
        print("Optimization completed!")

        # Calculate the optimized energy mix
        optimized_system_results = optimized_energy_system.calculate_mix()
        print("\n=== Optimized Energy Mix Results ===")
        print(f"Technologies: {optimized_system_results['techs']}")
        print(f"Energy mix shares: {optimized_system_results['Anteile']}")
        print(f"Heat generation costs: {optimized_system_results['WGK_Gesamt']:.2f} €/MWh")
        print(f"Specific emissions: {optimized_system_results.get('specific_emissions_Gesamt', 'N/A'):.3f} tCO2/MWh")
        print(f"Primary energy factor: {optimized_system_results.get('primärenergiefaktor_Gesamt', 'N/A'):.3f}")

        # Compare results
        print("\n=== Optimization Comparison ===")
        initial_cost = system_results['WGK_Gesamt']
        optimized_cost = optimized_system_results['WGK_Gesamt']
        cost_savings = initial_cost - optimized_cost
        cost_savings_percent = (cost_savings / initial_cost) * 100

        print(f"Initial costs: {initial_cost:.2f} €/MWh")
        print(f"Optimized costs: {optimized_cost:.2f} €/MWh")
        print(f"Cost savings: {cost_savings:.2f} €/MWh ({cost_savings_percent:.1f}%)")

        if plot:
            print("\nGenerating optimized plots...")
            fig3 = plt.figure(figsize=(12, 8))
            optimized_energy_system.plot_stack_plot(fig3)
            fig3.suptitle('Optimized Energy Mix - Stack Plot')
            
            fig4 = plt.figure(figsize=(10, 8))
            optimized_energy_system.plot_pie_chart(fig4)
            fig4.suptitle('Optimized Energy Mix - Pie Chart')

    print("\n=== Analysis Complete ===")
    return energy_system

if __name__ == "__main__":
    print("Starting Heat Generation Optimization Example")
    print("=" * 50)
    
    # Test with different optimization methods
    print("\n1. Testing without optimization:")
    energy_system_base = test_berechnung_erzeugermix(optimize=False, plot=True)
    
    print("\n2. Testing with SLSQP optimization:")
    energy_system_slsqp = test_berechnung_erzeugermix(optimize=True, plot=True, opt_method="SLSQP")

    print("\nShowing all plots...")
    plt.show()

Heat generation system optimization example.

Economic Analysis Examples

Annuity Calculation

15_example_annuity.py

"""
Filename: 15_example_annuity.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-19
Description: Example for the calculation of the annuity of a heat generator

"""

from districtheatingsim.heat_generators import annuity

# Test Annuitätsberechnung
def test_annuität():
    # Investition in €
    A0 = 10000

    # Technische Nutzungsdauer in Jahren
    TN = 20

    # Kostenfaktor Installationskosten als Anteil der Investitionskosten
    f_Inst = 0.03

    # Kostenfaktor Wartungs- und Instandhaltungskosten als Anteil der Investitionskosten
    f_W_Insp = 0.02

    # Bedienaufwand in Stunden (Stundensatz aktuell fix in der Funktion mit 45 €/h hinterlegt)
    # muss unbedingt noch weg von der fixen Definition
    Bedienaufwand = 10

    # Kapitalzinsfaktor 
    q = 1.05 # 5 %

    # Preissteigerungsfaktor
    r = 1.03 # 3 %

    # Betrachtungszeitraum in Jahren
    T = 20

    # Energiebedarf / Brennstoffbedarf in z.B. kWh
    Energiebedarf = 15000

    # Energiekosten in z.B. €/kWh --> Einheit Energie muss mit der des Energiebedarfs übereinstimmen
    Energiekosten = 0.15

    # Erlöse, könnte z.B. Stromverkauf aus BHKW sein oder auch Wärmeverkauf, kann auf 0 gesetzt werden, dann nur Aussage über Höhe der Kosten
    E1 = 0

    A_N = annuity.annuity(A0, TN, f_Inst, f_W_Insp, Bedienaufwand, q, r, T, Energiebedarf, Energiekosten, E1)

    print(f"Annuität: {A_N:.2f} €")

if __name__ == "__main__":
    test_annuität()

Economic evaluation and annuity calculation example.

Visualization Examples

Photovoltaics Integration

14_example_photovoltaics.py

"""
Filename: 14_example_photovoltaics.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-21
Description: 

"""

from districtheatingsim.heat_generators.photovoltaics import Calculate_PV

if __name__ == '__main__':
    # Define the input parameters for the photovoltaic calculation.
    TRY_data = "examples\\data\\TRY\\TRY_511676144222\\TRY2015_511676144222_Jahr.dat"
    Gross_area = 100 # m²
    Longitude = 11.581981
    STD_Longitude = 15
    Latitude = 48.135125
    Albedo = 0.2
    East_West_collector_azimuth_angle = 90
    Collector_tilt_angle = 30

    # Calculate the photovoltaic power output.
    Annual_PV_yield, Max_power, Power_output = Calculate_PV(TRY_data, Gross_area, Longitude, STD_Longitude, Latitude, Albedo,
                                                            East_West_collector_azimuth_angle, Collector_tilt_angle)

    print(f'Annual PV yield: {Annual_PV_yield} kWh')
    print(f'Maximum power: {Max_power} kW')
    print(f'Power output array: {Power_output} W')

Photovoltaic system integration example.

Annuity Calculation

15_example_annuity.py

"""
Filename: 15_example_annuity.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-19
Description: Example for the calculation of the annuity of a heat generator

"""

from districtheatingsim.heat_generators import annuity

# Test Annuitätsberechnung
def test_annuität():
    # Investition in €
    A0 = 10000

    # Technische Nutzungsdauer in Jahren
    TN = 20

    # Kostenfaktor Installationskosten als Anteil der Investitionskosten
    f_Inst = 0.03

    # Kostenfaktor Wartungs- und Instandhaltungskosten als Anteil der Investitionskosten
    f_W_Insp = 0.02

    # Bedienaufwand in Stunden (Stundensatz aktuell fix in der Funktion mit 45 €/h hinterlegt)
    # muss unbedingt noch weg von der fixen Definition
    Bedienaufwand = 10

    # Kapitalzinsfaktor 
    q = 1.05 # 5 %

    # Preissteigerungsfaktor
    r = 1.03 # 3 %

    # Betrachtungszeitraum in Jahren
    T = 20

    # Energiebedarf / Brennstoffbedarf in z.B. kWh
    Energiebedarf = 15000

    # Energiekosten in z.B. €/kWh --> Einheit Energie muss mit der des Energiebedarfs übereinstimmen
    Energiekosten = 0.15

    # Erlöse, könnte z.B. Stromverkauf aus BHKW sein oder auch Wärmeverkauf, kann auf 0 gesetzt werden, dann nur Aussage über Höhe der Kosten
    E1 = 0

    A_N = annuity.annuity(A0, TN, f_Inst, f_W_Insp, Bedienaufwand, q, r, T, Energiebedarf, Energiekosten, E1)

    print(f"Annuität: {A_N:.2f} €")

if __name__ == "__main__":
    test_annuität()

Annuity and financial calculations example.

Interactive Plotting

16_interactive_matplotlib.py

"""
Filename: 16_interactive_matplotlib.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-11-21
Description: Not really an example, but a test for interactive matplotlib plots.

"""

import sys
import numpy as np
from PyQt5.QtWidgets import (QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QPushButton, QCheckBox, QColorDialog)
from matplotlib.figure import Figure
from matplotlib.backends.backend_qt5agg import FigureCanvasQTAgg as FigureCanvas

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        self.central_widget = QWidget()
        self.setCentralWidget(self.central_widget)

        self.layout = QVBoxLayout(self.central_widget)

        self.canvas = FigureCanvas(Figure(figsize=(8, 6)))
        self.layout.addWidget(self.canvas)

        self.ax = self.canvas.figure.add_subplot(111)

        self.checkboxes_layout = QHBoxLayout()
        self.layout.addLayout(self.checkboxes_layout)

        self.checkboxes = {}
        self.colors = {}
        self.data = {
            'Dataset 1': np.random.rand(10),
            'Dataset 2': np.random.rand(10),
            'Dataset 3': np.random.rand(10)
        }

        for label in self.data.keys():
            checkbox = QCheckBox(label)
            checkbox.setChecked(True)
            checkbox.stateChanged.connect(self.update_plot)
            self.checkboxes_layout.addWidget(checkbox)
            self.checkboxes[label] = checkbox

            color_button = QPushButton('Color')
            color_button.clicked.connect(lambda _, l=label: self.change_color(l))
            self.checkboxes_layout.addWidget(color_button)
            self.colors[label] = 'blue'

        self.update_plot()

    def update_plot(self):
        self.ax.clear()

        for label, data in self.data.items():
            if self.checkboxes[label].isChecked():
                self.ax.plot(data, label=label, color=self.colors[label])

        self.ax.legend()
        self.canvas.draw()

    def change_color(self, label):
        color = QColorDialog.getColor()

        if color.isValid():
            self.colors[label] = color.name()
            self.update_plot()

if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())

Interactive plotting and visualization example.

Seasonal Storage

17_energy_system_seasonal_storage.py

import numpy as np
from districtheatingsim.heat_generators.energy_system import EnergySystem
from districtheatingsim.heat_generators.chp import CHP, CHPStrategy
from districtheatingsim.heat_generators.gas_boiler import GasBoiler, GasBoilerStrategy
from districtheatingsim.heat_generators.power_to_heat import PowerToHeat, PowerToHeatStrategy
from districtheatingsim.heat_generators.biomass_boiler import BiomassBoiler, BiomassBoilerStrategy
from districtheatingsim.heat_generators.river_heat_pump import RiverHeatPump
from districtheatingsim.heat_generators.waste_heat_pump import WasteHeatPump
from districtheatingsim.heat_generators.geothermal_heat_pump import Geothermal
from districtheatingsim.heat_generators.base_heat_pumps import HeatPumpStrategy
from districtheatingsim.heat_generators.solar_thermal import SolarThermal, SolarThermalStrategy
from districtheatingsim.heat_generators.STES import STES

from districtheatingsim.utilities.test_reference_year import import_TRY

from matplotlib import pyplot as plt

import pandas as pd
import os

# Testparameter
time_steps = pd.date_range(start="2023-01-01", end="2023-12-31 23:00:00", freq="h").to_numpy()

file_path = os.path.join('examples', 'data', 'Lastgang', 'Lastgang.csv')

df = pd.read_csv(file_path, delimiter=';', encoding='utf-8')
load_profile = df['Gesamtwärmebedarf_Gebäude_kW'].values
VLT_L = np.random.uniform(85, 85, 8760)
RLT_L = np.random.uniform(50, 50, 8760)

TRY_filename = os.path.abspath('src/districtheatingsim/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat')
TRY_data = import_TRY(TRY_filename)

COP_filename = os.path.abspath('src/districtheatingsim/data/COP/Kennlinien WP.csv')
COP_data = np.genfromtxt(COP_filename, delimiter=';')

economic_parameters = {"gas_price": 50, "wood_price": 40, "electricity_price": 120, "capital_interest_rate": 0.05, 
                       "inflation_rate": 0.03, "time_period": 20, "subsidy_eligibility": "Nein", "hourly_rate": 45}  # Wirtschaftsparameter

# Speicherparameter
storage_params = {
    "storage_type": "truncated_trapezoid",  # Speichergeometrie
    "dimensions": (20, 20, 50, 50, 15),  # Geometrieparameter
    "rho": 1000,  # Dichte des Mediums (kg/m³)
    "cp": 4180,  # Spezifische Wärmekapazität (J/kg*K)
    "T_ref": 10,  # Referenztemperatur (°C)
    "lambda_top": 0.04,  # Wärmeleitfähigkeit der oberen Isolierung (W/m*K)
    "lambda_side": 0.03,  # Wärmeleitfähigkeit der seitlichen Isolierung (W/m*K)
    "lambda_bottom": 0.05,  # Wärmeleitfähigkeit der unteren Isolierung (W/m*K)
    "lambda_soil": 1.5,  # Wärmeleitfähigkeit des Bodens (W/m*K)
    "dt_top": 0.3,  # Dicke der oberen Isolierung (m)
    "ds_side": 0.4,  # Dicke der seitlichen Isolierung (m)
    "db_bottom": 0.5,  # Dicke der unteren Isolierung (m)
    "T_amb": 10,  # Umgebungstemperatur (°C)
    "T_soil": 10,  # Bodentemperatur (°C)
    "T_max": 95,  # Maximale Speichertemperatur (°C)
    "T_min": 40,  # Minimale Speichertemperatur (°C)
    "initial_temp": 60,  # Anfangstemperatur des Speichers (°C)
    "hours": 8760,  # Anzahl der Stunden in einem Jahr
    "num_layers": 5,  # Anzahl der Schichten für die Schichtung
    "thermal_conductivity": 0.6  # Wärmeleitfähigkeit des Mediums (W/m*K)
}

# Initialisiere das Energiesystem
energy_system = EnergySystem(time_steps, load_profile, VLT_L, RLT_L, TRY_data, COP_data, economic_parameters)

# Initialisiere den Speicher
storage = STES(name="Saisonalspeicher", **storage_params)
energy_system.add_storage(storage)

# Füge Generatoren hinzu
chp = CHP("BHKW_1", th_Leistung_kW=500)
energy_system.add_technology(chp)
chp.strategy = CHPStrategy(charge_on=75, charge_off=70)

#pth = PowerToHeat("PtH_1", thermal_capacity_kW=500)
#energy_system.add_technology(pth)
#pth.strategy = PowerToHeatStrategy(charge_on=75)

# Biomasssboiler hinzufügen
#biomass_boiler = BiomassBoiler("Biomassekessel_1", thermal_capacity_kW=500)
#energy_system.add_technology(biomass_boiler)
#biomass_boiler.strategy = BiomassBoilerStrategy(charge_on=75, charge_off=70)

# Gasboiler hinzufügen
#gas_boiler = GasBoiler("Gasboiler_1", thermal_capacity_kW=1000)
#energy_system.add_technology(gas_boiler)
#gas_boiler.strategy = GasBoilerStrategy(charge_on=70)

# Erneuerbare Energien hinzufügen
#river_heat_pump = RiverHeatPump("Flusswärmepumpe_1", Wärmeleistung_FW_WP=600, Temperatur_FW_WP=20)
#energy_system.add_technology(river_heat_pump)
#river_heat_pump.strategy = HeatPumpStrategy(charge_on=75, charge_off=70)

#waste_heat_pump = WasteHeatPump("Abwärmepumpe_1", Kühlleistung_Abwärme=600, Temperatur_Abwärme=20)
#energy_system.add_technology(waste_heat_pump)
#waste_heat_pump.strategy = HeatPumpStrategy(charge_on=75, charge_off=70)

#waste_water_heat_pump = WasteHeatPump("Abwasserwärmepumpe_1", Kühlleistung_Abwärme=200, Temperatur_Abwärme=20)
#energy_system.add_technology(waste_water_heat_pump)
#waste_water_heat_pump.strategy = HeatPumpStrategy(charge_on=75, charge_off=70)

#geothermal_heat_pump = Geothermal("Geothermie_1", Fläche=10000, Bohrtiefe=100, Temperatur_Geothermie=20)
#energy_system.add_technology(geothermal_heat_pump)
#geothermal_heat_pump.strategy = HeatPumpStrategy(charge_on=75, charge_off=70)

#solar_thermal = SolarThermal("Solarthermie_1", bruttofläche_STA=2500, vs=50, Typ="Vakuumröhrenkollektor")
#energy_system.add_technology(solar_thermal)
#solar_thermal.strategy = SolarThermalStrategy(charge_on=75, charge_off=70)


# Berechne den Energiemix mit Speicher
results = energy_system.calculate_mix()

# Ergebnisse anzeigen
print("Simulationsergebnisse:")
print(f"Speicherwirkungsgrad: {results['storage_class'].efficiency*100:.2f}%")
# print(f"Betriebskosten: {results['storage_class'].operational_costs:.2f} €")  # Not yet implemented in STES
print(f"Überschüssige Wärme durch Stagnation: {results['storage_class'].excess_heat:.2f} kWh")
print(f"Nicht gedeckter Bedarf aufgrund von Speicherentleerung: {results['storage_class'].unmet_demand:.2f} kWh")
print(f"Stagnationsdauer: {results['storage_class'].stagnation_time} h")


# Ergebnisse plotten
results['storage_class'].plot_results(results["Wärmeleistung_L"][0], load_profile, VLT_L, RLT_L)
energy_system.plot_stack_plot()
energy_system.plot_pie_chart()
plt.show()

Seasonal energy storage systems example.

Utility Examples

STANET to Pandapipes Conversion

18_stanet_to_pandapipes.py

"""
Filename: 18_stanet_to_pandapipes.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2025-05-21
Description: This script demonstrates how to use the `create_net_from_stanet_csv` function from the `feature_develop.stanet_import_pandapipes` module.

"""

from stanet_import_pandapipes import create_net_from_stanet_csv
import pandapipes as pp

if __name__ == "__main__":
    # Example usage
    stanet_csv_file_path= "examples/data/STANET/Example_STANET_ETRS89.CSV"
    TRY_file_path = "examples/data/TRY/TRY_511676144222/TRY2015_511676144222_Jahr.dat"
    supply_temperature = 80  # Supply temperature in Celsius
    flow_pressure_pump = 4.0  # Flow pressure of the pump in bar
    lift_pressure_pump = 1.5  # Lift pressure of the pump in bar

    net, yearly_time_steps, total_heat_W, max_heat_requirement_W = create_net_from_stanet_csv(stanet_csv_file_path, TRY_file_path, supply_temperature, flow_pressure_pump, lift_pressure_pump)

STANET to pandapipes conversion example.

Generator Schematic Test

19_generator_schematic_test_window.py

"""
Filename: generator_schematic_test_window.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-09-27
Description: Test window for the schematic scene with buttons to add components.
"""

import sys

from PyQt5.QtWidgets import QMainWindow, QVBoxLayout, QPushButton, QWidget, QHBoxLayout, QApplication
from districtheatingsim.gui.EnergySystemTab._11_generator_schematic import SchematicScene, CustomGraphicsView

class SchematicWindow(QMainWindow):
    def __init__(self):
        super().__init__()

        # Set up main window
        self.setWindowTitle('Complex Heat Generator Schematic')
        self.setGeometry(100, 100, 1000, 1000)

        self.centralWidget = QWidget()
        self.setCentralWidget(self.centralWidget)

        layout = QHBoxLayout(self.centralWidget)

        # Instantiate SchematicScene (now decoupled from the window)
        self.scene = SchematicScene(1000, 1000)
        self.view = CustomGraphicsView(self.scene)  # Use custom view with zoom and pan functionality
        layout.addWidget(self.view)

        # Button panel for UI
        button_layout = QVBoxLayout()
        self.add_solar_button = QPushButton("Add Solar")
        self.add_solar_storage_button = QPushButton("Add Solar + Storage")
        self.add_chp_button = QPushButton("Add CHP")
        self.add_chp_storage_button = QPushButton("Add CHP + Storage")
        self.add_wood_chp_button = QPushButton("Add Wood-CHP")
        self.add_wood_chp_storage_button = QPushButton("Add Wood-CHP + Storage")
        self.add_biomass_boiler_button = QPushButton("Add Biomass Boiler")
        self.add_biomass_boiler_storage_button = QPushButton("Add Biomass Boiler + Storage")
        self.add_gas_boiler_button = QPushButton("Add Gas Boiler")
        self.add_geothermal_hp_button = QPushButton("Add Geothermal Heat Pump")
        self.add_river_hp_button = QPushButton("Add River Heat Pump")
        self.add_waste_hp_button = QPushButton("Add Waste Heat Pump")
        self.add_aqva_hp_button = QPushButton("Add Aqva Heat Pump")
        self.delete_button = QPushButton("Delete Selected")
        self.delete_all_button = QPushButton("Delete All")

        # Add the buttons to the layout
        button_layout.addWidget(self.add_solar_button)
        button_layout.addWidget(self.add_solar_storage_button)
        button_layout.addWidget(self.add_chp_button)
        button_layout.addWidget(self.add_chp_storage_button)
        button_layout.addWidget(self.add_wood_chp_button)
        button_layout.addWidget(self.add_wood_chp_storage_button)
        button_layout.addWidget(self.add_biomass_boiler_button)
        button_layout.addWidget(self.add_biomass_boiler_storage_button)
        button_layout.addWidget(self.add_gas_boiler_button)
        button_layout.addWidget(self.add_geothermal_hp_button)
        button_layout.addWidget(self.add_river_hp_button)
        button_layout.addWidget(self.add_waste_hp_button)
        button_layout.addWidget(self.add_aqva_hp_button)
        button_layout.addWidget(self.delete_button)
        button_layout.addWidget(self.delete_all_button)

        layout.addLayout(button_layout)

        # Button signals with new add_component logic
        self.add_solar_button.clicked.connect(lambda: self.scene.add_component(item_name="Solar", storage=False))
        self.add_solar_storage_button.clicked.connect(lambda: self.scene.add_component(item_name="Solar", storage=True))
        self.add_chp_button.clicked.connect(lambda: self.scene.add_component(item_name="CHP", storage=False))
        self.add_chp_storage_button.clicked.connect(lambda: self.scene.add_component(item_name="CHP", storage=True))
        self.add_wood_chp_button.clicked.connect(lambda: self.scene.add_component(item_name="Wood-CHP", storage=False))
        self.add_wood_chp_storage_button.clicked.connect(lambda: self.scene.add_component(item_name="Wood-CHP", storage=True))
        self.add_biomass_boiler_button.clicked.connect(lambda: self.scene.add_component(item_name="Biomass Boiler", storage=False))
        self.add_biomass_boiler_storage_button.clicked.connect(lambda: self.scene.add_component(item_name="Biomass Boiler", storage=True))
        self.add_gas_boiler_button.clicked.connect(lambda: self.scene.add_component(item_name="Gas Boiler", storage=False))
        self.add_geothermal_hp_button.clicked.connect(lambda: self.scene.add_component(item_name="Geothermal Heat Pump", storage=False))
        self.add_river_hp_button.clicked.connect(lambda: self.scene.add_component(item_name="River Heat Pump", storage=False))
        self.add_waste_hp_button.clicked.connect(lambda: self.scene.add_component(item_name="Waste Heat Pump", storage=False))
        self.add_aqva_hp_button.clicked.connect(lambda: self.scene.add_component(item_name="Aqva Heat Pump", storage=False))
        self.delete_button.clicked.connect(self.scene.delete_selected)
        self.delete_all_button.clicked.connect(self.scene.delete_all)

if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = SchematicWindow()
    window.show()
    sys.exit(app.exec())

Generator schematic testing example.

Leaflet Map Visualization

20_leaflet_test.py

"""
Filename: PyQt5_Leaflet.py
Author: Dipl.-Ing. (FH) Jonas Pfeiffer
Date: 2024-09-19
Description: Contains the LeafTab class for displaying a Leaflet map in a PyQt5 application.
"""

import sys
import os
import json
import geopandas as gpd
import os

from PyQt5.QtWidgets import QApplication, QVBoxLayout, QPushButton, QWidget, QFileDialog
from PyQt5.QtWebEngineWidgets import QWebEngineView
from PyQt5.QtCore import QUrl, QObject, pyqtSlot
from PyQt5.QtWebChannel import QWebChannel

class GeoJsonReceiver(QObject):
    @pyqtSlot(str)
    def sendGeoJSONToPython(self, geojson_str):
        print("Received GeoJSON from JavaScript")
        
        # Konvertiere den JSON-String in ein Python-Objekt
        geojson_data = json.loads(geojson_str)
        
        # Erstelle ein GeoDataFrame aus dem GeoJSON
        gdf = gpd.GeoDataFrame.from_features(geojson_data['features'])
        
        # Setze das ursprüngliche CRS (EPSG:4326)
        gdf.set_crs(epsg=4326, inplace=True)
        
        # Konvertiere das CRS in das gewünschte Ziel-CRS (z.B. EPSG:25833)
        target_crs = 'EPSG:25833'
        gdf.to_crs(target_crs, inplace=True)
        
        # Speichere die Daten als GeoJSON
        output_file = 'exported_data.geojson'
        gdf.to_file(output_file, driver="GeoJSON")
        print(f"GeoJSON gespeichert in {output_file}")

class LeafletTab(QWidget):
    def __init__(self):
        super().__init__()

        self.setWindowTitle('Leaflet.draw in PyQt5')
        self.showMaximized()

        # Erstelle eine QWebEngineView, um die HTML-Karte anzuzeigen
        self.web_view = QWebEngineView()

        # Lade die HTML-Datei
        map_file_path = os.path.join(os.getcwd(), 'src\\districtheatingsim\\leaflet\\map.html')
        self.web_view.setUrl(QUrl.fromLocalFile(map_file_path))

        # Erstelle den WebChannel und registriere das Python-Objekt
        self.channel = QWebChannel()
        self.receiver = GeoJsonReceiver()
        self.channel.registerObject('pywebchannel', self.receiver)
        self.web_view.page().setWebChannel(self.channel)

        # Set up layout
        layout = QVBoxLayout()
        layout.addWidget(self.web_view)
        self.setLayout(layout)

        # Add export button
        export_button = QPushButton('Export GeoJSON')
        export_button.clicked.connect(self.export_geojson)
        layout.addWidget(export_button)

        # Add import button
        import_button = QPushButton('Import GeoJSON')
        import_button.clicked.connect(self.import_geojson)
        layout.addWidget(import_button)

    def export_geojson(self):
        # Ruft die Funktion aus JavaScript auf
        self.web_view.page().runJavaScript("exportGeoJSON()")

    def import_geojson(self):
        # Öffne ein Dialogfeld, um eine GeoJSON-Datei auszuwählen
        options = QFileDialog.Options()
        geojson_file, _ = QFileDialog.getOpenFileName(self, 'Open GeoJSON File', '', 'GeoJSON Files (*.geojson)', options=options)

        # isolating the file name
        geojson_filename = geojson_file.split('/')[-1]

        if geojson_file:
            # Lese den Inhalt der GeoJSON-Datei
            with open(geojson_file, 'r', encoding='utf-8') as f:
                geojson_data = json.load(f)

            # Übergebe die GeoJSON-Daten an JavaScript
            geojson_str = json.dumps(geojson_data)
            # geojson_filename is passed to the JavaScript function, necessary for the function to work, transformed to a string
            self.web_view.page().runJavaScript(f"window.importGeoJSON({geojson_str}, '{geojson_filename}');")

if __name__ == '__main__':
    app = QApplication(sys.argv)
    window = LeafletTab()
    window.show()
    sys.exit(app.exec())

Interactive map visualization with Leaflet example.

Running Examples

To run the examples, navigate to the project root directory and execute:

# Navigate to project root
cd DistrictHeatingSim

# Run a specific example
python examples/01_example_geocoding.py

# Run heat demand calculation example
python examples/03_example_simple_heat_requirement.py

# Run network generation example
python examples/05_example_net_generation.py

Note

Make sure you have installed DistrictHeatingSim in development mode before running examples:

pip install -e .

Tip

All example files are located in the examples/ directory of the project repository. Each example is self-contained and demonstrates specific functionality of DistrictHeatingSim.