NGCI-DHN: District Heating Network Analysis

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

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 dhn_creator create --config configs/dhn_creator_example.json

• 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.
• configs/dhn_creator_example.json: working example configuration.

Configuration 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.

Python 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.