pet-adjusted 0.1.5__py3-none-any.whl

pet_adjusted/__init__.py

@@ -0,0 +1,115 @@
+"""PET with urban-adjusted air temperature and 1.2 m wind speed.
+
+PET uses a GPU/array port of ``pythermalcomfort.models.pet_steady`` (Tartarini & Schiavon,
+pythermalcomfort, SoftwareX 2020), which implements Höppe's MEMI with the corrections of
+Walther & Goestchel (2018). See pet.py.
+"""
+
+from datetime import date
+
+import numpy as np
+
+from .air_temperature import diurnal_factor, is_daytime, uhi_max, urban_air_temperature
+from .backend import gpu_available
+from .morphology import LC_BUILDING, classify, uhi_inputs, wind_inputs
+from .pet import pet_steady
+from .svf import sky_view_factor
+from .tmrt import read_raster, solweig_tmrt, write_raster
+from .wind import urban_wind_speed, wind_reduction
+
+__all__ = [
+    "classify", "diurnal_factor", "gpu_available", "is_daytime", "pet_map", "pet_netherlands", "pet_steady", "read_raster",
+    "sky_view_factor", "solweig_tmrt", "uhi_inputs", "uhi_max", "urban_air_temperature", "urban_pet", "urban_pet_from_rasters",
+    "urban_wind_speed", "wind_inputs", "wind_reduction", "write_raster",
+]
+
+
+def urban_pet(
+    t_ref, tr, rh, ff10, met, clo, *,
+    svf, fveg, s_down, tmax, tmin, u_mean, day: date, hour_utc,
+    lambda_b, lambda_t, h,
+    device="auto",
+    **pet_kwargs,
+):
+    """PET [°C] with Ta from the UHI model and v as the scaled 1.2 m urban wind.
+
+    t_ref, rh, ff10: reference station air temperature [°C], RH [%], 10-m wind [m/s].
+    tr: mean radiant temperature [°C]. met [met], clo [clo] as in pet_steady.
+    svf, fveg, s_down, tmax, tmin, u_mean, day, hour_utc: see urban_air_temperature.
+    lambda_b, lambda_t, h: see urban_wind_speed.
+    device: backend for all steps ("auto", "cpu", "gpu").
+    pet_kwargs: passed to pet_steady (p_atm, position, age, sex, weight, height, wme, chunk_size).
+    """
+    ta = urban_air_temperature(t_ref, svf, fveg, s_down, tmax, tmin, u_mean, day, hour_utc, device)
+    v = urban_wind_speed(ff10, lambda_b, lambda_t, h, device)
+    return pet_steady(ta, tr, v, rh, met, clo, device=device, **pet_kwargs)
+
+
+def urban_pet_from_rasters(
+    dsm, dem, ndvi, cell_size, *,
+    tr, t_ref, rh, ff10, wind_dir, met, clo,
+    s_down, tmax, tmin, u_mean, day: date, hour_utc,
+    svf=None, svf_radius_m=50.0, landcover=None, device="auto",
+    **pet_kwargs,
+):
+    """PET grid [°C] from DSM, DEM and NDVI rasters plus reference-station data for one hour.
+
+    dsm, dem, ndvi: 2D arrays on the same north-up grid, square cells of ``cell_size`` m.
+    tr: mean radiant temperature [°C], scalar or grid. wind_dir: direction the 10-m wind
+    comes from [degrees]. svf: sky-view factor grid if already computed (else from the DSM).
+    landcover: optional UMEP land-cover grid (see morphology.classify). The rest as in urban_pet. Cells with DSM/DEM nodata (NaN) come out NaN.
+    """
+    if svf is None:
+        svf = sky_view_factor(dsm, cell_size, radius_m=svf_radius_m, device=device)
+    svf_avg, fveg = uhi_inputs(dsm, dem, ndvi, cell_size, wind_dir, ff10,
+                               is_daytime(day, hour_utc), svf=svf, device=device, landcover=landcover)
+    lambda_b, lambda_t, h = wind_inputs(dsm, dem, ndvi, cell_size, wind_dir, ff10, device, landcover)
+    ta = urban_air_temperature(t_ref, svf_avg, fveg, s_down, tmax, tmin, u_mean, day, hour_utc, device)
+    v = urban_wind_speed(ff10, lambda_b, lambda_t, h, device)
+    nodata = ~(np.isfinite(dsm) & np.isfinite(dem))
+    return pet_steady(np.where(nodata, np.nan, ta), tr, v, rh, met, clo, device=device, **pet_kwargs)
+
+
+def pet_map(dsm, dem, landcover, ndvi, cell_size, origin, epsg, day: date, weather, subject, *,
+            workdir, hours=None, svf_radius_m=50.0, device="auto"):
+    """PET and Tmrt maps [°C] for one day, shape (n_hours, rows, cols) each.
+
+    dsm, dem, landcover, ndvi: 2D arrays on the same north-up grid (NaN = nodata), square
+    cells of ``cell_size`` m, upper-left corner ``origin`` (x, y) in EPSG ``epsg``.
+    landcover in UMEP codes (1 paved, 2 building, 3 evergreen, 4 deciduous, 5 grass,
+    6 bare soil, 7 water).
+    weather: mapping of hourly reference-station series for ``day`` (consecutive UTC hours,
+    ideally 0-23): hour_utc, t_ref [°C], rh [%], ff10 [m/s], wind_dir [°], kdown [W m-2] and
+    optionally p_atm [hPa]. Optional daily values for Eq. S.3: tmax, tmin [°C], s_down
+    [W m-2], u_mean [m/s]; by default they come from the series.
+    subject: person for pet_steady: met [met], clo [clo] and optionally age, sex, weight [kg],
+    height [m], position.
+    hours: UTC hours to return (default all hours in ``weather``).
+    Building cells (land cover 2) are NaN in both outputs: PET is for pedestrians.
+    Tmrt comes from SOLWEIG-GPU (see solweig_tmrt; inputs and outputs are kept in ``workdir``).
+    On Windows, call this under ``if __name__ == "__main__":``.
+    """
+    w = {k: np.asarray(v, dtype=float) for k, v in weather.items()}
+    hour_utc = w["hour_utc"].astype(int)
+    p_atm = np.broadcast_to(w.get("p_atm", 1013.25), hour_utc.shape)
+    tmrt = solweig_tmrt(dsm, dem, ndvi, cell_size, origin, epsg, day, hour_utc=hour_utc, t_ref=w["t_ref"],
+                        rh=w["rh"], ff10=w["ff10"], kdown=w["kdown"], p_atm=p_atm, wind_dir=w["wind_dir"],
+                        landcover=landcover, workdir=workdir)
+    # shortcut: daily values from this day's series; the paper uses 08 UTC to 07 UTC next day
+    tmax, tmin = w.get("tmax", w["t_ref"].max()), w.get("tmin", w["t_ref"].min())
+    s_down, u_mean = w.get("s_down", w["kdown"].mean()), w.get("u_mean", w["ff10"].mean())
+    svf = sky_view_factor(dsm, cell_size, radius_m=svf_radius_m, device=device)
+    idx = list(range(hour_utc.size)) if hours is None else [list(hour_utc).index(h) for h in hours]
+    pet = np.stack([
+        urban_pet_from_rasters(
+            dsm, dem, ndvi, cell_size, tr=tmrt[i], t_ref=w["t_ref"][i], rh=w["rh"][i], ff10=w["ff10"][i],
+            wind_dir=w["wind_dir"][i], s_down=s_down, tmax=tmax, tmin=tmin, u_mean=u_mean, day=day,
+            hour_utc=hour_utc[i], svf=svf, landcover=landcover, device=device, p_atm=p_atm[i], **subject,
+        )
+        for i in idx
+    ])
+    roof = np.asarray(landcover) == LC_BUILDING
+    return np.where(roof, np.nan, pet), np.where(roof, np.nan, tmrt[idx])
+
+
+from .netherlands import pet_netherlands  # noqa: E402 (uses pet_map above)

