topotherm is a pyomo-based open-source optimization model for district heating network design.

Topotherm is a pyomo-based mixed-integer linear programming district heating network design model which scales well into larger districts for single and mulitple time steps. It has been benchmarked against multiple other open-source models in a publication available at:

Lambert, Jerry and Ceruti, Amedeo and Spliethoff, Hartmut, Benchmark of Mixed-Integer Linear Programming Formulations for District Heating Network Design. Energy, Volume 308, 2024, 132885, ISSN 0360-5442, https://doi.org/10.1016/j.energy.2024.132885

• Single time-step topology and piping optimization.
  • Multiple time-steps version additionally includes operation with variable heating demands.
  • Greenfield optimization
  • Existing network in development.
• Forced and economic expansion of the district heating network to consumers.
• Supports all solvers of pyomo, but the output helper functions in utils.py might have to be rewritten (utils.py)
• Plotting functions included

• topotherm
  • Intro
  • Feature overview
  • Contents
  • Description
  • Why should I use this?
  • How to cite
  • Getting Started
    • Requirements
  • Install
    • Python
    • Anaconda or mamba
  • Solver
    • Gurobi
    • Open-source Alternatives
  • Usage
  • Contribute
  • Tests
  • License

To run the model, several incidence matrices have to be formulated. Then, the linear regression parameters can be calculated for a given supply, ambient and return temperature of the network. A pyomo model is then set up and solved with the solver of your choice.

Topotherm has the best scaling properties of multiple open-source models and has been benchmarked and validated.

Lambert, Jerry and Ceruti, Amedeo and Spliethoff, Hartmut, Benchmark of Mixed-Integer Linear Programming Formulations for District Heating Network Design. Energy, Volume 308, 2024, 132885, ISSN 0360-5442, https://doi.org/10.1016/j.energy.2024.132885

This repository needs a PC capable to run python and its standard libraries.

• Anaconda, mamba or venv

Use git to clone this repository into your computer. Then, install topotherm with a package manager such as Anaconda, or directly with Python.

git clone https://github.com/jylambert/topotherm.git

cd topotherm
python setup.py install

This can also be done with venv or equivalent.

We recommend to install the dependencies with anaconda or mamba:

cd topotherm
mamba env create -f environment.yml -n topotherm
mamba activate topotherm

The results in the paper were obtained with the commercial solver gurobi. A free academic license is available and can be installed by following the documentation here.

You can try the code on smaller benchmarks with several open source solvers, such as SCIP. Other popular open-source options are COIN-OR's cbc or HiGHS.

mamba activate topotherm
mamba install -c conda-forge pyscipopt

Generate the input incidence matrices for the district with .parquet format (see example). Then, modify and run the either one of the three scripts in that folder.

cd example
python run_sts.py

Pull requests and any feedback regarding the code are very welcome. For major changes, please open an issue first to discuss what you would like to change.

To run the tests, use pytest.

pip install .[dev]
pytest tests

MIT, see LICENSE file.