Metadata-Version: 2.5
Name: urban-heat-island-utac
Version: 1.0.0
Summary: Real surface urban heat island, park cooling, and city-scale green-roof air-temperature science -- no UTAC/CREP/AFET bridge
Project-URL: Homepage, https://github.com/GenesisAeon/urban-heat-island-utac
Project-URL: Repository, https://github.com/GenesisAeon/urban-heat-island-utac
Author: Römer, Johann
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# urban-heat-island-utac

GenesisAeon Package 132 - real **surface** urban heat island (MODIS LST),
park cooling, impervious-surface vs LST relationship structure, and
city-scale green-roof **ambient air**-temperature mitigation. **Deliberately
has no UTAC/CREP/AFET bridge** - see [DISCLAIMER.md](DISCLAIMER.md).

For a plain-language explanation of the same topic (German, no jargon,
written for general audiences), see [WHITEPAPER.md](WHITEPAPER.md).

## Separate from P108

This is **not** an extension of
[`urban-green-infrastructure-utac`](https://github.com/GenesisAeon/urban-green-infrastructure-utac)
(P108). P108 is hydrology only (sealing vs recharge; green-roof rainfall
retention). P132 is temperature (evaporative cooling / albedo / radiation
balance) - same precedence as the P107/P108 split itself.

## What's real here

- **Peng et al. (2012, *Environmental Science & Technology*)** - annual-mean
  **surface** UHI across 419 cities (MODIS LST): day **1.5 ± 1.2 °C**,
  night **1.1 ± 0.5 °C**. Day and night are uncorrelated. This is
  **surface** temperature, not air temperature.
- **Bowler et al. (2010, *Landscape and Urban Planning*)** - systematic
  review: parks are on average **0.94 °C** cooler (daytime) than
  surrounding built area.
- **Yang, Huang, Yang, Liu (2021, *Environmental Research Letters*)** -
  LST vs artificial impervious surface fraction across 682 cities. Cited
  as core structure; the **regression coefficient is intentionally unset**
  until pinned from the primary text (the build prompt does not list the
  slope number - inventing it is forbidden).
- **Santamouris (2014, *Solar Energy*)** - green roofs at city scale:
  **0.3-3.0 K** reduction of mean ambient **air** temperature (not LST,
  not indoor).

## Explicitly not used

- De Cristo et al. (2025) - documented-tier note only; **no** numeric
  constants from it.
- Unverified Phoenix ~1.5 °C / New York ~2.5 °C green-roof case studies
  (no DOI in source prompt) - excluded.

## Quickstart

```bash
pip install urban-heat-island-utac
```

```python
from urban_heat_island_utac import (
    uhi_surface_day_c_mean,
    uhi_surface_night_c_mean,
    park_daytime_cooling_c_mean,
    green_roof_cityscale_air_temp_reduction_k_range,
    yang_2021_lst_vs_impervious_slope,
    is_uhi_a_single_universal_value,
    is_surface_temperature_the_same_as_air_temperature,
)

print(uhi_surface_day_c_mean())          # 1.5  (SURFACE / LST)
print(uhi_surface_night_c_mean())        # 1.1  (SURFACE / LST)
print(park_daytime_cooling_c_mean())     # 0.94
print(green_roof_cityscale_air_temp_reduction_k_range())  # (0.3, 3.0) AIR
print(yang_2021_lst_vs_impervious_slope())  # None until pinned
print(is_uhi_a_single_universal_value())  # False
print(is_surface_temperature_the_same_as_air_temperature())  # False
```

## Development

```bash
pip install -e ".[dev]"
ruff check src tests
mypy src
pytest
```

## Citation

See [CITATION.cff](CITATION.cff) and [.zenodo.json](.zenodo.json).
