Metadata-Version: 2.5
Name: ngci-dhn
Version: 0.1.0
Summary: District heating network analysis and CLI workflows
Author-email: Abolfazl Rezaei <abolfazl.rezaei@mail.concordia.ca>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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`](CITATION.cff) file is included; you can also use the BibTeX entry below:
```bibtex
@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](LICENSE) for the LGPL text and [LICENSE.GPL](LICENSE.GPL) for the GPL text.

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