Heat CM: District Heating Supply
In A Glance
The District Heating Supply Calculation Module (CM) is a web‑based optimisation tool embedded in the Citiwatts platform. It helps planners design and operate district heating systems at hourly resolution by balancing technical constraints, operational costs, and investment decisions.
Key Features: - Two operating modes: 1. Dispatch only: finds the least‑cost hourly operation of existing capacities 2. Investment + dispatch: simultaneously selects new capacity additions and their dispatch - Hourly resolution for detailed insights into load matching, temperature constraints, and electricity‑price interactions - Multi‑technology support (CHP, boilers, heat pumps, waste‑to‑energy, solar thermal, excess heat) - Customisable parameters covering CAPEX/OPEX, efficiencies, lifetimes, CO₂ price, interest rate, and grid temperature limits
Primary Outputs: * Optimal dispatch schedules and (if enabled) capacity expansions * Levelized Cost of Heat (LCOH) and full annual cost breakdown (investment annuity, O&M, fuel, CO₂, ramping) * Annual generation volumes (thermal and electrical) and CO₂ emissions * Technology share in both investment and dispatch
Introduction
The District Heating Supply calculation module (CM) evaluates how best to meet a region’s district heating (DH) needs using a portfolio of supply technologies, ranging from boilers and heat pumps to CHP, waste‑to‑energy, solar thermal, and excess heat.
In dispatch mode, the module takes pre‑installed capacities and solves an hourly linear optimisation to minimise operating costs (including fuel, electricity, and CO₂ costs) while respecting network temperature constraints.
In investment + dispatch mode, the model simultaneously determines optimal capacity expansions and dispatch schedules to cover the annual load at lowest total cost. Users specify economic assumptions (investment cost, lifetimes, interest rate, CO₂ price) alongside demand and price profiles.
The method described here is to be understood as a first concept and can deviate from the actual implementation (model complexity, inputs and outputs, etc., must be seen from this point of view). This wiki page explains the version of the calculation module that is integrated into the toolbox. A stand-alone version of the calculation module is much more comprehensive and can be downloaded from here. This version requires, however, basic knowledge of Python programming. The documentation of the stand-alone version can be found here.
Inputs
District Heating Supply CM relies on various inputs. Some inputs are provided directly by the platform through its layers, while others come with default values that can be modified by users. Below is the summary of the main input parameters used by the model: - District heating demand of the grid (selected region) - Installed capacities of heat generators - Technical (efficiencies) and financial parameters(OPEX, CAPEX, lifetime) of heat generators - Profiles (time series of the heat demand, solar radiation, temperature, electricity prices, etc.)
The inputs are organized into several levels, ranging from the most basic to the most advanced. The following subsections give an complete list of inputs by their level.
1. Inputs
The first level of input parameters is referred to as "INPUTS," which consists of the fundamental input parameters.
| Input Name | Default | Min | Max | Options | Description |
|---|---|---|---|---|---|
| Thermal output capacity | 0 | 0 | 1e+102 MW_th | (Per technology) Existing installed capacity. | |
| Max. installed capacity in investment mode | 0 | 0 | 1e+102 MW_th | (Per technology) Maximum investment capacity (0 = no limit). | |
| CO₂ Price (EUR/tCO₂) | 150 | 0 | 1e+102 | Sets the CO₂ emission cost factor. | |
| Interest rate (%) | 4 | 0 | 100 | Used to calculate the annuity factor. | |
| Mode of operation | Investment + dispatch | – | – | Investment + dispatch, Dispatch only | “Investment + dispatch” allows new capacity investments; “Dispatch only” runs existing capacities. |
| District heating demand (incl. grid losses) (MWh) | 0 | 0 | 1e+102 | Total heating demand including network losses. | |
| Average electricity price (EUR/MWh) | 100 | -1e+102 | 1e+102 | Used with the default hourly profile. |
2. Basic Inputs
| Input Name | Default | Min | Max | Options | Description |
|---|---|---|---|---|---|
| Max. flow temperature (°C) | 70 | 0 | 150 | Maximum flow temperature of the district heating network. | |
| Min. flow temperature (°C) | 60 | 0 | 150 | Minimum flow temperature of the district heating network. | |
| Max. return temperature (°C) | 45 | 0 | 150 | Maximum return temperature of the district heating network. | |
| Min. return temperature (°C) | 40 | 0 | 150 | Minimum return temperature of the district heating network. | |
| Thermal efficiency | varies | 0 | 1.0 | (Per technology) e.g. CHP 0.76, Boiler 0.875, Solar 1. | |
| Electrical efficiency | varies | 0 | 1.0 | (Per technology with electricity output) e.g. CHP 0.14, Incineration 0.2. | |
| Lifetime (years) | varies | 0 | 100 | (Per technology) e.g. CHP 28 a, Heat Pump 25 a, Excess Heat 20 a. | |
| Energy carrier | – | – | wood pellets; electricity; bio gas; waste; radiation; excess heat; various | (Per technology) Select each technology’s fuel/input. |
3. Advanced Inputs (Level 1)
The table below lists the inputs in the Advanced Inputs (Level 1) category, which include emissions, energy carrier prices, and electricity pricing.
| Input Name | Default | Min | Max | Options | Description |
|---|---|---|---|---|---|
| Emission factor (tCO₂/MWh) | varies | -1e+102 | 1e+102 | (Per energy carrier) e.g. bio gas 0.126, electricity 0.025, others as specified. | |
| Energy carrier price (EUR/MWh) | varies | -1e+102 | 1e+102 | (Per energy carrier) e.g. waste 3; wood pellets 44; bio gas 40; excess heat 5; various 22. | |
| Electricity price (select) | hotmaps default hourly profile | – | hotmaps default hourly profile; fix | (Per technology) Method for purchase price. | |
| Fixed electricity price (EUR/MWh) | 45 | -1e+102 | 1e+102 | (Per technology if “fix”) Fixed purchase price. | |
| Sale electricity price (select) | hotmaps default hourly profile | – | hotmaps default hourly profile; fix | (Per technology with export) Method for sale price. | |
| Fixed sale electricity price (EUR/MWh) | 45 | -1e+102 | 1e+102 | (Per technology if “fix”) Fixed sale price. |
4. Advanced Inputs (Level 2)
The table below lists the inputs in the Advanced Inputs (Level 2) category, which include investment & operational cost parameters.
| Input Name | Default | Min | Max / Units | Options | Description |
|---|---|---|---|---|---|
| Investment cost (EUR/MW_th) | varies | 0 | 1e+102 | (Per technology) e.g. CHP 1 055 000; Incineration 3 200 000; Boiler 107 000; etc. | |
| OPEX fix (EUR/(MW·yr)) | varies | 0 | 1e+102 | (Per technology) Annual fixed operational cost. | |
| OPEX var (EUR/MWh) | varies | 0 | 1e+102 | (Per technology) Variable cost per MWh. | |
| Ramping cost (EUR/MWh) | varies | 0 | 1e+102 | (Per technology with ramp constraints) Applicable to CHP and waste incineration. |
Outputs
Upon completion of a simulation, the District Heating Supply CM generates a comprehensive set of outputs that provide insights into the technical and economic performance of the DH system. These outputs are accessible through the Citiwatts platform and are also available for download in various formats.
The main output indicators of the calculation module are: - Heat generation costs - Investment, operation and fuel costs - Heat generation mix per heat generator - CO2 Emissions - Full Load Hours
Platform Indicators
Within the Citiwatts platform, key performance indicators (KPIs) are presented to offer a quick overview of the simulation results:
| Indicator | Unit | Description |
|---|---|---|
| Total LCOH | EUR/MWh | Levelized Cost of Heat: the average cost per megawatt‑hour of thermal energy produced. |
| Annual Total Costs | EUR/yr | Sum of all annual costs (investment annuity, O&M, fuel, CO₂, ramping). |
| Total Revenue From Electricity | EUR/yr | Total revenue earned from electricity sales. |
| Total Thermal Generation | MWh/yr | Total thermal energy produced in one year. |
| Total Electricity Generation | MWh/yr | Total electrical energy produced in one year. |
| Total Investment Costs | EUR/yr | Annualized investment cost across all technologies. |
| Total O&M Costs | EUR/yr | Total fixed and variable operation & maintenance costs per year. |
| Total Fuel Costs | EUR/yr | Total annual cost of all fuel inputs. |
| Total CO₂ Costs | EUR/yr | Annual cost associated with CO₂ emissions (at the chosen CO₂ price). |
| Total Ramping Costs | EUR/yr | Annual cost incurred by ramping up/down dispatchable units. |
| Total CO₂ Emissions | t/yr | Total CO₂ emitted per year by all technologies. |
| Total Heat Demand | MWh/yr | Annual district heating demand (including grid losses). |
| Total Final Energy Demand | MWh/yr | Total energy used (input) to satisfy the DH demand. |
| NUTS‑level profiles used | – | Regions used for heat‑load and electricity‑price time series. |
| Peak heat load | MW | Maximum instantaneous heat load in the district heating network. |
Charts
In addition to the indicators, several charts are available in the "Charts" tab. These charts provide a breakdown of the overall system-level indicators by technology or energy carrier, allowing for a more detailed comparison.
Additional Output Files
Beyond the summary indicators shown on the platform, the module generates a ZIP archive containing a load duration curve plot in PNG format and an Excel workbook with detailed outputs. This workbook allows you to dig deeper into time‑series data and technology breakdowns:
-
Load Duration Curve Plot (.png) A high‑resolution image of the sorted hourly district‑heating load (stacked by technology).
-
Excel Report (.xlsx) A multi‑sheet workbook with:
-
Load Profile Hourly district‑heating load sorted into a duration curve.
-
Electricity Price Profile Time series of the purchase price used for each hour (default hourly profile or your fixed value).
-
Sale Electricity Price Profile Time series of the sale price used for each hour (default hourly profile or your fixed value).
-
Thermal Generation Mix Hourly split of thermal generation by technology.
Users can use these outputs for detailed plots, custom analysis, and integration with your own tools.
Method
The module is implemented as a linear program and can be used on the one hand as a pure dispatch model and on the other hand for investment planning to cover a load profile. The objective function aims to minimise the difference between heat generation costs and electricity production revenues.
Equation fragments of the linear program:
The total costs ctotal yield from the sum of:
investment costs IC (installed capacities multiplied by the annuities of the specific investment costs)
captial costs CC :
the variable costs OPEX :
ramp costs of CHP and waste incineration plants (rough Estimation) :
assumed costs for the peak electrical load in the winter time (rough Estimation):
The total revenues revtotal yield from::
the sale of electricity (for example from CHP plants and waste incineration plants).:
Legend
GitHub Repository Of This Calculation Module
You can access the open-source code for this calculation module here.
Sample Run
WARNING: The model does not a have default DH demand assumption. The users should provide it. Otherwise, the model will raise the error: "Notification: The annual DH demand is zero. Please provide a valid demand value".
The "District heating demand (incl. grid losses)" input parameter can be found at the bottom of the "INPUTS" section.
Step 1: Select the region
The DH Supply CM works on all geographical levels provided by the platform. Please note that the chosen area will be treated as a single-connected DH system.
Select the LAU2 region Vienna for this sample run.
Figure CM - District Heating Supply: Selection of the working region (LAU2)
Step 2: Enter the input parameters
After selecting the region, users should click on the "Calculation Modules" tab located in the left pane. Next, click on "CM - District Heating Supply" to display the input options.
The inputs are organised into several levels, ranging from the most basic to the most advanced. The first level of input parameters is referred to as "INPUTS," which consists of the fundamental input parameters. The full list of parameters in this category, along with their default, maximum, and minimum values and descriptions, can be found in Table: Inputs.
Enter the DH Demand parameter of 3000000 MWh for this sample run.
Figure CM - District Heating Supply: Selection of the input parameters
Step 3 (optional): Enter the basic input parameters
After scrolling down in the inputs section, users will find the "Basic Inputs" category. The full list of parameters in this category, along with their default, maximum, and minimum values and descriptions, can be found in Table: Basic Inputs.
Figure CM - District Heating Supply: Selection of the basic input parameters
Step 4 (optional): Enter the advanced input parameters (level 1)
After further scrolling down in the inputs section, the user will find the "ADVANCED INPUTS: (LEVEL 1)" category. The full list of parameters in this category, along with their default, maximum, and minimum values and descriptions, can be found in Table: Advanced Inputs (level 1).
Figure CM - District Heating Supply: Selection of the advanced input parameters (level 1)
Step 5 (optional): Enter the advanced input parameters (level 2)
After further scrolling down in the inputs section, the user will find the "ADVANCED INPUTS: (LEVEL 2)" category. The full list of parameters in this category, along with their default, maximum, and minimum values and descriptions, can be found in Table: Advanced Inputs (level 2).
Figure CM - District Heating Supply: Selection of the advanced input parameters (level 2)
Step 6: Run the CM and retrieve the results
Indicators
Users can start the calculation by scrolling down to the bottom of the inputs section and clicking on the "RUN CM" button. The calculation might take from a few seconds to up to a few minutes, depending on the complexity of the problem. Then, a results tab will appear on the right-hand side of the screen. In this tab, the main indicators are displayed to offer a quick overview of the simulation results. The full list of indicators, alongside their units and descriptions, is available in Table: Platform Indicators.
Figure CM - District Heating Supply: Indicators displayed on the platform
The users also have the option to export results. The buttons to export results are located at the bottom of the INDICATORS section. There are two methods available for exporting the results:
1. Exporting indicators Click EXPORT INDICATORS to download a CSV file containing all of the summary indicators shown on the platform (LCOH, total costs, generation volumes, etc.).
2. Exporting detailed results Click EXPORT EXTRA FILES to download a ZIP archive with two files:
-
Excel Report (.xlsx) Contains four worksheets—Load Profile, Electricity Price Profile, Sale Electricity Price Profile, and Thermal Generation Mix—so you can explore the full time‑series and breakdowns in your spreadsheet tool of choice.
-
Load Duration Curve Plot (.png) A high‑resolution image of the sorted hourly heating load by technology for quick inclusion in presentations or reports.
Charts
By clicking on "CHARTS" (just next to the "INDICATORS"), users can display the charts generated by the CM.
The users also have the option to download the underlying data behind the charts. The button to export charts are located at the bottom of the CHARTS section.
Figure CM - District Heating Supply: Charts on the platform
References
How To Cite
Ali Kök, in CitiWatts-Wiki, CM DH Supply. Go To Top
Authors And Reviewers
This page is written by Ali Kök EEG-TU Wien.
License
Copyright © 2025: Ali Kök
Creative Commons Attribution 4.0 International License
This work is licensed under a Creative Commons CC BY 4.0 International License.
SPDX-License-Identifier: CC-BY-4.0
License-Text: https://spdx.org/licenses/CC-BY-4.0.html