GSCC — Global Source-Conditioned Conductance–Circuit Method

Reference implementation of the GSCC method for mapping relative urban ventilation capacity from building morphology.

GSCC takes an aligned urban-morphology raster, a prescribed meteorological wind-from direction, and configuration values, and returns a direction-specific relative circuit-constrained ventilation-capacity field. Each inlet source's cumulative least-cost path history is turned into a reciprocal conductance contribution, the contributions are summed into a whole-domain conductance prior, and that prior weights a four-neighbour graph for a normalized boundary-value (circuit) solution whose incident edge transfers are read out as the capacity field.

The output is a relative ordering of the mapped domain — it is not local wind speed, physical ventilation volume, or a CFD-equivalent field.

This repository accompanies:

Gao, K., He, Y., & Ng, E. — Mapping Relative Urban Ventilation Capacity with a Global Source-Conditioned Conductance–Circuit Method (manuscript under review; see CITATION.cff).

The source-conditioned cumulative-path construction builds on the prior least-cost-path method:

He, Y., Gao, K., et al. (2026). A meter-level resolution least-cost-path method for fast urban ventilation assessment: Preliminary validation using CFD and wind tunnel. Building and Environment, 301, 114774. https://doi.org/10.1016/j.buildenv.2026.114774

---

Installation

Requires Python ≥ 3.10.

git clone https://github.com/nikegoose/GSCC.git
cd GSCC
pip install -e .

Optional extras:

pip install -e ".[dev]"         # pytest, pytest-cov, pytest-xdist
pip install -e ".[urbantales]"  # xarray + h5netcdf (UrbanTALES NetCDF readers)
pip install -e ".[gis]"         # rasterio, fiona, shapely, geopandas

The wind-tunnel Excel 97-2003 workbook additionally requires xlrd, imported lazily by gscc/io/wt_loader.py.

Quick start (no external data)

python examples/01_toy_grid_demo.py
python examples/02_synthetic_block_demo.py
python examples/03_inlet_outlet_demo.py

These build synthetic grids, print intermediate least-cost and conductance values, and save diagnostic figures under outputs/debug/.

Reproducing the CFD-21 evaluation (data bundled)

The 21-layout CFD evaluation inputs are included under data/cfd21/ (pattern_id N in the code corresponds to "Layout N" in the article):

python scripts/cfd21/run_cfd21_validation.py --n-jobs 8

This writes results, figures, and CFD21_VALIDATION_REPORT.md under outputs/validation_cfd21/. Related scripts: run_cfd21_z40_validation.py (z = 40 m elevated plane), run_cfd21_calibration.py (regularizer sensitivity), run_cfd21_pattern_comparison.py (per-layout figures), run_cfd21_summary_report.py, and run_cfd21_vector_validation.py (diagnostic graph-flux vector). examples\run_cfd21_suite.bat chains the main four on Windows.

Method → code map

Paper object (equation)	Code location
Morphology raster and passable mask	gscc/io/raster_grid.py, gscc/io/synthetic.py
Relative morphological resistance ρ(x)	gscc/resistance/ (cost_map.py, wall_friction.py)
Direction-specific circular boundary and source set S_θ	gscc/inlet/ (oblique.py, boundary.py)
Source-conditioned resistance R_s,θ — Eq. (1)	gscc/pathfinding/engine.py (LCPEngine, on skimage.graph.MCP_Geometric)
Reciprocal contributions g_s,θ and prior G_θ — Eqs. (2)–(3)	gscc/conductance/gscc_core.py
Harmonic edge mapping, circuit solve, capacity readout — Eqs. (4)–(7)	gscc/flow/conductance_flow.py
Diagnostic graph-flux vector q_θ	gscc/flow/vector_flux.py
Correspondence / ordering metrics	gscc/validation/metrics.py

Terminology: code keys ↔ paper terms

The code predates the article's final terminology; configuration keys are kept stable so that recorded configurations remain reproducible.

Code key / name	Paper term
uvp, "UVP" (accessibility field)	whole-domain relative conductance prior G_θ ("ventilation potential" gloss)
circuit-flow output (incident flux magnitude)	relative ventilation-capacity field F_θ
rf_only	morphology-resistance-only source histories (working construction, Table 2)
rf_plus_turning, dp_turning	optional turning-penalty variants
harmonic	harmonic edge mapping, Eq. (4)
M1 / M2 / M3	axis-aligned edge / rotated-polygon / circular boundary constructions (the circular construction is the adopted one)
arc_width_deg = 180	180° inlet arc (working reference)
R0 / r0	reciprocal regularizer r₀
pattern_id 1–21 (CFD-21)	Layout 1–21
patterns A–H (wind tunnel)	Patterns A–H
rho_A* columns	within-unit spatial correspondence (internal Spearman variant)
rho_B* columns	cross-unit ordering (internal Spearman variant)

The article's reported statistics use block-median correspondence and cluster-aware inference on top of these fields; the recorded working configuration is rf_only histories, harmonic mapping, 180° arc, r₀ = 0.001. Central algorithmic constants live in gscc/constants.py.

Repository structure

gscc/                 Python package (the reference implementation)
  io/                 raster/vector I/O and dataset loaders
  resistance/         morphology-conditioned resistance construction
  inlet/              direction-specific boundary and source generation
  pathfinding/        least-cost engines (Dijkstra / MCP), turning penalties
  conductance/        reciprocal aggregation into the conductance prior
  flow/               circuit solve and capacity/vector readouts
  validation/         dataset comparison pipelines and metrics
  analysis/, viz/     derived maps, figures
constants.py          (gscc/constants.py) central algorithmic constants
examples/             runnable demos (synthetic first, then dataset demos)
scripts/              validation and sensitivity drivers per dataset
  cfd21/  urbantales/  windtunnel/  sensitivity/
tests/                pytest suite (unit + integration)
data/cfd21/           bundled CFD-21 evaluation inputs (see data/README.md)
outputs/              created at runtime; not tracked

Datasets

See data/README.md: CFD-21 is bundled; UrbanTALES is a third-party published dataset (obtain from its source and place under data/urbantales/); the wind-tunnel measurements cannot be redistributed; the legacy CFD-12 set is available on request.

Tests

pip install -e ".[dev]"
pytest

Tests that need an absent optional dataset skip automatically. The critical marker gates pathfinding correctness; slow marks long-running validation tests.

License and citation

MIT License (see LICENSE). If you use this software, please cite the article and/or the software as given in CITATION.cff.

Corresponding author of the accompanying articles: Kai Gao (gaolingxuan@gmail.com) & Yueyang He (yueyanghe@cuhk.edu.hk). Issues and questions are welcome on the repository issue tracker.