Software 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:

.. code-block:: text

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   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 :doc:`Software License<d_license>` file.

See :doc:`Author<c_author>` for contributor information.