Overview

DHNpype is a simulation and analysis tool designed for quick evaluations of district heating & cooling network performance, particularly focused on pipe insulation, heat flow losses, and thermal behavior.

It is intended for engineers, researchers, and planners analysing and comparing different configurations and scenarios of heating & cooling distribution systems.

The software was developed as part of a reserach project at the University of Ljubljana (Slovenia) to support studies of energy transformation scenarios.

Support from the 3DIVERSE project (www.3dvierse.eu, LIFE21-CET-PDA-3DiVERSE, No. 101077343) is gratefully acknowledged.

Main Software Functionalities

The software calculates:

  • Section-by-section distribution of heat flow losses

  • Temperature and mass flow evolution along the pipeline

  • System-level cumulative losses

  • Total heat flow in the system

  • Fluid velocities

Core Assumptions

  • 1D flow with no heat generation inside the pipeline

  • Steady-state thermal and hydraulic conditions

  • Uniform properties per section

  • Constant thermal conductivities

  • Insulation follows standard thickness classes defined in a JSON file

  • Input data must follow specific CSV formats

Code Structure

The project is organized into logical components:

dhnpype/
├── data
│   ├── network_config_data
│   │   └── input_reference.csv           # Network/branch topology data
│   ├── __init__.py                       # API
│   ├── display_input_data.py             # Reads and displays input data in a CSV file
│   └── insulation_thickness.json         # Pipe & insulation standard thickness data
├── src
│   ├── utils
│   │   ├── __init__.py                   # API
│   │   ├── constants.py                  # List of constants used in the program
│   │   ├── exceptions.py                 # List of custom exceptions
│   │   ├── functions.py                  # List of functions used in the program
│   │   └── validation.py                 # Validation of insulation damage input
│   ├── __init__.py                       # Public API & version
│   ├── branch.py                         # Main calculation orchestrator
│   ├── config_data.py                    # Model initial setup
│   ├── data_input.py                     # Reading input data from a CSV file
│   ├── data_output.py                    # Dataframes containing analyses results
│   ├── main.py                           # Main script for running the program when used with Python
│   ├── model_param.py                    # Physical parameters (thermal properties, convection)
│   └── plots.py                          # Visualisation of data
├── tutorials
│   ├── figures
│   │   └── logo.png                      # dhnpype logo
│   └── one_branch.ipynb                  # An example of a 1-branch network simulation in a Jupyter notebook
├── AUTHOR                                # List of contributors
├── LICENSE                               # Software license
├── README.md                             # This file
└── requirements.txt                      # Package dependencies

Running the program

Run the main script directly:

python src/main.py

This runs the complete analysis using default input data found in data/network_config_data/input_reference.csv.

Input Requirements

Ensure the following input files are present:

  • `input_reference.csv`: Network topology and pipe definitions

  • `insulation_thickness.json`: Standard insulation thickness options

Notebook Example

To try DHNpype in interactive mode:

jupyter notebook tutorials/one_branch.ipynb

Viewing the Results

Simulation results are saved as:

  • Pandas dataframes, which are defined in: data_output.py

  • Results can be plotted in normal or interactive mode. For the latter, the plotly module must be loaded.

  • The following results are available:

    • Temperature distribution

    • Heat flow losses

    • Normalised heat flow losses

    • Heat flow to the consumers

    • Residual heat flow from consumers

    • Velocity of the fluid inside the pipeline

    • Total heat flow in the system

License & Credits

This software is licensed under the terms of the Software License file.

See Author for contributor information.