Skip to content

Sky Patches

Implements the Tregenza hemisphere subdivision (145 patches) used by all weighted carving modes. Each patch represents a solid-angle region of the sky dome; the scoring module assigns a weight to each patch depending on the analysis mode.

  • Tregenza geometry -- 145 direction vectors and their solid angles, following the standard subdivision used in climate-based daylight modelling.
  • EPW-based weights (compute_EPW_based_weights) -- aggregates hourly direct and diffuse irradiance from an EPW weather file onto each patch using the Perez all-weather sky model. Supports filtering by heating-benefit hours (outdoor temperature below balance point) and CIE overcast luminance.
  • Radiative cooling weights (compute_radiative_cooling_weights) -- models long-wave sky emissivity per patch using the Martin-Berdahl clear-sky model with Bliss angular attenuation.

urbansolarcarver.sky_patches

UrbanSolarCarver Sky Patch Weighting Module

Generates sky-patch direction vectors, solid angles, and per-patch weight distributions for the voxel carving pipeline.

Core Functions

  1. fetch_tregenza_patch_directions(device) → torch.Tensor Lazily loads a Ladybug ViewSphere and returns a (P×3) tensor of unit vectors for the P Tregenza sky patches.

  2. fetch_tregenza_patch_solid_angles(device) → torch.Tensor Returns a length-P tensor of solid angles (steradians) per patch.

  3. compute_EPW_based_weights(mode, epw_file, hoys, device, ...) → torch.Tensor Climate-based weights via Ladybug SkyMatrix (Perez all-weather model). Supports modes: irradiance, benefit, daylight.

  4. compute_radiative_cooling_weights(dew_point, bliss_k, device) → torch.Tensor Theoretical radiative cooling potential per patch (Martin-Berdahl + Bliss angular attenuation). Assumes horizontal analysis surface. Compute_weights yields all the sky-patch coefficients necessary to accumulate per-voxel exposure scores. Tregenza vectors and solid angles are also available for diagnostics or custom weighting schemes.

fetch_tregenza_patch_directions(device)

Returns the 145 unit direction vectors of the Tregenza hemisphere subdivision (Tregenza, 1987). The dome divides the sky hemisphere into 145 patches of approximately equal solid angle, organized in 7 altitude rings plus a zenith cap.

Returns tensor [P, 3] of unit vectors for each Tregenza sky patch. Uses ladybug ViewSphere internally.

fetch_tregenza_patch_solid_angles(device)

Returns tensor [P] of solid angles (in steradians) per tregenza sky patch. Uses ladybug viewsphere

compute_radiative_cooling_weights(dewpoint_celsius, bliss_k, device, min_elevation_deg=0.0)

Return a long-wave "cooling potential" weight for each Tregenza sky patch, given an outdoor dew-point temperature.

Scientific background

• Sky (hemispherical) emissivity, εₛky
The clear-sky emissivity in the 8-13 µm thermal-IR window can be estimated from near-surface water-vapour content. Martin & Berdahl (1984) fit a quadratic in relative dew-point x = T_dp / 100 °C to a wide range of radiometer measurements:

  εₛky(x) = 0.758 + 0.521 x + 0.625 x²                (Eq. 1)

A larger εₛky means the sky behaves more like a blackbody, emitting and absorbing more long-wave radiation and therefore offering less potential cooling for a hot surface.

• Directional emissivity (ε_dir) Long-wave exchange also depends on zenith angle θ: the drier, higher-altitude air seen near the zenith is usually "blacker" than the humid boundary layer near the horizon. Bliss (1961) proposed an exponential attenuation law that relates the hemispherical value in Eq. 1 to a direction-dependent value:

  ε_dir(θ) = 1 - (1 - εₛky)^(1 /(k · cos θ))          (Eq. 2)

with k ≈ 1.8 for clear nocturnal skies. The code clamps cos θ to 1e-3 to avoid division by zero at the horizon.

• Radiative cooling potential
A surface "sees" the sky patch through its solid angle Ω_p. Assuming the surface itself is nearly black in the long-wave, its net radiative heat loss in direction p is proportional to

  (1 - ε_dir) · Ω_p                                 (Eq. 3)

because (1 - ε_dir) is the fraction of the surface's own emission not returned by the sky (i.e. the deficit in sky emission).

Parameters:

Name Type Description Default
dewpoint_celsius float

Outdoor dew-point temperature [°C]. Acts as a proxy for absolute humidity in Eq. 1.

 required
bliss_k float

Empirical constant from Bliss (1961) governing angular variation of atmospheric emissivity. Typical clear-sky values range 1.5 - 2.0; larger k increases zenith-horizon contrast.

 1.8
device device

Target compute device for the returned tensor.

 required
min_elevation_deg float

Design-constraint protection cone: sky patches whose center elevation is below this angle are excluded (weight 0) and the remaining weights renormalized. This is NOT part of the physical model — it declares which portion of the sky dome the design defends, analogous to obstruction-angle rules in daylight codes. 0 (default) keeps the full hemisphere (pure physical model).

 0.0

Returns:

Type Description
torch.Tensor (length = P sky patches, dtype =float32)

