NGCI-DHN: District Heating Network Analysis

Tools for creating and analyzing district heating networks from building footprints and road networks. Provides a CLI.

Two commands over one engine:

• ngci-dhn create: the creator. Builds a network from footprints and roads, sizes its pipes, renders and exports it for the front-end (the API calls run_create).
• ngci-dhn run: the pipeline. One configuration file runs screen, demand, layout, size, simulate, check and evaluate and writes a workspace with a manifest (input hashes, versions, per-stage status, artefact hashes, KPIs).

Both are built on the same stage functions and the data contract of docs/CONTRACT.md (ngci_dhn.model, ngci_dhn.ports), one feature package per stage: road_processing (screen), creation (layout), sizing (reduce, size), operation (simulate, check), economics (evaluate), with adapters in data_fetching and demand.

ngci-dhn validate-config tests/fixtures/toy_district/config.json
ngci-dhn run --config tests/fixtures/toy_district/config.json --workspace outputs/toy

docs/CONFIG.md describes both configuration schemas, docs/OUTPUTS.md the workspace and the conventions behind the KPI block, docs/CONTRACT.md the types, ports and every engineering decision with its date. Fixtures: tests/fixtures/toy_district (a synthetic year), tests/fixtures/st_jerome (real roads with 0.25 m vertices), tests/fixtures/destest_ce1 (the IBPSA DESTEST pipe classes).

Overview

This project builds a district heating network by:

1. Selecting buildings within a radius around a center point.
2. Validating building attributes and deriving heights.
3. Preparing a road network (from a file or OSM download).
4. Creating a network graph (exported as image and/or GeoJSON) and sizing pipes.

Quickstart

1. Create a virtual environment and install dependencies.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt

2. Install the package (to enable the ngci-dhn CLI entrypoint).

pip install -e ".[dev]"

3. Run the example workflow.

ngci-dhn create --config configs/dhn_creator_example.json --output outputs/dhn_creator_demo --plot

CLI Usage

• Main workflow:

ngci-dhn create --config configs/dhn_creator_example.json --output outputs/dhn_creator_demo

• Alternative (no editable install):

python -m ngci_dhn create --config configs/dhn_creator_example.json --output outputs/dhn_creator_demo

• Output directory and log level:

ngci-dhn create --config configs/dhn_creator_example.json --output outputs/run_01 --log-level DEBUG

Notes:

• pip install -e . is only needed once per environment, and only if you want the ngci-dhn command.

Documentation

• docs/CONFIG.md: configuration reference with fields and defaults.
• docs/OUTPUTS.md: output files and logs.
• docs/METHODS.md: how each stage works: assumptions, typical values and the reasons behind them.
• configs/dhn_creator_example.json: working example configuration.

Configuration

Creator inputs

The JSON config is organized into creator, city, and factory steps. city and factory are optional; if omitted they are skipped. The output directory is provided via CLI --output. See the example at configs/dhn_creator_example.json. Legacy config keys (inputs, selection, roads_download, etc.) are no longer supported.

Key sections:

• creator: inputs, selection, building validation, plants, and roads settings.
• city: EnergyPlus settings (optional).
• factory: pipe sizing settings (optional).

Dataset note:

• If you want Montreal buildings/roads data, you can download the dataset here:

https://ngci.encs.concordia.ca/ckan/dataset/dhn-building-and-road-data

• Once downloaded, point creator.inputs.buildings and creator.inputs.roads in configs/dhn_creator_example.json to the local files.

Overpass API

The ngci-dhn downloads road network open data through osmnx, which depends on a public Overpass API instance (https://overpass-api.de). This is perfect for small, experimental use because it requires no environment setup. However, for high-volume use, we strongly recommend you run a local Overpass API instance with Docker. To use in ngci-dhn, please set the environment variable OVERPASS_URL. For example, in Linux:

export OVERPASS_URL="https://your_overpass_instance"

Python API

You can use the ngci-dhn package via CLI or API. See https://ngci.encs.concordia.ca/gitea/CERC/district_heating_network_api

Project Structure

• src/ngci_dhn/: core package, CLI, workflow, and utilities.
• configs/: example configuration files.
• docs/: configuration and outputs documentation.
• scripts/: helper scripts for data prep and rendering.
• tests/: pytest suite and fixtures.

Testing

Run the tests from the repo root:

pytest

Notes:

• If creator.inputs.roads is missing or not found, the workflow downloads roads from OpenStreetMap via OSMnx (when enabled).
• Plot output is saved as network-graph.png when --plot is enabled.

Citation

If you use this software in your research, please cite it. A CITATION.cff file is included; you can also use the BibTeX entry below:

@software{rezaei_dhn_analysis,
  author  = {Rezaei, Abolfazl},
  title   = {District Heating Network Analysis},
  year    = {2026},
  version = {0.0.0},
  license = {LGPL-3.0-or-later},
  url     = {https://ngci.encs.concordia.ca/gitea/a_rezaei/district_heating_network_analysis}
}

License

This project is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). The LGPL incorporates the terms of the GNU GPL v3.0 by reference. See LICENSE for the LGPL text and LICENSE.GPL for the GPL text.

Copyright © 2025-2026 Next-Generation Cities Institute, Concordia University.