pet_adjusted/air_temperature.py

@@ -0,0 +1,75 @@
+"""Urban air temperature from a rural reference station (Koopmans et al. 2020, Building and Environment 181, 106984, supplement B2)."""
+
+from datetime import date
+
+import numpy as np
+
+from .backend import get_xp, to_numpy
+
+RHO_CP = 1.2 * 1005.0  # air density * heat capacity [J m-3 K-1]; W m-2 -> kinematic K m s-1
+
+# Table S.3: start date (month, day) of each period -> sunrise/sunset column (UTC).
+# The paper lists "1 April t/m 19 April" and "13 April t/m 20 April"; read as 1-12 April.
+_PERIODS = [
+    ((4, 1), "5/18"), ((4, 13), "5/19"), ((4, 20), "4/19"), ((5, 20), "4/20"),
+    ((5, 26), "3/20"), ((7, 11), "4/20"), ((7, 31), "4/19"), ((8, 22), "5/19"),
+    ((8, 31), "5/18"), ((9, 25), "5/17"), ((9, 28), "6/17"),
+]
+
+# Table S.4: UHI factor per UTC hour 0..23 for each sunrise/sunset column.
+_UHI_FACTORS = {
+    "6/17": [0.748, 0.667, 0.602, 0.525, 0.449, 0.281, 0.127, 0.063, 0.019, -0.015, -0.020, 0.000,
+             0.030, 0.065, 0.117, 0.205, 0.335, 0.532, 0.747, 0.906, 0.975, 1.000, 0.931, 0.849],
+    "5/17": [0.728, 0.640, 0.573, 0.490, 0.355, 0.150, 0.078, 0.025, -0.013, -0.020, -0.001, 0.025,
+             0.056, 0.090, 0.165, 0.270, 0.413, 0.600, 0.803, 0.920, 0.978, 1.000, 0.925, 0.830],
+    "5/18": [0.807, 0.704, 0.617, 0.533, 0.435, 0.227, 0.095, 0.032, -0.009, -0.020, -0.003, 0.020,
+             0.048, 0.080, 0.136, 0.215, 0.325, 0.485, 0.662, 0.849, 0.932, 0.979, 1.000, 0.918],
+    "5/19": [0.910, 0.780, 0.675, 0.590, 0.490, 0.320, 0.120, 0.040, -0.005, -0.020, -0.004, 0.016,
+             0.042, 0.071, 0.111, 0.176, 0.270, 0.386, 0.546, 0.716, 0.877, 0.941, 0.981, 1.000],
+    "4/19": [0.900, 0.757, 0.710, 0.543, 0.413, 0.150, 0.057, 0.000, -0.020, -0.005, 0.013, 0.037,
+             0.063, 0.090, 0.150, 0.222, 0.318, 0.450, 0.600, 0.762, 0.890, 0.950, 0.982, 1.000],
+    "4/20": [1.000, 0.888, 0.728, 0.609, 0.490, 0.256, 0.079, 0.007, -0.020, -0.006, 0.010, 0.033,
+             0.056, 0.082, 0.128, 0.184, 0.270, 0.366, 0.506, 0.651, 0.803, 0.901, 0.958, 0.983],
+    "3/20": [1.000, 0.866, 0.690, 0.560, 0.380, 0.107, 0.015, -0.020, -0.007, 0.007, 0.029, 0.050,
+             0.074, 0.108, 0.161, 0.228, 0.312, 0.424, 0.556, 0.695, 0.838, 0.911, 0.964, 0.984],
+}
+
+
+def _column(day: date):
+    if not 4 <= day.month <= 9:
+        raise ValueError("Table S.3 only covers 1 April - 30 September")
+    return [c for start, c in _PERIODS if (day.month, day.day) >= start][-1]
+
+
+def diurnal_factor(day: date, hour_utc):
+    """UHI correction factor (Tables S.3/S.4) for a date and UTC hour(s) 0-23."""
+    return np.asarray(_UHI_FACTORS[_column(day)])[np.asarray(hour_utc)]
+
+
+def is_daytime(day: date, hour_utc) -> bool:
+    """Between sunrise and sunset of Table S.3 (UTC)."""
+    sunrise, sunset = map(int, _column(day).split("/"))
+    return sunrise <= hour_utc < sunset
+
+
+def _uhi_max(xp, svf, fveg, s_down, tmax, tmin, u):
+    svf, fveg, s_down, tmax, tmin, u = (xp.asarray(a, dtype=float) for a in (svf, fveg, s_down, tmax, tmin, u))
+    return (2 - svf - fveg) * (s_down / RHO_CP * (tmax - tmin) ** 3 / u) ** 0.25
+
+
+def uhi_max(svf, fveg, s_down, tmax, tmin, u, device="auto"):
+    """Daily maximum UHI [K], Eq. S.3.
+
+    svf, fveg: source-area averaged sky-view factor and vegetation fraction [-].
+    s_down: mean daily downward shortwave radiation at the reference station [W m-2].
+    tmax, tmin: max/min reference temperature (08 UTC - 07 UTC next day) [°C or K].
+    u: mean reference wind speed over the same period [m s-1].
+    """
+    return to_numpy(_uhi_max(get_xp(device), svf, fveg, s_down, tmax, tmin, u))
+
+
+def urban_air_temperature(t_ref, svf, fveg, s_down, tmax, tmin, u, day: date, hour_utc, device="auto"):
+    """Urban air temperature [°C], Eq. S.4: T_ref + UHImax * diurnal_cycle[h]."""
+    xp = get_xp(device)
+    factor = xp.asarray(diurnal_factor(day, hour_utc))
+    return to_numpy(xp.asarray(t_ref, dtype=float) + _uhi_max(xp, svf, fveg, s_down, tmax, tmin, u) * factor)