cooling weights wᵢ ≥ 0, Σ wᵢ = 1.
Notes
  • Assumes horizontal analysis surface (flat roof). The view-factor weighting cos(θ)/π used in Eq. 3 is only correct for an upward-facing horizontal surface. For tilted or vertical surfaces the angular integration bounds change significantly; applying these weights to non-horizontal surfaces will over-weight the zenith and under-weight low-altitude patches.
  • Valid for clear nights; clouds would raise εₛky toward unity and flatten the weight distribution.
  • Units cancel, so the weights are dimensionless fractions that can multiply any radiative-heat-transfer coefficient in further calculations.
References
  • Bliss, R.W. 1961. "Atmospheric Radiation near the Surface of the Ground." Solar Energy 5 (3): 103-120.
  • Martin, M. & Berdahl, P. 1984. "Characteristics of Infrared Sky Radiation in the United States." Solar Energy 33 (3-4): 321-336.

compute_EPW_based_weights(mode, epw_path, hoys, device=None, balance_temperature=15.0, balance_offset=2.0, north=0.0, include_harm=False, usefulness=None)

Return a vector of sky-patch weights (length P) derived from Energy-Plus Weather (EPW) data or CIE overcast sky (for daylight). Each weight expresses the relative importance of the corresponding Tregenza sky patch for a chosen metric:

┌──────────────┬──────────────────────────────────────────────┐
│ mode         │ physical meaning of the weight wᵢ            │
├──────────────┼──────────────────────────────────────────────┤
│ time-based   │ uniform probability 1/P                      │
│ daylight     │ CIE overcast luminance Ω·(1+2 cos θ)/3       │
│ irradiance   │ solar short-wave power (direct+diffuse)      │
│ benefit      │ net *heating benefit* of solar gains         │
└──────────────┴──────────────────────────────────────────────┘
Scientific background

  • Sky patch geometry — Tregenza subdivides the hemisphere into 145 quasi-equal solid-angle patches. fetch_tregenza_patch_ returns Ωᵢ and view vector d̂ᵢ = (lᵢ, mᵢ, nᵢ)* with nᵢ = cos θ.

  • time-based — Baseline uninformative prior:
    wᵢ = 1/P. For time-based carving using traditional time-based solar envelope methods.

  • daylight — The CIE Standard Overcast Sky (Darula & Kittler 2002) prescribes relative luminance
    L(θ) ∝ (1 + 2 cos θ)/3.

  • irradiance — 'SkyMatrix.from_epw' (Ladybug Tools) builds a Perez All-Weather sky for every time step, then integrates the selected hours ('hoys') to obtain cumulative short-wave energy per patch:

    wᵢ = Σₜ (E_dirᵢₜ + E_difᵢₜ) [J m⁻²]

where E_dirᵢₜ is direct beam contribution and E_difᵢₜ diffuse.

  • benefit — Heating-benefit filter: only solar gains occurring in hours cold enough to offset heating demand are credited,

    wᵢ = Σₜ (E_dirᵢₜ + E_difᵢₜ) · H( T_bal - ΔT - Tₐₜ )

with Heaviside switch H. Implemented by selecting the cold hours from the EPW dry-bulb series and building a plain cumulative irradiance SkyMatrix over exactly those hours, so the formula above IS the implementation (period-stable: warm hours in the analysis period contribute nothing). With include_harm=True (opt-in, experimental) the weights instead reproduce Ladybug's composite radiation-benefit concept: hot-hour (Tₐ > T_bal + ΔT) radiation is subtracted per patch and the result clipped at zero,

  wᵢ = max( Σ_cold E − Σ_hot E , 0 )

Results then depend on how much of the warm season the analysis period includes, and a patch's weight erodes only to zero, never below — shading value cannot be a carving force. 'balance_temperature' (T_bal) is the building's free-running balance point — derive project-specific values with the Honeybee/E+ balance-point workflow; 'balance_offset' (ΔT) is the dead-band around it (hours inside the band count for neither side).

Parameters:

Name Type Description Default
mode (time - based, daylight, irradiance, benefit)

Weighting strategy (see table above).

 'time-based'
epw_path str

Path to an EPW file. Required for irradiance and benefit.

 required
hoys Sequence[float]

Hour-of-year indices to sample. For benefit, a full-year period is safe and natural: the balance filter selects the beneficial hours by itself.

 required
device device

Compute device for the returned tensor.

 'cuda' if available else 'cpu'
balance_temperature float

Free-running balance-point temperature for the benefit filter.

 15 °C
balance_offset float

Dead-band below the balance point.

 2 °C

Returns:

Type Description
Tensor

Shape (P,), dtype float32, residing on device. Weights are non-negative. Only radiative_cooling normalises to Σwᵢ = 1. Other modes preserve the physical scale returned by Ladybug (Wh/m² for irradiance/benefit) or the CIE luminance distribution (daylight). Threshold methods (carve_fraction, headtail) are scale-invariant, so the difference does not affect carving results.
Notes
  • The EPW-driven modes assume typical meteorology; rare events (e.g. > 99th percentile irradiance) may be under-represented.
  • For benefit mode the heating-balance filter is purely temperature-based; construction, occupancy and HVAC control logic are not considered.
References
  • Perez, R. et al. 1990. "Modeling daylight availability and irradiance components from direct and global irradiance." Solar Energy 44(5): 271-289.
  • Darula, S. & Kittler, R. 2002. "CIE general sky standard defining luminance distributions." Proceedings eSim 11: 13.
  • Ladybug Tools. "SkyMatrix" — cumulative Radiance sky matrix (gendaymtx / Perez all-weather). https://www.ladybug.tools/ladybug-radiance/docs/