pet_adjusted/backend.py

@@ -0,0 +1,29 @@
+"""Array backend: CuPy on a CUDA GPU when available, otherwise NumPy."""
+
+import numpy as np
+
+try:
+    import cupy as cp
+
+    _GPU = cp.cuda.runtime.getDeviceCount() > 0
+except Exception:  # CuPy not installed, or no CUDA driver/device
+    cp, _GPU = None, False
+
+
+def gpu_available() -> bool:
+    return _GPU
+
+
+def get_xp(device="auto"):
+    """Array module for ``device``: "auto" (GPU if available), "cpu" or "gpu"."""
+    if device not in ("auto", "cpu", "gpu"):
+        raise ValueError(f"device must be 'auto', 'cpu' or 'gpu', got {device!r}")
+    if device == "cpu" or (device == "auto" and not _GPU):
+        return np
+    if not _GPU:
+        raise RuntimeError("device='gpu' requested but CuPy/CUDA is not available")
+    return cp
+
+
+def to_numpy(a):
+    return cp.asnumpy(a) if cp is not None and isinstance(a, cp.ndarray) else np.asarray(a)

pet_adjusted/morphology.py

@@ -0,0 +1,152 @@
+"""UHI and wind inputs derived from DSM, DEM and NDVI rasters.
+
+All rasters are 2D arrays on the same grid with square cells of ``cell_size`` metres and
+north up (row 0 = north). Source areas follow Fig. S.2 (air temperature) and Fig. S.3
+(wind): rectangles oriented to the wind, or squares around the cell when ff10 < 1.5 m/s.
+Source-area sums are FFT convolutions, so every cell gets its own source area (the paper
+computes on a 35 m grid and interpolates, only to save time).
+"""
+
+import numpy as np
+from scipy import ndimage, signal
+
+from .backend import get_xp, to_numpy
+from .svf import sky_view_factor
+
+NDVI_VEG = 0.16  # vegetation threshold (B1, B2)
+MIN_OBSTACLE = 2.0  # buildings and trees lower than this are ignored [m]
+LOW_WIND = 1.5  # [m/s] below this the source areas are squares
+TILE_M = 25.0  # intermediate Svf/Fveg grid for the air temperature (B2)
+
+
+# UMEP / SOLWEIG land-cover codes
+LC_PAVED, LC_BUILDING, LC_EVERGREEN, LC_DECIDUOUS, LC_GRASS, LC_BARE, LC_WATER = range(1, 8)
+
+
+def classify(dsm, dem, ndvi, landcover=None):
+    """Object height [m] and masks (building, tree, vegetation, water).
+
+    landcover: optional grid in UMEP codes (1 paved, 2 building, 3 evergreen, 4 deciduous,
+    5 grass, 6 bare soil, 7 water). With it, buildings and water come from the land cover;
+    without it, buildings are tall non-green cells and water is NDVI < 0.
+    """
+    height = np.asarray(dsm, dtype=float) - np.asarray(dem, dtype=float)
+    ndvi = np.asarray(ndvi, dtype=float)
+    veg = ndvi > NDVI_VEG
+    tall = height > MIN_OBSTACLE
+    if landcover is None:
+        water = ndvi < 0
+        building = tall & ~veg
+    else:
+        landcover = np.asarray(landcover)
+        water = landcover == LC_WATER
+        building = tall & (landcover == LC_BUILDING)
+    tree = tall & veg & ~building
+    return height, building, tree, veg, water
+
+
+def source_kernel(cell, wind_dir, upwind, downwind, half_width):
+    """1/0 mask of a source area around the centre cell.
+
+    wind_dir: direction the wind comes from [degrees from north]. The area reaches
+    ``upwind`` metres into the wind, ``downwind`` metres behind and ``half_width`` aside.
+    """
+    r = int(np.ceil(np.hypot(max(upwind, downwind), half_width) / cell))
+    rows, cols = np.mgrid[-r:r + 1, -r:r + 1] * cell
+    east, north = cols, -rows
+    th = np.radians(wind_dir)
+    along = east * np.sin(th) + north * np.cos(th)  # > 0 towards where the wind comes from
+    across = east * np.cos(th) - north * np.sin(th)
+    return ((along <= upwind) & (along >= -downwind) & (np.abs(across) <= half_width)).astype(float)
+
+
+def _area_sum(xp, field, kernel):
+    """Sum of ``field`` over the source area of every cell (zero outside the grid)."""
+    if xp is np:
+        conv = signal.fftconvolve
+    else:
+        import cupyx.scipy.signal
+
+        conv = cupyx.scipy.signal.fftconvolve
+    out = conv(xp.asarray(field, dtype=xp.float64), xp.asarray(kernel[::-1, ::-1]), mode="same")
+    return xp.maximum(out, 0.0)  # FFT round-off can give tiny negatives
+
+
+def uhi_inputs(dsm, dem, ndvi, cell_size, wind_dir, ff10, daytime, svf=None,
+               svf_radius_m=50.0, device="auto", landcover=None):
+    """Source-area averaged sky-view factor and vegetation fraction for Eq. S.3.
+
+    Svf excludes buildings, water and vegetation; water counts as vegetation by day and as
+    built-up at night. Per 25 m tile, Svf is nodata when more than 90% of it is excluded.
+    Over the source area: Svf = 1 when 10% or less of it has data, the plain mean above 20%,
+    and a linear blend in between. ``svf`` can be passed if already computed from the DSM.
+    landcover: optional UMEP land-cover grid (see classify).
+    Returns (svf, fveg) on the input grid.
+    """
+    height, building, tree, veg, water = classify(dsm, dem, ndvi, landcover)
+    if svf is None:
+        svf = sky_view_factor(dsm, cell_size, radius_m=svf_radius_m, device=device)
+    svf = np.where(building | water | veg, np.nan, svf)
+    green = (veg | water) if daytime else (veg & ~water)
+
+    # 25 m tiles
+    t = max(int(round(TILE_M / cell_size)), 1)
+    n_rows, n_cols = svf.shape
+    pr, pc = -n_rows % t, -n_cols % t
+    svf_t = np.pad(svf, ((0, pr), (0, pc)), constant_values=np.nan).reshape(
+        (n_rows + pr) // t, t, (n_cols + pc) // t, t)
+    inside = np.pad(np.ones_like(svf), ((0, pr), (0, pc))).reshape(svf_t.shape)
+    green_t = np.pad(green.astype(float), ((0, pr), (0, pc))).reshape(svf_t.shape)
+    n_valid = np.isfinite(svf_t).sum(axis=(1, 3))
+    n_inside = inside.sum(axis=(1, 3))
+    tile_svf = np.nansum(svf_t, axis=(1, 3)) / np.maximum(n_valid, 1)
+    tile_ok = n_valid > 0.1 * n_inside
+    tile_fveg = green_t.sum(axis=(1, 3)) / n_inside
+
+    tile = t * cell_size
+    if ff10 < LOW_WIND:
+        kernel = source_kernel(tile, 0.0, 350.0, 350.0, 350.0)
+    else:
+        kernel = source_kernel(tile, wind_dir, 1000.0, 100.0, 250.0)
+    # 25 m grids are small: NumPy is enough here
+    total = _area_sum(np, np.ones_like(tile_svf), kernel)
+    n_ok = _area_sum(np, tile_ok, kernel)
+    mean = _area_sum(np, np.where(tile_ok, tile_svf, 0.0), kernel) / np.maximum(n_ok, 1e-9)
+    frac = n_ok / total
+    svf_avg = np.where(frac <= 0.1, 1.0, np.where(frac > 0.2, mean, 1 + (mean - 1) * (frac - 0.1) / 0.1))
+    fveg_avg = _area_sum(np, tile_fveg, kernel) / total
+
+    def to_grid(a):  # back to the input grid, bilinear
+        return ndimage.zoom(a, t, order=1)[:n_rows, :n_cols]
+
+    return to_grid(svf_avg), to_grid(fveg_avg)
+
+
+def wind_inputs(dsm, dem, ndvi, cell_size, wind_dir, ff10, device="auto", landcover=None):
+    """Frontal area densities of buildings and trees and mean obstacle height (steps 3-8).
+
+    Frontal area of a cell = rise in obstacle height from its upwind neighbour x cell width.
+    landcover: optional UMEP land-cover grid (see classify).
+    Returns (lambda_b, lambda_t, h) on the input grid.
+    """
+    xp = get_xp(device)
+    height, building, tree, _, _ = classify(dsm, dem, ndvi, landcover)
+    th = np.radians(wind_dir)
+    upwind_shift = (np.cos(th), -np.sin(th))  # out[x] = in[x + one cell upwind]
+
+    def frontal(mask):
+        h = np.where(mask, height, 0.0)
+        # shortcut: frontal width is one cell for any direction; exact only for N/E/S/W winds
+        return np.maximum(h - ndimage.shift(h, upwind_shift, order=1, cval=0.0), 0.0) * cell_size
+
+    if ff10 < LOW_WIND:
+        kernel = source_kernel(cell_size, 0.0, 87.5, 87.5, 87.5)
+    else:
+        kernel = source_kernel(cell_size, wind_dir, 210.0, 70.0, 70.0)
+    area = _area_sum(xp, np.ones_like(height), kernel) * cell_size**2
+    obstacle = building | tree
+    lambda_b = _area_sum(xp, frontal(building), kernel) / area
+    lambda_t = _area_sum(xp, frontal(tree), kernel) / area
+    h_sum = _area_sum(xp, np.where(obstacle, height, 0.0), kernel)
+    h_mean = h_sum / xp.maximum(_area_sum(xp, obstacle, kernel), 1e-9)
+    return to_numpy(lambda_b), to_numpy(lambda_t), to_numpy(h_mean)