+
+- :material-rocket-launch:{ .lg .middle } **Getting Started**
+
+ ---
+
+ Install SOLWEIG and run your first calculation
+
+ [:octicons-arrow-right-24: Quick Start](getting-started/quick-start.md)
+
+- :material-book-open-variant:{ .lg .middle } **User Guide**
+
+ ---
+
+ Learn how to use SOLWEIG for different scenarios
+
+ [:octicons-arrow-right-24: User Guide](guide/basic-usage.md)
+
+- :material-api:{ .lg .middle } **API Reference**
+
+ ---
+
+ Complete reference for all classes and functions
+
+ [:octicons-arrow-right-24: API Reference](api/index.md)
+
+- :material-flask:{ .lg .middle } **Physics**
+
+ ---
+
+ Scientific documentation of the radiation model
+
+ [:octicons-arrow-right-24: Physics](physics/index.md)
+
+
+
+## Citation
+
+If you use SOLWEIG in your research, please cite:
+
+> Lindberg F, Grimmond CSB, Gabey A, Huang B, Kent CW, Sun T, Theeuwes N, Järvi L, Ward H, Capel-Timms I, Chang YY, Jonsson P, Krave N, Liu D, Meyer D, Olofson F, Tan JG, Wästberg D, Xue L, Zhang Z (2018) Urban Multi-scale Environmental Predictor (UMEP) - An integrated tool for city-based climate services. Environmental Modelling and Software 99, 70-87 [doi:10.1016/j.envsoft.2017.09.020](https://doi.org/10.1016/j.envsoft.2017.09.020)
+
+## License
+
+GNU General Public License v3.0. See [LICENSE](https://github.com/UMEP-dev/solweig/blob/main/LICENSE) for details.
diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js
new file mode 100644
index 0000000..06dbf38
--- /dev/null
+++ b/docs/javascripts/mathjax.js
@@ -0,0 +1,16 @@
+window.MathJax = {
+ tex: {
+ inlineMath: [["\\(", "\\)"]],
+ displayMath: [["\\[", "\\]"]],
+ processEscapes: true,
+ processEnvironments: true
+ },
+ options: {
+ ignoreHtmlClass: ".*|",
+ processHtmlClass: "arithmatex"
+ }
+};
+
+document$.subscribe(() => {
+ MathJax.typesetPromise()
+})
diff --git a/docs/physics/ground-temperature.md b/docs/physics/ground-temperature.md
new file mode 100644
index 0000000..9dab73d
--- /dev/null
+++ b/docs/physics/ground-temperature.md
@@ -0,0 +1,66 @@
+# Ground Temperature
+
+Ground surface temperature significantly affects upwelling longwave radiation and thermal comfort.
+
+## TsWaveDelay Model
+
+SOLWEIG uses a simplified thermal mass model that accounts for:
+
+1. **Solar heating**: Ground absorbs shortwave radiation
+2. **Thermal inertia**: Temperature responds slowly to forcing
+3. **Phase lag**: Peak temperature lags peak radiation
+
+## Governing Equation
+
+Ground temperature evolution:
+
+$$T_g(t) = T_{air} + \Delta T_{max} \cdot f(t - \phi)$$
+
+Where:
+
+- $T_{air}$ = Air temperature
+- $\Delta T_{max}$ = Maximum ground-air temperature difference
+- $\phi$ = Phase lag (thermal delay)
+- $f(t)$ = Diurnal temperature wave function
+
+## Land Cover Dependency
+
+Different surfaces have different thermal properties:
+
+| Surface | Thermal Admittance | Typical $\Delta T_{max}$ |
+|---------|-------------------|-------------------------|
+| Asphalt | High | 15-25°C |
+| Concrete | High | 12-20°C |
+| Grass | Low | 5-10°C |
+| Water | Very High | 2-5°C |
+
+## Shading Effects
+
+Shaded ground has reduced temperature:
+
+$$T_{g,shade} = T_{g,sun} - \Delta T_{shade}$$
+
+Where $\Delta T_{shade}$ depends on shadow duration and surface properties.
+
+## Timeseries Considerations
+
+Ground temperature requires previous timesteps for accurate modeling:
+
+```python
+# CORRECT: Full timeseries preserves thermal state
+results = solweig.calculate_timeseries(
+ surface=surface,
+ weather_series=weather_list,
+)
+
+# WRONG: Single timestep loses thermal history
+result = solweig.calculate(surface, location, weather_noon)
+```
+
+## Implementation
+
+Ground temperature is computed in `components/ground.py` using the TsWaveDelay algorithm from UMEP.
+
+## References
+
+- Lindberg, F., Grimmond, C. S. B., & Martilli, A. (2015). Sunlit fractions on urban facets–Impact of spatial resolution and approach. *Urban Climate*, 12, 65-84.
diff --git a/docs/physics/gvf.md b/docs/physics/gvf.md
new file mode 100644
index 0000000..dcb2cf5
--- /dev/null
+++ b/docs/physics/gvf.md
@@ -0,0 +1,52 @@
+# Ground View Factor (GVF)
+
+The Ground View Factor quantifies the fraction of surrounding ground visible from a point, important for reflected radiation calculations.
+
+## Definition
+
+GVF represents the hemispherical view of ground surfaces:
+
+$$GVF = 1 - SVF - WVF$$
+
+Where:
+
+- $SVF$ = Sky View Factor
+- $WVF$ = Wall View Factor
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `gvf` | Total ground view factor |
+| `gvf_norm` | Normalized GVF for reflected radiation |
+
+## Role in Radiation
+
+GVF affects upwelling radiation calculations:
+
+1. **Reflected shortwave**: Ground reflects incoming solar radiation
+2. **Emitted longwave**: Ground emits thermal radiation based on temperature
+
+```python
+# Upwelling shortwave from ground
+Kup = albedo * Kdown * gvf
+
+# Upwelling longwave from ground
+Lup = emissivity * stefan_boltzmann * T_ground^4 * gvf
+```
+
+## Computation
+
+GVF is computed during SVF calculation by tracking rays that hit ground instead of sky:
+
+1. Cast rays from each point
+2. Rays not blocked by buildings/vegetation that hit ground contribute to GVF
+3. Weight by solid angle
+
+## Performance
+
+GVF is computed alongside SVF with minimal additional cost.
+
+## References
+
+- Lindberg, F., & Grimmond, C. S. B. (2011). The influence of vegetation and building morphology on shadow patterns and mean radiant temperatures in urban areas. *Theoretical and Applied Climatology*, 105(3), 311-323.
diff --git a/docs/physics/index.md b/docs/physics/index.md
new file mode 100644
index 0000000..9a5bfe5
--- /dev/null
+++ b/docs/physics/index.md
@@ -0,0 +1,89 @@
+# Physics Overview
+
+SOLWEIG (Solar and Longwave Environmental Irradiance Geometry) calculates the mean radiant temperature (Tmrt) by modeling the complete radiation budget at a point in an urban environment.
+
+## Radiation Budget
+
+The total radiation received by a human body is:
+
+$$
+R_{total} = R_{short} + R_{long}
+$$
+
+Where:
+
+- **Shortwave** ($R_{short}$): Direct and diffuse solar radiation
+- **Longwave** ($R_{long}$): Thermal radiation from sky, ground, and walls
+
+## Calculation Pipeline
+
+```mermaid
+graph LR
+ DSM[DSM] --> SVF[Sky View Factor]
+ DSM --> Shadows[Shadow Masks]
+ SVF --> GVF[Ground View Factor]
+ Shadows --> Radiation
+ GVF --> Radiation
+ Weather --> Radiation
+ Radiation --> Tmrt[Mean Radiant Temp]
+ Tmrt --> UTCI
+ Tmrt --> PET
+```
+
+## Component Models
+
+### 1. Sky View Factor (SVF)
+
+Fraction of sky visible from each point, accounting for buildings and vegetation.
+
+[:octicons-arrow-right-24: SVF Details](svf.md)
+
+### 2. Shadow Calculation
+
+Sun position and ray tracing to determine shadow patterns.
+
+[:octicons-arrow-right-24: Shadow Details](shadows.md)
+
+### 3. Ground View Factor (GVF)
+
+View factor from point to ground surface, with albedo weighting.
+
+[:octicons-arrow-right-24: GVF Details](gvf.md)
+
+### 4. Radiation Model
+
+Complete shortwave and longwave radiation budget.
+
+[:octicons-arrow-right-24: Radiation Details](radiation.md)
+
+### 5. Ground Temperature
+
+Surface temperature model with thermal inertia.
+
+[:octicons-arrow-right-24: Ground Temp Details](ground-temperature.md)
+
+### 6. Mean Radiant Temperature
+
+Integration of all radiation fluxes into Tmrt.
+
+[:octicons-arrow-right-24: Tmrt Details](tmrt.md)
+
+## Thermal Comfort Indices
+
+### UTCI (Universal Thermal Climate Index)
+
+Fast polynomial approximation for outdoor thermal comfort.
+
+[:octicons-arrow-right-24: UTCI Details](utci.md)
+
+### PET (Physiological Equivalent Temperature)
+
+Iterative solver based on human energy balance.
+
+[:octicons-arrow-right-24: PET Details](pet.md)
+
+## References
+
+1. Lindberg F, Holmer B, Thorsson S (2008) SOLWEIG 1.0 - Modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. Int J Biometeorol 52:697-713
+
+2. Lindberg F, Grimmond CSB (2011) The influence of vegetation and building morphology on shadow patterns and mean radiant temperatures in urban areas: model development and evaluation. Theor Appl Climatol 105:311-323
diff --git a/docs/physics/pet.md b/docs/physics/pet.md
new file mode 100644
index 0000000..ea48102
--- /dev/null
+++ b/docs/physics/pet.md
@@ -0,0 +1,108 @@
+# PET (Physiological Equivalent Temperature)
+
+PET is the air temperature in a reference environment at which the heat balance of the human body is maintained with core and skin temperatures equal to those under the actual conditions.
+
+## Definition
+
+PET is based on the Munich Energy Balance Model for Individuals (MEMI), which solves:
+
+$$M + W = R + C + E_{sk} + E_{res} + S$$
+
+Where:
+
+- $M$ = Metabolic rate
+- $W$ = Mechanical work
+- $R$ = Net radiation
+- $C$ = Convective heat loss
+- $E_{sk}$ = Evaporative heat loss (skin)
+- $E_{res}$ = Respiratory heat loss
+- $S$ = Heat storage
+
+## Reference Conditions
+
+The reference environment for PET has:
+
+- Wind speed 0.1 m/s
+- Water vapor pressure 12 hPa
+- Tmrt = Air temperature
+
+## Input Variables
+
+| Variable | Symbol | Units |
+|----------|--------|-------|
+| Air temperature | $T_a$ | °C |
+| Mean radiant temperature | $T_{mrt}$ | °C |
+| Wind speed | $v$ | m/s |
+| Relative humidity | $RH$ | % |
+
+## Human Parameters
+
+Unlike UTCI, PET allows customizable human parameters:
+
+```python
+human = solweig.HumanParams(
+ weight=70, # kg
+ height=1.75, # m
+ age=35, # years
+ sex="male", # or "female"
+ posture="standing", # or "sitting"
+)
+
+pet = result.compute_pet(weather, human=human)
+```
+
+## Thermal Perception Scale
+
+| PET (°C) | Thermal Perception | Physiological Stress |
+|----------|-------------------|---------------------|
+| > 41 | Very hot | Extreme heat stress |
+| 35 to 41 | Hot | Strong heat stress |
+| 29 to 35 | Warm | Moderate heat stress |
+| 23 to 29 | Slightly warm | Slight heat stress |
+| 18 to 23 | Comfortable | No thermal stress |
+| 13 to 18 | Slightly cool | Slight cold stress |
+| 8 to 13 | Cool | Moderate cold stress |
+| 4 to 8 | Cold | Strong cold stress |
+| < 4 | Very cold | Extreme cold stress |
+
+## Algorithm
+
+PET uses an iterative solver:
+
+1. Calculate body heat balance under actual conditions
+2. Determine core and skin temperatures
+3. Iteratively find reference air temperature that produces same thermal state
+4. Convergence typically requires 20-50 iterations
+
+## Performance
+
+PET is significantly slower than UTCI due to the iterative solver:
+
+| Metric | UTCI | PET |
+|--------|------|-----|
+| Single point | ~0.01 ms | ~0.5 ms |
+| 100×100 grid | ~1 ms | ~50 ms |
+| 72 timesteps | ~1 s | ~1 min |
+
+!!! warning "PET is ~50× slower than UTCI"
+ For large-scale studies, consider using UTCI unless PET's physiological basis is specifically needed.
+
+## Usage
+
+```python
+result = solweig.calculate(surface, location, weather)
+
+# Compute PET with default human
+pet = result.compute_pet(weather)
+
+# Compute PET with custom parameters
+pet = result.compute_pet(
+ weather,
+ human=solweig.HumanParams(weight=60, height=1.65)
+)
+```
+
+## References
+
+- Höppe, P. (1999). The physiological equivalent temperature–a universal index for the biometeorological assessment of the thermal environment. *International Journal of Biometeorology*, 43(2), 71-75.
+- Matzarakis, A., Rutz, F., & Mayer, H. (2007). Modelling radiation fluxes in simple and complex environments. *International Journal of Biometeorology*, 51(4), 323-334.
diff --git a/docs/physics/radiation.md b/docs/physics/radiation.md
new file mode 100644
index 0000000..dcd52f4
--- /dev/null
+++ b/docs/physics/radiation.md
@@ -0,0 +1,69 @@
+# Radiation Model
+
+SOLWEIG computes the complete 3D radiation environment for a standing human.
+
+## Radiation Components
+
+### Shortwave (Solar)
+
+| Component | Symbol | Description |
+|-----------|--------|-------------|
+| Direct | $K_{dir}$ | Direct beam from sun |
+| Diffuse | $K_{dif}$ | Scattered by atmosphere |
+| Reflected | $K_{ref}$ | Reflected from surfaces |
+
+### Longwave (Thermal)
+
+| Component | Symbol | Description |
+|-----------|--------|-------------|
+| Downwelling | $L_{down}$ | From sky and atmosphere |
+| Upwelling | $L_{up}$ | From ground |
+| Lateral | $L_{side}$ | From walls and surfaces |
+
+## Six-Direction Model
+
+Radiation is computed for six directions around a standing person:
+
+- **Up**: Sky/canopy radiation
+- **Down**: Ground radiation
+- **North, South, East, West**: Lateral radiation from walls
+
+## Direct/Diffuse Split
+
+Global radiation is split into direct and diffuse components using the Reindl model:
+
+$$K_{dir} = K_{global} \times (1 - k_d)$$
+$$K_{dif} = K_{global} \times k_d$$
+
+Where $k_d$ is the diffuse fraction, estimated from clearness index.
+
+## Anisotropic vs Isotropic Sky
+
+**Isotropic**: Assumes uniform sky radiance (faster)
+
+**Anisotropic**: Models non-uniform sky brightness (more accurate):
+
+- Circumsolar brightening near sun
+- Horizon brightening
+- Zenith darkening
+
+## Wall Radiation
+
+Walls contribute lateral radiation based on:
+
+- Wall temperature (function of orientation and solar exposure)
+- Wall emissivity
+- View factor from point to wall
+
+## Cylindric Weighting
+
+For a standing human (approximated as cylinder), radiation from different directions is weighted:
+
+$$K_{absorbed} = a_k \sum_i w_i K_i$$
+
+Where $w_i$ are direction-dependent weighting factors.
+
+## References
+
+- Lindberg, F., Holmer, B., & Thorsson, S. (2008). SOLWEIG 1.0. *International Journal of Biometeorology*, 52(7), 697-713.
+- Reindl, D. T., Beckman, W. A., & Duffie, J. A. (1990). Diffuse fraction correlations. *Solar Energy*, 45(1), 1-7.
diff --git a/docs/physics/shadows.md b/docs/physics/shadows.md
new file mode 100644
index 0000000..e0cb643
--- /dev/null
+++ b/docs/physics/shadows.md
@@ -0,0 +1,65 @@
+# Shadow Calculation
+
+Shadow computation determines which grid cells are shaded from direct solar radiation at a given sun position.
+
+## Sun Position
+
+Sun position is computed from:
+
+- **Latitude/Longitude**: Geographic location
+- **DateTime**: Local time with UTC offset
+- **Algorithm**: NREL Solar Position Algorithm (SPA)
+
+Outputs:
+
+- **Altitude** ($\alpha$): Angle above horizon (0-90°)
+- **Azimuth** ($\psi$): Compass direction (0-360°, north=0°)
+
+## Shadow Algorithm
+
+SOLWEIG uses a shadow volume approach:
+
+1. For each building pixel, compute shadow projection based on sun angle
+2. Project shadow along solar azimuth
+3. Shadow length: $L = h / \tan(\alpha)$ where $h$ is building height
+
+```python
+# Shadow projection distance
+shadow_length = height / tan(sun_altitude)
+
+# Shadow direction (opposite to sun)
+shadow_azimuth = (sun_azimuth + 180) % 360
+```
+
+## Building Shadows
+
+Building shadows are binary (0 or 1):
+
+- **0** = Sunlit
+- **1** = Shaded by building
+
+## Vegetation Shadows
+
+Vegetation provides partial shade with transmissivity:
+
+$$F_{sh,veg} = 1 - T_{veg}$$
+
+Where $T_{veg}$ depends on leaf area index (LAI) and path length through canopy.
+
+## Shadow Matrices
+
+For anisotropic sky calculations, SOLWEIG pre-computes shadow patterns for multiple sun positions covering the sky hemisphere.
+
+## Output
+
+The shadow calculation produces:
+
+| Output | Description |
+|--------|-------------|
+| `shadow` | Combined shadow fraction (0-1) |
+| `shadow_building` | Building shadow mask |
+| `shadow_vegetation` | Vegetation shadow fraction |
+
+## References
+
+- Lindberg, F., Holmer, B., & Thorsson, S. (2008). SOLWEIG 1.0–Modelling spatial variations of 3D radiant fluxes and mean radiant temperature in complex urban settings. *International Journal of Biometeorology*, 52(7), 697-713.
diff --git a/docs/physics/svf.md b/docs/physics/svf.md
new file mode 100644
index 0000000..cd5e053
--- /dev/null
+++ b/docs/physics/svf.md
@@ -0,0 +1,63 @@
+# Sky View Factor (SVF)
+
+The Sky View Factor quantifies the fraction of sky visible from a point on the ground.
+
+## Definition
+
+$$SVF = \frac{1}{\pi} \int_0^{2\pi} \int_0^{\pi/2} \cos(\theta) \sin(\theta) \, d\theta \, d\phi$$
+
+Where:
+
+- $\theta$ = zenith angle
+- $\phi$ = azimuth angle
+
+SVF ranges from 0 (no sky visible) to 1 (open sky).
+
+## Directional Components
+
+SOLWEIG computes directional SVF for anisotropic radiation:
+
+| Component | Description |
+|-----------|-------------|
+| `svf` | Total sky view factor |
+| `svf_north` | Northern hemisphere contribution |
+| `svf_south` | Southern hemisphere contribution |
+| `svf_east` | Eastern hemisphere contribution |
+| `svf_west` | Western hemisphere contribution |
+
+## Algorithm
+
+SVF is computed using hemisphere sampling with configurable resolution:
+
+1. Cast rays from each ground point across the hemisphere
+2. Check occlusion against DSM (buildings) and CDSM (vegetation)
+3. Weight visible rays by solid angle
+4. Sum contributions for total and directional components
+
+## Vegetation Handling
+
+Vegetation (CDSM) partially blocks sky view with transmissivity:
+
+- **Trans** = trunk zone transmissivity (~0.43 default)
+- **TransVeg** = vegetation transmissivity function
+
+```python
+# Effective SVF through vegetation
+svf_veg = svf * trans_veg + svf_building * (1 - trans_veg)
+```
+
+## Performance
+
+SVF computation is expensive (O(n² × rays)):
+
+| Grid Size | Computation Time |
+|-----------|-----------------|
+| 100×100 | ~5 seconds |
+| 200×200 | ~67 seconds |
+| 500×500 | ~10 minutes |
+
+SVF only depends on geometry, so it's computed once and cached.
+
+## References
+
+- Lindberg, F., & Grimmond, C. S. B. (2011). The influence of vegetation and building morphology on shadow patterns and mean radiant temperatures in urban areas: model development and evaluation. *Theoretical and Applied Climatology*, 105(3), 311-323.
diff --git a/docs/physics/tmrt.md b/docs/physics/tmrt.md
new file mode 100644
index 0000000..7747e73
--- /dev/null
+++ b/docs/physics/tmrt.md
@@ -0,0 +1,71 @@
+# Mean Radiant Temperature (Tmrt)
+
+Mean Radiant Temperature is the uniform temperature of an imaginary black enclosure that would result in the same radiant heat exchange as the actual non-uniform environment.
+
+## Definition
+
+$$T_{mrt} = \sqrt[4]{\frac{\sum_i F_i T_i^4}{\sigma}}$$
+
+Where:
+
+- $F_i$ = View factor to surface $i$
+- $T_i$ = Temperature of surface $i$
+- $\sigma$ = Stefan-Boltzmann constant
+
+## SOLWEIG Calculation
+
+SOLWEIG computes Tmrt from absorbed radiation:
+
+$$T_{mrt} = \sqrt[4]{\frac{S_{str}}{\varepsilon_p \sigma}} - 273.15$$
+
+Where $S_{str}$ is the mean radiant flux density (W/m²).
+
+## Mean Radiant Flux
+
+The mean radiant flux combines all radiation components:
+
+$$S_{str} = a_k (K_{down} + K_{up} + K_{side}) + a_l (L_{down} + L_{up} + L_{side})$$
+
+Where:
+
+- $a_k$ = Shortwave absorptivity (~0.7 for clothed human)
+- $a_l$ = Longwave absorptivity (~0.97 for clothed human)
+- $K$ = Shortwave radiation components
+- $L$ = Longwave radiation components
+
+## Directional Components
+
+For a standing human (cylinder approximation):
+
+| Direction | Weight Factor |
+|-----------|--------------|
+| Up | 0.06 |
+| Down | 0.06 |
+| North | 0.22 |
+| South | 0.22 |
+| East | 0.22 |
+| West | 0.22 |
+
+## Typical Values
+
+| Environment | Tmrt Range |
+|-------------|-----------|
+| Deep shade | ~Air temperature |
+| Open sky, summer noon | 50-70°C |
+| Near hot pavement | +10-20°C above air |
+| Near cool grass | -5-10°C below open |
+
+## Output
+
+```python
+result = solweig.calculate(surface, location, weather)
+
+# Tmrt grid (°C)
+tmrt = result.tmrt
+print(f"Mean Tmrt: {tmrt.mean():.1f}°C")
+print(f"Max Tmrt: {tmrt.max():.1f}°C")
+```
+
+## References
+
+- Thorsson, S., Lindberg, F., Eliasson, I., & Holmer, B. (2007). Different methods for estimating the mean radiant temperature in an outdoor urban setting. *International Journal of Climatology*, 27(14), 1983-1993.
diff --git a/docs/physics/utci.md b/docs/physics/utci.md
new file mode 100644
index 0000000..b94ffcc
--- /dev/null
+++ b/docs/physics/utci.md
@@ -0,0 +1,78 @@
+# UTCI (Universal Thermal Climate Index)
+
+UTCI represents the air temperature of a reference environment that produces the same thermal strain as the actual environment.
+
+## Definition
+
+UTCI is based on a multi-node thermophysiological model that simulates:
+
+- Heat exchange between body and environment
+- Thermoregulation (sweating, shivering, vasodilation)
+- Clothing adaptation
+
+## Reference Conditions
+
+The reference environment has:
+
+- 50% relative humidity (vapor pressure capped at 20 hPa)
+- Wind speed 0.5 m/s at 10m height
+- Tmrt = Air temperature
+- Metabolic rate 135 W/m² (walking 4 km/h)
+
+## Input Variables
+
+| Variable | Symbol | Units |
+|----------|--------|-------|
+| Air temperature | $T_a$ | °C |
+| Mean radiant temperature | $T_{mrt}$ | °C |
+| Wind speed (10m) | $v_{10}$ | m/s |
+| Relative humidity | $RH$ | % |
+
+## Polynomial Approximation
+
+SOLWEIG uses a fast polynomial approximation (~200 terms):
+
+$$UTCI = T_a + f(T_a, T_{mrt} - T_a, v_{10}, e)$$
+
+Where $e$ is water vapor pressure (hPa).
+
+## Validity Range
+
+| Variable | Min | Max |
+|----------|-----|-----|
+| $T_a$ | -50°C | +50°C |
+| $T_{mrt} - T_a$ | -30°C | +70°C |
+| $v_{10}$ | 0.5 m/s | 17 m/s |
+
+## Stress Categories
+
+| UTCI (°C) | Stress Category |
+|-----------|-----------------|
+| > 46 | Extreme heat stress |
+| 38 to 46 | Very strong heat stress |
+| 32 to 38 | Strong heat stress |
+| 26 to 32 | Moderate heat stress |
+| 9 to 26 | No thermal stress |
+| 0 to 9 | Slight cold stress |
+| -13 to 0 | Moderate cold stress |
+| -27 to -13 | Strong cold stress |
+| < -40 | Extreme cold stress |
+
+## Usage
+
+```python
+result = solweig.calculate(surface, location, weather)
+
+# Compute UTCI from Tmrt
+utci = result.compute_utci(weather)
+print(f"Mean UTCI: {utci.mean():.1f}°C")
+```
+
+## Performance
+
+UTCI computation is fast (~1ms per grid) due to the polynomial approximation.
+
+## References
+
+- Jendritzky, G., de Dear, R., & Havenith, G. (2012). UTCI—Why another thermal index? *International Journal of Biometeorology*, 56(3), 421-428.
+- Bröde, P., et al. (2012). Deriving the operational procedure for the Universal Thermal Climate Index (UTCI). *International Journal of Biometeorology*, 56(3), 481-494.
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..a7a92ea
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,98 @@
+site_name: SOLWEIG
+site_description: High-performance urban microclimate model for Mean Radiant Temperature and thermal comfort
+site_url: https://umep-dev.github.io/solweig/
+repo_url: https://github.com/UMEP-dev/solweig
+repo_name: UMEP-dev/solweig
+
+theme:
+ name: material
+ palette:
+ - scheme: default
+ primary: teal
+ accent: amber
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ - scheme: slate
+ primary: teal
+ accent: amber
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+ features:
+ - navigation.instant
+ - navigation.tracking
+ - navigation.sections
+ - navigation.expand
+ - navigation.top
+ - search.highlight
+ - search.suggest
+ - content.code.copy
+ - content.code.annotate
+ icon:
+ repo: fontawesome/brands/github
+
+plugins:
+ - search
+ - mkdocstrings:
+ handlers:
+ python:
+ options:
+ docstring_style: google
+ show_source: true
+ show_root_heading: true
+ members_order: source
+
+markdown_extensions:
+ - admonition
+ - pymdownx.details
+ - pymdownx.superfences
+ - pymdownx.highlight:
+ anchor_linenums: true
+ - pymdownx.inlinehilite
+ - pymdownx.tabbed:
+ alternate_style: true
+ - pymdownx.arithmatex:
+ generic: true
+ - tables
+ - toc:
+ permalink: true
+
+extra_javascript:
+ - javascripts/mathjax.js
+ - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+
+nav:
+ - Home: index.md
+ - Getting Started:
+ - Quick Start: getting-started/quick-start.md
+ - Installation: getting-started/installation.md
+ - User Guide:
+ - Basic Usage: guide/basic-usage.md
+ - Working with GeoTIFFs: guide/geotiffs.md
+ - Timeseries Calculations: guide/timeseries.md
+ - Thermal Comfort (UTCI/PET): guide/thermal-comfort.md
+ - API Reference:
+ - Overview: api/index.md
+ - Core Functions: api/functions.md
+ - Data Classes: api/dataclasses.md
+ - Errors: api/errors.md
+ - Physics:
+ - Overview: physics/index.md
+ - Sky View Factor: physics/svf.md
+ - Shadows: physics/shadows.md
+ - Ground View Factor: physics/gvf.md
+ - Radiation: physics/radiation.md
+ - Ground Temperature: physics/ground-temperature.md
+ - Mean Radiant Temperature: physics/tmrt.md
+ - UTCI: physics/utci.md
+ - PET: physics/pet.md
+ - Development:
+ - Contributing: development/contributing.md
+ - Architecture: development/architecture.md
+ - Roadmap: development/roadmap.md
+
+extra:
+ social:
+ - icon: fontawesome/brands/github
+ link: https://github.com/UMEP-dev/solweig
diff --git a/pyproject.toml b/pyproject.toml
index 7d60412..6f21551 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
[project]
-name = "umepr"
-version = "0.0.1b61"
-description = "rust implementation of urban multi-scale environmental predictor"
+name = "solweig"
+version = "0.1.0b15"
+description = "High-performance SOLWEIG urban microclimate model (Rust + Python)"
readme = "README.md"
requires-python = ">=3.9, <3.14"
license = { text = "AGPL-3.0" }
@@ -26,29 +26,37 @@ keywords = [
authors = [{ name = "UMEP Developers" }]
maintainers = [{ name = "UMEP Developers" }]
classifiers = [
+ "Development Status :: 3 - Alpha",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
+ "Programming Language :: Rust",
+ "Topic :: Scientific/Engineering :: Atmospheric Science",
+ "Topic :: Scientific/Engineering :: GIS",
]
dependencies = [
- "geopandas>=1.0.1",
- "matplotlib>=3.9.4",
- "momepy>=0.6.0",
- "numpy>=2.0.2",
- "pandas>=2.3.1",
- "pvlib>=0.13.0",
- "pyepw>=0.1",
- "pyproj>=3.6.1",
- "pytz>=2025.2",
- "rasterio>=1.4.3",
- "rioxarray>=0.15.0",
- "scipy>=1.13.1",
- "shapely>=2.0.7",
- "tqdm>=4.67.1",
- "umep==0.0.1a18",
- "xarray>=2024.7.0",
+ "numpy>=1.26.0", # Allows OSGeo4W 2.2.2 AND newer
+ "pyproj>=3.6.0", # Matches OSGeo4W 3.6.x minimum
+ "scipy>=1.13.0", # Matches OSGeo4W 1.13.0
+ "shapely>=2.0.1", # Matches OSGeo4W 2.0.x
+]
+
+[project.optional-dependencies]
+# Full installation with all features (recommended for standalone use)
+full = [
+ "geopandas>=1.0.1", # POI/WOI point-of-interest analysis
+ "rasterio>=1.3.0", # Fast raster I/O (pip-installable, falls back to GDAL in QGIS)
+ "tqdm>=4.67.1", # Terminal progress bars
+ "pillow>=9.0.0", # Preview PNG generation for GeoTIFFs
+]
+# QGIS plugin mode - uses bundled GDAL, QGIS progress bars
+qgis = [
+ # No additional dependencies - uses bundled OSGeo4W packages
+ # geopandas: optional, only for POI/WOI features
+ # rasterio: not needed, uses GDAL backend
+ # tqdm: not needed, uses QGIS QgsProcessingFeedback
]
[build-system]
@@ -58,11 +66,12 @@ build-backend = "maturin"
[tool.maturin]
manifest-path = "rust/Cargo.toml"
python-source = "pysrc"
-module-name = 'umepr.rustalgos'
-features = ["pyo3/extension-module", "gpu"]
+module-name = 'solweig.rustalgos'
+features = ["pyo3/extension-module", "pyo3/abi3-py39", "gpu"]
+include = ["LICENSE"]
[tool.setuptools]
-packages = ["umepr"]
+packages = ["solweig"]
[dependency-groups]
dev = [
@@ -75,16 +84,51 @@ dev = [
"pip>=23.2",
"ruff>=0.5.1",
"poethepoet>=0.29.0",
- "pyright>=1.1.398",
+ "umep>=0.0.1a18", # For cross-checking tests against reference implementation
+ "ty>=0.0.12",
+ # Include full optional dependencies for dev/testing
+ "geopandas>=1.0.1", # POI/WOI point-of-interest analysis
+ "rasterio>=1.3.0", # Fast raster I/O (falls back to GDAL)
+ "tqdm>=4.67.1", # Terminal progress bars
+ "pillow>=9.0.0", # Preview PNG generation for GeoTIFFs
+ "pre-commit>=4.3.0",
+ # Documentation
+ "mkdocs>=1.6.0",
+ "mkdocs-material>=9.5.0",
+ "mkdocstrings[python]>=0.27.0",
+ "ipykernel>=6.31.0",
+]
+# QGIS 3.34 LTR compatibility testing - uses GDAL backend, no rasterio/geopandas
+# Tests the minimal dependency set that works in QGIS/OSGeo4W Python environment
+# Package versions from: http://download.osgeo.org/osgeo4w/v2/x86_64/release/
+# QGIS 3.34.14 (Dec 2024) uses Python 3.12.8
+qgis-compat = [
+ "numpy==1.26.4", # OSGeo4W bundles 1.26.4 (Apr 2024)
+ "pandas>=2.2.2", # OSGeo4W bundles 2.2.2 (Apr 2024), also 2.3.1 available
+ "scipy>=1.13.0", # OSGeo4W bundles 1.13.0 (Apr 2024)
+ # Note: GDAL is a system package in QGIS/OSGeo4W, not pip-installed.
+ # In CI, install matching version separately: uv pip install gdal==$(gdal-config --version)
+ "pyproj>=3.6.0", # OSGeo4W bundles 3.6.x-3.7.x
+ "shapely>=2.0.1", # OSGeo4W bundles 2.0.x
+ # Note: tqdm not bundled in OSGeo4W - progress.py falls back to QGIS progress bars
+ # Note: geopandas not bundled - POI/WOI features unavailable without manual install
+ "pytest>=7.2.0", # Testing
+ "maturin>=1.8.3", # Build Rust extension
]
[project.urls]
-homepage = "https://github.com/UMEP-dev/umep-rust"
-documentation = "https://github.com/UMEP-dev/umep-rust"
-repository = "https://github.com/UMEP-dev/umep-rust"
+homepage = "https://github.com/UMEP-dev/solweig"
+documentation = "https://github.com/UMEP-dev/solweig"
+repository = "https://github.com/UMEP-dev/solweig"
[tool.poe.tasks]
-verify_project = { shell = "ruff format && ruff check && pyright . && pytest ./tests" }
+verify_project = { shell = "ruff format && ruff check --fix && ty check pysrc/ tests/ demos/ scripts/ qgis_plugin/ && pytest ./tests" }
+lint = { shell = "ruff format && ruff check --fix" }
+typecheck = { shell = "ty check pysrc/ tests/ demos/ scripts/ qgis_plugin/" }
+test_quick = { shell = "pytest tests/ -m 'not slow' -x -q" }
+test_full = { shell = "pytest tests/ -x -q" }
+docs = { shell = "mkdocs serve" }
+docs_build = { shell = "mkdocs build --strict" }
[tool.ruff]
line-length = 120
@@ -107,6 +151,10 @@ select = [
]
fixable = ["ALL"]
+[tool.ruff.lint.per-file-ignores]
+# EPW test data contains literal long lines matching real file format
+"tests/test_io.py" = ["E501"]
+
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
@@ -115,30 +163,18 @@ line-ending = "auto"
docstring-code-format = true
docstring-code-line-length = "dynamic"
-[tool.pyright]
-pythonVersion = "3.11"
-include = ["umepr"]
-exclude = [
- "**/__pycache__",
- "**/__pypackages__",
- "build",
- "docs",
- "**/temp/",
- "tests/",
- "dist",
- ".venv",
-]
-typeCheckingMode = "strict"
-useLibraryCodeForTypes = true
-reportUntypedFunctionDecorator = false
-reportUntypedClassDecorator = false
-reportUnknownMemberType = false
-reportMissingTypeStubs = false
-reportUnnecessaryIsInstance = false
-
[tool.pytest.ini_options]
console_output_style = "count"
log_cli = true
log_cli_level = "INFO"
testpaths = ["tests"]
addopts = "-s"
+markers = [
+ "slow: marks tests as slow (full SOLWEIG computation, deselect with '-m \"not slow\"')",
+ "validation: marks tests requiring external validation datasets (deselect with '-m \"not validation\"')",
+]
+
+[tool.ty.rules]
+# Ignore unresolved imports for external/optional modules that ty cannot resolve
+# (rustalgos is a Rust extension, osgeo/qgis are optional dependencies)
+unresolved-import = "ignore"
diff --git a/pysrc/solweig/__init__.py b/pysrc/solweig/__init__.py
new file mode 100644
index 0000000..522cf31
--- /dev/null
+++ b/pysrc/solweig/__init__.py
@@ -0,0 +1,203 @@
+"""
+SOLWEIG - High-performance urban microclimate model.
+
+A Python package with Rust-accelerated algorithms for computing mean radiant
+temperature (Tmrt) and other urban climate parameters.
+
+## Modern API
+
+ import solweig
+ from datetime import datetime
+
+ result = solweig.calculate(
+ surface=solweig.SurfaceData(dsm=my_dsm_array),
+ location=solweig.Location(latitude=57.7, longitude=12.0),
+ weather=solweig.Weather(
+ datetime=datetime(2024, 7, 15, 12, 0),
+ ta=25, rh=50, global_rad=800
+ ),
+ )
+ print(f"Tmrt: {result.tmrt.mean():.1f}°C")
+
+## Time Series
+
+ results = solweig.calculate_timeseries(
+ surface=surface,
+ weather_series=[weather1, weather2, weather3],
+ location=location,
+ )
+
+## Utilities
+
+ # Load raster data
+ dsm, transform, crs, nodata = solweig.io.load_raster("dsm.tif")
+
+ # Generate wall heights and aspects
+ solweig.walls.generate_wall_hts(dsm_path, bbox, out_dir)
+"""
+
+import contextlib
+import logging
+from importlib.metadata import PackageNotFoundError, version
+
+logger = logging.getLogger(__name__)
+
+# Version: single source of truth is pyproject.toml
+try:
+ __version__ = version("solweig")
+except PackageNotFoundError:
+ __version__ = "0.0.0.dev0" # Fallback for editable/source installs without metadata
+
+# Import simplified API
+# Import utility modules
+from . import io, progress, walls # noqa: E402
+from .api import ( # noqa: E402
+ HumanParams,
+ Location,
+ ModelConfig,
+ PrecomputedData,
+ SolweigResult,
+ SurfaceData,
+ TileSpec,
+ Weather,
+ calculate,
+ # Tiled processing helpers
+ calculate_buffer_distance,
+ calculate_tiled,
+ calculate_timeseries,
+ calculate_timeseries_tiled,
+ compute_pet,
+ compute_pet_grid,
+ # Post-processing: Thermal comfort indices
+ compute_utci,
+ compute_utci_grid,
+ # Run metadata/provenance
+ create_run_metadata,
+ # I/O
+ download_epw,
+ generate_tiles,
+ load_materials,
+ load_params,
+ load_physics,
+ load_run_metadata,
+ save_run_metadata,
+ # Validation
+ validate_inputs,
+)
+from .errors import SolweigError # noqa: E402
+
+# Try to import Rust algorithms
+try:
+ from .rustalgos import GPU_ENABLED, RELEASE_BUILD, gvf, pet, shadowing, sky, skyview, utci, vegetation
+
+ # Enable GPU by default if available
+ if GPU_ENABLED:
+ shadowing.enable_gpu()
+ logger.info("GPU acceleration enabled by default")
+ else:
+ logger.debug("GPU support not compiled in this build")
+
+except ImportError as e:
+ logger.warning(f"Failed to import Rust algorithms: {e}")
+ GPU_ENABLED = False
+ RELEASE_BUILD = False
+ shadowing = None
+ skyview = None
+ gvf = None
+ sky = None
+ vegetation = None
+ utci = None
+ pet = None
+
+
+def is_gpu_available() -> bool:
+ """
+ Check if GPU acceleration is available at runtime.
+
+ Returns True if:
+ - GPU support was compiled into the Rust extension
+ - A GPU device was successfully detected and initialized
+
+ Use this to check GPU status before running compute-intensive operations.
+
+ Returns:
+ True if GPU acceleration is available, False otherwise.
+ """
+ if not GPU_ENABLED:
+ return False
+ if shadowing is None:
+ return False
+ try:
+ return shadowing.is_gpu_enabled()
+ except (AttributeError, RuntimeError):
+ return False
+
+
+def get_compute_backend() -> str:
+ """
+ Get the current compute backend.
+
+ Returns:
+ "gpu" if GPU acceleration is available and enabled, "cpu" otherwise.
+ """
+ return "gpu" if is_gpu_available() else "cpu"
+
+
+def disable_gpu() -> None:
+ """
+ Disable GPU acceleration, falling back to CPU.
+
+ This can be useful for debugging or if GPU results differ from expected.
+ The change takes effect immediately for subsequent calculations.
+ """
+ if shadowing is not None:
+ with contextlib.suppress(AttributeError):
+ shadowing.disable_gpu()
+
+
+__all__ = [
+ # Version
+ "__version__",
+ # Core API
+ "SurfaceData",
+ "PrecomputedData",
+ "Location",
+ "Weather",
+ "HumanParams",
+ "ModelConfig",
+ "SolweigResult",
+ "SolweigError",
+ "calculate",
+ "calculate_timeseries",
+ "calculate_tiled",
+ "calculate_timeseries_tiled",
+ "validate_inputs",
+ "load_params",
+ "load_physics",
+ "load_materials",
+ # Tiled processing
+ "calculate_buffer_distance",
+ "TileSpec",
+ "generate_tiles",
+ # Post-processing: Thermal comfort
+ "compute_utci",
+ "compute_pet",
+ "compute_utci_grid",
+ "compute_pet_grid",
+ # Run metadata/provenance
+ "create_run_metadata",
+ "save_run_metadata",
+ "load_run_metadata",
+ # I/O
+ "download_epw",
+ # Utility modules
+ "io",
+ "walls",
+ "progress",
+ # GPU utilities
+ "is_gpu_available",
+ "get_compute_backend",
+ "disable_gpu",
+ "GPU_ENABLED",
+ "RELEASE_BUILD",
+]
diff --git a/pysrc/solweig/_compat.py b/pysrc/solweig/_compat.py
new file mode 100644
index 0000000..9d932f0
--- /dev/null
+++ b/pysrc/solweig/_compat.py
@@ -0,0 +1,123 @@
+"""Geospatial backend detection — single source of truth.
+
+Determines whether to use rasterio or GDAL for raster I/O and geometric
+utilities. In QGIS / OSGeo4W environments rasterio is never attempted
+(it causes numpy binary-incompatibility crashes).
+
+Exported flags
+--------------
+GDAL_ENV : bool
+ True → use GDAL for raster operations.
+ False → use rasterio.
+RASTERIO_AVAILABLE : bool
+ True when rasterio was successfully imported.
+GDAL_AVAILABLE : bool
+ True when GDAL (osgeo) was successfully imported.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Environment detection
+# ---------------------------------------------------------------------------
+
+
+def in_osgeo_environment() -> bool:
+ """Return True when running inside QGIS or OSGeo4W."""
+ if "qgis" in sys.modules or "qgis.core" in sys.modules:
+ return True
+ if any(k in os.environ for k in ("QGIS_PREFIX_PATH", "QGIS_DEBUG", "OSGEO4W_ROOT")):
+ return True
+ exe = sys.executable.lower()
+ return any(m in exe for m in ("osgeo4w", "qgis"))
+
+
+# ---------------------------------------------------------------------------
+# Import probes
+# ---------------------------------------------------------------------------
+
+
+def _try_import_rasterio() -> bool:
+ try:
+ import pyproj # noqa: F401
+ import rasterio # noqa: F401
+ from rasterio.features import rasterize # noqa: F401
+ from rasterio.mask import mask # noqa: F401
+ from rasterio.transform import Affine, from_origin # noqa: F401
+ from rasterio.windows import Window # noqa: F401
+ from shapely import geometry # noqa: F401
+
+ return True
+ except (ImportError, OSError, RuntimeError) as e:
+ logger.debug("Rasterio import failed: %s", e)
+ return False
+
+
+def _try_import_gdal() -> bool:
+ try:
+ from osgeo import gdal, osr # noqa: F401
+
+ return True
+ except (ImportError, OSError) as e:
+ logger.debug("GDAL import failed: %s", e)
+ return False
+
+
+# ---------------------------------------------------------------------------
+# Backend selection (runs once at first import)
+# ---------------------------------------------------------------------------
+
+
+def _setup_geospatial_backend() -> tuple[bool, bool, bool]:
+ """Choose the geospatial backend.
+
+ Returns (gdal_env, rasterio_available, gdal_available).
+ """
+ # 1. Forced via env-var
+ if os.environ.get("UMEP_USE_GDAL", "").lower() in ("1", "true", "yes"):
+ if _try_import_gdal():
+ logger.info("Using GDAL for raster operations (forced via UMEP_USE_GDAL).")
+ return True, False, True
+ raise ImportError("UMEP_USE_GDAL is set but GDAL could not be imported. Install GDAL or unset UMEP_USE_GDAL.")
+
+ # 2. QGIS / OSGeo4W — prefer GDAL, never try rasterio first
+ if in_osgeo_environment():
+ logger.debug("Detected OSGeo4W/QGIS environment, preferring GDAL backend.")
+ if _try_import_gdal():
+ logger.info("Using GDAL for raster operations (OSGeo4W/QGIS environment).")
+ return True, False, True
+ # Unexpected — GDAL should always be present here
+ logger.warning("GDAL import failed in OSGeo4W/QGIS environment, trying rasterio...")
+ if _try_import_rasterio():
+ logger.info("Using rasterio for raster operations.")
+ return False, True, False
+ raise ImportError(
+ "Failed to import both GDAL and rasterio in OSGeo4W/QGIS environment.\n"
+ "This is unexpected — GDAL should be available. Check your installation."
+ )
+
+ # 3. Standard environment — prefer rasterio, fall back to GDAL
+ if _try_import_rasterio():
+ logger.info("Using rasterio for raster operations.")
+ return False, True, False
+
+ logger.warning("Rasterio import failed, trying GDAL...")
+ if _try_import_gdal():
+ logger.info("Using GDAL for raster operations.")
+ return True, False, True
+
+ raise ImportError(
+ "Neither rasterio nor GDAL could be imported.\n"
+ "Install with: pip install rasterio\n"
+ "Or for QGIS/OSGeo4W environments, ensure GDAL is properly configured."
+ )
+
+
+GDAL_ENV, RASTERIO_AVAILABLE, GDAL_AVAILABLE = _setup_geospatial_backend()
diff --git a/pysrc/solweig/api.py b/pysrc/solweig/api.py
new file mode 100644
index 0000000..b51d695
--- /dev/null
+++ b/pysrc/solweig/api.py
@@ -0,0 +1,483 @@
+"""
+Simplified SOLWEIG API
+
+This module provides a clean, minimal API for SOLWEIG calculations.
+It wraps the complex internal machinery with simple dataclasses that:
+- Take minimal user input
+- Auto-compute derived values (sun position, diffuse fraction, etc.)
+- Provide sensible defaults
+
+Example:
+ import solweig
+ from datetime import datetime
+
+ result = solweig.calculate(
+ surface=solweig.SurfaceData(dsm=my_dsm_array),
+ location=solweig.Location(latitude=57.7, longitude=12.0),
+ weather=solweig.Weather(
+ datetime=datetime(2024, 7, 15, 12, 0),
+ ta=25.0, rh=50.0, global_rad=800.0
+ ),
+ )
+ print(f"Tmrt: {result.tmrt.mean():.1f}°C")
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .computation import calculate_core, calculate_core_fused # noqa: F401 (calculate_core kept for direct use)
+from .errors import (
+ ConfigurationError,
+ GridShapeMismatch,
+ InvalidSurfaceData,
+ MissingPrecomputedData,
+ SolweigError,
+ WeatherDataError,
+)
+from .io import download_epw
+
+# Import from extracted modules
+from .loaders import load_materials, load_params, load_physics, resolve_wall_params
+from .metadata import create_run_metadata, load_run_metadata, save_run_metadata
+from .models import (
+ HumanParams,
+ Location,
+ ModelConfig,
+ PrecomputedData,
+ ShadowArrays,
+ SolweigResult,
+ SurfaceData,
+ SvfArrays,
+ ThermalState,
+ TileSpec,
+ Weather,
+)
+from .postprocess import (
+ compute_pet,
+ compute_pet_grid,
+ compute_utci,
+ compute_utci_grid,
+)
+from .tiling import (
+ calculate_buffer_distance,
+ calculate_tiled,
+ calculate_timeseries_tiled,
+ generate_tiles,
+ validate_tile_size,
+)
+from .timeseries import calculate_timeseries
+from .utils import dict_to_namespace, extract_bounds, intersect_bounds, namespace_to_dict, resample_to_grid
+
+if TYPE_CHECKING:
+ pass
+
+
+def validate_inputs(
+ surface: SurfaceData,
+ location: Location | None = None,
+ weather: Weather | list[Weather] | None = None,
+ use_anisotropic_sky: bool = False,
+ precomputed: PrecomputedData | None = None,
+) -> list[str]:
+ """
+ Validate inputs before calculation (preflight check).
+
+ Call this before expensive operations to catch errors early.
+ Raises exceptions for fatal errors, returns warnings for potential issues.
+
+ Args:
+ surface: Surface data to validate.
+ location: Location to validate (optional).
+ weather: Weather data to validate (optional, can be single or list).
+ use_anisotropic_sky: Whether anisotropic sky will be used.
+ precomputed: Precomputed data to validate.
+
+ Returns:
+ List of warning messages (empty if all valid).
+
+ Raises:
+ GridShapeMismatch: If surface grid shapes don't match DSM.
+ MissingPrecomputedData: If required precomputed data is missing.
+ WeatherDataError: If weather data is invalid.
+
+ Example:
+ try:
+ warnings = solweig.validate_inputs(surface, location, weather)
+ for w in warnings:
+ print(f"Warning: {w}")
+ result = solweig.calculate(surface, location, weather)
+ except solweig.GridShapeMismatch as e:
+ print(f"Grid mismatch: {e.field} expected {e.expected}, got {e.got}")
+ except solweig.MissingPrecomputedData as e:
+ print(f"Missing data: {e}")
+ """
+ warnings = []
+ dsm_shape = surface.dsm.shape
+
+ # Check grid shapes match DSM
+ grids_to_check = [
+ ("cdsm", surface.cdsm),
+ ("dem", surface.dem),
+ ("tdsm", surface.tdsm),
+ ("wall_height", surface.wall_height),
+ ("wall_aspect", surface.wall_aspect),
+ ("land_cover", surface.land_cover),
+ ("albedo", surface.albedo),
+ ("emissivity", surface.emissivity),
+ ]
+ for name, grid in grids_to_check:
+ if grid is not None and grid.shape != dsm_shape:
+ raise GridShapeMismatch(name, dsm_shape, grid.shape)
+
+ # Check SVF arrays if present
+ if surface.svf is not None:
+ svf_grids = [
+ ("svf.svf", surface.svf.svf),
+ ("svf.svf_north", surface.svf.svf_north),
+ ("svf.svf_east", surface.svf.svf_east),
+ ("svf.svf_south", surface.svf.svf_south),
+ ("svf.svf_west", surface.svf.svf_west),
+ ]
+ for name, grid in svf_grids:
+ if grid is not None and grid.shape != dsm_shape:
+ raise GridShapeMismatch(name, dsm_shape, grid.shape)
+
+ # Check SVF is available (required for all calculations)
+ if surface.svf is None and (precomputed is None or precomputed.svf is None):
+ raise MissingPrecomputedData(
+ "Sky View Factor (SVF) data is required but not available.",
+ "Call surface.compute_svf() before calculate(), or use SurfaceData.prepare() "
+ "which computes SVF automatically.",
+ )
+
+ # Check anisotropic sky requirements
+ if use_anisotropic_sky:
+ has_shadow_matrices = (precomputed is not None and precomputed.shadow_matrices is not None) or (
+ surface.shadow_matrices is not None
+ )
+ if not has_shadow_matrices:
+ raise MissingPrecomputedData(
+ "shadow_matrices required for anisotropic sky model",
+ "Either set use_anisotropic_sky=False, or provide shadow matrices via "
+ "precomputed=PrecomputedData(shadow_matrices=...) or surface.shadow_matrices",
+ )
+
+ # Check for potential issues (warnings, not errors)
+ if surface.cdsm is not None and not surface._preprocessed and surface.cdsm_relative:
+ warnings.append(
+ "CDSM provided with cdsm_relative=True but preprocess() not called. "
+ "Vegetation heights may be incorrect. Call surface.preprocess() first."
+ )
+ if surface.tdsm is not None and not surface._preprocessed and surface.tdsm_relative:
+ warnings.append(
+ "TDSM provided with tdsm_relative=True but preprocess() not called. "
+ "Trunk heights may be incorrect. Call surface.preprocess() first."
+ )
+
+ # DSM height sanity checks
+ dsm_max = float(np.nanmax(surface.dsm))
+ dsm_min = float(np.nanmin(surface.dsm))
+ height_range = dsm_max - dsm_min
+
+ if height_range > 500:
+ warnings.append(
+ f"DSM height range is {height_range:.0f}m (max={dsm_max:.0f}m, min={dsm_min:.0f}m). "
+ "This exceeds typical urban areas. If your DSM contains terrain elevation, "
+ "provide a DEM to separate ground from building heights."
+ )
+
+ if surface.dem is None and dsm_min > 100:
+ warnings.append(
+ f"DSM minimum value is {dsm_min:.0f}m with no DEM provided. "
+ "If this is above-sea-level elevation, provide a DEM so SOLWEIG can "
+ "compute building heights correctly."
+ )
+
+ # Per-layer relative height mismatch detection
+ for grid_name, grid, is_relative in [
+ ("CDSM", surface.cdsm, surface.cdsm_relative),
+ ("TDSM", surface.tdsm, surface.tdsm_relative),
+ ]:
+ if grid is not None and is_relative:
+ nonzero = grid[grid > 0]
+ if nonzero.size > 0:
+ grid_min_nz = float(np.nanmin(nonzero))
+ if grid_min_nz > 50:
+ flag = f"{grid_name.lower()}_relative"
+ warnings.append(
+ f"{grid_name} minimum non-zero value is {grid_min_nz:.0f}m with "
+ f"{flag}=True. Relative vegetation heights are typically "
+ f"0-50m. If it contains absolute elevations, set {flag}=False."
+ )
+
+ if surface.cdsm is not None and not surface.cdsm_relative and surface._looks_like_relative_heights():
+ cdsm_max = float(np.nanmax(surface.cdsm))
+ warnings.append(
+ f"CDSM values (max={cdsm_max:.1f}m) are much smaller than DSM "
+ f"(min={dsm_min:.1f}m) with cdsm_relative=False. "
+ "If CDSM contains height-above-ground, set cdsm_relative=True "
+ "and call surface.preprocess()."
+ )
+
+ # Validate weather if provided
+ if weather is not None:
+ weather_list = weather if isinstance(weather, list) else [weather]
+ for i, w in enumerate(weather_list):
+ # Basic range checks (Weather.__post_init__ catches some, but we add more)
+ if w.ta < -100 or w.ta > 60:
+ warnings.append(
+ f"Weather[{i}].ta={w.ta}°C is outside typical range [-100, 60]. Verify this is correct."
+ )
+ if w.global_rad > 1400:
+ warnings.append(
+ f"Weather[{i}].global_rad={w.global_rad} W/m² exceeds solar constant. Verify this is correct."
+ )
+
+ return warnings
+
+
+def calculate(
+ surface: SurfaceData,
+ location: Location,
+ weather: Weather,
+ config: ModelConfig | None = None,
+ human: HumanParams | None = None,
+ precomputed: PrecomputedData | None = None,
+ use_anisotropic_sky: bool | None = None,
+ conifer: bool = False,
+ poi_coords: list[tuple[int, int]] | None = None,
+ state: ThermalState | None = None,
+ physics: SimpleNamespace | None = None,
+ materials: SimpleNamespace | None = None,
+ wall_material: str | None = None,
+ max_shadow_distance_m: float | None = None,
+) -> SolweigResult:
+ """
+ Calculate mean radiant temperature (Tmrt).
+
+ This is the main entry point for SOLWEIG calculations.
+
+ Args:
+ surface: Surface/terrain data (DSM required, CDSM/DEM optional).
+ location: Geographic location (lat, lon, UTC offset).
+ weather: Weather data (datetime, temperature, humidity, radiation).
+ config: Model configuration object providing base settings.
+ Explicit parameters (human, use_anisotropic_sky, etc.) override
+ config values when provided.
+ human: Human body parameters (absorption, posture, weight, height, etc.).
+ If None, uses config.human or HumanParams defaults.
+ precomputed: Pre-computed preprocessing data (walls, SVF, shadow matrices). Optional.
+ When provided, skips expensive preprocessing computations.
+ Use PrecomputedData.load() to load from directories.
+ use_anisotropic_sky: Use anisotropic sky model for radiation.
+ If None, uses config.use_anisotropic_sky or defaults to False.
+ Requires precomputed.shadow_matrices to be provided.
+ Uses Perez diffuse model and patch-based longwave calculation.
+ conifer: Treat vegetation as evergreen conifers (always leaf-on). Default False.
+ When False, uses seasonal leaf on/off logic (deciduous trees).
+ When True, vegetation always has leaves (transmissivity constant).
+ Only relevant when CDSM (canopy) data is provided in surface.
+ poi_coords: Optional list of (row, col) coordinates for POI mode.
+ If provided, only computes at these points (much faster).
+ state: Thermal state from previous timestep. Optional.
+ When provided, enables accurate multi-timestep simulation with
+ thermal inertia modeling (TsWaveDelay). The returned result
+ will include updated state for the next timestep.
+ physics: Physics parameters (Tree_settings, Posture geometry) from load_physics().
+ Site-independent scientific constants. If None, uses config.physics or bundled defaults.
+ materials: Material properties (albedo, emissivity per landcover class) from load_materials().
+ Site-specific landcover parameters. Only needed if surface has land_cover grid.
+ If None, uses config.materials.
+ wall_material: Wall material type for temperature model.
+ One of "brick", "concrete", "wood", "cobblestone" (case-insensitive).
+ If None (default), uses generic wall params from materials JSON.
+
+ Returns:
+ SolweigResult with Tmrt and optionally UTCI/PET grids.
+ When state parameter is provided, result.state contains the
+ updated thermal state for the next timestep.
+
+ Example:
+ # Single timestep with all defaults
+ result = calculate(
+ surface=SurfaceData(dsm=my_dsm),
+ location=Location(latitude=57.7, longitude=12.0),
+ weather=Weather(datetime=dt, ta=25, rh=50, global_rad=800),
+ )
+
+ # Multi-timestep with state management
+ state = ThermalState.initial(dsm.shape)
+ for weather in weather_list:
+ result = calculate(surface, location, weather, state=state)
+ state = result.state # Carry forward to next timestep
+
+ # With custom human parameters
+ result = calculate(
+ surface=surface,
+ location=location,
+ weather=weather,
+ human=HumanParams(abs_k=0.65, weight=70, height=1.65),
+ )
+
+ # With config as base, explicit param override
+ config = ModelConfig(use_anisotropic_sky=True)
+ result = calculate(
+ surface, location, weather,
+ config=config,
+ use_anisotropic_sky=False, # Explicit param wins
+ )
+ """
+ import logging
+
+ logger = logging.getLogger(__name__)
+
+ # Build effective configuration: explicit params override config
+ # Config provides base values, explicit params take precedence
+ effective_aniso = use_anisotropic_sky
+ effective_human = human
+ effective_physics = physics
+ effective_materials = materials
+ effective_max_shadow = max_shadow_distance_m
+
+ if config is not None:
+ # Use config values as fallback for None parameters
+ if effective_aniso is None:
+ effective_aniso = config.use_anisotropic_sky
+ if effective_human is None:
+ effective_human = config.human
+ if effective_physics is None:
+ effective_physics = config.physics
+ if effective_materials is None:
+ effective_materials = config.materials
+ if effective_max_shadow is None:
+ effective_max_shadow = config.max_shadow_distance_m
+
+ # Debug log when explicit params override config
+ overrides = []
+ if use_anisotropic_sky is not None and use_anisotropic_sky != config.use_anisotropic_sky:
+ overrides.append(f"use_anisotropic_sky={use_anisotropic_sky}")
+ if human is not None and config.human is not None:
+ overrides.append("human")
+ if physics is not None and config.physics is not None:
+ overrides.append("physics")
+ if materials is not None and config.materials is not None:
+ overrides.append("materials")
+ if overrides:
+ logger.debug(f"Explicit params override config: {', '.join(overrides)}")
+
+ # Apply defaults for anything still None
+ if effective_aniso is None:
+ effective_aniso = False
+ if effective_human is None:
+ effective_human = HumanParams()
+ # Auto-load bundled UMEP JSON as default materials (single source of truth)
+ if effective_materials is None:
+ effective_materials = load_params()
+
+ # Assign back to use in the rest of the function
+ use_anisotropic_sky = effective_aniso
+ human = effective_human
+ physics = effective_physics
+ materials = effective_materials
+
+ # Use default human params if not provided
+ if human is None:
+ human = HumanParams()
+
+ # Load default physics if not provided
+ if physics is None:
+ physics = load_physics()
+
+ # Compute derived weather values (sun position, radiation split)
+ if not weather._derived_computed:
+ weather.compute_derived(location)
+
+ # Note: poi_coords parameter exists but POI mode not yet implemented
+ if poi_coords is not None:
+ raise NotImplementedError("POI mode (point-of-interest calculation) is planned for Phase 4")
+
+ # Fill NaN in surface layers (idempotent — skipped if already done)
+ surface.fill_nan()
+
+ # Fused Rust pipeline — single FFI call per daytime timestep.
+ # Both isotropic and anisotropic sky models are supported.
+ return calculate_core_fused(
+ surface=surface,
+ location=location,
+ weather=weather,
+ human=human,
+ precomputed=precomputed,
+ state=state,
+ physics=physics,
+ materials=materials,
+ conifer=conifer,
+ wall_material=wall_material,
+ use_anisotropic_sky=use_anisotropic_sky,
+ max_shadow_distance_m=effective_max_shadow,
+ )
+
+
+# =============================================================================
+# Public API - All exports
+# =============================================================================
+
+__all__ = [
+ # Main calculation functions
+ "calculate",
+ "calculate_timeseries",
+ "calculate_tiled",
+ "calculate_timeseries_tiled",
+ "validate_inputs",
+ # Dataclasses - Core inputs
+ "SurfaceData",
+ "Location",
+ "Weather",
+ "HumanParams",
+ # Dataclasses - Configuration
+ "ModelConfig",
+ "PrecomputedData",
+ "ThermalState",
+ "TileSpec",
+ # Dataclasses - Internal (for advanced use)
+ "SvfArrays",
+ "ShadowArrays",
+ # Results
+ "SolweigResult",
+ # Errors
+ "SolweigError",
+ "InvalidSurfaceData",
+ "GridShapeMismatch",
+ "MissingPrecomputedData",
+ "WeatherDataError",
+ "ConfigurationError",
+ # Post-processing
+ "compute_utci",
+ "compute_pet",
+ "compute_utci_grid",
+ "compute_pet_grid",
+ # Configuration loading
+ "load_params",
+ "load_physics",
+ "load_materials",
+ "resolve_wall_params",
+ # Metadata
+ "create_run_metadata",
+ "save_run_metadata",
+ "load_run_metadata",
+ # Tiling utilities
+ "calculate_buffer_distance",
+ "validate_tile_size",
+ "generate_tiles",
+ # I/O
+ "download_epw",
+ # Utilities
+ "dict_to_namespace",
+ "namespace_to_dict",
+ "extract_bounds",
+ "intersect_bounds",
+ "resample_to_grid",
+]
diff --git a/pysrc/solweig/buffers.py b/pysrc/solweig/buffers.py
new file mode 100644
index 0000000..abf669b
--- /dev/null
+++ b/pysrc/solweig/buffers.py
@@ -0,0 +1,246 @@
+"""
+Pre-allocated buffer pools for reducing per-timestep memory allocation.
+
+This module provides a BufferPool class that manages reusable numpy arrays
+to avoid repeated allocation/deallocation during time series calculations.
+
+Usage:
+ pool = BufferPool(shape=(1000, 1000))
+
+ # Get a zeroed buffer
+ temp = pool.get_zeros("ani_lum")
+
+ # Get an uninitialized buffer (faster, use when you'll overwrite all values)
+ temp = pool.get("shadow_temp")
+
+ # Buffers are automatically reused on next get() call with same name
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+
+class BufferPool:
+ """
+ Manages pre-allocated numpy arrays for reuse across timesteps.
+
+ This reduces memory allocation overhead during time series calculations
+ by reusing the same memory for intermediate computations.
+
+ The pool uses named buffers - each unique name gets its own buffer that
+ persists across calls. When you request a buffer by name, you get the
+ same underlying memory (optionally zeroed).
+
+ Attributes:
+ shape: The 2D shape for all buffers in this pool
+ dtype: Data type for buffers (default: float32)
+ _buffers: Dictionary mapping names to pre-allocated arrays
+
+ Example:
+ pool = BufferPool((1000, 1000))
+
+ # First call allocates
+ buf1 = pool.get_zeros("radiation_temp")
+ buf1[:] = some_computation()
+
+ # Second call reuses same memory (zeroed)
+ buf1 = pool.get_zeros("radiation_temp") # Same buffer, zeroed
+ """
+
+ __slots__ = ("shape", "dtype", "_buffers")
+
+ def __init__(
+ self,
+ shape: tuple[int, int],
+ dtype: np.dtype | type = np.float32,
+ ) -> None:
+ """
+ Initialize a buffer pool.
+
+ Args:
+ shape: 2D shape (rows, cols) for all buffers
+ dtype: NumPy dtype for buffers (default: float32)
+ """
+ self.shape = shape
+ self.dtype = np.dtype(dtype)
+ self._buffers: dict[str, NDArray[np.floating]] = {}
+
+ def get(self, name: str) -> NDArray[np.floating]:
+ """
+ Get a buffer by name (uninitialized).
+
+ Returns an uninitialized buffer - use this when you will overwrite
+ all values anyway. Faster than get_zeros().
+
+ Args:
+ name: Unique identifier for this buffer
+
+ Returns:
+ Pre-allocated array (contents undefined)
+ """
+ if name not in self._buffers:
+ self._buffers[name] = np.empty(self.shape, dtype=self.dtype)
+ return self._buffers[name]
+
+ def get_zeros(self, name: str) -> NDArray[np.floating]:
+ """
+ Get a zeroed buffer by name.
+
+ Returns a buffer filled with zeros. Use this when you need
+ a clean slate for accumulation operations.
+
+ Args:
+ name: Unique identifier for this buffer
+
+ Returns:
+ Pre-allocated array filled with zeros
+ """
+ buf = self.get(name)
+ buf.fill(0.0)
+ return buf
+
+ def get_full(self, name: str, fill_value: float) -> NDArray[np.floating]:
+ """
+ Get a buffer filled with a specific value.
+
+ Args:
+ name: Unique identifier for this buffer
+ fill_value: Value to fill the buffer with
+
+ Returns:
+ Pre-allocated array filled with fill_value
+ """
+ buf = self.get(name)
+ buf.fill(fill_value)
+ return buf
+
+ def ensure_float32(
+ self,
+ arr: NDArray,
+ name: str | None = None,
+ ) -> NDArray[np.float32]:
+ """
+ Ensure array is float32, using pooled buffer if conversion needed.
+
+ If the array is already float32, returns it unchanged (no copy).
+ If conversion is needed and a name is provided, uses a pooled buffer.
+ Otherwise, falls back to regular astype().
+
+ Args:
+ arr: Input array (any dtype)
+ name: Optional buffer name for pooled conversion
+
+ Returns:
+ Array with float32 dtype (may be same object if already float32)
+ """
+ if arr.dtype == np.float32:
+ return arr
+
+ if name is not None and arr.shape == self.shape:
+ buf = self.get(name)
+ np.copyto(buf, arr, casting="unsafe")
+ return buf
+
+ return arr.astype(np.float32)
+
+ def clear(self) -> None:
+ """
+ Clear all buffers from the pool.
+
+ Call this to release memory when done with a calculation series.
+ """
+ self._buffers.clear()
+
+ @property
+ def num_buffers(self) -> int:
+ """Number of buffers currently allocated."""
+ return len(self._buffers)
+
+ @property
+ def memory_bytes(self) -> int:
+ """Total memory used by all buffers in bytes."""
+ if not self._buffers:
+ return 0
+ return len(self._buffers) * self.shape[0] * self.shape[1] * self.dtype.itemsize
+
+ def __repr__(self) -> str:
+ mb = self.memory_bytes / (1024 * 1024)
+ return f"BufferPool(shape={self.shape}, dtype={self.dtype}, buffers={self.num_buffers}, memory={mb:.1f}MB)"
+
+
+class TimestepBuffers:
+ """
+ Context manager for timestep-scoped buffer reuse.
+
+ This provides a convenient way to reuse buffers within a single timestep
+ calculation without polluting the namespace.
+
+ Usage:
+ with TimestepBuffers((1000, 1000)) as buffers:
+ temp1 = buffers.get_zeros("radiation")
+ temp2 = buffers.get_zeros("shadow")
+ # ... use buffers ...
+ # Buffers are cleared when exiting context
+ """
+
+ __slots__ = ("pool",)
+
+ def __init__(self, shape: tuple[int, int], dtype: np.dtype | type = np.float32):
+ self.pool = BufferPool(shape, dtype)
+
+ def __enter__(self) -> BufferPool:
+ return self.pool
+
+ def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+ self.pool.clear()
+ return None
+
+
+def ensure_float32_inplace(arr: NDArray) -> NDArray[np.float32]:
+ """
+ Convert array to float32 in-place if possible, otherwise copy.
+
+ This is a utility function for cases where we want to avoid allocation
+ when the input is already float32.
+
+ Args:
+ arr: Input array
+
+ Returns:
+ Float32 array (same object if already float32, new array otherwise)
+ """
+ if arr.dtype == np.float32:
+ return arr
+ return arr.astype(np.float32)
+
+
+def as_float32(arr: NDArray) -> NDArray[np.float32]:
+ """
+ Ensure array is float32, avoiding copy if already correct dtype.
+
+ Shorthand for ensure_float32_inplace() - use this in component code
+ to replace `.astype(np.float32)` calls where the array might already
+ be float32.
+
+ Args:
+ arr: Input array (any dtype)
+
+ Returns:
+ Float32 array (same object if already float32, copy otherwise)
+
+ Example:
+ # Instead of:
+ svf.astype(np.float32) # Always copies
+
+ # Use:
+ as_float32(svf) # Only copies if needed
+ """
+ if arr.dtype == np.float32:
+ return arr
+ return arr.astype(np.float32)
diff --git a/pysrc/solweig/bundles.py b/pysrc/solweig/bundles.py
new file mode 100644
index 0000000..a92ed54
--- /dev/null
+++ b/pysrc/solweig/bundles.py
@@ -0,0 +1,271 @@
+"""
+Data bundle classes for SOLWEIG computation components.
+
+These dataclasses group related arrays and values to reduce parameter passing
+and make data flow clearer through the computation pipeline.
+
+Each bundle represents the output of a distinct computation stage:
+- DirectionalArrays: N/E/S/W directional components (used by SVF and radiation)
+- SvfBundle: All sky view factor arrays
+- ShadowBundle: Shadow computation results
+- GroundBundle: Ground temperature model outputs
+- RadiationBundle: Radiation calculation results
+- GvfBundle: Ground view factor results
+- LupBundle: Upwelling longwave with thermal state
+
+This modular design enables:
+1. Easier testing of individual components
+2. Clearer boundaries for Rust migration
+3. Reduced parameter counts (bundles instead of 10+ arrays)
+4. Better code organization and maintainability
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ import numpy as np
+ from numpy.typing import NDArray
+
+ from .models import ThermalState
+
+
+@dataclass
+class DirectionalArrays:
+ """
+ Directional arrays for N, E, S, W components.
+
+ Used for:
+ - SVF directional components (svf_north, svf_east, svf_south, svf_west)
+ - Radiation directional components (kside_n, kside_e, kside_s, kside_w)
+ - Longwave directional components (lside_n, lside_e, lside_s, lside_w)
+
+ Attributes:
+ north: North-facing component
+ east: East-facing component
+ south: South-facing component
+ west: West-facing component
+ """
+
+ north: NDArray[np.floating]
+ east: NDArray[np.floating]
+ south: NDArray[np.floating]
+ west: NDArray[np.floating]
+
+
+@dataclass
+class SvfBundle:
+ """
+ Sky View Factor computation results.
+
+ Groups all SVF-related arrays to simplify passing to radiation calculations.
+
+ Attributes:
+ svf: Total sky view factor (0-1)
+ svf_directional: Directional SVF components (N, E, S, W)
+ svf_veg: Vegetation-only SVF
+ svf_veg_directional: Directional vegetation SVF (N, E, S, W)
+ svf_aveg: SVF above vegetation (building shadow on veg)
+ svf_aveg_directional: Directional SVF above vegetation (N, E, S, W)
+ svfbuveg: Combined SVF accounting for vegetation transmissivity
+ svfalfa: Angular factor from SVF (for anisotropic calculations)
+ """
+
+ svf: NDArray[np.floating]
+ svf_directional: DirectionalArrays
+ svf_veg: NDArray[np.floating]
+ svf_veg_directional: DirectionalArrays
+ svf_aveg: NDArray[np.floating]
+ svf_aveg_directional: DirectionalArrays
+ svfbuveg: NDArray[np.floating]
+ svfalfa: NDArray[np.floating]
+
+
+@dataclass
+class ShadowBundle:
+ """
+ Shadow computation results.
+
+ Attributes:
+ shadow: Combined shadow fraction (0=sun, 1=shadow)
+ bldg_sh: Building shadow only
+ veg_sh: Vegetation shadow only
+ wallsun: Wall sun exposure (for wall temperature)
+ psi: Vegetation transmissivity used (for reference)
+ """
+
+ shadow: NDArray[np.floating]
+ bldg_sh: NDArray[np.floating]
+ veg_sh: NDArray[np.floating]
+ wallsun: NDArray[np.floating]
+ psi: float
+
+
+@dataclass
+class GroundBundle:
+ """
+ Ground temperature model outputs.
+
+ Results from the ground temperature computation, including
+ spatially-varying surface properties.
+
+ Attributes:
+ tg: Ground temperature deviation from air temperature (K or °C)
+ tg_wall: Wall temperature deviation from air temperature
+ ci_tg: Clearness index correction factor
+ alb_grid: Albedo per pixel (0-1)
+ emis_grid: Emissivity per pixel (0-1)
+ """
+
+ tg: NDArray[np.floating]
+ tg_wall: float
+ ci_tg: float
+ alb_grid: NDArray[np.floating]
+ emis_grid: NDArray[np.floating]
+
+
+@dataclass
+class GvfBundle:
+ """
+ Ground View Factor computation results.
+
+ Includes upwelling longwave radiation components before thermal delay
+ and albedo view factors for reflected shortwave radiation.
+
+ Attributes:
+ lup: Upwelling longwave radiation (W/m²)
+ lup_e: Upwelling longwave from east
+ lup_s: Upwelling longwave from south
+ lup_w: Upwelling longwave from west
+ lup_n: Upwelling longwave from north
+ gvfalb: Ground view factor × albedo (for Kup calculation)
+ gvfalb_e: GVF × albedo from east
+ gvfalb_s: GVF × albedo from south
+ gvfalb_w: GVF × albedo from west
+ gvfalb_n: GVF × albedo from north
+ gvfalbnosh: GVF × albedo without shadow (for anisotropic)
+ gvfalbnosh_e: GVF × albedo (no shadow) from east
+ gvfalbnosh_s: GVF × albedo (no shadow) from south
+ gvfalbnosh_w: GVF × albedo (no shadow) from west
+ gvfalbnosh_n: GVF × albedo (no shadow) from north
+ """
+
+ lup: NDArray[np.floating]
+ lup_e: NDArray[np.floating]
+ lup_s: NDArray[np.floating]
+ lup_w: NDArray[np.floating]
+ lup_n: NDArray[np.floating]
+ gvfalb: NDArray[np.floating]
+ gvfalb_e: NDArray[np.floating]
+ gvfalb_s: NDArray[np.floating]
+ gvfalb_w: NDArray[np.floating]
+ gvfalb_n: NDArray[np.floating]
+ gvfalbnosh: NDArray[np.floating]
+ gvfalbnosh_e: NDArray[np.floating]
+ gvfalbnosh_s: NDArray[np.floating]
+ gvfalbnosh_w: NDArray[np.floating]
+ gvfalbnosh_n: NDArray[np.floating]
+
+
+@dataclass
+class LupBundle:
+ """
+ Upwelling longwave radiation with thermal state.
+
+ Results after applying TsWaveDelay thermal inertia model.
+ Includes updated thermal state for next timestep.
+
+ Attributes:
+ lup: Final upwelling longwave (center view) after thermal delay
+ lup_e: Final upwelling longwave from east
+ lup_s: Final upwelling longwave from south
+ lup_w: Final upwelling longwave from west
+ lup_n: Final upwelling longwave from north
+ state: Updated thermal state to carry forward to next timestep
+ """
+
+ lup: NDArray[np.floating]
+ lup_e: NDArray[np.floating]
+ lup_s: NDArray[np.floating]
+ lup_w: NDArray[np.floating]
+ lup_n: NDArray[np.floating]
+ state: ThermalState | None # Forward reference to avoid circular import
+
+
+@dataclass
+class RadiationBundle:
+ """
+ Radiation calculation outputs.
+
+ Complete radiation budget including shortwave and longwave components.
+
+ Attributes:
+ kdown: Downwelling shortwave radiation (W/m²)
+ kup: Upwelling shortwave radiation (W/m²)
+ ldown: Downwelling longwave radiation (W/m²)
+ lup: Upwelling longwave radiation (W/m²)
+ kside: Shortwave radiation from 4 directions (W/m²)
+ lside: Longwave radiation from 4 directions (W/m²)
+ kside_total: Total shortwave on vertical surface (for anisotropic Tmrt)
+ lside_total: Total longwave on vertical surface (for anisotropic Tmrt)
+ drad: Diffuse radiation term (for Tmrt calculation)
+ """
+
+ kdown: NDArray[np.floating]
+ kup: NDArray[np.floating]
+ ldown: NDArray[np.floating]
+ lup: NDArray[np.floating]
+ kside: DirectionalArrays
+ lside: DirectionalArrays
+ kside_total: NDArray[np.floating]
+ lside_total: NDArray[np.floating]
+ drad: NDArray[np.floating]
+
+
+@dataclass
+class WallBundle:
+ """
+ Wall geometry data.
+
+ Wall heights and aspects needed for shadow calculation and wall temperature.
+
+ Attributes:
+ wall_height: Wall height at each pixel (meters)
+ wall_aspect: Wall orientation at each pixel (degrees, 0=North)
+ """
+
+ wall_height: NDArray[np.floating]
+ wall_aspect: NDArray[np.floating]
+
+
+@dataclass
+class VegetationBundle:
+ """
+ Vegetation geometry data.
+
+ Vegetation heights needed for shadow and SVF calculations.
+
+ Attributes:
+ cdsm: Canopy Digital Surface Model (vegetation heights)
+ tdsm: Trunk Digital Surface Model (trunk zone heights)
+ bush: Bush/shrub layer (boolean or height)
+ """
+
+ cdsm: NDArray[np.floating] | None
+ tdsm: NDArray[np.floating] | None
+ bush: NDArray[np.floating] | None
+
+
+__all__ = [
+ "DirectionalArrays",
+ "SvfBundle",
+ "ShadowBundle",
+ "GroundBundle",
+ "GvfBundle",
+ "LupBundle",
+ "RadiationBundle",
+ "WallBundle",
+ "VegetationBundle",
+]
diff --git a/pysrc/solweig/cache.py b/pysrc/solweig/cache.py
new file mode 100644
index 0000000..8e165ca
--- /dev/null
+++ b/pysrc/solweig/cache.py
@@ -0,0 +1,187 @@
+"""
+Cache validation utilities for SVF and wall data.
+
+Provides hash-based validation to detect stale caches when input data changes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+ pass
+
+logger = logging.getLogger(__name__)
+
+# Cache metadata filename
+CACHE_METADATA_FILE = "cache_meta.json"
+
+
+def compute_array_hash(arr: np.ndarray, *, sample_size: int = 10000) -> str:
+ """
+ Compute a fast hash of a numpy array.
+
+ Uses a combination of shape, dtype, and sampled values for speed.
+ For large arrays, samples evenly spaced values rather than hashing everything.
+
+ Args:
+ arr: Numpy array to hash.
+ sample_size: Maximum number of values to sample for hashing.
+
+ Returns:
+ Hex string hash.
+ """
+ hasher = hashlib.sha256()
+
+ # Include shape and dtype
+ hasher.update(str(arr.shape).encode())
+ hasher.update(str(arr.dtype).encode())
+
+ # For small arrays, hash everything
+ flat = arr.ravel()
+ if len(flat) <= sample_size:
+ hasher.update(flat.tobytes())
+ else:
+ # Sample evenly spaced values for large arrays
+ indices = np.linspace(0, len(flat) - 1, sample_size, dtype=np.int64)
+ hasher.update(flat[indices].tobytes())
+
+ return hasher.hexdigest()[:16] # First 16 chars is enough
+
+
+@dataclass
+class CacheMetadata:
+ """Metadata for cache validation."""
+
+ dsm_hash: str
+ dsm_shape: tuple[int, int]
+ pixel_size: float
+ cdsm_hash: str | None = None
+ version: str = "1.0"
+
+ def to_dict(self) -> dict:
+ """Convert to dictionary for JSON serialization."""
+ return {
+ "version": self.version,
+ "dsm_hash": self.dsm_hash,
+ "dsm_shape": list(self.dsm_shape),
+ "pixel_size": self.pixel_size,
+ "cdsm_hash": self.cdsm_hash,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict) -> CacheMetadata:
+ """Create from dictionary."""
+ return cls(
+ version=data.get("version", "1.0"),
+ dsm_hash=data["dsm_hash"],
+ dsm_shape=tuple(data["dsm_shape"]),
+ pixel_size=data["pixel_size"],
+ cdsm_hash=data.get("cdsm_hash"),
+ )
+
+ @classmethod
+ def from_arrays(
+ cls,
+ dsm: np.ndarray,
+ pixel_size: float,
+ cdsm: np.ndarray | None = None,
+ ) -> CacheMetadata:
+ """Create metadata from input arrays."""
+ return cls(
+ dsm_hash=compute_array_hash(dsm),
+ dsm_shape=(dsm.shape[0], dsm.shape[1]),
+ pixel_size=pixel_size,
+ cdsm_hash=compute_array_hash(cdsm) if cdsm is not None else None,
+ )
+
+ def matches(self, other: CacheMetadata) -> bool:
+ """Check if this metadata matches another."""
+ return (
+ self.dsm_hash == other.dsm_hash
+ and self.dsm_shape == other.dsm_shape
+ and abs(self.pixel_size - other.pixel_size) < 0.001
+ and self.cdsm_hash == other.cdsm_hash
+ )
+
+ def save(self, directory: Path) -> None:
+ """Save metadata to cache directory."""
+ meta_path = directory / CACHE_METADATA_FILE
+ with open(meta_path, "w") as f:
+ json.dump(self.to_dict(), f, indent=2)
+
+ @classmethod
+ def load(cls, directory: Path) -> CacheMetadata | None:
+ """Load metadata from cache directory. Returns None if not found."""
+ meta_path = directory / CACHE_METADATA_FILE
+ if not meta_path.exists():
+ return None
+ try:
+ with open(meta_path) as f:
+ data = json.load(f)
+ return cls.from_dict(data)
+ except (json.JSONDecodeError, KeyError) as e:
+ logger.warning(f"Failed to load cache metadata: {e}")
+ return None
+
+
+def validate_cache(
+ cache_dir: Path,
+ dsm: np.ndarray,
+ pixel_size: float,
+ cdsm: np.ndarray | None = None,
+) -> bool:
+ """
+ Validate that cached data matches current inputs.
+
+ Args:
+ cache_dir: Directory containing cached data.
+ dsm: Current DSM array.
+ pixel_size: Current pixel size.
+ cdsm: Current CDSM array (optional).
+
+ Returns:
+ True if cache is valid, False if stale or missing.
+ """
+ stored = CacheMetadata.load(cache_dir)
+ if stored is None:
+ logger.debug(f"No cache metadata found in {cache_dir}")
+ return False
+
+ current = CacheMetadata.from_arrays(dsm, pixel_size, cdsm)
+
+ if stored.matches(current):
+ logger.debug(f"Cache validated: {cache_dir}")
+ return True
+ else:
+ logger.info(f"Cache stale (input changed): {cache_dir}")
+ logger.debug(f" Stored: dsm_hash={stored.dsm_hash}, shape={stored.dsm_shape}")
+ logger.debug(f" Current: dsm_hash={current.dsm_hash}, shape={current.dsm_shape}")
+ return False
+
+
+def clear_stale_cache(cache_dir: Path) -> None:
+ """
+ Remove stale cache files from a directory.
+
+ Deletes all .npy files and the metadata file.
+ """
+ if not cache_dir.exists():
+ return
+
+ import shutil
+
+ for item in cache_dir.iterdir():
+ if item.is_file() and (item.suffix == ".npy" or item.name == CACHE_METADATA_FILE):
+ item.unlink()
+ elif item.is_dir():
+ shutil.rmtree(item)
+
+ logger.info(f"Cleared stale cache: {cache_dir}")
diff --git a/pysrc/solweig/components/__init__.py b/pysrc/solweig/components/__init__.py
new file mode 100644
index 0000000..e03905d
--- /dev/null
+++ b/pysrc/solweig/components/__init__.py
@@ -0,0 +1,17 @@
+"""
+SOLWEIG computation components.
+
+This package contains modular computation functions extracted from the
+monolithic `_calculate_core()` function. Each component is responsible
+for a specific part of the Tmrt calculation.
+
+Components:
+- ground: Ground temperature model (TgMaps)
+- svf_resolution: SVF (Sky View Factor) resolution from multiple sources
+- shadows: Shadow computation with vegetation transmissivity
+- gvf: Ground View Factor calculation (upwelling radiation from surfaces)
+- radiation: Complete radiation budget (shortwave and longwave from all directions)
+- tmrt: Mean Radiant Temperature calculation from radiation budget
+"""
+
+__all__ = ["ground", "svf_resolution", "shadows", "gvf", "radiation", "tmrt"]
diff --git a/pysrc/solweig/components/ground.py b/pysrc/solweig/components/ground.py
new file mode 100644
index 0000000..131129d
--- /dev/null
+++ b/pysrc/solweig/components/ground.py
@@ -0,0 +1,137 @@
+"""
+Ground temperature model component.
+
+Implements the SOLWEIG TgMaps ground temperature model with:
+- Parameterization from land cover properties
+- Diurnal temperature cycle based on sun altitude
+- Clearness index correction for cloudy conditions
+
+Reference:
+- Lindberg et al. (2008, 2016) - SOLWEIG ground temperature parameterization
+- Reindl et al. (1990) - Clearness index approach
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..bundles import GroundBundle
+from ..physics.clearnessindex_2013b import clearnessindex_2013b
+from ..physics.daylen import daylen
+from ..physics.diffusefraction import diffusefraction
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..api import Location, Weather
+
+
+def compute_ground_temperature(
+ weather: Weather,
+ location: Location,
+ alb_grid: NDArray[np.floating],
+ emis_grid: NDArray[np.floating],
+ tgk_grid: NDArray[np.floating],
+ tstart_grid: NDArray[np.floating],
+ tmaxlst_grid: NDArray[np.floating],
+ *,
+ tgk_wall: float | None = None,
+ tstart_wall: float | None = None,
+ tmaxlst_wall: float | None = None,
+) -> GroundBundle:
+ """
+ Compute ground and wall temperature deviations from air temperature.
+
+ Uses the SOLWEIG TgMaps model with land-cover-specific parameterization.
+ Temperature amplitude depends on max sun altitude and land cover type.
+ Clearness index correction accounts for reduced heating under cloudy skies.
+
+ Args:
+ weather: Weather data including temperature, radiation, sun position
+ location: Geographic location (latitude, longitude) for sunrise calculation
+ alb_grid: Albedo per pixel (0-1) from land cover properties
+ emis_grid: Emissivity per pixel (0-1) from land cover properties
+ tgk_grid: TgK parameter per pixel (temperature gain coefficient)
+ tstart_grid: Tstart parameter per pixel (temperature baseline offset)
+ tmaxlst_grid: TmaxLST parameter per pixel (hour of maximum temperature)
+ tgk_wall: Optional wall TgK parameter. If None, uses cobblestone default (0.37).
+ tstart_wall: Optional wall Tstart parameter. If None, uses cobblestone default (-3.41).
+ tmaxlst_wall: Optional wall TmaxLST parameter. If None, uses cobblestone default (15.0).
+
+ Returns:
+ GroundBundle containing:
+ - tg: Ground temperature deviation from air temperature (K)
+ - tg_wall: Wall temperature deviation from air temperature (K)
+ - ci_tg: Clearness index correction factor (0-1)
+ - alb_grid: Albedo grid (passed through for convenience)
+ - emis_grid: Emissivity grid (passed through for convenience)
+
+ Reference:
+ Lindberg et al. (2008): "Urban Multi-scale Environmental Predictor (UMEP)"
+ Formula: Tgamp = TgK * altmax + Tstart
+ Tg = Tgamp * sin(phase * pi/2) * CI_TgG
+ """
+ from ..rustalgos import ground as ground_rust
+
+ # Day of year and sunrise time
+ jday = weather.datetime.timetuple().tm_yday
+ _, _, _, snup = daylen(jday, location.latitude)
+
+ # Maximum sun altitude for the day (computed in Weather.compute_derived())
+ altmax = weather.altmax
+
+ # Decimal time (fraction of day)
+ dectime = (weather.datetime.hour + weather.datetime.minute / 60.0) / 24.0
+
+ # CI_TgG correction for non-clear conditions (Lindberg et al. 2008, Reindl et al. 1990)
+ # This accounts for reduced ground heating under cloudy skies
+ # Full formula from solweig.py: CI_TgG = (radG / radG0) + (1 - corr)
+ zen = (90.0 - weather.sun_altitude) * (np.pi / 180.0) # zenith in radians
+ deg2rad = np.pi / 180.0
+
+ # Get clear sky radiation (I0) from clearnessindex function
+ location_dict = {"latitude": location.latitude, "longitude": location.longitude, "altitude": 0.0}
+ i0, _, _, _, _ = clearnessindex_2013b(
+ zen, jday, weather.ta, weather.rh / 100.0, weather.global_rad, location_dict, -999.0
+ )
+
+ # Calculate clear sky direct and diffuse components
+ if i0 > 0 and weather.sun_altitude > 0:
+ rad_i0, rad_d0 = diffusefraction(i0, weather.sun_altitude, 1.0, weather.ta, weather.rh)
+ # Clear sky global horizontal radiation
+ rad_g0 = rad_i0 * np.sin(weather.sun_altitude * deg2rad) + rad_d0
+ else:
+ rad_g0 = 0.0
+
+ # Zenith angle in degrees
+ zen_deg = 90.0 - weather.sun_altitude
+
+ # Call Rust implementation (positional args to match Rust signature)
+ tg, tg_wall, ci_tg, alb_grid_out, emis_grid_out = ground_rust.compute_ground_temperature(
+ weather.ta,
+ weather.sun_altitude,
+ altmax,
+ dectime,
+ snup,
+ weather.global_rad,
+ rad_g0,
+ zen_deg,
+ alb_grid.astype(np.float32),
+ emis_grid.astype(np.float32),
+ tgk_grid.astype(np.float32),
+ tstart_grid.astype(np.float32),
+ tmaxlst_grid.astype(np.float32),
+ tgk_wall=tgk_wall,
+ tstart_wall=tstart_wall,
+ tmaxlst_wall=tmaxlst_wall,
+ )
+
+ return GroundBundle(
+ tg=tg,
+ tg_wall=float(tg_wall),
+ ci_tg=float(ci_tg),
+ alb_grid=alb_grid_out,
+ emis_grid=emis_grid_out,
+ )
diff --git a/pysrc/solweig/components/gvf.py b/pysrc/solweig/components/gvf.py
new file mode 100644
index 0000000..e5ad40b
--- /dev/null
+++ b/pysrc/solweig/components/gvf.py
@@ -0,0 +1,269 @@
+"""
+Ground View Factor (GVF) computation component.
+
+Computes upwelling longwave radiation from surrounding surfaces (ground + walls)
+and albedo view factors for reflected shortwave radiation.
+
+The GVF represents how much a person at a given height "sees" the ground and walls
+versus the sky. This determines the thermal radiation received from below and sides.
+
+Reference:
+- Lindberg et al. (2008) - SOLWEIG GVF model with wall radiation
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..buffers import as_float32
+from ..bundles import GvfBundle
+from ..constants import KELVIN_OFFSET, SBC
+from ..physics.morphology import generate_binary_structure
+
+try:
+ from ..rustalgos import morphology as _rust_morph
+
+ def _binary_dilation(input_array, structure, iterations):
+ return _rust_morph.binary_dilation(
+ input_array.astype(np.uint8),
+ structure.astype(np.uint8),
+ iterations,
+ ).astype(bool)
+except ImportError:
+ from ..physics.morphology import binary_dilation as _binary_dilation
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..api import HumanParams, SurfaceData, Weather
+
+
+def detect_building_mask(
+ dsm: NDArray[np.floating],
+ land_cover: NDArray[np.integer] | None,
+ wall_height: NDArray[np.floating] | None,
+ pixel_size: float,
+) -> NDArray[np.floating]:
+ """
+ Create a building mask for GVF calculation.
+
+ GVF (Ground View Factor) expects: 0=building, 1=ground.
+ This is used to normalize GVF values over buildings where GVF doesn't apply.
+
+ Args:
+ dsm: Digital Surface Model array.
+ land_cover: Optional land cover grid (UMEP standard: ID 2 = buildings).
+ wall_height: Optional wall height grid.
+ pixel_size: Pixel size in meters.
+
+ Returns:
+ Building mask where 0=building pixels, 1=ground pixels.
+
+ Detection strategy:
+ 1. If land_cover provided: Use ID 2 (buildings) directly
+ 2. Elif wall_height provided: Dilate wall pixels + detect elevated areas
+ 3. Else: Assume all ground (no buildings)
+ """
+ if land_cover is not None:
+ # Use land cover directly: ID 2 = buildings
+ buildings = np.ones_like(dsm, dtype=np.float32)
+ buildings[land_cover == 2] = 0.0
+ return buildings
+
+ if wall_height is not None:
+ # Approximate building footprints from wall heights
+ # Wall pixels mark building edges; dilate to capture interiors
+ wall_mask = wall_height > 0
+
+ # Dilate to capture building interiors (typical building width up to 50m)
+ struct = generate_binary_structure(2, 2) # 8-connectivity
+ iterations = int(25 / pixel_size) + 1
+ dilated = _binary_dilation(wall_mask, struct, iterations=iterations)
+
+ # Also detect elevated areas (building roofs)
+ ground_level = np.nanpercentile(dsm[~wall_mask], 10) if np.any(~wall_mask) else np.nanmin(dsm)
+ elevated = dsm > (ground_level + 2.0) # At least 2m above ground
+
+ # Combine: building pixels where either dilated walls OR elevated flat areas
+ is_building = dilated | (elevated & ~np.isnan(dsm))
+
+ # Invert: 0=building, 1=ground
+ return (~is_building).astype(np.float32)
+
+ # No building info available - assume all ground
+ return np.ones_like(dsm, dtype=np.float32)
+
+
+def compute_gvf(
+ surface: SurfaceData,
+ weather: Weather,
+ human: HumanParams,
+ tg: NDArray[np.floating],
+ tg_wall: float,
+ shadow: NDArray[np.floating],
+ wallsun: NDArray[np.floating],
+ alb_grid: NDArray[np.floating],
+ emis_grid: NDArray[np.floating],
+ svf: NDArray[np.floating],
+ pixel_size: float,
+ wall_ht: NDArray[np.floating] | None = None,
+ wall_asp: NDArray[np.floating] | None = None,
+) -> GvfBundle:
+ """
+ Compute Ground View Factor for upwelling longwave and albedo components.
+
+ GVF represents how much a person "sees" the ground and walls from a given height.
+ This determines thermal radiation received from surrounding surfaces.
+
+ Args:
+ surface: Surface data (DSM, land cover)
+ weather: Weather data (temperature)
+ human: Human parameters (height, posture)
+ tg: Ground temperature deviation from air temperature (K)
+ tg_wall: Wall temperature deviation from air temperature (K)
+ shadow: Combined shadow fraction (0=sun, 1=shadow)
+ wallsun: Wall sun exposure (for wall temperature)
+ alb_grid: Albedo per pixel (0-1)
+ emis_grid: Emissivity per pixel (0-1)
+ svf: Sky view factor (for simplified GVF when no walls)
+ pixel_size: Grid resolution in meters
+ wall_ht: Wall heights (optional, for full GVF with walls)
+ wall_asp: Wall aspects in degrees (optional, for full GVF with walls)
+
+ Returns:
+ GvfBundle containing:
+ - lup_*: Upwelling longwave from 5 directions (center, N, E, S, W)
+ - gvfalb_*: Ground view factor × albedo (for reflected shortwave)
+ - gvfalbnosh_*: GVF × albedo without shadow (for anisotropic)
+
+ Reference:
+ Lindberg et al. (2008) - SOLWEIG model equations for GVF calculation
+ """
+ # Import here to avoid circular dependency
+ from ..rustalgos import gvf as gvf_module
+
+ has_walls = wall_ht is not None and wall_asp is not None
+
+ # Human height parameters for GVF (matching runner: first=round(height), second=round(height*20))
+ first = np.round(human.height)
+ if first == 0.0:
+ first = 1.0
+ second = np.round(human.height * 20.0)
+
+ # Building mask for GVF calculation
+ buildings = detect_building_mask(
+ surface.dsm,
+ surface.land_cover,
+ wall_ht if has_walls else None,
+ pixel_size,
+ )
+
+ # Wall properties (from SOLWEIG parameters)
+ albedo_wall = 0.20
+ emis_wall = 0.90
+
+ # Land cover settings for gvf_calc
+ use_landcover = surface.land_cover is not None
+ lc_grid = surface.land_cover.astype(np.float32) if surface.land_cover is not None else None
+
+ if has_walls:
+ # Type narrowing - wall_ht and wall_asp are not None when has_walls is True
+ assert wall_ht is not None
+ assert wall_asp is not None
+ # Use full GVF calculation with wall radiation
+ # Create parameter struct (reduces 20 params to 11)
+ gvf_params = gvf_module.GvfScalarParams(
+ scale=pixel_size,
+ first=first,
+ second=second,
+ tgwall=tg_wall,
+ ta=weather.ta,
+ ewall=emis_wall,
+ sbc=SBC,
+ albedo_b=albedo_wall,
+ twater=weather.ta, # Twater = Ta (approximation for water temperature)
+ landcover=use_landcover,
+ )
+ gvf_result = gvf_module.gvf_calc(
+ as_float32(wallsun),
+ as_float32(wall_ht),
+ as_float32(buildings),
+ as_float32(shadow),
+ as_float32(wall_asp),
+ as_float32(tg),
+ as_float32(emis_grid),
+ as_float32(alb_grid),
+ lc_grid,
+ gvf_params,
+ )
+
+ # Extract GVF results
+ lup = np.array(gvf_result.gvf_lup)
+ lup_e = np.array(gvf_result.gvf_lup_e)
+ lup_s = np.array(gvf_result.gvf_lup_s)
+ lup_w = np.array(gvf_result.gvf_lup_w)
+ lup_n = np.array(gvf_result.gvf_lup_n)
+ gvfalb = np.array(gvf_result.gvfalb)
+ gvfalb_e = np.array(gvf_result.gvfalb_e)
+ gvfalb_s = np.array(gvf_result.gvfalb_s)
+ gvfalb_w = np.array(gvf_result.gvfalb_w)
+ gvfalb_n = np.array(gvf_result.gvfalb_n)
+ gvfalbnosh = np.array(gvf_result.gvfalbnosh)
+ gvfalbnosh_e = np.array(gvf_result.gvfalbnosh_e)
+ gvfalbnosh_s = np.array(gvf_result.gvfalbnosh_s)
+ gvfalbnosh_w = np.array(gvf_result.gvfalbnosh_w)
+ gvfalbnosh_n = np.array(gvf_result.gvfalbnosh_n)
+ else:
+ # Simplified GVF (no walls)
+ # Ground view factor is complement of sky view factor
+ gvf_simple = 1.0 - svf
+
+ # Ground temperature with shadow effect
+ # Note: shadow=1 for sunlit, shadow=0 for shaded
+ # Multiply tg by shadow - shaded areas have cooler ground
+ # (Rust gvf_calc does this internally for the full path)
+ tg_with_shadow = tg * shadow
+
+ # Upwelling longwave: Stefan-Boltzmann law for ground emission
+ # Lup = emissivity × SBC × T^4
+ lup = emis_grid * SBC * np.power(weather.ta + tg_with_shadow + KELVIN_OFFSET, 4)
+
+ # Simplified: assume isotropic (all directions same)
+ lup_e = lup
+ lup_s = lup
+ lup_w = lup
+ lup_n = lup
+
+ # Albedo view factors for reflected shortwave
+ gvfalb = alb_grid * gvf_simple
+ gvfalb_e = gvfalb
+ gvfalb_s = gvfalb
+ gvfalb_w = gvfalb
+ gvfalb_n = gvfalb
+
+ # Without shadow (for anisotropic calculations)
+ gvfalbnosh = alb_grid
+ gvfalbnosh_e = alb_grid
+ gvfalbnosh_s = alb_grid
+ gvfalbnosh_w = alb_grid
+ gvfalbnosh_n = alb_grid
+
+ return GvfBundle(
+ lup=as_float32(lup),
+ lup_e=as_float32(lup_e),
+ lup_s=as_float32(lup_s),
+ lup_w=as_float32(lup_w),
+ lup_n=as_float32(lup_n),
+ gvfalb=as_float32(gvfalb),
+ gvfalb_e=as_float32(gvfalb_e),
+ gvfalb_s=as_float32(gvfalb_s),
+ gvfalb_w=as_float32(gvfalb_w),
+ gvfalb_n=as_float32(gvfalb_n),
+ gvfalbnosh=as_float32(gvfalbnosh),
+ gvfalbnosh_e=as_float32(gvfalbnosh_e),
+ gvfalbnosh_s=as_float32(gvfalbnosh_s),
+ gvfalbnosh_w=as_float32(gvfalbnosh_w),
+ gvfalbnosh_n=as_float32(gvfalbnosh_n),
+ )
diff --git a/pysrc/solweig/components/radiation.py b/pysrc/solweig/components/radiation.py
new file mode 100644
index 0000000..6d0b320
--- /dev/null
+++ b/pysrc/solweig/components/radiation.py
@@ -0,0 +1,456 @@
+"""
+Radiation calculation component.
+
+Computes complete radiation budget:
+- Shortwave: direct beam, diffuse sky, ground reflection, wall reflection
+- Longwave: sky emission, ground emission, wall emission
+- Directional components (N, E, S, W) for human body sides
+
+Supports both isotropic and anisotropic (Perez et al. 1993) diffuse sky models.
+
+Reference:
+- Lindberg et al. (2008, 2016) - SOLWEIG radiation model
+- Perez et al. (1993) - Anisotropic sky luminance distribution
+- Jonsson et al. (2006) - Longwave radiation formulas
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..buffers import as_float32
+from ..bundles import DirectionalArrays, RadiationBundle
+from ..constants import F_SIDE_SITTING, F_SIDE_STANDING, F_UP_SITTING, F_UP_STANDING, KELVIN_OFFSET, SBC
+from ..physics.Kup_veg_2015a import Kup_veg_2015a
+from ..physics.patch_radiation import patch_steradians
+from ..physics.Perez_v3 import Perez_v3
+from ..rustalgos import sky as _sky
+
+if TYPE_CHECKING:
+ from ..api import HumanParams, PrecomputedData, Weather
+ from ..bundles import GvfBundle, LupBundle, ShadowBundle, SvfBundle
+
+
+def compute_radiation(
+ weather: Weather,
+ svf_bundle: SvfBundle,
+ shadow_bundle: ShadowBundle,
+ gvf_bundle: GvfBundle,
+ lup_bundle: LupBundle,
+ human: HumanParams,
+ use_anisotropic_sky: bool,
+ precomputed: PrecomputedData | None,
+ albedo_wall: float = 0.20,
+ emis_wall: float = 0.90,
+ tg_wall: float = 0.0,
+) -> RadiationBundle:
+ """
+ Compute radiation budget for Tmrt calculation.
+
+ Computes complete shortwave and longwave radiation fluxes from all directions,
+ accounting for sky, ground, walls, and vegetation effects.
+
+ Args:
+ weather: Weather data (temperature, humidity, radiation, sun position)
+ svf_bundle: Sky view factors with directional components
+ shadow_bundle: Shadow fractions and vegetation transmissivity
+ gvf_bundle: Ground view factors and albedo components
+ lup_bundle: Upwelling longwave after thermal delay
+ human: Human parameters (height, posture, absorptivities)
+ use_anisotropic_sky: Use anisotropic (Perez) diffuse model if shadow matrices available
+ precomputed: Optional pre-computed shadow matrices for anisotropic model
+ albedo_wall: Wall albedo (default 0.20 for cobblestone)
+ emis_wall: Wall emissivity (default 0.90 for brick/concrete)
+ tg_wall: Wall temperature deviation from air temperature (K)
+
+ Returns:
+ RadiationBundle containing:
+ - kdown: Downwelling shortwave (W/m²)
+ - kup: Upwelling shortwave (reflected from ground)
+ - ldown: Downwelling longwave (sky + wall emission)
+ - lup: Upwelling longwave (from lup_bundle after thermal delay)
+ - kside: Directional shortwave components (N, E, S, W)
+ - lside: Directional longwave components (N, E, S, W)
+ - kside_direct: Direct beam on vertical surface (for anisotropic)
+ - drad: Diffuse radiation term (anisotropic or isotropic)
+
+ Reference:
+ - Lindberg et al. (2008) - SOLWEIG radiation model equations
+ - Perez et al. (1993) - Anisotropic sky model
+ - Jonsson et al. (2006) - Longwave radiation formulation
+ """
+ # Import here to avoid circular dependency
+ from ..rustalgos import sky, vegetation
+
+ # Sky emissivity (Jonsson et al. 2006)
+ ta_k = weather.ta + KELVIN_OFFSET
+ ea = 6.107 * 10 ** ((7.5 * weather.ta) / (237.3 + weather.ta)) * (weather.rh / 100.0)
+ msteg = 46.5 * (ea / ta_k)
+ esky = 1 - (1 + msteg) * np.exp(-np.sqrt(1.2 + 3.0 * msteg))
+
+ # View factors (from SOLWEIG parameters - depends on posture)
+ cyl = human.posture == "standing"
+ if cyl:
+ _f_up = F_UP_STANDING # Reserved for future cylindric body model
+ _f_side = F_SIDE_STANDING # Reserved for future cylindric body model
+ # f_cyl = F_CYL_STANDING # Cylindrical projection factor for direct beam (not used here)
+ else:
+ _f_up = F_UP_SITTING # Reserved for future cylindric body model # noqa: F841
+ _f_side = F_SIDE_SITTING # Reserved for future cylindric body model # noqa: F841
+ # f_cyl = 0.2
+
+ # Shortwave radiation components
+ sin_alt = np.sin(np.radians(weather.sun_altitude))
+ rad_i = weather.direct_rad
+ rad_d = weather.diffuse_rad
+ rad_g = weather.global_rad
+
+ # Extract SVF components
+ svf = svf_bundle.svf
+ svf_directional = svf_bundle.svf_directional
+ svf_veg = svf_bundle.svf_veg
+ svf_veg_directional = svf_bundle.svf_veg_directional
+ svf_aveg = svf_bundle.svf_aveg
+ svf_aveg_directional = svf_bundle.svf_aveg_directional
+ svfbuveg = svf_bundle.svfbuveg
+ svfalfa = svf_bundle.svfalfa
+
+ # Extract shadow components
+ shadow = shadow_bundle.shadow
+ psi = shadow_bundle.psi
+
+ # Check if anisotropic sky model should be used
+ has_shadow_matrices = precomputed is not None and precomputed.shadow_matrices is not None
+ use_aniso = use_anisotropic_sky and has_shadow_matrices
+
+ # Compute F_sh (fraction shadow on building walls based on sun altitude and SVF)
+ zen = weather.sun_zenith * (np.pi / 180.0) # Convert to radians for cylindric_wedge
+ f_sh = _sky.cylindric_wedge(float(zen), as_float32(svfalfa))
+ f_sh = np.nan_to_num(f_sh, nan=0.5)
+
+ # Compute Kup (ground-reflected shortwave) using full directional model
+ kup, kup_e, kup_s, kup_w, kup_n = Kup_veg_2015a(
+ rad_i,
+ rad_d,
+ rad_g,
+ weather.sun_altitude,
+ svfbuveg,
+ albedo_wall,
+ f_sh,
+ gvf_bundle.gvfalb,
+ gvf_bundle.gvfalb_e,
+ gvf_bundle.gvfalb_s,
+ gvf_bundle.gvfalb_w,
+ gvf_bundle.gvfalb_n,
+ gvf_bundle.gvfalbnosh,
+ gvf_bundle.gvfalbnosh_e,
+ gvf_bundle.gvfalbnosh_s,
+ gvf_bundle.gvfalbnosh_w,
+ gvf_bundle.gvfalbnosh_n,
+ )
+
+ # Compute diffuse radiation and directional shortwave
+ if use_aniso:
+ # Type narrowing - precomputed and shadow_matrices are not None when use_aniso is True
+ assert precomputed is not None
+ assert precomputed.shadow_matrices is not None
+ # Anisotropic Diffuse Radiation after Perez et al. 1993
+ shadow_mats = precomputed.shadow_matrices
+ patch_option = shadow_mats.patch_option
+ jday = weather.datetime.timetuple().tm_yday
+
+ # Get Perez luminance distribution
+ lv, _, _ = Perez_v3(
+ weather.sun_zenith,
+ weather.sun_azimuth,
+ rad_d,
+ rad_i,
+ jday,
+ patchchoice=1,
+ patch_option=patch_option,
+ )
+
+ # Get diffuse shadow matrix (accounts for vegetation transmissivity)
+ diffsh = shadow_mats.diffsh(psi, use_vegetation=psi < 0.5)
+ shadow_mats.release_float32_cache() # Free unpacked float32; bitpacked still available
+
+ # Total relative luminance from sky patches into each cell
+ ani_lum = _sky.weighted_patch_sum(
+ as_float32(diffsh),
+ as_float32(lv[:, 2]),
+ )
+
+ drad = ani_lum * rad_d
+
+ # Compute asvf (angle from SVF) for anisotropic calculations
+ asvf = np.arccos(np.sqrt(np.clip(svf, 0.0, 1.0)))
+
+ # Pass bitpacked shadow matrices directly to Rust
+ shmat = np.ascontiguousarray(shadow_mats._shmat_u8)
+ vegshmat = np.ascontiguousarray(shadow_mats._vegshmat_u8)
+ vbshmat = np.ascontiguousarray(shadow_mats._vbshmat_u8)
+
+ # Compute base Ldown first (needed for lside_veg)
+ ldown_base = (
+ (svf + svf_veg - 1) * esky * SBC * (ta_k**4)
+ + (2 - svf_veg - svf_aveg) * emis_wall * SBC * (ta_k**4)
+ + (svf_aveg - svf) * emis_wall * SBC * ((weather.ta + tg_wall + KELVIN_OFFSET) ** 4)
+ + (2 - svf - svf_veg) * (1 - emis_wall) * esky * SBC * (ta_k**4)
+ )
+
+ # CI correction for non-clear conditions
+ ci = weather.clearness_index
+ if ci < 0.95:
+ c = 1.0 - ci
+ ldown_cloudy = (
+ (svf + svf_veg - 1) * SBC * (ta_k**4)
+ + (2 - svf_veg - svf_aveg) * emis_wall * SBC * (ta_k**4)
+ + (svf_aveg - svf) * emis_wall * SBC * ((weather.ta + tg_wall + KELVIN_OFFSET) ** 4)
+ + (2 - svf - svf_veg) * (1 - emis_wall) * SBC * (ta_k**4)
+ )
+ ldown_base = ldown_base * (1 - c) + ldown_cloudy * c
+
+ # Call lside_veg for base directional longwave (Least, Lsouth, Lwest, Lnorth)
+ lside_veg_result = vegetation.lside_veg(
+ as_float32(svf_directional.south),
+ as_float32(svf_directional.west),
+ as_float32(svf_directional.north),
+ as_float32(svf_directional.east),
+ as_float32(svf_veg_directional.east),
+ as_float32(svf_veg_directional.south),
+ as_float32(svf_veg_directional.west),
+ as_float32(svf_veg_directional.north),
+ as_float32(svf_aveg_directional.east),
+ as_float32(svf_aveg_directional.south),
+ as_float32(svf_aveg_directional.west),
+ as_float32(svf_aveg_directional.north),
+ weather.sun_azimuth,
+ weather.sun_altitude,
+ weather.ta,
+ tg_wall,
+ SBC,
+ emis_wall,
+ as_float32(ldown_base),
+ esky,
+ 0.0, # t (instrument offset, matching reference)
+ as_float32(f_sh),
+ weather.clearness_index,
+ as_float32(lup_bundle.lup_e), # TsWaveDelay-processed values
+ as_float32(lup_bundle.lup_s),
+ as_float32(lup_bundle.lup_w),
+ as_float32(lup_bundle.lup_n),
+ True, # anisotropic_sky flag
+ )
+ # Extract base directional longwave
+ lside_e_base = np.array(lside_veg_result.least)
+ lside_s_base = np.array(lside_veg_result.lsouth)
+ lside_w_base = np.array(lside_veg_result.lwest)
+ lside_n_base = np.array(lside_veg_result.lnorth)
+
+ # Compute steradians for patches
+ steradians, _, _ = patch_steradians(lv)
+
+ # Create L_patches array for anisotropic sky (altitude, azimuth, luminance)
+ l_patches = as_float32(lv)
+
+ # Adjust sky emissivity for cloudy conditions (CI < 0.95)
+ # This matches the reference implementation: esky = CI * esky + (1 - CI) * 1.0
+ esky_aniso = esky
+ ci = weather.clearness_index
+ if ci < 0.95:
+ esky_aniso = ci * esky + (1 - ci) * 1.0
+
+ # Create parameter structs for cleaner function signature
+ sun_params = sky.SunParams(
+ altitude=weather.sun_altitude,
+ azimuth=weather.sun_azimuth,
+ )
+ sky_params = sky.SkyParams(
+ esky=esky_aniso,
+ ta=weather.ta,
+ cyl=bool(cyl),
+ wall_scheme=False,
+ albedo=albedo_wall,
+ )
+ surface_params = sky.SurfaceParams(
+ tgwall=tg_wall,
+ ewall=emis_wall,
+ rad_i=rad_i,
+ rad_d=rad_d,
+ )
+
+ # Call full Rust anisotropic sky function with structs
+ ani_sky_result = sky.anisotropic_sky(
+ shmat,
+ vegshmat,
+ vbshmat,
+ sun_params,
+ as_float32(asvf),
+ sky_params,
+ l_patches,
+ None, # voxelTable
+ None, # voxelMaps
+ as_float32(steradians),
+ surface_params,
+ as_float32(lup_bundle.lup), # TsWaveDelay-processed value
+ as_float32(lv),
+ as_float32(shadow),
+ as_float32(kup_e),
+ as_float32(kup_s),
+ as_float32(kup_w),
+ as_float32(kup_n),
+ )
+
+ # Extract results from anisotropic sky
+ ldown = np.array(ani_sky_result.ldown)
+ # For directional longwave, use lside_veg_result (base) values
+ # ani_sky_result provides anisotropic additions, but for cyl=1, aniso=1
+ # the Sstr formula uses base directional longwave from lside_veg
+ lside_e = lside_e_base
+ lside_s = lside_s_base
+ lside_w = lside_w_base
+ lside_n = lside_n_base
+ # Shortwave from anisotropic sky result
+ kside_e = np.array(ani_sky_result.keast)
+ kside_s = np.array(ani_sky_result.ksouth)
+ kside_w = np.array(ani_sky_result.kwest)
+ kside_n = np.array(ani_sky_result.knorth)
+ kside_i = np.array(ani_sky_result.kside_i)
+ # Total radiation on vertical surfaces (for Tmrt f_cyl term)
+ kside_total = np.array(ani_sky_result.kside)
+ lside_total = np.array(ani_sky_result.lside)
+
+ else:
+ # Isotropic model - use Rust functions for kside and lside
+
+ # Isotropic diffuse radiation
+ drad = rad_d * svfbuveg # Diffuse weighted by combined SVF
+
+ # Compute asvf for Rust functions (needed even for isotropic)
+ asvf = np.arccos(np.sqrt(np.clip(svf, 0.0, 1.0)))
+
+ # Use Rust kside_veg for directional shortwave (isotropic mode: no lv, no shadow matrices)
+ kside_result = vegetation.kside_veg(
+ rad_i,
+ rad_d,
+ rad_g,
+ as_float32(shadow),
+ as_float32(svf_directional.south),
+ as_float32(svf_directional.west),
+ as_float32(svf_directional.north),
+ as_float32(svf_directional.east),
+ as_float32(svf_veg_directional.east),
+ as_float32(svf_veg_directional.south),
+ as_float32(svf_veg_directional.west),
+ as_float32(svf_veg_directional.north),
+ weather.sun_azimuth,
+ weather.sun_altitude,
+ psi,
+ 0.0, # t (instrument offset)
+ albedo_wall,
+ as_float32(f_sh),
+ as_float32(kup_e),
+ as_float32(kup_s),
+ as_float32(kup_w),
+ as_float32(kup_n),
+ bool(cyl),
+ None, # lv (None for isotropic)
+ False, # anisotropic_sky
+ None, # diffsh (None for isotropic)
+ as_float32(asvf),
+ None, # shmat (None for isotropic)
+ None, # vegshmat (None for isotropic)
+ None, # vbshvegshmat (None for isotropic)
+ )
+ kside_e = np.array(kside_result.keast)
+ kside_s = np.array(kside_result.ksouth)
+ kside_w = np.array(kside_result.kwest)
+ kside_n = np.array(kside_result.knorth)
+ kside_i = np.array(kside_result.kside_i)
+ # Total radiation on vertical surfaces (for Tmrt f_cyl term)
+ kside_total = kside_i # Isotropic uses direct beam only
+ lside_total = np.zeros_like(kside_i) # Not used in isotropic Tmrt formula
+
+ # Longwave: Ldown (from Jonsson et al. 2006)
+ ldown = (
+ (svf + svf_veg - 1) * esky * SBC * (ta_k**4)
+ + (2 - svf_veg - svf_aveg) * emis_wall * SBC * (ta_k**4)
+ + (svf_aveg - svf) * emis_wall * SBC * ((weather.ta + tg_wall + KELVIN_OFFSET) ** 4)
+ + (2 - svf - svf_veg) * (1 - emis_wall) * esky * SBC * (ta_k**4)
+ )
+
+ # CI correction for non-clear conditions (reference: if CI < 0.95)
+ # Under cloudy skies, effective sky emissivity approaches 1.0
+ ci = weather.clearness_index
+ if ci < 0.95:
+ c = 1.0 - ci
+ ldown_cloudy = (
+ (svf + svf_veg - 1) * SBC * (ta_k**4) # No esky for cloudy
+ + (2 - svf_veg - svf_aveg) * emis_wall * SBC * (ta_k**4)
+ + (svf_aveg - svf) * emis_wall * SBC * ((weather.ta + tg_wall + KELVIN_OFFSET) ** 4)
+ + (2 - svf - svf_veg) * (1 - emis_wall) * SBC * (ta_k**4) # No esky
+ )
+ ldown = ldown * (1 - c) + ldown_cloudy * c
+
+ # Use Rust lside_veg for directional longwave
+ lside_veg_result = vegetation.lside_veg(
+ as_float32(svf_directional.south),
+ as_float32(svf_directional.west),
+ as_float32(svf_directional.north),
+ as_float32(svf_directional.east),
+ as_float32(svf_veg_directional.east),
+ as_float32(svf_veg_directional.south),
+ as_float32(svf_veg_directional.west),
+ as_float32(svf_veg_directional.north),
+ as_float32(svf_aveg_directional.east),
+ as_float32(svf_aveg_directional.south),
+ as_float32(svf_aveg_directional.west),
+ as_float32(svf_aveg_directional.north),
+ weather.sun_azimuth,
+ weather.sun_altitude,
+ weather.ta,
+ tg_wall,
+ SBC,
+ emis_wall,
+ as_float32(ldown),
+ esky,
+ 0.0, # t (instrument offset, matching reference)
+ as_float32(f_sh),
+ weather.clearness_index,
+ as_float32(lup_bundle.lup_e), # TsWaveDelay-processed values
+ as_float32(lup_bundle.lup_s),
+ as_float32(lup_bundle.lup_w),
+ as_float32(lup_bundle.lup_n),
+ False, # anisotropic_sky
+ )
+ lside_e = np.array(lside_veg_result.least)
+ lside_s = np.array(lside_veg_result.lsouth)
+ lside_w = np.array(lside_veg_result.lwest)
+ lside_n = np.array(lside_veg_result.lnorth)
+
+ # Kdown (downwelling shortwave = direct on horizontal + diffuse sky + wall reflected)
+ kdown = rad_i * shadow * sin_alt + drad + albedo_wall * (1 - svfbuveg) * (rad_g * (1 - f_sh) + rad_d * f_sh)
+
+ return RadiationBundle(
+ kdown=as_float32(kdown),
+ kup=as_float32(kup),
+ ldown=as_float32(ldown),
+ lup=lup_bundle.lup, # Already float32 from LupBundle
+ kside=DirectionalArrays(
+ north=as_float32(kside_n),
+ east=as_float32(kside_e),
+ south=as_float32(kside_s),
+ west=as_float32(kside_w),
+ ),
+ lside=DirectionalArrays(
+ north=as_float32(lside_n),
+ east=as_float32(lside_e),
+ south=as_float32(lside_s),
+ west=as_float32(lside_w),
+ ),
+ kside_total=as_float32(kside_total),
+ lside_total=as_float32(lside_total),
+ drad=as_float32(drad),
+ )
diff --git a/pysrc/solweig/components/shadows.py b/pysrc/solweig/components/shadows.py
new file mode 100644
index 0000000..f532a21
--- /dev/null
+++ b/pysrc/solweig/components/shadows.py
@@ -0,0 +1,180 @@
+"""
+Shadow computation component.
+
+Handles:
+- Ray tracing for building and vegetation shadows
+- Vegetation transmissivity (seasonal leaf on/off)
+- Combined shadow accounting for light penetration through vegetation
+- Wall sun exposure for thermal calculations
+
+Returns a ShadowBundle with all shadow components.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..bundles import ShadowBundle
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..api import Weather
+
+
+def compute_transmissivity(
+ doy: int,
+ physics: SimpleNamespace | None = None,
+ conifer: bool = False,
+) -> float:
+ """
+ Compute vegetation transmissivity based on day of year and leaf status.
+
+ This implements seasonal leaf on/off logic from configs.py EnvironData.
+ During leaf-on season, vegetation transmits less light (low psi ~0.03).
+ During leaf-off season (winter), bare branches transmit more light (psi ~0.5).
+
+ Args:
+ doy: Day of year (1-366)
+ physics: Physics params from load_physics() containing Tree_settings.
+ If provided, reads Transmissivity, First_day_leaf, Last_day_leaf.
+ conifer: Override to treat vegetation as conifer (always leaf-on).
+
+ Returns:
+ Transmissivity value:
+ - 0.03 (default) during leaf-on period
+ - 0.5 during leaf-off period (deciduous trees in winter)
+
+ Reference:
+ configs.py EnvironData.leafon computation and psi assignment
+ """
+ # Default values matching configs.py
+ transmissivity = 0.03
+ first_day = 100 # ~April 10
+ last_day = 300 # ~October 27
+ is_conifer = conifer
+
+ # Override from physics params if provided
+ if physics is not None and hasattr(physics, "Tree_settings"):
+ ts = physics.Tree_settings.Value
+ transmissivity = getattr(ts, "Transmissivity", 0.03)
+ first_day = int(getattr(ts, "First_day_leaf", 100))
+ last_day = int(getattr(ts, "Last_day_leaf", 300))
+ # Note: Conifer flag may not be in all params files
+ is_conifer = conifer or getattr(ts, "Conifer", False)
+
+ # Determine leaf on/off
+ if is_conifer:
+ leaf_on = True
+ elif first_day > last_day:
+ # Wraps around year end (southern hemisphere or unusual dates)
+ leaf_on = doy > first_day or doy < last_day
+ else:
+ # Normal case: leaves on between first_day and last_day
+ leaf_on = first_day < doy < last_day
+
+ # Return appropriate transmissivity
+ # Leaf-off uses 0.5 to match configs.py: self.psi[self.leafon == 0] = 0.5
+ return transmissivity if leaf_on else 0.5
+
+
+def compute_shadows(
+ weather: Weather,
+ dsm: NDArray[np.floating],
+ pixel_size: float,
+ max_height: float,
+ use_veg: bool,
+ physics: SimpleNamespace | None,
+ conifer: bool,
+ cdsm: NDArray[np.floating] | None = None,
+ tdsm: NDArray[np.floating] | None = None,
+ bush: NDArray[np.floating] | None = None,
+ wall_ht: NDArray[np.floating] | None = None,
+ wall_asp_rad: NDArray[np.floating] | None = None,
+) -> ShadowBundle:
+ """
+ Compute shadows from buildings and vegetation.
+
+ Uses ray tracing to determine shadowed areas based on sun position.
+ Accounts for vegetation transmissivity (light passing through canopy).
+
+ Args:
+ weather: Weather data including sun position (azimuth, altitude)
+ dsm: Digital Surface Model (building heights)
+ pixel_size: Grid resolution in meters
+ max_height: Maximum building height for shadow computation
+ use_veg: Whether to include vegetation shadows
+ physics: Physics parameters (for transmissivity calculation)
+ conifer: Whether vegetation is coniferous (always leaf-on)
+ cdsm: Canopy Digital Surface Model (optional, for vegetation)
+ tdsm: Trunk Digital Surface Model (optional, for vegetation)
+ bush: Bush/shrub layer (optional, for vegetation)
+ wall_ht: Wall heights (optional, for wall sun exposure)
+ wall_asp_rad: Wall aspects in radians (optional, for wall sun exposure)
+
+ Returns:
+ ShadowBundle containing:
+ - shadow: Combined shadow fraction (0=sun, 1=shadow)
+ - bldg_sh: Building shadow only
+ - veg_sh: Vegetation shadow only
+ - wallsun: Wall sun exposure (for wall temperature)
+ - psi: Vegetation transmissivity used
+
+ Reference:
+ Lindberg et al. (2008) - SOLWEIG shadow model
+ Formula: shadow = bldg_sh - (1 - veg_sh) * (1 - psi)
+ """
+ # Import here to avoid circular dependency
+ from ..rustalgos import shadowing
+
+ has_walls = wall_ht is not None and wall_asp_rad is not None
+
+ # Call Rust shadow calculation
+ shadow_result = shadowing.calculate_shadows_wall_ht_25(
+ weather.sun_azimuth,
+ weather.sun_altitude,
+ pixel_size,
+ max_height,
+ dsm,
+ cdsm if use_veg else None,
+ tdsm if use_veg else None,
+ bush if use_veg else None,
+ wall_ht if has_walls else None,
+ wall_asp_rad if has_walls else None,
+ None, # walls_scheme
+ None, # aspect_scheme
+ 3.0, # min_sun_altitude
+ )
+
+ # Vegetation transmissivity - compute dynamically based on season
+ doy = weather.datetime.timetuple().tm_yday
+ psi = compute_transmissivity(doy, physics, conifer)
+
+ # Extract shadow arrays
+ bldg_sh = np.array(shadow_result.bldg_sh)
+
+ # Compute combined shadow accounting for vegetation transmissivity
+ # This matches the reference: shadow = bldg_sh - (1 - veg_sh) * (1 - psi)
+ # where psi is vegetation transmissivity (fraction of light that passes through)
+ if use_veg:
+ veg_sh = np.array(shadow_result.veg_sh)
+ shadow = bldg_sh - (1 - veg_sh) * (1 - psi)
+ # Note: No clipping here to match reference exactly. In practice, shadow
+ # should stay in [0,1] because veg_sh is constrained by bldg_sh.
+ else:
+ veg_sh = np.zeros_like(bldg_sh)
+ shadow = bldg_sh
+
+ # Wall sun exposure (for wall temperature calculation)
+ wallsun = np.array(shadow_result.wall_sun) if has_walls else np.zeros_like(dsm)
+
+ return ShadowBundle(
+ shadow=shadow.astype(np.float32),
+ bldg_sh=bldg_sh.astype(np.float32),
+ veg_sh=veg_sh.astype(np.float32),
+ wallsun=wallsun.astype(np.float32),
+ psi=psi,
+ )
diff --git a/pysrc/solweig/components/svf_resolution.py b/pysrc/solweig/components/svf_resolution.py
new file mode 100644
index 0000000..d6b34a0
--- /dev/null
+++ b/pysrc/solweig/components/svf_resolution.py
@@ -0,0 +1,188 @@
+"""
+SVF (Sky View Factor) resolution component.
+
+Resolves SVF data from two sources:
+1. Cached SVF from surface preparation (surface.svf)
+2. Pre-computed SVF (precomputed.svf)
+
+Raises MissingPrecomputedData if no SVF is available.
+SVF must be computed explicitly via surface.compute_svf() or
+SurfaceData.prepare() before calling calculate().
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..bundles import DirectionalArrays, SvfBundle
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..api import PrecomputedData, SurfaceData
+
+
+def resolve_svf(
+ surface: SurfaceData,
+ precomputed: PrecomputedData | None,
+ dsm: NDArray[np.floating],
+ cdsm: NDArray[np.floating] | None,
+ tdsm: NDArray[np.floating] | None,
+ pixel_size: float,
+ use_veg: bool,
+ max_height: float,
+ psi: float | None = None,
+) -> tuple[SvfBundle, bool]:
+ """
+ Resolve SVF data from available sources or compute on-the-fly.
+
+ Checks three sources in priority order:
+ 1. surface.svf (cached/prepared) - fastest
+ 2. precomputed.svf (legacy) - fast
+ 3. Compute fresh using skyview.calculate_svf - slower
+
+ Args:
+ surface: Surface data (may contain cached SVF)
+ precomputed: Pre-computed data (may contain SVF)
+ dsm: Digital Surface Model (for fresh computation)
+ cdsm: Canopy DSM (for fresh computation if use_veg=True)
+ tdsm: Trunk DSM (for fresh computation if use_veg=True)
+ pixel_size: Grid resolution in meters
+ use_veg: Whether to include vegetation in SVF calculation
+ max_height: Maximum building height for SVF computation
+ psi: Vegetation transmissivity (optional, for svfbuveg calculation)
+ If None, uses preliminary calculation that needs later adjustment
+
+ Returns:
+ Tuple of (SvfBundle, needs_psi_adjustment):
+ - SvfBundle: Complete SVF data with all directional components
+ - needs_psi_adjustment: True if svfbuveg needs recalculation with psi
+
+ Note:
+ When loading from cached/precomputed sources, svfbuveg already includes
+ transmissivity adjustment, so needs_psi_adjustment=False.
+ When computing fresh, svfbuveg is preliminary and needs_psi_adjustment=True.
+ """
+ # Import here to avoid circular dependency
+
+ needs_psi_adjustment = False
+
+ # Priority 1: Check surface.svf (from prepare/cache)
+ if surface.svf is not None:
+ svf_data = surface.svf
+ svf = svf_data.svf
+ svf_directional = DirectionalArrays(
+ north=svf_data.svf_north,
+ east=svf_data.svf_east,
+ south=svf_data.svf_south,
+ west=svf_data.svf_west,
+ )
+ svf_veg = svf_data.svf_veg
+ svf_veg_directional = DirectionalArrays(
+ north=svf_data.svf_veg_north,
+ east=svf_data.svf_veg_east,
+ south=svf_data.svf_veg_south,
+ west=svf_data.svf_veg_west,
+ )
+ svf_aveg = svf_data.svf_aveg
+ svf_aveg_directional = DirectionalArrays(
+ north=svf_data.svf_aveg_north,
+ east=svf_data.svf_aveg_east,
+ south=svf_data.svf_aveg_south,
+ west=svf_data.svf_aveg_west,
+ )
+ svfbuveg = svf_data.svfbuveg
+ # Cached svfbuveg already includes transmissivity adjustment
+ needs_psi_adjustment = False
+
+ # Priority 2: Check precomputed.svf (legacy)
+ elif precomputed is not None and precomputed.svf is not None:
+ svf_data = precomputed.svf
+ svf = svf_data.svf
+ svf_directional = DirectionalArrays(
+ north=svf_data.svf_north,
+ east=svf_data.svf_east,
+ south=svf_data.svf_south,
+ west=svf_data.svf_west,
+ )
+ svf_veg = svf_data.svf_veg
+ svf_veg_directional = DirectionalArrays(
+ north=svf_data.svf_veg_north,
+ east=svf_data.svf_veg_east,
+ south=svf_data.svf_veg_south,
+ west=svf_data.svf_veg_west,
+ )
+ svf_aveg = svf_data.svf_aveg
+ svf_aveg_directional = DirectionalArrays(
+ north=svf_data.svf_aveg_north,
+ east=svf_data.svf_aveg_east,
+ south=svf_data.svf_aveg_south,
+ west=svf_data.svf_aveg_west,
+ )
+ svfbuveg = svf_data.svfbuveg
+ # Precomputed svfbuveg already includes transmissivity adjustment
+ needs_psi_adjustment = False
+
+ # No SVF available — require explicit computation
+ else:
+ from ..errors import MissingPrecomputedData
+
+ raise MissingPrecomputedData(
+ "Sky View Factor (SVF) data is required but not available.",
+ "Call surface.compute_svf() before calculate(), or use SurfaceData.prepare() "
+ "which computes SVF automatically.",
+ )
+
+ # Compute svfalfa (SVF angle) from SVF values
+ # Formula: svfalfa = arcsin(exp(log(1 - (svf + svf_veg - 1)) / 2))
+ # Used in anisotropic sky calculations
+ tmp = np.clip(svf + svf_veg - 1.0, 0.0, 1.0)
+ eps = np.finfo(np.float32).tiny
+ safe_term = np.clip(1.0 - tmp, eps, 1.0)
+ svfalfa = np.arcsin(np.exp(np.log(safe_term) / 2.0))
+
+ # Construct bundle
+ bundle = SvfBundle(
+ svf=svf,
+ svf_directional=svf_directional,
+ svf_veg=svf_veg,
+ svf_veg_directional=svf_veg_directional,
+ svf_aveg=svf_aveg,
+ svf_aveg_directional=svf_aveg_directional,
+ svfbuveg=svfbuveg,
+ svfalfa=svfalfa,
+ )
+
+ return bundle, needs_psi_adjustment
+
+
+def adjust_svfbuveg_with_psi(
+ svf: NDArray[np.floating],
+ svf_veg: NDArray[np.floating],
+ psi: float,
+ use_veg: bool,
+) -> NDArray[np.floating]:
+ """
+ Adjust svfbuveg with vegetation transmissivity.
+
+ This is needed when SVF was computed fresh without knowledge of psi.
+
+ Args:
+ svf: Total sky view factor
+ svf_veg: Vegetation-only SVF
+ psi: Vegetation transmissivity (0.03 typical for deciduous trees)
+ use_veg: Whether vegetation is active
+
+ Returns:
+ Adjusted svfbuveg array
+
+ Formula:
+ svfbuveg = svf - (1 - svf_veg) * (1 - psi)
+ """
+ if use_veg:
+ svfbuveg = svf - (1.0 - svf_veg) * (1.0 - psi)
+ return np.clip(svfbuveg, 0.0, 1.0).astype(np.float32)
+ else:
+ return svf.astype(np.float32)
diff --git a/pysrc/solweig/components/tmrt.py b/pysrc/solweig/components/tmrt.py
new file mode 100644
index 0000000..f138eda
--- /dev/null
+++ b/pysrc/solweig/components/tmrt.py
@@ -0,0 +1,102 @@
+"""
+Mean Radiant Temperature (Tmrt) computation component.
+
+Computes Tmrt from radiation budget using human body geometry and absorptivities.
+The human body is modeled as a standing or sitting cylinder with specific view factors.
+
+Reference:
+- Lindberg et al. (2008, 2016) - SOLWEIG Tmrt calculation
+- Höppe (1992) - Human body radiation model
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .. import rustalgos
+from ..buffers import as_float32
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..api import HumanParams
+ from ..bundles import RadiationBundle
+
+
+def compute_tmrt(
+ radiation: RadiationBundle,
+ human: HumanParams,
+ use_anisotropic_sky: bool,
+) -> NDArray[np.floating]:
+ """
+ Compute Mean Radiant Temperature from radiation budget.
+
+ Tmrt represents the uniform temperature of an imaginary enclosure where
+ the radiant heat exchange with the human body equals that in the actual
+ non-uniform radiant environment.
+
+ Args:
+ radiation: Complete radiation budget from all directions
+ human: Human parameters (height, posture, absorptivities)
+ use_anisotropic_sky: Whether anisotropic sky model was used
+
+ Returns:
+ Tmrt array in degrees Celsius, clipped to [-50, 80]
+
+ Formula:
+ Tmrt = (Sstr / (abs_l × SBC))^0.25 - 273.15
+ where Sstr = absorbed shortwave + absorbed longwave
+
+ Reference:
+ Lindberg et al. (2008): "SOLWEIG 1.0 - modelling spatial variations
+ of 3D radiant fluxes and mean radiant temperature in complex urban settings"
+ """
+ # Extract radiation components (use as_float32 to avoid unnecessary copies)
+ kdown = as_float32(radiation.kdown)
+ kup = as_float32(radiation.kup)
+ ldown = as_float32(radiation.ldown)
+ lup = as_float32(radiation.lup)
+ kside_n = as_float32(radiation.kside.north)
+ kside_e = as_float32(radiation.kside.east)
+ kside_s = as_float32(radiation.kside.south)
+ kside_w = as_float32(radiation.kside.west)
+ lside_n = as_float32(radiation.lside.north)
+ lside_e = as_float32(radiation.lside.east)
+ lside_s = as_float32(radiation.lside.south)
+ lside_w = as_float32(radiation.lside.west)
+ kside_total = as_float32(radiation.kside_total)
+ lside_total = as_float32(radiation.lside_total)
+
+ # Posture flag (True for standing, False for sitting)
+ is_standing = human.posture == "standing"
+
+ # Create parameter struct (reduces 18 params to 15)
+ tmrt_params = rustalgos.tmrt.TmrtParams(
+ abs_k=human.abs_k,
+ abs_l=human.abs_l,
+ is_standing=is_standing,
+ use_anisotropic_sky=use_anisotropic_sky,
+ )
+
+ # Call Rust implementation with parameter struct
+ tmrt = rustalgos.tmrt.compute_tmrt(
+ kdown,
+ kup,
+ ldown,
+ lup,
+ kside_n,
+ kside_e,
+ kside_s,
+ kside_w,
+ lside_n,
+ lside_e,
+ lside_s,
+ lside_w,
+ kside_total,
+ lside_total,
+ tmrt_params,
+ )
+
+ return tmrt
diff --git a/pysrc/solweig/computation.py b/pysrc/solweig/computation.py
new file mode 100644
index 0000000..495aaf7
--- /dev/null
+++ b/pysrc/solweig/computation.py
@@ -0,0 +1,775 @@
+"""
+Orchestration layer for SOLWEIG core calculation.
+
+This module coordinates all computation components in a clean, linear flow:
+SVF resolution → Shadows → Ground temp → GVF → Thermal delay → Radiation → Tmrt
+
+Replaces the monolithic 841-line `_calculate_core()` with focused orchestration.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .bundles import LupBundle
+from .components.ground import compute_ground_temperature
+from .components.gvf import compute_gvf
+from .components.radiation import compute_radiation
+from .components.shadows import compute_shadows
+from .components.svf_resolution import resolve_svf
+from .components.tmrt import compute_tmrt
+from .constants import KELVIN_OFFSET, SBC
+from .rustalgos import ground as ground_rust
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from .api import HumanParams, Location, PrecomputedData, SolweigResult, SurfaceData, ThermalState, Weather
+ from .bundles import GvfBundle
+
+
+def _nighttime_result(
+ surface: SurfaceData,
+ weather: Weather,
+ state: ThermalState | None,
+ materials: SimpleNamespace | None,
+) -> SolweigResult:
+ """
+ Compute simplified nighttime result when sun is below horizon.
+
+ At night:
+ - Tmrt ≈ Ta (no solar radiation)
+ - Shadow = 0 (everything shaded)
+ - Kdown = Kup = 0 (no shortwave)
+ - Ldown/Lup from atmospheric and surface emission only
+
+ Args:
+ surface: Surface data (for emissivity grid)
+ weather: Weather data (for air temperature)
+ state: Optional thermal state (resets for morning)
+ materials: Material properties (for emissivity)
+
+ Returns:
+ SolweigResult with nighttime values
+ """
+ # Import here to avoid circular dependency
+ from .api import SolweigResult
+
+ rows, cols = surface.dsm.shape
+
+ # Get emissivity grid for nighttime longwave
+ _, emis_grid, _, _, _ = surface.get_land_cover_properties(materials)
+
+ # Nighttime: Tmrt ≈ Ta (simplified, no solar heating)
+ tmrt = np.full((rows, cols), weather.ta, dtype=np.float32)
+ shadow = np.zeros((rows, cols), dtype=np.float32) # 0 = shaded (night)
+
+ # Nighttime longwave: Lup = SBC × emis × Ta⁴
+ ta_k = weather.ta + KELVIN_OFFSET
+ lup_night = SBC * emis_grid * np.power(ta_k, 4)
+ # Ldown from sky with typical nighttime emissivity ~0.95
+ ldown_night = np.full((rows, cols), SBC * 0.95 * np.power(ta_k, 4), dtype=np.float32)
+
+ # Update thermal state for nighttime (reset for next morning)
+ output_state = None
+ if state is not None:
+ state.firstdaytime = 1.0 # Reset for morning
+ state.timeadd = 0.0 # Reset time accumulator
+ output_state = state.copy()
+
+ return SolweigResult(
+ tmrt=tmrt,
+ shadow=shadow,
+ kdown=np.zeros((rows, cols), dtype=np.float32),
+ kup=np.zeros((rows, cols), dtype=np.float32),
+ ldown=ldown_night.astype(np.float32),
+ lup=lup_night.astype(np.float32),
+ utci=None,
+ pet=None,
+ state=output_state,
+ )
+
+
+def _apply_thermal_delay(
+ gvf_bundle: GvfBundle,
+ ground_tg: NDArray[np.floating],
+ shadow: NDArray[np.floating],
+ weather: Weather,
+ state: ThermalState | None,
+) -> LupBundle:
+ """
+ Apply thermal inertia (TsWaveDelay) to upwelling longwave radiation.
+
+ This models the thermal mass of ground and walls, smoothing rapid temperature
+ changes throughout the day. Essential for accurate time-series simulations.
+
+ Uses batched Rust function to reduce FFI overhead from 6 calls to 1.
+
+ Args:
+ gvf_bundle: Ground view factor results (raw Lup before delay)
+ ground_tg: Ground temperature deviation from air temperature (K)
+ shadow: Shadow fraction (for ground temperature with shadow effect)
+ weather: Weather data (for air temperature and daytime flag)
+ state: Thermal state carrying forward surface temperature history
+
+ Returns:
+ LupBundle with thermally-delayed upwelling longwave and updated state
+ """
+ from .buffers import as_float32
+
+ output_state = None
+
+ if state is not None:
+ # Compute ground temperature with shadow effect
+ tg_temp = (ground_tg * shadow + weather.ta).astype(np.float32)
+
+ # Apply TsWaveDelay for thermal mass effect (batched - 6 calls → 1)
+ firstdaytime_int = int(state.firstdaytime)
+ result = ground_rust.ts_wave_delay_batch(
+ as_float32(gvf_bundle.lup),
+ as_float32(gvf_bundle.lup_e),
+ as_float32(gvf_bundle.lup_s),
+ as_float32(gvf_bundle.lup_w),
+ as_float32(gvf_bundle.lup_n),
+ tg_temp,
+ firstdaytime_int,
+ state.timeadd,
+ state.timestep_dec,
+ as_float32(state.tgmap1),
+ as_float32(state.tgmap1_e),
+ as_float32(state.tgmap1_s),
+ as_float32(state.tgmap1_w),
+ as_float32(state.tgmap1_n),
+ as_float32(state.tgout1),
+ )
+
+ # Extract delayed outputs
+ lup = np.asarray(result.lup)
+ lup_e = np.asarray(result.lup_e)
+ lup_s = np.asarray(result.lup_s)
+ lup_w = np.asarray(result.lup_w)
+ lup_n = np.asarray(result.lup_n)
+
+ # Update state with new values
+ state.timeadd = result.timeadd
+ state.tgmap1 = np.asarray(result.tgmap1)
+ state.tgmap1_e = np.asarray(result.tgmap1_e)
+ state.tgmap1_s = np.asarray(result.tgmap1_s)
+ state.tgmap1_w = np.asarray(result.tgmap1_w)
+ state.tgmap1_n = np.asarray(result.tgmap1_n)
+ state.tgout1 = np.asarray(result.tgout1)
+
+ # Update firstdaytime flag for next timestep
+ if weather.is_daytime:
+ state.firstdaytime = 0.0
+ else:
+ state.firstdaytime = 1.0
+ state.timeadd = 0.0
+
+ # Return a copy of state to avoid mutation issues
+ output_state = state.copy()
+ else:
+ # Single timestep: use raw GVF values (no thermal delay)
+ lup = gvf_bundle.lup
+ lup_e = gvf_bundle.lup_e
+ lup_s = gvf_bundle.lup_s
+ lup_w = gvf_bundle.lup_w
+ lup_n = gvf_bundle.lup_n
+
+ return LupBundle(
+ lup=lup.astype(np.float32),
+ lup_e=lup_e.astype(np.float32),
+ lup_s=lup_s.astype(np.float32),
+ lup_w=lup_w.astype(np.float32),
+ lup_n=lup_n.astype(np.float32),
+ state=output_state,
+ )
+
+
+def calculate_core(
+ surface: SurfaceData,
+ location: Location,
+ weather: Weather,
+ human: HumanParams,
+ precomputed: PrecomputedData | None,
+ use_anisotropic_sky: bool,
+ state: ThermalState | None,
+ physics: SimpleNamespace | None,
+ materials: SimpleNamespace | None,
+ conifer: bool = False,
+ wall_material: str | None = None,
+ max_shadow_distance_m: float | None = None,
+) -> SolweigResult:
+ """
+ Core SOLWEIG calculation orchestrating all components.
+
+ This is the clean orchestration layer that wires together all extracted
+ components in a linear flow:
+
+ 1. Early exit for nighttime (sun below horizon)
+ 2. SVF resolution (from cache/precomputed or fresh computation)
+ 3. Shadow computation (buildings + vegetation with transmissivity)
+ 4. Ground temperature model (TgMaps with land cover parameterization)
+ 5. Ground View Factor (upwelling radiation from surfaces)
+ 6. Thermal delay (TsWaveDelay for thermal inertia)
+ 7. Radiation calculation (shortwave + longwave from all directions)
+ 8. Tmrt calculation (absorbed radiation → mean radiant temperature)
+
+ Args:
+ surface: Surface/terrain data (DSM, vegetation, walls, land cover)
+ location: Geographic location (latitude, longitude)
+ weather: Weather conditions (temperature, humidity, radiation, sun position)
+ human: Human parameters (height, posture, absorptivities)
+ precomputed: Optional pre-computed data (SVF, shadow matrices)
+ use_anisotropic_sky: Use anisotropic (Perez) diffuse sky model
+ state: Optional thermal state for time-series (carries forward temperatures)
+ physics: Optional physics parameters (vegetation transmissivity, etc.)
+ materials: Optional material properties (albedo, emissivity by land cover)
+ conifer: Treat vegetation as evergreen conifers (always leaf-on)
+
+ Returns:
+ SolweigResult with Tmrt, shadow, radiation components, and updated state
+
+ Reference:
+ Lindberg et al. (2008, 2016) - SOLWEIG model description
+ """
+ # Import here to avoid circular dependency
+ from .api import SolweigResult
+
+ # Early exit for nighttime
+ if weather.sun_altitude <= 0:
+ return _nighttime_result(surface, weather, state, materials)
+
+ # === Daytime calculation ===
+
+ # Extract grid dimensions
+ rows, cols = surface.dsm.shape
+ pixel_size = surface.pixel_size
+
+ # Get surface properties: albedo, emissivity, and ground temp parameters
+ alb_grid, emis_grid, tgk_grid, tstart_grid, tmaxlst_grid = surface.get_land_cover_properties(materials)
+
+ # Prepare vegetation inputs
+ use_veg = surface.cdsm is not None
+ cdsm = surface.cdsm if use_veg else None
+ tdsm = surface.tdsm if use_veg else None
+ # Bush layer: Create empty mask when vegetation present (no bushes assumed)
+ # Rust validation requires all three vegetation inputs (cdsm, tdsm, bush) or none
+ if use_veg:
+ pool = surface.get_buffer_pool()
+ bush = pool.get_zeros("bush")
+ else:
+ bush = None
+
+ # Prepare wall inputs
+ has_walls = surface.wall_height is not None and surface.wall_aspect is not None
+ wall_ht = surface.wall_height if has_walls else None
+ wall_asp = surface.wall_aspect if has_walls else None
+
+ # Maximum building height for shadow/SVF computation
+ max_height = float(np.nanmax(surface.dsm)) if surface.dsm.size > 0 else 50.0
+
+ # Cap shadow reach if max_shadow_distance_m is set
+ if max_shadow_distance_m is not None:
+ from .tiling import MIN_SUN_ELEVATION_DEG
+
+ height_cap = max_shadow_distance_m * np.tan(np.radians(MIN_SUN_ELEVATION_DEG))
+ max_height = min(max_height, height_cap)
+
+ # Step 1: SVF Resolution (sky view factors from cached/precomputed sources)
+ svf_bundle, _needs_psi_adjustment = resolve_svf(
+ surface=surface,
+ precomputed=precomputed,
+ dsm=surface.dsm,
+ cdsm=cdsm,
+ tdsm=tdsm,
+ pixel_size=pixel_size,
+ use_veg=use_veg,
+ max_height=max_height,
+ )
+
+ # Step 2: Shadow Computation (with vegetation transmissivity)
+ shadow_bundle = compute_shadows(
+ weather=weather,
+ dsm=surface.dsm,
+ pixel_size=pixel_size,
+ max_height=max_height,
+ use_veg=use_veg,
+ physics=physics,
+ conifer=conifer,
+ cdsm=cdsm,
+ tdsm=tdsm,
+ bush=bush,
+ wall_ht=wall_ht,
+ wall_asp_rad=wall_asp * (np.pi / 180.0) if wall_asp is not None else None,
+ )
+
+ # Step 3: Ground Temperature Model (TgMaps with land cover parameterization)
+ # Resolve wall params: explicit wall_material wins, then materials JSON, then Rust defaults
+ tgk_wall = None
+ tstart_wall = None
+ tmaxlst_wall = None
+ if wall_material is not None:
+ from .loaders import resolve_wall_params
+
+ tgk_wall, tstart_wall, tmaxlst_wall = resolve_wall_params(wall_material, materials)
+ elif materials is not None:
+ tgk_wall = getattr(getattr(getattr(materials, "Ts_deg", None), "Value", None), "Walls", None)
+ tstart_wall = getattr(getattr(getattr(materials, "Tstart", None), "Value", None), "Walls", None)
+ tmaxlst_wall = getattr(getattr(getattr(materials, "TmaxLST", None), "Value", None), "Walls", None)
+
+ ground_bundle = compute_ground_temperature(
+ weather=weather,
+ location=location,
+ alb_grid=alb_grid,
+ emis_grid=emis_grid,
+ tgk_grid=tgk_grid,
+ tstart_grid=tstart_grid,
+ tmaxlst_grid=tmaxlst_grid,
+ tgk_wall=tgk_wall,
+ tstart_wall=tstart_wall,
+ tmaxlst_wall=tmaxlst_wall,
+ )
+
+ # Step 4: Ground View Factor (upwelling radiation from ground + walls)
+ gvf_bundle = compute_gvf(
+ surface=surface,
+ weather=weather,
+ human=human,
+ tg=ground_bundle.tg,
+ tg_wall=ground_bundle.tg_wall,
+ shadow=shadow_bundle.shadow,
+ wallsun=shadow_bundle.wallsun,
+ alb_grid=ground_bundle.alb_grid,
+ emis_grid=ground_bundle.emis_grid,
+ svf=svf_bundle.svf,
+ pixel_size=pixel_size,
+ wall_ht=wall_ht,
+ wall_asp=wall_asp,
+ )
+
+ # Step 5: Apply Thermal Delay (TsWaveDelay for thermal inertia)
+ lup_bundle = _apply_thermal_delay(
+ gvf_bundle=gvf_bundle,
+ ground_tg=ground_bundle.tg,
+ shadow=shadow_bundle.shadow,
+ weather=weather,
+ state=state,
+ )
+
+ # Step 6: Radiation Calculation (complete shortwave + longwave budget)
+ radiation_bundle = compute_radiation(
+ weather=weather,
+ svf_bundle=svf_bundle,
+ shadow_bundle=shadow_bundle,
+ gvf_bundle=gvf_bundle,
+ lup_bundle=lup_bundle,
+ human=human,
+ use_anisotropic_sky=use_anisotropic_sky,
+ precomputed=precomputed,
+ albedo_wall=0.20, # Default cobblestone
+ emis_wall=0.90, # Default brick/concrete
+ tg_wall=ground_bundle.tg_wall,
+ )
+
+ # Step 7: Tmrt Calculation (absorbed radiation → mean radiant temperature)
+ tmrt = compute_tmrt(
+ radiation=radiation_bundle,
+ human=human,
+ use_anisotropic_sky=use_anisotropic_sky,
+ )
+
+ return SolweigResult(
+ tmrt=tmrt,
+ shadow=shadow_bundle.shadow,
+ kdown=radiation_bundle.kdown,
+ kup=radiation_bundle.kup,
+ ldown=radiation_bundle.ldown,
+ lup=lup_bundle.lup,
+ utci=None, # Computed separately via post-processing
+ pet=None, # Computed separately via post-processing
+ state=lup_bundle.state,
+ )
+
+
+def calculate_core_fused(
+ surface: SurfaceData,
+ location: Location,
+ weather: Weather,
+ human: HumanParams,
+ precomputed: PrecomputedData | None,
+ state: ThermalState | None,
+ physics: SimpleNamespace | None,
+ materials: SimpleNamespace | None,
+ conifer: bool = False,
+ wall_material: str | None = None,
+ use_anisotropic_sky: bool = False,
+ max_shadow_distance_m: float | None = None,
+) -> SolweigResult:
+ """
+ Fused SOLWEIG calculation — single Rust FFI call per daytime timestep.
+
+ Functionally identical to calculate_core() but orchestrates shadows → ground →
+ GVF → thermal delay → radiation → Tmrt entirely within Rust, eliminating
+ intermediate numpy allocations and FFI round-trips.
+
+ Supports both isotropic and anisotropic (Perez) sky models.
+
+ Args:
+ Same as calculate_core().
+ """
+ from .api import SolweigResult
+ from .buffers import as_float32
+ from .components.gvf import detect_building_mask
+ from .components.shadows import compute_transmissivity
+ from .components.svf_resolution import resolve_svf
+ from .models.state import ThermalState
+ from .physics.clearnessindex_2013b import clearnessindex_2013b
+ from .physics.daylen import daylen
+ from .physics.diffusefraction import diffusefraction
+ from .rustalgos import pipeline
+
+ # Ensure derived weather fields are computed (sun position, radiation split)
+ if not weather._derived_computed:
+ weather.compute_derived(location)
+
+ # Early exit for nighttime
+ if weather.sun_altitude <= 0:
+ return _nighttime_result(surface, weather, state, materials)
+
+ # === Precompute (stays in Python) ===
+
+ rows, cols = surface.dsm.shape
+ pixel_size = surface.pixel_size
+
+ # Valid pixel mask (True where all layers have finite data)
+ # Computed once by SurfaceData.prepare(), or derived from DSM on-the-fly
+ valid_mask = surface.valid_mask
+ if valid_mask is None:
+ valid_mask = np.isfinite(surface.dsm)
+ valid_mask_u8 = np.ascontiguousarray(valid_mask, dtype=np.uint8)
+
+ # Land cover properties
+ alb_grid, emis_grid, tgk_grid, tstart_grid, tmaxlst_grid = surface.get_land_cover_properties(materials)
+
+ # Vegetation inputs
+ use_veg = surface.cdsm is not None
+ cdsm = surface.cdsm if use_veg else None
+ tdsm = surface.tdsm if use_veg else None
+ if use_veg:
+ pool = surface.get_buffer_pool()
+ bush = pool.get_zeros("bush")
+ else:
+ bush = None
+
+ # Wall inputs
+ has_walls = surface.wall_height is not None and surface.wall_aspect is not None
+ wall_ht = surface.wall_height if has_walls else None
+ wall_asp = surface.wall_aspect if has_walls else None
+
+ max_height = float(np.nanmax(surface.dsm)) if surface.dsm.size > 0 else 50.0
+
+ # Cap shadow reach if max_shadow_distance_m is set
+ if max_shadow_distance_m is not None:
+ from .tiling import MIN_SUN_ELEVATION_DEG
+
+ height_cap = max_shadow_distance_m * np.tan(np.radians(MIN_SUN_ELEVATION_DEG))
+ max_height = min(max_height, height_cap)
+
+ # SVF resolution (cached between timesteps)
+ svf_bundle, _needs_psi_adjustment = resolve_svf(
+ surface=surface,
+ precomputed=precomputed,
+ dsm=surface.dsm,
+ cdsm=cdsm,
+ tdsm=tdsm,
+ pixel_size=pixel_size,
+ use_veg=use_veg,
+ max_height=max_height,
+ )
+
+ # Vegetation transmissivity
+ doy = weather.datetime.timetuple().tm_yday
+ psi = compute_transmissivity(doy, physics, conifer)
+
+ # Wall material resolution
+ tgk_wall = 0.37
+ tstart_wall = -3.41
+ tmaxlst_wall = 15.0
+ albedo_wall = 0.20
+ emis_wall = 0.90
+ if wall_material is not None:
+ from .loaders import resolve_wall_params
+
+ tgk_wall, tstart_wall, tmaxlst_wall = resolve_wall_params(wall_material, materials)
+ elif materials is not None:
+ tgk_w = getattr(getattr(getattr(materials, "Ts_deg", None), "Value", None), "Walls", None)
+ tstart_w = getattr(getattr(getattr(materials, "Tstart", None), "Value", None), "Walls", None)
+ tmaxlst_w = getattr(getattr(getattr(materials, "TmaxLST", None), "Value", None), "Walls", None)
+ if tgk_w is not None:
+ tgk_wall = tgk_w
+ if tstart_w is not None:
+ tstart_wall = tstart_w
+ if tmaxlst_w is not None:
+ tmaxlst_wall = tmaxlst_w
+
+ # Weather-derived scalars for ground temperature model
+ _, _, _, snup = daylen(doy, location.latitude)
+ dectime = (weather.datetime.hour + weather.datetime.minute / 60.0) / 24.0
+ zen_deg = 90.0 - weather.sun_altitude
+
+ # Clear-sky radiation for ground temperature CI correction
+ zen_rad = zen_deg * (np.pi / 180.0)
+ location_dict = {
+ "latitude": location.latitude,
+ "longitude": location.longitude,
+ "altitude": 0.0,
+ }
+ i0, _, _, _, _ = clearnessindex_2013b(
+ zen_rad,
+ doy,
+ weather.ta,
+ weather.rh / 100.0,
+ weather.global_rad,
+ location_dict,
+ -999.0,
+ )
+ if i0 > 0 and weather.sun_altitude > 0:
+ rad_i0, rad_d0 = diffusefraction(i0, weather.sun_altitude, 1.0, weather.ta, weather.rh)
+ rad_g0 = rad_i0 * np.sin(weather.sun_altitude * np.pi / 180.0) + rad_d0
+ else:
+ rad_g0 = 0.0
+
+ # === Build Rust input structs ===
+
+ ws = pipeline.WeatherScalars(
+ sun_azimuth=float(weather.sun_azimuth),
+ sun_altitude=float(weather.sun_altitude),
+ sun_zenith=float(weather.sun_zenith),
+ ta=float(weather.ta),
+ rh=float(weather.rh),
+ global_rad=float(weather.global_rad),
+ direct_rad=float(weather.direct_rad),
+ diffuse_rad=float(weather.diffuse_rad),
+ altmax=float(weather.altmax),
+ clearness_index=float(weather.clearness_index),
+ dectime=float(dectime),
+ snup=float(snup),
+ rad_g0=float(rad_g0),
+ zen_deg=float(zen_deg),
+ psi=float(psi),
+ is_daytime=weather.sun_altitude > 0,
+ )
+
+ hs = pipeline.HumanScalars(
+ height=float(human.height),
+ abs_k=float(human.abs_k),
+ abs_l=float(human.abs_l),
+ is_standing=human.posture == "standing",
+ )
+
+ cs = pipeline.ConfigScalars(
+ pixel_size=float(pixel_size),
+ max_height=float(max_height),
+ albedo_wall=float(albedo_wall),
+ emis_wall=float(emis_wall),
+ tgk_wall=float(tgk_wall),
+ tstart_wall=float(tstart_wall),
+ tmaxlst_wall=float(tmaxlst_wall),
+ use_veg=use_veg,
+ has_walls=has_walls,
+ conifer=conifer,
+ use_anisotropic=use_anisotropic_sky,
+ )
+
+ # Buildings mask for GVF (computed from DSM/land_cover/walls)
+ buildings = detect_building_mask(
+ surface.dsm,
+ surface.land_cover,
+ wall_ht,
+ pixel_size,
+ )
+ lc_grid = surface.land_cover.astype(np.float32) if surface.land_cover is not None else None
+
+ # GVF geometry cache: precompute on first daytime call, reuse on subsequent
+ gvf_cache = getattr(surface, "_gvf_geometry_cache", None)
+ if gvf_cache is None and has_walls:
+ assert wall_asp is not None # guaranteed by has_walls
+ assert wall_ht is not None
+ gvf_cache = pipeline.precompute_gvf_cache(
+ as_float32(buildings),
+ as_float32(wall_asp),
+ as_float32(wall_ht),
+ as_float32(alb_grid),
+ float(pixel_size),
+ float(human.height),
+ float(albedo_wall),
+ )
+ surface._gvf_geometry_cache = gvf_cache
+
+ # Anisotropic sky pre-computation (Perez stays in Python, <1ms)
+ aniso_shmat = None
+ aniso_vegshmat = None
+ aniso_vbshmat = None
+ aniso_l_patches = None
+ aniso_steradians = None
+ aniso_lv = None
+ aniso_asvf = None
+ aniso_esky = None
+
+ if use_anisotropic_sky:
+ from .physics.patch_radiation import patch_steradians
+ from .physics.Perez_v3 import Perez_v3
+
+ # Get shadow matrices
+ shadow_mats = None
+ if precomputed is not None and precomputed.shadow_matrices is not None:
+ shadow_mats = precomputed.shadow_matrices
+ elif surface.shadow_matrices is not None:
+ shadow_mats = surface.shadow_matrices
+
+ if shadow_mats is not None:
+ patch_option = shadow_mats.patch_option
+ jday = weather.datetime.timetuple().tm_yday
+ rad_d = float(weather.diffuse_rad)
+ rad_i = float(weather.direct_rad)
+
+ # Perez luminance distribution
+ lv_arr, _, _ = Perez_v3(
+ weather.sun_zenith,
+ weather.sun_azimuth,
+ rad_d,
+ rad_i,
+ jday,
+ patchchoice=1,
+ patch_option=patch_option,
+ )
+
+ # Steradians
+ ster, _, _ = patch_steradians(lv_arr)
+
+ # ASVF from SVF
+ asvf_arr = np.arccos(np.sqrt(np.clip(svf_bundle.svf, 0.0, 1.0)))
+
+ # Esky (Jonsson et al. 2006) with CI correction for anisotropic
+ ta_k = weather.ta + 273.15
+ ea = 6.107 * 10 ** ((7.5 * weather.ta) / (237.3 + weather.ta)) * (weather.rh / 100.0)
+ msteg = 46.5 * (ea / ta_k)
+ esky_val = 1 - (1 + msteg) * np.exp(-np.sqrt(1.2 + 3.0 * msteg))
+ ci = weather.clearness_index
+ if ci < 0.95:
+ esky_val = ci * esky_val + (1 - ci) * 1.0
+
+ aniso_shmat = np.ascontiguousarray(shadow_mats._shmat_u8)
+ aniso_vegshmat = np.ascontiguousarray(shadow_mats._vegshmat_u8)
+ aniso_vbshmat = np.ascontiguousarray(shadow_mats._vbshmat_u8)
+ aniso_l_patches = as_float32(lv_arr)
+ aniso_steradians = as_float32(ster)
+ aniso_lv = as_float32(lv_arr)
+ aniso_asvf = as_float32(asvf_arr)
+ aniso_esky = float(esky_val)
+
+ # Thermal state (create initial if None)
+ if state is None:
+ state = ThermalState.initial((rows, cols))
+
+ firstdaytime_int = int(state.firstdaytime)
+
+ # === Call fused Rust pipeline ===
+
+ result = pipeline.compute_timestep(
+ # Scalar structs
+ ws,
+ hs,
+ cs,
+ # GVF geometry cache (None on first call triggers full GVF, then cached)
+ gvf_cache,
+ # Surface arrays
+ as_float32(surface.dsm),
+ as_float32(cdsm) if cdsm is not None else None,
+ as_float32(tdsm) if tdsm is not None else None,
+ as_float32(bush) if bush is not None else None,
+ as_float32(wall_ht) if wall_ht is not None else None,
+ as_float32(wall_asp) if wall_asp is not None else None,
+ # SVF arrays
+ as_float32(svf_bundle.svf),
+ as_float32(svf_bundle.svf_directional.north),
+ as_float32(svf_bundle.svf_directional.east),
+ as_float32(svf_bundle.svf_directional.south),
+ as_float32(svf_bundle.svf_directional.west),
+ as_float32(svf_bundle.svf_veg),
+ as_float32(svf_bundle.svf_veg_directional.north),
+ as_float32(svf_bundle.svf_veg_directional.east),
+ as_float32(svf_bundle.svf_veg_directional.south),
+ as_float32(svf_bundle.svf_veg_directional.west),
+ as_float32(svf_bundle.svf_aveg),
+ as_float32(svf_bundle.svf_aveg_directional.north),
+ as_float32(svf_bundle.svf_aveg_directional.east),
+ as_float32(svf_bundle.svf_aveg_directional.south),
+ as_float32(svf_bundle.svf_aveg_directional.west),
+ as_float32(svf_bundle.svfbuveg),
+ as_float32(svf_bundle.svfalfa),
+ # Land cover property grids
+ as_float32(alb_grid),
+ as_float32(emis_grid),
+ as_float32(tgk_grid),
+ as_float32(tstart_grid),
+ as_float32(tmaxlst_grid),
+ # Buildings mask + land cover
+ as_float32(buildings),
+ as_float32(lc_grid) if lc_grid is not None else None,
+ # Anisotropic sky inputs (None for isotropic)
+ aniso_shmat,
+ aniso_vegshmat,
+ aniso_vbshmat,
+ aniso_l_patches,
+ aniso_steradians,
+ aniso_lv,
+ aniso_asvf,
+ aniso_esky,
+ # Thermal state
+ firstdaytime_int,
+ float(state.timeadd),
+ float(state.timestep_dec),
+ as_float32(state.tgmap1),
+ as_float32(state.tgmap1_e),
+ as_float32(state.tgmap1_s),
+ as_float32(state.tgmap1_w),
+ as_float32(state.tgmap1_n),
+ as_float32(state.tgout1),
+ # Valid pixel mask for early NaN exit
+ valid_mask_u8,
+ )
+
+ # === Unpack result and update thermal state ===
+
+ state.timeadd = result.timeadd
+ state.tgmap1 = np.asarray(result.tgmap1)
+ state.tgmap1_e = np.asarray(result.tgmap1_e)
+ state.tgmap1_s = np.asarray(result.tgmap1_s)
+ state.tgmap1_w = np.asarray(result.tgmap1_w)
+ state.tgmap1_n = np.asarray(result.tgmap1_n)
+ state.tgout1 = np.asarray(result.tgout1)
+
+ if weather.is_daytime:
+ state.firstdaytime = 0.0
+ else:
+ state.firstdaytime = 1.0
+ state.timeadd = 0.0
+
+ output_state = state.copy()
+
+ return SolweigResult(
+ tmrt=np.asarray(result.tmrt),
+ shadow=np.asarray(result.shadow),
+ kdown=np.asarray(result.kdown),
+ kup=np.asarray(result.kup),
+ ldown=np.asarray(result.ldown),
+ lup=np.asarray(result.lup),
+ utci=None,
+ pet=None,
+ state=output_state,
+ )
diff --git a/pysrc/solweig/constants.py b/pysrc/solweig/constants.py
new file mode 100644
index 0000000..dd3a893
--- /dev/null
+++ b/pysrc/solweig/constants.py
@@ -0,0 +1,82 @@
+"""
+Physical constants and default parameters for SOLWEIG.
+
+This module consolidates all physical constants and default parameter values
+to eliminate duplication across the codebase and provide clear documentation
+with proper references.
+"""
+
+# =============================================================================
+# Physical Constants
+# =============================================================================
+
+# Stefan-Boltzmann constant (W/m²/K⁴)
+# Used for blackbody radiation calculations: E = σ × T⁴
+# Reference: CODATA 2018 recommended value
+SBC = 5.67e-8
+
+# Kelvin to Celsius conversion offset
+# Used for temperature unit conversions
+KELVIN_OFFSET = 273.15
+
+# Minimum sun elevation for shadow calculations (degrees)
+# Below this threshold, shadows are not computed (negligible solar radiation)
+MIN_SUN_ELEVATION_DEG = 3.0
+
+
+# =============================================================================
+# View Factor Constants
+# =============================================================================
+# View factors represent the fraction of radiation leaving one surface
+# that is intercepted by another surface. For a human body modeled as
+# a cylinder or cube, these factors depend on posture.
+#
+# Reference: Höppe (1992) - "The physiological equivalent temperature"
+# =============================================================================
+
+# Standing posture view factors (cylindrical model)
+# Human body modeled as a standing cylinder
+F_UP_STANDING = 0.06 # View factor to sky/ground from top/bottom
+F_SIDE_STANDING = 0.22 # View factor from each of 4 cardinal directions (N, E, S, W)
+F_CYL_STANDING = 0.28 # Cylindrical projection factor for direct beam radiation
+
+# Sitting posture view factors (cubic model)
+# Human body modeled as a sitting cube with equal area on all 6 sides
+F_UP_SITTING = 0.166666 # View factor to sky/ground (1/6 per side)
+F_SIDE_SITTING = 0.166666 # View factor from each of 4 cardinal directions (1/6 per side)
+# Note: F_CYL is not used for sitting posture in current implementation
+
+
+# =============================================================================
+# Default Physical Parameters
+# =============================================================================
+# These are common default values used when not specified by the user
+# or when materials/physics config is not provided.
+# =============================================================================
+
+# Default wall properties
+DEFAULT_ALBEDO_WALL = 0.20 # Wall albedo (reflectance)
+DEFAULT_EMIS_WALL = 0.90 # Wall emissivity (longwave radiation)
+DEFAULT_TG_WALL = 0.0 # Wall temperature deviation from air temperature (K)
+
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+__all__ = [
+ # Physical constants
+ "SBC",
+ "KELVIN_OFFSET",
+ "MIN_SUN_ELEVATION_DEG",
+ # View factors
+ "F_UP_STANDING",
+ "F_SIDE_STANDING",
+ "F_CYL_STANDING",
+ "F_UP_SITTING",
+ "F_SIDE_SITTING",
+ # Defaults
+ "DEFAULT_ALBEDO_WALL",
+ "DEFAULT_EMIS_WALL",
+ "DEFAULT_TG_WALL",
+]
diff --git a/pysrc/solweig/data/default_materials.json b/pysrc/solweig/data/default_materials.json
new file mode 100644
index 0000000..263335b
--- /dev/null
+++ b/pysrc/solweig/data/default_materials.json
@@ -0,0 +1,221 @@
+{
+ "Names": {
+ "Value": {
+ "0": "Cobble_stone_2014a",
+ "1": "Dark_asphalt",
+ "2": "Roofs(buildings)",
+ "5": "Grass_unmanaged",
+ "6": "Bare_soil",
+ "7": "Water",
+ "99": "Walls",
+ "100": "Brick_wall",
+ "101": "Concrete_wall",
+ "102": "Wood_wall"
+ },
+ "Comment": "Name of each respective land cover class in land cover data."
+ },
+ "Code": {
+ "Value": {
+ "Cobble_stone_2014a": 0,
+ "Dark_asphalt": 1,
+ "Roofs(buildings)": 2,
+ "Grass_unmanaged": 5,
+ "Bare_soil": 6,
+ "Water": 7,
+ "Walls": 99,
+ "Brick_wall": 100,
+ "Concrete_wall": 101,
+ "Wood_wall": 102
+ },
+ "Comment": "Code for each land cover class name."
+ },
+ "Albedo": {
+ "Effective": {
+ "Value": {
+ "Cobble_stone_2014a": 0.2,
+ "Dark_asphalt": 0.18,
+ "Roofs(buildings)": 0.18,
+ "Grass_unmanaged": 0.16,
+ "Bare_soil": 0.25,
+ "Water": 0.05,
+ "Walls": 0.2
+ },
+ "Comment": "Effective albedos according to Lindberg et al., 2008; 2016."
+ },
+ "Material": {
+ "Value": {
+ "Brick_wall": 0.2,
+ "Concrete_wall": 0.2,
+ "Wood_wall": 0.2
+ },
+ "Comment": "Material albedos according to Wallenberg et al., 2025."
+ }
+ },
+ "Emissivity": {
+ "Value": {
+ "Cobble_stone_2014a": 0.95,
+ "Dark_asphalt": 0.95,
+ "Roofs(buildings)": 0.95,
+ "Grass_unmanaged": 0.94,
+ "Bare_soil": 0.94,
+ "Water": 0.98,
+ "Walls": 0.9,
+ "Brick_wall": 0.9,
+ "Concrete_wall": 0.9,
+ "Wood_wall": 0.9
+ },
+ "Comment": "Emissivity of each land cover class."
+ },
+ "Specific_heat": {
+ "Value": {
+ "Cobble_stone_2014a": -9999.0,
+ "Dark_asphalt": -9999.0,
+ "Roofs(buildings)": -9999.0,
+ "Grass_unmanaged": -9999.0,
+ "Bare_soil": -9999.0,
+ "Water": -9999.0,
+ "Walls": -9999.0,
+ "Brick_wall": 800,
+ "Concrete_wall": 840,
+ "Wood_wall": 1880
+ },
+ "Comment": "Specific heat capacity, in units J kg-1 K-1, used for wall surface temperatures according to Wallenberg et al. 2025."
+ },
+ "Thermal_conductivity": {
+ "Value": {
+ "Cobble_stone_2014a": -9999.0,
+ "Dark_asphalt": -9999.0,
+ "Roofs(buildings)": -9999.0,
+ "Grass_unmanaged": -9999.0,
+ "Bare_soil": -9999.0,
+ "Water": -9999.0,
+ "Walls": -9999.0,
+ "Brick_wall": 0.84,
+ "Concrete_wall": 1.7,
+ "Wood_wall": 0.17
+ },
+ "Comment": "Thermal conductivity of each land cover class, in units W m-1 K-1, used for wall surface temperatures according to Wallenberg et al. 2025."
+ },
+ "Density": {
+ "Value": {
+ "Cobble_stone_2014a": -9999.0,
+ "Dark_asphalt": -9999.0,
+ "Roofs(buildings)": -9999.0,
+ "Grass_unmanaged": -9999.0,
+ "Bare_soil": -9999.0,
+ "Water": -9999.0,
+ "Walls": -9999.0,
+ "Brick_wall": 1700,
+ "Concrete_wall": 2200,
+ "Wood_wall": 700
+ },
+ "Comment": "Density of the material in units kg m-3, used for wall surface temperatures according to Wallenberg et al. 2025."
+ },
+ "Wall_thickness": {
+ "Value": {
+ "Brick_wall": 0.1,
+ "Concrete_wall": 0.2,
+ "Wood_wall": 0.03
+ },
+ "Comment": "Wall thickness in units meters, used to calculate characteristic time for wall surface temperatures (Wallenberg et al., 2025)."
+ },
+ "TmaxLST": {
+ "Value": {
+ "Cobble_stone_2014a": 15.0,
+ "Dark_asphalt": 15.0,
+ "Roofs(buildings)": 15.0,
+ "Grass_unmanaged": 14.0,
+ "Bare_soil": 14.0,
+ "Water": 12.0,
+ "Walls": 15.0,
+ "Brick_wall": 15.0,
+ "Concrete_wall": 16.0,
+ "Wood_wall": 14.0
+ },
+ "Comment": "TmaxLST used for ground surface temperatures and wall surface temperatures according to Lindberg et al. 2008; 2016."
+ },
+ "Ts_deg": {
+ "Value": {
+ "Cobble_stone_2014a": 0.37,
+ "Dark_asphalt": 0.58,
+ "Roofs(buildings)": 0.58,
+ "Grass_unmanaged": 0.21,
+ "Bare_soil": 0.33,
+ "Water": 0.0,
+ "Walls": 0.37,
+ "Brick_wall": 0.40,
+ "Concrete_wall": 0.35,
+ "Wood_wall": 0.50
+ },
+ "Comment": "Ts_deg used for ground surface temperatures and wall surface temperatures according to Lindberg et al. 2008; 2016."
+ },
+ "Tstart": {
+ "Value": {
+ "Cobble_stone_2014a": -3.41,
+ "Dark_asphalt": -9.78,
+ "Roofs(buildings)": -9.78,
+ "Grass_unmanaged": -3.38,
+ "Bare_soil": -3.01,
+ "Water": 0.0,
+ "Walls": -3.41,
+ "Brick_wall": -4.0,
+ "Concrete_wall": -5.0,
+ "Wood_wall": -2.0
+ },
+ "Comment": "Tstart used for ground surface temperatures and wall surface temperatures according to Lindberg et al. 2008; 2016."
+ },
+ "Tmrt_params": {
+ "Value": {
+ "absK": 0.70,
+ "absL": 0.97,
+ "posture": "Standing"
+ },
+ "Comment": "Absorption coefficients per ISO 7726:1998. absK=0.70 (shortwave), absL=0.97 (longwave)."
+ },
+ "PET_settings": {
+ "Value": {
+ "Age": 35,
+ "Weight": 75.0,
+ "Height": 180,
+ "Sex": "Male",
+ "Activity": 80.0,
+ "clo": 0.90
+ },
+ "Comment": "Settings to calculate Physiological Equivalent Temperature (PET). Sex is either Male or Female."
+ },
+ "Wind_Height": {
+ "Value": {
+ "magl": 10.0
+ },
+ "Comment": "Height of wind sensor for PET and UTCI calculations."
+ },
+ "Tree_settings": {
+ "Value": {
+ "Transmissivity": 0.03,
+ "Trunk_ratio": 0.25,
+ "First_day_leaf": 97,
+ "Last_day_leaf": 300
+ },
+ "Comment": "Settings for trees. Shortwave transmissivity in %. Trunk ratio as a fraction of total height."
+ },
+ "Posture": {
+ "Standing": {
+ "Value": {
+ "Fside": 0.22,
+ "Fup": 0.06,
+ "height": 1.1,
+ "Fcyl": 0.28
+ },
+ "Comment": "Standing posture of human body. Used in Tmrt calculations."
+ },
+ "Sitting": {
+ "Value": {
+ "Fside": 0.166666,
+ "Fup": 0.166666,
+ "height": 0.75,
+ "Fcyl": 0.2
+ },
+ "Comment": "Sitting posture of human body. Used in Tmrt calculations."
+ }
+ }
+}
diff --git a/pysrc/solweig/data/default_params.json b/pysrc/solweig/data/default_params.json
new file mode 100644
index 0000000..d67ce65
--- /dev/null
+++ b/pysrc/solweig/data/default_params.json
@@ -0,0 +1,56 @@
+{
+ "Tmrt_params": {
+ "Value": {
+ "absK": 0.7,
+ "absL": 0.97,
+ "posture": "Standing"
+ },
+ "Comment": "Absorption coefficients per ISO 7726:1998. absK=0.70 (shortwave, clothed human), absL=0.97 (longwave). Posture is Standing or Sitting."
+ },
+ "PET_settings": {
+ "Value": {
+ "Age": 35,
+ "Weight": 75.0,
+ "Height": 180,
+ "Sex": "Male",
+ "Activity": 80.0,
+ "clo": 0.9
+ },
+ "Comment": "Settings to calculate Physiological Equivalent Temperature (PET). Sex is either Male or Female."
+ },
+ "Wind_Height": {
+ "Value": {
+ "magl": 10.0
+ },
+ "Comment": "Height of wind sensor for PET and UTCI calculations."
+ },
+ "Tree_settings": {
+ "Value": {
+ "Transmissivity": 0.03,
+ "Trunk_ratio": 0.25,
+ "First_day_leaf": 97,
+ "Last_day_leaf": 300
+ },
+ "Comment": "Settings for trees. Shortwave transmissivity in %. Trunk ratio as a fraction of total height."
+ },
+ "Posture": {
+ "Standing": {
+ "Value": {
+ "Fside": 0.22,
+ "Fup": 0.06,
+ "height": 1.1,
+ "Fcyl": 0.28
+ },
+ "Comment": "Standing posture of human body. Used in Tmrt calculations."
+ },
+ "Sitting": {
+ "Value": {
+ "Fside": 0.166666,
+ "Fup": 0.166666,
+ "height": 0.75,
+ "Fcyl": 0.2
+ },
+ "Comment": "Sitting posture of human body. Used in Tmrt calculations."
+ }
+ }
+}
diff --git a/pysrc/solweig/data/physics_defaults.json b/pysrc/solweig/data/physics_defaults.json
new file mode 100644
index 0000000..3b63036
--- /dev/null
+++ b/pysrc/solweig/data/physics_defaults.json
@@ -0,0 +1,31 @@
+{
+ "Tree_settings": {
+ "Value": {
+ "Transmissivity": 0.03,
+ "Trunk_ratio": 0.25,
+ "First_day_leaf": 97,
+ "Last_day_leaf": 300
+ },
+ "Comment": "Settings for trees. Shortwave transmissivity (leaf-on). Trunk ratio as a fraction of total height. Seasonal dates (day of year)."
+ },
+ "Posture": {
+ "Standing": {
+ "Value": {
+ "Fside": 0.22,
+ "Fup": 0.06,
+ "height": 1.1,
+ "Fcyl": 0.28
+ },
+ "Comment": "Standing posture geometry. Projected area fractions for human body. Used in Tmrt calculations."
+ },
+ "Sitting": {
+ "Value": {
+ "Fside": 0.166666,
+ "Fup": 0.166666,
+ "height": 0.75,
+ "Fcyl": 0.2
+ },
+ "Comment": "Sitting posture geometry. Projected area fractions for human body. Used in Tmrt calculations."
+ }
+ }
+}
diff --git a/pysrc/solweig/errors.py b/pysrc/solweig/errors.py
new file mode 100644
index 0000000..f026cb8
--- /dev/null
+++ b/pysrc/solweig/errors.py
@@ -0,0 +1,123 @@
+"""SOLWEIG error types for actionable error messages.
+
+These exceptions provide structured information about what went wrong
+and how to fix it, rather than generic error messages.
+
+Example:
+ try:
+ result = solweig.calculate(surface, location, weather)
+ except solweig.GridShapeMismatch as e:
+ print(f"Grid '{e.field}' has wrong shape: expected {e.expected}, got {e.got}")
+ except solweig.MissingPrecomputedData as e:
+ print(f"Missing data: {e}")
+"""
+
+from __future__ import annotations
+
+
+class SolweigError(Exception):
+ """Base class for all SOLWEIG errors."""
+
+ pass
+
+
+class InvalidSurfaceData(SolweigError):
+ """Raised when surface data is invalid or inconsistent.
+
+ Attributes:
+ message: Human-readable error description.
+ field: Name of the problematic field (e.g., "cdsm", "dem").
+ expected: What was expected (optional).
+ got: What was actually provided (optional).
+ """
+
+ def __init__(
+ self,
+ message: str,
+ field: str | None = None,
+ expected: str | None = None,
+ got: str | None = None,
+ ):
+ self.field = field
+ self.expected = expected
+ self.got = got
+ super().__init__(message)
+
+
+class GridShapeMismatch(InvalidSurfaceData):
+ """Raised when grid shapes don't match the DSM.
+
+ All surface grids (CDSM, DEM, TDSM, land_cover, etc.) must have
+ the same shape as the DSM.
+
+ Example:
+ >>> surface = SurfaceData(dsm=np.ones((100, 100)), cdsm=np.ones((50, 50)))
+ GridShapeMismatch: Grid shape mismatch for 'cdsm':
+ Expected: (100, 100) (matching DSM)
+ Got: (50, 50)
+ """
+
+ def __init__(self, field: str, expected_shape: tuple, actual_shape: tuple):
+ message = (
+ f"Grid shape mismatch for '{field}':\n"
+ f" Expected: {expected_shape} (matching DSM)\n"
+ f" Got: {actual_shape}\n"
+ "Ensure all surface grids have the same dimensions as the DSM."
+ )
+ super().__init__(message, field=field, expected=str(expected_shape), got=str(actual_shape))
+ self.expected_shape = expected_shape
+ self.actual_shape = actual_shape
+
+
+class MissingPrecomputedData(SolweigError):
+ """Raised when required precomputed data is not available.
+
+ Some features require precomputed data (e.g., anisotropic sky needs
+ shadow matrices). This error explains what's missing and how to fix it.
+
+ Attributes:
+ what: Description of the missing data.
+ suggestion: How to fix the issue (optional).
+ """
+
+ def __init__(self, what: str, suggestion: str | None = None):
+ self.what = what
+ self.suggestion = suggestion
+ message = f"Missing precomputed data: {what}"
+ if suggestion:
+ message += f"\n{suggestion}"
+ super().__init__(message)
+
+
+class WeatherDataError(SolweigError):
+ """Raised when weather data is invalid.
+
+ Attributes:
+ field: The problematic weather field (e.g., "ta", "rh").
+ value: The invalid value.
+ reason: Why the value is invalid.
+ """
+
+ def __init__(self, field: str, value: float | str, reason: str | None = None):
+ self.field = field
+ self.value = value
+ self.reason = reason
+ message = f"Invalid weather data for '{field}': {value}"
+ if reason:
+ message += f" ({reason})"
+ super().__init__(message)
+
+
+class ConfigurationError(SolweigError):
+ """Raised when configuration is invalid or inconsistent.
+
+ Attributes:
+ parameter: The problematic parameter name.
+ reason: Why the configuration is invalid.
+ """
+
+ def __init__(self, parameter: str, reason: str):
+ self.parameter = parameter
+ self.reason = reason
+ message = f"Invalid configuration for '{parameter}': {reason}"
+ super().__init__(message)
diff --git a/pysrc/solweig/io.py b/pysrc/solweig/io.py
new file mode 100644
index 0000000..688e410
--- /dev/null
+++ b/pysrc/solweig/io.py
@@ -0,0 +1,1212 @@
+from __future__ import annotations
+
+import logging
+import math
+from pathlib import Path
+
+import numpy as np
+
+from ._compat import GDAL_ENV
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# Conditional imports based on the backend chosen in _compat
+if GDAL_ENV:
+ from osgeo import gdal
+else:
+ import pyproj
+ import rasterio
+ from rasterio.features import rasterize
+ from rasterio.mask import mask
+ from rasterio.transform import Affine, from_origin
+ from rasterio.windows import Window
+ from shapely import geometry
+
+
+FLOAT_TOLERANCE = 1e-9
+
+
+def _assert_north_up(transform) -> None:
+ """Ensure the raster transform describes a north-up raster."""
+ if hasattr(transform, "b") and hasattr(transform, "d"):
+ if not math.isclose(transform.b, 0.0, abs_tol=FLOAT_TOLERANCE) or not math.isclose(
+ transform.d, 0.0, abs_tol=FLOAT_TOLERANCE
+ ):
+ raise ValueError("Only north-up rasters (no rotation) are supported.")
+ else:
+ # GDAL-style tuple (c, a, b, f, d, e)
+ if len(transform) < 6:
+ raise ValueError("Transform must contain 6 elements.")
+ if not math.isclose(transform[2], 0.0, abs_tol=FLOAT_TOLERANCE) or not math.isclose(
+ transform[4], 0.0, abs_tol=FLOAT_TOLERANCE
+ ):
+ raise ValueError("Only north-up rasters (no rotation) are supported.")
+
+
+def _shrink_axis_to_grid(min_val: float, max_val: float, origin: float, pixel_size: float) -> tuple[float, float]:
+ if pixel_size == 0:
+ raise ValueError("Pixel size must be non-zero to shrink bbox to pixel grid.")
+ step = abs(pixel_size)
+ start_idx = math.ceil(((min_val - origin) / step) - FLOAT_TOLERANCE)
+ end_idx = math.floor(((max_val - origin) / step) + FLOAT_TOLERANCE)
+ new_min = origin + start_idx * step
+ new_max = origin + end_idx * step
+ if not new_max > new_min:
+ raise ValueError("Bounding box collapsed after snapping to the pixel grid.")
+ return new_min, new_max
+
+
+def shrink_bbox_to_pixel_grid(
+ bbox: tuple[float, float, float, float],
+ origin_x: float,
+ origin_y: float,
+ pixel_width: float,
+ pixel_height: float,
+) -> tuple[float, float, float, float]:
+ """Shrink bbox so its edges land on the pixel grid defined by the raster origin."""
+
+ minx, miny, maxx, maxy = bbox
+ if minx >= maxx or miny >= maxy:
+ raise ValueError("Bounding box is invalid (min must be < max for both axes).")
+ snapped_minx, snapped_maxx = _shrink_axis_to_grid(minx, maxx, origin_x, pixel_width)
+ snapped_miny, snapped_maxy = _shrink_axis_to_grid(miny, maxy, origin_y, pixel_height)
+ return snapped_minx, snapped_miny, snapped_maxx, snapped_maxy
+
+
+def _bounds_to_tuple(bounds) -> tuple[float, float, float, float]:
+ if hasattr(bounds, "left"):
+ return bounds.left, bounds.bottom, bounds.right, bounds.top
+ return tuple(bounds)
+
+
+def _validate_bbox_within_bounds(
+ bbox: tuple[float, float, float, float], bounds, *, tol: float = FLOAT_TOLERANCE
+) -> None:
+ minx, miny, maxx, maxy = bbox
+ left, bottom, right, top = _bounds_to_tuple(bounds)
+ if minx < left - tol or maxx > right + tol or miny < bottom - tol or maxy > top + tol:
+ raise ValueError("Bounding box is not fully contained within the raster dataset bounds")
+
+
+def _compute_bounds_from_transform(transform, width: int, height: int) -> tuple[float, float, float, float]:
+ """Return raster bounds for a GDAL-style transform tuple."""
+ left = transform[0]
+ top = transform[3]
+ right = transform[0] + width * transform[1]
+ bottom = transform[3] + height * transform[5]
+ minx = min(left, right)
+ maxx = max(left, right)
+ miny = min(top, bottom)
+ maxy = max(top, bottom)
+ return minx, miny, maxx, maxy
+
+
+def _normalise_bbox(bbox_sequence) -> tuple[float, float, float, float]:
+ try:
+ minx, miny, maxx, maxy = bbox_sequence
+ except Exception as exc: # noqa: BLE001
+ raise ValueError("Bounding box must contain exactly four numeric values") from exc
+ return float(minx), float(miny), float(maxx), float(maxy)
+
+
+def rasterise_gdf(gdf, geom_col, ht_col, bbox=None, pixel_size: float = 1.0):
+ # Define raster parameters
+ if bbox is not None:
+ # Unpack bbox values
+ minx, miny, maxx, maxy = _normalise_bbox(bbox)
+ else:
+ # Use the total bounds of the GeoDataFrame
+ minx, miny, maxx, maxy = map(float, gdf.total_bounds)
+ if pixel_size <= 0:
+ raise ValueError("Pixel size must be a positive number.")
+ minx, miny, maxx, maxy = shrink_bbox_to_pixel_grid(
+ (minx, miny, maxx, maxy),
+ origin_x=minx,
+ origin_y=maxy,
+ pixel_width=pixel_size,
+ pixel_height=pixel_size,
+ )
+ width = int(round((maxx - minx) / pixel_size))
+ height = int(round((maxy - miny) / pixel_size))
+ if width <= 0 or height <= 0:
+ raise ValueError("Bounding box collapsed after snapping to pixel grid.")
+ transform = from_origin(minx, maxy, pixel_size, pixel_size)
+ # Create a blank array for the raster
+ raster = np.zeros((height, width), dtype=np.float32)
+ # Burn geometries into the raster
+ shapes = ((geom, value) for geom, value in zip(gdf[geom_col], gdf[ht_col]))
+ raster = rasterize(shapes, out_shape=raster.shape, transform=transform, fill=0, dtype=np.float32)
+
+ return raster, transform
+
+
+def check_path(path_str: str | Path, make_dir: bool = False) -> Path:
+ # Ensure path exists
+ path = Path(path_str).absolute()
+ if not path.parent.exists():
+ if make_dir:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ else:
+ raise OSError(
+ f"Parent directory {path.parent} does not exist for path {path}. Set make_dir=True to create it."
+ )
+ if not path.exists() and not path.suffix:
+ if make_dir:
+ path.mkdir(parents=True, exist_ok=True)
+ else:
+ raise OSError(f"Path {path} does not exist. Set make_dir=True to create it.")
+ return path
+
+
+# Default color scale ranges for preview images (ensures consistency across timesteps)
+# Format: prefix -> (vmin, vmax)
+_PREVIEW_RANGES: dict[str, tuple[float, float]] = {
+ "tmrt": (0, 80), # Mean radiant temperature (°C)
+ "utci": (-40, 50), # Universal Thermal Climate Index (°C)
+ "pet": (-40, 50), # Physiological Equivalent Temperature (°C)
+ "shadow": (0, 1), # Shadow fraction (0=sun, 1=shade)
+ "kdown": (0, 1200), # Downwelling shortwave radiation (W/m²)
+ "kup": (0, 800), # Upwelling shortwave radiation (W/m²)
+ "ldown": (150, 550), # Downwelling longwave radiation (W/m²)
+ "lup": (250, 650), # Upwelling longwave radiation (W/m²)
+ "svf": (0, 1), # Sky view factor
+ "gvf": (0, 1), # Ground view factor
+}
+
+
+def _get_preview_range(filename: str) -> tuple[float, float] | None:
+ """Get the color scale range for a variable based on filename prefix."""
+ name = filename.lower()
+ for prefix, range_vals in _PREVIEW_RANGES.items():
+ if name.startswith(prefix):
+ return range_vals
+ return None
+
+
+def _generate_preview_png(data_arr: np.ndarray, out_path: Path, max_size: int = 512, colormap: str = "turbo") -> None:
+ """
+ Generate a color PNG preview image from raster data.
+
+ Uses consistent color scales for known variable types (tmrt, utci, shadow, etc.)
+ to enable visual comparison across timesteps. Falls back to percentile-based
+ scaling for unknown variables.
+
+ Args:
+ data_arr: 2D numpy array to visualize
+ out_path: Output file path (preview will be saved as .preview.png)
+ max_size: Maximum dimension for the preview image (maintains aspect ratio)
+ colormap: Matplotlib colormap name (default: 'turbo'). Falls back to grayscale if unavailable.
+ Common options: 'turbo', 'viridis', 'plasma', 'inferno', 'magma', 'coolwarm'
+ """
+ try:
+ from PIL import Image
+
+ # Handle NaN values
+ valid_mask = ~np.isnan(data_arr)
+ if not np.any(valid_mask):
+ return # All NaN, skip preview
+
+ # Use variable-specific range if available, otherwise fall back to percentiles
+ preset_range = _get_preview_range(out_path.stem)
+ if preset_range is not None:
+ vmin, vmax = preset_range
+ else:
+ # Fallback: use percentiles for unknown variables
+ valid_data = data_arr[valid_mask]
+ vmin, vmax = np.nanpercentile(valid_data, [2, 98])
+
+ if vmax <= vmin:
+ vmax = vmin + 1 # Avoid division by zero
+
+ # Normalize to 0-1
+ normalized = np.clip((data_arr - vmin) / (vmax - vmin), 0, 1)
+ normalized = np.nan_to_num(normalized, nan=0)
+
+ # Try to apply matplotlib colormap for color output
+ try:
+ import matplotlib.pyplot as plt
+
+ # Get colormap and apply
+ cmap = plt.get_cmap(colormap)
+ colored = cmap(normalized) # Returns RGBA in [0, 1]
+
+ # Convert to RGB uint8 (drop alpha channel)
+ rgb = (colored[:, :, :3] * 255).astype(np.uint8)
+ img = Image.fromarray(rgb, mode="RGB")
+ except (ImportError, ValueError):
+ # Fallback to grayscale if matplotlib not available or colormap invalid
+ grayscale = (normalized * 255).astype(np.uint8)
+ img = Image.fromarray(grayscale, mode="L")
+
+ # Resize to max_size while maintaining aspect ratio
+ if max(img.size) > max_size:
+ ratio = max_size / max(img.size)
+ new_size = (int(img.width * ratio), int(img.height * ratio))
+ img = img.resize(new_size, Image.Resampling.LANCZOS)
+
+ # Save preview
+ preview_path = out_path.with_suffix(".preview.png")
+ img.save(preview_path, "PNG")
+ logger.debug(f"Saved preview: {preview_path}")
+ except ImportError:
+ logger.debug("PIL not available, skipping preview generation")
+ except Exception as e:
+ logger.warning(f"Failed to generate preview: {e}")
+
+
+def save_raster(
+ out_path_str: str,
+ data_arr: np.ndarray,
+ trf_arr: list[float],
+ crs_wkt: str | None,
+ no_data_val: float = -9999,
+ coerce_f64_to_f32: bool = True,
+ use_cog: bool = True,
+ generate_preview: bool = True,
+):
+ """
+ Save raster to GeoTIFF (Cloud-Optimized by default).
+
+ Args:
+ out_path_str: Output file path
+ data_arr: 2D numpy array to save
+ trf_arr: GDAL-style geotransform [top_left_x, pixel_width, rotation, top_left_y, rotation, pixel_height]
+ crs_wkt: CRS in WKT format
+ no_data_val: No-data value to use
+ coerce_f64_to_f32: If True, convert float64 arrays to float32 before saving
+ (default: True for memory efficiency)
+ use_cog: If True, save as Cloud-Optimized GeoTIFF with built-in overviews
+ (default: True for better OS thumbnail support)
+ generate_preview: If True, generate a sidecar .preview.png file for OS thumbnails
+ (default: True for float data that can't be previewed directly)
+ """
+ # Only convert float64 to float32, leave ints/bools unchanged
+ if coerce_f64_to_f32 and data_arr.dtype == np.float64:
+ data_arr = data_arr.astype(np.float32)
+
+ attempts = 2
+ while attempts > 0:
+ attempts -= 1
+ try:
+ out_path = check_path(out_path_str, make_dir=True)
+ height, width = data_arr.shape
+
+ if GDAL_ENV is False:
+ trf = Affine.from_gdal(*trf_arr)
+ crs = None
+ if crs_wkt:
+ crs = pyproj.CRS(crs_wkt)
+
+ if use_cog:
+ # Write as Cloud-Optimized GeoTIFF
+ # COG driver creates overviews automatically
+ from rasterio.io import MemoryFile
+
+ # Create in memory first, then write as COG
+ memfile = MemoryFile()
+ with memfile.open(
+ driver="GTiff",
+ height=height,
+ width=width,
+ count=1,
+ dtype=data_arr.dtype,
+ crs=crs,
+ transform=trf,
+ nodata=no_data_val,
+ ) as mem:
+ mem.write(data_arr, 1)
+
+ # Now copy to COG format
+ from rasterio.shutil import copy
+
+ copy(
+ memfile.open(),
+ out_path,
+ driver="COG",
+ overview_resampling="average",
+ )
+ memfile.close()
+ logger.debug(f"Saved COG: {out_path}")
+ else:
+ # Standard GeoTIFF
+ with rasterio.open(
+ out_path,
+ "w",
+ driver="GTiff",
+ height=height,
+ width=width,
+ count=1,
+ dtype=data_arr.dtype,
+ crs=crs,
+ transform=trf,
+ nodata=no_data_val,
+ ) as dst:
+ dst.write(data_arr, 1)
+ else:
+ # GDAL backend
+ if use_cog:
+ # Use COG driver (GDAL 3.1+)
+ driver = gdal.GetDriverByName("COG")
+ if driver is None:
+ # Fallback to GTiff with overviews if COG driver not available
+ logger.warning("COG driver not available, using GTiff with overviews")
+ driver = gdal.GetDriverByName("GTiff")
+ options = ["TILED=YES"]
+ ds = driver.Create(str(out_path), width, height, 1, gdal.GDT_Float32, options)
+ ds.SetGeoTransform(trf_arr)
+ if crs_wkt:
+ ds.SetProjection(crs_wkt)
+ band = ds.GetRasterBand(1)
+ band.SetNoDataValue(no_data_val)
+ band.WriteArray(data_arr)
+ # Build overviews
+ if min(height, width) > 256:
+ overview_levels = []
+ size = min(height, width)
+ level = 2
+ while size // level > 128:
+ overview_levels.append(level)
+ level *= 2
+ if overview_levels:
+ ds.BuildOverviews("AVERAGE", overview_levels)
+ ds = None
+ else:
+ # COG driver requires creating via CreateCopy from memory dataset
+ mem_driver = gdal.GetDriverByName("MEM")
+ mem_ds = mem_driver.Create("", width, height, 1, gdal.GDT_Float32)
+ mem_ds.SetGeoTransform(trf_arr)
+ if crs_wkt:
+ mem_ds.SetProjection(crs_wkt)
+ band = mem_ds.GetRasterBand(1)
+ band.SetNoDataValue(no_data_val)
+ band.WriteArray(data_arr)
+
+ # Copy to COG
+ cog_options = ["OVERVIEW_RESAMPLING=AVERAGE"]
+ driver.CreateCopy(str(out_path), mem_ds, options=cog_options)
+ mem_ds = None
+ logger.debug(f"Saved COG: {out_path}")
+ else:
+ # Standard GeoTIFF
+ driver = gdal.GetDriverByName("GTiff")
+ ds = driver.Create(str(out_path), width, height, 1, gdal.GDT_Float32)
+ ds.SetGeoTransform(trf_arr)
+ if crs_wkt:
+ ds.SetProjection(crs_wkt)
+ band = ds.GetRasterBand(1)
+ band.SetNoDataValue(no_data_val)
+ band.WriteArray(data_arr)
+ ds = None
+
+ # Generate sidecar preview PNG for float data (OS can't render float GeoTIFFs)
+ if generate_preview and np.issubdtype(data_arr.dtype, np.floating):
+ _generate_preview_png(data_arr, out_path)
+
+ return
+ except Exception as e:
+ if attempts == 0:
+ raise e
+ logger.warning(f"Failed to save raster to {out_path_str}: {e}. Retrying...")
+
+
+def get_raster_metadata(path_str: str | Path) -> dict:
+ """
+ Get raster metadata without loading the whole file.
+ Returns dict with keys: rows, cols, transform, crs, nodata, res.
+ Transform is always a list [c, a, b, f, d, e] (GDAL-style).
+ CRS is always a WKT string (or None).
+ """
+ path = check_path(path_str)
+ if GDAL_ENV is False:
+ with rasterio.open(path) as src:
+ # Convert Affine to GDAL-style list
+ trf = src.transform
+ transform_list = [trf.c, trf.a, trf.b, trf.f, trf.d, trf.e]
+ # Convert CRS to WKT string
+ crs_wkt = src.crs.to_wkt() if src.crs is not None else None
+ return {
+ "rows": src.height,
+ "cols": src.width,
+ "transform": transform_list,
+ "crs": crs_wkt,
+ "nodata": src.nodata,
+ "res": src.res, # (xres, yres)
+ "bounds": src.bounds,
+ }
+ else:
+ ds = gdal.Open(str(path))
+ if ds is None:
+ raise OSError(f"Could not open {path}")
+ gt = ds.GetGeoTransform()
+ return {
+ "rows": ds.RasterYSize,
+ "cols": ds.RasterXSize,
+ "transform": gt,
+ "crs": ds.GetProjection() or None,
+ "nodata": ds.GetRasterBand(1).GetNoDataValue(),
+ "res": (gt[1], abs(gt[5])), # Approximate resolution
+ }
+
+
+def read_raster_window(path_str: str | Path, window: tuple[slice, slice], band: int = 1) -> np.ndarray:
+ """
+ Read a window from a raster file.
+ window is (row_slice, col_slice).
+ """
+ path = check_path(path_str)
+ row_slice, col_slice = window
+
+ # Handle None slices (read full dimension)
+ # This is tricky without knowing full shape, so we assume caller provides valid slices
+ # or we'd need to open file to check shape first.
+ # For now, assume valid integer slices.
+
+ if GDAL_ENV is False:
+ with rasterio.open(path) as src:
+ # rasterio Window(col_off, row_off, width, height)
+ # Slices are start:stop
+ r_start = row_slice.start if row_slice.start is not None else 0
+ r_stop = row_slice.stop if row_slice.stop is not None else src.height
+ c_start = col_slice.start if col_slice.start is not None else 0
+ c_stop = col_slice.stop if col_slice.stop is not None else src.width
+
+ win = Window(c_start, r_start, c_stop - c_start, r_stop - r_start) # type: ignore[too-many-positional-arguments]
+ return src.read(band, window=win)
+ else:
+ ds = gdal.Open(str(path))
+ if ds is None:
+ raise OSError(f"Could not open {path}")
+
+ r_start = row_slice.start if row_slice.start is not None else 0
+ r_stop = row_slice.stop if row_slice.stop is not None else ds.RasterYSize
+ c_start = col_slice.start if col_slice.start is not None else 0
+ c_stop = col_slice.stop if col_slice.stop is not None else ds.RasterXSize
+
+ xoff = c_start
+ yoff = r_start
+ xsize = c_stop - c_start
+ ysize = r_stop - r_start
+
+ return ds.GetRasterBand(band).ReadAsArray(xoff, yoff, xsize, ysize)
+
+
+def load_raster(
+ path_str: str, bbox: list[int] | None = None, band: int = 0, coerce_f64_to_f32: bool = True
+) -> tuple[np.ndarray, list[float], str | None, float | None]:
+ """
+ Load raster, optionally crop to bbox.
+
+ Args:
+ path_str: Path to raster file
+ bbox: Optional bounding box [minx, miny, maxx, maxy]
+ band: Band index to read (0-based)
+ coerce_f64_to_f32: If True, coerce array to float32 (default: True for memory efficiency)
+
+ Returns:
+ Tuple of (array, transform, crs_wkt, no_data_value)
+ """
+ # Load raster, optionally crop to bbox
+ path = check_path(path_str, make_dir=False)
+ if not path.exists():
+ raise FileNotFoundError(f"Raster file {path} does not exist.")
+ if GDAL_ENV is False:
+ with rasterio.open(path) as dataset:
+ _assert_north_up(dataset.transform)
+ crs_wkt = dataset.crs.to_wkt() if dataset.crs is not None else None
+ no_data_val = dataset.nodata
+ transform = dataset.transform
+ if bbox is not None:
+ bbox_tuple = _normalise_bbox(bbox)
+ snapped_bbox = shrink_bbox_to_pixel_grid(
+ bbox_tuple,
+ origin_x=transform.c,
+ origin_y=transform.f,
+ pixel_width=transform.a,
+ pixel_height=transform.e,
+ )
+ _validate_bbox_within_bounds(snapped_bbox, dataset.bounds)
+ bbox_geom = geometry.box(*snapped_bbox)
+ rast, trf = mask(dataset, [bbox_geom], crop=True)
+ else:
+ rast = dataset.read()
+ trf = transform
+ # Convert rasterio Affine to GDAL-style list
+ trf_arr = [trf.c, trf.a, trf.b, trf.f, trf.d, trf.e]
+ # rast shape: (bands, rows, cols)
+ if rast.ndim == 3:
+ if band < 0 or band >= rast.shape[0]:
+ raise IndexError(f"Requested band {band} out of range; raster has {rast.shape[0]} band(s)")
+ rast_arr = rast[band]
+ # Only convert float64 to float32, leave ints/bools unchanged
+ if coerce_f64_to_f32 and rast_arr.dtype == np.float64:
+ rast_arr = rast_arr.astype(np.float32)
+ else:
+ rast_arr = rast
+ # Only convert float64 to float32, leave ints/bools unchanged
+ if coerce_f64_to_f32 and rast_arr.dtype == np.float64:
+ rast_arr = rast_arr.astype(np.float32)
+ else:
+ dataset = gdal.Open(str(path))
+ if dataset is None:
+ raise FileNotFoundError(f"Could not open {path}")
+ trf = dataset.GetGeoTransform()
+ _assert_north_up(trf)
+ # GetProjection returns WKT string (or empty string)
+ crs_wkt = dataset.GetProjection() or None
+ rb = dataset.GetRasterBand(band + 1)
+ if rb is None:
+ dataset = None
+ raise IndexError(f"Requested band {band} out of range in GDAL dataset")
+ rast_arr = rb.ReadAsArray()
+ # Only convert float64 to float32, leave ints/bools unchanged
+ if coerce_f64_to_f32 and rast_arr.dtype == np.float64:
+ rast_arr = rast_arr.astype(np.float32)
+ no_data_val = rb.GetNoDataValue()
+ if bbox is not None:
+ bbox_tuple = _normalise_bbox(bbox)
+ snapped_bbox = shrink_bbox_to_pixel_grid(
+ bbox_tuple,
+ origin_x=trf[0],
+ origin_y=trf[3],
+ pixel_width=trf[1],
+ pixel_height=trf[5],
+ )
+ bounds = _compute_bounds_from_transform(trf, dataset.RasterXSize, dataset.RasterYSize)
+ _validate_bbox_within_bounds(snapped_bbox, bounds)
+ min_x, min_y, max_x, max_y = snapped_bbox
+ pixel_width = trf[1]
+ pixel_height = abs(trf[5])
+ xoff = int(round((min_x - trf[0]) / pixel_width))
+ yoff = int(round((trf[3] - max_y) / pixel_height))
+ xsize = int(round((max_x - min_x) / pixel_width))
+ ysize = int(round((max_y - min_y) / pixel_height))
+ # guard offsets/sizes
+ if xoff < 0 or yoff < 0 or xsize <= 0 or ysize <= 0:
+ dataset = None
+ raise ValueError("Computed window from bbox is out of raster bounds or invalid")
+ rast_arr = rast_arr[yoff : yoff + ysize, xoff : xoff + xsize]
+ trf_arr = [min_x, trf[1], 0, max_y, 0, trf[5]]
+ else:
+ trf_arr = [trf[0], trf[1], 0, trf[3], 0, trf[5]]
+ dataset = None # ensure dataset closed
+ # Handle no-data (support NaN)
+ if no_data_val is not None and not np.isnan(no_data_val):
+ logger.info(f"No-data value is {no_data_val}, replacing with NaN")
+ rast_arr[rast_arr == no_data_val] = np.nan
+ if rast_arr.size == 0:
+ raise ValueError("Raster array is empty after loading/cropping")
+ return rast_arr, trf_arr, crs_wkt, no_data_val
+
+
+def xy_to_lnglat(crs_wkt: str | None, x, y):
+ """Convert x, y coordinates to longitude and latitude.
+
+ Accepts scalar or array-like x/y. If crs_wkt is None the inputs are
+ assumed already to be lon/lat and are returned unchanged.
+ """
+ if crs_wkt is None:
+ logger.info("No CRS provided, assuming coordinates are already in WGS84 (lon/lat).")
+ return x, y
+
+ try:
+ if GDAL_ENV is False:
+ source_crs = pyproj.CRS(crs_wkt)
+ target_crs = pyproj.CRS(4326) # WGS84
+ transformer = pyproj.Transformer.from_crs(source_crs, target_crs, always_xy=True)
+ lng, lat = transformer.transform(x, y)
+ else:
+ old_cs = gdal.osr.SpatialReference()
+ old_cs.ImportFromWkt(crs_wkt)
+ new_cs = gdal.osr.SpatialReference()
+ new_cs.ImportFromEPSG(4326)
+ transform = gdal.osr.CoordinateTransformation(old_cs, new_cs)
+ out = transform.TransformPoint(float(x), float(y))
+ lng, lat = out[0], out[1]
+
+ return lng, lat
+
+ except Exception:
+ logger.exception("Failed to transform coordinates")
+ raise
+
+
+def create_empty_raster(
+ path_str: str | Path,
+ rows: int,
+ cols: int,
+ transform: list[float],
+ crs_wkt: str,
+ dtype=np.float32,
+ nodata: float = -9999,
+ bands: int = 1,
+):
+ """
+ Create an empty GeoTIFF file initialized with nodata.
+ """
+ path = check_path(path_str, make_dir=True)
+
+ if GDAL_ENV is False:
+ trf = Affine.from_gdal(*transform)
+ crs = None
+ if crs_wkt:
+ crs = pyproj.CRS(crs_wkt)
+
+ with rasterio.open(
+ path,
+ "w",
+ driver="GTiff",
+ height=rows,
+ width=cols,
+ count=bands,
+ dtype=dtype,
+ crs=crs,
+ transform=trf,
+ nodata=nodata,
+ ):
+ pass # Just create empty raster
+ else:
+ driver = gdal.GetDriverByName("GTiff")
+ # Map numpy dtype to GDAL type
+ gdal_type = gdal.GDT_Float32 # Default
+ if dtype == np.float64:
+ gdal_type = gdal.GDT_Float64
+ elif dtype == np.int32:
+ gdal_type = gdal.GDT_Int32
+ elif dtype == np.int16:
+ gdal_type = gdal.GDT_Int16
+ elif dtype == np.uint8:
+ gdal_type = gdal.GDT_Byte
+
+ ds = driver.Create(str(path), cols, rows, bands, gdal_type)
+ ds.SetGeoTransform(transform)
+ if crs_wkt:
+ ds.SetProjection(crs_wkt)
+ for b in range(1, bands + 1):
+ band = ds.GetRasterBand(b)
+ band.SetNoDataValue(nodata)
+ band.Fill(nodata)
+ ds = None
+
+
+def write_raster_window(path_str: str | Path, data: np.ndarray, window: tuple[slice, slice], band: int = 1):
+ """
+ Write a data array to a specific window in an existing raster.
+ window is (row_slice, col_slice).
+ """
+ path = check_path(path_str)
+ row_slice, col_slice = window
+
+ if GDAL_ENV is False:
+ from rasterio.windows import Window
+
+ with rasterio.open(path, "r+") as dst:
+ win = Window(
+ col_slice.start, # type: ignore[too-many-positional-arguments]
+ row_slice.start,
+ col_slice.stop - col_slice.start,
+ row_slice.stop - row_slice.start,
+ )
+ dst.write(data, band, window=win)
+ else:
+ ds = gdal.Open(str(path), gdal.GA_Update)
+ if ds is None:
+ raise OSError(f"Could not open {path} for update")
+
+ xoff = col_slice.start
+ yoff = row_slice.start
+
+ ds.GetRasterBand(band).WriteArray(data, xoff, yoff)
+ ds = None
+
+
+class _EpwDataIndex:
+ """Lightweight index class mimicking pandas DatetimeIndex for EPW data."""
+
+ def __init__(self, timestamps: list):
+ self._timestamps = timestamps
+ self.tz = None
+ self.name = "datetime"
+
+ def __len__(self):
+ return len(self._timestamps)
+
+ def __getitem__(self, idx):
+ return self._timestamps[idx]
+
+ def __iter__(self):
+ return iter(self._timestamps)
+
+ def __ge__(self, other):
+ """Greater than or equal comparison, returns boolean array."""
+ return _BooleanArray([t >= other for t in self._timestamps])
+
+ def __le__(self, other):
+ """Less than or equal comparison, returns boolean array."""
+ return _BooleanArray([t <= other for t in self._timestamps])
+
+ def __gt__(self, other):
+ """Greater than comparison, returns boolean array."""
+ return _BooleanArray([t > other for t in self._timestamps])
+
+ def __lt__(self, other):
+ """Less than comparison, returns boolean array."""
+ return _BooleanArray([t < other for t in self._timestamps])
+
+ @property
+ def empty(self):
+ return len(self._timestamps) == 0
+
+ @property
+ def year(self):
+ return [t.year for t in self._timestamps]
+
+ @property
+ def month(self):
+ return _IndexAccessor([t.month for t in self._timestamps])
+
+ @property
+ def day(self):
+ return _IndexAccessor([t.day for t in self._timestamps])
+
+ @property
+ def hour(self):
+ return _IndexAccessor([t.hour for t in self._timestamps])
+
+ def min(self):
+ return min(self._timestamps) if self._timestamps else None
+
+ def max(self):
+ return max(self._timestamps) if self._timestamps else None
+
+ def tz_localize(self, tz):
+ # Return self since we don't handle timezones in the fallback
+ return self
+
+
+class _IndexAccessor:
+ """Helper for index property access like df.index.hour."""
+
+ def __init__(self, values: list):
+ self._values = values
+
+ def __iter__(self):
+ return iter(self._values)
+
+ def __gt__(self, other):
+ return _BooleanArray([v > other for v in self._values])
+
+ def __ge__(self, other):
+ return _BooleanArray([v >= other for v in self._values])
+
+ def __lt__(self, other):
+ return _BooleanArray([v < other for v in self._values])
+
+ def __le__(self, other):
+ return _BooleanArray([v <= other for v in self._values])
+
+ def __eq__(self, other):
+ return _BooleanArray([v == other for v in self._values])
+
+ def isin(self, values_set):
+ return [v in values_set for v in self._values]
+
+
+class _BooleanArray:
+ """Helper for boolean array operations (& and |)."""
+
+ def __init__(self, values: list):
+ self._values = values
+
+ def __and__(self, other):
+ if isinstance(other, _BooleanArray):
+ return _BooleanArray([a and b for a, b in zip(self._values, other._values)])
+ return _BooleanArray([a and b for a, b in zip(self._values, other)])
+
+ def __or__(self, other):
+ if isinstance(other, _BooleanArray):
+ return _BooleanArray([a or b for a, b in zip(self._values, other._values)])
+ return _BooleanArray([a or b for a, b in zip(self._values, other)])
+
+ def __iter__(self):
+ return iter(self._values)
+
+ def __getitem__(self, idx):
+ return self._values[idx]
+
+ def __len__(self):
+ return len(self._values)
+
+ def all(self):
+ return all(self._values)
+
+ def any(self):
+ return any(self._values)
+
+ def tolist(self):
+ return self._values
+
+
+class _EpwRow:
+ """Lightweight row class mimicking pandas Series for EPW data."""
+
+ def __init__(self, data: dict):
+ self._data = data
+
+ def __getitem__(self, key):
+ return self._data.get(key, float("nan"))
+
+ def get(self, key, default=None):
+ """Get value with default, like dict.get()."""
+ val = self._data.get(key, default)
+ if val is None or (isinstance(val, float) and val != val): # NaN check
+ return default
+ return val
+
+
+class _EpwColumn:
+ """Lightweight column accessor mimicking a pandas Series for a single column."""
+
+ def __init__(self, values: list):
+ self._values = values
+
+ def __getitem__(self, idx):
+ return self._values[idx]
+
+ def __len__(self):
+ return len(self._values)
+
+ def __iter__(self):
+ return iter(self._values)
+
+ def min(self):
+ return min(v for v in self._values if v == v) # skip NaN
+
+ def max(self):
+ return max(v for v in self._values if v == v) # skip NaN
+
+ def __ge__(self, other):
+ return _BooleanArray([v >= other for v in self._values])
+
+ def __le__(self, other):
+ return _BooleanArray([v <= other for v in self._values])
+
+ def __gt__(self, other):
+ return _BooleanArray([v > other for v in self._values])
+
+ def __lt__(self, other):
+ return _BooleanArray([v < other for v in self._values])
+
+ def all(self):
+ return all(self._values)
+
+
+class _EpwIloc:
+ """Positional indexing for _EpwDataFrame."""
+
+ def __init__(self, rows: list[dict]):
+ self._rows = rows
+
+ def __getitem__(self, idx):
+ return _EpwRow(self._rows[idx])
+
+
+class _EpwDataFrame:
+ """Lightweight DataFrame-like class for EPW data without pandas dependency."""
+
+ def __init__(self, rows: list[dict], timestamps: list):
+ self._rows = rows
+ self._timestamps = timestamps
+ self.index = _EpwDataIndex(timestamps)
+
+ def __len__(self):
+ return len(self._rows)
+
+ @property
+ def columns(self):
+ """Column names from the first row."""
+ if self._rows:
+ return list(self._rows[0].keys())
+ return []
+
+ @property
+ def iloc(self):
+ """Positional indexing (returns _EpwRow objects)."""
+ return _EpwIloc(self._rows)
+
+ def __getitem__(self, key):
+ """Access by column name (str) or filter by boolean mask."""
+ if isinstance(key, str):
+ return _EpwColumn([row.get(key, float("nan")) for row in self._rows])
+ if isinstance(key, _BooleanArray):
+ key = key._values
+ if isinstance(key, list):
+ filtered_rows = [r for r, m in zip(self._rows, key) if m]
+ filtered_ts = [t for t, m in zip(self._timestamps, key) if m]
+ return _EpwDataFrame(filtered_rows, filtered_ts)
+ raise TypeError(f"Unsupported indexing type: {type(key)}")
+
+ @property
+ def empty(self):
+ return len(self._rows) == 0
+
+ def iterrows(self):
+ """Iterate over (timestamp, row) pairs."""
+ for ts, row_data in zip(self._timestamps, self._rows):
+ yield _EpwTimestamp(ts), _EpwRow(row_data)
+
+ def to_dataframe(self):
+ """Convert to pandas DataFrame if pandas is available.
+
+ Returns:
+ pd.DataFrame with DatetimeIndex, or self if pandas unavailable.
+ """
+ try:
+ import pandas as pd
+
+ df = pd.DataFrame(self._rows)
+ df.index = pd.DatetimeIndex(self._timestamps, name="datetime")
+ return df
+ except ImportError:
+ return self
+
+
+class _EpwTimestamp:
+ """Wrapper for datetime to provide pandas-like interface."""
+
+ def __init__(self, dt_obj):
+ self._dt = dt_obj
+
+ def __getattr__(self, name):
+ return getattr(self._dt, name)
+
+ def to_pydatetime(self):
+ return self._dt
+
+ def replace(self, **kwargs):
+ return self._dt.replace(**kwargs)
+
+
+def _parse_epw_metadata(path: Path) -> dict:
+ """Parse EPW header to extract metadata."""
+ metadata = {}
+ with open(path, encoding="utf-8") as f:
+ location_line = f.readline().strip()
+ if not location_line.startswith("LOCATION"):
+ raise ValueError("Invalid EPW file: first line must start with 'LOCATION'")
+
+ location_parts = location_line.split(",")
+ if len(location_parts) < 10:
+ raise ValueError(f"Invalid LOCATION line: expected at least 10 fields, got {len(location_parts)}")
+
+ metadata["city"] = location_parts[1].strip()
+ metadata["state"] = location_parts[2].strip()
+ metadata["country"] = location_parts[3].strip()
+ metadata["latitude"] = float(location_parts[6])
+ metadata["longitude"] = float(location_parts[7])
+ metadata["tz_offset"] = float(location_parts[8])
+ metadata["elevation"] = float(location_parts[9])
+
+ return metadata
+
+
+def _read_epw_pure_python(path: Path) -> tuple:
+ """Pure Python EPW parser without pandas dependency."""
+ import csv
+ from datetime import datetime as dt_class
+
+ metadata = _parse_epw_metadata(path)
+
+ # Column indices for the fields we need
+ # EPW format has 35 fields per line
+ col_indices = {
+ "year": 0,
+ "month": 1,
+ "day": 2,
+ "hour": 3,
+ "minute": 4,
+ "temp_air": 6,
+ "relative_humidity": 8,
+ "atmospheric_pressure": 9,
+ "ghi": 13,
+ "dni": 14,
+ "dhi": 15,
+ "wind_direction": 20,
+ "wind_speed": 21,
+ }
+
+ na_values = {"99", "999", "9999", "99999", "999999999", ""}
+
+ rows = []
+ timestamps = []
+
+ with open(path, encoding="utf-8") as f:
+ # Skip 8 header lines
+ for _ in range(8):
+ f.readline()
+
+ reader = csv.reader(f)
+ for line in reader:
+ if len(line) < 22:
+ continue
+
+ try:
+ year = int(line[col_indices["year"]])
+ month = int(line[col_indices["month"]])
+ day = int(line[col_indices["day"]])
+ hour = int(line[col_indices["hour"]])
+ minute = int(line[col_indices["minute"]])
+
+ # EPW uses 1-24 hour format; hour 24 means midnight of next day
+ if hour == 24:
+ hour = 0
+ # We'd need to add a day, but for simplicity just use hour 0
+ # This matches pandas behavior with errors="coerce"
+
+ timestamp = dt_class(year, month, day, hour, minute)
+ timestamps.append(timestamp)
+
+ def parse_float(idx, row_data=line):
+ val = row_data[idx].strip()
+ if val in na_values:
+ return float("nan")
+ try:
+ return float(val)
+ except (ValueError, TypeError):
+ return float("nan")
+
+ row = {
+ "temp_air": parse_float(col_indices["temp_air"]),
+ "relative_humidity": parse_float(col_indices["relative_humidity"]),
+ "atmospheric_pressure": parse_float(col_indices["atmospheric_pressure"]),
+ "ghi": parse_float(col_indices["ghi"]),
+ "dni": parse_float(col_indices["dni"]),
+ "dhi": parse_float(col_indices["dhi"]),
+ "wind_speed": parse_float(col_indices["wind_speed"]),
+ "wind_direction": parse_float(col_indices["wind_direction"]),
+ }
+ rows.append(row)
+ except (ValueError, IndexError):
+ continue
+
+ if not rows:
+ raise ValueError("EPW file contains no valid data rows")
+
+ df = _EpwDataFrame(rows, timestamps)
+ logger.info(f"Loaded EPW file: {metadata['city']}, {len(df)} timesteps (pure Python parser)")
+
+ return df, metadata
+
+
+def download_epw(
+ latitude: float,
+ longitude: float,
+ output_path: str | Path,
+ *,
+ timeout: int = 60,
+) -> Path:
+ """
+ Download a Typical Meteorological Year (TMY) EPW file from PVGIS.
+
+ Uses the EU Joint Research Centre's PVGIS API (no API key required).
+ Coverage is near-global (all continents except polar regions),
+ using ERA5 reanalysis data.
+
+ Args:
+ latitude: Latitude in decimal degrees (-90 to 90).
+ longitude: Longitude in decimal degrees (-180 to 180).
+ output_path: Path where the EPW file will be saved.
+ timeout: HTTP request timeout in seconds (default 60).
+
+ Returns:
+ Path to the saved EPW file.
+
+ Raises:
+ ValueError: If coordinates are out of range.
+ ConnectionError: If the PVGIS server is unreachable.
+ RuntimeError: If the download fails (e.g. location over ocean).
+
+ Example:
+ >>> from solweig.io import download_epw
+ >>> path = download_epw(37.98, 23.73, "athens.epw")
+ >>> data, metadata = read_epw(path)
+ """
+ import urllib.error
+ import urllib.request
+
+ if not -90 <= latitude <= 90:
+ raise ValueError(f"Latitude must be between -90 and 90, got {latitude}")
+ if not -180 <= longitude <= 180:
+ raise ValueError(f"Longitude must be between -180 and 180, got {longitude}")
+
+ output_path = Path(output_path)
+
+ url = f"https://re.jrc.ec.europa.eu/api/v5_3/tmy?lat={latitude}&lon={longitude}&outputformat=epw"
+
+ logger.info(f"Downloading EPW from PVGIS for ({latitude:.4f}, {longitude:.4f})...")
+
+ try:
+ req = urllib.request.Request(url)
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ data = resp.read()
+ except urllib.error.HTTPError as e:
+ if e.code == 400:
+ raise RuntimeError(
+ f"PVGIS has no data for ({latitude}, {longitude}). The location may be over ocean or outside coverage."
+ ) from e
+ raise RuntimeError(f"PVGIS download failed (HTTP {e.code}): {e.reason}") from e
+ except urllib.error.URLError as e:
+ raise ConnectionError(f"Cannot reach PVGIS server: {e.reason}") from e
+
+ if len(data) < 1000:
+ # PVGIS returns a short error message for invalid locations
+ text = data.decode("utf-8", errors="replace")
+ raise RuntimeError(f"PVGIS returned an error: {text.strip()}")
+
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ output_path.write_bytes(data)
+
+ lines = data.decode("utf-8", errors="replace").split("\n")
+ n_data_lines = len(lines) - 8 # subtract header lines
+ logger.info(f"Saved EPW file: {output_path} ({n_data_lines} hourly records)")
+
+ return output_path
+
+
+def read_epw(path: str | Path) -> tuple:
+ """
+ Read EnergyPlus Weather (EPW) file and return weather data with metadata.
+
+ EPW files have 8 header lines followed by hourly weather data.
+ Uses pure Python parser (no pandas/scipy dependencies).
+
+ Args:
+ path: Path to EPW file (string or Path)
+
+ Returns:
+ Tuple of (data, metadata_dict):
+ - data: DataFrame-like object with datetime index and weather columns:
+ - temp_air: Dry bulb temperature (°C)
+ - relative_humidity: Relative humidity (%)
+ - atmospheric_pressure: Atmospheric pressure (Pa)
+ - ghi: Global horizontal irradiance (W/m²)
+ - dni: Direct normal irradiance (W/m²)
+ - dhi: Diffuse horizontal irradiance (W/m²)
+ - wind_speed: Wind speed (m/s)
+ - wind_direction: Wind direction (degrees)
+ - metadata_dict: Dictionary with keys:
+ - city: Location city name
+ - latitude: Latitude (degrees)
+ - longitude: Longitude (degrees)
+ - elevation: Elevation (m)
+ - tz_offset: Timezone offset (hours)
+
+ Raises:
+ FileNotFoundError: If EPW file doesn't exist
+ ValueError: If EPW file is malformed
+ """
+ path = Path(path)
+ if not path.exists():
+ raise FileNotFoundError(f"EPW file not found: {path}")
+
+ return _read_epw_pure_python(path)
diff --git a/pysrc/solweig/loaders.py b/pysrc/solweig/loaders.py
new file mode 100644
index 0000000..e079407
--- /dev/null
+++ b/pysrc/solweig/loaders.py
@@ -0,0 +1,257 @@
+"""Configuration and parameter loading from JSON files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .utils import dict_to_namespace
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+
+def load_params(params_json_path: str | Path | None = None) -> SimpleNamespace:
+ """
+ Load SOLWEIG parameters from a JSON file.
+
+ Returns a mutable SimpleNamespace with all UMEP-standard parameters:
+ land cover properties, wall materials, Tmrt settings, PET settings,
+ tree settings, and posture geometry.
+
+ Args:
+ params_json_path: Path to the parameters JSON file.
+ If None (default), loads the bundled default_materials.json
+ with all UMEP-standard values.
+
+ Returns:
+ SimpleNamespace object with nested parameter values accessible via attributes.
+ The namespace is mutable — override individual values as needed.
+
+ Examples:
+ Load bundled defaults:
+
+ >>> params = load_params()
+ >>> params.Tmrt_params.Value.absK # 0.7
+ >>> params.Albedo.Effective.Value.Dark_asphalt # 0.18
+
+ Override a specific value:
+
+ >>> params = load_params()
+ >>> params.Ts_deg.Value.Walls = 0.50 # Change wall TgK
+ """
+ if params_json_path is None:
+ # Use bundled default parameters (full UMEP-format JSON with all sections)
+ params_path = Path(__file__).parent / "data" / "default_materials.json"
+ else:
+ params_path = Path(params_json_path)
+
+ if not params_path.exists():
+ raise FileNotFoundError(f"Parameters file not found: {params_path}")
+
+ with open(params_path) as f:
+ params_dict = json.load(f)
+
+ result = dict_to_namespace(params_dict)
+ assert isinstance(result, SimpleNamespace)
+ return result
+
+
+def load_physics(physics_json_path: str | Path | None = None) -> SimpleNamespace:
+ """
+ Load physics parameters (site-independent scientific constants).
+
+ Physics parameters include:
+ - Tree_settings: Vegetation transmissivity, seasonal dates, trunk ratio
+ - Posture: Human posture geometry (Standing/Sitting projected area fractions)
+
+ These are universal constants that rarely need customization.
+
+ Args:
+ physics_json_path: Path to a custom physics JSON file.
+ If None (default), loads bundled physics_defaults.json with standard values.
+
+ Returns:
+ SimpleNamespace object with physics parameters accessible via attributes.
+
+ Examples:
+ Load bundled defaults:
+
+ >>> physics = load_physics() # Uses bundled physics_defaults.json
+ >>> physics.Tree_settings.Value.Transmissivity # 0.03
+ >>> physics.Posture.Standing.Value.Fside # 0.22
+
+ Load custom physics (e.g., different tree transmissivity):
+
+ >>> physics = load_physics("custom_trees.json")
+ """
+ if physics_json_path is None:
+ # Use bundled physics defaults
+ physics_path = Path(__file__).parent / "data" / "physics_defaults.json"
+ else:
+ physics_path = Path(physics_json_path)
+
+ if not physics_path.exists():
+ raise FileNotFoundError(f"Physics parameters file not found: {physics_path}")
+
+ with open(physics_path) as f:
+ physics_dict = json.load(f)
+
+ result = dict_to_namespace(physics_dict)
+ assert isinstance(result, SimpleNamespace)
+ return result
+
+
+def load_materials(materials_json_path: str | Path) -> SimpleNamespace:
+ """
+ Load material properties (site-specific landcover parameters).
+
+ Material properties include per-landcover-class values for:
+ - Names: Landcover class names (e.g., "Dark_asphalt", "Grass_unmanaged")
+ - Code: Landcover class IDs
+ - Albedo: Surface albedo per class
+ - Emissivity: Surface emissivity per class
+ - TmaxLST, Ts_deg, Tstart: Ground temperature model parameters per class
+ - Specific_heat, Thermal_conductivity, Density, Wall_thickness: Wall thermal properties
+
+ These are site-specific and require a landcover grid (land_cover input).
+
+ Args:
+ materials_json_path: Path to a materials JSON file.
+ This file must contain landcover-specific property definitions.
+
+ Returns:
+ SimpleNamespace object with material parameters accessible via attributes.
+
+ Examples:
+ Load site-specific materials:
+
+ >>> materials = load_materials("site_materials.json")
+ >>> materials.Albedo.Effective.Value.Dark_asphalt # 0.18
+ >>> materials.Emissivity.Value.Grass_unmanaged # 0.94
+
+ Notes:
+ Materials are ONLY used when a landcover grid is provided to SurfaceData.
+ If no landcover grid, uniform default properties are used.
+ """
+ materials_path = Path(materials_json_path)
+
+ if not materials_path.exists():
+ raise FileNotFoundError(f"Materials file not found: {materials_path}")
+
+ with open(materials_path) as f:
+ materials_dict = json.load(f)
+
+ result = dict_to_namespace(materials_dict)
+ assert isinstance(result, SimpleNamespace)
+ return result
+
+
+def get_lc_properties_from_params(
+ land_cover: NDArray[np.integer],
+ params: SimpleNamespace,
+ shape: tuple[int, int],
+) -> tuple[
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+]:
+ """
+ Derive surface properties from land cover grid using loaded params.
+
+ This mirrors the logic in configs.py TgMaps class.
+
+ Args:
+ land_cover: Land cover classification grid (UMEP standard IDs).
+ params: Loaded parameters from JSON file.
+ shape: Output grid shape (rows, cols).
+
+ Returns:
+ Tuple of (albedo_grid, emissivity_grid, tgk_grid, tstart_grid, tmaxlst_grid).
+ """
+ rows, cols = shape
+ alb_grid = np.full((rows, cols), 0.15, dtype=np.float32)
+ emis_grid = np.full((rows, cols), 0.95, dtype=np.float32)
+ tgk_grid = np.full((rows, cols), 0.37, dtype=np.float32)
+ tstart_grid = np.full((rows, cols), -3.41, dtype=np.float32)
+ tmaxlst_grid = np.full((rows, cols), 15.0, dtype=np.float32)
+
+ # Get unique land cover IDs and filter to valid ones (0-7)
+ lc = np.copy(land_cover)
+ lc[lc >= 100] = 2 # Treat wall codes as buildings
+ unique_ids = np.unique(lc)
+ valid_ids = unique_ids[unique_ids <= 7].astype(int)
+
+ # Build mappings from land cover ID to name to parameter values
+ for lc_id in valid_ids:
+ # Get land cover name from ID (e.g., 0 -> "Cobble_stone_2014a")
+ name = getattr(params.Names.Value, str(lc_id), None)
+ if name is None:
+ continue
+
+ # Get parameter values for this land cover type
+ albedo = getattr(params.Albedo.Effective.Value, name, 0.15)
+ emissivity = getattr(params.Emissivity.Value, name, 0.95)
+ tgk = getattr(params.Ts_deg.Value, name, 0.37)
+ tstart = getattr(params.Tstart.Value, name, -3.41)
+ tmaxlst = getattr(params.TmaxLST.Value, name, 15.0)
+
+ # Apply to grid where land cover matches
+ mask = lc == lc_id
+ if np.any(mask):
+ alb_grid[mask] = albedo
+ emis_grid[mask] = emissivity
+ tgk_grid[mask] = tgk
+ tstart_grid[mask] = tstart
+ tmaxlst_grid[mask] = tmaxlst
+
+ return alb_grid, emis_grid, tgk_grid, tstart_grid, tmaxlst_grid
+
+
+# Map user-facing wall material names to JSON keys in default_materials.json
+WALL_MATERIAL_MAP: dict[str, str] = {
+ "brick": "Brick_wall",
+ "concrete": "Concrete_wall",
+ "wood": "Wood_wall",
+ "cobblestone": "Walls",
+}
+
+
+def resolve_wall_params(
+ wall_material: str,
+ materials: SimpleNamespace | None = None,
+) -> tuple[float, float, float]:
+ """Resolve wall material name to (tgk_wall, tstart_wall, tmaxlst_wall).
+
+ Args:
+ wall_material: Material name (case-insensitive).
+ One of: "brick", "concrete", "wood", "cobblestone".
+ materials: Loaded materials namespace. If None, loads bundled defaults.
+
+ Returns:
+ Tuple of (tgk_wall, tstart_wall, tmaxlst_wall) floats.
+
+ Raises:
+ ValueError: If wall_material is not a recognized material name.
+ """
+ key = wall_material.lower()
+ if key not in WALL_MATERIAL_MAP:
+ valid = ", ".join(sorted(WALL_MATERIAL_MAP))
+ msg = f"Unknown wall material {wall_material!r}. Valid options: {valid}"
+ raise ValueError(msg)
+
+ json_name = WALL_MATERIAL_MAP[key]
+
+ if materials is None:
+ materials = load_params()
+
+ tgk = float(getattr(materials.Ts_deg.Value, json_name))
+ tstart = float(getattr(materials.Tstart.Value, json_name))
+ tmaxlst = float(getattr(materials.TmaxLST.Value, json_name))
+ return tgk, tstart, tmaxlst
diff --git a/pysrc/solweig/metadata.py b/pysrc/solweig/metadata.py
new file mode 100644
index 0000000..3d610dd
--- /dev/null
+++ b/pysrc/solweig/metadata.py
@@ -0,0 +1,137 @@
+"""Run metadata and provenance tracking."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime as dt
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+ from .models import HumanParams, Location, SurfaceData, Weather
+
+
+def create_run_metadata(
+ surface: SurfaceData,
+ location: Location,
+ weather_series: list[Weather],
+ human: HumanParams | None,
+ physics: SimpleNamespace | None,
+ materials: SimpleNamespace | None,
+ use_anisotropic_sky: bool,
+ conifer: bool,
+ output_dir: str | Path,
+ outputs: list[str] | None,
+) -> dict:
+ """
+ Create run metadata dictionary for provenance tracking.
+
+ Args:
+ surface: Surface data used in calculation.
+ location: Location parameters.
+ weather_series: List of Weather objects.
+ human: Human parameters (or None for defaults).
+ physics: Physics parameters (or None for defaults).
+ materials: Materials parameters (or None).
+ use_anisotropic_sky: Whether anisotropic sky model was used.
+ conifer: Whether conifer mode was used.
+ output_dir: Output directory path.
+ outputs: List of output variables saved.
+
+ Returns:
+ Dictionary containing run metadata.
+ """
+ from .utils import namespace_to_dict
+
+ metadata = {
+ "solweig_version": "0.0.1a1",
+ "run_timestamp": dt.now().isoformat(),
+ "grid": {
+ "rows": surface.shape[0],
+ "cols": surface.shape[1],
+ "pixel_size": surface.pixel_size,
+ "crs": surface.crs,
+ },
+ "location": {
+ "latitude": location.latitude,
+ "longitude": location.longitude,
+ "utc_offset": location.utc_offset,
+ },
+ "timeseries": {
+ "start": weather_series[0].datetime.isoformat(),
+ "end": weather_series[-1].datetime.isoformat(),
+ "timesteps": len(weather_series),
+ },
+ "parameters": {
+ "use_anisotropic_sky": use_anisotropic_sky,
+ "conifer": conifer,
+ },
+ "outputs": {
+ "directory": str(output_dir),
+ "variables": outputs or ["tmrt"],
+ },
+ }
+
+ # Add optional parameter info
+ if human is not None:
+ metadata["human"] = {
+ "abs_k": human.abs_k,
+ "abs_l": human.abs_l,
+ "posture": human.posture,
+ }
+
+ if physics is not None:
+ physics_info = {}
+ try:
+ physics_info["full_params"] = namespace_to_dict(physics)
+ except Exception:
+ physics_info["note"] = "Physics parameters provided but not serializable"
+ metadata["physics"] = physics_info
+
+ if materials is not None:
+ materials_info = {}
+ try:
+ materials_info["full_params"] = namespace_to_dict(materials)
+ except Exception:
+ materials_info["note"] = "Materials parameters provided but not serializable"
+ metadata["materials"] = materials_info
+
+ return metadata
+
+
+def save_run_metadata(metadata: dict, output_dir: str | Path, filename: str = "run_metadata.json") -> Path:
+ """
+ Save run metadata to JSON file.
+
+ Args:
+ metadata: Metadata dictionary from create_run_metadata().
+ output_dir: Output directory.
+ filename: Filename for metadata JSON (default: run_metadata.json).
+
+ Returns:
+ Path to saved metadata file.
+ """
+ output_path = Path(output_dir)
+ metadata_path = output_path / filename
+
+ with open(metadata_path, "w") as f:
+ json.dump(metadata, f, indent=2)
+
+ return metadata_path
+
+
+def load_run_metadata(metadata_path: str | Path) -> dict:
+ """
+ Load run metadata from JSON file.
+
+ Args:
+ metadata_path: Path to metadata JSON file.
+
+ Returns:
+ Metadata dictionary.
+ """
+ with open(metadata_path) as f:
+ metadata = json.load(f)
+
+ return metadata
diff --git a/pysrc/solweig/models/__init__.py b/pysrc/solweig/models/__init__.py
new file mode 100644
index 0000000..1f5194a
--- /dev/null
+++ b/pysrc/solweig/models/__init__.py
@@ -0,0 +1,37 @@
+"""Data models for SOLWEIG calculations.
+
+This package contains all data model classes organized by domain:
+- state: ThermalState, TileSpec
+- surface: SurfaceData
+- weather: Location, Weather
+- precomputed: SvfArrays, ShadowArrays, PrecomputedData
+- config: ModelConfig, HumanParams
+- results: SolweigResult
+"""
+
+from .config import HumanParams, ModelConfig
+from .precomputed import PrecomputedData, ShadowArrays, SvfArrays
+from .results import SolweigResult
+from .state import ThermalState, TileSpec
+from .surface import SurfaceData
+from .weather import Location, Weather
+
+__all__ = [
+ # State management
+ "ThermalState",
+ "TileSpec",
+ # Surface data
+ "SurfaceData",
+ # Weather and location
+ "Location",
+ "Weather",
+ # Precomputed data
+ "SvfArrays",
+ "ShadowArrays",
+ "PrecomputedData",
+ # Configuration
+ "ModelConfig",
+ "HumanParams",
+ # Results
+ "SolweigResult",
+]
diff --git a/pysrc/solweig/models/config.py b/pysrc/solweig/models/config.py
new file mode 100644
index 0000000..6dffef3
--- /dev/null
+++ b/pysrc/solweig/models/config.py
@@ -0,0 +1,240 @@
+"""Model configuration classes."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+ pass
+
+
+@dataclass
+class ModelConfig:
+ """
+ Model configuration for SOLWEIG calculations.
+
+ Groups all computational settings in one typed object.
+ Pure configuration - no paths or data.
+
+ Attributes:
+ use_anisotropic_sky: Use anisotropic sky model. Default False.
+ human: Human body parameters for Tmrt calculations.
+ material_params: Optional material properties from JSON file.
+ outputs: Which outputs to save in timeseries calculations.
+ max_shadow_distance_m: Maximum shadow reach in meters. Default 500.0.
+ Caps shadow ray computation distance and serves as tile overlap buffer
+ for automatic tiled processing of large rasters. At low sun angles (3°),
+ a 26m building casts a 500m shadow — taller buildings are capped.
+
+ Note:
+ UTCI and PET are now computed via post-processing functions (compute_utci, compute_pet)
+ rather than during the main calculation loop for better performance.
+
+ Examples:
+ Basic usage with defaults:
+
+ >>> config = ModelConfig.defaults()
+ >>> config.save("my_config.json")
+
+ Custom configuration:
+
+ >>> config = ModelConfig(
+ ... use_anisotropic_sky=True,
+ ... human=HumanParams(abs_k=0.7, posture="standing"),
+ ... )
+
+ Load from legacy JSON:
+
+ >>> config = ModelConfig.from_json("parametersforsolweig.json")
+ """
+
+ use_anisotropic_sky: bool = False
+ human: HumanParams | None = None
+ material_params: SimpleNamespace | None = None
+ outputs: list[str] = field(default_factory=lambda: ["tmrt"])
+ physics: SimpleNamespace | None = None
+ materials: SimpleNamespace | None = None
+ max_shadow_distance_m: float = 500.0
+
+ def __post_init__(self):
+ """Initialize default HumanParams if not provided."""
+ # Defer import to avoid forward reference issues
+ if self.human is None:
+ # HumanParams is defined later in this module
+ pass # Will be instantiated when HumanParams is available
+
+ @classmethod
+ def defaults(cls) -> ModelConfig:
+ """
+ Standard configuration for most users.
+
+ Returns:
+ ModelConfig with recommended defaults:
+ - Anisotropic sky enabled
+ """
+ return cls(
+ use_anisotropic_sky=True,
+ )
+
+ @classmethod
+ def from_json(cls, path: str | Path) -> ModelConfig:
+ """
+ Load configuration from legacy JSON parameters file.
+
+ Args:
+ path: Path to parametersforsolweig.json
+
+ Returns:
+ ModelConfig with settings extracted from JSON
+
+ Example:
+ >>> config = ModelConfig.from_json("parametersforsolweig.json")
+ >>> config.human.abs_k # From Tmrt_params
+ 0.7
+ """
+ from ..loaders import load_params
+
+ params = load_params(path)
+
+ # Extract human parameters from JSON
+ human = HumanParams()
+ if hasattr(params, "Tmrt_params"):
+ human.abs_k = getattr(params.Tmrt_params, "absK", 0.7)
+ human.abs_l = getattr(params.Tmrt_params, "absL", 0.97)
+ posture_str = getattr(params.Tmrt_params, "posture", "Standing")
+ human.posture = posture_str.lower()
+
+ if hasattr(params, "PET_settings"):
+ human.age = getattr(params.PET_settings, "Age", 35)
+ human.weight = getattr(params.PET_settings, "Weight", 75.0)
+ human.height = getattr(params.PET_settings, "Height", 1.75)
+ human.sex = getattr(params.PET_settings, "Sex", 1)
+ human.activity = getattr(params.PET_settings, "Activity", 80.0)
+ human.clothing = getattr(params.PET_settings, "clo", 0.9)
+
+ return cls(
+ human=human,
+ material_params=params,
+ )
+
+ def save(self, path: str | Path):
+ """
+ Save configuration to JSON file.
+
+ Args:
+ path: Output path for JSON file
+
+ Example:
+ >>> config = ModelConfig.defaults()
+ >>> config.save("my_settings.json")
+ """
+ path = Path(path)
+ path.parent.mkdir(parents=True, exist_ok=True)
+
+ # Serialize to dict
+ data = {
+ "use_anisotropic_sky": self.use_anisotropic_sky,
+ "max_shadow_distance_m": self.max_shadow_distance_m,
+ "outputs": self.outputs,
+ "human": {
+ "posture": self.human.posture,
+ "abs_k": self.human.abs_k,
+ "abs_l": self.human.abs_l,
+ "age": self.human.age,
+ "weight": self.human.weight,
+ "height": self.human.height,
+ "sex": self.human.sex,
+ "activity": self.human.activity,
+ "clothing": self.human.clothing,
+ }
+ if self.human
+ else None,
+ }
+
+ with open(path, "w") as f:
+ json.dump(data, f, indent=2)
+
+ logger.info(f"Saved configuration to {path}")
+
+ @classmethod
+ def load(cls, path: str | Path) -> ModelConfig:
+ """
+ Load configuration from JSON file.
+
+ Args:
+ path: Path to JSON configuration file
+
+ Returns:
+ ModelConfig loaded from file
+
+ Example:
+ >>> config = ModelConfig.load("my_settings.json")
+ >>> results = calculate_timeseries(surface, weather, config=config)
+ """
+ path = Path(path)
+
+ with open(path) as f:
+ data = json.load(f)
+
+ # Deserialize human params
+ human = None
+ if data.get("human"):
+ human = HumanParams(**data["human"])
+
+ return cls(
+ use_anisotropic_sky=data.get("use_anisotropic_sky", False),
+ max_shadow_distance_m=data.get("max_shadow_distance_m", 500.0),
+ human=human,
+ outputs=data.get("outputs", ["tmrt"]),
+ )
+
+
+@dataclass
+class HumanParams:
+ """
+ Human body parameters for thermal comfort calculations.
+
+ These parameters affect how radiation is absorbed by a person.
+ Default values represent a standard reference person.
+
+ Attributes:
+ posture: Body posture ("standing" or "sitting"). Default "standing".
+ abs_k: Shortwave absorption coefficient. Default 0.7.
+ abs_l: Longwave absorption coefficient. Default 0.97.
+
+ PET-specific parameters (used by compute_pet() post-processing):
+ age: Age in years. Default 35.
+ weight: Body weight in kg. Default 75.
+ height: Body height in meters. Default 1.75.
+ sex: Biological sex (1=male, 2=female). Default 1.
+ activity: Metabolic activity in W. Default 80.
+ clothing: Clothing insulation in clo. Default 0.9.
+ """
+
+ posture: str = "standing"
+ abs_k: float = 0.7
+ abs_l: float = 0.97
+
+ # PET-specific (optional)
+ age: int = 35
+ weight: float = 75.0
+ height: float = 1.75
+ sex: int = 1
+ activity: float = 80.0
+ clothing: float = 0.9
+
+ def __post_init__(self):
+ valid_postures = ("standing", "sitting")
+ if self.posture not in valid_postures:
+ raise ValueError(f"Posture must be one of {valid_postures}, got {self.posture}")
+ if not 0 < self.abs_k <= 1:
+ raise ValueError(f"abs_k must be in (0, 1], got {self.abs_k}")
+ if not 0 < self.abs_l <= 1:
+ raise ValueError(f"abs_l must be in (0, 1], got {self.abs_l}")
diff --git a/pysrc/solweig/models/precomputed.py b/pysrc/solweig/models/precomputed.py
new file mode 100644
index 0000000..88a7b25
--- /dev/null
+++ b/pysrc/solweig/models/precomputed.py
@@ -0,0 +1,681 @@
+"""Precomputed data models (SVF, shadow matrices)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+from ..cache import CacheMetadata
+from ..solweig_logging import get_logger
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class SvfArrays:
+ """
+ Pre-computed Sky View Factor arrays.
+
+ Use this when you have already computed SVF and want to skip
+ re-computation. Can be loaded from SOLWEIG svfs.zip format.
+
+ Attributes:
+ svf: Total sky view factor (0-1).
+ svf_north, svf_east, svf_south, svf_west: Directional SVF components.
+ svf_veg: Vegetation SVF (set to ones if no vegetation).
+ svf_veg_north, svf_veg_east, svf_veg_south, svf_veg_west: Directional veg SVF.
+ svf_aveg: Vegetation blocking building shadow.
+ svf_aveg_north, svf_aveg_east, svf_aveg_south, svf_aveg_west: Directional.
+
+ Memory note:
+ All arrays are stored as float32. For a 768x768 grid with all 15 arrays,
+ total memory is approximately 35 MB.
+ """
+
+ svf: NDArray[np.floating]
+ svf_north: NDArray[np.floating]
+ svf_east: NDArray[np.floating]
+ svf_south: NDArray[np.floating]
+ svf_west: NDArray[np.floating]
+ svf_veg: NDArray[np.floating]
+ svf_veg_north: NDArray[np.floating]
+ svf_veg_east: NDArray[np.floating]
+ svf_veg_south: NDArray[np.floating]
+ svf_veg_west: NDArray[np.floating]
+ svf_aveg: NDArray[np.floating]
+ svf_aveg_north: NDArray[np.floating]
+ svf_aveg_east: NDArray[np.floating]
+ svf_aveg_south: NDArray[np.floating]
+ svf_aveg_west: NDArray[np.floating]
+
+ def __post_init__(self):
+ # Ensure all arrays are float32 for memory efficiency
+ # Note: np.asarray preserves memmap arrays (doesn't copy unless dtype changes)
+ def ensure_f32(arr):
+ if isinstance(arr, np.memmap):
+ # Preserve memmap - only convert dtype if needed
+ if arr.dtype != np.float32:
+ # This would load into memory - warn user
+ logger.warning("Memmap array has wrong dtype, loading into memory")
+ return np.asarray(arr, dtype=np.float32)
+ return arr
+ return np.asarray(arr, dtype=np.float32)
+
+ self.svf = ensure_f32(self.svf)
+ self.svf_north = ensure_f32(self.svf_north)
+ self.svf_east = ensure_f32(self.svf_east)
+ self.svf_south = ensure_f32(self.svf_south)
+ self.svf_west = ensure_f32(self.svf_west)
+ self.svf_veg = ensure_f32(self.svf_veg)
+ self.svf_veg_north = ensure_f32(self.svf_veg_north)
+ self.svf_veg_east = ensure_f32(self.svf_veg_east)
+ self.svf_veg_south = ensure_f32(self.svf_veg_south)
+ self.svf_veg_west = ensure_f32(self.svf_veg_west)
+ self.svf_aveg = ensure_f32(self.svf_aveg)
+ self.svf_aveg_north = ensure_f32(self.svf_aveg_north)
+ self.svf_aveg_east = ensure_f32(self.svf_aveg_east)
+ self.svf_aveg_south = ensure_f32(self.svf_aveg_south)
+ self.svf_aveg_west = ensure_f32(self.svf_aveg_west)
+
+ @property
+ def svfalfa(self) -> NDArray[np.floating]:
+ """Compute SVF alpha (angle) from SVF values. Computed on-demand."""
+ tmp = self.svf + self.svf_veg - 1.0
+ tmp = np.clip(tmp, 0.0, 1.0)
+ eps = np.finfo(np.float32).tiny
+ safe_term = np.clip(1.0 - tmp, eps, 1.0)
+ return np.arcsin(np.exp(np.log(safe_term) / 2.0))
+
+ @property
+ def svfbuveg(self) -> NDArray[np.floating]:
+ """Combined building + vegetation SVF. Computed on-demand."""
+ return np.clip(self.svf + self.svf_veg - 1.0, 0.0, 1.0)
+
+ def crop(self, r0: int, r1: int, c0: int, c1: int) -> SvfArrays:
+ """Crop all SVF arrays to [r0:r1, c0:c1]."""
+ return SvfArrays(
+ svf=self.svf[r0:r1, c0:c1].copy(),
+ svf_north=self.svf_north[r0:r1, c0:c1].copy(),
+ svf_east=self.svf_east[r0:r1, c0:c1].copy(),
+ svf_south=self.svf_south[r0:r1, c0:c1].copy(),
+ svf_west=self.svf_west[r0:r1, c0:c1].copy(),
+ svf_veg=self.svf_veg[r0:r1, c0:c1].copy(),
+ svf_veg_north=self.svf_veg_north[r0:r1, c0:c1].copy(),
+ svf_veg_east=self.svf_veg_east[r0:r1, c0:c1].copy(),
+ svf_veg_south=self.svf_veg_south[r0:r1, c0:c1].copy(),
+ svf_veg_west=self.svf_veg_west[r0:r1, c0:c1].copy(),
+ svf_aveg=self.svf_aveg[r0:r1, c0:c1].copy(),
+ svf_aveg_north=self.svf_aveg_north[r0:r1, c0:c1].copy(),
+ svf_aveg_east=self.svf_aveg_east[r0:r1, c0:c1].copy(),
+ svf_aveg_south=self.svf_aveg_south[r0:r1, c0:c1].copy(),
+ svf_aveg_west=self.svf_aveg_west[r0:r1, c0:c1].copy(),
+ )
+
+ @classmethod
+ def from_bundle(cls, bundle) -> SvfArrays:
+ """
+ Create SvfArrays from a SvfBundle (computation result).
+
+ This enables caching fresh-computed SVF back to surface.svf for reuse.
+
+ Args:
+ bundle: SvfBundle from resolve_svf() or skyview.calculate_svf()
+
+ Returns:
+ SvfArrays instance suitable for caching on SurfaceData.svf
+ """
+ return cls(
+ svf=bundle.svf,
+ svf_north=bundle.svf_directional.north,
+ svf_east=bundle.svf_directional.east,
+ svf_south=bundle.svf_directional.south,
+ svf_west=bundle.svf_directional.west,
+ svf_veg=bundle.svf_veg,
+ svf_veg_north=bundle.svf_veg_directional.north,
+ svf_veg_east=bundle.svf_veg_directional.east,
+ svf_veg_south=bundle.svf_veg_directional.south,
+ svf_veg_west=bundle.svf_veg_directional.west,
+ svf_aveg=bundle.svf_aveg,
+ svf_aveg_north=bundle.svf_aveg_directional.north,
+ svf_aveg_east=bundle.svf_aveg_directional.east,
+ svf_aveg_south=bundle.svf_aveg_directional.south,
+ svf_aveg_west=bundle.svf_aveg_directional.west,
+ )
+
+ @classmethod
+ def from_zip(cls, zip_path: str | Path, use_vegetation: bool = True) -> SvfArrays:
+ """
+ Load SVF arrays from SOLWEIG svfs.zip format.
+
+ Args:
+ zip_path: Path to svfs.zip file.
+ use_vegetation: Whether to load vegetation SVF arrays. Default True.
+
+ Returns:
+ SvfArrays instance with loaded data.
+
+ Memory note:
+ Files are extracted temporarily and loaded as float32 arrays.
+ The zip file contains GeoTIFF rasters.
+ """
+ import tempfile
+ import zipfile
+
+ from .. import io as common
+
+ zip_path = Path(zip_path)
+ if not zip_path.exists():
+ raise FileNotFoundError(f"SVF zip file not found: {zip_path}")
+
+ with tempfile.TemporaryDirectory() as tmpdir:
+ with zipfile.ZipFile(str(zip_path), "r") as zf:
+ zf.extractall(tmpdir)
+
+ tmppath = Path(tmpdir)
+
+ def load(filename: str) -> NDArray[np.floating]:
+ filepath = tmppath / filename
+ if not filepath.exists():
+ raise FileNotFoundError(f"Expected SVF file not found in zip: {filename}")
+ data, _, _, _ = common.load_raster(str(filepath), coerce_f64_to_f32=True)
+ return data
+
+ # Load basic SVF arrays
+ svf = load("svf.tif")
+ svf_n = load("svfN.tif")
+ svf_e = load("svfE.tif")
+ svf_s = load("svfS.tif")
+ svf_w = load("svfW.tif")
+
+ # Load vegetation arrays or create defaults
+ if use_vegetation:
+ svf_veg = load("svfveg.tif")
+ svf_veg_n = load("svfNveg.tif")
+ svf_veg_e = load("svfEveg.tif")
+ svf_veg_s = load("svfSveg.tif")
+ svf_veg_w = load("svfWveg.tif")
+ svf_aveg = load("svfaveg.tif")
+ svf_aveg_n = load("svfNaveg.tif")
+ svf_aveg_e = load("svfEaveg.tif")
+ svf_aveg_s = load("svfSaveg.tif")
+ svf_aveg_w = load("svfWaveg.tif")
+ else:
+ ones = np.ones_like(svf)
+ svf_veg = ones
+ svf_veg_n = ones
+ svf_veg_e = ones
+ svf_veg_s = ones
+ svf_veg_w = ones
+ svf_aveg = ones
+ svf_aveg_n = ones
+ svf_aveg_e = ones
+ svf_aveg_s = ones
+ svf_aveg_w = ones
+
+ return cls(
+ svf=svf,
+ svf_north=svf_n,
+ svf_east=svf_e,
+ svf_south=svf_s,
+ svf_west=svf_w,
+ svf_veg=svf_veg,
+ svf_veg_north=svf_veg_n,
+ svf_veg_east=svf_veg_e,
+ svf_veg_south=svf_veg_s,
+ svf_veg_west=svf_veg_w,
+ svf_aveg=svf_aveg,
+ svf_aveg_north=svf_aveg_n,
+ svf_aveg_east=svf_aveg_e,
+ svf_aveg_south=svf_aveg_s,
+ svf_aveg_west=svf_aveg_w,
+ )
+
+ def to_memmap(self, directory: str | Path, metadata: CacheMetadata | None = None) -> Path:
+ """
+ Save SVF arrays as memory-mapped .npy files for efficient large-raster processing.
+
+ This enables processing of 10k×10k+ rasters without loading all SVF data into RAM.
+ The OS handles paging, loading only the needed regions into physical memory.
+
+ Args:
+ directory: Directory to save memmap files. Created if doesn't exist.
+ metadata: Optional cache metadata for validation on reload.
+ When provided, enables automatic cache invalidation if inputs change.
+
+ Returns:
+ Path to the directory containing memmap files.
+
+ Memory note:
+ For a 10k×10k grid with 15 arrays: ~6 GB on disk, but only accessed
+ regions are loaded into RAM. Typical usage loads <100 MB.
+
+ Example:
+ svf = SvfArrays.from_zip("svfs.zip")
+ svf.to_memmap("cache/svf_memmap")
+ # Later:
+ svf = SvfArrays.from_memmap("cache/svf_memmap")
+ """
+ directory = Path(directory)
+ directory.mkdir(parents=True, exist_ok=True)
+
+ # Save each array as .npy file
+ array_names = [
+ "svf",
+ "svf_north",
+ "svf_east",
+ "svf_south",
+ "svf_west",
+ "svf_veg",
+ "svf_veg_north",
+ "svf_veg_east",
+ "svf_veg_south",
+ "svf_veg_west",
+ "svf_aveg",
+ "svf_aveg_north",
+ "svf_aveg_east",
+ "svf_aveg_south",
+ "svf_aveg_west",
+ ]
+
+ for name in array_names:
+ arr = getattr(self, name)
+ np.save(directory / f"{name}.npy", arr)
+
+ # Save metadata for cache validation
+ if metadata is not None:
+ metadata.save(directory)
+
+ logger.info(f"Saved SVF memmap cache to {directory} ({len(array_names)} arrays)")
+ return directory
+
+ @classmethod
+ def from_memmap(cls, directory: str | Path, mode: Literal["r", "r+", "c"] = "r") -> SvfArrays:
+ """
+ Load SVF arrays as memory-mapped files for efficient large-raster processing.
+
+ Memory-mapped arrays are not loaded into RAM until accessed. The OS handles
+ paging, making this suitable for rasters larger than available RAM.
+
+ Args:
+ directory: Directory containing memmap .npy files (from to_memmap()).
+ mode: Memory-map mode. Default "r" (read-only).
+ - "r": Read-only (safest, allows OS caching)
+ - "r+": Read-write (modifications saved to disk)
+ - "c": Copy-on-write (modifications not saved)
+
+ Returns:
+ SvfArrays with memory-mapped backing.
+
+ Memory note:
+ Only accessed regions are loaded into physical RAM. For tiled processing,
+ this dramatically reduces memory usage compared to loading full arrays.
+
+ Example:
+ svf = SvfArrays.from_memmap("cache/svf_memmap")
+ # Arrays are loaded on-demand as tiles access them
+ """
+ directory = Path(directory)
+ if not directory.exists():
+ raise FileNotFoundError(f"SVF memmap directory not found: {directory}")
+
+ def load_memmap(name: str) -> np.ndarray:
+ path = directory / f"{name}.npy"
+ if not path.exists():
+ raise FileNotFoundError(f"SVF memmap file not found: {path}")
+ return np.load(path, mmap_mode=mode)
+
+ return cls(
+ svf=load_memmap("svf"),
+ svf_north=load_memmap("svf_north"),
+ svf_east=load_memmap("svf_east"),
+ svf_south=load_memmap("svf_south"),
+ svf_west=load_memmap("svf_west"),
+ svf_veg=load_memmap("svf_veg"),
+ svf_veg_north=load_memmap("svf_veg_north"),
+ svf_veg_east=load_memmap("svf_veg_east"),
+ svf_veg_south=load_memmap("svf_veg_south"),
+ svf_veg_west=load_memmap("svf_veg_west"),
+ svf_aveg=load_memmap("svf_aveg"),
+ svf_aveg_north=load_memmap("svf_aveg_north"),
+ svf_aveg_east=load_memmap("svf_aveg_east"),
+ svf_aveg_south=load_memmap("svf_aveg_south"),
+ svf_aveg_west=load_memmap("svf_aveg_west"),
+ )
+
+
+def _unpack_bitpacked_to_float32(packed: NDArray[np.uint8], patch_count: int) -> NDArray[np.floating]:
+ """Unpack bitpacked shadow matrix to float32 (0.0 or 1.0).
+
+ Args:
+ packed: Bitpacked array, shape (rows, cols, n_pack) where n_pack = ceil(patch_count/8).
+ patch_count: Number of actual patches.
+
+ Returns:
+ Float32 array, shape (rows, cols, patch_count) with values 0.0 or 1.0.
+ """
+ rows, cols, _ = packed.shape
+ result = np.zeros((rows, cols, patch_count), dtype=np.float32)
+ for p in range(patch_count):
+ byte_idx = p >> 3
+ bit_mask = np.uint8(1 << (p & 7))
+ result[:, :, p] = ((packed[:, :, byte_idx] & bit_mask) != 0).astype(np.float32)
+ return result
+
+
+def _pack_u8_to_bitpacked(
+ u8_data: NDArray[np.uint8],
+) -> NDArray[np.uint8]:
+ """Pack u8 shadow matrix (0 or 255 per patch) to bitpacked format.
+
+ Args:
+ u8_data: Array shape (rows, cols, patch_count) with values 0 or 255.
+
+ Returns:
+ Bitpacked array, shape (rows, cols, n_pack) where n_pack = ceil(patch_count/8).
+ """
+ rows, cols, patch_count = u8_data.shape
+ n_pack = (patch_count + 7) // 8
+ packed = np.zeros((rows, cols, n_pack), dtype=np.uint8)
+ for p in range(patch_count):
+ byte_idx = p >> 3
+ bit_mask = np.uint8(1 << (p & 7))
+ packed[:, :, byte_idx] |= np.where(u8_data[:, :, p] >= 128, bit_mask, np.uint8(0))
+ return packed
+
+
+@dataclass
+class ShadowArrays:
+ """
+ Pre-computed anisotropic shadow matrices for sky patch calculations.
+
+ Internally stored as bitpacked uint8 arrays of shape (rows, cols, n_pack)
+ where n_pack = ceil(patch_count / 8). Each bit represents one sky patch
+ (1 = sky visible / shadowed value was 255, 0 = blocked / was 0).
+
+ Memory optimization:
+ Bitpacking stores 8 patches per byte instead of 1, reducing memory 7.6x.
+ For a 2500x2500 grid with 153 patches: 375 MB bitpacked vs 2.87 GB as uint8.
+ Converted to float32 only when accessed via properties (e.g. for diffsh).
+
+ Attributes:
+ _shmat_u8: Building shadow matrix (bitpacked uint8).
+ _vegshmat_u8: Vegetation shadow matrix (bitpacked uint8).
+ _vbshmat_u8: Combined veg+building shadow matrix (bitpacked uint8).
+ patch_count: Number of sky patches (145, 153, 306, or 612).
+ """
+
+ _shmat_u8: NDArray[np.uint8]
+ _vegshmat_u8: NDArray[np.uint8]
+ _vbshmat_u8: NDArray[np.uint8]
+ _n_patches: int = 153
+ patch_count: int = field(init=False)
+ # Cache for converted float32 arrays (allocated on first access)
+ _shmat_f32: NDArray[np.floating] | None = field(init=False, default=None, repr=False)
+ _vegshmat_f32: NDArray[np.floating] | None = field(init=False, default=None, repr=False)
+ _vbshmat_f32: NDArray[np.floating] | None = field(init=False, default=None, repr=False)
+
+ def __post_init__(self):
+ # Ensure uint8 dtype
+ if self._shmat_u8.dtype != np.uint8:
+ self._shmat_u8 = self._shmat_u8.astype(np.uint8)
+ if self._vegshmat_u8.dtype != np.uint8:
+ self._vegshmat_u8 = self._vegshmat_u8.astype(np.uint8)
+ if self._vbshmat_u8.dtype != np.uint8:
+ self._vbshmat_u8 = self._vbshmat_u8.astype(np.uint8)
+
+ self.patch_count = self._n_patches
+ # Initialize cache as None (lazy allocation)
+ self._shmat_f32 = None
+ self._vegshmat_f32 = None
+ self._vbshmat_f32 = None
+
+ @property
+ def shmat(self) -> NDArray[np.floating]:
+ """Building shadow matrix as float32 (0.0-1.0). Unpacked from bitpacked on demand."""
+ if self._shmat_f32 is None:
+ self._shmat_f32 = _unpack_bitpacked_to_float32(self._shmat_u8, self.patch_count)
+ return self._shmat_f32
+
+ @property
+ def vegshmat(self) -> NDArray[np.floating]:
+ """Vegetation shadow matrix as float32 (0.0-1.0). Unpacked from bitpacked on demand."""
+ if self._vegshmat_f32 is None:
+ self._vegshmat_f32 = _unpack_bitpacked_to_float32(self._vegshmat_u8, self.patch_count)
+ return self._vegshmat_f32
+
+ @property
+ def vbshmat(self) -> NDArray[np.floating]:
+ """Combined shadow matrix as float32 (0.0-1.0). Unpacked from bitpacked on demand."""
+ if self._vbshmat_f32 is None:
+ self._vbshmat_f32 = _unpack_bitpacked_to_float32(self._vbshmat_u8, self.patch_count)
+ return self._vbshmat_f32
+
+ @property
+ def patch_option(self) -> int:
+ """Patch option code (1=145, 2=153, 3=306, 4=612 patches)."""
+ patch_map = {145: 1, 153: 2, 306: 3, 612: 4}
+ return patch_map.get(self.patch_count, 2)
+
+ def diffsh(self, transmissivity: float = 0.03, use_vegetation: bool = True) -> NDArray[np.floating]:
+ """
+ Compute diffuse shadow matrix.
+
+ Args:
+ transmissivity: Vegetation transmissivity (default 0.03).
+ use_vegetation: Whether to account for vegetation.
+
+ Returns:
+ Diffuse shadow matrix as float32.
+ """
+ shmat = self.shmat
+ if use_vegetation:
+ vegshmat = self.vegshmat
+ return (shmat - (1 - vegshmat) * (1 - transmissivity)).astype(np.float32)
+ return shmat
+
+ def release_float32_cache(self) -> None:
+ """Release cached float32 shadow matrices to free memory.
+
+ The bitpacked originals remain available. Future property access will
+ re-unpack as needed.
+ """
+ self._shmat_f32 = None
+ self._vegshmat_f32 = None
+ self._vbshmat_f32 = None
+
+ def crop(self, r0: int, r1: int, c0: int, c1: int) -> ShadowArrays:
+ """Crop all shadow matrices to [r0:r1, c0:c1] (3D: rows, cols, n_pack)."""
+ return ShadowArrays(
+ _shmat_u8=self._shmat_u8[r0:r1, c0:c1, :].copy(),
+ _vegshmat_u8=self._vegshmat_u8[r0:r1, c0:c1, :].copy(),
+ _vbshmat_u8=self._vbshmat_u8[r0:r1, c0:c1, :].copy(),
+ _n_patches=self.patch_count,
+ )
+
+ @classmethod
+ def from_npz(cls, npz_path: str | Path) -> ShadowArrays:
+ """
+ Load shadow matrices from SOLWEIG shadowmats.npz format.
+
+ Handles both legacy u8-per-patch format and new bitpacked format.
+ Legacy files have shape[2] matching patch count (145/153/306/612).
+ New files include a 'patch_count' metadata key.
+ """
+ npz_path = Path(npz_path)
+ if not npz_path.exists():
+ raise FileNotFoundError(f"Shadow matrices file not found: {npz_path}")
+
+ data = np.load(str(npz_path))
+
+ shmat = data["shadowmat"]
+ vegshmat = data["vegshadowmat"]
+ vbshmat = data["vbshmat"]
+
+ # Detect format: new bitpacked files include 'patch_count' key
+ if "patch_count" in data:
+ patch_count = int(data["patch_count"])
+ # Data is already bitpacked uint8
+ return cls(
+ _shmat_u8=shmat.astype(np.uint8),
+ _vegshmat_u8=vegshmat.astype(np.uint8),
+ _vbshmat_u8=vbshmat.astype(np.uint8),
+ _n_patches=patch_count,
+ )
+
+ # Legacy format: shape[2] == patch_count, values are 0/255 uint8 or 0.0/1.0 float32
+ # Convert float32 → uint8 first if needed
+ if shmat.dtype != np.uint8:
+ shmat = (np.clip(shmat, 0, 1) * 255).astype(np.uint8)
+ if vegshmat.dtype != np.uint8:
+ vegshmat = (np.clip(vegshmat, 0, 1) * 255).astype(np.uint8)
+ if vbshmat.dtype != np.uint8:
+ vbshmat = (np.clip(vbshmat, 0, 1) * 255).astype(np.uint8)
+
+ patch_count = shmat.shape[2]
+
+ # Pack u8 → bitpacked
+ return cls(
+ _shmat_u8=_pack_u8_to_bitpacked(shmat),
+ _vegshmat_u8=_pack_u8_to_bitpacked(vegshmat),
+ _vbshmat_u8=_pack_u8_to_bitpacked(vbshmat),
+ _n_patches=patch_count,
+ )
+
+
+@dataclass
+class PrecomputedData:
+ """
+ Container for pre-computed preprocessing data to skip expensive calculations.
+
+ Use this to provide already-computed walls, SVF, and/or shadow matrices
+ to the calculate() function. This is useful when:
+ - Running multiple timesteps with the same geometry
+ - Using data generated by external tools
+ - Optimizing performance by pre-computing once
+
+ Attributes:
+ wall_height: Pre-computed wall height grid (meters). If None, computed on-the-fly.
+ wall_aspect: Pre-computed wall aspect grid (degrees, 0=N). If None, computed on-the-fly.
+ svf: Pre-computed SVF arrays. If None, SVF is computed on-the-fly.
+ shadow_matrices: Pre-computed anisotropic shadow matrices.
+ If None, isotropic sky model is used.
+
+ Example:
+ # Load all preprocessing
+ precomputed = PrecomputedData.load(
+ walls_dir="preprocessed/walls",
+ svf_dir="preprocessed/svf",
+ )
+
+ # Or create manually
+ svf = SvfArrays.from_zip("path/to/svfs.zip")
+ shadows = ShadowArrays.from_npz("path/to/shadowmats.npz")
+ precomputed = PrecomputedData(svf=svf, shadow_matrices=shadows)
+
+ result = calculate(
+ surface=surface,
+ location=location,
+ weather=weather,
+ precomputed=precomputed,
+ )
+ """
+
+ wall_height: NDArray[np.floating] | None = None
+ wall_aspect: NDArray[np.floating] | None = None
+ svf: SvfArrays | None = None
+ shadow_matrices: ShadowArrays | None = None
+
+ @classmethod
+ def prepare(
+ cls,
+ walls_dir: str | Path | None = None,
+ svf_dir: str | Path | None = None,
+ ) -> PrecomputedData:
+ """
+ Prepare preprocessing data from directories.
+
+ Loads preprocessing files if they exist. If files don't exist,
+ the corresponding data will be None and computed on-the-fly during calculation.
+
+ All parameters are optional.
+
+ Args:
+ walls_dir: Directory containing wall preprocessing files:
+ - wall_hts.tif: Wall heights (meters)
+ - wall_aspects.tif: Wall aspects (degrees, 0=N)
+ svf_dir: Directory containing SVF preprocessing files:
+ - svfs.zip: SVF arrays (required if svf_dir provided)
+ - shadowmats.npz: Shadow matrices for anisotropic sky (optional)
+
+ Returns:
+ PrecomputedData with loaded arrays. Missing data is set to None.
+
+ Example:
+ # Prepare all preprocessing
+ precomputed = PrecomputedData.prepare(
+ walls_dir="preprocessed/walls",
+ svf_dir="preprocessed/svf",
+ )
+
+ # Prepare only SVF
+ precomputed = PrecomputedData.prepare(svf_dir="preprocessed/svf")
+
+ # Nothing prepared (all computed on-the-fly)
+ precomputed = PrecomputedData.prepare()
+ """
+ from .. import io
+
+ wall_height_arr = None
+ wall_aspect_arr = None
+ svf_arrays = None
+ shadow_arrays = None
+
+ # Load walls if directory provided
+ if walls_dir is not None:
+ walls_path = Path(walls_dir)
+ wall_height_path = walls_path / "wall_hts.tif"
+ wall_aspect_path = walls_path / "wall_aspects.tif"
+
+ if wall_height_path.exists():
+ wall_height_arr, _, _, _ = io.load_raster(str(wall_height_path))
+ logger.info(f" Loaded wall heights from {walls_dir}")
+ else:
+ logger.debug(f" Wall heights not found: {wall_height_path}")
+
+ if wall_aspect_path.exists():
+ wall_aspect_arr, _, _, _ = io.load_raster(str(wall_aspect_path))
+ logger.info(f" Loaded wall aspects from {walls_dir}")
+ else:
+ logger.debug(f" Wall aspects not found: {wall_aspect_path}")
+
+ # Load SVF if directory provided
+ if svf_dir is not None:
+ svf_path = Path(svf_dir)
+ svf_zip = svf_path / "svfs.zip"
+
+ if svf_zip.exists():
+ svf_arrays = SvfArrays.from_zip(str(svf_zip))
+ logger.info(f" Loaded SVF data: {svf_arrays.svf.shape}")
+ else:
+ logger.debug(f" SVF not found: {svf_zip}")
+
+ # Load shadow matrices (optional - for anisotropic sky)
+ shadow_npz = svf_path / "shadowmats.npz"
+ if shadow_npz.exists():
+ shadow_arrays = ShadowArrays.from_npz(str(shadow_npz))
+ logger.info(" Loaded shadow matrices for anisotropic sky")
+ else:
+ logger.debug(" No shadow matrices found (anisotropic sky will be slower)")
+
+ return cls(
+ wall_height=wall_height_arr,
+ wall_aspect=wall_aspect_arr,
+ svf=svf_arrays,
+ shadow_matrices=shadow_arrays,
+ )
diff --git a/pysrc/solweig/models/results.py b/pysrc/solweig/models/results.py
new file mode 100644
index 0000000..8ab0b72
--- /dev/null
+++ b/pysrc/solweig/models/results.py
@@ -0,0 +1,324 @@
+"""Result data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime as dt
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from ..solweig_logging import get_logger
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from ..models import HumanParams
+ from .state import ThermalState
+ from .surface import SurfaceData
+ from .weather import Weather
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class SolweigResult:
+ """
+ Results from a SOLWEIG calculation.
+
+ All output grids have the same shape as the input DSM.
+
+ Attributes:
+ tmrt: Mean Radiant Temperature grid (°C).
+ utci: Universal Thermal Climate Index grid (°C). Optional.
+ pet: Physiological Equivalent Temperature grid (°C). Optional.
+ shadow: Shadow mask (1=shadow, 0=sunlit).
+ kdown: Downwelling shortwave radiation (W/m²).
+ kup: Upwelling shortwave radiation (W/m²).
+ ldown: Downwelling longwave radiation (W/m²).
+ lup: Upwelling longwave radiation (W/m²).
+ state: Thermal state for multi-timestep chaining. Optional.
+ When state parameter was passed to calculate(), this contains
+ the updated state for the next timestep.
+ """
+
+ tmrt: NDArray[np.floating]
+ shadow: NDArray[np.floating] | None = None
+ kdown: NDArray[np.floating] | None = None
+ kup: NDArray[np.floating] | None = None
+ ldown: NDArray[np.floating] | None = None
+ lup: NDArray[np.floating] | None = None
+ utci: NDArray[np.floating] | None = None
+ pet: NDArray[np.floating] | None = None
+ state: ThermalState | None = None
+
+ def to_geotiff(
+ self,
+ output_dir: str | Path,
+ timestamp: dt | None = None,
+ outputs: list[str] | None = None,
+ surface: SurfaceData | None = None,
+ transform: list[float] | None = None,
+ crs_wkt: str | None = None,
+ ) -> None:
+ """
+ Save results to GeoTIFF files.
+
+ Creates one GeoTIFF file per output variable per timestep.
+ Filename pattern: {output}_{YYYYMMDD}_{HHMM}.tif
+
+ Args:
+ output_dir: Directory to write GeoTIFF files.
+ timestamp: Timestamp for filename. If None, uses current time.
+ outputs: List of outputs to save. Options: "tmrt", "utci", "pet",
+ "shadow", "kdown", "kup", "ldown", "lup".
+ Default: ["tmrt"] (only save Mean Radiant Temperature).
+ surface: SurfaceData object (if loaded via from_geotiff, contains CRS/transform).
+ If provided and transform/crs_wkt not specified, uses surface metadata.
+ transform: GDAL-style geotransform [x_origin, pixel_width, 0,
+ y_origin, 0, -pixel_height]. If None, attempts to use surface metadata,
+ otherwise uses identity transform.
+ crs_wkt: Coordinate reference system in WKT format. If None, attempts to use
+ surface metadata, otherwise no CRS set.
+
+ Example:
+ # With surface metadata (recommended when using from_geotiff)
+ >>> surface, precomputed = SurfaceData.from_geotiff("dsm.tif", svf_dir="svf/")
+ >>> result = solweig.calculate(surface, location, weather, precomputed=precomputed)
+ >>> result.to_geotiff("output/", timestamp=weather.dt, surface=surface)
+
+ # Without surface metadata (explicit transform/CRS)
+ >>> result.to_geotiff(
+ ... "output/",
+ ... timestamp=datetime(2023, 7, 15, 12, 0),
+ ... outputs=["tmrt", "utci", "pet"],
+ ... transform=[0, 1, 0, 0, 0, -1],
+ ... crs_wkt="EPSG:32633",
+ ... )
+ """
+ from .. import io
+
+ output_dir = Path(output_dir)
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ # Default outputs: just tmrt
+ if outputs is None:
+ outputs = ["tmrt"]
+
+ # Default timestamp: current time
+ if timestamp is None:
+ timestamp = dt.now()
+
+ # Format timestamp for filename
+ ts_str = timestamp.strftime("%Y%m%d_%H%M")
+
+ # Use surface metadata if available and not overridden
+ if surface is not None:
+ if transform is None and surface._geotransform is not None:
+ transform = surface._geotransform
+ if crs_wkt is None and surface._crs_wkt is not None:
+ crs_wkt = surface._crs_wkt
+
+ # Default transform: identity (top-left origin, 1m pixels)
+ if transform is None:
+ height, width = self.tmrt.shape
+ transform = [0.0, 1.0, 0.0, 0.0, 0.0, -1.0]
+
+ # Default CRS: empty string (no CRS)
+ if crs_wkt is None:
+ crs_wkt = ""
+
+ # Map output names to arrays
+ available_outputs = {
+ "tmrt": self.tmrt,
+ "utci": self.utci,
+ "pet": self.pet,
+ "shadow": self.shadow,
+ "kdown": self.kdown,
+ "kup": self.kup,
+ "ldown": self.ldown,
+ "lup": self.lup,
+ }
+
+ # Save each requested output
+ for name in outputs:
+ if name not in available_outputs:
+ logger.warning(f"Unknown output '{name}', skipping. Valid: {list(available_outputs.keys())}")
+ continue
+
+ array = available_outputs[name]
+ if array is None:
+ logger.warning(f"Output '{name}' is None (not computed), skipping.")
+ continue
+
+ # Write to GeoTIFF in component subdirectory
+ comp_dir = output_dir / name
+ comp_dir.mkdir(parents=True, exist_ok=True)
+ filepath = comp_dir / f"{name}_{ts_str}.tif"
+ io.save_raster(
+ out_path_str=str(filepath),
+ data_arr=array,
+ trf_arr=transform,
+ crs_wkt=crs_wkt,
+ no_data_val=np.nan,
+ )
+ logger.debug(f"Saved {name} to {filepath}")
+
+ def compute_utci(
+ self,
+ weather_or_ta: Weather | float,
+ rh: float | None = None,
+ wind: float | None = None,
+ ) -> NDArray[np.floating]:
+ """
+ Compute UTCI (Universal Thermal Climate Index) from this result's Tmrt.
+
+ Can be called with either a Weather object or individual values:
+ utci = result.compute_utci(weather)
+ utci = result.compute_utci(ta=25.0, rh=50.0, wind=2.0)
+
+ Args:
+ weather_or_ta: Either a Weather object, or air temperature in °C.
+ rh: Relative humidity in % (required if weather_or_ta is float).
+ wind: Wind speed at 10m height in m/s. Default 1.0 if not provided.
+
+ Returns:
+ UTCI grid (°C) with same shape as tmrt.
+
+ Example:
+ result = solweig.calculate(surface, location, weather)
+
+ # Pattern A: Pass weather object (convenient)
+ utci = result.compute_utci(weather)
+
+ # Pattern B: Pass individual values (explicit)
+ utci = result.compute_utci(25.0, rh=50.0, wind=2.0)
+ """
+ from ..postprocess import compute_utci_grid
+ from .weather import Weather as WeatherClass
+
+ # Duck-type check avoids isinstance failure from dual module import paths
+ if hasattr(weather_or_ta, "ta") and hasattr(weather_or_ta, "rh"):
+ w: WeatherClass = weather_or_ta # type: ignore[assignment]
+ return compute_utci_grid(self.tmrt, w.ta, w.rh, w.ws)
+ else:
+ # Individual values
+ ta = float(weather_or_ta)
+ if rh is None:
+ raise ValueError("rh is required when ta is provided as a float")
+ return compute_utci_grid(self.tmrt, ta, rh, wind if wind is not None else 1.0)
+
+ def compute_pet(
+ self,
+ weather_or_ta: Weather | float,
+ rh: float | None = None,
+ wind: float | None = None,
+ human: HumanParams | None = None,
+ ) -> NDArray[np.floating]:
+ """
+ Compute PET (Physiological Equivalent Temperature) from this result's Tmrt.
+
+ Can be called with either a Weather object or individual values:
+ pet = result.compute_pet(weather)
+ pet = result.compute_pet(ta=25.0, rh=50.0, wind=2.0)
+
+ Args:
+ weather_or_ta: Either a Weather object, or air temperature in °C.
+ rh: Relative humidity in % (required if weather_or_ta is float).
+ wind: Wind speed at 10m height in m/s. Default 1.0 if not provided.
+ human: Human body parameters. Uses defaults if not provided.
+
+ Returns:
+ PET grid (°C) with same shape as tmrt.
+
+ Note:
+ PET uses an iterative solver and is ~50× slower than UTCI.
+
+ Example:
+ result = solweig.calculate(surface, location, weather)
+
+ # Pattern A: Pass weather object (convenient)
+ pet = result.compute_pet(weather)
+
+ # Pattern B: Pass individual values with custom human params
+ pet = result.compute_pet(
+ 25.0, rh=50.0, wind=2.0,
+ human=HumanParams(weight=70, height=1.65)
+ )
+ """
+ from ..postprocess import compute_pet_grid
+ from .weather import Weather as WeatherClass
+
+ # Duck-type check avoids isinstance failure from dual module import paths
+ if hasattr(weather_or_ta, "ta") and hasattr(weather_or_ta, "rh"):
+ w: WeatherClass = weather_or_ta # type: ignore[assignment]
+ return compute_pet_grid(self.tmrt, w.ta, w.rh, w.ws, human)
+ else:
+ # Individual values
+ ta = float(weather_or_ta)
+ if rh is None:
+ raise ValueError("rh is required when ta is provided as a float")
+ return compute_pet_grid(self.tmrt, ta, rh, wind if wind is not None else 1.0, human)
+
+
+@dataclass
+class TileSpec:
+ """
+ Specification for a single tile with overlap regions.
+
+ Attributes:
+ row_start, row_end: Core tile row bounds (without overlap).
+ col_start, col_end: Core tile column bounds (without overlap).
+ row_start_full, row_end_full: Full tile row bounds (with overlap).
+ col_start_full, col_end_full: Full tile column bounds (with overlap).
+ overlap_top, overlap_bottom: Vertical overlap in pixels.
+ overlap_left, overlap_right: Horizontal overlap in pixels.
+ """
+
+ row_start: int
+ row_end: int
+ col_start: int
+ col_end: int
+ row_start_full: int
+ row_end_full: int
+ col_start_full: int
+ col_end_full: int
+ overlap_top: int
+ overlap_bottom: int
+ overlap_left: int
+ overlap_right: int
+
+ @property
+ def core_shape(self) -> tuple[int, int]:
+ """Shape of core tile (without overlap)."""
+ return (self.row_end - self.row_start, self.col_end - self.col_start)
+
+ @property
+ def full_shape(self) -> tuple[int, int]:
+ """Shape of full tile (with overlap)."""
+ return (self.row_end_full - self.row_start_full, self.col_end_full - self.col_start_full)
+
+ @property
+ def core_slice(self) -> tuple[slice, slice]:
+ """Slices for extracting core from full tile result."""
+ return (
+ slice(self.overlap_top, self.overlap_top + self.core_shape[0]),
+ slice(self.overlap_left, self.overlap_left + self.core_shape[1]),
+ )
+
+ @property
+ def write_slice(self) -> tuple[slice, slice]:
+ """Slices for writing core to global output."""
+ return (
+ slice(self.row_start, self.row_end),
+ slice(self.col_start, self.col_end),
+ )
+
+ @property
+ def read_slice(self) -> tuple[slice, slice]:
+ """Slices for reading full tile from global input."""
+ return (
+ slice(self.row_start_full, self.row_end_full),
+ slice(self.col_start_full, self.col_end_full),
+ )
diff --git a/pysrc/solweig/models/state.py b/pysrc/solweig/models/state.py
new file mode 100644
index 0000000..5462634
--- /dev/null
+++ b/pysrc/solweig/models/state.py
@@ -0,0 +1,152 @@
+"""State management for SOLWEIG calculations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+
+@dataclass
+class ThermalState:
+ """
+ Thermal state for multi-timestep calculations.
+
+ Carries forward surface temperature history between timesteps
+ to model thermal inertia of ground and walls (TsWaveDelay_2015a).
+
+ This enables accurate time-series simulations where surface temperatures
+ depend on accumulated heating throughout the day.
+
+ Attributes:
+ tgmap1: Upwelling longwave history (center view).
+ tgmap1_e: Upwelling longwave history (east view).
+ tgmap1_s: Upwelling longwave history (south view).
+ tgmap1_w: Upwelling longwave history (west view).
+ tgmap1_n: Upwelling longwave history (north view).
+ tgout1: Ground temperature output history.
+ firstdaytime: Flag for first morning timestep (1.0=first, 0.0=subsequent).
+ timeadd: Accumulated time for thermal delay function.
+ timestep_dec: Decimal time between steps (fraction of day).
+
+ Example:
+ # Manual state management for custom time loops
+ state = ThermalState.initial(dsm.shape)
+ for weather in weather_list:
+ result = calculate(..., state=state)
+ state = result.state
+ """
+
+ tgmap1: NDArray[np.floating]
+ tgmap1_e: NDArray[np.floating]
+ tgmap1_s: NDArray[np.floating]
+ tgmap1_w: NDArray[np.floating]
+ tgmap1_n: NDArray[np.floating]
+ tgout1: NDArray[np.floating]
+ firstdaytime: float = 1.0
+ timeadd: float = 0.0
+ timestep_dec: float = 0.0
+
+ @classmethod
+ def initial(cls, shape: tuple[int, int]) -> ThermalState:
+ """
+ Create initial state for first timestep.
+
+ Args:
+ shape: Grid shape (rows, cols) matching the DSM.
+
+ Returns:
+ ThermalState with zero-initialized arrays.
+ """
+ zeros = np.zeros(shape, dtype=np.float32)
+ return cls(
+ tgmap1=zeros.copy(),
+ tgmap1_e=zeros.copy(),
+ tgmap1_s=zeros.copy(),
+ tgmap1_w=zeros.copy(),
+ tgmap1_n=zeros.copy(),
+ tgout1=zeros.copy(),
+ firstdaytime=1.0,
+ timeadd=0.0,
+ timestep_dec=0.0,
+ )
+
+ def copy(self) -> ThermalState:
+ """Create a deep copy of this state."""
+ return ThermalState(
+ tgmap1=self.tgmap1.copy(),
+ tgmap1_e=self.tgmap1_e.copy(),
+ tgmap1_s=self.tgmap1_s.copy(),
+ tgmap1_w=self.tgmap1_w.copy(),
+ tgmap1_n=self.tgmap1_n.copy(),
+ tgout1=self.tgout1.copy(),
+ firstdaytime=self.firstdaytime,
+ timeadd=self.timeadd,
+ timestep_dec=self.timestep_dec,
+ )
+
+
+@dataclass
+class TileSpec:
+ """
+ Specification for a single tile with overlap regions.
+
+ Attributes:
+ row_start, row_end: Core tile row bounds (without overlap).
+ col_start, col_end: Core tile column bounds (without overlap).
+ row_start_full, row_end_full: Full tile row bounds (with overlap).
+ col_start_full, col_end_full: Full tile column bounds (with overlap).
+ overlap_top, overlap_bottom: Vertical overlap in pixels.
+ overlap_left, overlap_right: Horizontal overlap in pixels.
+ """
+
+ row_start: int
+ row_end: int
+ col_start: int
+ col_end: int
+ row_start_full: int
+ row_end_full: int
+ col_start_full: int
+ col_end_full: int
+ overlap_top: int
+ overlap_bottom: int
+ overlap_left: int
+ overlap_right: int
+
+ @property
+ def core_shape(self) -> tuple[int, int]:
+ """Shape of core tile (without overlap)."""
+ return (self.row_end - self.row_start, self.col_end - self.col_start)
+
+ @property
+ def full_shape(self) -> tuple[int, int]:
+ """Shape of full tile (with overlap)."""
+ return (self.row_end_full - self.row_start_full, self.col_end_full - self.col_start_full)
+
+ @property
+ def core_slice(self) -> tuple[slice, slice]:
+ """Slices for extracting core from full tile result."""
+ return (
+ slice(self.overlap_top, self.overlap_top + self.core_shape[0]),
+ slice(self.overlap_left, self.overlap_left + self.core_shape[1]),
+ )
+
+ @property
+ def write_slice(self) -> tuple[slice, slice]:
+ """Slices for writing core to global output."""
+ return (
+ slice(self.row_start, self.row_end),
+ slice(self.col_start, self.col_end),
+ )
+
+ @property
+ def read_slice(self) -> tuple[slice, slice]:
+ """Slices for reading full tile from global input."""
+ return (
+ slice(self.row_start_full, self.row_end_full),
+ slice(self.col_start_full, self.col_end_full),
+ )
diff --git a/pysrc/solweig/models/surface.py b/pysrc/solweig/models/surface.py
new file mode 100644
index 0000000..4fb0f53
--- /dev/null
+++ b/pysrc/solweig/models/surface.py
@@ -0,0 +1,1959 @@
+"""Surface and terrain data models."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from affine import Affine as AffineClass
+
+from .. import io
+from .. import walls as walls_module
+from ..buffers import BufferPool
+from ..cache import CacheMetadata, clear_stale_cache, validate_cache
+from ..loaders import get_lc_properties_from_params
+from ..rustalgos import skyview
+from ..solweig_logging import get_logger
+from ..utils import extract_bounds, intersect_bounds, resample_to_grid
+from .precomputed import ShadowArrays, SvfArrays
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+logger = get_logger(__name__)
+
+
+def _save_svfs_zip(svf_data: SvfArrays, svf_cache_dir: Path, aligned_rasters: dict) -> None:
+ """Save SVF arrays as svfs.zip for PrecomputedData.prepare() compatibility."""
+ import tempfile
+ import zipfile
+
+ geotransform = aligned_rasters.get("dsm_transform")
+ crs_wkt = aligned_rasters.get("dsm_crs")
+
+ # If geotransform/CRS not available, skip zip (memmap still works)
+ if geotransform is None:
+ logger.debug(" Skipping svfs.zip (no geotransform available)")
+ return
+
+ svf_files = {
+ "svf.tif": svf_data.svf,
+ "svfN.tif": svf_data.svf_north,
+ "svfE.tif": svf_data.svf_east,
+ "svfS.tif": svf_data.svf_south,
+ "svfW.tif": svf_data.svf_west,
+ "svfveg.tif": svf_data.svf_veg,
+ "svfNveg.tif": svf_data.svf_veg_north,
+ "svfEveg.tif": svf_data.svf_veg_east,
+ "svfSveg.tif": svf_data.svf_veg_south,
+ "svfWveg.tif": svf_data.svf_veg_west,
+ "svfaveg.tif": svf_data.svf_aveg,
+ "svfNaveg.tif": svf_data.svf_aveg_north,
+ "svfEaveg.tif": svf_data.svf_aveg_east,
+ "svfSaveg.tif": svf_data.svf_aveg_south,
+ "svfWaveg.tif": svf_data.svf_aveg_west,
+ }
+
+ # Convert Affine to GDAL geotransform list if needed
+ if isinstance(geotransform, AffineClass):
+ geotransform = [geotransform.c, geotransform.a, geotransform.b, geotransform.f, geotransform.d, geotransform.e]
+
+ svf_zip_path = svf_cache_dir / "svfs.zip"
+ with tempfile.TemporaryDirectory() as tmpdir:
+ for filename, arr in svf_files.items():
+ if arr is not None:
+ tif_path = str(Path(tmpdir) / filename)
+ io.save_raster(tif_path, arr, geotransform, crs_wkt)
+ with zipfile.ZipFile(str(svf_zip_path), "w", zipfile.ZIP_DEFLATED) as zf:
+ for filename in svf_files:
+ tif_file = Path(tmpdir) / filename
+ if tif_file.exists():
+ zf.write(str(tif_file), filename)
+
+ logger.info(f" ✓ SVF saved as {svf_zip_path}")
+
+
+def _save_shadow_matrices(svf_result, svf_cache_dir: Path, patch_count: int = 153) -> None:
+ """Save shadow matrices as shadowmats.npz for anisotropic sky model."""
+ # Shadow matrices are bitpacked uint8 from Rust: shape (rows, cols, ceil(patches/8))
+ shadow_path = svf_cache_dir / "shadowmats.npz"
+ np.savez_compressed(
+ str(shadow_path),
+ shadowmat=np.array(svf_result.bldg_sh_matrix),
+ vegshadowmat=np.array(svf_result.veg_sh_matrix),
+ vbshmat=np.array(svf_result.veg_blocks_bldg_sh_matrix),
+ patch_count=np.array(patch_count),
+ )
+
+ logger.info(f" ✓ Shadow matrices saved as {shadow_path}")
+
+
+@dataclass
+class SurfaceData:
+ """
+ Surface/terrain data for SOLWEIG calculations.
+
+ Only `dsm` is required. Other rasters are optional and will be
+ treated as absent if not provided.
+
+ Attributes:
+ dsm: Digital Surface Model (elevation in meters). Required.
+ cdsm: Canopy Digital Surface Model (vegetation heights). Optional.
+ dem: Digital Elevation Model (ground elevation). Optional.
+ tdsm: Trunk Digital Surface Model (trunk zone heights). Optional.
+ land_cover: Land cover classification grid (UMEP standard IDs). Optional.
+ IDs: 0=paved, 1=asphalt, 2=buildings, 5=grass, 6=bare_soil, 7=water.
+ When provided, albedo and emissivity are derived from land cover.
+ wall_height: Preprocessed wall heights (meters). Optional.
+ If not provided, computed on-the-fly from DSM.
+ wall_aspect: Preprocessed wall aspects (degrees, 0=N). Optional.
+ If not provided, computed on-the-fly from DSM.
+ svf: Preprocessed Sky View Factor arrays. Optional.
+ If not provided, computed on-the-fly.
+ shadow_matrices: Preprocessed shadow matrices for anisotropic sky. Optional.
+ pixel_size: Pixel size in meters. Default 1.0.
+ trunk_ratio: Ratio for auto-generating TDSM from CDSM. Default 0.25.
+ dsm_relative: Whether DSM contains relative heights (above ground)
+ rather than absolute elevations. Default False. If True, DEM is
+ required and preprocess() converts DSM to absolute via DSM + DEM.
+ cdsm_relative: Whether CDSM contains relative heights. Default True.
+ If True and preprocess() is not called, a warning is issued.
+ tdsm_relative: Whether TDSM contains relative heights. Default True.
+ If True and preprocess() is not called, a warning is issued.
+
+ Note:
+ Albedo and emissivity are derived internally from land_cover using
+ standard UMEP parameters. They cannot be directly specified.
+
+ Note:
+ max_height is auto-computed from dsm as: np.nanmax(dsm) - np.nanmin(dsm)
+
+ Height Conventions:
+ Each raster layer can independently use relative or absolute heights.
+ The per-layer flags (``dsm_relative``, ``cdsm_relative``,
+ ``tdsm_relative``) control the convention for each layer.
+
+ **Relative Heights** (height above ground):
+ - CDSM/TDSM: vegetation height above ground (e.g., 6m tree)
+ - DSM: building/surface height above ground (requires DEM)
+ - Typical range: 0-40m for CDSM, 0-10m for TDSM
+ - Must call ``preprocess()`` before calculations
+
+ **Absolute Heights** (elevation above sea level):
+ - Values in the same vertical reference system
+ - Example: DSM=127m, CDSM=133m means 6m vegetation
+ - No preprocessing needed
+
+ The internal algorithms (Rust) always use **absolute heights**. The
+ ``preprocess()`` method converts relative → absolute using:
+ dsm_absolute = dem + dsm_relative (requires DEM)
+ cdsm_absolute = base + cdsm_relative
+ tdsm_absolute = base + tdsm_relative
+ where ``base = DEM`` if available, else ``base = DSM``.
+
+ Example:
+ # Relative CDSM (common case):
+ surface = SurfaceData(dsm=dsm, cdsm=cdsm_rel)
+ surface.preprocess() # Converts CDSM to absolute
+
+ # Absolute CDSM:
+ surface = SurfaceData(dsm=dsm, cdsm=cdsm_abs, cdsm_relative=False)
+
+ # Mixed: absolute DSM, relative CDSM, absolute TDSM:
+ surface = SurfaceData(
+ dsm=dsm, cdsm=cdsm, tdsm=tdsm,
+ cdsm_relative=True, tdsm_relative=False,
+ )
+ surface.preprocess() # Only converts CDSM
+
+ # Relative DSM (requires DEM):
+ surface = SurfaceData(dsm=ndsm, dem=dem, dsm_relative=True)
+ surface.preprocess() # Converts DSM to absolute via DEM + nDSM
+ """
+
+ # Surface rasters
+ dsm: NDArray[np.floating]
+ cdsm: NDArray[np.floating] | None = None
+ dem: NDArray[np.floating] | None = None
+ tdsm: NDArray[np.floating] | None = None
+ albedo: NDArray[np.floating] | None = None
+ emissivity: NDArray[np.floating] | None = None
+ land_cover: NDArray[np.integer] | None = None
+
+ # Preprocessing data (walls, SVF, shadows)
+ wall_height: NDArray[np.floating] | None = None
+ wall_aspect: NDArray[np.floating] | None = None
+ svf: SvfArrays | None = None
+ shadow_matrices: ShadowArrays | None = None
+
+ # Grid properties
+ pixel_size: float = 1.0
+ trunk_ratio: float = 0.25 # Trunk zone ratio for auto-generating TDSM from CDSM
+ dsm_relative: bool = False # Whether DSM contains relative heights (requires DEM)
+ cdsm_relative: bool = True # Whether CDSM contains relative heights
+ tdsm_relative: bool = True # Whether TDSM contains relative heights
+
+ # Internal state
+ _nan_filled: bool = field(default=False, init=False, repr=False)
+ _preprocessed: bool = field(default=False, init=False, repr=False)
+ _geotransform: list[float] | None = field(default=None, init=False, repr=False) # GDAL geotransform
+ _crs_wkt: str | None = field(default=None, init=False, repr=False) # CRS as WKT string
+ _buffer_pool: BufferPool | None = field(default=None, init=False, repr=False) # Reusable array pool
+ _gvf_geometry_cache: object = field(default=None, init=False, repr=False) # Rust GVF geometry cache
+ _valid_mask: NDArray[np.bool_] | None = field(default=None, init=False, repr=False) # Combined valid mask
+
+ def __post_init__(self):
+ # Ensure dsm is float32 for memory efficiency
+ self.dsm = np.asarray(self.dsm, dtype=np.float32)
+
+ # Convert optional surface arrays if provided
+ if self.cdsm is not None:
+ self.cdsm = np.asarray(self.cdsm, dtype=np.float32)
+ if self.dem is not None:
+ self.dem = np.asarray(self.dem, dtype=np.float32)
+ if self.tdsm is not None:
+ self.tdsm = np.asarray(self.tdsm, dtype=np.float32)
+ if self.albedo is not None:
+ self.albedo = np.asarray(self.albedo, dtype=np.float32)
+ if self.emissivity is not None:
+ self.emissivity = np.asarray(self.emissivity, dtype=np.float32)
+ if self.land_cover is not None:
+ self.land_cover = np.asarray(self.land_cover, dtype=np.uint8)
+
+ # Convert optional preprocessing arrays if provided
+ if self.wall_height is not None:
+ self.wall_height = np.asarray(self.wall_height, dtype=np.float32)
+ if self.wall_aspect is not None:
+ self.wall_aspect = np.asarray(self.wall_aspect, dtype=np.float32)
+
+ @classmethod
+ def prepare(
+ cls,
+ dsm: str | Path,
+ working_dir: str | Path,
+ cdsm: str | Path | None = None,
+ dem: str | Path | None = None,
+ tdsm: str | Path | None = None,
+ land_cover: str | Path | None = None,
+ wall_height: str | Path | None = None,
+ wall_aspect: str | Path | None = None,
+ svf_dir: str | Path | None = None,
+ bbox: list[float] | None = None,
+ pixel_size: float | None = None,
+ trunk_ratio: float = 0.25,
+ dsm_relative: bool = False,
+ cdsm_relative: bool = True,
+ tdsm_relative: bool = True,
+ force_recompute: bool = False,
+ feedback: Any = None,
+ ) -> SurfaceData:
+ """
+ Prepare surface data and optional preprocessing from GeoTIFF files.
+
+ Loads raster data from disk and prepares it for SOLWEIG calculations.
+ Optionally loads preprocessing data (walls, SVF) and automatically
+ aligns it to match the surface grid.
+
+ Args:
+ dsm: Path to DSM GeoTIFF file (required).
+ working_dir: Working directory for caching computed/resampled data (required).
+ Computed walls/SVF and resampled rasters are auto-discovered here and
+ reused on subsequent runs. Structure: working_dir/walls/, working_dir/svf/,
+ working_dir/resampled/. All intermediate results saved for inspection.
+ To regenerate cached data, delete the working_dir.
+ cdsm: Path to CDSM GeoTIFF file (optional).
+ dem: Path to DEM GeoTIFF file (optional).
+ tdsm: Path to TDSM GeoTIFF file (optional).
+ land_cover: Path to land cover GeoTIFF file (optional).
+ Albedo and emissivity are derived from land cover internally.
+ wall_height: Path to wall height GeoTIFF file (optional).
+ If not provided, walls are auto-discovered in working_dir/walls/ or
+ computed from DSM and cached.
+ wall_aspect: Path to wall aspect GeoTIFF file (optional, degrees 0=N).
+ If not provided, walls are auto-discovered in working_dir/walls/ or
+ computed from DSM and cached.
+ svf_dir: Directory containing SVF preprocessing files (optional):
+ - svfs.zip: SVF arrays (required if svf_dir provided)
+ - shadowmats.npz: Shadow matrices for anisotropic sky (optional)
+ If not provided, SVF is auto-discovered in working_dir/svf/ or
+ computed and cached.
+ bbox: Explicit bounding box [minx, miny, maxx, maxy] (optional).
+ If provided, all data is cropped/resampled to this extent.
+ If None, uses auto-intersection of all provided data.
+ pixel_size: Pixel size in meters. If None, computed from DSM geotransform.
+ trunk_ratio: Ratio for auto-generating TDSM from CDSM. Default 0.25.
+ dsm_relative: Whether DSM contains relative heights. Default False.
+ cdsm_relative: Whether CDSM contains relative heights. Default True.
+ tdsm_relative: Whether TDSM contains relative heights. Default True.
+ force_recompute: If True, skip cache and recompute walls/SVF even if they
+ exist in working_dir. Default False (use cached data when available).
+ feedback: Optional QGIS QgsProcessingFeedback for progress/cancellation.
+
+ Returns:
+ SurfaceData instance with loaded terrain and preprocessing data.
+
+ Note:
+ When preprocessing data (walls/SVF) has different extents or resolution
+ than the surface data, it is automatically resampled/cropped to match.
+ Use bbox parameter to explicitly control the output extent.
+
+ Example:
+ # Load surface with preprocessing
+ surface = SurfaceData.prepare(
+ dsm="data/dsm.tif",
+ cdsm="data/cdsm.tif",
+ wall_height="preprocessed/walls/wall_hts.tif",
+ wall_aspect="preprocessed/walls/wall_aspects.tif",
+ svf_dir="preprocessed/svf",
+ )
+
+ # Minimal case - walls and SVF computed automatically
+ surface = SurfaceData.prepare(dsm="data/dsm.tif")
+
+ # Mixed height conventions
+ surface = SurfaceData.prepare(
+ dsm="data/dsm.tif",
+ cdsm="data/cdsm.tif",
+ tdsm="data/tdsm.tif",
+ cdsm_relative=True,
+ tdsm_relative=False,
+ )
+ """
+ logger.info("Preparing surface data from GeoTIFF files...")
+
+ # Load and validate DSM
+ dsm_arr, dsm_transform, dsm_crs, pixel_size = cls._load_and_validate_dsm(dsm, pixel_size)
+
+ # Load optional terrain rasters
+ terrain_rasters = cls._load_terrain_rasters(cdsm, dem, tdsm, land_cover, trunk_ratio)
+
+ # Load preprocessing data (walls, SVF)
+ working_path = Path(working_dir)
+ preprocess_data = cls._load_preprocessing_data(wall_height, wall_aspect, svf_dir, working_path, force_recompute)
+
+ # Compute extent, validate bbox, and resample all rasters
+ aligned_rasters = cls._align_rasters(
+ dsm_arr,
+ dsm_transform,
+ dsm_crs,
+ pixel_size,
+ terrain_rasters,
+ preprocess_data,
+ bbox,
+ )
+
+ # Create SurfaceData instance
+ surface_data = cls._create_surface_instance(
+ aligned_rasters,
+ pixel_size,
+ trunk_ratio,
+ dsm_relative=dsm_relative,
+ cdsm_relative=cdsm_relative,
+ tdsm_relative=tdsm_relative,
+ )
+
+ # Validate cached SVF against current inputs (if SVF was loaded)
+ if preprocess_data["svf_data"] is not None and not force_recompute:
+ dsm_arr = aligned_rasters["dsm_arr"]
+ cdsm_arr = aligned_rasters.get("cdsm_arr")
+ svf_source = preprocess_data.get("svf_source", "none")
+
+ cache_valid = False
+ if svf_source == "memmap":
+ # Memmap has cache_meta.json — use hash-based validation
+ svf_cache_dir = working_path / "svf" / "memmap"
+ cache_valid = validate_cache(svf_cache_dir, dsm_arr, pixel_size, cdsm_arr)
+ elif svf_source == "zip":
+ # Zip has no metadata — validate by shape match only
+ svf_shape = preprocess_data["svf_data"].svf.shape
+ cache_valid = svf_shape == dsm_arr.shape
+ if not cache_valid:
+ logger.info(f" SVF shape {svf_shape} doesn't match DSM {dsm_arr.shape}")
+
+ if not cache_valid:
+ logger.info(" → Cache stale, clearing and recomputing SVF...")
+ clear_stale_cache(working_path / "svf" / "memmap")
+ # Also remove zip/npz so stale data doesn't persist
+ for stale_file in ("svfs.zip", "shadowmats.npz"):
+ stale_path = working_path / "svf" / stale_file
+ if stale_path.exists():
+ stale_path.unlink()
+ preprocess_data["svf_data"] = None
+ preprocess_data["compute_svf"] = True
+ surface_data.svf = None
+
+ # Compute and cache walls if needed
+ if preprocess_data["compute_walls"]:
+ cls._compute_and_cache_walls(surface_data, aligned_rasters, working_path)
+
+ # Compute and cache SVF if needed
+ if preprocess_data["compute_svf"]:
+ cls._compute_and_cache_svf(surface_data, aligned_rasters, working_path, trunk_ratio, feedback=feedback)
+
+ # Preprocess layers with relative heights to absolute
+ needs_preprocess = (
+ dsm_relative
+ or (cdsm_relative and surface_data.cdsm is not None)
+ or (tdsm_relative and surface_data.tdsm is not None)
+ )
+ if needs_preprocess:
+ logger.debug(" Preprocessing relative heights → absolute")
+ surface_data.preprocess()
+
+ # Compute unified valid mask, apply across all layers, crop to valid bbox
+ surface_data.compute_valid_mask()
+ surface_data.apply_valid_mask()
+ surface_data.crop_to_valid_bbox()
+ surface_data.save_cleaned(working_path)
+
+ logger.info("✓ Surface data prepared successfully")
+ return surface_data
+
+ @staticmethod
+ def _load_and_validate_dsm(dsm: str | Path, pixel_size: float | None) -> tuple:
+ """
+ Load DSM raster and validate CRS.
+
+ Args:
+ dsm: Path to DSM GeoTIFF file.
+ pixel_size: Optional pixel size in meters. If None, extracted from geotransform.
+
+ Returns:
+ Tuple of (dsm_array, dsm_transform, dsm_crs, pixel_size).
+
+ Raises:
+ ValueError: If DSM has no CRS or CRS is not projected.
+ """
+ from .. import io
+
+ # Load required DSM
+ dsm_arr, dsm_transform, dsm_crs, _ = io.load_raster(str(dsm))
+ logger.info(f" DSM: {dsm_arr.shape[1]}×{dsm_arr.shape[0]} pixels")
+
+ # Compute pixel size from geotransform if not provided
+ native_pixel_size = abs(dsm_transform[1]) # X pixel size from DSM
+ if pixel_size is None:
+ pixel_size = native_pixel_size
+ logger.info(f" Extracted pixel size from DSM: {pixel_size:.2f} m")
+ else:
+ # Validate against native resolution
+ if pixel_size < native_pixel_size - 1e-6:
+ raise ValueError(
+ f"Specified pixel_size ({pixel_size:.2f} m) is finer than the DSM native "
+ f"resolution ({native_pixel_size:.2f} m). Upsampling creates false precision. "
+ f"Use pixel_size >= {native_pixel_size:.2f} or omit to use native resolution."
+ )
+ if abs(pixel_size - native_pixel_size) > 1e-6:
+ logger.warning(
+ f" ⚠ Specified pixel_size ({pixel_size:.2f} m) differs from DSM native "
+ f"resolution ({native_pixel_size:.2f} m) — all rasters will be resampled"
+ )
+ logger.info(f" Using specified pixel size: {pixel_size:.2f} m")
+
+ # Warn if pixel size is less than 1 meter
+ if pixel_size < 1.0:
+ logger.warning(
+ f" ⚠ Pixel size ({pixel_size:.2f} m) is less than 1 meter - calculations may be slow for large areas"
+ )
+
+ # Validate CRS is projected (required for distance calculations)
+ if dsm_crs is None:
+ raise ValueError("DSM file has no CRS information. SOLWEIG requires a projected coordinate system.")
+
+ try:
+ from pyproj import CRS as pyproj_CRS
+
+ crs_obj = pyproj_CRS.from_wkt(dsm_crs)
+ if not crs_obj.is_projected:
+ raise ValueError(
+ f"DSM CRS is geographic (lat/lon): {crs_obj.name}. "
+ f"SOLWEIG requires a projected coordinate system (e.g., UTM, State Plane) "
+ f"for accurate distance and area calculations. Please reproject your data."
+ )
+ logger.info(f" CRS validated: {crs_obj.name} (EPSG:{crs_obj.to_epsg() or 'custom'})")
+ except Exception as e:
+ logger.warning(f" ⚠ Could not validate CRS: {e}")
+
+ return dsm_arr, dsm_transform, dsm_crs, pixel_size
+
+ @staticmethod
+ def _load_terrain_rasters(
+ cdsm: str | Path | None,
+ dem: str | Path | None,
+ tdsm: str | Path | None,
+ land_cover: str | Path | None,
+ trunk_ratio: float,
+ ) -> dict:
+ """
+ Load optional terrain rasters (CDSM, DEM, TDSM, land_cover).
+
+ Args:
+ cdsm: Path to CDSM GeoTIFF file (optional).
+ dem: Path to DEM GeoTIFF file (optional).
+ tdsm: Path to TDSM GeoTIFF file (optional).
+ land_cover: Path to land cover GeoTIFF file (optional).
+ trunk_ratio: Trunk ratio for auto-generating TDSM from CDSM.
+
+ Returns:
+ Dictionary with keys: cdsm_arr, cdsm_transform, dem_arr, dem_transform,
+ tdsm_arr, tdsm_transform, land_cover_arr, land_cover_transform.
+ """
+ from .. import io
+
+ result = {}
+
+ # Load CDSM
+ if cdsm is not None:
+ result["cdsm_arr"], result["cdsm_transform"], _, _ = io.load_raster(str(cdsm))
+ logger.info(" ✓ Canopy DSM (CDSM) provided")
+ else:
+ result["cdsm_arr"], result["cdsm_transform"] = None, None
+ logger.info(" → No vegetation data - simulation without trees/vegetation")
+
+ # Load DEM
+ if dem is not None:
+ result["dem_arr"], result["dem_transform"], _, _ = io.load_raster(str(dem))
+ logger.info(" ✓ Ground elevation (DEM) provided")
+ else:
+ result["dem_arr"], result["dem_transform"] = None, None
+
+ # Load TDSM
+ if tdsm is not None:
+ result["tdsm_arr"], result["tdsm_transform"], _, _ = io.load_raster(str(tdsm))
+ logger.info(" ✓ Trunk DSM (TDSM) provided")
+ elif result["cdsm_arr"] is not None:
+ result["tdsm_arr"], result["tdsm_transform"] = None, None
+ logger.info(f" → No TDSM provided - will auto-generate from CDSM (ratio={trunk_ratio})")
+ else:
+ result["tdsm_arr"], result["tdsm_transform"] = None, None
+
+ # Load land cover
+ if land_cover is not None:
+ result["land_cover_arr"], result["land_cover_transform"], _, _ = io.load_raster(str(land_cover))
+ logger.info(" ✓ Land cover provided (albedo/emissivity derived from classification)")
+ else:
+ result["land_cover_arr"], result["land_cover_transform"] = None, None
+
+ return result
+
+ @staticmethod
+ def _load_preprocessing_data(
+ wall_height: str | Path | None,
+ wall_aspect: str | Path | None,
+ svf_dir: str | Path | None,
+ working_path: Path,
+ force_recompute: bool,
+ ) -> dict:
+ """
+ Load preprocessing data (walls, SVF) with auto-discovery.
+
+ Args:
+ wall_height: Path to wall height GeoTIFF file (optional).
+ wall_aspect: Path to wall aspect GeoTIFF file (optional).
+ svf_dir: Directory containing SVF preprocessing files (optional).
+ working_path: Working directory for caching.
+ force_recompute: If True, skip cache and recompute.
+
+ Returns:
+ Dictionary with keys: wall_height_arr, wall_height_transform, wall_aspect_arr,
+ wall_aspect_transform, svf_data, shadow_data, compute_walls, compute_svf.
+ """
+ from .. import io
+ from .precomputed import ShadowArrays, SvfArrays
+
+ logger.info("Checking for preprocessing data...")
+
+ result = {
+ "wall_height_arr": None,
+ "wall_height_transform": None,
+ "wall_aspect_arr": None,
+ "wall_aspect_transform": None,
+ "svf_data": None,
+ "svf_source": "none", # "memmap", "zip", or "none"
+ "shadow_data": None,
+ "compute_walls": False,
+ "compute_svf": False,
+ }
+
+ # Load walls with auto-discovery
+ if wall_height is not None and wall_aspect is not None:
+ # Explicit paths provided - use them
+ result["wall_height_arr"], result["wall_height_transform"], _, _ = io.load_raster(str(wall_height))
+ result["wall_aspect_arr"], result["wall_aspect_transform"], _, _ = io.load_raster(str(wall_aspect))
+ logger.info(" ✓ Existing walls found (will use precomputed)")
+
+ elif wall_height is not None or wall_aspect is not None:
+ logger.warning(" ⚠ Only one wall file provided - both wall_height and wall_aspect required")
+ logger.info(" → Walls will be computed from DSM and cached")
+ result["compute_walls"] = True
+
+ else:
+ # Try to auto-discover walls in working_dir (unless force_recompute)
+ if force_recompute:
+ logger.info(" → force_recompute=True - will recompute walls from DSM and cache")
+ result["compute_walls"] = True
+ else:
+ walls_cache_dir = working_path / "walls"
+ wall_hts_path = walls_cache_dir / "wall_hts.tif"
+ wall_aspects_path = walls_cache_dir / "wall_aspects.tif"
+
+ if wall_hts_path.exists() and wall_aspects_path.exists():
+ # Files exist - load them
+ result["wall_height_arr"], result["wall_height_transform"], _, _ = io.load_raster(
+ str(wall_hts_path)
+ )
+ result["wall_aspect_arr"], result["wall_aspect_transform"], _, _ = io.load_raster(
+ str(wall_aspects_path)
+ )
+ logger.info(f" ✓ Walls found in working_dir: {walls_cache_dir}")
+ else:
+ # No cached walls - will compute and cache
+ logger.info(" → No walls found in working_dir - will compute from DSM and cache")
+ result["compute_walls"] = True
+
+ # Helper to load SVF, preferring memmap for efficiency.
+ # Returns (SvfArrays | None, source: str) where source is "memmap", "zip", or "none".
+ def load_svf_from_dir(svf_path: Path) -> tuple[SvfArrays | None, str]:
+ memmap_dir = svf_path / "memmap"
+ svf_zip_path = svf_path / "svfs.zip"
+
+ # Prefer memmap (more efficient for large rasters)
+ if memmap_dir.exists() and (memmap_dir / "svf.npy").exists():
+ svf_data = SvfArrays.from_memmap(memmap_dir)
+ logger.info(" ✓ SVF loaded from memmap (memory-efficient)")
+ return svf_data, "memmap"
+ elif svf_zip_path.exists():
+ svf_data = SvfArrays.from_zip(str(svf_zip_path))
+ logger.info(" ✓ SVF loaded from zip")
+ return svf_data, "zip"
+ return None, "none"
+
+ # Load SVF with auto-discovery
+ if svf_dir is not None:
+ # Explicit SVF directory provided - use it
+ svf_path = Path(svf_dir)
+ shadow_npz_path = svf_path / "shadowmats.npz"
+
+ svf_data, svf_source = load_svf_from_dir(svf_path)
+ if svf_data is not None:
+ result["svf_data"] = svf_data
+ result["svf_source"] = svf_source
+ logger.info(" ✓ Existing SVF found (will use precomputed)")
+
+ if shadow_npz_path.exists():
+ result["shadow_data"] = ShadowArrays.from_npz(str(shadow_npz_path))
+ logger.info(" ✓ Existing shadow matrices found (anisotropic sky enabled)")
+ else:
+ logger.info(f" → SVF directory provided but no SVF files found: {svf_path}")
+ logger.info(" → SVF will be computed and cached")
+ result["compute_svf"] = True
+
+ else:
+ # Try to auto-discover SVF in working_dir (unless force_recompute)
+ if force_recompute:
+ logger.info(" → force_recompute=True - will recompute SVF and cache")
+ result["compute_svf"] = True
+ else:
+ svf_cache_dir = working_path / "svf"
+ shadow_npz_path = svf_cache_dir / "shadowmats.npz"
+
+ svf_data, svf_source = load_svf_from_dir(svf_cache_dir)
+ if svf_data is not None:
+ result["svf_data"] = svf_data
+ result["svf_source"] = svf_source
+ logger.info(f" ✓ SVF found in working_dir: {svf_cache_dir}")
+
+ if shadow_npz_path.exists():
+ result["shadow_data"] = ShadowArrays.from_npz(str(shadow_npz_path))
+ logger.info(" ✓ Shadow matrices found (anisotropic sky enabled)")
+ else:
+ # No cached SVF - will compute and cache
+ logger.info(" → No SVF found in working_dir - will compute and cache")
+ result["compute_svf"] = True
+
+ return result
+
+ @staticmethod
+ def _align_rasters(
+ dsm_arr,
+ dsm_transform,
+ dsm_crs,
+ pixel_size: float,
+ terrain_rasters: dict,
+ preprocess_data: dict,
+ bbox: list[float] | None,
+ ) -> dict:
+ """
+ Compute extent, validate bbox, and resample all rasters to common grid.
+
+ Args:
+ dsm_arr: DSM array.
+ dsm_transform: DSM geotransform.
+ dsm_crs: DSM CRS.
+ pixel_size: Target pixel size in meters.
+ terrain_rasters: Dictionary with terrain raster data.
+ preprocess_data: Dictionary with preprocessing data.
+ bbox: Optional explicit bounding box.
+
+ Returns:
+ Dictionary with all aligned rasters and metadata.
+ """
+ logger.info("Computing spatial extent and resolution...")
+
+ # Extract bounds from all loaded rasters
+ bounds_list = [extract_bounds(dsm_transform, dsm_arr.shape)]
+
+ if terrain_rasters["cdsm_arr"] is not None and terrain_rasters["cdsm_transform"] is not None:
+ bounds_list.append(extract_bounds(terrain_rasters["cdsm_transform"], terrain_rasters["cdsm_arr"].shape))
+ if terrain_rasters["dem_arr"] is not None and terrain_rasters["dem_transform"] is not None:
+ bounds_list.append(extract_bounds(terrain_rasters["dem_transform"], terrain_rasters["dem_arr"].shape))
+ if terrain_rasters["tdsm_arr"] is not None and terrain_rasters["tdsm_transform"] is not None:
+ bounds_list.append(extract_bounds(terrain_rasters["tdsm_transform"], terrain_rasters["tdsm_arr"].shape))
+ if terrain_rasters["land_cover_arr"] is not None and terrain_rasters["land_cover_transform"] is not None:
+ bounds_list.append(
+ extract_bounds(terrain_rasters["land_cover_transform"], terrain_rasters["land_cover_arr"].shape)
+ )
+ if preprocess_data["wall_height_arr"] is not None and preprocess_data["wall_height_transform"] is not None:
+ bounds_list.append(
+ extract_bounds(preprocess_data["wall_height_transform"], preprocess_data["wall_height_arr"].shape)
+ )
+ if preprocess_data["wall_aspect_arr"] is not None and preprocess_data["wall_aspect_transform"] is not None:
+ bounds_list.append(
+ extract_bounds(preprocess_data["wall_aspect_transform"], preprocess_data["wall_aspect_arr"].shape)
+ )
+
+ # Determine target bounding box
+ if bbox is not None:
+ # User provided explicit bbox - validate it's within intersection
+ computed_intersection = intersect_bounds(bounds_list)
+ user_minx, user_miny, user_maxx, user_maxy = bbox
+ int_minx, int_miny, int_maxx, int_maxy = computed_intersection
+
+ # Check if user bbox is within or equal to intersection
+ if (
+ user_minx < int_minx - 1e-6
+ or user_maxx > int_maxx + 1e-6
+ or user_miny < int_miny - 1e-6
+ or user_maxy > int_maxy + 1e-6
+ ):
+ raise ValueError(
+ f"Specified bbox {bbox} extends beyond the intersection of input rasters "
+ f"{computed_intersection}. Bbox must be within or equal to the intersection."
+ )
+
+ target_bbox = bbox
+ logger.info(f" Using user-specified extent: {target_bbox}")
+ else:
+ # Auto-compute intersection
+ target_bbox = intersect_bounds(bounds_list)
+ logger.info(f" Auto-computed extent from raster intersection: {target_bbox}")
+
+ # Check if resampling is needed (compare DSM to target)
+ dsm_bounds = extract_bounds(dsm_transform, dsm_arr.shape)
+ dsm_pixel_size = abs(dsm_transform[1])
+ needs_resampling = (
+ abs(dsm_bounds[0] - target_bbox[0]) > 1e-6
+ or abs(dsm_bounds[1] - target_bbox[1]) > 1e-6
+ or abs(dsm_bounds[2] - target_bbox[2]) > 1e-6
+ or abs(dsm_bounds[3] - target_bbox[3]) > 1e-6
+ or abs(dsm_pixel_size - pixel_size) > 1e-6
+ )
+
+ if needs_resampling:
+ logger.info(" Resampling all rasters to target grid...")
+
+ # Resample DSM
+ dsm_arr, dsm_transform = resample_to_grid(
+ dsm_arr, dsm_transform, target_bbox, pixel_size, method="bilinear", src_crs=dsm_crs
+ )
+
+ # Resample optional terrain rasters
+ if terrain_rasters["cdsm_arr"] is not None and terrain_rasters["cdsm_transform"] is not None:
+ terrain_rasters["cdsm_arr"], _ = resample_to_grid(
+ terrain_rasters["cdsm_arr"],
+ terrain_rasters["cdsm_transform"],
+ target_bbox,
+ pixel_size,
+ method="bilinear",
+ src_crs=dsm_crs,
+ )
+ if terrain_rasters["dem_arr"] is not None and terrain_rasters["dem_transform"] is not None:
+ terrain_rasters["dem_arr"], _ = resample_to_grid(
+ terrain_rasters["dem_arr"],
+ terrain_rasters["dem_transform"],
+ target_bbox,
+ pixel_size,
+ method="bilinear",
+ src_crs=dsm_crs,
+ )
+ if terrain_rasters["tdsm_arr"] is not None and terrain_rasters["tdsm_transform"] is not None:
+ terrain_rasters["tdsm_arr"], _ = resample_to_grid(
+ terrain_rasters["tdsm_arr"],
+ terrain_rasters["tdsm_transform"],
+ target_bbox,
+ pixel_size,
+ method="bilinear",
+ src_crs=dsm_crs,
+ )
+ if terrain_rasters["land_cover_arr"] is not None and terrain_rasters["land_cover_transform"] is not None:
+ # Use nearest neighbor for categorical data
+ terrain_rasters["land_cover_arr"], _ = resample_to_grid(
+ terrain_rasters["land_cover_arr"],
+ terrain_rasters["land_cover_transform"],
+ target_bbox,
+ pixel_size,
+ method="nearest",
+ src_crs=dsm_crs,
+ )
+
+ # Resample preprocessing data
+ if preprocess_data["wall_height_arr"] is not None and preprocess_data["wall_height_transform"] is not None:
+ preprocess_data["wall_height_arr"], _ = resample_to_grid(
+ preprocess_data["wall_height_arr"],
+ preprocess_data["wall_height_transform"],
+ target_bbox,
+ pixel_size,
+ method="bilinear",
+ src_crs=dsm_crs,
+ )
+ if preprocess_data["wall_aspect_arr"] is not None and preprocess_data["wall_aspect_transform"] is not None:
+ preprocess_data["wall_aspect_arr"], _ = resample_to_grid(
+ preprocess_data["wall_aspect_arr"],
+ preprocess_data["wall_aspect_transform"],
+ target_bbox,
+ pixel_size,
+ method="bilinear",
+ src_crs=dsm_crs,
+ )
+
+ # Note: SVF resampling is more complex (multiple arrays) - handled separately if needed
+ if preprocess_data["svf_data"] is not None and preprocess_data["svf_data"].svf.shape != dsm_arr.shape:
+ logger.warning(
+ f" ⚠ SVF shape {preprocess_data['svf_data'].svf.shape} doesn't match target shape "
+ f"{dsm_arr.shape} - SVF resampling not yet implemented. "
+ f"SVF will be recomputed on-the-fly if needed."
+ )
+ preprocess_data["svf_data"] = None
+ preprocess_data["shadow_data"] = None
+
+ logger.info(f" ✓ Resampled to {dsm_arr.shape[1]}×{dsm_arr.shape[0]} pixels")
+ else:
+ logger.info(" ✓ No resampling needed - all rasters match target grid")
+
+ # Return all aligned data
+ return {
+ "dsm_arr": dsm_arr,
+ "dsm_transform": dsm_transform,
+ "dsm_crs": dsm_crs,
+ "pixel_size": pixel_size,
+ "cdsm_arr": terrain_rasters["cdsm_arr"],
+ "dem_arr": terrain_rasters["dem_arr"],
+ "tdsm_arr": terrain_rasters["tdsm_arr"],
+ "land_cover_arr": terrain_rasters["land_cover_arr"],
+ "wall_height_arr": preprocess_data["wall_height_arr"],
+ "wall_aspect_arr": preprocess_data["wall_aspect_arr"],
+ "svf_data": preprocess_data["svf_data"],
+ "shadow_data": preprocess_data["shadow_data"],
+ }
+
+ @classmethod
+ def _create_surface_instance(
+ cls,
+ aligned_rasters: dict,
+ pixel_size: float,
+ trunk_ratio: float,
+ *,
+ dsm_relative: bool = False,
+ cdsm_relative: bool = True,
+ tdsm_relative: bool = True,
+ ) -> SurfaceData:
+ """
+ Create SurfaceData instance from aligned rasters.
+
+ Args:
+ aligned_rasters: Dictionary with all aligned rasters and metadata.
+ pixel_size: Pixel size in meters.
+ trunk_ratio: Trunk ratio for auto-generating TDSM from CDSM.
+ dsm_relative: Whether DSM contains relative heights.
+ cdsm_relative: Whether CDSM contains relative heights.
+ tdsm_relative: Whether TDSM contains relative heights.
+
+ Returns:
+ SurfaceData instance with loaded terrain and preprocessing data.
+ """
+ from affine import Affine as AffineClass
+
+ # Create SurfaceData instance
+ surface_data = cls(
+ dsm=aligned_rasters["dsm_arr"],
+ cdsm=aligned_rasters["cdsm_arr"],
+ dem=aligned_rasters["dem_arr"],
+ tdsm=aligned_rasters["tdsm_arr"],
+ land_cover=aligned_rasters["land_cover_arr"],
+ wall_height=aligned_rasters["wall_height_arr"],
+ wall_aspect=aligned_rasters["wall_aspect_arr"],
+ svf=aligned_rasters["svf_data"],
+ shadow_matrices=aligned_rasters["shadow_data"],
+ pixel_size=pixel_size,
+ trunk_ratio=trunk_ratio,
+ dsm_relative=dsm_relative,
+ cdsm_relative=cdsm_relative,
+ tdsm_relative=tdsm_relative,
+ )
+
+ # Store geotransform and CRS for later export
+ dsm_transform = aligned_rasters["dsm_transform"]
+ if isinstance(dsm_transform, AffineClass):
+ surface_data._geotransform = list(dsm_transform.to_gdal())
+ else:
+ surface_data._geotransform = dsm_transform
+ surface_data._crs_wkt = aligned_rasters["dsm_crs"]
+
+ # Log what was loaded
+ layers_loaded = ["DSM"]
+ if aligned_rasters["cdsm_arr"] is not None:
+ layers_loaded.append("CDSM")
+ if aligned_rasters["dem_arr"] is not None:
+ layers_loaded.append("DEM")
+ if aligned_rasters["tdsm_arr"] is not None:
+ layers_loaded.append("TDSM")
+ if aligned_rasters["land_cover_arr"] is not None:
+ layers_loaded.append("land_cover")
+ logger.info(f" Layers loaded: {', '.join(layers_loaded)}")
+
+ return surface_data
+
+ @staticmethod
+ def _compute_and_cache_walls(
+ surface_data: SurfaceData,
+ aligned_rasters: dict,
+ working_path: Path,
+ ) -> None:
+ """
+ Compute wall heights/aspects from DSM and cache to working_dir.
+
+ Args:
+ surface_data: SurfaceData instance to update with computed walls.
+ aligned_rasters: Dictionary with aligned raster data.
+ working_path: Working directory for caching.
+ """
+
+ logger.info("Computing walls from DSM and caching to working_dir...")
+ walls_cache_dir = working_path / "walls"
+
+ # Save resampled DSM to working_dir so wall computation can use it
+ resampled_dir = working_path / "resampled"
+ resampled_dir.mkdir(parents=True, exist_ok=True)
+ resampled_dsm_path = resampled_dir / "dsm_resampled.tif"
+
+ dsm_transform = aligned_rasters["dsm_transform"]
+ io.save_raster(
+ str(resampled_dsm_path),
+ aligned_rasters["dsm_arr"],
+ list(dsm_transform.to_gdal()) if isinstance(dsm_transform, AffineClass) else dsm_transform,
+ aligned_rasters["dsm_crs"],
+ )
+
+ # Generate walls using the walls module
+ walls_module.generate_wall_hts(
+ dsm_path=str(resampled_dsm_path),
+ bbox=None, # Already resampled to target extent
+ out_dir=str(walls_cache_dir),
+ )
+
+ # Load the generated walls back into surface_data
+ wall_hts_path = walls_cache_dir / "wall_hts.tif"
+ wall_aspects_path = walls_cache_dir / "wall_aspects.tif"
+
+ if wall_hts_path.exists() and wall_aspects_path.exists():
+ wall_height_arr, _, _, _ = io.load_raster(str(wall_hts_path))
+ wall_aspect_arr, _, _, _ = io.load_raster(str(wall_aspects_path))
+ surface_data.wall_height = wall_height_arr
+ surface_data.wall_aspect = wall_aspect_arr
+ logger.info(f" ✓ Walls computed and cached to {walls_cache_dir}")
+ else:
+ logger.warning(" ⚠ Wall generation completed but files not found")
+
+ @staticmethod
+ def _compute_and_cache_svf(
+ surface_data: SurfaceData,
+ aligned_rasters: dict,
+ working_path: Path,
+ trunk_ratio: float,
+ on_tile_complete: Callable | None = None,
+ feedback: Any = None,
+ progress_range: tuple[float, float] | None = None,
+ ) -> None:
+ """
+ Compute SVF from DSM/CDSM/TDSM and cache to working_dir.
+
+ Automatically tiles the computation for large grids to avoid GPU
+ buffer size limits. Tiled mode skips shadow matrix assembly (too
+ large for anisotropic sky — consistent with calculate_tiled()).
+
+ Saves three cache formats:
+ - memmap/ for fast reload in Python API
+ - svfs.zip for PrecomputedData.prepare() compatibility
+ - shadowmats.npz for anisotropic sky model (non-tiled only)
+
+ Args:
+ surface_data: SurfaceData instance to update with computed SVF.
+ aligned_rasters: Dictionary with aligned raster data.
+ working_path: Working directory for caching.
+ trunk_ratio: Trunk ratio for SVF computation.
+ on_tile_complete: Optional callback(tile_idx, n_tiles) called after each tile
+ (only invoked when tiling is used for large grids).
+ feedback: Optional QGIS QgsProcessingFeedback for progress/cancellation.
+ progress_range: Optional (start_pct, end_pct) for QGIS progress sub-range.
+ """
+
+ dsm_arr = aligned_rasters["dsm_arr"]
+ cdsm_arr = aligned_rasters["cdsm_arr"]
+ tdsm_arr = aligned_rasters["tdsm_arr"]
+ pixel_size = aligned_rasters.get("pixel_size", 1.0)
+
+ rows, cols = dsm_arr.shape
+ use_veg = cdsm_arr is not None
+ if use_veg:
+ logger.info("Computing SVF from DSM/CDSM/TDSM...")
+ else:
+ logger.info("Computing SVF from DSM...")
+
+ # Prepare vegetation arrays (Rust requires all three or none)
+ if use_veg:
+ cdsm_for_svf = cdsm_arr.astype(np.float32)
+ # Auto-generate TDSM if not provided
+ if tdsm_arr is not None:
+ tdsm_for_svf = tdsm_arr.astype(np.float32)
+ else:
+ tdsm_for_svf = (cdsm_arr * trunk_ratio).astype(np.float32)
+ else:
+ cdsm_for_svf = np.zeros_like(dsm_arr, dtype=np.float32)
+ tdsm_for_svf = np.zeros_like(dsm_arr, dtype=np.float32)
+
+ # Compute max height for SVF calculation
+ max_height = float(np.nanmax(dsm_arr))
+ if use_veg and cdsm_arr is not None:
+ veg_max = float(np.nanmax(cdsm_arr))
+ max_height = max(max_height, veg_max)
+
+ # Auto-detect whether tiling is needed based on GPU buffer limits.
+ # wgpu max buffer = 256 MiB. SVF staging uses ~32 bytes/pixel.
+ # Use 80% headroom to trigger tiling before hitting the limit.
+ _GPU_MAX_BUFFER = 268_435_456 # 256 MiB
+ _BYTES_PER_PIXEL = 32 # empirical: staging buffers for SVF
+ _max_pixels = int(_GPU_MAX_BUFFER * 0.8) // _BYTES_PER_PIXEL # ~6.7M pixels
+ needs_tiling = rows * cols > _max_pixels
+
+ svf_cache_dir = working_path / "svf"
+ svf_cache_dir.mkdir(parents=True, exist_ok=True)
+ metadata = CacheMetadata.from_arrays(dsm_arr, pixel_size, cdsm_arr)
+
+ if needs_tiling:
+ svf_data, (shmat_mm, vegshmat_mm, vbshmat_mm) = SurfaceData._compute_svf_tiled(
+ dsm_arr.astype(np.float32),
+ cdsm_for_svf,
+ tdsm_for_svf,
+ pixel_size,
+ use_veg,
+ max_height,
+ svf_cache_dir,
+ on_tile_complete=on_tile_complete,
+ feedback=feedback,
+ progress_range=progress_range,
+ )
+ n_patches = 153 # patch_option=2
+
+ # Cache SVF arrays
+ memmap_dir = svf_cache_dir / "memmap"
+ svf_data.to_memmap(memmap_dir, metadata=metadata)
+ _save_svfs_zip(svf_data, svf_cache_dir, aligned_rasters)
+
+ # Save shadow matrices as npz for cache reload on future runs
+ shadow_path = svf_cache_dir / "shadowmats.npz"
+ np.savez_compressed(
+ str(shadow_path),
+ shadowmat=np.asarray(shmat_mm),
+ vegshadowmat=np.asarray(vegshmat_mm),
+ vbshmat=np.asarray(vbshmat_mm),
+ patch_count=np.array(n_patches),
+ )
+ logger.info(f" ✓ Shadow matrices saved as {shadow_path}")
+
+ surface_data.svf = svf_data
+ # Shadow matrices assembled from tiled memmaps (bitpacked uint8, on disk)
+ surface_data.shadow_matrices = ShadowArrays(
+ _shmat_u8=shmat_mm,
+ _vegshmat_u8=vegshmat_mm,
+ _vbshmat_u8=vbshmat_mm,
+ _n_patches=n_patches,
+ )
+ logger.info(f" ✓ SVF computed (tiled) and cached to {svf_cache_dir}")
+ else:
+ # Single-shot computation for grids that fit in GPU memory.
+ # Use SkyviewRunner with threading + polling for progress and cancel.
+ import threading
+
+ from ..progress import ProgressReporter
+
+ n_patches = 153 # patch_option=2
+
+ runner = skyview.SkyviewRunner()
+ result_box: list = [None]
+ error_box: list = [None]
+
+ def _run_svf():
+ try:
+ result_box[0] = runner.calculate_svf(
+ dsm_arr.astype(np.float32),
+ cdsm_for_svf,
+ tdsm_for_svf,
+ pixel_size,
+ use_veg,
+ max_height,
+ 2, # patch_option
+ 3.0, # min_sun_elev_deg
+ )
+ except Exception as e:
+ error_box[0] = e
+
+ thread = threading.Thread(target=_run_svf, daemon=True)
+ thread.start()
+
+ # Poll progress (153 patches)
+ pbar = ProgressReporter(
+ total=n_patches,
+ desc="Computing Sky View Factor",
+ feedback=feedback,
+ progress_range=progress_range,
+ )
+ last = 0
+ while thread.is_alive():
+ thread.join(timeout=0.05)
+ done = runner.progress()
+ if done > last:
+ pbar.update(done - last)
+ last = done
+ # Check QGIS cancellation
+ if feedback is not None and hasattr(feedback, "isCanceled") and feedback.isCanceled():
+ runner.cancel()
+ thread.join(timeout=5.0)
+ pbar.close()
+ return
+ if last < n_patches:
+ pbar.update(n_patches - last)
+ pbar.close()
+
+ thread.join()
+ if error_box[0] is not None:
+ raise error_box[0]
+ svf_result = result_box[0]
+
+ ones = np.ones_like(dsm_arr, dtype=np.float32)
+
+ svf_data = SvfArrays(
+ svf=np.array(svf_result.svf),
+ svf_north=np.array(svf_result.svf_north),
+ svf_east=np.array(svf_result.svf_east),
+ svf_south=np.array(svf_result.svf_south),
+ svf_west=np.array(svf_result.svf_west),
+ svf_veg=np.array(svf_result.svf_veg) if use_veg else ones.copy(),
+ svf_veg_north=np.array(svf_result.svf_veg_north) if use_veg else ones.copy(),
+ svf_veg_east=np.array(svf_result.svf_veg_east) if use_veg else ones.copy(),
+ svf_veg_south=np.array(svf_result.svf_veg_south) if use_veg else ones.copy(),
+ svf_veg_west=np.array(svf_result.svf_veg_west) if use_veg else ones.copy(),
+ svf_aveg=np.array(svf_result.svf_veg_blocks_bldg_sh) if use_veg else ones.copy(),
+ svf_aveg_north=np.array(svf_result.svf_veg_blocks_bldg_sh_north) if use_veg else ones.copy(),
+ svf_aveg_east=np.array(svf_result.svf_veg_blocks_bldg_sh_east) if use_veg else ones.copy(),
+ svf_aveg_south=np.array(svf_result.svf_veg_blocks_bldg_sh_south) if use_veg else ones.copy(),
+ svf_aveg_west=np.array(svf_result.svf_veg_blocks_bldg_sh_west) if use_veg else ones.copy(),
+ )
+
+ # Cache SVF arrays
+ memmap_dir = svf_cache_dir / "memmap"
+ svf_data.to_memmap(memmap_dir, metadata=metadata)
+ _save_svfs_zip(svf_data, svf_cache_dir, aligned_rasters)
+
+ # Save shadow matrices (only available in non-tiled mode)
+ _save_shadow_matrices(svf_result, svf_cache_dir)
+
+ surface_data.svf = svf_data
+
+ # Shadow matrices are bitpacked uint8 from Rust
+ surface_data.shadow_matrices = ShadowArrays(
+ _shmat_u8=np.array(svf_result.bldg_sh_matrix),
+ _vegshmat_u8=np.array(svf_result.veg_sh_matrix),
+ _vbshmat_u8=np.array(svf_result.veg_blocks_bldg_sh_matrix),
+ _n_patches=n_patches,
+ )
+
+ logger.info(f" ✓ SVF computed and cached to {svf_cache_dir}")
+
+ @staticmethod
+ def _compute_svf_tiled(
+ dsm_f32: np.ndarray,
+ cdsm_f32: np.ndarray,
+ tdsm_f32: np.ndarray,
+ pixel_size: float,
+ use_veg: bool,
+ max_height: float,
+ working_path: Path,
+ on_tile_complete: Callable | None = None,
+ feedback: Any = None,
+ progress_range: tuple[float, float] | None = None,
+ ) -> tuple[SvfArrays, tuple[np.ndarray, np.ndarray, np.ndarray]]:
+ """
+ Compute SVF using tiled processing for large grids.
+
+ Automatically determines the largest safe tile size from the GPU
+ buffer limit, divides the grid into overlapping tiles, computes
+ SVF per tile, and stitches the core regions into full-size arrays.
+
+ Shadow matrices are assembled into memory-mapped bitpacked uint8 files to
+ avoid holding the full 3D arrays in RAM.
+
+ Args:
+ dsm_f32: DSM array (float32).
+ cdsm_f32: Canopy DSM array (float32, zeros if no veg).
+ tdsm_f32: Trunk DSM array (float32, zeros if no veg).
+ pixel_size: Pixel size in meters.
+ use_veg: Whether vegetation is present.
+ max_height: Maximum height in the DSM (for buffer calculation).
+ working_path: Directory for memmap files.
+ on_tile_complete: Optional callback(tile_idx, n_tiles) called after each tile.
+
+ Returns:
+ Tuple of (SvfArrays, (shmat_mm, vegshmat_mm, vbshmat_mm))
+ where the shadow matrix memmaps are bitpacked uint8 (rows, cols, n_pack).
+ """
+ from ..progress import ProgressReporter
+ from ..tiling import calculate_buffer_distance, generate_tiles, validate_tile_size
+
+ rows, cols = dsm_f32.shape
+
+ buffer_m = calculate_buffer_distance(max_height)
+ buffer_pixels = int(np.ceil(buffer_m / pixel_size))
+
+ # Compute the largest safe tile size from GPU buffer limit.
+ # The tile includes overlap buffers on each side, so the full tile
+ # (core + 2*buffer) must fit in GPU memory.
+ # wgpu max buffer = 256MB. SVF uses ~32 bytes/pixel for staging
+ # buffers (shadow matrices, intermediate arrays). Use 80% headroom.
+ _GPU_MAX_BUFFER = 268_435_456 # 256 MiB
+ _BYTES_PER_PIXEL = 32 # empirical: staging buffers for SVF
+ max_tile_pixels = int(_GPU_MAX_BUFFER * 0.8) // _BYTES_PER_PIXEL
+ # Full tile side = core + 2*buffer, so core = sqrt(max_pixels) - 2*buffer
+ max_full_side = int(max_tile_pixels**0.5)
+ tile_size = max(256, max_full_side - 2 * buffer_pixels)
+
+ adjusted_tile_size, warning = validate_tile_size(tile_size, buffer_pixels, pixel_size)
+ if warning:
+ logger.warning(warning)
+
+ tiles = generate_tiles(rows, cols, adjusted_tile_size, buffer_pixels)
+ n_tiles = len(tiles)
+
+ # Determine patch count from a small probe (patch_option=2 → 153 patches)
+ n_patches = 153
+
+ logger.info(
+ f" Tiled SVF: {rows}x{cols} raster, {n_tiles} tiles, "
+ f"tile_size={adjusted_tile_size}, buffer={buffer_m:.0f}m ({buffer_pixels}px)"
+ )
+
+ # SVF field names on the Rust result object
+ svf_fields = ["svf", "svf_north", "svf_east", "svf_south", "svf_west"]
+ veg_fields = [
+ "svf_veg",
+ "svf_veg_north",
+ "svf_veg_east",
+ "svf_veg_south",
+ "svf_veg_west",
+ "svf_veg_blocks_bldg_sh",
+ "svf_veg_blocks_bldg_sh_north",
+ "svf_veg_blocks_bldg_sh_east",
+ "svf_veg_blocks_bldg_sh_south",
+ "svf_veg_blocks_bldg_sh_west",
+ ]
+ all_fields = svf_fields + veg_fields
+
+ # Pre-allocate output arrays (ones = default SVF for unprocessed edges)
+ outputs: dict[str, np.ndarray] = {}
+ for name in all_fields:
+ outputs[name] = np.ones((rows, cols), dtype=np.float32)
+
+ # Pre-allocate memmap files for shadow matrices (bitpacked uint8, on disk)
+ memmap_dir = working_path / "shadow_memmaps"
+ memmap_dir.mkdir(parents=True, exist_ok=True)
+ n_pack = (n_patches + 7) // 8 # ceil(153/8) = 20
+ sh_shape = (rows, cols, n_pack)
+ shmat_mm = np.memmap(
+ memmap_dir / "shmat.dat",
+ dtype=np.uint8,
+ mode="w+",
+ shape=sh_shape,
+ )
+ vegshmat_mm = np.memmap(
+ memmap_dir / "vegshmat.dat",
+ dtype=np.uint8,
+ mode="w+",
+ shape=sh_shape,
+ )
+ vbshmat_mm = np.memmap(
+ memmap_dir / "vbshmat.dat",
+ dtype=np.uint8,
+ mode="w+",
+ shape=sh_shape,
+ )
+
+ pbar = ProgressReporter(
+ total=n_tiles,
+ desc="Computing SVF (tiled)",
+ feedback=feedback,
+ progress_range=progress_range,
+ )
+
+ # Pipeline: overlap GPU computation of tile N+1 with CPU
+ # result-copying of tile N. calculate_svf releases the GIL
+ # inside py.allow_threads(), so a background thread can drive
+ # the GPU while the main thread does numpy bookkeeping.
+ import threading
+
+ def _submit_tile(tile):
+ """Prepare inputs and run SVF on background thread."""
+ rs = tile.read_slice
+ td = dsm_f32[rs].copy()
+ tc = cdsm_f32[rs].copy()
+ tt = tdsm_f32[rs].copy()
+ mh = float(np.nanmax(td))
+ if use_veg:
+ mh = max(mh, float(np.nanmax(tc)))
+ box = [None, None] # [result, error]
+
+ def _run():
+ try:
+ box[0] = skyview.calculate_svf(
+ td,
+ tc,
+ tt,
+ pixel_size,
+ use_veg,
+ mh,
+ 2,
+ 3.0,
+ None,
+ )
+ except Exception as e:
+ box[1] = e
+
+ t = threading.Thread(target=_run, daemon=True)
+ t.start()
+ return t, box
+
+ def _process_result(tile_result, tile):
+ """Copy SVF + shadow matrices from a completed tile."""
+ cs = tile.core_slice
+ ws = tile.write_slice
+ for name in svf_fields:
+ outputs[name][ws] = np.array(getattr(tile_result, name))[cs]
+ if use_veg:
+ for name in veg_fields:
+ outputs[name][ws] = np.array(getattr(tile_result, name))[cs]
+ # Shadow matrices are already bitpacked uint8 from Rust
+ for src_name, mm in [
+ ("bldg_sh_matrix", shmat_mm),
+ ("veg_sh_matrix", vegshmat_mm),
+ ("veg_blocks_bldg_sh_matrix", vbshmat_mm),
+ ]:
+ arr = np.array(getattr(tile_result, src_name))
+ mm[ws] = arr[cs]
+
+ # Kick off first tile
+ thread, box = _submit_tile(tiles[0])
+
+ for tile_idx in range(n_tiles):
+ pbar.set_description(f"SVF tile {tile_idx + 1}/{n_tiles}")
+ pbar.set_text(f"Computing SVF — Tile {tile_idx + 1}/{n_tiles}")
+ # Wait for current tile to finish
+ thread.join()
+ if box[1] is not None:
+ raise box[1]
+ cur_result = box[0]
+ cur_tile = tiles[tile_idx]
+
+ # Submit next tile (GPU starts while we copy results below)
+ if tile_idx + 1 < n_tiles:
+ thread, box = _submit_tile(tiles[tile_idx + 1])
+
+ # Copy results on main thread (overlaps with next GPU computation)
+ _process_result(cur_result, cur_tile)
+ pbar.update(1)
+ if on_tile_complete is not None:
+ on_tile_complete(tile_idx, n_tiles)
+ # Check QGIS cancellation between tiles
+ if pbar.is_cancelled():
+ pbar.close()
+ logger.info(" SVF computation cancelled by user")
+ break
+
+ pbar.close()
+ # Flush memmaps to disk
+ shmat_mm.flush()
+ vegshmat_mm.flush()
+ vbshmat_mm.flush()
+
+ ones = np.ones((rows, cols), dtype=np.float32)
+
+ svf_data = SvfArrays(
+ svf=outputs["svf"],
+ svf_north=outputs["svf_north"],
+ svf_east=outputs["svf_east"],
+ svf_south=outputs["svf_south"],
+ svf_west=outputs["svf_west"],
+ svf_veg=outputs["svf_veg"] if use_veg else ones.copy(),
+ svf_veg_north=outputs["svf_veg_north"] if use_veg else ones.copy(),
+ svf_veg_east=outputs["svf_veg_east"] if use_veg else ones.copy(),
+ svf_veg_south=outputs["svf_veg_south"] if use_veg else ones.copy(),
+ svf_veg_west=outputs["svf_veg_west"] if use_veg else ones.copy(),
+ svf_aveg=outputs["svf_veg_blocks_bldg_sh"] if use_veg else ones.copy(),
+ svf_aveg_north=outputs["svf_veg_blocks_bldg_sh_north"] if use_veg else ones.copy(),
+ svf_aveg_east=outputs["svf_veg_blocks_bldg_sh_east"] if use_veg else ones.copy(),
+ svf_aveg_south=outputs["svf_veg_blocks_bldg_sh_south"] if use_veg else ones.copy(),
+ svf_aveg_west=outputs["svf_veg_blocks_bldg_sh_west"] if use_veg else ones.copy(),
+ )
+
+ return svf_data, (shmat_mm, vegshmat_mm, vbshmat_mm)
+
+ def preprocess(self) -> None:
+ """
+ Convert layers from relative to absolute heights based on per-layer flags.
+
+ Converts each layer that is flagged as relative (``dsm_relative``,
+ ``cdsm_relative``, ``tdsm_relative``) to absolute heights. Layers
+ already flagged as absolute are left unchanged.
+
+ This method:
+ 1. Converts DSM from relative to absolute if ``dsm_relative=True``
+ (requires DEM: ``dsm_absolute = dem + dsm_relative``)
+ 2. Auto-generates TDSM from CDSM * trunk_ratio if TDSM is not provided
+ 3. Converts CDSM from relative to absolute if ``cdsm_relative=True``
+ 4. Converts TDSM from relative to absolute if ``tdsm_relative=True``
+ 5. Zeros out vegetation pixels with height < 0.1m
+
+ Note:
+ This method modifies arrays in-place and clears the per-layer
+ relative flags once conversion is done.
+ """
+ if self._preprocessed:
+ return
+
+ # Fill NaN in surface layers before any height conversion
+ self.fill_nan()
+
+ threshold = np.float32(0.1)
+ zero32 = np.float32(0.0)
+ nan32 = np.float32(np.nan)
+
+ # Step 1: Convert DSM from relative to absolute (requires DEM)
+ if self.dsm_relative:
+ if self.dem is None:
+ raise ValueError(
+ "DSM is flagged as relative (dsm_relative=True) but no DEM "
+ "is provided. A DEM is required to convert relative DSM "
+ "(height above ground) to absolute elevations."
+ )
+ logger.info("Converting relative DSM to absolute: DSM = DEM + nDSM")
+ self.dsm = (self.dem + self.dsm).astype(np.float32)
+ self.dsm_relative = False
+
+ # Step 2: Auto-generate TDSM from trunk ratio if CDSM provided but not TDSM
+ if self.cdsm is not None and self.tdsm is None:
+ logger.info(f"Auto-generating TDSM from CDSM using trunk_ratio={self.trunk_ratio}")
+ self.tdsm = (self.cdsm * self.trunk_ratio).astype(np.float32)
+ self.tdsm_relative = self.cdsm_relative
+
+ # Use DEM as base if available, otherwise DSM (now absolute after step 1)
+ base = self.dem if self.dem is not None else self.dsm
+
+ # Step 3: Convert CDSM from relative to absolute
+ if self.cdsm_relative and self.cdsm is not None:
+ cdsm_rel = np.where(np.isnan(self.cdsm), zero32, self.cdsm)
+ cdsm_abs = np.where(~np.isnan(base), base + cdsm_rel, nan32)
+ cdsm_abs = np.where(cdsm_abs - base < threshold, zero32, cdsm_abs)
+ self.cdsm = cdsm_abs.astype(np.float32)
+ self.cdsm_relative = False
+ logger.info(f"Converted relative CDSM to absolute (base: {'DEM' if self.dem is not None else 'DSM'})")
+
+ # Step 4: Convert TDSM from relative to absolute
+ if self.tdsm_relative and self.tdsm is not None:
+ tdsm_rel = np.where(np.isnan(self.tdsm), zero32, self.tdsm)
+ tdsm_abs = np.where(~np.isnan(base), base + tdsm_rel, nan32)
+ tdsm_abs = np.where(tdsm_abs - base < threshold, zero32, tdsm_abs)
+ self.tdsm = tdsm_abs.astype(np.float32)
+ self.tdsm_relative = False
+ logger.info(f"Converted relative TDSM to absolute (base: {'DEM' if self.dem is not None else 'DSM'})")
+
+ self._preprocessed = True
+
+ def compute_svf(self) -> None:
+ """
+ Compute Sky View Factor (SVF) and store in self.svf.
+
+ This must be called before calculate() or calculate_timeseries()
+ when constructing SurfaceData manually (not via prepare()).
+
+ SVF is stored without psi (vegetation transmissivity) adjustment,
+ since psi depends on day-of-year and conifer flag which are not
+ known at SVF computation time. The adjustment is applied automatically
+ during calculation.
+
+ Also computes and stores shadow matrices in self.shadow_matrices
+ (required for anisotropic sky model).
+
+ Example:
+ surface = SurfaceData(dsm=dsm, cdsm=cdsm)
+ surface.preprocess()
+ surface.compute_svf()
+ result = calculate(surface, location, weather)
+ """
+ if self.svf is not None:
+ return # Already computed
+
+ use_veg = self.cdsm is not None
+ dsm_f32 = self.dsm.astype(np.float32)
+
+ if use_veg:
+ assert self.cdsm is not None # Type narrowing for type checker
+ cdsm_f32 = self.cdsm.astype(np.float32)
+ if self.tdsm is not None:
+ tdsm_f32 = self.tdsm.astype(np.float32)
+ else:
+ tdsm_f32 = (self.cdsm * self.trunk_ratio).astype(np.float32)
+ else:
+ cdsm_f32 = np.zeros_like(dsm_f32)
+ tdsm_f32 = np.zeros_like(dsm_f32)
+
+ max_height = float(np.nanmax(dsm_f32))
+ if use_veg:
+ veg_max = float(np.nanmax(cdsm_f32))
+ max_height = max(max_height, veg_max)
+
+ logger.info("Computing Sky View Factor...")
+ svf_result = skyview.calculate_svf(
+ dsm_f32,
+ cdsm_f32,
+ tdsm_f32,
+ self.pixel_size,
+ use_veg,
+ max_height,
+ 2, # patch_option (153 patches)
+ 3.0, # min_sun_elev_deg
+ None, # progress callback
+ )
+
+ ones = np.ones_like(dsm_f32)
+ self.svf = SvfArrays(
+ svf=np.array(svf_result.svf),
+ svf_north=np.array(svf_result.svf_north),
+ svf_east=np.array(svf_result.svf_east),
+ svf_south=np.array(svf_result.svf_south),
+ svf_west=np.array(svf_result.svf_west),
+ svf_veg=np.array(svf_result.svf_veg) if use_veg else ones.copy(),
+ svf_veg_north=np.array(svf_result.svf_veg_north) if use_veg else ones.copy(),
+ svf_veg_east=np.array(svf_result.svf_veg_east) if use_veg else ones.copy(),
+ svf_veg_south=np.array(svf_result.svf_veg_south) if use_veg else ones.copy(),
+ svf_veg_west=np.array(svf_result.svf_veg_west) if use_veg else ones.copy(),
+ svf_aveg=np.array(svf_result.svf_veg_blocks_bldg_sh) if use_veg else ones.copy(),
+ svf_aveg_north=np.array(svf_result.svf_veg_blocks_bldg_sh_north) if use_veg else ones.copy(),
+ svf_aveg_east=np.array(svf_result.svf_veg_blocks_bldg_sh_east) if use_veg else ones.copy(),
+ svf_aveg_south=np.array(svf_result.svf_veg_blocks_bldg_sh_south) if use_veg else ones.copy(),
+ svf_aveg_west=np.array(svf_result.svf_veg_blocks_bldg_sh_west) if use_veg else ones.copy(),
+ )
+
+ # Store shadow matrices for anisotropic sky model
+ # Shadow matrices are bitpacked uint8 from Rust
+ self.shadow_matrices = ShadowArrays(
+ _shmat_u8=np.array(svf_result.bldg_sh_matrix),
+ _vegshmat_u8=np.array(svf_result.veg_sh_matrix),
+ _vbshmat_u8=np.array(svf_result.veg_blocks_bldg_sh_matrix),
+ _n_patches=153, # patch_option=2
+ )
+
+ logger.info(" SVF computed successfully")
+
+ @property
+ def max_height(self) -> float:
+ """Auto-compute maximum height difference for shadow buffer calculation.
+
+ Considers both DSM (buildings) and CDSM (vegetation) since both cast shadows.
+ Returns max elevation minus ground level.
+ """
+ dsm_max = float(np.nanmax(self.dsm))
+ ground_min = float(np.nanmin(self.dsm))
+
+ # Also consider vegetation if present (CDSM may be taller than buildings)
+ if self.cdsm is not None:
+ cdsm_max = float(np.nanmax(self.cdsm))
+ # After preprocessing, CDSM contains absolute elevations
+ # Use the higher of DSM or CDSM
+ max_elevation = max(dsm_max, cdsm_max)
+ else:
+ max_elevation = dsm_max
+
+ return max_elevation - ground_min
+
+ @property
+ def shape(self) -> tuple[int, int]:
+ """Return DSM shape (rows, cols)."""
+ rows, cols = self.dsm.shape
+ return (rows, cols)
+
+ @property
+ def crs(self) -> str | None:
+ """Return CRS as WKT string, or None if not set."""
+ return self._crs_wkt
+
+ @property
+ def valid_mask(self) -> NDArray[np.bool_] | None:
+ """Return computed valid mask, or None if not yet computed."""
+ return self._valid_mask
+
+ def fill_nan(self, tolerance: float = 0.1) -> None:
+ """Fill NaN in surface layers using DEM as ground reference.
+
+ NaN in DSM/CDSM/TDSM means "no data, assume ground level."
+ After filling, values within *tolerance* of ground are clamped
+ to exactly the ground value to avoid shadow/SVF noise from
+ resampling jitter.
+
+ Fill rules:
+ - DSM NaN → DEM value (if DEM provided, else left as NaN)
+ - CDSM NaN → base value (DEM if available, else DSM)
+ - TDSM NaN → base value (DEM if available, else DSM)
+ - DEM NaN → not filled (DEM is the ground-truth baseline)
+
+ Works identically for relative and absolute height conventions.
+
+ Args:
+ tolerance: Height difference (m) below which a surface pixel
+ is considered "at ground" and clamped. Default 0.1 m.
+ """
+ if self._nan_filled:
+ return
+
+ tol = np.float32(tolerance)
+
+ # DSM: fill with DEM where available
+ if self.dem is not None:
+ dsm_nan = np.isnan(self.dsm)
+ if np.any(dsm_nan):
+ n = int(dsm_nan.sum())
+ self.dsm = np.where(dsm_nan, self.dem, self.dsm).astype(np.float32)
+ logger.info(f" Filled {n} NaN DSM pixels with DEM")
+
+ base = self.dem if self.dem is not None else self.dsm
+ base_label = "DEM" if self.dem is not None else "DSM"
+
+ # CDSM: fill NaN with base, clamp near-ground noise
+ if self.cdsm is not None:
+ cdsm_nan = np.isnan(self.cdsm)
+ if np.any(cdsm_nan):
+ n = int(cdsm_nan.sum())
+ self.cdsm = np.where(cdsm_nan, base, self.cdsm).astype(np.float32)
+ logger.info(f" Filled {n} NaN CDSM pixels with {base_label}")
+ near_ground = np.abs(self.cdsm - base) < tol
+ if np.any(near_ground):
+ self.cdsm = np.where(near_ground, base, self.cdsm).astype(np.float32)
+
+ # TDSM: same treatment as CDSM
+ if self.tdsm is not None:
+ tdsm_nan = np.isnan(self.tdsm)
+ if np.any(tdsm_nan):
+ n = int(tdsm_nan.sum())
+ self.tdsm = np.where(tdsm_nan, base, self.tdsm).astype(np.float32)
+ logger.info(f" Filled {n} NaN TDSM pixels with {base_label}")
+ near_ground = np.abs(self.tdsm - base) < tol
+ if np.any(near_ground):
+ self.tdsm = np.where(near_ground, base, self.tdsm).astype(np.float32)
+
+ self._nan_filled = True
+
+ def compute_valid_mask(self) -> NDArray[np.bool_]:
+ """Compute combined valid mask: True where ALL ground-reference layers have finite data.
+
+ A pixel is valid only if DSM (and DEM/walls if provided) have finite values.
+ CDSM/TDSM are excluded — NaN vegetation means "at ground", not "invalid pixel".
+ Call fill_nan() before this to fill vegetation NaN with ground values.
+
+ Returns:
+ Boolean array with same shape as DSM. True = valid pixel.
+ """
+ valid = np.isfinite(self.dsm)
+ for arr in [self.dem, self.wall_height, self.wall_aspect]:
+ if arr is not None:
+ valid &= np.isfinite(arr)
+ if self.land_cover is not None:
+ valid &= self.land_cover != 255
+ self._valid_mask = valid
+ n_invalid = int(np.sum(~valid))
+ if n_invalid > 0:
+ pct = 100.0 * n_invalid / valid.size
+ logger.info(f" Valid mask: {n_invalid} invalid pixels ({pct:.1f}%)")
+ else:
+ logger.info(" Valid mask: all pixels valid")
+ return valid
+
+ def apply_valid_mask(self) -> None:
+ """Set NaN in ALL layers where ANY layer has nodata.
+
+ Ensures consistent nodata across all surface arrays.
+ Must call compute_valid_mask() first (or it will be called automatically).
+ """
+ if self._valid_mask is None:
+ self.compute_valid_mask()
+ assert self._valid_mask is not None # set by compute_valid_mask
+ invalid = ~self._valid_mask
+ if not np.any(invalid):
+ return
+ self.dsm[invalid] = np.nan
+ for attr in ("cdsm", "dem", "tdsm", "wall_height", "wall_aspect", "albedo", "emissivity"):
+ arr = getattr(self, attr)
+ if arr is not None:
+ arr[invalid] = np.nan
+ if self.land_cover is not None:
+ self.land_cover[invalid] = 255
+
+ def crop_to_valid_bbox(self) -> tuple[int, int, int, int]:
+ """Crop all arrays to minimum bounding box of valid pixels.
+
+ Eliminates edge NaN bands to reduce wasted computation.
+ Updates geotransform to reflect the new origin.
+
+ Returns:
+ (row_start, row_end, col_start, col_end) of the crop window.
+ """
+ if self._valid_mask is None:
+ self.compute_valid_mask()
+ assert self._valid_mask is not None # set by compute_valid_mask
+ rows_any = np.any(self._valid_mask, axis=1)
+ cols_any = np.any(self._valid_mask, axis=0)
+ if not np.any(rows_any):
+ logger.warning(" No valid pixels found — cannot crop")
+ return (0, self.dsm.shape[0], 0, self.dsm.shape[1])
+ r0 = int(np.argmax(rows_any))
+ r1 = len(rows_any) - int(np.argmax(rows_any[::-1]))
+ c0 = int(np.argmax(cols_any))
+ c1 = len(cols_any) - int(np.argmax(cols_any[::-1]))
+
+ if r0 == 0 and r1 == self.dsm.shape[0] and c0 == 0 and c1 == self.dsm.shape[1]:
+ logger.info(" Crop: no trimming needed (valid bbox = full extent)")
+ return (r0, r1, c0, c1)
+
+ old_shape = self.dsm.shape
+ self.dsm = self.dsm[r0:r1, c0:c1].copy()
+ self._valid_mask = self._valid_mask[r0:r1, c0:c1].copy()
+ for attr in ("cdsm", "dem", "tdsm", "wall_height", "wall_aspect", "albedo", "emissivity", "land_cover"):
+ arr = getattr(self, attr)
+ if arr is not None:
+ setattr(self, attr, arr[r0:r1, c0:c1].copy())
+
+ # Update geotransform to reflect new origin
+ if self._geotransform is not None:
+ gt = self._geotransform
+ self._geotransform = [
+ gt[0] + c0 * gt[1] + r0 * gt[2], # new origin X
+ gt[1],
+ gt[2],
+ gt[3] + c0 * gt[4] + r0 * gt[5], # new origin Y
+ gt[4],
+ gt[5],
+ ]
+
+ # Crop SVF arrays if present
+ if self.svf is not None:
+ self.svf = self.svf.crop(r0, r1, c0, c1)
+ if self.shadow_matrices is not None:
+ self.shadow_matrices = self.shadow_matrices.crop(r0, r1, c0, c1)
+
+ # Clear buffer pool (shape changed)
+ self.clear_buffers()
+
+ logger.info(f" Cropped: {old_shape[1]}x{old_shape[0]} → {c1 - c0}x{r1 - r0} pixels")
+ return (r0, r1, c0, c1)
+
+ def save_cleaned(self, output_dir: str | Path) -> None:
+ """Save cleaned, aligned rasters to disk for inspection.
+
+ Writes all present layers to output_dir/cleaned/ as GeoTIFFs.
+
+ Args:
+ output_dir: Parent directory. Files are saved under output_dir/cleaned/.
+ """
+ out = Path(output_dir) / "cleaned"
+ out.mkdir(parents=True, exist_ok=True)
+ gt = self._geotransform or [0, self.pixel_size, 0, 0, 0, -self.pixel_size]
+ crs = self._crs_wkt or ""
+ io.save_raster(str(out / "dsm.tif"), self.dsm, gt, crs)
+ for name, arr in [
+ ("cdsm", self.cdsm),
+ ("dem", self.dem),
+ ("tdsm", self.tdsm),
+ ("wall_height", self.wall_height),
+ ("wall_aspect", self.wall_aspect),
+ ]:
+ if arr is not None:
+ io.save_raster(str(out / f"{name}.tif"), arr, gt, crs)
+ if self.land_cover is not None:
+ io.save_raster(str(out / "land_cover.tif"), self.land_cover.astype(np.float32), gt, crs)
+ if self._valid_mask is not None:
+ io.save_raster(str(out / "valid_mask.tif"), self._valid_mask.astype(np.float32), gt, crs)
+ logger.info(f" Cleaned rasters saved to {out}")
+
+ def get_buffer_pool(self) -> BufferPool:
+ """Get or create a buffer pool for this surface.
+
+ The buffer pool provides pre-allocated numpy arrays that can be
+ reused across timesteps during timeseries calculations. This
+ reduces memory allocation overhead and GC pressure.
+
+ Returns:
+ BufferPool sized to this surface's grid dimensions.
+
+ Example:
+ pool = surface.get_buffer_pool()
+ temp = pool.get_zeros("ani_lum") # First call allocates
+ temp = pool.get_zeros("ani_lum") # Second call reuses same memory
+ """
+ if self._buffer_pool is None:
+ self._buffer_pool = BufferPool(self.shape)
+ return self._buffer_pool
+
+ def clear_buffers(self) -> None:
+ """Clear the buffer pool to free memory.
+
+ Call this after completing a timeseries calculation to release
+ the pre-allocated arrays.
+ """
+ if self._buffer_pool is not None:
+ self._buffer_pool.clear()
+ self._buffer_pool = None
+
+ def _looks_like_relative_heights(self) -> bool:
+ """
+ Heuristic check if CDSM appears to contain relative heights.
+
+ Returns True if max(CDSM) is much smaller than min(DSM), suggesting
+ CDSM contains height-above-ground values rather than absolute elevations.
+
+ This is used to warn users who may have forgotten to call preprocess().
+ """
+ if self.cdsm is None:
+ return False
+
+ cdsm_max = np.nanmax(self.cdsm)
+ dsm_min = np.nanmin(self.dsm)
+
+ # If CDSM max is much smaller than DSM min, it's likely relative heights
+ # Typical case: DSM min ~100m elevation, CDSM max ~30m tree height
+ # Exception: coastal areas where DSM min could be near 0
+ if dsm_min > 10 and cdsm_max < dsm_min * 0.5:
+ return True
+
+ # Also check if CDSM values are typical vegetation heights (0-50m range)
+ # while DSM has larger values
+ return bool(cdsm_max < 60 and dsm_min > cdsm_max + 20)
+
+ def _check_preprocessing_needed(self) -> None:
+ """
+ Warn if CDSM appears to need preprocessing but wasn't preprocessed.
+
+ Called internally before calculations to alert users.
+ """
+ if self.cdsm is None:
+ return
+
+ if self.cdsm_relative and not self._preprocessed and self._looks_like_relative_heights():
+ logger.warning(
+ f"CDSM appears to contain relative vegetation heights "
+ f"(max CDSM={np.nanmax(self.cdsm):.1f}m < min DSM={np.nanmin(self.dsm):.1f}m), "
+ f"but preprocess() was not called. "
+ f"Call surface.preprocess() to convert to absolute heights, "
+ f"or set cdsm_relative=False if CDSM already contains absolute elevations."
+ )
+
+ def get_land_cover_properties(
+ self,
+ params: SimpleNamespace | None = None,
+ ) -> tuple[
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+ NDArray[np.floating],
+ ]:
+ """
+ Derive surface properties from land cover grid.
+
+ Args:
+ params: Optional loaded parameters from JSON file (via load_params()).
+ When provided, land cover properties are read from the params.
+ When None, uses built-in defaults matching parametersforsolweig.json.
+
+ Returns:
+ Tuple of (albedo_grid, emissivity_grid, tgk_grid, tstart_grid, tmaxlst_grid).
+ If land_cover is None, returns defaults.
+
+ Land cover parameters from Lindberg et al. 2008, 2016 (parametersforsolweig.json):
+ - TgK (Ts_deg): Temperature coefficient for surface heating
+ - Tstart: Temperature offset at sunrise
+ - TmaxLST: Hour of maximum local surface temperature
+ """
+ if self.land_cover is None:
+ # Use provided grids or defaults
+ alb = self.albedo if self.albedo is not None else np.full_like(self.dsm, 0.15)
+ emis = self.emissivity if self.emissivity is not None else np.full_like(self.dsm, 0.95)
+ tgk = np.full_like(self.dsm, 0.37) # Default TgK (cobblestone)
+ tstart = np.full_like(self.dsm, -3.41) # Default Tstart (cobblestone)
+ tmaxlst = np.full_like(self.dsm, 15.0) # Default TmaxLST (cobblestone)
+ return alb, emis, tgk, tstart, tmaxlst
+
+ # If params provided, use the helper function to extract from JSON
+ if params is not None:
+ return get_lc_properties_from_params(self.land_cover, params, self.shape)
+
+ # UMEP standard land cover properties from parametersforsolweig.json
+ # ID: (albedo, emissivity, TgK, Tstart, TmaxLST)
+ # Values must match the JSON parameters file for parity with runner
+ lc_properties = {
+ 0: (0.20, 0.95, 0.37, -3.41, 15.0), # Paved/cobblestone (Cobble_stone_2014a)
+ 1: (0.18, 0.95, 0.58, -9.78, 15.0), # Dark asphalt (albedo from JSON)
+ 2: (0.18, 0.95, 0.58, -9.78, 15.0), # Buildings/roofs (emissivity=0.95, albedo=0.18)
+ 3: (0.20, 0.95, 0.37, -3.41, 15.0), # Undefined (use paved defaults)
+ 4: (0.20, 0.95, 0.37, -3.41, 15.0), # Undefined (use paved defaults)
+ 5: (0.16, 0.94, 0.21, -3.38, 14.0), # Grass (Grass_unmanaged) - albedo=0.16, emis=0.94
+ 6: (0.25, 0.94, 0.33, -3.01, 14.0), # Bare soil - emis=0.94
+ 7: (0.05, 0.98, 0.00, 0.00, 12.0), # Water - albedo=0.05
+ }
+
+ rows, cols = self.shape
+ alb_grid = np.full((rows, cols), 0.15, dtype=np.float32)
+ emis_grid = np.full((rows, cols), 0.95, dtype=np.float32)
+ tgk_grid = np.full((rows, cols), 0.37, dtype=np.float32)
+ tstart_grid = np.full((rows, cols), -3.41, dtype=np.float32)
+ tmaxlst_grid = np.full((rows, cols), 15.0, dtype=np.float32)
+
+ lc = self.land_cover
+ for lc_id, (alb, emis, tgk, tstart, tmaxlst) in lc_properties.items():
+ mask = lc == lc_id
+ if np.any(mask):
+ alb_grid[mask] = alb
+ emis_grid[mask] = emis
+ tgk_grid[mask] = tgk
+ tstart_grid[mask] = tstart
+ tmaxlst_grid[mask] = tmaxlst
+
+ return alb_grid, emis_grid, tgk_grid, tstart_grid, tmaxlst_grid
diff --git a/pysrc/solweig/models/weather.py b/pysrc/solweig/models/weather.py
new file mode 100644
index 0000000..cd6fa21
--- /dev/null
+++ b/pysrc/solweig/models/weather.py
@@ -0,0 +1,739 @@
+"""Weather and location data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime as dt
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ..physics import sun_position as sp
+from ..physics.clearnessindex_2013b import clearnessindex_2013b
+from ..physics.diffusefraction import diffusefraction
+from ..solweig_logging import get_logger
+
+if TYPE_CHECKING:
+ from .surface import SurfaceData
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class Location:
+ """
+ Geographic location for sun position calculations.
+
+ Attributes:
+ latitude: Latitude in degrees (north positive).
+ longitude: Longitude in degrees (east positive).
+ altitude: Altitude above sea level in meters. Default 0.
+ utc_offset: UTC offset in hours. Default 0.
+ """
+
+ latitude: float
+ longitude: float
+ altitude: float = 0.0
+ utc_offset: int = 0
+
+ def __post_init__(self):
+ if not -90 <= self.latitude <= 90:
+ raise ValueError(f"Latitude must be in [-90, 90], got {self.latitude}")
+ if not -180 <= self.longitude <= 180:
+ raise ValueError(f"Longitude must be in [-180, 180], got {self.longitude}")
+
+ @classmethod
+ def from_dsm_crs(cls, dsm_path: str | Path, utc_offset: int = 0, altitude: float = 0.0) -> Location:
+ """
+ Extract location from DSM raster's CRS by converting center point to WGS84.
+
+ Args:
+ dsm_path: Path to DSM GeoTIFF file with valid CRS.
+ utc_offset: UTC offset in hours. Must be provided by user.
+ altitude: Altitude above sea level in meters. Default 0.
+
+ Returns:
+ Location object with lat/lon from DSM center point.
+
+ Raises:
+ ValueError: If DSM has no CRS or CRS conversion fails.
+
+ Example:
+ location = Location.from_dsm_crs("dsm.tif", utc_offset=2)
+ """
+ from .. import io
+
+ try:
+ from pyproj import Transformer
+ except ImportError as err:
+ raise ImportError("pyproj is required for CRS extraction. Install with: pip install pyproj") from err
+
+ # Load DSM to get CRS and bounds
+ _, transform, crs_wkt, _ = io.load_raster(str(dsm_path))
+
+ if not crs_wkt:
+ raise ValueError(
+ f"DSM has no CRS metadata: {dsm_path}\n"
+ f"Either:\n"
+ f" 1. Add CRS to GeoTIFF: gdal_edit.py -a_srs EPSG:XXXXX {dsm_path}\n"
+ f" 2. Provide location manually: Location(latitude=X, longitude=Y, utc_offset={utc_offset})"
+ )
+
+ # Get center point from geotransform
+ # Transform is [x_origin, x_pixel_size, x_rotation, y_origin, y_rotation, y_pixel_size]
+ # We need the raster dimensions to find center - load again to get shape
+ dsm_array, _, _, _ = io.load_raster(str(dsm_path))
+ rows, cols = dsm_array.shape
+
+ center_x = transform[0] + (cols / 2) * transform[1]
+ center_y = transform[3] + (rows / 2) * transform[5]
+
+ # Convert to WGS84
+ transformer = Transformer.from_crs(crs_wkt, "EPSG:4326", always_xy=True)
+ lon, lat = transformer.transform(center_x, center_y)
+
+ logger.info(f"Extracted location from DSM CRS: {lat:.4f}°N, {lon:.4f}°E (UTC{utc_offset:+d})")
+ return cls(latitude=lat, longitude=lon, altitude=altitude, utc_offset=utc_offset)
+
+ @classmethod
+ def from_surface(cls, surface: SurfaceData, utc_offset: int | None = None, altitude: float = 0.0) -> Location:
+ """
+ Extract location from SurfaceData's CRS by converting center point to WGS84.
+
+ This avoids reloading the DSM raster when you already have loaded SurfaceData.
+
+ Args:
+ surface: SurfaceData instance loaded from GeoTIFF.
+ utc_offset: UTC offset in hours. If not provided, defaults to 0 with a warning.
+ Always provide this explicitly for correct sun position calculations.
+ altitude: Altitude above sea level in meters. Default 0.
+
+ Returns:
+ Location object with lat/lon from DSM center point.
+
+ Raises:
+ ValueError: If surface has no CRS metadata.
+ ImportError: If pyproj is not installed.
+
+ Example:
+ surface = SurfaceData.from_geotiff("dsm.tif")
+ location = Location.from_surface(surface, utc_offset=2) # Athens: UTC+2
+ """
+ import warnings
+
+ try:
+ from pyproj import Transformer
+ except ImportError as err:
+ raise ImportError("pyproj is required for CRS extraction. Install with: pip install pyproj") from err
+
+ # Check if geotransform and CRS are available
+ if not hasattr(surface, "_geotransform") or surface._geotransform is None:
+ raise ValueError(
+ "Surface data has no geotransform metadata.\n"
+ "Load surface with SurfaceData.from_geotiff() or provide location manually."
+ )
+ if not hasattr(surface, "_crs_wkt") or surface._crs_wkt is None:
+ raise ValueError(
+ "Surface data has no CRS metadata.\n"
+ "Provide location manually: Location(latitude=X, longitude=Y, utc_offset=0)"
+ )
+
+ transform = surface._geotransform
+ crs_wkt = surface._crs_wkt
+ rows, cols = surface.dsm.shape
+
+ # Get center point from geotransform
+ # Transform is [x_origin, x_pixel_size, x_rotation, y_origin, y_rotation, y_pixel_size]
+ center_x = transform[0] + (cols / 2) * transform[1]
+ center_y = transform[3] + (rows / 2) * transform[5]
+
+ # Convert to WGS84
+ transformer = Transformer.from_crs(crs_wkt, "EPSG:4326", always_xy=True)
+ lon, lat = transformer.transform(center_x, center_y)
+
+ # Warn if utc_offset not explicitly provided
+ if utc_offset is None:
+ warnings.warn(
+ f"UTC offset not specified for auto-extracted location ({lat:.4f}°N, {lon:.4f}°E).\n"
+ f"Defaulting to UTC+0, which may cause incorrect sun positions.\n"
+ f"Fix: Location.from_surface(surface, utc_offset=YOUR_OFFSET) or\n"
+ f" Location(latitude={lat:.4f}, longitude={lon:.4f}, utc_offset=YOUR_OFFSET)",
+ UserWarning,
+ stacklevel=2,
+ )
+ utc_offset = 0
+
+ logger.debug(f"Auto-extracted location: {lat:.4f}°N, {lon:.4f}°E (UTC{utc_offset:+d})")
+ return cls(latitude=lat, longitude=lon, altitude=altitude, utc_offset=utc_offset)
+
+ @classmethod
+ def from_epw(cls, path: str | Path) -> Location:
+ """
+ Extract location from an EPW weather file header.
+
+ The EPW LOCATION line contains latitude, longitude, timezone offset,
+ and elevation — everything needed for a complete Location.
+
+ Args:
+ path: Path to the EPW file.
+
+ Returns:
+ Location with lat, lon, utc_offset, and altitude from the EPW header.
+
+ Raises:
+ FileNotFoundError: If the EPW file doesn't exist.
+ ValueError: If the EPW header is malformed.
+
+ Example:
+ location = Location.from_epw("madrid.epw")
+ # Location(latitude=40.45, longitude=-3.55, altitude=667.0, utc_offset=1)
+ """
+ from .. import io as common
+
+ metadata = common._parse_epw_metadata(Path(path))
+ utc_offset = int(metadata["tz_offset"])
+
+ logger.info(
+ f"Location from EPW: {metadata['city']} — "
+ f"{metadata['latitude']:.4f}°N, {metadata['longitude']:.4f}°E "
+ f"(UTC{utc_offset:+d}, {metadata['elevation']:.0f}m)"
+ )
+ return cls(
+ latitude=metadata["latitude"],
+ longitude=metadata["longitude"],
+ altitude=metadata["elevation"],
+ utc_offset=utc_offset,
+ )
+
+ def to_sun_position_dict(self) -> dict:
+ """Convert to dict format expected by sun_position module."""
+ return {
+ "latitude": self.latitude,
+ "longitude": self.longitude,
+ "altitude": self.altitude,
+ }
+
+
+@dataclass
+class Weather:
+ """
+ Weather/meteorological data for a single timestep.
+
+ Only basic measurements are required. Derived values (sun position,
+ direct/diffuse radiation split) are computed automatically.
+
+ Attributes:
+ datetime: Date and time of measurement (end of interval).
+ ta: Air temperature in °C.
+ rh: Relative humidity in % (0-100).
+ global_rad: Global solar radiation in W/m².
+ ws: Wind speed in m/s. Default 1.0.
+ pressure: Atmospheric pressure in hPa. Default 1013.25.
+ timestep_minutes: Data timestep in minutes. Default 60.0.
+ Sun position is computed at datetime - timestep/2 to represent
+ the center of the measurement interval.
+ measured_direct_rad: Optional measured direct beam radiation in W/m².
+ If provided with measured_diffuse_rad, these override the computed values.
+ measured_diffuse_rad: Optional measured diffuse radiation in W/m².
+ If provided with measured_direct_rad, these override the computed values.
+
+ Auto-computed (after calling compute_derived()):
+ sun_altitude: Sun altitude angle in degrees.
+ sun_azimuth: Sun azimuth angle in degrees.
+ direct_rad: Direct beam radiation in W/m² (from measured or computed).
+ diffuse_rad: Diffuse radiation in W/m² (from measured or computed).
+ """
+
+ datetime: dt
+ ta: float
+ rh: float
+ global_rad: float
+ ws: float = 1.0
+ pressure: float = 1013.25
+ timestep_minutes: float = 60.0 # Timestep in minutes (for half-timestep sun position offset)
+ measured_direct_rad: float | None = None # Optional measured direct beam radiation
+ measured_diffuse_rad: float | None = None # Optional measured diffuse radiation
+ precomputed_sun_altitude: float | None = None # Optional pre-computed sun altitude
+ precomputed_sun_azimuth: float | None = None # Optional pre-computed sun azimuth
+ precomputed_altmax: float | None = None # Optional pre-computed max sun altitude for day
+
+ # Auto-computed values (set by compute_derived)
+ sun_altitude: float = field(default=0.0, init=False)
+ sun_azimuth: float = field(default=0.0, init=False)
+ sun_zenith: float = field(default=90.0, init=False)
+ direct_rad: float = field(default=0.0, init=False)
+ diffuse_rad: float = field(default=0.0, init=False)
+ clearness_index: float = field(default=1.0, init=False)
+ altmax: float = field(default=45.0, init=False) # Maximum sun altitude for the day
+
+ _derived_computed: bool = field(default=False, init=False, repr=False)
+
+ def __post_init__(self):
+ if not 0 <= self.rh <= 100:
+ raise ValueError(f"Relative humidity must be in [0, 100], got {self.rh}")
+ if self.global_rad < 0:
+ raise ValueError(f"Global radiation must be >= 0, got {self.global_rad}")
+
+ def compute_derived(self, location: Location) -> None:
+ """
+ Compute derived values: sun position and radiation split.
+
+ Must be called before using sun_altitude, sun_azimuth, direct_rad,
+ or diffuse_rad.
+
+ Sun position is calculated at the center of the measurement interval
+ (datetime - timestep/2), which is standard for meteorological data
+ where measurements are averaged over the interval.
+
+ Args:
+ location: Geographic location for sun position calculation.
+ """
+ # Always create location_dict (needed for clearness index calculation)
+ location_dict = location.to_sun_position_dict()
+
+ # Use pre-computed sun position if provided, otherwise compute
+ if self.precomputed_sun_altitude is not None and self.precomputed_sun_azimuth is not None:
+ self.sun_altitude = self.precomputed_sun_altitude
+ self.sun_azimuth = self.precomputed_sun_azimuth
+ self.sun_zenith = 90.0 - self.sun_altitude
+ self.altmax = self.precomputed_altmax if self.precomputed_altmax is not None else self.sun_altitude
+ else:
+ # Apply half-timestep offset for sun position
+ # Meteorological data timestamps typically represent the end of an interval,
+ # so we compute sun position at the center of the interval to match SOLWEIG runner
+ from datetime import timedelta
+
+ half_timestep = timedelta(minutes=self.timestep_minutes / 2.0)
+ sun_time = self.datetime - half_timestep
+
+ # Compute sun position using NREL algorithm
+ time_dict = {
+ "year": sun_time.year,
+ "month": sun_time.month,
+ "day": sun_time.day,
+ "hour": sun_time.hour,
+ "min": sun_time.minute,
+ "sec": sun_time.second,
+ "UTC": location.utc_offset,
+ }
+ location_dict = location.to_sun_position_dict()
+
+ sun = sp.sun_position(time_dict, location_dict)
+
+ # Extract scalar values (sun_position may return 0-d arrays)
+ zenith = sun["zenith"]
+ azimuth = sun["azimuth"]
+ self.sun_zenith = float(np.asarray(zenith).flat[0]) if hasattr(zenith, "__iter__") else float(zenith)
+ self.sun_azimuth = float(np.asarray(azimuth).flat[0]) if hasattr(azimuth, "__iter__") else float(azimuth)
+ self.sun_altitude = 90.0 - self.sun_zenith
+
+ # Use pre-computed altmax if available (avoids expensive 96-iteration loop)
+ if self.precomputed_altmax is not None:
+ self.altmax = self.precomputed_altmax
+ else:
+ # Calculate maximum sun altitude for the day (iterate in 15-min intervals)
+ # This matches the method in configs.py:EnvironData
+ from datetime import timedelta
+
+ ymd = self.datetime.replace(hour=0, minute=0, second=0, microsecond=0)
+ sunmaximum = -90.0
+ fifteen_min = 15.0 / 1440.0 # 15 minutes as fraction of day
+
+ for step in range(96): # 24 hours * 4 (15-min intervals)
+ step_time = ymd + timedelta(days=step * fifteen_min)
+ time_dict_step = {
+ "year": step_time.year,
+ "month": step_time.month,
+ "day": step_time.day,
+ "hour": step_time.hour,
+ "min": step_time.minute,
+ "sec": 0,
+ "UTC": location.utc_offset,
+ }
+ sun_step = sp.sun_position(time_dict_step, location_dict)
+ zenith_step = sun_step["zenith"]
+ zenith_val = (
+ float(np.asarray(zenith_step).flat[0])
+ if hasattr(zenith_step, "__iter__")
+ else float(zenith_step)
+ )
+ alt_step = 90.0 - zenith_val
+ if alt_step > sunmaximum:
+ sunmaximum = alt_step
+
+ self.altmax = max(sunmaximum, 0.0) # Ensure non-negative
+
+ # Use measured radiation values if provided, otherwise compute
+ if self.measured_direct_rad is not None and self.measured_diffuse_rad is not None:
+ # Use pre-measured direct and diffuse radiation
+ self.direct_rad = self.measured_direct_rad
+ self.diffuse_rad = self.measured_diffuse_rad
+ self.clearness_index = 1.0 # Not computed when using measured values
+ elif self.sun_altitude > 0 and self.global_rad > 0:
+ # Compute clearness index
+ zen_rad = self.sun_zenith * (np.pi / 180.0)
+ result = clearnessindex_2013b(
+ zen_rad,
+ self.datetime.timetuple().tm_yday,
+ self.ta,
+ self.rh / 100.0,
+ self.global_rad,
+ location_dict,
+ self.pressure,
+ )
+ # clearnessindex_2013b returns: (I0, CI, Kt, I0_et, diff_et)
+ _, self.clearness_index, kt, _, _ = result
+
+ # Use Reindl model for diffuse fraction
+ self.direct_rad, self.diffuse_rad = diffusefraction(
+ self.global_rad, self.sun_altitude, kt, self.ta, self.rh
+ )
+ else:
+ # Night or no radiation
+ self.direct_rad = 0.0
+ self.diffuse_rad = self.global_rad
+ self.clearness_index = 1.0
+
+ self._derived_computed = True
+
+ @property
+ def is_daytime(self) -> bool:
+ """Check if sun is above horizon."""
+ return self.sun_altitude > 0
+
+ @classmethod
+ def from_values(
+ cls,
+ ta: float,
+ rh: float,
+ global_rad: float,
+ datetime: dt | None = None,
+ ws: float = 1.0,
+ **kwargs: Any,
+ ) -> Weather:
+ """
+ Quick factory for creating Weather with minimal required values.
+
+ Useful for testing and single-timestep calculations where you
+ just need to specify the essential parameters.
+
+ Args:
+ ta: Air temperature in °C.
+ rh: Relative humidity in % (0-100).
+ global_rad: Global solar radiation in W/m².
+ datetime: Date and time. If None, uses current time.
+ ws: Wind speed in m/s. Default 1.0.
+ **kwargs: Additional Weather parameters (pressure, etc.)
+
+ Returns:
+ Weather object ready for calculation.
+
+ Example:
+ # Quick weather for testing
+ weather = Weather.from_values(ta=25, rh=50, global_rad=800)
+
+ # With specific datetime
+ weather = Weather.from_values(
+ ta=30, rh=60, global_rad=900,
+ datetime=datetime(2024, 7, 15, 14, 0)
+ )
+ """
+ if datetime is None:
+ datetime = dt.now()
+ return cls(datetime=datetime, ta=ta, rh=rh, global_rad=global_rad, ws=ws, **kwargs)
+
+ @classmethod
+ def from_epw(
+ cls,
+ path: str | Path,
+ start: str | dt | None = None,
+ end: str | dt | None = None,
+ hours: list[int] | None = None,
+ year: int | None = None,
+ ) -> list[Weather]:
+ """
+ Load weather data from an EnergyPlus Weather (EPW) file.
+
+ Args:
+ path: Path to the EPW file.
+ start: Start date/datetime. Can be:
+ - ISO date string "YYYY-MM-DD" or "MM-DD" (for TMY with year=None)
+ - datetime object
+ If None, uses first date in file.
+ end: End date/datetime (inclusive). Same format as start.
+ If None, uses same as start (single day).
+ hours: List of hours to include (0-23). If None, includes all hours.
+ year: Year override for TMY files. If None and start/end use MM-DD format,
+ matches any year in the file.
+
+ Returns:
+ List of Weather objects for each timestep in the requested range.
+
+ Raises:
+ FileNotFoundError: If the EPW file doesn't exist.
+ ValueError: If requested dates are outside the EPW file's date range.
+
+ Example:
+ # Load a single day
+ weather_list = Weather.from_epw("weather.epw", start="2023-07-15", end="2023-07-15")
+
+ # Load with specific hours only (daylight hours)
+ weather_list = Weather.from_epw(
+ "weather.epw",
+ start="2023-07-15",
+ end="2023-07-16",
+ hours=[6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18]
+ )
+
+ # TMY file (year-agnostic)
+ weather_list = Weather.from_epw("tmy.epw", start="07-15", end="07-15")
+ """
+ from .. import io as common
+
+ # Parse EPW file
+ df, epw_info = common.read_epw(path)
+
+ # Parse start/end dates
+ def parse_date(date_val, is_tmy: bool, default_year: int):
+ if date_val is None:
+ return None
+ if isinstance(date_val, dt):
+ return date_val
+ # String parsing
+ date_str = str(date_val)
+ if "-" in date_str:
+ parts = date_str.split("-")
+ if len(parts) == 2:
+ # MM-DD format (TMY)
+ month, day = int(parts[0]), int(parts[1])
+ return dt(default_year, month, day)
+ elif len(parts) == 3:
+ # YYYY-MM-DD format
+ return dt.fromisoformat(date_str)
+ raise ValueError(f"Cannot parse date: {date_val}. Use 'YYYY-MM-DD' or 'MM-DD' format.")
+
+ # Determine if using TMY mode (year-agnostic)
+ is_tmy = year is None and start is not None and isinstance(start, str) and len(start.split("-")) == 2
+
+ # Get default year from EPW data
+ if df.index.empty:
+ raise ValueError("EPW file contains no data")
+ default_year = df.index[0].year if year is None else year
+
+ # Parse dates
+ start_dt = parse_date(start, is_tmy, default_year)
+ end_dt = parse_date(end, is_tmy, default_year)
+
+ if start_dt is None:
+ start_dt = df.index[0].replace(tzinfo=None)
+ if end_dt is None:
+ end_dt = start_dt
+
+ # Make end_dt inclusive of the full day
+ if end_dt.hour == 0 and end_dt.minute == 0:
+ end_dt = end_dt.replace(hour=23, minute=59, second=59)
+
+ # Filter by date range
+ # Remove timezone from index for comparison if needed
+ df_idx = df.index.tz_localize(None) if df.index.tz is not None else df.index
+
+ if is_tmy:
+ # TMY mode: match month and day, ignore year
+ mask = (
+ (df_idx.month > start_dt.month) | ((df_idx.month == start_dt.month) & (df_idx.day >= start_dt.day))
+ ) & ((df_idx.month < end_dt.month) | ((df_idx.month == end_dt.month) & (df_idx.day <= end_dt.day)))
+ else:
+ # Normal mode: match full datetime
+ mask = (df_idx >= start_dt) & (df_idx <= end_dt)
+
+ df_filtered = df[mask]
+
+ if df_filtered.empty:
+ # Build helpful error message
+ avail_start = df_idx.min()
+ avail_end = df_idx.max()
+ raise ValueError(
+ f"Requested dates {start_dt.date()} to {end_dt.date()} not found in EPW file.\n"
+ f"EPW file '{path}' contains data for: {avail_start.date()} to {avail_end.date()}\n"
+ "Suggestions:\n"
+ " - Use dates within the available range\n"
+ " - For TMY files, use 'MM-DD' format (e.g., '07-15') to match any year"
+ )
+
+ # Filter by hours if specified
+ if hours is not None:
+ hours_set = set(hours)
+ hour_mask = df_filtered.index.hour.isin(hours_set)
+ df_filtered = df_filtered[hour_mask]
+
+ # Create Weather objects
+ weather_list = []
+ for timestamp, row in df_filtered.iterrows():
+ # Create Weather object with available data
+ # EPW has dni/dhi which we can use as measured values
+ w = cls(
+ datetime=timestamp.to_pydatetime().replace(tzinfo=None),
+ ta=float(row["temp_air"]) if not np.isnan(row["temp_air"]) else 20.0,
+ rh=float(row["relative_humidity"]) if not np.isnan(row["relative_humidity"]) else 50.0,
+ global_rad=float(row["ghi"]) if not np.isnan(row["ghi"]) else 0.0,
+ ws=float(row["wind_speed"]) if not np.isnan(row["wind_speed"]) else 1.0,
+ pressure=(float(row["atmospheric_pressure"]) / 100.0)
+ if not np.isnan(row["atmospheric_pressure"])
+ else 1013.25, # Convert Pa to hPa
+ measured_direct_rad=float(row["dni"]) if not np.isnan(row["dni"]) else None,
+ measured_diffuse_rad=float(row["dhi"]) if not np.isnan(row["dhi"]) else None,
+ )
+ weather_list.append(w)
+
+ if weather_list:
+ logger.info(
+ f"Loaded {len(weather_list)} timesteps from EPW: "
+ f"{weather_list[0].datetime.strftime('%Y-%m-%d %H:%M')} → "
+ f"{weather_list[-1].datetime.strftime('%Y-%m-%d %H:%M')}"
+ )
+ else:
+ logger.warning(f"No timesteps found in EPW file for date range {start_dt} to {end_dt}")
+
+ return weather_list
+
+ @classmethod
+ def from_umep_met(
+ cls,
+ paths: str | Path | list[str | Path],
+ resample_hourly: bool = True,
+ start: str | dt | None = None,
+ end: str | dt | None = None,
+ ) -> list[Weather]:
+ """
+ Load weather data from UMEP/SUEWS meteorological forcing files.
+
+ The UMEP met format is space-separated with columns:
+ %iy, id, it, imin, Q*, QH, QE, Qs, Qf, Wind, RH, Td, press,
+ rain, Kdn, snow, ldown, fcld, wuh, xsmd, lai_hr, Kdiff, Kdir, Wd
+
+ Missing values are encoded as -999.
+
+ Args:
+ paths: Path(s) to UMEP met file(s). Multiple files are
+ concatenated (e.g., one per month).
+ resample_hourly: If True, keep only on-the-hour rows (imin=0).
+ Default True since SOLWEIG works best with hourly data.
+ start: Start date filter as "YYYY-MM-DD" or datetime. Optional.
+ end: End date filter (inclusive) as "YYYY-MM-DD" or datetime. Optional.
+
+ Returns:
+ List of Weather objects sorted by datetime.
+
+ Example:
+ # Single file
+ weather = Weather.from_umep_met("metdata_10min_july.txt")
+
+ # Multiple monthly files
+ weather = Weather.from_umep_met([
+ "metdata_10min_may.txt",
+ "metdata_10min_june.txt",
+ ])
+ """
+ from datetime import timedelta
+
+ if isinstance(paths, (str, Path)):
+ paths = [paths]
+
+ rows: list[dict[str, float]] = []
+ for path in paths:
+ path = Path(path)
+ if not path.exists():
+ raise FileNotFoundError(f"UMEP met file not found: {path}")
+
+ with open(path) as f:
+ for line in f:
+ line = line.strip()
+ if not line or line.startswith("%") or line.startswith("#"):
+ continue
+ parts = line.split()
+ if len(parts) < 24:
+ continue
+ try:
+ rows.append(
+ {
+ "year": int(parts[0]),
+ "doy": int(parts[1]),
+ "hour": int(parts[2]),
+ "minute": int(parts[3]),
+ "wind": float(parts[9]),
+ "rh": float(parts[10]),
+ "ta": float(parts[11]),
+ "press_kpa": float(parts[12]),
+ "kdn": float(parts[14]),
+ "kdiff": float(parts[21]),
+ "kdir": float(parts[22]),
+ }
+ )
+ except (ValueError, IndexError):
+ continue
+
+ if not rows:
+ raise ValueError(f"No valid data rows found in UMEP met files: {paths}")
+
+ # Filter hourly if requested
+ if resample_hourly:
+ rows = [r for r in rows if r["minute"] == 0]
+
+ # Convert to Weather objects
+ weather_list = []
+ for r in rows:
+ timestamp = dt(int(r["year"]), 1, 1) + timedelta(
+ days=int(r["doy"]) - 1, hours=int(r["hour"]), minutes=int(r["minute"])
+ )
+
+ # Skip rows with missing critical data
+ if r["ta"] <= -998 or r["rh"] <= -998 or r["kdn"] <= -998:
+ continue
+
+ # Convert pressure from kPa to hPa (-999 means missing)
+ pressure = r["press_kpa"] * 10.0 if r["press_kpa"] > -998 else 1013.25
+
+ # Direct/diffuse radiation (-999 means missing)
+ kdir = r["kdir"] if r["kdir"] > -998 else None
+ kdiff = r["kdiff"] if r["kdiff"] > -998 else None
+
+ # Wind speed (-999 means missing)
+ ws = r["wind"] if r["wind"] > -998 else 1.0
+
+ timestep = 60.0 if resample_hourly else 10.0
+
+ w = cls(
+ datetime=timestamp,
+ ta=r["ta"],
+ rh=r["rh"],
+ global_rad=max(r["kdn"], 0.0),
+ ws=ws,
+ pressure=pressure,
+ timestep_minutes=timestep,
+ measured_direct_rad=kdir,
+ measured_diffuse_rad=kdiff,
+ )
+ weather_list.append(w)
+
+ # Sort by datetime
+ weather_list.sort(key=lambda w: w.datetime)
+
+ # Apply date filters
+ if start is not None:
+ start_dt = dt.fromisoformat(start) if isinstance(start, str) else start
+ weather_list = [w for w in weather_list if w.datetime >= start_dt]
+ if end is not None:
+ end_dt = dt.fromisoformat(end) if isinstance(end, str) else end
+ if end_dt.hour == 0 and end_dt.minute == 0:
+ end_dt = end_dt.replace(hour=23, minute=59, second=59)
+ weather_list = [w for w in weather_list if w.datetime <= end_dt]
+
+ if weather_list:
+ logger.info(
+ f"Loaded {len(weather_list)} timesteps from UMEP met: "
+ f"{weather_list[0].datetime.strftime('%Y-%m-%d %H:%M')} → "
+ f"{weather_list[-1].datetime.strftime('%Y-%m-%d %H:%M')}"
+ )
+
+ return weather_list
diff --git a/pysrc/umepr/parametersforsolweig.json b/pysrc/solweig/parametersforsolweig.json
similarity index 97%
rename from pysrc/umepr/parametersforsolweig.json
rename to pysrc/solweig/parametersforsolweig.json
index 17a8cbe..bb327de 100644
--- a/pysrc/umepr/parametersforsolweig.json
+++ b/pysrc/solweig/parametersforsolweig.json
@@ -167,10 +167,10 @@
"Tmrt_params": {
"Value": {
"absK": 0.70,
- "absL": 0.95,
+ "absL": 0.97,
"posture": "Standing"
},
- "Comment": "Absorption coefficients for mean radiant temperature (Tmrt) and posture. Posture is either standing or sitting."
+ "Comment": "Absorption coefficients per ISO 7726:1998. absK=0.70 (shortwave), absL=0.97 (longwave)."
},
"PET_settings": {
"Value": {
diff --git a/pysrc/solweig/physics/Kup_veg_2015a.py b/pysrc/solweig/physics/Kup_veg_2015a.py
new file mode 100644
index 0000000..d63a63a
--- /dev/null
+++ b/pysrc/solweig/physics/Kup_veg_2015a.py
@@ -0,0 +1,33 @@
+import numpy as np
+
+
+def Kup_veg_2015a(
+ radI,
+ radD,
+ radG,
+ altitude,
+ svfbuveg,
+ albedo_b,
+ F_sh,
+ gvfalb,
+ gvfalbE,
+ gvfalbS,
+ gvfalbW,
+ gvfalbN,
+ gvfalbnosh,
+ gvfalbnoshE,
+ gvfalbnoshS,
+ gvfalbnoshW,
+ gvfalbnoshN,
+):
+ # Pre-compute common terms once (2x speedup)
+ radI_sin_alt = radI * np.sin(altitude * (np.pi / 180.0))
+ common_term = radD * svfbuveg + albedo_b * (1 - svfbuveg) * (radG * (1 - F_sh) + radD * F_sh)
+
+ Kup = gvfalb * radI_sin_alt + common_term * gvfalbnosh
+ KupE = gvfalbE * radI_sin_alt + common_term * gvfalbnoshE
+ KupS = gvfalbS * radI_sin_alt + common_term * gvfalbnoshS
+ KupW = gvfalbW * radI_sin_alt + common_term * gvfalbnoshW
+ KupN = gvfalbN * radI_sin_alt + common_term * gvfalbnoshN
+
+ return Kup, KupE, KupS, KupW, KupN
diff --git a/pysrc/solweig/physics/Perez_v3.py b/pysrc/solweig/physics/Perez_v3.py
new file mode 100644
index 0000000..7625303
--- /dev/null
+++ b/pysrc/solweig/physics/Perez_v3.py
@@ -0,0 +1,313 @@
+import numpy as np
+
+from ..constants import MIN_SUN_ELEVATION_DEG
+from .create_patches import create_patches
+
+
+def Perez_v3(zen, azimuth, radD, radI, jday, patchchoice, patch_option):
+ """
+ This function calculates distribution of luminance on the skyvault based on
+ Perez luminince distribution model.
+
+ ALL-WEATHER MODEL FOR SKY LUMINANCE DISTRIBUTION
+ PRELIMINARY CONFIGURATION AND VALIDATION
+ R. PEREZ, R. SEALS, and J. MICHALSKY
+ Solar Energy Vol. 50, No, 3, pp. 235-245, 1993
+
+ Abstract--This article reports the development and evaluation of a new model for describing, from routine
+ irradiance measurements, the mean instantaneous sky luminance angular distribution patterns for all sky
+ conditions from overcast to clear, through partly cloudy, skies.
+
+ Created by:
+ Fredrik Lindberg 20120527, fredrikl@gvc.gu.se
+ Gothenburg University, Sweden
+ Urban Climte Group
+
+ Input parameters:
+ - zen: Zenith angle of the Sun (in degrees)
+ - azimuth: Azimuth angle of the Sun (in degrees)
+ - radD: Horizontal diffuse radiation (W m-2)
+ - radI: Direct radiation perpendicular to the Sun beam (W m-2)
+ - jday: Day of year
+
+ Output parameters:
+ - lv: Relative luminance map (same dimensions as theta. gamma)
+
+
+ acoeff=[1.353 -0.258 -0.269 -1.437
+ -1.222 -0.773 1.415 1.102
+ -1.100 -0.252 0.895 0.016
+ -0.585 -0.665 -0.267 0.712
+ -0.600 -0.347 -2.500 2.323
+ -1.016 -0.367 1.008 1.405
+ -1.000 0.021 0.503 -0.512
+ -1.050 0.029 0.426 0.359];
+
+ bcoeff=[-0.767 0.001 1.273 -0.123
+ -0.205 0.037 -3.913 0.916
+ 0.278 -0.181 -4.500 1.177
+ 0.723 -0.622 -5.681 2.630
+ 0.294 0.049 -5.681 1.842
+ 0.288 -0.533 -3.850 3.375
+ -0.300 0.192 0.702 -1.632
+ -0.325 0.116 0.778 0.003];
+
+ ccoeff=[2.800 0.600 1.238 1.000
+ 6.975 0.177 6.448 -0.124
+ 24.22 -13.08 -37.70 34.84
+ 33.34 -18.30 -62.25 52.08
+ 21.00 -4.766 -21.59 7.249
+ 14.00 -0.999 -7.14 7.547
+ 19.00 -5.000 1.243 -1.91
+ 31.06 -14.50 -46.11 55.37];
+
+ dcoeff=[1.874 0.630 0.974 0.281
+ -1.580 -0.508 -1.781 0.108
+ -5.00 1.522 3.923 -2.62
+ -3.50 0.002 1.148 0.106
+ -3.50 -0.155 1.406 0.399
+ -3.40 -0.108 -1.075 1.57
+ -4.00 0.025 0.384 0.266
+ -7.23 0.405 13.35 0.623];
+
+ ecoeff=[0.035 -0.125 -0.572 0.994
+ 0.262 0.067 -0.219 -0.428
+ -0.016 0.160 0.420 -0.556
+ 0.466 -0.33 -0.088 -0.033
+ 0.003 0.077 -0.066 -0.129
+ -0.067 0.402 0.302 -0.484
+ 1.047 -0.379 -2.452 1.466
+ 1.500 -0.643 1.856 0.564];
+
+ :param zen:
+ :param azimuth:
+ :param radD:
+ :param radI:
+ :param jday:
+ :param patchchoice:
+ :return:
+ """
+
+ # Use established threshold from constants (3°)
+ # Physical justification for uniform fallback below this:
+ # - Air mass > 20 → extreme atmospheric scattering
+ # - Direct beam is negligible (heavy atmospheric absorption)
+ # - Circumsolar brightening disappears → sky approximates uniform
+ # - Tmrt is dominated by longwave at these angles anyway
+ # This also avoids numerical instability from large tan(zenith) values.
+ altitude_deg = 90 - zen
+
+ # Return uniform distribution for very low sun or very low diffuse radiation
+ if altitude_deg < MIN_SUN_ELEVATION_DEG or radD < 10:
+ if patchchoice == 1:
+ skyvaultalt, skyvaultazi, _, _, _, _, _ = create_patches(patch_option)
+ n_patches = skyvaultalt.shape[0]
+ uniform_lv = 1.0 / n_patches
+ x = np.transpose(np.atleast_2d(skyvaultalt))
+ y = np.transpose(np.atleast_2d(skyvaultazi))
+ z = np.transpose(np.atleast_2d(np.full(n_patches, uniform_lv)))
+ lv = np.append(np.append(x, y, axis=1), z, axis=1)
+ else:
+ lv = np.ones((90, 361), dtype=np.float32) / (90 * 361)
+ # Return uniform distribution with clearness=1 (overcast), brightness=0
+ return lv, 1.0, 0.0
+
+ m_a1 = np.array([1.3525, -1.2219, -1.1000, -0.5484, -0.6000, -1.0156, -1.0000, -1.0500])
+ m_a2 = np.array([-0.2576, -0.7730, -0.2515, -0.6654, -0.3566, -0.3670, 0.0211, 0.0289])
+ m_a3 = np.array([-0.2690, 1.4148, 0.8952, -0.2672, -2.5000, 1.0078, 0.5025, 0.4260])
+ m_a4 = np.array([-1.4366, 1.1016, 0.0156, 0.7117, 2.3250, 1.4051, -0.5119, 0.3590])
+ m_b1 = np.array([-0.7670, -0.2054, 0.2782, 0.7234, 0.2937, 0.2875, -0.3000, -0.3250])
+ m_b2 = np.array([0.0007, 0.0367, -0.1812, -0.6219, 0.0496, -0.5328, 0.1922, 0.1156])
+ m_b3 = np.array([1.2734, -3.9128, -4.5000, -5.6812, -5.6812, -3.8500, 0.7023, 0.7781])
+ m_b4 = np.array([-0.1233, 0.9156, 1.1766, 2.6297, 1.8415, 3.3750, -1.6317, 0.0025])
+ m_c1 = np.array([2.8000, 6.9750, 24.7219, 33.3389, 21.0000, 14.0000, 19.0000, 31.0625])
+ m_c2 = np.array([0.6004, 0.1774, -13.0812, -18.3000, -4.7656, -0.9999, -5.0000, -14.5000])
+ m_c3 = np.array([1.2375, 6.4477, -37.7000, -62.2500, -21.5906, -7.1406, 1.2438, -46.1148])
+ m_c4 = np.array([1.0000, -0.1239, 34.8438, 52.0781, 7.2492, 7.5469, -1.9094, 55.3750])
+ m_d1 = np.array([1.8734, -1.5798, -5.0000, -3.5000, -3.5000, -3.4000, -4.0000, -7.2312])
+ m_d2 = np.array([0.6297, -0.5081, 1.5218, 0.0016, -0.1554, -0.1078, 0.0250, 0.4050])
+ m_d3 = np.array([0.9738, -1.7812, 3.9229, 1.1477, 1.4062, -1.0750, 0.3844, 13.3500])
+ m_d4 = np.array([0.2809, 0.1080, -2.6204, 0.1062, 0.3988, 1.5702, 0.2656, 0.6234])
+ m_e1 = np.array([0.0356, 0.2624, -0.0156, 0.4659, 0.0032, -0.0672, 1.0468, 1.5000])
+ m_e2 = np.array([-0.1246, 0.0672, 0.1597, -0.3296, 0.0766, 0.4016, -0.3788, -0.6426])
+ m_e3 = np.array([-0.5718, -0.2190, 0.4199, -0.0876, -0.0656, 0.3017, -2.4517, 1.8564])
+ m_e4 = np.array([0.9938, -0.4285, -0.5562, -0.0329, -0.1294, -0.4844, 1.4656, 0.5636])
+
+ acoeff = np.transpose(np.atleast_2d([m_a1, m_a2, m_a3, m_a4]))
+ bcoeff = np.transpose(np.atleast_2d([m_b1, m_b2, m_b3, m_b4]))
+ ccoeff = np.transpose(np.atleast_2d([m_c1, m_c2, m_c3, m_c4]))
+ dcoeff = np.transpose(np.atleast_2d([m_d1, m_d2, m_d3, m_d4]))
+ ecoeff = np.transpose(np.atleast_2d([m_e1, m_e2, m_e3, m_e4]))
+
+ deg2rad = np.pi / 180
+ rad2deg = 180 / np.pi
+ altitude = 90 - zen
+ zen = zen * deg2rad
+ azimuth = azimuth * deg2rad
+ altitude = altitude * deg2rad
+ Idh = radD
+ # Ibh = radI/sin(altitude)
+ Ibn = radI
+
+ # Skyclearness - guard against division by very small Idh
+ Idh_safe = max(Idh, 1.0) # Minimum 1 W/m² to avoid division issues
+ PerezClearness = ((Idh_safe + Ibn) / Idh_safe + 1.041 * np.power(zen, 3)) / (1 + 1.041 * np.power(zen, 3))
+
+ # Extra terrestrial radiation
+ day_angle = jday * 2 * np.pi / 365
+ # I0=1367*(1+0.033*np.cos((2*np.pi*jday)/365))
+ I0 = 1367 * (
+ 1.00011
+ + 0.034221 * np.cos(day_angle)
+ + 0.00128 * np.sin(day_angle)
+ + 0.000719 * np.cos(2 * day_angle)
+ + 0.000077 * np.sin(2 * day_angle)
+ ) # New from robinsson
+
+ # Optical air mass (Kasten & Young 1989)
+ # Use corrected formula for all positive altitudes to avoid instability
+ if altitude >= 10 * deg2rad:
+ AirMass = 1 / np.sin(altitude)
+ elif altitude > 0:
+ # Kasten & Young correction for low sun angles (0-10°)
+ # This avoids division by sin(altitude) approaching zero
+ altitude_deg = altitude * rad2deg
+ AirMass = 1 / (np.sin(altitude) + 0.50572 * np.power(altitude_deg + 6.07995, -1.6364))
+ else:
+ # Negative altitude shouldn't reach here due to early exit, but clamp to safe value
+ AirMass = 40.0 # Maximum air mass at horizon
+
+ # Clamp air mass to reasonable range
+ AirMass = min(float(np.real(AirMass)), 40.0)
+
+ # Skybrightness
+ PerezBrightness = (AirMass * radD) / I0
+ if Idh <= 10:
+ # Very low diffuse radiation - use zero brightness
+ PerezBrightness = 0
+ # if altitude < 0:
+ # print("Airmass")
+ # print(AirMass)
+ # print(PerezBrightness)
+ # sky clearness bins
+ if PerezClearness < 1.065:
+ intClearness = 0
+ elif PerezClearness < 1.230:
+ intClearness = 1
+ elif PerezClearness < 1.500:
+ intClearness = 2
+ elif PerezClearness < 1.950:
+ intClearness = 3
+ elif PerezClearness < 2.800:
+ intClearness = 4
+ elif PerezClearness < 4.500:
+ intClearness = 5
+ elif PerezClearness < 6.200:
+ intClearness = 6
+ if PerezClearness > 6.200:
+ intClearness = 7
+
+ m_a = (
+ acoeff[intClearness, 0]
+ + acoeff[intClearness, 1] * zen
+ + PerezBrightness * (acoeff[intClearness, 2] + acoeff[intClearness, 3] * zen)
+ )
+ m_b = (
+ bcoeff[intClearness, 0]
+ + bcoeff[intClearness, 1] * zen
+ + PerezBrightness * (bcoeff[intClearness, 2] + bcoeff[intClearness, 3] * zen)
+ )
+ m_e = (
+ ecoeff[intClearness, 0]
+ + ecoeff[intClearness, 1] * zen
+ + PerezBrightness * (ecoeff[intClearness, 2] + ecoeff[intClearness, 3] * zen)
+ )
+
+ if intClearness > 0:
+ m_c = (
+ ccoeff[intClearness, 0]
+ + ccoeff[intClearness, 1] * zen
+ + PerezBrightness * (ccoeff[intClearness, 2] + ccoeff[intClearness, 3] * zen)
+ )
+ m_d = (
+ dcoeff[intClearness, 0]
+ + dcoeff[intClearness, 1] * zen
+ + PerezBrightness * (dcoeff[intClearness, 2] + dcoeff[intClearness, 3] * zen)
+ )
+ else:
+ # different equations for c & d in clearness bin no. 1, from Robinsson
+ m_c = (
+ np.exp(
+ np.power(
+ PerezBrightness * (ccoeff[intClearness, 0] + ccoeff[intClearness, 1] * zen), ccoeff[intClearness, 2]
+ )
+ )
+ - 1
+ )
+ m_d = (
+ -np.exp(PerezBrightness * (dcoeff[intClearness, 0] + dcoeff[intClearness, 1] * zen))
+ + dcoeff[intClearness, 2]
+ + PerezBrightness * dcoeff[intClearness, 3]
+ )
+
+ # print 'a = ', m_a
+ # print 'b = ', m_b
+ # print 'e = ', m_e
+ # print 'c = ', m_c
+ # print 'd = ', m_d
+
+ if patchchoice == 2:
+ skyvaultalt = np.atleast_2d([])
+ skyvaultazi = np.atleast_2d([])
+ # Creating skyvault at one degree intervals
+ skyvaultalt = np.ones([90, 361], dtype=np.float32) * 90
+ skyvaultazi = np.empty((90, 361), dtype=np.float32)
+ for j in range(90):
+ skyvaultalt[j, :] = 91 - j
+ skyvaultazi[j, :] = range(361)
+
+ elif patchchoice == 1:
+ # Creating skyvault of patches of constant radians (Tregeneza and Sharples, 1993)
+ skyvaultalt, skyvaultazi, _, _, _, _, _ = create_patches(patch_option)
+
+ skyvaultzen = (90 - skyvaultalt) * deg2rad
+ skyvaultalt = skyvaultalt * deg2rad
+ skyvaultazi = skyvaultazi * deg2rad
+
+ # Angular distance from the sun from Robinsson
+ cosSkySunAngle = np.sin(skyvaultalt) * np.sin(altitude) + np.cos(altitude) * np.cos(skyvaultalt) * np.cos(
+ np.abs(skyvaultazi - azimuth)
+ )
+
+ cos_zen = np.cos(skyvaultzen)
+ exp_arg_h = m_b / cos_zen
+ ang = np.arccos(cosSkySunAngle)
+ exp_arg_c = m_d * ang
+ circumsolar = 1 + m_c * np.exp(exp_arg_c) + m_e * cosSkySunAngle * cosSkySunAngle
+
+ lv = (1 + m_a * np.exp(exp_arg_h)) * circumsolar
+
+ # Normalisation (with safeguard)
+ if np.any(lv < 0):
+ print("Warning: found negative Perez luminances, using uniform distribution as fallback.")
+ lv.fill(1.0 / lv.size) # uniform fallback
+ else:
+ lv = lv / np.sum(lv)
+
+ # plotting
+ # axesm('stereo','Origin',[90 180],'MapLatLimit',[0 90],'Aspect','transverse')
+ # framem off; gridm on; mlabel off; plabel off;axis on;
+ # setm(gca,'MLabelParallel',-20)
+ # geoshow(skyvaultalt*rad2deg,skyvaultazi*rad2deg,lv,'DisplayType','texture');
+ # colorbar
+ # set(gcf,'Color',[1 1 1])
+ # pause(1)
+
+ if patchchoice == 1:
+ # x = np.atleast_2d([])
+ # lv = np.transpose(np.append(np.append(np.append(x, skyvaultalt*rad2deg), skyvaultazi*rad2deg), lv))
+ x = np.transpose(np.atleast_2d(skyvaultalt * rad2deg))
+ y = np.transpose(np.atleast_2d(skyvaultazi * rad2deg))
+ z = np.transpose(np.atleast_2d(lv))
+ lv = np.append(np.append(x, y, axis=1), z, axis=1)
+ return lv, PerezClearness, PerezBrightness
diff --git a/temp/.gitkeep b/pysrc/solweig/physics/__init__.py
similarity index 100%
rename from temp/.gitkeep
rename to pysrc/solweig/physics/__init__.py
diff --git a/pysrc/solweig/physics/clearnessindex_2013b.py b/pysrc/solweig/physics/clearnessindex_2013b.py
new file mode 100644
index 0000000..bf9b4e3
--- /dev/null
+++ b/pysrc/solweig/physics/clearnessindex_2013b.py
@@ -0,0 +1,88 @@
+import math
+
+import numpy as np
+
+from . import sun_distance
+
+__author__ = "xlinfr"
+
+
+def clearnessindex_2013b(zen, jday, Ta, RH, radG, location, P):
+ """Clearness Index at the Earth's surface calculated from Crawford and Duchon 1999
+
+ :param zen: zenith angle in radians
+ :param jday: day of year
+ :param Ta: air temperature
+ :param RH: relative humidity
+ :param radG: global shortwave radiation
+ :param location: distionary including lat, lon and alt
+ :param P: pressure
+ :return:
+ """
+
+ p = 1013.0 if P == -999.0 else P * 10.0 # Pressure in millibars (convert hPa to mb)
+
+ Itoa = 1370.0 # Effective solar constant
+ D = sun_distance.sun_distance(jday) # irradiance differences due to Sun-Earth distances
+ m = 35.0 * np.cos(zen) * ((1224.0 * (np.cos(zen) ** 2) + 1) ** (-1 / 2.0)) # optical air mass at p=1013
+ Trpg = (
+ 1.021 - 0.084 * (m * (0.000949 * p + 0.051)) ** 0.5
+ ) # Transmission coefficient for Rayliegh scattering and permanent gases
+
+ # empirical constant depending on latitude
+ if location["latitude"] < 10.0:
+ G_coeffs = [3.37, 2.85, 2.80, 2.64]
+ elif location["latitude"] >= 10.0 and location["latitude"] < 20.0:
+ G_coeffs = [2.99, 3.02, 2.70, 2.93]
+ elif location["latitude"] >= 20.0 and location["latitude"] < 30.0:
+ G_coeffs = [3.60, 3.00, 2.98, 2.93]
+ elif location["latitude"] >= 30.0 and location["latitude"] < 40.0:
+ G_coeffs = [3.04, 3.11, 2.92, 2.94]
+ elif location["latitude"] >= 40.0 and location["latitude"] < 50.0:
+ G_coeffs = [2.70, 2.95, 2.77, 2.71]
+ elif location["latitude"] >= 50.0 and location["latitude"] < 60.0:
+ G_coeffs = [2.52, 3.07, 2.67, 2.93]
+ elif location["latitude"] >= 60.0 and location["latitude"] < 70.0:
+ G_coeffs = [1.76, 2.69, 2.61, 2.61]
+ elif location["latitude"] >= 70.0 and location["latitude"] < 80.0:
+ G_coeffs = [1.60, 1.67, 2.24, 2.63]
+ else: # latitude >= 80.0
+ G_coeffs = [1.11, 1.44, 1.94, 2.02]
+
+ if jday > 335 or jday <= 60:
+ G: float = G_coeffs[0]
+ elif jday > 60 and jday <= 152:
+ G = G_coeffs[1]
+ elif jday > 152 and jday <= 244:
+ G = G_coeffs[2]
+ else: # jday > 244 and jday <= 335
+ G = G_coeffs[3]
+
+ # dewpoint calculation
+ a2 = 17.27
+ b2 = 237.7
+ Td = (b2 * (((a2 * Ta) / (b2 + Ta)) + np.log(RH))) / (a2 - (((a2 * Ta) / (b2 + Ta)) + np.log(RH)))
+ Td = (Td * 1.8) + 32 # Dewpoint (F)
+ u = np.exp(0.1133 - np.log(G + 1) + 0.0393 * Td) # Precipitable water
+ Tw = 1 - 0.077 * ((u * m) ** 0.3) # Transmission coefficient for water vapor
+ Tar = 0.935**m # Transmission coefficient for aerosols
+
+ I0 = Itoa * np.cos(zen) * Trpg * Tw * D * Tar
+ if abs(zen) > np.pi / 2:
+ I0 = 0
+ # b=I0==abs(zen)>np.pi/2
+ # I0(b==1)=0
+ # clear b;
+ if not (np.isreal(I0)):
+ I0 = 0
+
+ corr = 0.1473 * np.log(90 - (zen / np.pi * 180)) + 0.3454 # 20070329
+
+ CIuncorr = radG / I0
+ CI = CIuncorr + (1 - corr)
+ I0et = Itoa * np.cos(zen) * D # extra terrestial solar radiation
+ Kt = radG / I0et
+ if math.isnan(CI):
+ CI = float("Inf")
+
+ return I0, CI, Kt, I0et, CIuncorr
diff --git a/pysrc/solweig/physics/create_patches.py b/pysrc/solweig/physics/create_patches.py
new file mode 100644
index 0000000..72d85e0
--- /dev/null
+++ b/pysrc/solweig/physics/create_patches.py
@@ -0,0 +1,68 @@
+import numpy as np
+
+
+def create_patches(patch_option):
+ # patch_option = 1 = 145 patches (Robinson & Stone, 2004)
+ # patch_option = 2 = 153 patches (Wallenberg et al., 2022)
+ # patch_option = 3 = 306 patches -> test
+ # patch_option = 4 = 612 patches -> test
+
+ skyvaultalt = np.atleast_2d([])
+ skyvaultazi = np.atleast_2d([])
+
+ # Creating skyvault of patches of constant radians (Tregeneza and Sharples, 1993)
+ # Patch option 1, 145 patches, Original Robinson & Stone (2004) after Tregenza (1987)/Tregenza & Sharples (1993)
+ if patch_option == 1:
+ annulino = np.array([0, 12, 24, 36, 48, 60, 72, 84, 90])
+ skyvaultaltint = np.array([6, 18, 30, 42, 54, 66, 78, 90]) # Robinson & Stone (2004)
+ azistart = np.array([0, 4, 2, 5, 8, 0, 10, 0]) # Fredrik/Nils
+ patches_in_band = np.array([30, 30, 24, 24, 18, 12, 6, 1]) # Robinson & Stone (2004)
+ # Patch option 2, 153 patches, Wallenberg et al. (2022)
+ elif patch_option == 2:
+ annulino = np.array([0, 12, 24, 36, 48, 60, 72, 84, 90])
+ skyvaultaltint = np.array([6, 18, 30, 42, 54, 66, 78, 90]) # Robinson & Stone (2004)
+ azistart = np.array([0, 4, 2, 5, 8, 0, 10, 0]) # Fredrik/Nils
+ patches_in_band = np.array([31, 30, 28, 24, 19, 13, 7, 1]) # Nils
+ # Patch option 3, 306 patches, test
+ elif patch_option == 3:
+ annulino = np.array([0, 12, 24, 36, 48, 60, 72, 84, 90])
+ skyvaultaltint = np.array([6, 18, 30, 42, 54, 66, 78, 90]) # Robinson & Stone (2004)
+ azistart = np.array([0, 4, 2, 5, 8, 0, 10, 0]) # Fredrik/Nils
+ patches_in_band = np.array([31 * 2, 30 * 2, 28 * 2, 24 * 2, 19 * 2, 13 * 2, 7 * 2, 1]) # Nils
+ # Patch option 4, 612 patches, test
+ elif patch_option == 4:
+ annulino = np.array([0, 4.5, 9, 15, 21, 27, 33, 39, 45, 51, 57, 63, 69, 75, 81, 90]) # Nils
+ skyvaultaltint = np.array([3, 9, 15, 21, 27, 33, 39, 45, 51, 57, 63, 69, 75, 81, 90]) # Nils
+ patches_in_band = np.array(
+ [
+ 31 * 2,
+ 31 * 2,
+ 30 * 2,
+ 30 * 2,
+ 28 * 2,
+ 28 * 2,
+ 24 * 2,
+ 24 * 2,
+ 19 * 2,
+ 19 * 2,
+ 13 * 2,
+ 13 * 2,
+ 7 * 2,
+ 7 * 2,
+ 1,
+ ]
+ ) # Nils
+ azistart = np.array([0, 0, 4, 4, 2, 2, 5, 5, 8, 8, 0, 0, 10, 10, 0]) # Nils
+
+ skyvaultaziint = np.array([360 / patches for patches in patches_in_band])
+
+ for j in range(0, skyvaultaltint.shape[0]):
+ for k in range(0, patches_in_band[j]):
+ skyvaultalt = np.append(skyvaultalt, skyvaultaltint[j])
+ skyvaultazi = np.append(skyvaultazi, k * skyvaultaziint[j] + azistart[j])
+
+ # skyvaultzen = (90 - skyvaultalt) * deg2rad
+ # skyvaultalt = skyvaultalt * deg2rad
+ # skyvaultazi = skyvaultazi * deg2rad
+
+ return skyvaultalt, skyvaultazi, annulino, skyvaultaltint, patches_in_band, skyvaultaziint, azistart
diff --git a/pysrc/solweig/physics/cylindric_wedge.py b/pysrc/solweig/physics/cylindric_wedge.py
new file mode 100644
index 0000000..3403ef8
--- /dev/null
+++ b/pysrc/solweig/physics/cylindric_wedge.py
@@ -0,0 +1,109 @@
+import numpy as np
+
+from ..constants import MIN_SUN_ELEVATION_DEG
+
+# Convert to radians for internal use
+_MIN_SUN_ALTITUDE_RAD = MIN_SUN_ELEVATION_DEG * (np.pi / 180.0)
+
+
+def cylindric_wedge(zen, svfalfa, rows, cols):
+ """
+ Fraction of sunlit walls based on sun altitude and SVF-weighted building angles.
+
+ Args:
+ zen: Sun zenith angle (radians)
+ svfalfa: SVF-related angle grid (2D array, radians)
+ rows, cols: Grid dimensions (unused, kept for API compatibility)
+
+ Returns:
+ F_sh: Shadow fraction grid (0 = fully sunlit, 1 = fully shaded)
+
+ Note:
+ At very low sun altitudes (< 3°), returns F_sh = 1.0 to avoid
+ numerical instability from tan(zen) approaching infinity.
+ """
+ # Guard against low sun angles where tan(zen) → infinity
+ # zenith = 90° - altitude, so zen > 87° means altitude < 3°
+ altitude_rad = (np.pi / 2.0) - zen
+ if altitude_rad < _MIN_SUN_ALTITUDE_RAD:
+ # Sun too low - walls fully shaded
+ return np.ones_like(svfalfa, dtype=np.float32)
+
+ # Pre-compute trigonometric values once (1.7x speedup)
+ tan_zen = np.tan(zen)
+ tan_alfa = np.tan(svfalfa)
+
+ # Guard against very small tan_alfa (near-horizontal surfaces)
+ tan_alfa = np.maximum(tan_alfa, 1e-6)
+
+ ba = 1.0 / tan_alfa
+ tan_product = tan_alfa * tan_zen
+
+ # Guard against division by very small values
+ tan_product = np.maximum(tan_product, 1e-6)
+
+ xa = 1 - 2.0 / tan_product
+ ha = 2.0 / tan_product
+ hkil = 2.0 * ba * ha
+
+ # Use np.where for vectorized conditionals (avoids index assignment overhead)
+ mask = xa < 0
+ qa = np.where(mask, tan_zen / 2, 0.0).astype(np.float32)
+
+ # Compute Za with safe sqrt
+ ba_sq = ba**2
+ Za_sq = np.maximum(ba_sq - (qa**2) / 4, 0)
+ Za = np.where(mask, np.sqrt(Za_sq), 0.0).astype(np.float32)
+
+ # Safe arctan (avoid division by zero)
+ phi = np.where(mask & (qa > 1e-10), np.arctan(Za / np.maximum(qa, 1e-10)), 0.0).astype(np.float32)
+
+ # Compute A with safe denominator
+ cos_phi = np.cos(phi)
+ sin_phi = np.sin(phi)
+ denom = np.maximum(1 - cos_phi, 1e-10)
+ A = np.where(mask, (sin_phi - phi * cos_phi) / denom, 0.0).astype(np.float32)
+
+ ukil = np.where(mask, 2 * ba * xa * A, 0.0).astype(np.float32)
+
+ Ssurf = hkil + ukil
+ F_sh = (2 * np.pi * ba - Ssurf) / (2 * np.pi * ba)
+
+ return F_sh.astype(np.float32)
+
+
+def cylindric_wedge_voxel(zen, svfalfa):
+ np.seterr(divide="ignore", invalid="ignore")
+
+ # Fraction of sunlit walls based on sun altitude and svf wieghted building angles
+ # input:
+ # sun zenith angle "beta"
+ # svf related angle "alfa"
+
+ beta = zen
+
+ xa = 1 - 2.0 / (np.tan(svfalfa) * np.tan(beta))
+ ha = 2.0 / (np.tan(svfalfa) * np.tan(beta))
+ ba = 1.0 / np.tan(svfalfa)
+ hkil = 2.0 * ba * ha
+
+ qa = np.zeros((svfalfa.shape[0]), dtype=np.float32)
+ qa[xa < 0] = np.tan(beta) / 2
+
+ Za = np.zeros((svfalfa.shape[0]), dtype=np.float32)
+ Za[xa < 0] = ((ba[xa < 0] ** 2) - ((qa[xa < 0] ** 2) / 4)) ** 0.5
+
+ phi = np.zeros((svfalfa.shape[0]), dtype=np.float32)
+ phi[xa < 0] = np.arctan(Za[xa < 0] / qa[xa < 0])
+
+ A = np.zeros((svfalfa.shape[0]), dtype=np.float32)
+ A[xa < 0] = (np.sin(phi[xa < 0]) - phi[xa < 0] * np.cos(phi[xa < 0])) / (1 - np.cos(phi[xa < 0]))
+
+ ukil = np.zeros((svfalfa.shape[0]), dtype=np.float32)
+ ukil[xa < 0] = 2 * ba[xa < 0] * xa[xa < 0] * A[xa < 0]
+
+ Ssurf = hkil + ukil
+
+ F_sh = (2 * np.pi * ba - Ssurf) / (2 * np.pi * ba)
+
+ return F_sh
diff --git a/pysrc/solweig/physics/daylen.py b/pysrc/solweig/physics/daylen.py
new file mode 100644
index 0000000..442185e
--- /dev/null
+++ b/pysrc/solweig/physics/daylen.py
@@ -0,0 +1,22 @@
+import numpy as np
+
+
+def daylen(DOY, XLAT):
+ # Calculation of declination of sun (Eqn. 16). Amplitude= +/-23.45
+ # deg. Minimum = DOY 355 (DEC 21), maximum = DOY 172.5 (JUN 21/22).
+ # Sun angles. SOC limited for latitudes above polar circles.
+ # Calculate daylength, sunrise and sunset (Eqn. 17)
+
+ RAD = np.pi / 180.0
+
+ DEC = -23.45 * np.cos(2.0 * np.pi * (DOY + 10.0) / 365.0)
+
+ SOC = np.tan(RAD * DEC) * np.tan(RAD * XLAT)
+ SOC = min(max(SOC, -1.0), 1.0)
+ # SOC=alt
+
+ DAYL = 12.0 + 24.0 * np.arcsin(SOC) / np.pi
+ SNUP = 12.0 - DAYL / 2.0
+ SNDN = 12.0 + DAYL / 2.0
+
+ return DAYL, DEC, SNDN, SNUP
diff --git a/pysrc/solweig/physics/diffusefraction.py b/pysrc/solweig/physics/diffusefraction.py
new file mode 100644
index 0000000..46d60b4
--- /dev/null
+++ b/pysrc/solweig/physics/diffusefraction.py
@@ -0,0 +1,47 @@
+import numpy as np
+
+
+def diffusefraction(radG, altitude, Kt, Ta, RH):
+ """
+ This function estimates diffuse and directbeam radiation according to
+ Reindl et al (1990), Solar Energy 45:1
+
+ :param radG:
+ :param altitude:
+ :param Kt: # radiation at the top of the atmosphere
+ :param Ta:
+ :param RH:
+ :return:
+ """
+
+ alfa = altitude * (np.pi / 180)
+
+ if Ta <= -999.00 or RH <= -999.00 or np.isnan(Ta) or np.isnan(RH):
+ if Kt <= 0.3:
+ radD = radG * (1.020 - 0.248 * Kt)
+ elif Kt > 0.3 and Kt < 0.78:
+ radD = radG * (1.45 - 1.67 * Kt)
+ else:
+ radD = radG * 0.147
+ else:
+ RH = RH / 100
+ if Kt <= 0.3:
+ radD = radG * (1 - 0.232 * Kt + 0.0239 * np.sin(alfa) - 0.000682 * Ta + 0.0195 * RH)
+ elif Kt > 0.3 and Kt < 0.78:
+ radD = radG * (1.329 - 1.716 * Kt + 0.267 * np.sin(alfa) - 0.00357 * Ta + 0.106 * RH)
+ else:
+ radD = radG * (0.426 * Kt - 0.256 * np.sin(alfa) + 0.00349 * Ta + 0.0734 * RH)
+
+ radI = (radG - radD) / (np.sin(alfa))
+
+ # Corrections for low sun altitudes (20130307)
+ if radI < 0:
+ radI = 0
+
+ if altitude < 1 and radI > radG:
+ radI = radG
+
+ if radD > radG:
+ radD = radG
+
+ return radI, radD
diff --git a/pysrc/solweig/physics/morphology.py b/pysrc/solweig/physics/morphology.py
new file mode 100644
index 0000000..724c594
--- /dev/null
+++ b/pysrc/solweig/physics/morphology.py
@@ -0,0 +1,188 @@
+"""
+Pure numpy implementations of morphological operations.
+
+Replaces scipy.ndimage functions to eliminate the scipy dependency,
+making the package lighter for QGIS plugin distribution.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def rotate_array(
+ array: NDArray[np.floating],
+ angle: float,
+ order: int = 1,
+ reshape: bool = False,
+ mode: str = "nearest",
+) -> NDArray[np.floating]:
+ """
+ Rotate a 2D array by the given angle (in degrees).
+
+ Pure numpy implementation replacing scipy.ndimage.interpolation.rotate.
+
+ Args:
+ array: 2D input array to rotate.
+ angle: Rotation angle in degrees (counter-clockwise).
+ order: Interpolation order (0=nearest, 1=bilinear).
+ reshape: If True, output shape is adjusted to contain the whole rotated array.
+ If False (default), output has same shape as input.
+ mode: How to handle boundaries ('nearest', 'constant').
+
+ Returns:
+ Rotated array.
+ """
+ if reshape:
+ raise NotImplementedError("reshape=True not implemented")
+
+ rows, cols = array.shape
+ # scipy uses pixel-centered coordinates: center is at (n-1)/2 for n pixels
+ center_y, center_x = (rows - 1) / 2, (cols - 1) / 2
+
+ # Convert angle to radians
+ theta = np.radians(angle)
+ cos_t, sin_t = np.cos(theta), np.sin(theta)
+
+ # Create output array
+ output = np.zeros_like(array)
+
+ # Create coordinate grids
+ y_indices, x_indices = np.mgrid[0:rows, 0:cols]
+
+ # Translate to center, rotate, translate back (inverse mapping)
+ # For each output pixel, find the corresponding input pixel
+ x_centered = x_indices - center_x
+ y_centered = y_indices - center_y
+
+ # Inverse rotation to find source coordinates
+ # scipy.ndimage.rotate uses counter-clockwise in image coordinates (y pointing down)
+ # For inverse mapping, we apply the transpose of the rotation matrix
+ src_x = cos_t * x_centered - sin_t * y_centered + center_x
+ src_y = sin_t * x_centered + cos_t * y_centered + center_y
+
+ if order == 0:
+ # Nearest neighbor interpolation
+ src_x_int = np.round(src_x).astype(np.int32)
+ src_y_int = np.round(src_y).astype(np.int32)
+
+ # Clip to valid range
+ src_x_int = np.clip(src_x_int, 0, cols - 1)
+ src_y_int = np.clip(src_y_int, 0, rows - 1)
+
+ output = array[src_y_int, src_x_int]
+
+ elif order == 1:
+ # Bilinear interpolation
+ x0 = np.floor(src_x).astype(np.int32)
+ y0 = np.floor(src_y).astype(np.int32)
+ x1 = x0 + 1
+ y1 = y0 + 1
+
+ # Clip coordinates
+ x0_clipped = np.clip(x0, 0, cols - 1)
+ x1_clipped = np.clip(x1, 0, cols - 1)
+ y0_clipped = np.clip(y0, 0, rows - 1)
+ y1_clipped = np.clip(y1, 0, rows - 1)
+
+ # Weights
+ wx = src_x - x0
+ wy = src_y - y0
+ wx = np.clip(wx, 0, 1)
+ wy = np.clip(wy, 0, 1)
+
+ # Bilinear interpolation
+ output = (
+ array[y0_clipped, x0_clipped] * (1 - wx) * (1 - wy)
+ + array[y0_clipped, x1_clipped] * wx * (1 - wy)
+ + array[y1_clipped, x0_clipped] * (1 - wx) * wy
+ + array[y1_clipped, x1_clipped] * wx * wy
+ )
+ else:
+ raise ValueError(f"order must be 0 or 1, got {order}")
+
+ return output.astype(array.dtype)
+
+
+def binary_dilation(
+ input_array: NDArray[np.bool_],
+ structure: NDArray[np.bool_] | None = None,
+ iterations: int = 1,
+) -> NDArray[np.bool_]:
+ """
+ Perform binary dilation on a 2D boolean array.
+
+ Pure numpy implementation replacing scipy.ndimage.binary_dilation.
+
+ Args:
+ input_array: 2D boolean array to dilate.
+ structure: Structuring element (3x3 boolean array).
+ If None, uses 8-connectivity (all neighbors).
+ iterations: Number of times to apply dilation.
+
+ Returns:
+ Dilated boolean array.
+ """
+ if structure is None:
+ # Default: 8-connectivity (3x3 all ones)
+ structure = np.ones((3, 3), dtype=bool)
+
+ result = input_array.copy()
+
+ for _ in range(iterations):
+ # Pad the array
+ padded = np.pad(result, 1, mode="constant", constant_values=False)
+ new_result = np.zeros_like(result)
+
+ # Apply structuring element
+ rows, cols = result.shape
+ struct_rows, struct_cols = structure.shape
+ offset_r = struct_rows // 2
+ offset_c = struct_cols // 2
+
+ for dr in range(struct_rows):
+ for dc in range(struct_cols):
+ if structure[dr, dc]:
+ shifted = padded[
+ 1 + dr - offset_r : 1 + rows + dr - offset_r,
+ 1 + dc - offset_c : 1 + cols + dc - offset_c,
+ ]
+ new_result |= shifted
+
+ result = new_result
+
+ return result
+
+
+def generate_binary_structure(rank: int, connectivity: int) -> NDArray[np.bool_]:
+ """
+ Generate a binary structuring element for morphological operations.
+
+ Pure numpy implementation replacing scipy.ndimage.generate_binary_structure.
+
+ Args:
+ rank: Number of dimensions (must be 2).
+ connectivity: 1 for 4-connectivity (cross), 2 for 8-connectivity (square).
+
+ Returns:
+ 3x3 boolean structuring element.
+ """
+ if rank != 2:
+ raise ValueError(f"Only rank=2 supported, got {rank}")
+
+ if connectivity == 1:
+ # 4-connectivity (cross pattern)
+ return np.array(
+ [
+ [False, True, False],
+ [True, True, True],
+ [False, True, False],
+ ],
+ dtype=bool,
+ )
+ elif connectivity == 2:
+ # 8-connectivity (all neighbors)
+ return np.ones((3, 3), dtype=bool)
+ else:
+ raise ValueError(f"connectivity must be 1 or 2, got {connectivity}")
diff --git a/pysrc/solweig/physics/patch_radiation.py b/pysrc/solweig/physics/patch_radiation.py
new file mode 100644
index 0000000..8c1cd9e
--- /dev/null
+++ b/pysrc/solweig/physics/patch_radiation.py
@@ -0,0 +1,373 @@
+import numpy as np
+
+from ..constants import KELVIN_OFFSET, SBC
+
+
+def shortwave_from_sky(sky, angle_of_incidence, lumChi, steradian, patch_azimuth, cyl):
+ """Calculates the amount of diffuse shortwave radiation from the sky for a patch with:
+ angle of incidence = angle_of_incidence
+ luminance = lumChi
+ steradian = steradian"""
+
+ # Diffuse vertical radiation
+ diffuse_shortwave_radiation = sky * lumChi * angle_of_incidence * steradian
+
+ return diffuse_shortwave_radiation
+
+
+def longwave_from_sky(sky, Lsky_side, Lsky_down, patch_azimuth):
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ # Longwave radiation from sky to vertical surface
+ Ldown_sky = sky * Lsky_down
+
+ # Longwave radiation from sky to horizontal surface
+ Lside_sky = sky * Lsky_side
+
+ #
+ Least = np.zeros((sky.shape[0], sky.shape[1]), dtype=np.float32)
+ Lsouth = np.zeros((sky.shape[0], sky.shape[1]), dtype=np.float32)
+ Lwest = np.zeros((sky.shape[0], sky.shape[1]), dtype=np.float32)
+ Lnorth = np.zeros((sky.shape[0], sky.shape[1]), dtype=np.float32)
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = sky * Lsky_side * np.cos((90 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = sky * Lsky_side * np.cos((180 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = sky * Lsky_side * np.cos((270 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = sky * Lsky_side * np.cos((0 - patch_azimuth) * deg2rad)
+
+ return Lside_sky, Ldown_sky, Least, Lsouth, Lwest, Lnorth
+
+
+def longwave_from_veg(
+ vegetation, steradian, angle_of_incidence, angle_of_incidence_h, patch_altitude, patch_azimuth, ewall, Ta
+):
+ """Calculates the amount of longwave radiation from vegetation for a patch with:
+ angle of incidence = angle_of_incidence
+ steradian = steradian
+ if a patch is vegetation = vegetation
+ amount of radiation from vegetated patch = vegetation_surface"""
+
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ # Longwave radiation from vegetation surface (considered vertical)
+ vegetation_surface = (ewall * SBC * ((Ta + KELVIN_OFFSET) ** 4)) / np.pi
+
+ # Longwave radiation reaching a vertical surface
+ Lside_veg = vegetation_surface * steradian * angle_of_incidence * vegetation
+
+ # Longwave radiation reaching a horizontal surface
+ Ldown_veg = vegetation_surface * steradian * angle_of_incidence_h * vegetation
+
+ #
+ Least = np.zeros((vegetation.shape[0], vegetation.shape[1]), dtype=np.float32)
+ Lsouth = np.zeros((vegetation.shape[0], vegetation.shape[1]), dtype=np.float32)
+ Lwest = np.zeros((vegetation.shape[0], vegetation.shape[1]), dtype=np.float32)
+ Lnorth = np.zeros((vegetation.shape[0], vegetation.shape[1]), dtype=np.float32)
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = (
+ vegetation_surface
+ * steradian
+ * np.cos(patch_altitude * deg2rad)
+ * vegetation
+ * np.cos((90 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = (
+ vegetation_surface
+ * steradian
+ * np.cos(patch_altitude * deg2rad)
+ * vegetation
+ * np.cos((180 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = (
+ vegetation_surface
+ * steradian
+ * np.cos(patch_altitude * deg2rad)
+ * vegetation
+ * np.cos((270 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = (
+ vegetation_surface
+ * steradian
+ * np.cos(patch_altitude * deg2rad)
+ * vegetation
+ * np.cos((0 - patch_azimuth) * deg2rad)
+ )
+
+ return Lside_veg, Ldown_veg, Least, Lsouth, Lwest, Lnorth
+
+
+def longwave_from_buildings(
+ building,
+ steradian,
+ angle_of_incidence,
+ angle_of_incidence_h,
+ patch_azimuth,
+ sunlit_patches,
+ shaded_patches,
+ azimuth_difference,
+ solar_altitude,
+ ewall,
+ Ta,
+ Tgwall,
+):
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ #
+ Least = np.zeros((building.shape[0], building.shape[1]), dtype=np.float32)
+ Lsouth = np.zeros((building.shape[0], building.shape[1]), dtype=np.float32)
+ Lwest = np.zeros((building.shape[0], building.shape[1]), dtype=np.float32)
+ Lnorth = np.zeros((building.shape[0], building.shape[1]), dtype=np.float32)
+
+ # Longwave radiation from sunlit surfaces
+ sunlit_surface = (ewall * SBC * ((Ta + Tgwall + KELVIN_OFFSET) ** 4)) / np.pi
+ # Longwave radiation from shaded surfaces
+ shaded_surface = (ewall * SBC * ((Ta + KELVIN_OFFSET) ** 4)) / np.pi
+ if (azimuth_difference > 90) and (azimuth_difference < 270) and (solar_altitude > 0):
+ # Calculate which patches defined as buildings that are sunlit or shaded
+ # sunlit_patches, shaded_patches = sunlit_shaded_patches.shaded_or_sunlit(
+ # solar_altitude, solar_azimuth, patch_altitude, patch_azimuth, asvf
+ # )
+
+ # Calculate longwave radiation from sunlit walls to vertical surface
+ Lside_sun = sunlit_surface * sunlit_patches * steradian * angle_of_incidence * building
+ # Calculate longwave radiation from shaded walls to vertical surface
+ Lside_sh = shaded_surface * shaded_patches * steradian * angle_of_incidence * building
+
+ # Calculate longwave radiation from sunlit walls to horizontal surface
+ Ldown_sun = sunlit_surface * sunlit_patches * steradian * angle_of_incidence_h * building
+ # Calculate longwave radiation from shaded walls to horizontal surface
+ Ldown_sh = shaded_surface * shaded_patches * steradian * angle_of_incidence_h * building
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = (
+ sunlit_surface
+ * sunlit_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((90 - patch_azimuth) * deg2rad)
+ )
+ Least += (
+ shaded_surface
+ * shaded_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((90 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = (
+ sunlit_surface
+ * sunlit_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((180 - patch_azimuth) * deg2rad)
+ )
+ Lsouth += (
+ shaded_surface
+ * shaded_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((180 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = (
+ sunlit_surface
+ * sunlit_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((270 - patch_azimuth) * deg2rad)
+ )
+ Lwest += (
+ shaded_surface
+ * shaded_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((270 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = (
+ sunlit_surface
+ * sunlit_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((0 - patch_azimuth) * deg2rad)
+ )
+ Lnorth += (
+ shaded_surface
+ * shaded_patches
+ * steradian
+ * angle_of_incidence
+ * building
+ * np.cos((0 - patch_azimuth) * deg2rad)
+ )
+
+ else:
+ # Calculate longwave radiation from shaded walls reaching a vertical surface
+ Lside_sh = shaded_surface * steradian * angle_of_incidence * building
+ Lside_sun = np.zeros((Lside_sh.shape[0], Lside_sh.shape[1]), dtype=np.float32)
+
+ # Calculate longwave radiation from shaded walls reaching a horizontal surface
+ Ldown_sh = shaded_surface * steradian * angle_of_incidence_h * building
+ Ldown_sun = np.zeros((Lside_sh.shape[0], Lside_sh.shape[1]), dtype=np.float32)
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = shaded_surface * steradian * angle_of_incidence * building * np.cos((90 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = (
+ shaded_surface * steradian * angle_of_incidence * building * np.cos((180 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = shaded_surface * steradian * angle_of_incidence * building * np.cos((270 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = shaded_surface * steradian * angle_of_incidence * building * np.cos((0 - patch_azimuth) * deg2rad)
+
+ return Lside_sun, Lside_sh, Ldown_sun, Ldown_sh, Least, Lsouth, Lwest, Lnorth
+
+
+def longwave_from_buildings_wallScheme(
+ voxelMaps, voxelTable, steradian, angle_of_incidence, angle_of_incidence_h, patch_azimuth
+):
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ #
+ Lside = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Lside_sh = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Ldown = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Ldown_sh = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Least = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Lsouth = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Lwest = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+ Lnorth = np.zeros((voxelMaps.shape[0], voxelMaps.shape[1]), dtype=np.float32)
+
+ # print(voxelMaps)
+ # print(voxelTable.head())
+ unique_ids = list(np.unique(voxelMaps)[1:])
+ # print(unique_ids)
+ lw_rad_dict = dict(voxelTable.loc[unique_ids, "LongwaveRadiation"])
+ # print(lw_rad_dict)
+ patch_radiation = np.vectorize(lw_rad_dict.get)(voxelMaps).astype(float)
+ patch_radiation[np.isnan(patch_radiation)] = 0
+ Lside += patch_radiation * steradian * angle_of_incidence
+ Ldown += patch_radiation * steradian * angle_of_incidence_h
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = patch_radiation * steradian * angle_of_incidence * np.cos((90 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = patch_radiation * steradian * angle_of_incidence * np.cos((180 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = patch_radiation * steradian * angle_of_incidence * np.cos((270 - patch_azimuth) * deg2rad)
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = patch_radiation * steradian * angle_of_incidence * np.cos((0 - patch_azimuth) * deg2rad)
+
+ return Lside, Lside_sh, Ldown, Ldown_sh, Least, Lsouth, Lwest, Lnorth
+
+
+def reflected_longwave(
+ reflecting_surface, steradian, angle_of_incidence, angle_of_incidence_h, patch_azimuth, Ldown_sky, Lup, ewall
+):
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ # Calculate reflected longwave in each patch
+ reflected_radiation = ((Ldown_sky + Lup) * (1 - ewall) * 0.5) / np.pi
+
+ # Reflected longwave radiation reaching vertical surfaces
+ Lside_ref = reflected_radiation * steradian * angle_of_incidence * reflecting_surface
+
+ # Reflected longwave radiation reaching horizontal surfaces
+ Ldown_ref = reflected_radiation * steradian * angle_of_incidence_h * reflecting_surface
+
+ #
+ Least = np.zeros((reflecting_surface.shape[0], reflecting_surface.shape[1]), dtype=np.float32)
+ Lsouth = np.zeros((reflecting_surface.shape[0], reflecting_surface.shape[1]), dtype=np.float32)
+ Lwest = np.zeros((reflecting_surface.shape[0], reflecting_surface.shape[1]), dtype=np.float32)
+ Lnorth = np.zeros((reflecting_surface.shape[0], reflecting_surface.shape[1]), dtype=np.float32)
+
+ # Portion into cardinal directions to be used for standing box or POI output
+ if (patch_azimuth > 360) or (patch_azimuth < 180):
+ Least = (
+ reflected_radiation
+ * steradian
+ * angle_of_incidence
+ * reflecting_surface
+ * np.cos((90 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 90) and (patch_azimuth < 270):
+ Lsouth = (
+ reflected_radiation
+ * steradian
+ * angle_of_incidence
+ * reflecting_surface
+ * np.cos((180 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 180) and (patch_azimuth < 360):
+ Lwest = (
+ reflected_radiation
+ * steradian
+ * angle_of_incidence
+ * reflecting_surface
+ * np.cos((270 - patch_azimuth) * deg2rad)
+ )
+ if (patch_azimuth > 270) or (patch_azimuth < 90):
+ Lnorth = (
+ reflected_radiation
+ * steradian
+ * angle_of_incidence
+ * reflecting_surface
+ * np.cos((0 - patch_azimuth) * deg2rad)
+ )
+
+ return Lside_ref, Ldown_ref, Least, Lsouth, Lwest, Lnorth
+
+
+def patch_steradians(L_patches):
+ """'This function calculates the steradians of the patches"""
+
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ # Unique altitudes for patches
+ skyalt, skyalt_c = np.unique(L_patches[:, 0], return_counts=True)
+
+ # Altitudes of the Robinson & Stone patches
+ patch_altitude = L_patches[:, 0]
+
+ # Calculation of steradian for each patch
+ steradian = np.zeros((patch_altitude.shape[0]), dtype=np.float32)
+ for i in range(patch_altitude.shape[0]):
+ # If there are more than one patch in a band
+ if skyalt_c[skyalt == patch_altitude[i]] > 1:
+ steradian[i] = ((360 / skyalt_c[skyalt == patch_altitude[i]]) * deg2rad) * (
+ np.sin((patch_altitude[i] + patch_altitude[0]) * deg2rad)
+ - np.sin((patch_altitude[i] - patch_altitude[0]) * deg2rad)
+ )
+ # If there is only one patch in band, i.e. 90 degrees
+ else:
+ steradian[i] = ((360 / skyalt_c[skyalt == patch_altitude[i]]) * deg2rad) * (
+ np.sin((patch_altitude[i]) * deg2rad) - np.sin((patch_altitude[i - 1] + patch_altitude[0]) * deg2rad)
+ )
+
+ return steradian, skyalt, patch_altitude
diff --git a/pysrc/solweig/physics/sun_distance.py b/pysrc/solweig/physics/sun_distance.py
new file mode 100644
index 0000000..68c2034
--- /dev/null
+++ b/pysrc/solweig/physics/sun_distance.py
@@ -0,0 +1,20 @@
+__author__ = "xlinfr"
+import numpy as np
+
+
+def sun_distance(jday):
+ """
+
+ #% Calculatesrelative earth sun distance
+ #% with day of year as input.
+ #% Partridge and Platt, 1975
+ """
+ b = 2.0 * np.pi * jday / 365.0
+ D = np.sqrt(
+ 1.00011
+ + np.dot(0.034221, np.cos(b))
+ + np.dot(0.001280, np.sin(b))
+ + np.dot(0.000719, np.cos(2.0 * b))
+ + np.dot(0.000077, np.sin(2.0 * b))
+ )
+ return D
diff --git a/pysrc/solweig/physics/sun_position.py b/pysrc/solweig/physics/sun_position.py
new file mode 100644
index 0000000..3875546
--- /dev/null
+++ b/pysrc/solweig/physics/sun_position.py
@@ -0,0 +1,1061 @@
+import numpy as np
+
+
+def sun_position(time, location):
+ """
+ % sun = sun_position(time, location)
+ %
+ % This function compute the sun position (zenith and azimuth angle at the observer
+ % location) as a function of the observer local time and position.
+ %
+ % It is an implementation of the algorithm presented by Reda et Andreas in:
+ % Reda, I., Andreas, A. (2003) Solar position algorithm for solar
+ % radiation application. National Renewable Energy Laboratory (NREL)
+ % Technical report NREL/TP-560-34302.
+ % This document is avalaible at www.osti.gov/bridge
+ %
+ % This algorithm is based on numerical approximation of the exact equations.
+ % The authors of the original paper state that this algorithm should be
+ % precise at +/- 0.0003 degrees. I have compared it to NOAA solar table
+ % (http://www.srrb.noaa.gov/highlights/sunrise/azel.html) and to USNO solar
+ % table (http://aa.usno.navy.mil/data/docs/AltAz.html) and found very good
+ % correspondance (up to the precision of those tables), except for large
+ % zenith angle, where the refraction by the atmosphere is significant
+ % (difference of about 1 degree). Note that in this code the correction
+ % for refraction in the atmosphere as been implemented for a temperature
+ % of 10C (283 kelvins) and a pressure of 1010 mbar. See the subfunction
+ % �sun_topocentric_zenith_angle_calculation� for a possible modification
+ % to explicitely model the effect of temperature and pressure as describe
+ % in Reda & Andreas (2003).
+ %
+ % Input parameters:
+ % time: a structure that specify the time when the sun position is
+ % calculated.
+ % time.year: year. Valid for [-2000, 6000]
+ % time.month: month [1-12]
+ % time.day: calendar day [1-31]
+ % time.hour: local hour [0-23]
+ % time.min: minute [0-59]
+ % time.sec: second [0-59]
+ % time.UTC: offset hour from UTC. Local time = Greenwich time + time.UTC
+ % This input can also be passed using the Matlab time format ('dd-mmm-yyyy HH:MM:SS').
+ % In that case, the time has to be specified as UTC time (time.UTC = 0)
+ %
+ % location: a structure that specify the location of the observer
+ % location.latitude: latitude (in degrees, north of equator is
+ % positive)
+ % location.longitude: longitude (in degrees, positive for east of
+ % Greenwich)
+ % location.altitude: altitude above mean sea level (in meters)
+ %
+ % Output parameters
+ % sun: a structure with the calculated sun position
+ % sun.zenith = zenith angle in degrees (angle from the vertical)
+ % sun.azimuth = azimuth angle in degrees, eastward from the north.
+ % Only the sun zenith and azimuth angles are returned as output, but a lot
+ % of other parameters are calculated that could also extracted as output of
+ % this function.
+ %
+ % Exemple of use
+ %
+ % location.longitude = -105.1786;
+ % location.latitude = 39.742476;
+ % location.altitude = 1830.14;
+ % time.year = 2005;
+ % time.month = 10;
+ % time.day = 17;
+ % time.hour = 6;
+ % time.min = 30;
+ % time.sec = 30;
+ % time.UTC = -7;
+ % %
+ % location.longitude = 11.94;
+ % location.latitude = 57.70;
+ % location.altitude = 3.0;
+ % time.UTC = 1;
+ % sun = sun_position(time, location);
+ %
+ % sun =
+ %
+ % zenith: 50.1080438859849
+ % azimuth: 194.341174010338
+ %
+ % History
+ % 09/03/2004 Original creation by Vincent Roy (vincent.roy@drdc-rddc.gc.ca)
+ % 10/03/2004 Fixed a bug in julian_calculation subfunction (was
+ % incorrect for year 1582 only), Vincent Roy
+ % 18/03/2004 Correction to the header (help display) only. No changes to
+ % the code. (changed the �elevation� field in �location� structure
+ % information to �altitude�), Vincent Roy
+ % 13/04/2004 Following a suggestion from Jody Klymak (jklymak@ucsd.edu),
+ % allowed the 'time' input to be passed as a Matlab time string.
+ % 22/08/2005 Following a bug report from Bruce Bowler
+ % (bbowler@bigelow.org), modified the julian_calculation function. Bug
+ % was 'MATLAB has allowed structure assignment to a non-empty non-structure
+ % to overwrite the previous value. This behavior will continue in this release,
+ % but will be an error in a future version of MATLAB. For advice on how to
+ % write code that will both avoid this warning and work in future versions of
+ % MATLAB, see R14SP2 Release Notes'. Script should now be
+ % compliant with futher release of Matlab...
+ """
+
+ # 1. Calculate the Julian Day, and Century. Julian Ephemeris day, century
+ # and millenium are calculated using a mean delta_t of 33.184 seconds.
+ julian = julian_calculation(time)
+ # print(julian)
+
+ # 2. Calculate the Earth heliocentric longitude, latitude, and radius
+ # vector (L, B, and R)
+ earth_heliocentric_position = earth_heliocentric_position_calculation(julian)
+
+ # 3. Calculate the geocentric longitude and latitude
+ sun_geocentric_position = sun_geocentric_position_calculation(earth_heliocentric_position)
+
+ # 4. Calculate the nutation in longitude and obliquity (in degrees).
+ nutation = nutation_calculation(julian)
+
+ # 5. Calculate the true obliquity of the ecliptic (in degrees).
+ true_obliquity = true_obliquity_calculation(julian, nutation)
+
+ # 6. Calculate the aberration correction (in degrees)
+ aberration_correction = abberation_correction_calculation(earth_heliocentric_position)
+
+ # 7. Calculate the apparent sun longitude in degrees)
+ apparent_sun_longitude = apparent_sun_longitude_calculation(
+ sun_geocentric_position, nutation, aberration_correction
+ )
+
+ # 8. Calculate the apparent sideral time at Greenwich (in degrees)
+ apparent_stime_at_greenwich = apparent_stime_at_greenwich_calculation(julian, nutation, true_obliquity)
+
+ # 9. Calculate the sun rigth ascension (in degrees)
+ sun_rigth_ascension = sun_rigth_ascension_calculation(
+ apparent_sun_longitude, true_obliquity, sun_geocentric_position
+ )
+
+ # 10. Calculate the geocentric sun declination (in degrees). Positive or
+ # negative if the sun is north or south of the celestial equator.
+ sun_geocentric_declination = sun_geocentric_declination_calculation(
+ apparent_sun_longitude, true_obliquity, sun_geocentric_position
+ )
+
+ # 11. Calculate the observer local hour angle (in degrees, westward from south).
+ observer_local_hour = observer_local_hour_calculation(apparent_stime_at_greenwich, location, sun_rigth_ascension)
+
+ # 12. Calculate the topocentric sun position (rigth ascension, declination and
+ # rigth ascension parallax in degrees)
+ topocentric_sun_position = topocentric_sun_position_calculate(
+ earth_heliocentric_position, location, observer_local_hour, sun_rigth_ascension, sun_geocentric_declination
+ )
+
+ # 13. Calculate the topocentric local hour angle (in degrees)
+ topocentric_local_hour = topocentric_local_hour_calculate(observer_local_hour, topocentric_sun_position)
+
+ # 14. Calculate the topocentric zenith and azimuth angle (in degrees)
+ sun = sun_topocentric_zenith_angle_calculate(location, topocentric_sun_position, topocentric_local_hour)
+
+ return sun
+
+
+def julian_calculation(t_input):
+ """
+ % This function compute the julian day and julian century from the local
+ % time and timezone information. Ephemeris are calculated with a delta_t=0
+ % seconds.
+
+ % If time input is a Matlab time string, extract the information from
+ % this string and create the structure as defined in the main header of
+ % this script.
+ """
+ if not isinstance(t_input, dict):
+ # tt = datetime.datetime.strptime(t_input, "%Y-%m-%d %H:%M:%S.%f") # if t_input is a string of this format
+ # t_input should be a datetime object
+ time = dict()
+ time["UTC"] = 0
+ time["year"] = t_input.year
+ time["month"] = t_input.month
+ time["day"] = t_input.day
+ time["hour"] = t_input.hour
+ time["min"] = t_input.minute
+ time["sec"] = t_input.second
+ else:
+ time = t_input
+
+ if time["month"] == 1 or time["month"] == 2:
+ Y = time["year"] - 1
+ M = time["month"] + 12
+ else:
+ Y = time["year"]
+ M = time["month"]
+
+ ut_time = (
+ ((time["hour"] - time["UTC"]) / 24) + (time["min"] / (60 * 24)) + (time["sec"] / (60 * 60 * 24))
+ ) # time of day in UT time.
+ D = time["day"] + ut_time # Day of month in decimal time, ex. 2sd day of month at 12:30:30UT, D=2.521180556
+
+ # In 1582, the gregorian calendar was adopted
+ if time["year"] == 1582:
+ if time["month"] == 10:
+ if time["day"] <= 4: # The Julian calendar ended on October 4, 1582
+ B = 0
+ elif time["day"] >= 15: # The Gregorian calendar started on October 15, 1582
+ A = np.floor(Y / 100)
+ B = 2 - A + np.floor(A / 4)
+ else:
+ print("This date never existed!. Date automatically set to October 4, 1582")
+ time["month"] = 10
+ time["day"] = 4
+ B = 0
+ elif time["month"] < 10: # Julian calendar
+ B = 0
+ else: # Gregorian calendar
+ A = np.floor(Y / 100)
+ B = 2 - A + np.floor(A / 4)
+ elif time["year"] < 1582: # Julian calendar
+ B = 0
+ else:
+ A = np.floor(Y / 100) # Gregorian calendar
+ B = 2 - A + np.floor(A / 4)
+
+ julian = dict()
+ julian["day"] = D + B + np.floor(365.25 * (Y + 4716)) + np.floor(30.6001 * (M + 1)) - 1524.5
+
+ delta_t = 0 # 33.184;
+ julian["ephemeris_day"] = (julian["day"]) + (delta_t / 86400)
+ julian["century"] = (julian["day"] - 2451545) / 36525
+ julian["ephemeris_century"] = (julian["ephemeris_day"] - 2451545) / 36525
+ julian["ephemeris_millenium"] = (julian["ephemeris_century"]) / 10
+
+ return julian
+
+
+def earth_heliocentric_position_calculation(julian):
+ """
+ % This function compute the earth position relative to the sun, using
+ % tabulated values.
+
+ % Tabulated values for the longitude calculation
+ % L terms from the original code.
+ """
+ # Tabulated values for the longitude calculation
+ # L terms from the original code.
+ L0_terms = np.array(
+ [
+ [175347046.0, 0, 0],
+ [3341656.0, 4.6692568, 6283.07585],
+ [34894.0, 4.6261, 12566.1517],
+ [3497.0, 2.7441, 5753.3849],
+ [3418.0, 2.8289, 3.5231],
+ [3136.0, 3.6277, 77713.7715],
+ [2676.0, 4.4181, 7860.4194],
+ [2343.0, 6.1352, 3930.2097],
+ [1324.0, 0.7425, 11506.7698],
+ [1273.0, 2.0371, 529.691],
+ [1199.0, 1.1096, 1577.3435],
+ [990, 5.233, 5884.927],
+ [902, 2.045, 26.298],
+ [857, 3.508, 398.149],
+ [780, 1.179, 5223.694],
+ [753, 2.533, 5507.553],
+ [505, 4.583, 18849.228],
+ [492, 4.205, 775.523],
+ [357, 2.92, 0.067],
+ [317, 5.849, 11790.629],
+ [284, 1.899, 796.298],
+ [271, 0.315, 10977.079],
+ [243, 0.345, 5486.778],
+ [206, 4.806, 2544.314],
+ [205, 1.869, 5573.143],
+ [202, 2.4458, 6069.777],
+ [156, 0.833, 213.299],
+ [132, 3.411, 2942.463],
+ [126, 1.083, 20.775],
+ [115, 0.645, 0.98],
+ [103, 0.636, 4694.003],
+ [102, 0.976, 15720.839],
+ [102, 4.267, 7.114],
+ [99, 6.21, 2146.17],
+ [98, 0.68, 155.42],
+ [86, 5.98, 161000.69],
+ [85, 1.3, 6275.96],
+ [85, 3.67, 71430.7],
+ [80, 1.81, 17260.15],
+ [79, 3.04, 12036.46],
+ [71, 1.76, 5088.63],
+ [74, 3.5, 3154.69],
+ [74, 4.68, 801.82],
+ [70, 0.83, 9437.76],
+ [62, 3.98, 8827.39],
+ [61, 1.82, 7084.9],
+ [57, 2.78, 6286.6],
+ [56, 4.39, 14143.5],
+ [56, 3.47, 6279.55],
+ [52, 0.19, 12139.55],
+ [52, 1.33, 1748.02],
+ [51, 0.28, 5856.48],
+ [49, 0.49, 1194.45],
+ [41, 5.37, 8429.24],
+ [41, 2.4, 19651.05],
+ [39, 6.17, 10447.39],
+ [37, 6.04, 10213.29],
+ [37, 2.57, 1059.38],
+ [36, 1.71, 2352.87],
+ [36, 1.78, 6812.77],
+ [33, 0.59, 17789.85],
+ [30, 0.44, 83996.85],
+ [30, 2.74, 1349.87],
+ [25, 3.16, 4690.48],
+ ]
+ )
+
+ L1_terms = np.array(
+ [
+ [628331966747.0, 0, 0],
+ [206059.0, 2.678235, 6283.07585],
+ [4303.0, 2.6351, 12566.1517],
+ [425.0, 1.59, 3.523],
+ [119.0, 5.796, 26.298],
+ [109.0, 2.966, 1577.344],
+ [93, 2.59, 18849.23],
+ [72, 1.14, 529.69],
+ [68, 1.87, 398.15],
+ [67, 4.41, 5507.55],
+ [59, 2.89, 5223.69],
+ [56, 2.17, 155.42],
+ [45, 0.4, 796.3],
+ [36, 0.47, 775.52],
+ [29, 2.65, 7.11],
+ [21, 5.34, 0.98],
+ [19, 1.85, 5486.78],
+ [19, 4.97, 213.3],
+ [17, 2.99, 6275.96],
+ [16, 0.03, 2544.31],
+ [16, 1.43, 2146.17],
+ [15, 1.21, 10977.08],
+ [12, 2.83, 1748.02],
+ [12, 3.26, 5088.63],
+ [12, 5.27, 1194.45],
+ [12, 2.08, 4694],
+ [11, 0.77, 553.57],
+ [10, 1.3, 3286.6],
+ [10, 4.24, 1349.87],
+ [9, 2.7, 242.73],
+ [9, 5.64, 951.72],
+ [8, 5.3, 2352.87],
+ [6, 2.65, 9437.76],
+ [6, 4.67, 4690.48],
+ ]
+ )
+
+ L2_terms = np.array(
+ [
+ [52919.0, 0, 0],
+ [8720.0, 1.0721, 6283.0758],
+ [309.0, 0.867, 12566.152],
+ [27, 0.05, 3.52],
+ [16, 5.19, 26.3],
+ [16, 3.68, 155.42],
+ [10, 0.76, 18849.23],
+ [9, 2.06, 77713.77],
+ [7, 0.83, 775.52],
+ [5, 4.66, 1577.34],
+ [4, 1.03, 7.11],
+ [4, 3.44, 5573.14],
+ [3, 5.14, 796.3],
+ [3, 6.05, 5507.55],
+ [3, 1.19, 242.73],
+ [3, 6.12, 529.69],
+ [3, 0.31, 398.15],
+ [3, 2.28, 553.57],
+ [2, 4.38, 5223.69],
+ [2, 3.75, 0.98],
+ ]
+ )
+
+ L3_terms = np.array(
+ [
+ [289.0, 5.844, 6283.076],
+ [35, 0, 0],
+ [17, 5.49, 12566.15],
+ [3, 5.2, 155.42],
+ [1, 4.72, 3.52],
+ [1, 5.3, 18849.23],
+ [1, 5.97, 242.73],
+ ]
+ )
+ L4_terms = np.array([[114.0, 3.142, 0], [8, 4.13, 6283.08], [1, 3.84, 12566.15]])
+
+ L5_terms = np.array([1, 3.14, 0])
+ L5_terms = np.atleast_2d(L5_terms) # since L5_terms is 1D, we have to convert it to 2D to avoid indexErrors
+
+ A0 = L0_terms[:, 0]
+ B0 = L0_terms[:, 1]
+ C0 = L0_terms[:, 2]
+
+ A1 = L1_terms[:, 0]
+ B1 = L1_terms[:, 1]
+ C1 = L1_terms[:, 2]
+
+ A2 = L2_terms[:, 0]
+ B2 = L2_terms[:, 1]
+ C2 = L2_terms[:, 2]
+
+ A3 = L3_terms[:, 0]
+ B3 = L3_terms[:, 1]
+ C3 = L3_terms[:, 2]
+
+ A4 = L4_terms[:, 0]
+ B4 = L4_terms[:, 1]
+ C4 = L4_terms[:, 2]
+
+ A5 = L5_terms[:, 0]
+ B5 = L5_terms[:, 1]
+ C5 = L5_terms[:, 2]
+
+ JME = julian["ephemeris_millenium"]
+
+ # Compute the Earth Heliochentric longitude from the tabulated values.
+ L0 = np.sum(A0 * np.cos(B0 + (C0 * JME)))
+ L1 = np.sum(A1 * np.cos(B1 + (C1 * JME)))
+ L2 = np.sum(A2 * np.cos(B2 + (C2 * JME)))
+ L3 = np.sum(A3 * np.cos(B3 + (C3 * JME)))
+ L4 = np.sum(A4 * np.cos(B4 + (C4 * JME)))
+ L5 = A5 * np.cos(B5 + (C5 * JME))
+
+ earth_heliocentric_position = dict()
+ earth_heliocentric_position["longitude"] = (
+ L0
+ + (L1 * JME)
+ + (L2 * np.power(JME, 2))
+ + (L3 * np.power(JME, 3))
+ + (L4 * np.power(JME, 4))
+ + (L5 * np.power(JME, 5))
+ ) / 1e8
+ # Convert the longitude to degrees.
+ earth_heliocentric_position["longitude"] = earth_heliocentric_position["longitude"] * 180 / np.pi
+
+ # Limit the range to [0,360]
+ earth_heliocentric_position["longitude"] = set_to_range(earth_heliocentric_position["longitude"], 0, 360)
+
+ # Tabulated values for the earth heliocentric latitude.
+ # B terms from the original code.
+ B0_terms = np.array(
+ [[280.0, 3.199, 84334.662], [102.0, 5.422, 5507.553], [80, 3.88, 5223.69], [44, 3.7, 2352.87], [32, 4, 1577.34]]
+ )
+
+ B1_terms = np.array([[9, 3.9, 5507.55], [6, 1.73, 5223.69]])
+
+ A0 = B0_terms[:, 0]
+ B0 = B0_terms[:, 1]
+ C0 = B0_terms[:, 2]
+
+ A1 = B1_terms[:, 0]
+ B1 = B1_terms[:, 1]
+ C1 = B1_terms[:, 2]
+
+ L0 = np.sum(A0 * np.cos(B0 + (C0 * JME)))
+ L1 = np.sum(A1 * np.cos(B1 + (C1 * JME)))
+
+ earth_heliocentric_position["latitude"] = (L0 + (L1 * JME)) / 1e8
+
+ # Convert the latitude to degrees.
+ earth_heliocentric_position["latitude"] = earth_heliocentric_position["latitude"] * 180 / np.pi
+
+ # Limit the range to [0,360];
+ earth_heliocentric_position["latitude"] = set_to_range(earth_heliocentric_position["latitude"], 0, 360)
+
+ # Tabulated values for radius vector.
+ # R terms from the original code
+ R0_terms = np.array(
+ [
+ [100013989.0, 0, 0],
+ [1670700.0, 3.0984635, 6283.07585],
+ [13956.0, 3.05525, 12566.1517],
+ [3084.0, 5.1985, 77713.7715],
+ [1628.0, 1.1739, 5753.3849],
+ [1576.0, 2.8469, 7860.4194],
+ [925.0, 5.453, 11506.77],
+ [542.0, 4.564, 3930.21],
+ [472.0, 3.661, 5884.927],
+ [346.0, 0.964, 5507.553],
+ [329.0, 5.9, 5223.694],
+ [307.0, 0.299, 5573.143],
+ [243.0, 4.273, 11790.629],
+ [212.0, 5.847, 1577.344],
+ [186.0, 5.022, 10977.079],
+ [175.0, 3.012, 18849.228],
+ [110.0, 5.055, 5486.778],
+ [98, 0.89, 6069.78],
+ [86, 5.69, 15720.84],
+ [86, 1.27, 161000.69],
+ [85, 0.27, 17260.15],
+ [63, 0.92, 529.69],
+ [57, 2.01, 83996.85],
+ [56, 5.24, 71430.7],
+ [49, 3.25, 2544.31],
+ [47, 2.58, 775.52],
+ [45, 5.54, 9437.76],
+ [43, 6.01, 6275.96],
+ [39, 5.36, 4694],
+ [38, 2.39, 8827.39],
+ [37, 0.83, 19651.05],
+ [37, 4.9, 12139.55],
+ [36, 1.67, 12036.46],
+ [35, 1.84, 2942.46],
+ [33, 0.24, 7084.9],
+ [32, 0.18, 5088.63],
+ [32, 1.78, 398.15],
+ [28, 1.21, 6286.6],
+ [28, 1.9, 6279.55],
+ [26, 4.59, 10447.39],
+ ]
+ )
+
+ R1_terms = np.array(
+ [
+ [103019.0, 1.10749, 6283.07585],
+ [1721.0, 1.0644, 12566.1517],
+ [702.0, 3.142, 0],
+ [32, 1.02, 18849.23],
+ [31, 2.84, 5507.55],
+ [25, 1.32, 5223.69],
+ [18, 1.42, 1577.34],
+ [10, 5.91, 10977.08],
+ [9, 1.42, 6275.96],
+ [9, 0.27, 5486.78],
+ ]
+ )
+
+ R2_terms = np.array(
+ [
+ [4359.0, 5.7846, 6283.0758],
+ [124.0, 5.579, 12566.152],
+ [12, 3.14, 0],
+ [9, 3.63, 77713.77],
+ [6, 1.87, 5573.14],
+ [3, 5.47, 18849],
+ ]
+ )
+
+ R3_terms = np.array([[145.0, 4.273, 6283.076], [7, 3.92, 12566.15]])
+
+ R4_terms = [4, 2.56, 6283.08]
+ R4_terms = np.atleast_2d(R4_terms) # since L5_terms is 1D, we have to convert it to 2D to avoid indexErrors
+
+ A0 = R0_terms[:, 0]
+ B0 = R0_terms[:, 1]
+ C0 = R0_terms[:, 2]
+
+ A1 = R1_terms[:, 0]
+ B1 = R1_terms[:, 1]
+ C1 = R1_terms[:, 2]
+
+ A2 = R2_terms[:, 0]
+ B2 = R2_terms[:, 1]
+ C2 = R2_terms[:, 2]
+
+ A3 = R3_terms[:, 0]
+ B3 = R3_terms[:, 1]
+ C3 = R3_terms[:, 2]
+
+ A4 = R4_terms[:, 0]
+ B4 = R4_terms[:, 1]
+ C4 = R4_terms[:, 2]
+
+ # Compute the Earth heliocentric radius vector
+ L0 = np.sum(A0 * np.cos(B0 + (C0 * JME)))
+ L1 = np.sum(A1 * np.cos(B1 + (C1 * JME)))
+ L2 = np.sum(A2 * np.cos(B2 + (C2 * JME)))
+ L3 = np.sum(A3 * np.cos(B3 + (C3 * JME)))
+ L4 = A4 * np.cos(B4 + (C4 * JME))
+
+ # Units are in AU
+ earth_heliocentric_position["radius"] = (
+ L0 + (L1 * JME) + (L2 * np.power(JME, 2)) + (L3 * np.power(JME, 3)) + (L4 * np.power(JME, 4))
+ ) / 1e8
+
+ return earth_heliocentric_position
+
+
+def sun_geocentric_position_calculation(earth_heliocentric_position):
+ """
+ % This function compute the sun position relative to the earth.
+ """
+ sun_geocentric_position = dict()
+ sun_geocentric_position["longitude"] = earth_heliocentric_position["longitude"] + 180
+ # Limit the range to [0,360];
+ sun_geocentric_position["longitude"] = set_to_range(sun_geocentric_position["longitude"], 0, 360)
+
+ sun_geocentric_position["latitude"] = -earth_heliocentric_position["latitude"]
+ # Limit the range to [0,360]
+ sun_geocentric_position["latitude"] = set_to_range(sun_geocentric_position["latitude"], 0, 360)
+ return sun_geocentric_position
+
+
+def nutation_calculation(julian):
+ """
+ % This function compute the nutation in longtitude and in obliquity, in
+ % degrees.
+ :param julian:
+ :return: nutation
+ """
+
+ # All Xi are in degrees.
+ JCE = julian["ephemeris_century"]
+
+ # 1. Mean elongation of the moon from the sun
+ p = np.atleast_2d([(1 / 189474), -0.0019142, 445267.11148, 297.85036])
+
+ # X0 = polyval(p, JCE);
+ X0 = (
+ p[0, 0] * np.power(JCE, 3) + p[0, 1] * np.power(JCE, 2) + p[0, 2] * JCE + p[0, 3]
+ ) # This is faster than polyval...
+
+ # 2. Mean anomaly of the sun (earth)
+ p = np.atleast_2d([-(1 / 300000), -0.0001603, 35999.05034, 357.52772])
+
+ # X1 = polyval(p, JCE)
+ X1 = p[0, 0] * np.power(JCE, 3) + p[0, 1] * np.power(JCE, 2) + p[0, 2] * JCE + p[0, 3]
+
+ # 3. Mean anomaly of the moon
+ p = np.atleast_2d([(1 / 56250), 0.0086972, 477198.867398, 134.96298])
+
+ # X2 = polyval(p, JCE);
+ X2 = p[0, 0] * np.power(JCE, 3) + p[0, 1] * np.power(JCE, 2) + p[0, 2] * JCE + p[0, 3]
+
+ # 4. Moon argument of latitude
+ p = np.atleast_2d([(1 / 327270), -0.0036825, 483202.017538, 93.27191])
+
+ # X3 = polyval(p, JCE)
+ X3 = p[0, 0] * np.power(JCE, 3) + p[0, 1] * np.power(JCE, 2) + p[0, 2] * JCE + p[0, 3]
+
+ # 5. Longitude of the ascending node of the moon's mean orbit on the
+ # ecliptic, measured from the mean equinox of the date
+ p = np.atleast_2d([(1 / 450000), 0.0020708, -1934.136261, 125.04452])
+
+ # X4 = polyval(p, JCE);
+ X4 = p[0, 0] * np.power(JCE, 3) + p[0, 1] * np.power(JCE, 2) + p[0, 2] * JCE + p[0, 3]
+
+ # Y tabulated terms from the original code
+ Y_terms = np.array(
+ [
+ [0, 0, 0, 0, 1],
+ [-2, 0, 0, 2, 2],
+ [0, 0, 0, 2, 2],
+ [0, 0, 0, 0, 2],
+ [0, 1, 0, 0, 0],
+ [0, 0, 1, 0, 0],
+ [-2, 1, 0, 2, 2],
+ [0, 0, 0, 2, 1],
+ [0, 0, 1, 2, 2],
+ [-2, -1, 0, 2, 2],
+ [-2, 0, 1, 0, 0],
+ [-2, 0, 0, 2, 1],
+ [0, 0, -1, 2, 2],
+ [2, 0, 0, 0, 0],
+ [0, 0, 1, 0, 1],
+ [2, 0, -1, 2, 2],
+ [0, 0, -1, 0, 1],
+ [0, 0, 1, 2, 1],
+ [-2, 0, 2, 0, 0],
+ [0, 0, -2, 2, 1],
+ [2, 0, 0, 2, 2],
+ [0, 0, 2, 2, 2],
+ [0, 0, 2, 0, 0],
+ [-2, 0, 1, 2, 2],
+ [0, 0, 0, 2, 0],
+ [-2, 0, 0, 2, 0],
+ [0, 0, -1, 2, 1],
+ [0, 2, 0, 0, 0],
+ [2, 0, -1, 0, 1],
+ [-2, 2, 0, 2, 2],
+ [0, 1, 0, 0, 1],
+ [-2, 0, 1, 0, 1],
+ [0, -1, 0, 0, 1],
+ [0, 0, 2, -2, 0],
+ [2, 0, -1, 2, 1],
+ [2, 0, 1, 2, 2],
+ [0, 1, 0, 2, 2],
+ [-2, 1, 1, 0, 0],
+ [0, -1, 0, 2, 2],
+ [2, 0, 0, 2, 1],
+ [2, 0, 1, 0, 0],
+ [-2, 0, 2, 2, 2],
+ [-2, 0, 1, 2, 1],
+ [2, 0, -2, 0, 1],
+ [2, 0, 0, 0, 1],
+ [0, -1, 1, 0, 0],
+ [-2, -1, 0, 2, 1],
+ [-2, 0, 0, 0, 1],
+ [0, 0, 2, 2, 1],
+ [-2, 0, 2, 0, 1],
+ [-2, 1, 0, 2, 1],
+ [0, 0, 1, -2, 0],
+ [-1, 0, 1, 0, 0],
+ [-2, 1, 0, 0, 0],
+ [1, 0, 0, 0, 0],
+ [0, 0, 1, 2, 0],
+ [0, 0, -2, 2, 2],
+ [-1, -1, 1, 0, 0],
+ [0, 1, 1, 0, 0],
+ [0, -1, 1, 2, 2],
+ [2, -1, -1, 2, 2],
+ [0, 0, 3, 2, 2],
+ [2, -1, 0, 2, 2],
+ ]
+ )
+
+ nutation_terms = np.array(
+ [
+ [-171996, -174.2, 92025, 8.9],
+ [-13187, -1.6, 5736, -3.1],
+ [-2274, -0.2, 977, -0.5],
+ [2062, 0.2, -895, 0.5],
+ [1426, -3.4, 54, -0.1],
+ [712, 0.1, -7, 0],
+ [-517, 1.2, 224, -0.6],
+ [-386, -0.4, 200, 0],
+ [-301, 0, 129, -0.1],
+ [217, -0.5, -95, 0.3],
+ [-158, 0, 0, 0],
+ [129, 0.1, -70, 0],
+ [123, 0, -53, 0],
+ [63, 0, 0, 0],
+ [63, 0.1, -33, 0],
+ [-59, 0, 26, 0],
+ [-58, -0.1, 32, 0],
+ [-51, 0, 27, 0],
+ [48, 0, 0, 0],
+ [46, 0, -24, 0],
+ [-38, 0, 16, 0],
+ [-31, 0, 13, 0],
+ [29, 0, 0, 0],
+ [29, 0, -12, 0],
+ [26, 0, 0, 0],
+ [-22, 0, 0, 0],
+ [21, 0, -10, 0],
+ [17, -0.1, 0, 0],
+ [16, 0, -8, 0],
+ [-16, 0.1, 7, 0],
+ [-15, 0, 9, 0],
+ [-13, 0, 7, 0],
+ [-12, 0, 6, 0],
+ [11, 0, 0, 0],
+ [-10, 0, 5, 0],
+ [-8, 0, 3, 0],
+ [7, 0, -3, 0],
+ [-7, 0, 0, 0],
+ [-7, 0, 3, 0],
+ [-7, 0, 3, 0],
+ [6, 0, 0, 0],
+ [6, 0, -3, 0],
+ [6, 0, -3, 0],
+ [-6, 0, 3, 0],
+ [-6, 0, 3, 0],
+ [5, 0, 0, 0],
+ [-5, 0, 3, 0],
+ [-5, 0, 3, 0],
+ [-5, 0, 3, 0],
+ [4, 0, 0, 0],
+ [4, 0, 0, 0],
+ [4, 0, 0, 0],
+ [-4, 0, 0, 0],
+ [-4, 0, 0, 0],
+ [-4, 0, 0, 0],
+ [3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ [-3, 0, 0, 0],
+ ]
+ )
+
+ # Using the tabulated values, compute the delta_longitude and
+ # delta_obliquity.
+ Xi = np.array([X0, X1, X2, X3, X4]) # a col mat in octave
+
+ tabulated_argument = Y_terms.dot(np.transpose(Xi)) * (np.pi / 180)
+
+ delta_longitude = (nutation_terms[:, 0] + (nutation_terms[:, 1] * JCE)) * np.sin(tabulated_argument)
+ delta_obliquity = (nutation_terms[:, 2] + (nutation_terms[:, 3] * JCE)) * np.cos(tabulated_argument)
+
+ nutation = dict() # init nutation dictionary
+ # Nutation in longitude
+ nutation["longitude"] = np.sum(delta_longitude) / 36000000
+
+ # Nutation in obliquity
+ nutation["obliquity"] = np.sum(delta_obliquity) / 36000000
+
+ return nutation
+
+
+def true_obliquity_calculation(julian, nutation):
+ """
+ This function compute the true obliquity of the ecliptic.
+
+ :param julian:
+ :param nutation:
+ :return:
+ """
+
+ p = np.atleast_2d([2.45, 5.79, 27.87, 7.12, -39.05, -249.67, -51.38, 1999.25, -1.55, -4680.93, 84381.448])
+
+ # mean_obliquity = polyval(p, julian.ephemeris_millenium/10);
+ U = julian["ephemeris_millenium"] / 10
+ mean_obliquity = (
+ p[0, 0] * np.power(U, 10)
+ + p[0, 1] * np.power(U, 9)
+ + p[0, 2] * np.power(U, 8)
+ + p[0, 3] * np.power(U, 7)
+ + p[0, 4] * np.power(U, 6)
+ + p[0, 5] * np.power(U, 5)
+ + p[0, 6] * np.power(U, 4)
+ + p[0, 7] * np.power(U, 3)
+ + p[0, 8] * np.power(U, 2)
+ + p[0, 9] * U
+ + p[0, 10]
+ )
+
+ true_obliquity = (mean_obliquity / 3600) + nutation["obliquity"]
+
+ return true_obliquity
+
+
+def abberation_correction_calculation(earth_heliocentric_position):
+ """
+ This function compute the aberration_correction, as a function of the
+ earth-sun distance.
+
+ :param earth_heliocentric_position:
+ :return:
+ """
+ aberration_correction = -20.4898 / (3600 * earth_heliocentric_position["radius"])
+ return aberration_correction
+
+
+def apparent_sun_longitude_calculation(sun_geocentric_position, nutation, aberration_correction):
+ """
+ This function compute the sun apparent longitude
+
+ :param sun_geocentric_position:
+ :param nutation:
+ :param aberration_correction:
+ :return:
+ """
+ apparent_sun_longitude = sun_geocentric_position["longitude"] + nutation["longitude"] + aberration_correction
+ return apparent_sun_longitude
+
+
+def apparent_stime_at_greenwich_calculation(julian, nutation, true_obliquity):
+ """
+ This function compute the apparent sideral time at Greenwich.
+
+ :param julian:
+ :param nutation:
+ :param true_obliquity:
+ :return:
+ """
+
+ JD = julian["day"]
+ JC = julian["century"]
+
+ # Mean sideral time, in degrees
+ mean_stime = (
+ 280.46061837
+ + (360.98564736629 * (JD - 2451545))
+ + (0.000387933 * np.power(JC, 2))
+ - (np.power(JC, 3) / 38710000)
+ )
+
+ # Limit the range to [0-360];
+ mean_stime = set_to_range(mean_stime, 0, 360)
+
+ apparent_stime_at_greenwich = mean_stime + (nutation["longitude"] * np.cos(true_obliquity * np.pi / 180))
+ return apparent_stime_at_greenwich
+
+
+def sun_rigth_ascension_calculation(apparent_sun_longitude, true_obliquity, sun_geocentric_position):
+ """
+ This function compute the sun rigth ascension.
+ :param apparent_sun_longitude:
+ :param true_obliquity:
+ :param sun_geocentric_position:
+ :return:
+ """
+
+ argument_numerator = (np.sin(apparent_sun_longitude * np.pi / 180) * np.cos(true_obliquity * np.pi / 180)) - (
+ np.tan(sun_geocentric_position["latitude"] * np.pi / 180) * np.sin(true_obliquity * np.pi / 180)
+ )
+ argument_denominator = np.cos(apparent_sun_longitude * np.pi / 180)
+ sun_rigth_ascension = np.arctan2(argument_numerator, argument_denominator) * 180 / np.pi
+ # Limit the range to [0,360];
+ sun_rigth_ascension = set_to_range(sun_rigth_ascension, 0, 360)
+ return sun_rigth_ascension
+
+
+def sun_geocentric_declination_calculation(apparent_sun_longitude, true_obliquity, sun_geocentric_position):
+ """
+
+ :param apparent_sun_longitude:
+ :param true_obliquity:
+ :param sun_geocentric_position:
+ :return:
+ """
+
+ argument = (np.sin(sun_geocentric_position["latitude"] * np.pi / 180) * np.cos(true_obliquity * np.pi / 180)) + (
+ np.cos(sun_geocentric_position["latitude"] * np.pi / 180)
+ * np.sin(true_obliquity * np.pi / 180)
+ * np.sin(apparent_sun_longitude * np.pi / 180)
+ )
+
+ sun_geocentric_declination = np.arcsin(argument) * 180 / np.pi
+ return sun_geocentric_declination
+
+
+def observer_local_hour_calculation(apparent_stime_at_greenwich, location, sun_rigth_ascension):
+ """
+ This function computes observer local hour.
+
+ :param apparent_stime_at_greenwich:
+ :param location:
+ :param sun_rigth_ascension:
+ :return:
+ """
+
+ observer_local_hour = apparent_stime_at_greenwich + location["longitude"] - sun_rigth_ascension
+ # Set the range to [0-360]
+ observer_local_hour = set_to_range(observer_local_hour, 0, 360)
+ return observer_local_hour
+
+
+def topocentric_sun_position_calculate(
+ earth_heliocentric_position, location, observer_local_hour, sun_rigth_ascension, sun_geocentric_declination
+):
+ """
+ This function compute the sun position (rigth ascension and declination)
+ with respect to the observer local position at the Earth surface.
+
+ :param earth_heliocentric_position:
+ :param location:
+ :param observer_local_hour:
+ :param sun_rigth_ascension:
+ :param sun_geocentric_declination:
+ :return:
+ """
+
+ # Equatorial horizontal parallax of the sun in degrees
+ eq_horizontal_parallax = 8.794 / (3600 * earth_heliocentric_position["radius"])
+
+ # Term u, used in the following calculations (in radians)
+ u = np.arctan(0.99664719 * np.tan(location["latitude"] * np.pi / 180))
+
+ # Term x, used in the following calculations
+ x = np.cos(u) + ((location["altitude"] / 6378140) * np.cos(location["latitude"] * np.pi / 180))
+
+ # Term y, used in the following calculations
+ y = (0.99664719 * np.sin(u)) + ((location["altitude"] / 6378140) * np.sin(location["latitude"] * np.pi / 180))
+
+ # Parallax in the sun rigth ascension (in radians)
+ nominator = -x * np.sin(eq_horizontal_parallax * np.pi / 180) * np.sin(observer_local_hour * np.pi / 180)
+ denominator = np.cos(sun_geocentric_declination * np.pi / 180) - (
+ x * np.sin(eq_horizontal_parallax * np.pi / 180) * np.cos(observer_local_hour * np.pi / 180)
+ )
+ sun_rigth_ascension_parallax = np.arctan2(nominator, denominator)
+ # Conversion to degrees.
+ topocentric_sun_position = dict()
+ topocentric_sun_position["rigth_ascension_parallax"] = sun_rigth_ascension_parallax * 180 / np.pi
+
+ # Topocentric sun rigth ascension (in degrees)
+ topocentric_sun_position["rigth_ascension"] = sun_rigth_ascension + (sun_rigth_ascension_parallax * 180 / np.pi)
+
+ # Topocentric sun declination (in degrees)
+ nominator = (
+ np.sin(sun_geocentric_declination * np.pi / 180) - (y * np.sin(eq_horizontal_parallax * np.pi / 180))
+ ) * np.cos(sun_rigth_ascension_parallax)
+ denominator = np.cos(sun_geocentric_declination * np.pi / 180) - (
+ y * np.sin(eq_horizontal_parallax * np.pi / 180)
+ ) * np.cos(observer_local_hour * np.pi / 180)
+ topocentric_sun_position["declination"] = np.arctan2(nominator, denominator) * 180 / np.pi
+ return topocentric_sun_position
+
+
+def topocentric_local_hour_calculate(observer_local_hour, topocentric_sun_position):
+ """
+ This function compute the topocentric local jour angle in degrees
+
+ :param observer_local_hour:
+ :param topocentric_sun_position:
+ :return:
+ """
+
+ topocentric_local_hour = observer_local_hour - topocentric_sun_position["rigth_ascension_parallax"]
+ return topocentric_local_hour
+
+
+def sun_topocentric_zenith_angle_calculate(location, topocentric_sun_position, topocentric_local_hour):
+ """
+ This function compute the sun zenith angle, taking into account the
+ atmospheric refraction. A default temperature of 283K and a
+ default pressure of 1010 mbar are used.
+
+ :param location:
+ :param topocentric_sun_position:
+ :param topocentric_local_hour:
+ :return:
+ """
+
+ # Topocentric elevation, without atmospheric refraction
+ argument = (
+ np.sin(location["latitude"] * np.pi / 180) * np.sin(topocentric_sun_position["declination"] * np.pi / 180)
+ ) + (
+ np.cos(location["latitude"] * np.pi / 180)
+ * np.cos(topocentric_sun_position["declination"] * np.pi / 180)
+ * np.cos(topocentric_local_hour * np.pi / 180)
+ )
+ true_elevation = np.arcsin(argument) * 180 / np.pi
+
+ # Atmospheric refraction correction (in degrees)
+ argument = true_elevation + (10.3 / (true_elevation + 5.11))
+ refraction_corr = 1.02 / (60 * np.tan(argument * np.pi / 180))
+
+ # For exact pressure and temperature correction, use this,
+ # with P the pressure in mbar amd T the temperature in Kelvins:
+ # refraction_corr = (P/1010) * (283/T) * 1.02 / (60 * tan(argument * pi/180));
+
+ # Apparent elevation
+ apparent_elevation = true_elevation + refraction_corr
+
+ sun = dict()
+ sun["zenith"] = 90 - apparent_elevation
+
+ # Topocentric azimuth angle. The +180 conversion is to pass from astronomer
+ # notation (westward from south) to navigation notation (eastward from
+ # north);
+ nominator = np.sin(topocentric_local_hour * np.pi / 180)
+ denominator = (np.cos(topocentric_local_hour * np.pi / 180) * np.sin(location["latitude"] * np.pi / 180)) - (
+ np.tan(topocentric_sun_position["declination"] * np.pi / 180) * np.cos(location["latitude"] * np.pi / 180)
+ )
+ sun["azimuth"] = (np.arctan2(nominator, denominator) * 180 / np.pi) + 180
+
+ # Set the range to [0-360]
+ sun["azimuth"] = set_to_range(sun["azimuth"], 0, 360)
+ return sun
+
+
+def set_to_range(var, min_interval, max_interval):
+ """
+ Sets a variable in range min_interval and max_interval
+
+ :param var:
+ :param min_interval:
+ :param max_interval:
+ :return:
+ """
+ var = var - max_interval * np.floor(var / max_interval)
+
+ if var < min_interval:
+ var = var + max_interval
+ return var
diff --git a/pysrc/solweig/physics/sunlit_shaded_patches.py b/pysrc/solweig/physics/sunlit_shaded_patches.py
new file mode 100644
index 0000000..1fbb76f
--- /dev/null
+++ b/pysrc/solweig/physics/sunlit_shaded_patches.py
@@ -0,0 +1,38 @@
+import numpy as np
+
+""" This function calculates whether a point is sunlit or shaded
+ based on a sky view factor (in a cylinder), solar altitude, solar azimuth """
+
+
+def shaded_or_sunlit(solar_altitude, solar_azimuth, patch_altitude, patch_azimuth, asvf):
+ # Patch azimuth in relation to sun azimuth
+ patch_to_sun_azi = np.abs(solar_azimuth - patch_azimuth)
+
+ # Degrees to radians
+ deg2rad = np.pi / 180
+
+ # Radians to degrees
+ rad2deg = 180 / np.pi
+
+ #
+ xi = np.cos(patch_to_sun_azi * deg2rad)
+
+ #
+ yi = 2 * xi * np.tan(solar_altitude * deg2rad)
+
+ hsvf = np.tan(asvf)
+
+ yi_ = 0 if yi > 0 else yi
+
+ #
+ tan_delta = hsvf + yi_
+
+ # Degrees where below is in shade and above is sunlit
+ sunlit_degrees = np.arctan(tan_delta) * rad2deg
+
+ # Boolean for pixels where patch is sunlit
+ sunlit_patches = sunlit_degrees < patch_altitude
+ # Boolean for pixels where patch is shaded
+ shaded_patches = sunlit_degrees > patch_altitude
+
+ return sunlit_patches, shaded_patches
diff --git a/pysrc/solweig/physics/wallalgorithms.py b/pysrc/solweig/physics/wallalgorithms.py
new file mode 100644
index 0000000..6275619
--- /dev/null
+++ b/pysrc/solweig/physics/wallalgorithms.py
@@ -0,0 +1,214 @@
+__author__ = "xlinfr"
+
+import math
+
+import numpy as np
+
+from ..progress import get_progress_iterator
+from .morphology import rotate_array
+
+
+def findwalls(a, walllimit):
+ # This function identifies walls based on a DSM and a wall-height limit
+ # Walls are represented by outer pixels within building footprints
+ #
+ # Fredrik Lindberg, Goteborg Urban Climate Group
+ # fredrikl@gvc.gu.se
+ # 20150625
+ #
+ # For each pixel, find the max of its 4 cardinal neighbors (cross kernel).
+ # Wall height = max_neighbor - self, clipped to walllimit.
+
+ walls = np.zeros_like(a, dtype=np.float32)
+
+ # Max of 4 cardinal neighbors for all interior pixels
+ max_neighbors = np.maximum.reduce(
+ [
+ a[:-2, 1:-1], # north
+ a[2:, 1:-1], # south
+ a[1:-1, :-2], # west
+ a[1:-1, 2:], # east
+ ]
+ )
+ walls[1:-1, 1:-1] = max_neighbors
+
+ walls = walls - a
+ walls[walls < walllimit] = 0
+
+ # Zero borders
+ walls[0, :] = 0
+ walls[-1, :] = 0
+ walls[:, 0] = 0
+ walls[:, -1] = 0
+
+ return walls
+
+
+def filter1Goodwin_as_aspect_v3(walls, scale, a, feedback=None):
+ """
+ tThis function applies the filter processing presented in Goodwin et al (2010) but instead for removing
+ linear fetures it calculates wall aspect based on a wall pixels grid, a dsm (a) and a scale factor
+
+ Fredrik Lindberg, 2012-02-14
+ fredrikl@gvc.gu.se
+
+ Translated: 2015-09-15
+
+ :param walls:
+ :param scale:
+ :param a:
+ :return: dirwalls
+ """
+ # Try Rust implementation first (much faster)
+ try:
+ import threading
+
+ from ..progress import ProgressReporter
+ from ..rustalgos import wall_aspect as _wa_rust
+
+ walls_f32 = np.asarray(walls, dtype=np.float32)
+ dsm_f32 = np.asarray(a, dtype=np.float32)
+
+ runner = _wa_rust.WallAspectRunner()
+ result = [None]
+ error = [None]
+
+ def _run():
+ try:
+ result[0] = runner.compute(walls_f32, float(scale), dsm_f32)
+ except Exception as e:
+ error[0] = e
+
+ thread = threading.Thread(target=_run, daemon=True)
+ thread.start()
+
+ # Poll progress (180 angle iterations)
+ total = 180
+ pbar = ProgressReporter(total=total, desc="Computing wall aspects", feedback=feedback)
+ last = 0
+ while thread.is_alive():
+ thread.join(timeout=0.05)
+ done = runner.progress()
+ if done > last:
+ pbar.update(done - last)
+ last = done
+ # Check QGIS cancellation
+ if feedback is not None and hasattr(feedback, "isCanceled") and feedback.isCanceled():
+ runner.cancel()
+ thread.join(timeout=5.0)
+ pbar.close()
+ return np.zeros_like(walls_f32)
+ if last < total:
+ pbar.update(total - last)
+ pbar.close()
+
+ thread.join()
+ if error[0] is not None:
+ raise error[0]
+ return np.asarray(result[0])
+ except ImportError:
+ pass
+
+ # Python fallback
+ row = a.shape[0]
+ col = a.shape[1]
+
+ filtersize = np.floor((scale + 0.0000000001) * 9)
+ if filtersize <= 2:
+ filtersize = 3
+ elif filtersize != 9 and filtersize % 2 == 0:
+ filtersize = filtersize + 1
+
+ filthalveceil = int(np.ceil(filtersize / 2.0))
+ filthalvefloor = int(np.floor(filtersize / 2.0))
+
+ filtmatrix = np.zeros((int(filtersize), int(filtersize)), dtype=np.float32)
+ buildfilt = np.zeros((int(filtersize), int(filtersize)), dtype=np.float32)
+
+ filtmatrix[:, filthalveceil - 1] = 1
+ n = filtmatrix.shape[0] - 1
+ buildfilt[filthalveceil - 1, 0:filthalvefloor] = 1
+ buildfilt[filthalveceil - 1, filthalveceil : int(filtersize)] = 2
+
+ y = np.zeros((row, col), dtype=np.float32) # final direction
+ z = np.zeros((row, col), dtype=np.float32) # temporary direction
+ x = np.zeros((row, col), dtype=np.float32) # building side
+ walls[walls > 0.5] = 1
+
+ for h in get_progress_iterator(
+ range(0, 180), desc="Computing wall aspects", feedback=feedback
+ ): # =0:1:180 #%increased resolution to 1 deg 20140911
+ filtmatrix1temp = rotate_array(filtmatrix, h, order=1, reshape=False, mode="nearest") # bilinear
+ filtmatrix1 = np.round(filtmatrix1temp)
+ filtmatrixbuildtemp = rotate_array(buildfilt, h, order=0, reshape=False, mode="nearest") # Nearest neighbor
+ # filtmatrixbuild = np.round(filtmatrixbuildtemp / 127.)
+ filtmatrixbuild = np.round(filtmatrixbuildtemp)
+ index = 270 - h
+ if h == 150:
+ filtmatrixbuild[:, n] = 0
+ if h == 30:
+ filtmatrixbuild[:, n] = 0
+ if index == 225:
+ # n = filtmatrix.shape[0] - 1 # length(filtmatrix);
+ filtmatrix1[0, 0] = 1
+ filtmatrix1[n, n] = 1
+ if index == 135:
+ # n = filtmatrix.shape[0] - 1 # length(filtmatrix);
+ filtmatrix1[0, n] = 1
+ filtmatrix1[n, 0] = 1
+
+ for i in range(int(filthalveceil) - 1, row - int(filthalveceil) - 1): # i=filthalveceil:sizey-filthalveceil
+ for j in range(
+ int(filthalveceil) - 1, col - int(filthalveceil) - 1
+ ): # (j=filthalveceil:sizex-filthalveceil
+ if walls[i, j] == 1:
+ wallscut = (
+ walls[
+ i - filthalvefloor : i + filthalvefloor + 1,
+ j - filthalvefloor : j + filthalvefloor + 1,
+ ]
+ * filtmatrix1
+ )
+ dsmcut = a[
+ i - filthalvefloor : i + filthalvefloor + 1,
+ j - filthalvefloor : j + filthalvefloor + 1,
+ ]
+ if z[i, j] < wallscut.sum(): # sum(sum(wallscut))
+ z[i, j] = wallscut.sum() # sum(sum(wallscut));
+ if np.sum(dsmcut[filtmatrixbuild == 1]) > np.sum(dsmcut[filtmatrixbuild == 2]):
+ x[i, j] = 1
+ else:
+ x[i, j] = 2
+
+ y[i, j] = index
+
+ y[(x == 1)] = y[(x == 1)] - 180
+ y[(y < 0)] = y[(y < 0)] + 360
+
+ grad, asp = get_ders(a, scale)
+
+ y = y + ((walls == 1) * 1) * ((y == 0) * 1) * (asp / (math.pi / 180.0))
+
+ dirwalls = y
+
+ return dirwalls
+
+
+def cart2pol(x, y, units="deg"):
+ radius = np.sqrt(x**2 + y**2)
+ theta = np.arctan2(y, x)
+ if units in ["deg", "degs"]:
+ theta = theta * 180 / np.pi
+ return theta, radius
+
+
+def get_ders(dsm, scale):
+ # dem,_,_=read_dem_grid(dem_file)
+ dx = 1 / scale
+ # dx=0.5
+ fy, fx = np.gradient(dsm, dx, dx)
+ asp, grad = cart2pol(fy, fx, "rad")
+ grad = np.arctan(grad)
+ asp = asp * -1
+ asp = asp + (asp < 0) * (np.pi * 2)
+ return grad, asp
diff --git a/pysrc/solweig/postprocess.py b/pysrc/solweig/postprocess.py
new file mode 100644
index 0000000..30f0332
--- /dev/null
+++ b/pysrc/solweig/postprocess.py
@@ -0,0 +1,356 @@
+"""Post-processing: UTCI and PET thermal comfort indices."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from datetime import datetime as dt
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .models import HumanParams
+from .progress import ProgressReporter
+from .rustalgos import pet as pet_rust
+from .rustalgos import utci as utci_rust
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+ from .models import Location, Weather
+
+
+# =============================================================================
+# Post-Processing: Thermal Comfort Indices
+# =============================================================================
+
+
+def compute_utci_grid(
+ tmrt: NDArray[np.floating],
+ ta: float,
+ rh: float,
+ wind: float,
+) -> NDArray[np.floating]:
+ """
+ Compute UTCI (Universal Thermal Climate Index) for a single grid.
+
+ This is a thin wrapper around the Rust UTCI implementation for in-memory processing.
+ For batch processing of saved Tmrt files, use compute_utci() instead.
+
+ Args:
+ tmrt: Mean Radiant Temperature grid (°C).
+ ta: Air temperature (°C).
+ rh: Relative humidity (%).
+ wind: Wind speed at 10m height (m/s).
+
+ Returns:
+ UTCI grid (°C).
+
+ Example:
+ # Compute UTCI for a single result
+ utci = compute_utci_grid(
+ tmrt=result.tmrt,
+ ta=25.0,
+ rh=60.0,
+ wind=2.0,
+ )
+ """
+
+ wind_grid = np.full_like(tmrt, wind, dtype=np.float32)
+ return utci_rust.utci_grid(ta, rh, tmrt, wind_grid)
+
+
+def compute_pet_grid(
+ tmrt: NDArray[np.floating],
+ ta: float,
+ rh: float,
+ wind: float,
+ human: HumanParams | None = None,
+) -> NDArray[np.floating]:
+ """
+ Compute PET (Physiological Equivalent Temperature) for a single grid.
+
+ This is a thin wrapper around the Rust PET implementation for in-memory processing.
+ For batch processing of saved Tmrt files, use compute_pet() instead.
+
+ Args:
+ tmrt: Mean Radiant Temperature grid (°C).
+ ta: Air temperature (°C).
+ rh: Relative humidity (%).
+ wind: Wind speed at 10m height (m/s).
+ human: Human body parameters. Uses defaults if not provided.
+
+ Returns:
+ PET grid (°C).
+
+ Example:
+ # Compute PET for a single result
+ pet = compute_pet_grid(
+ tmrt=result.tmrt,
+ ta=25.0,
+ rh=60.0,
+ wind=2.0,
+ human=HumanParams(weight=75, height=1.75),
+ )
+ """
+
+ if human is None:
+ human = HumanParams()
+
+ wind_grid = np.full_like(tmrt, wind, dtype=np.float32)
+ return pet_rust.pet_grid(
+ ta,
+ rh,
+ tmrt,
+ wind_grid,
+ human.weight,
+ float(human.age),
+ human.height,
+ human.activity,
+ human.clothing,
+ human.sex,
+ )
+
+
+def compute_utci(
+ tmrt_dir: str | Path,
+ weather_series: list[Weather],
+ output_dir: str | Path,
+ location: Location | None = None,
+ progress_callback: Callable[[int, int], None] | None = None,
+) -> int:
+ """
+ Batch compute UTCI from saved Tmrt GeoTIFF files.
+
+ Auto-discovers tmrt_*.tif files in tmrt_dir, matches them with weather_series
+ by datetime, and saves utci_*.tif files to output_dir.
+
+ Args:
+ tmrt_dir: Directory containing tmrt_YYYYMMDD_HHMM.tif files.
+ weather_series: List of Weather objects with datetime, ta, rh, ws.
+ output_dir: Directory to save utci_YYYYMMDD_HHMM.tif files.
+ location: Geographic location for weather.compute_derived().
+ If None, assumes weather is already computed.
+ progress_callback: Optional callback(current_step, total_steps) called after
+ each timestep. If None, a tqdm progress bar is shown automatically.
+
+ Returns:
+ Number of UTCI files processed.
+
+ Example:
+ # After running calculate_timeseries with output_dir
+ n_processed = solweig.compute_utci(
+ tmrt_dir="output/",
+ weather_series=weather_list,
+ output_dir="output_utci/",
+ )
+ print(f"Processed {n_processed} timesteps")
+ """
+ import re
+
+ from . import io
+
+ tmrt_dir = Path(tmrt_dir)
+ output_dir = Path(output_dir)
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ # Find tmrt_*.tif files (check tmrt/ subdirectory first, then flat layout)
+ tmrt_files = sorted(tmrt_dir.glob("tmrt_*.tif"))
+ if not tmrt_files and (tmrt_dir / "tmrt").exists():
+ tmrt_files = sorted((tmrt_dir / "tmrt").glob("tmrt_*.tif"))
+ if not tmrt_files:
+ logger.warning(f"No tmrt_*.tif files found in {tmrt_dir}")
+ return 0
+
+ # Parse timestamps from filenames
+ pattern = re.compile(r"tmrt_(\d{8})_(\d{4})\.tif")
+ tmrt_map = {}
+ for f in tmrt_files:
+ match = pattern.match(f.name)
+ if match:
+ date_str, time_str = match.groups()
+ timestamp = dt.strptime(f"{date_str}_{time_str}", "%Y%m%d_%H%M")
+ tmrt_map[timestamp] = f
+
+ # Match weather with timestamps
+ if location is not None:
+ for w in weather_series:
+ if not w._derived_computed:
+ w.compute_derived(location)
+
+ # Set up progress reporting
+ n_steps = len(weather_series)
+ _progress = None if progress_callback is not None else ProgressReporter(total=n_steps, desc="Computing UTCI")
+
+ # Start timing
+ start_time = time.time()
+ processed = 0
+ for i, weather in enumerate(weather_series):
+ if weather.datetime not in tmrt_map:
+ logger.warning(f"No Tmrt file found for {weather.datetime}")
+ if progress_callback is not None:
+ progress_callback(i + 1, n_steps)
+ elif _progress is not None:
+ _progress.update(1)
+ continue
+
+ # Load Tmrt
+ tmrt_path = tmrt_map[weather.datetime]
+ tmrt, transform, crs, _ = io.load_raster(str(tmrt_path))
+
+ # Compute UTCI
+ utci = compute_utci_grid(tmrt, weather.ta, weather.rh, weather.ws)
+
+ # Save UTCI
+ date_str = weather.datetime.strftime("%Y%m%d")
+ time_str = weather.datetime.strftime("%H%M")
+ utci_path = output_dir / f"utci_{date_str}_{time_str}.tif"
+
+ io.save_raster(
+ str(utci_path),
+ utci,
+ transform if isinstance(transform, list) else list(transform.to_gdal()),
+ crs,
+ )
+ processed += 1
+
+ # Report progress
+ if progress_callback is not None:
+ progress_callback(i + 1, n_steps)
+ elif _progress is not None:
+ _progress.update(1)
+
+ if _progress is not None:
+ _progress.close()
+
+ total_time = time.time() - start_time
+ rate = processed / total_time if total_time > 0 else 0
+ logger.info(f"UTCI complete: {processed} files saved to {output_dir} ({total_time:.1f}s, {rate:.2f} steps/s)")
+ return processed
+
+
+def compute_pet(
+ tmrt_dir: str | Path,
+ weather_series: list[Weather],
+ output_dir: str | Path,
+ human: HumanParams | None = None,
+ location: Location | None = None,
+ progress_callback: Callable[[int, int], None] | None = None,
+) -> int:
+ """
+ Batch compute PET from saved Tmrt GeoTIFF files.
+
+ Auto-discovers tmrt_*.tif files in tmrt_dir, matches them with weather_series
+ by datetime, and saves pet_*.tif files to output_dir.
+
+ Args:
+ tmrt_dir: Directory containing tmrt_YYYYMMDD_HHMM.tif files.
+ weather_series: List of Weather objects with datetime, ta, rh, ws.
+ output_dir: Directory to save pet_YYYYMMDD_HHMM.tif files.
+ human: Human body parameters. Uses defaults if not provided.
+ location: Geographic location for weather.compute_derived().
+ If None, assumes weather is already computed.
+ progress_callback: Optional callback(current_step, total_steps) called after
+ each timestep. If None, a tqdm progress bar is shown automatically.
+
+ Returns:
+ Number of PET files processed.
+
+ Example:
+ # After running calculate_timeseries with output_dir
+ n_processed = solweig.compute_pet(
+ tmrt_dir="output/",
+ weather_series=weather_list,
+ output_dir="output_pet/",
+ human=HumanParams(weight=75, height=1.75),
+ )
+ print(f"Processed {n_processed} timesteps")
+ """
+ import re
+
+ from . import io
+
+ if human is None:
+ human = HumanParams()
+
+ tmrt_dir = Path(tmrt_dir)
+ output_dir = Path(output_dir)
+ output_dir.mkdir(parents=True, exist_ok=True)
+
+ # Find tmrt_*.tif files (check tmrt/ subdirectory first, then flat layout)
+ tmrt_files = sorted(tmrt_dir.glob("tmrt_*.tif"))
+ if not tmrt_files and (tmrt_dir / "tmrt").exists():
+ tmrt_files = sorted((tmrt_dir / "tmrt").glob("tmrt_*.tif"))
+ if not tmrt_files:
+ logger.warning(f"No tmrt_*.tif files found in {tmrt_dir}")
+ return 0
+
+ # Parse timestamps from filenames
+ pattern = re.compile(r"tmrt_(\d{8})_(\d{4})\.tif")
+ tmrt_map = {}
+ for f in tmrt_files:
+ match = pattern.match(f.name)
+ if match:
+ date_str, time_str = match.groups()
+ timestamp = dt.strptime(f"{date_str}_{time_str}", "%Y%m%d_%H%M")
+ tmrt_map[timestamp] = f
+
+ # Match weather with timestamps
+ if location is not None:
+ for w in weather_series:
+ if not w._derived_computed:
+ w.compute_derived(location)
+
+ # Set up progress reporting
+ n_steps = len(weather_series)
+ _progress = None if progress_callback is not None else ProgressReporter(total=n_steps, desc="Computing PET")
+
+ # Start timing
+ start_time = time.time()
+ processed = 0
+ for i, weather in enumerate(weather_series):
+ if weather.datetime not in tmrt_map:
+ logger.warning(f"No Tmrt file found for {weather.datetime}")
+ if progress_callback is not None:
+ progress_callback(i + 1, n_steps)
+ elif _progress is not None:
+ _progress.update(1)
+ continue
+
+ # Load Tmrt
+ tmrt_path = tmrt_map[weather.datetime]
+ tmrt, transform, crs, _ = io.load_raster(str(tmrt_path))
+
+ # Compute PET
+ pet = compute_pet_grid(tmrt, weather.ta, weather.rh, weather.ws, human)
+
+ # Save PET
+ date_str = weather.datetime.strftime("%Y%m%d")
+ time_str = weather.datetime.strftime("%H%M")
+ pet_path = output_dir / f"pet_{date_str}_{time_str}.tif"
+
+ io.save_raster(
+ str(pet_path),
+ pet,
+ transform if isinstance(transform, list) else list(transform.to_gdal()),
+ crs,
+ )
+ processed += 1
+
+ # Report progress
+ if progress_callback is not None:
+ progress_callback(i + 1, n_steps)
+ elif _progress is not None:
+ _progress.update(1)
+
+ if _progress is not None:
+ _progress.close()
+
+ total_time = time.time() - start_time
+ rate = processed / total_time if total_time > 0 else 0
+ logger.info(f"PET complete: {processed} files saved to {output_dir} ({total_time:.1f}s, {rate:.2f} steps/s)")
+ return processed
diff --git a/pysrc/solweig/progress.py b/pysrc/solweig/progress.py
new file mode 100644
index 0000000..c723738
--- /dev/null
+++ b/pysrc/solweig/progress.py
@@ -0,0 +1,255 @@
+"""
+Progress reporting abstraction for SOLWEIG.
+
+Automatically uses the appropriate progress mechanism:
+- QGIS: QgsProcessingFeedback (native progress bar)
+- Python: tqdm (terminal progress bar)
+- Fallback: no-op (silent iteration)
+
+Usage:
+ from solweig.progress import get_progress_iterator, ProgressReporter
+
+ # Simple iteration with progress
+ for item in get_progress_iterator(items, desc="Processing"):
+ process(item)
+
+ # Manual progress control
+ progress = ProgressReporter(total=100, desc="Computing")
+ for i in range(100):
+ do_work(i)
+ progress.update(1)
+ progress.close()
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from collections.abc import Iterable, Iterator
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# Detect environment once at module load
+_QGIS_AVAILABLE = False
+_TQDM_AVAILABLE = False
+_qgis_feedback_class = None
+
+# Check for QGIS
+try:
+ if "qgis" in sys.modules or "qgis.core" in sys.modules:
+ from qgis.core import QgsProcessingFeedback
+
+ _QGIS_AVAILABLE = True
+ _qgis_feedback_class = QgsProcessingFeedback
+ logger.debug("QGIS environment detected, will use QgsProcessingFeedback")
+except ImportError:
+ pass
+
+# Check for tqdm
+_tqdm: type | None = None
+try:
+ from tqdm import tqdm as _tqdm
+
+ _TQDM_AVAILABLE = True
+except ImportError:
+ pass
+
+
+class ProgressReporter:
+ """
+ Unified progress reporter that works in QGIS, terminal, or silently.
+
+ Args:
+ total: Total number of steps (required for percentage calculation).
+ desc: Description shown in progress bar.
+ feedback: Optional QGIS QgsProcessingFeedback object. If provided,
+ uses QGIS progress. Otherwise auto-detects environment.
+ disable: If True, disable all progress output.
+ """
+
+ def __init__(
+ self,
+ total: int,
+ desc: str = "",
+ feedback: Any = None,
+ disable: bool = False,
+ progress_range: tuple[float, float] | None = None,
+ ):
+ self.total = total
+ self.desc = desc
+ self.current = 0
+ self.disable = disable
+ self._closed = False
+
+ # Optional QGIS percentage sub-range mapping.
+ # When set, maps internal 0..total to progress_range[0]..progress_range[1]
+ # instead of the default 0..100. Useful when SVF is one phase of a
+ # larger QGIS algorithm (e.g. surface preprocessing maps SVF to 35-74%).
+ self._progress_range = progress_range
+
+ # Determine which backend to use
+ self._qgis_feedback = None
+ self._tqdm_bar = None
+
+ if disable:
+ return
+
+ # If explicit QGIS feedback provided, use it
+ if feedback is not None:
+ self._qgis_feedback = feedback
+ return
+
+ # Auto-detect: prefer QGIS if available in environment
+ if _QGIS_AVAILABLE and "qgis.core" in sys.modules:
+ # In QGIS but no feedback provided - log only, no progress bar
+ logger.debug(f"QGIS detected but no feedback provided for: {desc}")
+ return
+
+ # Use tqdm if available
+ if _tqdm is not None:
+ self._tqdm_bar = _tqdm(total=total, desc=desc)
+ return
+
+ # Fallback: silent operation
+ logger.debug(f"No progress backend available for: {desc}")
+
+ def update(self, n: int = 1) -> None:
+ """Update progress by n steps."""
+ if self._closed:
+ return
+
+ self.current += n
+
+ if self.disable:
+ return
+
+ if self._qgis_feedback is not None:
+ # QGIS expects percentage 0-100
+ frac = min(1.0, self.current / self.total) if self.total > 0 else 0.0
+ if self._progress_range is not None:
+ lo, hi = self._progress_range
+ percent = int(lo + frac * (hi - lo))
+ else:
+ percent = int(100 * frac)
+ self._qgis_feedback.setProgress(percent)
+ elif self._tqdm_bar is not None:
+ self._tqdm_bar.update(n)
+
+ def set_description(self, desc: str) -> None:
+ """Update the progress bar description (tqdm only, no QGIS log output)."""
+ self.desc = desc
+ if self._tqdm_bar is not None:
+ self._tqdm_bar.set_description(desc)
+
+ def set_text(self, text: str) -> None:
+ """Update status text above the progress bar (QGIS only).
+
+ In QGIS, calls ``feedback.setProgressText()`` to update the label
+ shown above the progress bar. In tqdm/fallback mode this is a no-op
+ (use :meth:`set_description` for tqdm bar text instead).
+ """
+ if self._qgis_feedback is not None:
+ self._qgis_feedback.setProgressText(text)
+
+ def is_cancelled(self) -> bool:
+ """Check if user requested cancellation (QGIS only)."""
+ if self._qgis_feedback is not None:
+ return self._qgis_feedback.isCanceled()
+ return False
+
+ def close(self) -> None:
+ """Close the progress bar."""
+ if self._closed:
+ return
+ self._closed = True
+
+ if self._tqdm_bar is not None:
+ self._tqdm_bar.close()
+
+
+class _ProgressIterator(Iterator[T]):
+ """Iterator wrapper that reports progress."""
+
+ def __init__(self, iterable: Iterable[T], reporter: ProgressReporter):
+ self._iterator = iter(iterable)
+ self._reporter = reporter
+
+ def __iter__(self) -> _ProgressIterator[T]:
+ return self
+
+ def __next__(self) -> T:
+ try:
+ item = next(self._iterator)
+ self._reporter.update(1)
+ return item
+ except StopIteration:
+ self._reporter.close()
+ raise
+
+
+def get_progress_iterator(
+ iterable: Iterable[T],
+ desc: str = "",
+ total: int | None = None,
+ feedback: Any = None,
+ disable: bool = False,
+) -> Iterator[T]:
+ """
+ Wrap an iterable with automatic progress reporting.
+
+ Automatically uses the appropriate progress mechanism:
+ - QGIS environment with feedback: QgsProcessingFeedback
+ - Terminal: tqdm progress bar
+ - Fallback: silent iteration
+
+ Args:
+ iterable: The iterable to wrap.
+ desc: Description for the progress bar.
+ total: Total number of items (computed from len() if not provided).
+ feedback: Optional QGIS QgsProcessingFeedback for progress reporting.
+ disable: If True, disable progress output entirely.
+
+ Returns:
+ Iterator that reports progress as items are consumed.
+
+ Example:
+ # Simple usage
+ for item in get_progress_iterator(items, desc="Processing"):
+ process(item)
+
+ # With QGIS feedback (in processing algorithm)
+ for item in get_progress_iterator(items, feedback=self.feedback):
+ process(item)
+ """
+ if total is None:
+ try:
+ total = len(iterable) # type: ignore
+ except TypeError:
+ # Iterable doesn't have len(), estimate or use 0
+ total = 0
+
+ reporter = ProgressReporter(total=total, desc=desc, feedback=feedback, disable=disable)
+ return _ProgressIterator(iterable, reporter)
+
+
+# Convenience function that matches tqdm signature for easy migration
+def progress(
+ iterable: Iterable[T],
+ desc: str = "",
+ total: int | None = None,
+ **kwargs,
+) -> Iterator[T]:
+ """
+ Drop-in replacement for tqdm that auto-detects environment.
+
+ This function has a similar signature to tqdm for easy migration.
+ Additional kwargs are ignored for compatibility.
+
+ Example:
+ # Replace: for item in tqdm(items, desc="Processing"):
+ # With: for item in progress(items, desc="Processing"):
+ """
+ return get_progress_iterator(iterable, desc=desc, total=total)
diff --git a/pysrc/solweig/solweig_logging.py b/pysrc/solweig/solweig_logging.py
new file mode 100644
index 0000000..4474595
--- /dev/null
+++ b/pysrc/solweig/solweig_logging.py
@@ -0,0 +1,189 @@
+"""
+QGIS-compatible logging for SOLWEIG.
+
+Provides automatic environment detection and uses appropriate logging backend:
+- QGIS: QgsProcessingFeedback.pushInfo() / pushDebugInfo()
+- Python: Standard logging module
+- Fallback: Print to stdout
+
+Usage:
+ from solweig.solweig_logging import get_logger
+
+ logger = get_logger(__name__)
+ logger.info("Surface data loaded: 400×400 pixels")
+ logger.debug(f"Using {len(weather_list)} timesteps")
+ logger.warning("SVF not provided, will compute on-the-fly (slow)")
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from enum import IntEnum
+from typing import Any
+
+
+class LogLevel(IntEnum):
+ """Log levels matching Python logging."""
+
+ DEBUG = 10
+ INFO = 20
+ WARNING = 30
+ ERROR = 40
+
+
+class SolweigLogger:
+ """
+ Unified logger that works in both QGIS and Python environments.
+
+ Auto-detects environment and uses appropriate backend:
+ - QGIS: Uses QgsProcessingFeedback if available
+ - Python: Uses standard logging module
+ - Fallback: Prints to stdout
+ """
+
+ def __init__(self, name: str, level: LogLevel = LogLevel.INFO):
+ """
+ Initialize logger.
+
+ Args:
+ name: Logger name (usually module name)
+ level: Minimum log level to display
+ """
+ self.name = name
+ self.level = level
+ self._feedback = None
+ self._backend = self._detect_backend()
+
+ def _detect_backend(self) -> str:
+ """Detect which logging backend to use."""
+ # Check if running in QGIS
+ try:
+ from qgis.core import QgsProcessingFeedback # noqa: F401
+
+ # QGIS is available, but we need a feedback object to be set
+ # This will be set via set_feedback() when running as QGIS processing algorithm
+ return "qgis"
+ except ImportError:
+ pass
+
+ # Use standard Python logging
+ return "logging"
+
+ def set_feedback(self, feedback: Any) -> None:
+ """
+ Set QGIS feedback object for logging.
+
+ Args:
+ feedback: QgsProcessingFeedback object
+ """
+ self._feedback = feedback
+
+ def _log(self, level: LogLevel, message: str) -> None:
+ """Internal logging method."""
+ if level < self.level:
+ return # Below minimum level
+
+ if self._backend == "qgis" and self._feedback is not None:
+ # Use QGIS feedback
+ if level >= LogLevel.ERROR:
+ self._feedback.reportError(message)
+ elif level >= LogLevel.WARNING:
+ self._feedback.pushInfo(f"WARNING: {message}")
+ elif level >= LogLevel.INFO:
+ self._feedback.pushInfo(message)
+ else: # DEBUG
+ self._feedback.pushDebugInfo(message)
+ elif self._backend == "logging":
+ # Use Python logging
+ logger = logging.getLogger(self.name)
+ logger.log(level, message)
+ else:
+ # Fallback: print to stdout
+ prefix = {
+ LogLevel.DEBUG: "DEBUG",
+ LogLevel.INFO: "INFO",
+ LogLevel.WARNING: "WARNING",
+ LogLevel.ERROR: "ERROR",
+ }.get(level, "INFO")
+ print(f"[{prefix}] {self.name}: {message}", file=sys.stderr if level >= LogLevel.WARNING else sys.stdout)
+
+ def debug(self, message: str) -> None:
+ """Log debug message."""
+ self._log(LogLevel.DEBUG, message)
+
+ def info(self, message: str) -> None:
+ """Log info message."""
+ self._log(LogLevel.INFO, message)
+
+ def warning(self, message: str) -> None:
+ """Log warning message."""
+ self._log(LogLevel.WARNING, message)
+
+ def error(self, message: str) -> None:
+ """Log error message."""
+ self._log(LogLevel.ERROR, message)
+
+ def set_level(self, level: LogLevel | int) -> None:
+ """Set minimum log level."""
+ self.level = LogLevel(level) if isinstance(level, int) else level
+
+
+# Global logger registry
+_loggers: dict[str, SolweigLogger] = {}
+
+
+def get_logger(name: str, level: LogLevel | int = LogLevel.INFO) -> SolweigLogger:
+ """
+ Get or create a logger for the given name.
+
+ Args:
+ name: Logger name (usually module name or __name__)
+ level: Minimum log level (default: INFO)
+
+ Returns:
+ SolweigLogger instance
+
+ Example:
+ >>> logger = get_logger(__name__)
+ >>> logger.info("Processing started")
+ >>> logger.debug(f"Grid size: {rows}×{cols}")
+ """
+ if name not in _loggers:
+ _loggers[name] = SolweigLogger(name, LogLevel(level) if isinstance(level, int) else level)
+ return _loggers[name]
+
+
+def set_global_level(level: LogLevel | int) -> None:
+ """
+ Set log level for all existing loggers.
+
+ Args:
+ level: Minimum log level (DEBUG, INFO, WARNING, ERROR)
+
+ Example:
+ >>> import solweig.solweig_logging as slog
+ >>> slog.set_global_level(slog.LogLevel.DEBUG) # Show debug messages
+ """
+ level = LogLevel(level) if isinstance(level, int) else level
+ for logger in _loggers.values():
+ logger.set_level(level)
+
+
+def set_global_feedback(feedback: Any) -> None:
+ """
+ Set QGIS feedback object for all loggers.
+
+ Args:
+ feedback: QgsProcessingFeedback object
+ """
+ for logger in _loggers.values():
+ logger.set_feedback(feedback)
+
+
+# Configure Python logging to be less verbose by default
+logging.basicConfig(
+ level=logging.INFO,
+ format="%(name)s: %(message)s",
+ stream=sys.stdout,
+)
diff --git a/pysrc/solweig/tiling.py b/pysrc/solweig/tiling.py
new file mode 100644
index 0000000..881f550
--- /dev/null
+++ b/pysrc/solweig/tiling.py
@@ -0,0 +1,861 @@
+"""
+Tiled processing for large rasters.
+
+This module provides automatic and manual tiling for SOLWEIG calculations,
+supporting both single-timestep and timeseries modes. Large rasters are
+automatically divided into overlapping tiles with buffers sized to capture
+shadows from the tallest buildings at low sun angles.
+
+Timeseries mode preserves thermal state accumulation across tiles and timesteps,
+ensuring physically accurate ground temperature modeling with thermal inertia.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from .models import HumanParams, PrecomputedData, SolweigResult, SurfaceData, ThermalState, TileSpec
+from .solweig_logging import get_logger
+
+logger = get_logger(__name__)
+
+if TYPE_CHECKING:
+ from .models import (
+ Location,
+ ModelConfig,
+ Weather,
+ )
+
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+MIN_TILE_SIZE = 256 # Minimum tile size in pixels
+MAX_TILE_SIZE = 2500 # Maximum tile size in pixels
+MIN_SUN_ELEVATION_DEG = 3.0 # Minimum sun elevation for shadow calculations
+MAX_BUFFER_M = 500.0 # Default maximum buffer / shadow distance in meters
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _should_use_tiling(rows: int, cols: int) -> bool:
+ """Check if raster size requires automatic tiling."""
+ return rows > MAX_TILE_SIZE or cols > MAX_TILE_SIZE
+
+
+def _calculate_auto_tile_size(rows: int, cols: int) -> int:
+ """
+ Calculate optimal tile size based on raster dimensions.
+
+ Heuristic:
+ - >16M pixels (4000x4000): use 1024x1024 tiles
+ - >4M pixels (2000x2000): use 2048x2048 tiles
+ - Otherwise: no tiling needed (full raster)
+
+ Returns:
+ Tile size in pixels.
+ """
+ total_pixels = rows * cols
+ if total_pixels > 4000 * 4000:
+ return 1024
+ elif total_pixels > 2000 * 2000:
+ return min(rows, cols, 2048)
+ else:
+ return max(rows, cols)
+
+
+def _extract_tile_surface(
+ surface: SurfaceData,
+ tile: TileSpec,
+ pixel_size: float,
+) -> SurfaceData:
+ """
+ Extract tile slice from full surface, reusing precomputed SVF when available.
+
+ Creates a new SurfaceData with sliced arrays (DSM, CDSM, etc.).
+ If the global surface has precomputed SVF (via prepare() or compute_svf()),
+ the SVF is sliced to the tile bounds — avoiding expensive per-tile
+ recomputation. When no global SVF exists, compute_svf() computes it fresh.
+
+ Args:
+ surface: Full raster surface data.
+ tile: Tile specification with slice bounds.
+ pixel_size: Pixel size in meters.
+
+ Returns:
+ SurfaceData for this tile with SVF available.
+ """
+ read_slice = tile.read_slice
+
+ tile_dsm = surface.dsm[read_slice].copy()
+ tile_cdsm = surface.cdsm[read_slice].copy() if surface.cdsm is not None else None
+ tile_tdsm = surface.tdsm[read_slice].copy() if surface.tdsm is not None else None
+ tile_dem = surface.dem[read_slice].copy() if surface.dem is not None else None
+ tile_lc = surface.land_cover[read_slice].copy() if surface.land_cover is not None else None
+ tile_albedo = surface.albedo[read_slice].copy() if surface.albedo is not None else None
+ tile_emis = surface.emissivity[read_slice].copy() if surface.emissivity is not None else None
+
+ # Slice precomputed SVF if available (avoids per-tile recomputation)
+ tile_svf = None
+ if surface.svf is not None:
+ tile_svf = surface.svf.crop(
+ tile.row_start_full,
+ tile.row_end_full,
+ tile.col_start_full,
+ tile.col_end_full,
+ )
+
+ tile_surface = SurfaceData(
+ dsm=tile_dsm,
+ cdsm=tile_cdsm,
+ tdsm=tile_tdsm,
+ dem=tile_dem,
+ land_cover=tile_lc,
+ albedo=tile_albedo,
+ emissivity=tile_emis,
+ pixel_size=pixel_size,
+ svf=tile_svf,
+ )
+ tile_surface.compute_svf() # No-op when tile_svf is set
+
+ return tile_surface
+
+
+def _slice_tile_precomputed(
+ precomputed: PrecomputedData | None,
+ tile: TileSpec,
+) -> PrecomputedData | None:
+ """
+ Slice walls from precomputed data for a tile.
+
+ SVF is handled via surface.svf (sliced in _extract_tile_surface).
+ Shadow matrices are not supported in tiled mode.
+
+ Args:
+ precomputed: Full raster precomputed data (or None).
+ tile: Tile specification with slice bounds.
+
+ Returns:
+ PrecomputedData with sliced walls, or None.
+ """
+ if precomputed is None:
+ return None
+
+ read_slice = tile.read_slice
+
+ tile_wall_ht = None
+ tile_wall_asp = None
+
+ if precomputed.wall_height is not None:
+ tile_wall_ht = precomputed.wall_height[read_slice].copy()
+ if precomputed.wall_aspect is not None:
+ tile_wall_asp = precomputed.wall_aspect[read_slice].copy()
+
+ if tile_wall_ht is None and tile_wall_asp is None:
+ return None
+
+ return PrecomputedData(
+ wall_height=tile_wall_ht,
+ wall_aspect=tile_wall_asp,
+ svf=None,
+ shadow_matrices=None,
+ )
+
+
+def _write_tile_result(
+ tile_result: SolweigResult,
+ tile: TileSpec,
+ tmrt_out: np.ndarray,
+ shadow_out: np.ndarray,
+ kdown_out: np.ndarray,
+ kup_out: np.ndarray,
+ ldown_out: np.ndarray,
+ lup_out: np.ndarray,
+) -> None:
+ """Write core region of tile result to global output arrays."""
+ core_slice = tile.core_slice
+ write_slice = tile.write_slice
+
+ tmrt_out[write_slice] = tile_result.tmrt[core_slice]
+ if tile_result.shadow is not None:
+ shadow_out[write_slice] = tile_result.shadow[core_slice]
+ if tile_result.kdown is not None:
+ kdown_out[write_slice] = tile_result.kdown[core_slice]
+ if tile_result.kup is not None:
+ kup_out[write_slice] = tile_result.kup[core_slice]
+ if tile_result.ldown is not None:
+ ldown_out[write_slice] = tile_result.ldown[core_slice]
+ if tile_result.lup is not None:
+ lup_out[write_slice] = tile_result.lup[core_slice]
+
+
+def _slice_tile_state(state: ThermalState, tile: TileSpec) -> ThermalState:
+ """
+ Slice thermal state arrays for a tile.
+
+ Spatial arrays are sliced using tile.read_slice (full tile with overlap).
+ Scalar values are copied as-is (they're global, not spatial).
+
+ Args:
+ state: Global thermal state for full raster.
+ tile: Tile specification with slice bounds.
+
+ Returns:
+ ThermalState for this tile.
+ """
+ read_slice = tile.read_slice
+
+ return ThermalState(
+ tgmap1=state.tgmap1[read_slice].copy(),
+ tgmap1_e=state.tgmap1_e[read_slice].copy(),
+ tgmap1_s=state.tgmap1_s[read_slice].copy(),
+ tgmap1_w=state.tgmap1_w[read_slice].copy(),
+ tgmap1_n=state.tgmap1_n[read_slice].copy(),
+ tgout1=state.tgout1[read_slice].copy(),
+ firstdaytime=state.firstdaytime,
+ timeadd=state.timeadd,
+ timestep_dec=state.timestep_dec,
+ )
+
+
+def _merge_tile_state(
+ tile_state: ThermalState,
+ tile: TileSpec,
+ global_state: ThermalState,
+) -> None:
+ """
+ Merge tile state arrays back into global state (in-place).
+
+ Writes core region (tile.core_slice) of tile state arrays to the
+ corresponding region (tile.write_slice) in global state. Updates
+ global scalar values from tile state (identical across all tiles
+ for a given timestep).
+
+ Args:
+ tile_state: Computed state for this tile.
+ tile: Tile specification with slice bounds.
+ global_state: Global state to update (modified in-place).
+ """
+ core_slice = tile.core_slice
+ write_slice = tile.write_slice
+
+ global_state.tgmap1[write_slice] = tile_state.tgmap1[core_slice]
+ global_state.tgmap1_e[write_slice] = tile_state.tgmap1_e[core_slice]
+ global_state.tgmap1_s[write_slice] = tile_state.tgmap1_s[core_slice]
+ global_state.tgmap1_w[write_slice] = tile_state.tgmap1_w[core_slice]
+ global_state.tgmap1_n[write_slice] = tile_state.tgmap1_n[core_slice]
+ global_state.tgout1[write_slice] = tile_state.tgout1[core_slice]
+
+ # Scalars are the same across all tiles for a given timestep
+ global_state.firstdaytime = tile_state.firstdaytime
+ global_state.timeadd = tile_state.timeadd
+
+
+# =============================================================================
+# Public Functions
+# =============================================================================
+
+
+def calculate_buffer_distance(
+ max_height: float,
+ min_sun_elev_deg: float = MIN_SUN_ELEVATION_DEG,
+ max_shadow_distance_m: float = MAX_BUFFER_M,
+) -> float:
+ """
+ Calculate required buffer distance for tiled processing based on max building height.
+
+ The buffer must be large enough to capture shadows cast by the tallest buildings
+ at the lowest sun elevation angle.
+
+ Formula: buffer = min(max_height / tan(min_sun_elevation), max_shadow_distance_m)
+
+ Args:
+ max_height: Maximum building/DSM height in meters.
+ min_sun_elev_deg: Minimum sun elevation angle in degrees. Default 3.0.
+ max_shadow_distance_m: Maximum buffer distance in meters. Default 500.0.
+
+ Returns:
+ Buffer distance in meters, capped at max_shadow_distance_m.
+
+ Example:
+ >>> calculate_buffer_distance(30.0) # 30m building
+ 500.0 # Capped (actual would be 573m)
+ >>> calculate_buffer_distance(10.0) # 10m building
+ 190.8 # 10m / tan(3)
+ """
+ if max_height <= 0:
+ return 0.0
+
+ tan_elev = np.tan(np.radians(min_sun_elev_deg))
+ if tan_elev <= 0:
+ return max_shadow_distance_m
+
+ buffer = max_height / tan_elev
+ return min(buffer, max_shadow_distance_m)
+
+
+def validate_tile_size(
+ tile_size: int,
+ buffer_pixels: int,
+ pixel_size: float,
+) -> tuple[int, str | None]:
+ """
+ Validate and adjust tile size for tiled processing.
+
+ Ensures the tile size is within bounds and leaves meaningful core area
+ after accounting for buffer overlap.
+
+ Args:
+ tile_size: Requested tile size in pixels.
+ buffer_pixels: Buffer size in pixels.
+ pixel_size: Pixel size in meters.
+
+ Returns:
+ Tuple of (adjusted_tile_size, warning_message or None).
+
+ Constraints:
+ - tile_size >= MIN_TILE_SIZE (256)
+ - tile_size <= MAX_TILE_SIZE (2500)
+ - Core area (tile_size - 2*buffer) >= 128 pixels
+ """
+ warning = None
+ adjusted = tile_size
+
+ # Enforce minimum
+ if adjusted < MIN_TILE_SIZE:
+ warning = f"Tile size {tile_size} below minimum, using {MIN_TILE_SIZE}"
+ adjusted = MIN_TILE_SIZE
+
+ # Enforce maximum
+ if adjusted > MAX_TILE_SIZE:
+ warning = f"Tile size {tile_size} above maximum, using {MAX_TILE_SIZE}"
+ adjusted = MAX_TILE_SIZE
+
+ # Ensure meaningful core area (at least 128 pixels after buffer)
+ min_for_buffer = 2 * buffer_pixels + 128
+ if adjusted < min_for_buffer:
+ adjusted = min(min_for_buffer, MAX_TILE_SIZE)
+ buffer_m = buffer_pixels * pixel_size
+ warning = f"Tile size increased to {adjusted} to ensure meaningful core area with {buffer_m:.0f}m buffer"
+
+ return adjusted, warning
+
+
+def generate_tiles(
+ rows: int,
+ cols: int,
+ tile_size: int,
+ overlap: int,
+) -> list[TileSpec]:
+ """
+ Generate tile specifications with overlaps for tiled processing.
+
+ Args:
+ rows: Total number of rows in raster.
+ cols: Total number of columns in raster.
+ tile_size: Core tile size in pixels (without overlap).
+ overlap: Overlap size in pixels.
+
+ Returns:
+ List of TileSpec objects covering the entire raster.
+ """
+ tiles = []
+ n_tiles_row = int(np.ceil(rows / tile_size))
+ n_tiles_col = int(np.ceil(cols / tile_size))
+
+ for i in range(n_tiles_row):
+ for j in range(n_tiles_col):
+ # Core tile bounds
+ row_start = i * tile_size
+ row_end = min((i + 1) * tile_size, rows)
+ col_start = j * tile_size
+ col_end = min((j + 1) * tile_size, cols)
+
+ # Calculate overlaps (bounded by raster edges)
+ overlap_top = overlap if i > 0 else 0
+ overlap_bottom = overlap if row_end < rows else 0
+ overlap_left = overlap if j > 0 else 0
+ overlap_right = overlap if col_end < cols else 0
+
+ # Full tile bounds with overlap
+ row_start_full = max(0, row_start - overlap_top)
+ row_end_full = min(rows, row_end + overlap_bottom)
+ col_start_full = max(0, col_start - overlap_left)
+ col_end_full = min(cols, col_end + overlap_right)
+
+ tiles.append(
+ TileSpec(
+ row_start=row_start,
+ row_end=row_end,
+ col_start=col_start,
+ col_end=col_end,
+ row_start_full=row_start_full,
+ row_end_full=row_end_full,
+ col_start_full=col_start_full,
+ col_end_full=col_end_full,
+ overlap_top=overlap_top,
+ overlap_bottom=overlap_bottom,
+ overlap_left=overlap_left,
+ overlap_right=overlap_right,
+ )
+ )
+
+ return tiles
+
+
+def calculate_tiled(
+ surface: SurfaceData,
+ location: Location,
+ weather: Weather,
+ human: HumanParams | None = None,
+ precomputed: PrecomputedData | None = None,
+ tile_size: int = 1024,
+ use_anisotropic_sky: bool = False,
+ conifer: bool = False,
+ physics: SimpleNamespace | None = None,
+ materials: SimpleNamespace | None = None,
+ max_shadow_distance_m: float = MAX_BUFFER_M,
+ progress_callback: Callable[..., Any] | None = None,
+) -> SolweigResult:
+ """
+ Calculate mean radiant temperature using tiled processing for large rasters.
+
+ Processes the raster in tiles with overlapping buffers to ensure accurate
+ shadow calculations at tile boundaries.
+
+ Args:
+ surface: Surface/terrain data (DSM required).
+ location: Geographic location (lat, lon, UTC offset).
+ weather: Weather data for a single timestep.
+ human: Human body parameters. Uses defaults if not provided.
+ precomputed: Pre-computed walls (SVF computed per-tile).
+ tile_size: Core tile size in pixels (default 1024).
+ use_anisotropic_sky: Use anisotropic sky model. Default False.
+ conifer: Treat vegetation as evergreen conifers. Default False.
+ physics: Physics parameters. If None, uses bundled defaults.
+ materials: Material properties. If None, uses bundled defaults.
+ max_shadow_distance_m: Maximum shadow reach / tile buffer in meters.
+ Default 500.0.
+ progress_callback: Optional callback(tile_idx, total_tiles).
+
+ Returns:
+ SolweigResult with Tmrt grid. State is not returned for single-timestep
+ tiled mode.
+ """
+
+ logger = logging.getLogger(__name__)
+
+ if human is None:
+ human = HumanParams()
+
+ # Compute derived weather values
+ if not weather._derived_computed:
+ weather.compute_derived(location)
+
+ rows, cols = surface.shape
+ pixel_size = surface.pixel_size
+
+ # Tile overlap = max_shadow_distance_m (conservative worst case)
+ buffer_pixels = int(np.ceil(max_shadow_distance_m / pixel_size))
+
+ # Validate and adjust tile size
+ adjusted_tile_size, warning = validate_tile_size(tile_size, buffer_pixels, pixel_size)
+ if warning:
+ logger.warning(warning)
+
+ # Check if tiling is actually needed
+ if rows <= adjusted_tile_size and cols <= adjusted_tile_size:
+ logger.info(f"Raster {rows}x{cols} fits in single tile, using non-tiled calculation")
+ from .api import calculate
+
+ return calculate(
+ surface=surface,
+ location=location,
+ weather=weather,
+ human=human,
+ use_anisotropic_sky=use_anisotropic_sky,
+ physics=physics,
+ materials=materials,
+ max_shadow_distance_m=max_shadow_distance_m,
+ )
+
+ # Generate tiles
+ tiles = generate_tiles(rows, cols, adjusted_tile_size, buffer_pixels)
+ n_tiles = len(tiles)
+
+ from .api import calculate
+
+ logger.info(
+ f"Tiled processing: {rows}x{cols} raster, {n_tiles} tiles, "
+ f"tile_size={adjusted_tile_size}, buffer={max_shadow_distance_m:.0f}m ({buffer_pixels}px)"
+ )
+
+ # Initialize output arrays
+ tmrt_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ shadow_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ kdown_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ kup_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ ldown_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ lup_out = np.full((rows, cols), np.nan, dtype=np.float32)
+
+ # Set up progress reporting
+ from .progress import ProgressReporter
+
+ _progress = None if progress_callback is not None else ProgressReporter(total=n_tiles, desc="SOLWEIG tiled")
+
+ # Process each tile
+ for tile_idx, tile in enumerate(tiles):
+ # Update progress description
+ desc = f"Tile {tile_idx + 1}/{n_tiles}"
+ if _progress is not None:
+ _progress.set_description(desc)
+ _progress.set_text(f"Tile {tile_idx + 1}/{n_tiles}")
+
+ if progress_callback:
+ progress_callback(tile_idx, n_tiles)
+
+ tile_surface = _extract_tile_surface(surface, tile, pixel_size)
+ tile_precomputed = _slice_tile_precomputed(precomputed, tile)
+
+ tile_result = calculate(
+ surface=tile_surface,
+ location=location,
+ weather=weather,
+ human=human,
+ precomputed=tile_precomputed,
+ use_anisotropic_sky=use_anisotropic_sky,
+ conifer=conifer,
+ state=None,
+ physics=physics,
+ materials=materials,
+ max_shadow_distance_m=max_shadow_distance_m,
+ )
+
+ _write_tile_result(tile_result, tile, tmrt_out, shadow_out, kdown_out, kup_out, ldown_out, lup_out)
+
+ if _progress is not None:
+ _progress.update(1)
+
+ if progress_callback:
+ progress_callback(n_tiles, n_tiles)
+
+ if _progress is not None:
+ _progress.close()
+
+ return SolweigResult(
+ tmrt=tmrt_out,
+ shadow=shadow_out,
+ kdown=kdown_out,
+ kup=kup_out,
+ ldown=ldown_out,
+ lup=lup_out,
+ utci=None,
+ pet=None,
+ state=None,
+ )
+
+
+def calculate_timeseries_tiled(
+ surface: SurfaceData,
+ weather_series: list[Weather],
+ location: Location,
+ config: ModelConfig | None = None,
+ human: HumanParams | None = None,
+ precomputed: PrecomputedData | None = None,
+ use_anisotropic_sky: bool | None = None,
+ conifer: bool = False,
+ physics: SimpleNamespace | None = None,
+ materials: SimpleNamespace | None = None,
+ wall_material: str | None = None,
+ max_shadow_distance_m: float | None = None,
+ output_dir: str | Path | None = None,
+ outputs: list[str] | None = None,
+ progress_callback: Callable[[int, int], None] | None = None,
+) -> list[SolweigResult]:
+ """
+ Calculate Tmrt timeseries using tiled processing for large rasters.
+
+ Automatically divides large rasters into overlapping tiles and processes
+ each timestep tile-by-tile, preserving thermal state accumulation across
+ both tiles and timesteps.
+
+ This function is called automatically by calculate_timeseries() when the
+ raster exceeds MAX_TILE_SIZE in either dimension.
+
+ Args:
+ surface: Surface/terrain data (DSM required).
+ weather_series: List of Weather objects in chronological order.
+ location: Geographic location (lat, lon, UTC offset).
+ config: Model configuration (provides defaults for None params).
+ human: Human body parameters. If None, uses config or defaults.
+ precomputed: Pre-computed walls (SVF computed per-tile).
+ use_anisotropic_sky: Use anisotropic sky model.
+ Not supported in tiled mode — raises NotImplementedError.
+ conifer: Treat vegetation as evergreen conifers. Default False.
+ physics: Physics parameters. If None, uses config or bundled defaults.
+ materials: Material properties. If None, uses config or bundled defaults.
+ wall_material: Wall material type for temperature model.
+ max_shadow_distance_m: Maximum shadow reach / tile buffer in meters.
+ If None, uses config or default (500.0).
+ output_dir: Directory to save results incrementally as GeoTIFF.
+ outputs: Which outputs to save (e.g., ["tmrt", "shadow"]).
+ progress_callback: Optional callback(current_step, total_steps).
+
+ Returns:
+ List of SolweigResult objects, one per timestep.
+ """
+ if not weather_series:
+ return []
+
+ # Resolve effective parameters from config
+ effective_aniso = use_anisotropic_sky
+ effective_human = human
+ effective_physics = physics
+ effective_materials = materials
+ effective_outputs = outputs
+ effective_max_shadow = max_shadow_distance_m
+
+ if config is not None:
+ if effective_aniso is None:
+ effective_aniso = config.use_anisotropic_sky
+ if effective_human is None:
+ effective_human = config.human
+ if effective_physics is None:
+ effective_physics = config.physics
+ if effective_materials is None:
+ effective_materials = config.materials
+ if effective_outputs is None and config.outputs:
+ effective_outputs = config.outputs
+ if effective_max_shadow is None:
+ effective_max_shadow = config.max_shadow_distance_m
+
+ if effective_aniso is None:
+ effective_aniso = False
+ if effective_human is None:
+ effective_human = HumanParams()
+ if effective_max_shadow is None:
+ effective_max_shadow = MAX_BUFFER_M
+ if effective_materials is None:
+ from .loaders import load_params
+
+ effective_materials = load_params()
+ if effective_physics is None:
+ from .loaders import load_physics
+
+ effective_physics = load_physics()
+
+ if output_dir is not None and effective_outputs is None:
+ effective_outputs = ["tmrt"]
+
+ # Fill NaN in surface layers
+ surface.fill_nan()
+
+ rows, cols = surface.shape
+ pixel_size = surface.pixel_size
+
+ # Tile overlap = max_shadow_distance_m (conservative worst case)
+ buffer_pixels = int(np.ceil(effective_max_shadow / pixel_size))
+
+ # Determine tile size
+ tile_size = _calculate_auto_tile_size(rows, cols)
+ adjusted_tile_size, warning = validate_tile_size(tile_size, buffer_pixels, pixel_size)
+ if warning:
+ logger.warning(warning)
+
+ # Generate tiles
+ tiles = generate_tiles(rows, cols, adjusted_tile_size, buffer_pixels)
+ n_tiles = len(tiles)
+ n_steps = len(weather_series)
+
+ # Pre-compute weather (sun positions, radiation)
+ from .timeseries import _precompute_weather
+
+ logger.info("=" * 60)
+ logger.info("Starting SOLWEIG tiled timeseries calculation")
+ logger.info(f" Grid size: {cols}x{rows} pixels")
+ logger.info(f" Timesteps: {n_steps}")
+ start_str = weather_series[0].datetime.strftime("%Y-%m-%d %H:%M")
+ end_str = weather_series[-1].datetime.strftime("%Y-%m-%d %H:%M")
+ logger.info(f" Period: {start_str} -> {end_str}")
+ logger.info(f" Location: {location.latitude:.2f}N, {location.longitude:.2f}E")
+ logger.info(f" Tiles: {n_tiles} (size={adjusted_tile_size}, buffer={effective_max_shadow:.0f}m)")
+ logger.info("=" * 60)
+
+ logger.info("Pre-computing sun positions and radiation splits...")
+ precompute_start = time.time()
+ _precompute_weather(weather_series, location)
+ precompute_time = time.time() - precompute_start
+ logger.info(f" Pre-computed {n_steps} timesteps in {precompute_time:.1f}s")
+
+ # Create output directory if needed
+ if output_dir is not None:
+ output_path = Path(output_dir)
+ output_path.mkdir(parents=True, exist_ok=True)
+
+ # Import calculate
+ from .api import calculate
+
+ # Initialize global state
+ state = ThermalState.initial(surface.shape)
+ if len(weather_series) >= 2:
+ dt0 = weather_series[0].datetime
+ dt1 = weather_series[1].datetime
+ state.timestep_dec = (dt1 - dt0).total_seconds() / 86400.0
+
+ results = []
+ total_work = n_steps * n_tiles
+ start_time = time.time()
+
+ # Incremental stats
+ _tmrt_sum = 0.0
+ _tmrt_max = -np.inf
+ _tmrt_min = np.inf
+ _tmrt_count = 0
+
+ # Set up progress reporting
+ from .progress import ProgressReporter
+
+ _progress = (
+ None if progress_callback is not None else ProgressReporter(total=total_work, desc="SOLWEIG tiled timeseries")
+ )
+
+ for t_idx, weather in enumerate(weather_series):
+ # Initialize output arrays for this timestep
+ tmrt_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ shadow_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ kdown_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ kup_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ ldown_out = np.full((rows, cols), np.nan, dtype=np.float32)
+ lup_out = np.full((rows, cols), np.nan, dtype=np.float32)
+
+ for tile_idx, tile in enumerate(tiles):
+ # Update progress description before computing this tile
+ desc = f"Step {t_idx + 1}/{n_steps} | Tile {tile_idx + 1}/{n_tiles}"
+ if _progress is not None:
+ _progress.set_description(desc)
+ _progress.set_text(f"Timestep {t_idx + 1}/{n_steps} \u2014 Tile {tile_idx + 1}/{n_tiles}")
+
+ # Extract tile surface
+ tile_surface = _extract_tile_surface(surface, tile, pixel_size)
+ tile_precomputed = _slice_tile_precomputed(precomputed, tile)
+
+ # Slice state for this tile
+ tile_state = _slice_tile_state(state, tile)
+
+ # Compute tile
+ tile_result = calculate(
+ surface=tile_surface,
+ location=location,
+ weather=weather,
+ human=effective_human,
+ precomputed=tile_precomputed,
+ use_anisotropic_sky=effective_aniso,
+ conifer=conifer,
+ state=tile_state,
+ physics=effective_physics,
+ materials=effective_materials,
+ wall_material=wall_material,
+ max_shadow_distance_m=effective_max_shadow,
+ )
+
+ # Write core results to global arrays
+ _write_tile_result(tile_result, tile, tmrt_out, shadow_out, kdown_out, kup_out, ldown_out, lup_out)
+
+ # Merge tile state back to global state
+ if tile_result.state is not None:
+ _merge_tile_state(tile_result.state, tile, state)
+
+ # Report progress
+ step = t_idx * n_tiles + tile_idx + 1
+ if progress_callback is not None:
+ progress_callback(step, total_work)
+ elif _progress is not None:
+ _progress.update(1)
+
+ # Log timestep completion
+ elapsed = time.time() - start_time
+ rate = (t_idx + 1) / elapsed if elapsed > 0 else 0
+ logger.info(f" Timestep {t_idx + 1}/{n_steps} complete ({rate:.2f} steps/s)")
+
+ # Create result for this timestep
+ result = SolweigResult(
+ tmrt=tmrt_out,
+ shadow=shadow_out,
+ kdown=kdown_out,
+ kup=kup_out,
+ ldown=ldown_out,
+ lup=lup_out,
+ utci=None,
+ pet=None,
+ state=None, # State managed externally
+ )
+
+ # Save incrementally if output_dir provided
+ if output_dir is not None:
+ result.to_geotiff(
+ output_dir=output_dir,
+ timestamp=weather.datetime,
+ outputs=effective_outputs,
+ surface=surface,
+ )
+
+ results.append(result)
+
+ # Update incremental stats
+ _valid = result.tmrt[np.isfinite(result.tmrt)]
+ if _valid.size > 0:
+ _tmrt_sum += _valid.sum()
+ _tmrt_count += _valid.size
+ _tmrt_max = max(_tmrt_max, float(_valid.max()))
+ _tmrt_min = min(_tmrt_min, float(_valid.min()))
+
+ # Close progress bar
+ if _progress is not None:
+ _progress.close()
+
+ # Log summary
+ total_time = time.time() - start_time
+ overall_rate = len(results) / total_time if total_time > 0 else 0
+
+ logger.info("=" * 60)
+ logger.info(f"Calculation complete: {len(results)} timesteps processed (tiled)")
+ logger.info(f" Total time: {total_time:.1f}s ({overall_rate:.2f} steps/s)")
+ if _tmrt_count > 0:
+ mean_tmrt = _tmrt_sum / _tmrt_count
+ logger.info(f" Tmrt range: {_tmrt_min:.1f}C - {_tmrt_max:.1f}C (mean: {mean_tmrt:.1f}C)")
+
+ if output_dir is not None and effective_outputs is not None:
+ file_count = len(results) * len(effective_outputs)
+ logger.info(f" Files saved: {file_count} GeoTIFFs in {output_dir}")
+ logger.info("=" * 60)
+
+ # Save run metadata if output_dir provided
+ if output_dir is not None:
+ from .metadata import create_run_metadata, save_run_metadata
+
+ metadata = create_run_metadata(
+ surface=surface,
+ location=location,
+ weather_series=weather_series,
+ human=effective_human,
+ physics=effective_physics,
+ materials=effective_materials,
+ use_anisotropic_sky=effective_aniso,
+ conifer=conifer,
+ output_dir=output_dir,
+ outputs=effective_outputs,
+ )
+ save_run_metadata(metadata, output_dir)
+
+ return results
diff --git a/pysrc/solweig/timeseries.py b/pysrc/solweig/timeseries.py
new file mode 100644
index 0000000..42f672a
--- /dev/null
+++ b/pysrc/solweig/timeseries.py
@@ -0,0 +1,439 @@
+"""Time series calculation with thermal state management."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from pathlib import Path
+from types import SimpleNamespace
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from .metadata import create_run_metadata, save_run_metadata
+from .models import HumanParams, Location, ThermalState
+from .progress import ProgressReporter
+from .solweig_logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def _precompute_weather(weather_series: list, location: Location) -> None:
+ """
+ Pre-compute derived weather values for all timesteps efficiently.
+
+ Optimizations:
+ 1. Compute max sun altitude (altmax) only once per unique day
+ 2. Pre-assign altmax to Weather objects to skip the 96-iteration loop
+
+ This reduces compute_derived() from O(96) iterations to O(1) per timestep
+ when multiple timesteps share the same day.
+
+ Args:
+ weather_series: List of Weather objects to process
+ location: Geographic location for sun position calculations
+ """
+ if not weather_series:
+ return
+
+ from datetime import timedelta
+
+ import numpy as np
+
+ from .physics import sun_position as sp
+
+ location_dict = location.to_sun_position_dict()
+
+ # Step 1: Compute altmax once per unique day
+ altmax_cache = {} # date -> altmax
+
+ for weather in weather_series:
+ day = weather.datetime.date()
+ if day not in altmax_cache:
+ # Compute max sun altitude for this day (iterate in 15-min intervals)
+ ymd = weather.datetime.replace(hour=0, minute=0, second=0, microsecond=0)
+ sunmaximum = -90.0
+ fifteen_min = 15.0 / 1440.0 # 15 minutes as fraction of day
+
+ for step in range(96): # 24 hours * 4 (15-min intervals)
+ step_time = ymd + timedelta(days=step * fifteen_min)
+ time_dict_step = {
+ "year": step_time.year,
+ "month": step_time.month,
+ "day": step_time.day,
+ "hour": step_time.hour,
+ "min": step_time.minute,
+ "sec": 0,
+ "UTC": location.utc_offset,
+ }
+ sun_step = sp.sun_position(time_dict_step, location_dict)
+ zenith_step = sun_step["zenith"]
+ zenith_val = (
+ float(np.asarray(zenith_step).flat[0]) if hasattr(zenith_step, "__iter__") else float(zenith_step)
+ )
+ altitude_step = 90.0 - zenith_val
+ if altitude_step > sunmaximum:
+ sunmaximum = altitude_step
+
+ altmax_cache[day] = sunmaximum
+
+ # Step 2: Pre-assign altmax to each weather object
+ for weather in weather_series:
+ day = weather.datetime.date()
+ weather.precomputed_altmax = altmax_cache[day]
+
+ # Step 3: Compute derived values (now fast since altmax is cached)
+ for weather in weather_series:
+ if not weather._derived_computed:
+ weather.compute_derived(location)
+
+
+if TYPE_CHECKING:
+ from .models import (
+ ModelConfig,
+ PrecomputedData,
+ SolweigResult,
+ SurfaceData,
+ Weather,
+ )
+
+
+def calculate_timeseries(
+ surface: SurfaceData,
+ weather_series: list[Weather],
+ location: Location | None = None,
+ config: ModelConfig | None = None,
+ human: HumanParams | None = None,
+ precomputed: PrecomputedData | None = None,
+ use_anisotropic_sky: bool | None = None,
+ conifer: bool = False,
+ physics: SimpleNamespace | None = None,
+ materials: SimpleNamespace | None = None,
+ wall_material: str | None = None,
+ max_shadow_distance_m: float | None = None,
+ output_dir: str | Path | None = None,
+ outputs: list[str] | None = None,
+ progress_callback: Callable[[int, int], None] | None = None,
+) -> list[SolweigResult]:
+ """
+ Calculate Tmrt for a time series of weather data.
+
+ Maintains thermal state across timesteps for accurate surface temperature
+ modeling with thermal inertia (TsWaveDelay_2015a).
+
+ Large rasters (>2500x2500 pixels) are automatically processed using
+ overlapping tiles to manage memory. Shadow buffer distance is set to
+ max_shadow_distance_m, ensuring accurate results at tile boundaries.
+
+ This is a convenience function that manages state automatically. For custom
+ control over state, use calculate() directly with the state parameter.
+
+ Args:
+ surface: Surface/terrain data (DSM required, CDSM/DEM optional).
+ weather_series: List of Weather objects in chronological order.
+ The datetime of each Weather object determines the timestep size.
+ location: Geographic location (lat, lon, UTC offset). If None, automatically
+ extracted from surface's CRS metadata.
+ config: Model configuration object providing base settings.
+ Explicit parameters override config values when provided.
+ human: Human body parameters (absorption, posture, weight, height, etc.).
+ If None, uses config.human or HumanParams defaults.
+ precomputed: Pre-computed SVF and/or shadow matrices. Optional.
+ use_anisotropic_sky: Use anisotropic sky model.
+ If None, uses config.use_anisotropic_sky or defaults to False.
+ conifer: Treat vegetation as evergreen conifers (always leaf-on). Default False.
+ physics: Physics parameters (Tree_settings, Posture geometry) from load_physics().
+ Site-independent scientific constants. If None, uses config.physics or bundled defaults.
+ materials: Material properties (albedo, emissivity per landcover class) from load_materials().
+ Site-specific landcover parameters. Only needed if surface has land_cover grid.
+ If None, uses config.materials.
+ wall_material: Wall material type for temperature model.
+ One of "brick", "concrete", "wood", "cobblestone" (case-insensitive).
+ If None (default), uses generic wall params from materials JSON.
+ max_shadow_distance_m: Maximum shadow reach in metres (default 500.0).
+ Caps shadow ray computation distance and serves as the tile overlap
+ buffer for automatic tiled processing of large rasters. If None,
+ uses config.max_shadow_distance_m or 500.0.
+ output_dir: Directory to save results. If provided, results are saved
+ incrementally as GeoTIFF files during calculation (recommended for
+ long timeseries to avoid memory issues).
+ outputs: Which outputs to save (e.g., ["tmrt", "shadow", "kdown"]).
+ Only used if output_dir is provided. If None, uses config.outputs or ["tmrt"].
+ progress_callback: Optional callback(current_step, total_steps) called after
+ each timestep. If None, a tqdm progress bar is shown automatically.
+
+ Returns:
+ List of SolweigResult objects, one per timestep.
+ Each result includes the thermal state at that timestep.
+ Note: UTCI and PET fields will be None. Use compute_utci() or compute_pet()
+ for post-processing thermal comfort indices.
+
+ Example:
+ # Run time series with all defaults
+ results = calculate_timeseries(
+ surface=surface,
+ weather_series=weather_list,
+ output_dir="output/",
+ )
+
+ # With config as base, explicit param override
+ config = ModelConfig(use_anisotropic_sky=True)
+ results = calculate_timeseries(
+ surface=surface,
+ weather_series=weather_list,
+ config=config,
+ use_anisotropic_sky=False, # Explicit param wins
+ output_dir="output/",
+ )
+ """
+ if not weather_series:
+ return []
+
+ # Auto-extract location from surface if not provided
+ if location is None:
+ logger.warning(
+ "Location not provided - auto-extracting from surface CRS.\n"
+ "⚠️ UTC offset will default to 0 if not specified, which may cause incorrect sun positions.\n"
+ " Recommend: provide location explicitly with correct UTC offset."
+ )
+ location = Location.from_surface(surface)
+
+ # Build effective configuration: explicit params override config
+ effective_aniso = use_anisotropic_sky
+ effective_human = human
+ effective_physics = physics
+ effective_materials = materials
+ effective_outputs = outputs
+ effective_max_shadow = max_shadow_distance_m
+
+ if config is not None:
+ # Use config values as fallback for None parameters
+ if effective_aniso is None:
+ effective_aniso = config.use_anisotropic_sky
+ if effective_human is None:
+ effective_human = config.human
+ if effective_physics is None:
+ effective_physics = config.physics
+ if effective_materials is None:
+ effective_materials = config.materials
+ if effective_outputs is None and config.outputs:
+ effective_outputs = config.outputs
+ if effective_max_shadow is None:
+ effective_max_shadow = config.max_shadow_distance_m
+
+ # Debug log when explicit params override config
+ overrides = []
+ if use_anisotropic_sky is not None and use_anisotropic_sky != config.use_anisotropic_sky:
+ overrides.append(f"use_anisotropic_sky={use_anisotropic_sky}")
+ if human is not None and config.human is not None:
+ overrides.append("human")
+ if physics is not None and config.physics is not None:
+ overrides.append("physics")
+ if materials is not None and config.materials is not None:
+ overrides.append("materials")
+ if outputs is not None and config.outputs:
+ overrides.append("outputs")
+ if max_shadow_distance_m is not None and max_shadow_distance_m != config.max_shadow_distance_m:
+ overrides.append(f"max_shadow_distance_m={max_shadow_distance_m}")
+ if overrides:
+ logger.debug(f"Explicit params override config: {', '.join(overrides)}")
+
+ # Apply defaults for anything still None
+ if effective_aniso is None:
+ effective_aniso = False
+ # Auto-load bundled UMEP JSON as default materials (single source of truth)
+ if effective_materials is None:
+ from .loaders import load_params
+
+ effective_materials = load_params()
+
+ # Assign back for use in the rest of the function
+ use_anisotropic_sky = effective_aniso
+ human = effective_human
+ physics = effective_physics
+ materials = effective_materials
+ outputs = effective_outputs
+
+ # Fill NaN in surface layers (idempotent — skipped if already done)
+ surface.fill_nan()
+
+ # Auto-tile large rasters transparently
+ from .tiling import _should_use_tiling
+
+ if _should_use_tiling(surface.shape[0], surface.shape[1]):
+ from .tiling import calculate_timeseries_tiled
+
+ logger.info(
+ f"Raster size {surface.dsm.shape[1]}×{surface.dsm.shape[0]} exceeds tiling threshold — "
+ "switching to tiled processing."
+ )
+ return calculate_timeseries_tiled(
+ surface=surface,
+ weather_series=weather_series,
+ location=location,
+ human=human,
+ precomputed=precomputed,
+ use_anisotropic_sky=use_anisotropic_sky,
+ conifer=conifer,
+ physics=physics,
+ materials=materials,
+ wall_material=wall_material,
+ max_shadow_distance_m=effective_max_shadow,
+ output_dir=output_dir,
+ outputs=outputs,
+ progress_callback=progress_callback,
+ )
+
+ # Log configuration summary
+ logger.info("=" * 60)
+ logger.info("Starting SOLWEIG timeseries calculation")
+ logger.info(f" Grid size: {surface.dsm.shape[1]}×{surface.dsm.shape[0]} pixels")
+ logger.info(f" Timesteps: {len(weather_series)}")
+ start_str = weather_series[0].datetime.strftime("%Y-%m-%d %H:%M")
+ end_str = weather_series[-1].datetime.strftime("%Y-%m-%d %H:%M")
+ logger.info(f" Period: {start_str} → {end_str}")
+ logger.info(f" Location: {location.latitude:.2f}°N, {location.longitude:.2f}°E")
+
+ options = []
+ if use_anisotropic_sky:
+ options.append("anisotropic sky")
+ if precomputed is not None:
+ options.append("precomputed SVF")
+ if options:
+ logger.info(f" Options: {', '.join(options)}")
+
+ if output_dir is not None:
+ logger.info(f" Auto-save: {output_dir} ({', '.join(outputs or ['tmrt'])})")
+ logger.info("=" * 60)
+
+ # Create output directory if needed
+ if output_dir is not None:
+ output_path = Path(output_dir)
+ output_path.mkdir(parents=True, exist_ok=True)
+
+ # Default outputs
+ if output_dir is not None and outputs is None:
+ outputs = ["tmrt"]
+
+ # Import calculate here to avoid circular import
+ from .api import calculate
+
+ # Pre-compute derived weather values in parallel (sun position, radiation split)
+ # This is ~4x faster than computing sequentially in the main loop
+ logger.info("Pre-computing sun positions and radiation splits...")
+ precompute_start = time.time()
+ _precompute_weather(weather_series, location)
+ precompute_time = time.time() - precompute_start
+ logger.info(f" Pre-computed {len(weather_series)} timesteps in {precompute_time:.1f}s")
+
+ results = []
+ state = ThermalState.initial(surface.shape)
+
+ # Incremental stats accumulators (avoids iterating all results for summary)
+ _tmrt_sum = 0.0
+ _tmrt_max = -np.inf
+ _tmrt_min = np.inf
+ _tmrt_count = 0
+
+ # Pre-calculate timestep size from first two entries (matching runner behavior)
+ # The runner uses a fixed timestep_dec for all iterations, calculated upfront
+ if len(weather_series) >= 2:
+ dt0 = weather_series[0].datetime
+ dt1 = weather_series[1].datetime
+ state.timestep_dec = (dt1 - dt0).total_seconds() / 86400.0
+
+ # Pre-create buffer pool for array reuse across timesteps
+ _ = surface.get_buffer_pool()
+
+ # Set up progress reporting (caller callback suppresses tqdm)
+ n_steps = len(weather_series)
+ _progress = None if progress_callback is not None else ProgressReporter(total=n_steps, desc="SOLWEIG timeseries")
+
+ # Start timing
+ start_time = time.time()
+
+ for i, weather in enumerate(weather_series):
+ # Process timestep
+ result = calculate(
+ surface=surface,
+ location=location,
+ weather=weather,
+ human=human,
+ precomputed=precomputed,
+ use_anisotropic_sky=use_anisotropic_sky,
+ conifer=conifer,
+ state=state,
+ physics=physics,
+ materials=materials,
+ wall_material=wall_material,
+ max_shadow_distance_m=effective_max_shadow,
+ )
+
+ # Carry forward state to next timestep
+ if result.state is not None:
+ state = result.state
+ result.state = None # Free state arrays (~23 MB); state managed externally
+
+ # Save incrementally if output_dir provided
+ if output_dir is not None:
+ result.to_geotiff(
+ output_dir=output_dir,
+ timestamp=weather.datetime,
+ outputs=outputs,
+ surface=surface,
+ )
+
+ results.append(result)
+
+ # Update incremental stats
+ _valid = result.tmrt[np.isfinite(result.tmrt)]
+ if _valid.size > 0:
+ _tmrt_sum += _valid.sum()
+ _tmrt_count += _valid.size
+ _tmrt_max = max(_tmrt_max, float(_valid.max()))
+ _tmrt_min = min(_tmrt_min, float(_valid.min()))
+
+ # Report progress
+ if progress_callback is not None:
+ progress_callback(i + 1, n_steps)
+ elif _progress is not None:
+ _progress.update(1)
+
+ # Close progress bar
+ if _progress is not None:
+ _progress.close()
+
+ # Calculate total elapsed time
+ total_time = time.time() - start_time
+ overall_rate = len(results) / total_time if total_time > 0 else 0
+
+ # Log summary statistics
+ logger.info("=" * 60)
+ logger.info(f"✓ Calculation complete: {len(results)} timesteps processed")
+ logger.info(f" Total time: {total_time:.1f}s ({overall_rate:.2f} steps/s)")
+ if _tmrt_count > 0:
+ mean_tmrt = _tmrt_sum / _tmrt_count
+ logger.info(f" Tmrt range: {_tmrt_min:.1f}°C - {_tmrt_max:.1f}°C (mean: {mean_tmrt:.1f}°C)")
+
+ if output_dir is not None and outputs is not None:
+ file_count = len(results) * len(outputs)
+ logger.info(f" Files saved: {file_count} GeoTIFFs in {output_dir}")
+ logger.info("=" * 60)
+
+ # Save run metadata if output_dir is provided
+ if output_dir is not None:
+ metadata = create_run_metadata(
+ surface=surface,
+ location=location,
+ weather_series=weather_series,
+ human=human,
+ physics=physics,
+ materials=materials,
+ use_anisotropic_sky=use_anisotropic_sky,
+ conifer=conifer,
+ output_dir=output_dir,
+ outputs=outputs,
+ )
+ save_run_metadata(metadata, output_dir)
+
+ return results
diff --git a/pysrc/solweig/utils.py b/pysrc/solweig/utils.py
new file mode 100644
index 0000000..cf7c36e
--- /dev/null
+++ b/pysrc/solweig/utils.py
@@ -0,0 +1,285 @@
+"""Utility functions for geometry and namespace conversion."""
+
+from __future__ import annotations
+
+import logging
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from ._compat import GDAL_AVAILABLE, RASTERIO_AVAILABLE
+
+if TYPE_CHECKING:
+ from affine import Affine
+ from numpy.typing import NDArray
+
+logger = logging.getLogger(__name__)
+
+if RASTERIO_AVAILABLE:
+ from rasterio.transform import array_bounds, from_bounds # noqa: F401
+ from rasterio.warp import Resampling, reproject # noqa: F401
+elif GDAL_AVAILABLE:
+ from osgeo import gdal, gdalconst # noqa: F401
+
+
+# =============================================================================
+# Namespace Conversion (for JSON parameter loading)
+# =============================================================================
+
+
+def dict_to_namespace(d: dict[str, Any] | list | Any) -> SimpleNamespace | list | Any:
+ """
+ Recursively convert dicts to SimpleNamespace.
+
+ This matches the runner's dict_to_namespace function for loading JSON parameters.
+
+ Args:
+ d: Dictionary, list, or scalar value to convert
+
+ Returns:
+ SimpleNamespace for dicts, list of converted items for lists, or original value for scalars
+ """
+ if isinstance(d, dict):
+ return SimpleNamespace(**{k: dict_to_namespace(v) for k, v in d.items()})
+ elif isinstance(d, list):
+ return [dict_to_namespace(i) for i in d]
+ else:
+ return d
+
+
+def namespace_to_dict(ns: SimpleNamespace | Any) -> dict | list | Any:
+ """
+ Recursively convert SimpleNamespace to dict for JSON serialization.
+
+ Inverse of dict_to_namespace.
+
+ Args:
+ ns: SimpleNamespace, list, or scalar value to convert
+
+ Returns:
+ Dict for SimpleNamespace, list of converted items for lists, or original value for scalars
+ """
+ if isinstance(ns, SimpleNamespace):
+ return {k: namespace_to_dict(v) for k, v in vars(ns).items()}
+ elif isinstance(ns, list):
+ return [namespace_to_dict(i) for i in ns]
+ else:
+ return ns
+
+
+# =============================================================================
+# Geometric Utilities (for raster operations)
+# =============================================================================
+
+
+def extract_bounds(transform: list[float] | Affine, shape: tuple[int, ...]) -> list[float]:
+ """
+ Extract bounding box [minx, miny, maxx, maxy] from affine transform and array shape.
+
+ Works with either rasterio or GDAL backend.
+
+ Args:
+ transform: Affine transformation matrix (Affine object or GDAL list)
+ shape: Array shape (rows, cols)
+
+ Returns:
+ Bounding box as [minx, miny, maxx, maxy]
+ """
+ rows, cols = shape
+
+ if RASTERIO_AVAILABLE:
+ from affine import Affine as AffineClass
+ from rasterio.transform import array_bounds
+
+ # Convert list to Affine if needed
+ if isinstance(transform, list):
+ transform = AffineClass.from_gdal(*transform)
+
+ bounds = array_bounds(rows, cols, transform)
+ # array_bounds returns (left, bottom, right, top)
+ return [bounds[0], bounds[1], bounds[2], bounds[3]]
+
+ elif GDAL_AVAILABLE:
+ # GDAL geotransform: [x_origin, x_pixel_size, x_rotation, y_origin, y_rotation, y_pixel_size]
+ # Convert Affine to GDAL list if needed (Affine has .to_gdal() method)
+ gt = transform if isinstance(transform, list) else list(transform.to_gdal())
+
+ x_origin, x_pixel_size, _, y_origin, _, y_pixel_size = gt
+
+ # Calculate bounds
+ minx = x_origin
+ maxx = x_origin + cols * x_pixel_size
+ maxy = y_origin # y_origin is typically top-left (north)
+ miny = y_origin + rows * y_pixel_size # y_pixel_size is typically negative
+
+ # Ensure correct order (miny < maxy)
+ if miny > maxy:
+ miny, maxy = maxy, miny
+
+ return [minx, miny, maxx, maxy]
+
+ else:
+ raise ImportError(
+ "Neither rasterio nor GDAL available. Install rasterio (pip install rasterio) "
+ "or run in OSGeo4W/QGIS environment."
+ )
+
+
+def intersect_bounds(bounds_list: list[list[float]]) -> list[float]:
+ """
+ Compute intersection of multiple bounding boxes.
+
+ Args:
+ bounds_list: List of bounding boxes, each as [minx, miny, maxx, maxy]
+
+ Returns:
+ Intersection bounding box as [minx, miny, maxx, maxy]
+
+ Raises:
+ ValueError: If bounding boxes don't intersect
+ """
+ if not bounds_list:
+ raise ValueError("No bounding boxes provided")
+
+ # Start with first bounds
+ minx = bounds_list[0][0]
+ miny = bounds_list[0][1]
+ maxx = bounds_list[0][2]
+ maxy = bounds_list[0][3]
+
+ # Compute intersection with remaining bounds
+ for bounds in bounds_list[1:]:
+ minx = max(minx, bounds[0])
+ miny = max(miny, bounds[1])
+ maxx = min(maxx, bounds[2])
+ maxy = min(maxy, bounds[3])
+
+ # Check if intersection is valid
+ if minx >= maxx or miny >= maxy:
+ raise ValueError(f"Bounding boxes don't intersect: intersection would be [{minx}, {miny}, {maxx}, {maxy}]")
+
+ return [minx, miny, maxx, maxy]
+
+
+def resample_to_grid(
+ array: NDArray,
+ src_transform: list[float] | Affine,
+ target_bbox: list[float],
+ target_pixel_size: float,
+ method: str = "bilinear",
+ src_crs: str | None = None,
+) -> tuple[NDArray, Affine]:
+ """
+ Resample array to match target grid specification.
+
+ Works with either rasterio or GDAL backend.
+
+ Args:
+ array: Source array to resample
+ src_transform: Source affine transformation (Affine object or GDAL list)
+ target_bbox: Target bounding box [minx, miny, maxx, maxy]
+ target_pixel_size: Target pixel size in map units
+ method: Resampling method ("bilinear" or "nearest")
+ src_crs: Source CRS (WKT string), required for rasterio reproject
+
+ Returns:
+ Tuple of (resampled_array, target_transform as Affine)
+ """
+ from affine import Affine as AffineClass
+
+ minx, miny, maxx, maxy = target_bbox
+
+ # Calculate target dimensions
+ width = int(np.round((maxx - minx) / target_pixel_size))
+ height = int(np.round((maxy - miny) / target_pixel_size))
+
+ if RASTERIO_AVAILABLE:
+ from rasterio.transform import from_bounds
+ from rasterio.warp import Resampling, reproject
+
+ # Convert list to Affine if needed
+ if isinstance(src_transform, list):
+ src_transform = AffineClass.from_gdal(*src_transform)
+
+ # Create target transform
+ target_transform = from_bounds(minx, miny, maxx, maxy, width, height)
+
+ # Create destination array
+ destination = np.zeros((height, width), dtype=array.dtype)
+
+ # Select resampling method
+ resampling_method = Resampling.nearest if method == "nearest" else Resampling.bilinear
+
+ # Reproject (same CRS, just resampling)
+ reproject(
+ source=array,
+ destination=destination,
+ src_transform=src_transform,
+ dst_transform=target_transform,
+ src_crs=src_crs, # Pass through CRS for rasterio
+ dst_crs=src_crs, # Same CRS (no reprojection, just resampling)
+ resampling=resampling_method,
+ )
+
+ return destination, target_transform
+
+ elif GDAL_AVAILABLE:
+ from osgeo import gdal, gdalconst
+
+ # Convert Affine to GDAL geotransform if needed (Affine has .to_gdal() method)
+ src_gt = src_transform if isinstance(src_transform, list) else list(src_transform.to_gdal())
+
+ # Create target geotransform (top-left origin, positive x, negative y)
+ target_gt = [minx, target_pixel_size, 0, maxy, 0, -target_pixel_size]
+
+ # Map numpy dtype to GDAL type
+ dtype_map = {
+ np.float32: gdalconst.GDT_Float32,
+ np.float64: gdalconst.GDT_Float64,
+ np.int32: gdalconst.GDT_Int32,
+ np.int16: gdalconst.GDT_Int16,
+ np.uint8: gdalconst.GDT_Byte,
+ np.uint16: gdalconst.GDT_UInt16,
+ np.uint32: gdalconst.GDT_UInt32,
+ }
+ gdal_dtype = dtype_map.get(array.dtype.type, gdalconst.GDT_Float32)
+
+ # Select resampling method
+ resample_alg = gdalconst.GRA_NearestNeighbour if method == "nearest" else gdalconst.GRA_Bilinear
+
+ # Create in-memory source dataset
+ src_rows, src_cols = array.shape
+ mem_driver = gdal.GetDriverByName("MEM")
+ src_ds = mem_driver.Create("", src_cols, src_rows, 1, gdal_dtype)
+ src_ds.SetGeoTransform(src_gt)
+ if src_crs:
+ src_ds.SetProjection(src_crs)
+ src_ds.GetRasterBand(1).WriteArray(array)
+
+ # Create in-memory destination dataset
+ dst_ds = mem_driver.Create("", width, height, 1, gdal_dtype)
+ dst_ds.SetGeoTransform(target_gt)
+ if src_crs:
+ dst_ds.SetProjection(src_crs)
+
+ # Perform resampling
+ gdal.ReprojectImage(src_ds, dst_ds, src_crs, src_crs, resample_alg)
+
+ # Read result
+ destination = dst_ds.GetRasterBand(1).ReadAsArray()
+
+ # Clean up
+ src_ds = None
+ dst_ds = None
+
+ # Create Affine transform for return value
+ target_transform = AffineClass.from_gdal(*target_gt)
+
+ return destination, target_transform
+
+ else:
+ raise ImportError(
+ "Neither rasterio nor GDAL available. Install rasterio (pip install rasterio) "
+ "or run in OSGeo4W/QGIS environment."
+ )
diff --git a/pysrc/solweig/walls.py b/pysrc/solweig/walls.py
new file mode 100644
index 0000000..adea4b4
--- /dev/null
+++ b/pysrc/solweig/walls.py
@@ -0,0 +1,59 @@
+"""
+Wall height and aspect generation from DSM.
+
+This algorithm identifies wall pixels and their height from ground and building
+digital surface models (DSM) using filters as presented by Lindberg et al. (2015a).
+Wall aspect is estimated using a specific linear filter as presented by
+Goodwin et al. (1999) and further developed by Lindberg et al. (2015b).
+
+References:
+- Goodwin NR, Coops NC, Tooke TR, Christen A, Voogt JA (2009)
+ Characterizing urban surface cover and structure with airborne lidar technology.
+ Can J Remote Sens 35:297–309
+- Lindberg F., Grimmond, C.S.B. and Martilli, A. (2015a)
+ Sunlit fractions on urban facets - Impact of spatial resolution and approach
+ Urban Climate DOI: 10.1016/j.uclim.2014.11.006
+- Lindberg F., Jonsson, P. & Honjo, T. and Wästberg, D. (2015b)
+ Solar energy on building envelopes - 3D modelling in a 2D environment
+ Solar Energy 115 369–378
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import io as common
+from .physics import wallalgorithms as wa
+
+
+def generate_wall_hts(
+ dsm_path: str,
+ bbox: list[int] | None,
+ out_dir: str,
+ wall_limit: float = 1,
+):
+ """
+ Generate wall height and aspect rasters from a DSM.
+
+ Args:
+ dsm_path: Path to the Digital Surface Model raster
+ bbox: Bounding box [minx, miny, maxx, maxy] or None for full extent
+ out_dir: Output directory for wall_hts.tif and wall_aspects.tif
+ wall_limit: Minimum height to be considered a wall (default: 1m)
+
+ Outputs:
+ wall_hts.tif: Wall heights in meters
+ wall_aspects.tif: Wall aspect in degrees (0 = North)
+ """
+ dsm_rast, dsm_transf, dsm_crs, _dsm_nd = common.load_raster(dsm_path, bbox, coerce_f64_to_f32=True)
+ dsm_scale = 1 / dsm_transf[1]
+
+ out_path = Path(out_dir)
+ out_path.mkdir(parents=True, exist_ok=True)
+ out_path_str = str(out_path)
+
+ walls = wa.findwalls(dsm_rast, wall_limit)
+ common.save_raster(out_path_str + "/" + "wall_hts.tif", walls, dsm_transf, dsm_crs, coerce_f64_to_f32=True)
+
+ dirwalls = wa.filter1Goodwin_as_aspect_v3(walls, dsm_scale, dsm_rast)
+ common.save_raster(out_path_str + "/" + "wall_aspects.tif", dirwalls, dsm_transf, dsm_crs, coerce_f64_to_f32=True)
diff --git a/pysrc/umepr/__init__.py b/pysrc/umepr/__init__.py
deleted file mode 100644
index f52e4a5..0000000
--- a/pysrc/umepr/__init__.py
+++ /dev/null
@@ -1,26 +0,0 @@
-"""
-UMEP-Rust: Urban Multi-scale Environmental Predictor (Rust implementation)
-"""
-
-import logging
-
-logger = logging.getLogger(__name__)
-
-try:
- from .rustalgos import GPU_ENABLED, shadowing
-
- # Export GPU functions at package level
- __all__ = ["GPU_ENABLED", "shadowing"]
-
- # Enable GPU by default if available
- if GPU_ENABLED:
- shadowing.enable_gpu()
- logger.info("GPU acceleration enabled by default")
- else:
- logger.info("GPU support not compiled in this build")
-
-except ImportError as e:
- # If rustalgos is not available or GPU feature not compiled
- logger.warning(f"Failed to import rustalgos GPU functions: {e}")
- GPU_ENABLED = False
- __all__ = ["GPU_ENABLED"]
diff --git a/pysrc/umepr/functions/daily_shading.py b/pysrc/umepr/functions/daily_shading.py
deleted file mode 100644
index 0e9a851..0000000
--- a/pysrc/umepr/functions/daily_shading.py
+++ /dev/null
@@ -1,235 +0,0 @@
-"""
-Daily shading calculations for a given DSM and vegetation DSM.
-Uses Rust algorithms for shadow calculations.
-"""
-
-import datetime as dt
-from builtins import range
-
-import numpy as np
-from tqdm import tqdm
-from umep import common
-from umep.util.SEBESOLWEIGCommonFiles import sun_position as sp
-
-from ..rustalgos import shadowing
-
-
-def daily_shading(
- dsm,
- vegdsm,
- vegdsm2,
- scale,
- lon,
- lat,
- dsm_width,
- dsm_height,
- tv,
- UTC,
- usevegdem,
- timeInterval,
- onetime,
- folder,
- dsm_transf,
- dsm_crs,
- trans,
- dst,
- wallshadow,
- wheight,
- waspect,
-):
- # lon = lonlat[0]
- # lat = lonlat[1]
- year = tv[0]
- month = tv[1]
- day = tv[2]
-
- alt = np.median(dsm)
- location = {"longitude": lon, "latitude": lat, "altitude": alt}
- if usevegdem == 1:
- psi = trans
- # amaxvalue
- vegmax = vegdsm.max()
- amaxvalue = dsm.max() - dsm.min()
- amaxvalue = np.maximum(amaxvalue, vegmax)
-
- # Elevation vegdsms if buildingDSM includes ground heights
- vegdem = vegdsm + dsm
- vegdem[vegdem == dsm] = 0
- vegdem2 = vegdsm2 + dsm
- vegdem2[vegdem2 == dsm] = 0
-
- # Bush separation
- bush = np.logical_not(vegdem2 * vegdem) * vegdem
- else:
- psi = 1.0
- vegdem = np.zeros_like(dsm)
- vegdem2 = np.zeros_like(dsm)
- amaxvalue = dsm.max() - dsm.min()
- bush = np.zeros_like(dsm)
-
- shtot = np.zeros((dsm_height, dsm_width))
-
- if onetime == 1:
- itera = 1
- else:
- itera = int(1440 / timeInterval)
-
- alt = np.zeros(itera)
- azi = np.zeros(itera)
- hour = 0
- index = 0
- time = dict()
- time["UTC"] = UTC
-
- if wallshadow == 1:
- walls = wheight
- dirwalls = waspect
- else:
- walls = np.zeros((dsm_height, dsm_width))
- dirwalls = np.zeros((dsm_height, dsm_width))
-
- for i in tqdm(range(0, itera)):
- if onetime == 0:
- minu = int(timeInterval * i)
- if minu >= 60:
- hour = int(np.floor(minu / 60))
- minu = int(minu - hour * 60)
- else:
- minu = tv[4]
- hour = tv[3]
-
- doy = day_of_year(year, month, day)
-
- ut_time = doy - 1.0 + ((hour - dst) / 24.0) + (minu / (60.0 * 24.0)) + (0.0 / (60.0 * 60.0 * 24.0))
-
- if ut_time < 0:
- year = year - 1
- month = 12
- day = 31
- doy = day_of_year(year, month, day)
- ut_time = ut_time + doy - 1
-
- HHMMSS = dectime_to_timevec(ut_time)
- time["year"] = year
- time["month"] = month
- time["day"] = day
- time["hour"] = HHMMSS[0]
- time["min"] = HHMMSS[1]
- time["sec"] = HHMMSS[2]
-
- sun = sp.sun_position(time, location)
- alt[i] = 90.0 - sun["zenith"]
- azi[i] = sun["azimuth"]
-
- if time["sec"] == 59: # issue 228 and 256
- time["sec"] = 0
- time["min"] = time["min"] + 1
- if time["min"] == 60:
- time["min"] = 0
- time["hour"] = time["hour"] + 1
- if time["hour"] == 24:
- time["hour"] = 0
-
- time_vector = dt.datetime(year, month, day, time["hour"], time["min"], time["sec"])
- timestr = time_vector.strftime("%Y%m%d_%H%M")
- if alt[i] > 0:
- if wallshadow == 1: # Include wall shadows (Issue #121)
- result = shadowing.calculate_shadows_wall_ht_25(
- azi[i],
- alt[i],
- scale,
- amaxvalue,
- dsm,
- vegdem,
- vegdem2,
- bush,
- wheight if wallshadow == 1 else np.zeros((dsm_height, dsm_width)),
- waspect * np.pi / 180.0 if wallshadow == 1 else np.zeros((dsm_height, dsm_width)),
- None,
- None,
- None,
- )
- sh = result.bldg_sh - (1 - result.veg_sh) * (1 - psi)
- if onetime == 0:
- filenamewallshve = folder + "/facade_shdw_veg/facade_shdw_veg_" + timestr + "_LST.tif"
- common.save_raster(filenamewallshve, result.wall_sh_veg, dsm_transf, dsm_crs)
- if onetime == 0:
- filename = folder + "/shadow_ground/shadow_ground_" + timestr + "_LST.tif"
- common.save_raster(filename, sh, dsm_transf, dsm_crs)
- filenamewallsh = folder + "/facade_shdw_bldgs/facade_shdw_bldgs_" + timestr + "_LST.tif"
- common.save_raster(filenamewallsh, result.wall_sh, dsm_transf, dsm_crs)
- else:
- result = shadowing.calculate_shadows_wall_ht_25(
- azi[i],
- alt[i],
- scale,
- amaxvalue,
- dsm,
- vegdem,
- vegdem2,
- bush,
- np.zeros((dsm_height, dsm_width)),
- np.zeros((dsm_height, dsm_width)),
- None,
- None,
- None,
- )
- sh = result.bldg_sh - (1 - result.veg_sh) * (1 - psi)
- if onetime == 0:
- filename = folder + "/Shadow_" + timestr + "_LST.tif"
- common.save_raster(filename, sh, dsm_transf, dsm_crs)
-
- shtot = shtot + sh
- index += 1
-
- shfinal = shtot / index
-
- if wallshadow == 1:
- if onetime == 1:
- filenamewallsh = folder + "/facade_shdw_bldgs/facade_shdw_bldgs_" + timestr + "_LST.tif"
- common.save_raster(filenamewallsh, result.wall_sh, dsm_transf, dsm_crs)
- filenamewallshve = folder + "/facade_shdw_veg/facade_shdw_veg_" + timestr + "_LST.tif"
- common.save_raster(filenamewallshve, result.wall_sh_veg, dsm_transf, dsm_crs)
-
- shadowresult = {"shfinal": shfinal, "time_vector": time_vector}
-
- return shadowresult
-
-
-def day_of_year(yy, month, day):
- if (yy % 4) == 0:
- if (yy % 100) == 0:
- if (yy % 400) == 0:
- leapyear = 1
- else:
- leapyear = 0
- else:
- leapyear = 1
- else:
- leapyear = 0
-
- if leapyear == 1:
- dayspermonth = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
- else:
- dayspermonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
-
- doy = np.sum(dayspermonth[0 : month - 1]) + day
-
- return doy
-
-
-def dectime_to_timevec(dectime):
- # This subroutine converts dectime to individual hours, minutes and seconds
-
- doy = np.floor(dectime)
-
- DH = dectime - doy
- HOURS = int(24 * DH)
-
- DM = 24 * DH - HOURS
- MINS = int(60 * DM)
-
- DS = 60 * DM - MINS
- SECS = int(60 * DS)
-
- return (HOURS, MINS, SECS)
diff --git a/pysrc/umepr/functions/solweig.py b/pysrc/umepr/functions/solweig.py
deleted file mode 100644
index 25b02d0..0000000
--- a/pysrc/umepr/functions/solweig.py
+++ /dev/null
@@ -1,883 +0,0 @@
-"""
-Solweig model in Python which calls shadowing and GVF calculations implemented in Rust.
-
-Implemented from SolweigRunRust class, which inherits from SolweigRunCore.
-
-This version is a copy except for the changes made to call the Rust functions directly.
-"""
-
-from copy import deepcopy
-
-import numpy as np
-from umep.functions.SOLWEIGpython.cylindric_wedge import cylindric_wedge
-from umep.functions.SOLWEIGpython.daylen import daylen
-from umep.functions.SOLWEIGpython.Kup_veg_2015a import Kup_veg_2015a
-
-# Anisotropic longwave
-from umep.functions.SOLWEIGpython.patch_radiation import patch_steradians
-from umep.functions.SOLWEIGpython.TsWaveDelay_2015a import TsWaveDelay_2015a
-
-# Wall surface temperature scheme
-from umep.functions.SOLWEIGpython.wall_surface_temperature import wall_surface_temperature
-from umep.util.SEBESOLWEIGCommonFiles.clearnessindex_2013b import clearnessindex_2013b
-from umep.util.SEBESOLWEIGCommonFiles.create_patches import create_patches
-from umep.util.SEBESOLWEIGCommonFiles.diffusefraction import diffusefraction
-from umep.util.SEBESOLWEIGCommonFiles.Perez_v3 import Perez_v3
-
-from ..rustalgos import gvf, shadowing, sky, vegetation
-
-
-def Solweig_2025a_calc(
- i,
- dsm,
- scale,
- rows,
- cols,
- svf,
- svfN,
- svfW,
- svfE,
- svfS,
- svfveg,
- svfNveg,
- svfEveg,
- svfSveg,
- svfWveg,
- svfaveg,
- svfEaveg,
- svfSaveg,
- svfWaveg,
- svfNaveg,
- vegdem,
- vegdem2,
- albedo_b,
- absK,
- absL,
- ewall,
- Fside,
- Fup,
- Fcyl,
- altitude,
- azimuth,
- zen,
- jday,
- usevegdem,
- onlyglobal,
- buildings,
- location,
- psi,
- landcover,
- lc_grid,
- dectime,
- altmax,
- dirwalls,
- walls,
- cyl,
- elvis,
- Ta,
- RH,
- radG,
- radD,
- radI,
- P,
- amaxvalue,
- bush,
- Twater,
- TgK,
- Tstart,
- alb_grid,
- emis_grid,
- TgK_wall,
- Tstart_wall,
- TmaxLST,
- TmaxLST_wall,
- first,
- second,
- svfalfa,
- svfbuveg,
- firstdaytime,
- timeadd,
- timestepdec,
- Tgmap1,
- Tgmap1E,
- Tgmap1S,
- Tgmap1W,
- Tgmap1N,
- CI,
- TgOut1,
- diffsh,
- shmat,
- vegshmat,
- vbshvegshmat,
- anisotropic_sky,
- asvf,
- patch_option,
- voxelMaps,
- voxelTable,
- ws,
- wallScheme,
- timeStep,
- steradians,
- walls_scheme,
- dirwalls_scheme,
-):
- # def Solweig_2021a_calc(i, dsm, scale, rows, cols, svf, svfN, svfW, svfE, svfS, svfveg, svfNveg, svfEveg, svfSveg,
- # svfWveg, svfaveg, svfEaveg, svfSaveg, svfWaveg, svfNaveg, vegdem, vegdem2, albedo_b, absK, absL,
- # ewall, Fside, Fup, Fcyl, altitude, azimuth, zen, jday, usevegdem, onlyglobal, buildings, location, psi,
- # landcover, lc_grid, dectime, altmax, dirwalls, walls, cyl, elvis, Ta, RH, radG, radD, radI, P,
- # amaxvalue, bush, Twater, TgK, Tstart, alb_grid, emis_grid, TgK_wall, Tstart_wall, TmaxLST,
- # TmaxLST_wall, first, second, svfalfa, svfbuveg, firstdaytime, timeadd, timestepdec, Tgmap1,
- # Tgmap1E, Tgmap1S, Tgmap1W, Tgmap1N, CI, TgOut1, diffsh, ani):
-
- # This is the core function of the SOLWEIG model
- # 2016-Aug-28
- # Fredrik Lindberg, fredrikl@gvc.gu.se
- # Goteborg Urban Climate Group
- # Gothenburg University
- #
- # Input variables:
- # dsm = digital surface model
- # scale = height to pixel size (2m pixel gives scale = 0.5)
- # svf,svfN,svfW,svfE,svfS = SVFs for building and ground
- # svfveg,svfNveg,svfEveg,svfSveg,svfWveg = Veg SVFs blocking sky
- # svfaveg,svfEaveg,svfSaveg,svfWaveg,svfNaveg = Veg SVFs blocking buildings
- # vegdem = Vegetation canopy DSM
- # vegdem2 = Vegetation trunk zone DSM
- # albedo_b = building wall albedo
- # absK = human absorption coefficient for shortwave radiation
- # absL = human absorption coefficient for longwave radiation
- # ewall = Emissivity of building walls
- # Fside = The angular factors between a person and the surrounding surfaces
- # Fup = The angular factors between a person and the surrounding surfaces
- # Fcyl = The angular factors between a culidric person and the surrounding surfaces
- # altitude = Sun altitude (degree)
- # azimuth = Sun azimuth (degree)
- # zen = Sun zenith angle (radians)
- # jday = day of year
- # usevegdem = use vegetation scheme
- # onlyglobal = calculate dir and diff from global shortwave (Reindl et al. 1990)
- # buildings = Boolena grid to identify building pixels
- # location = geographic location
- # height = height of measurements point (center of gravity of human)
- # psi = 1 - Transmissivity of shortwave through vegetation
- # landcover = use landcover scheme !!!NEW IN 2015a!!!
- # lc_grid = grid with landcoverclasses
- # lc_class = table with landcover properties
- # dectime = decimal time
- # altmax = maximum sun altitude
- # dirwalls = aspect of walls
- # walls = one pixel row outside building footprint. height of building walls
- # cyl = consider man as cylinder instead of cude
- # elvis = dummy
- # Ta = air temp
- # RH
- # radG = global radiation
- # radD = diffuse
- # radI = direct
- # P = pressure
- # amaxvalue = max height of buildings
- # bush = grid representing bushes
- # Twater = temperature of water (daily)
- # TgK, Tstart, TgK_wall, Tstart_wall, TmaxLST,TmaxLST_wall,
- # alb_grid, emis_grid = albedo and emmissivity on ground
- # first, second = conneted to old Ts model (source area based on Smidt et al.)
- # svfalfa = SVF recalculated to angle
- # svfbuveg = complete SVF
- # firstdaytime, timeadd, timestepdec, Tgmap1, Tgmap1E, Tgmap1S, Tgmap1W, Tgmap1N,
- # CI = Clearness index
- # TgOut1 = old Ts model
- # diffsh, ani = Used in anisotrpic models (Wallenberg et al. 2019, 2022)
-
- # # # Core program start # # #
-
- # Optimization: Crop to valid region to avoid needless computation on NaN boundaries
- valid_mask = ~(np.isnan(dsm) | np.isnan(svf))
-
- if not np.any(valid_mask):
- # Return all NaN arrays if no valid pixels
- nan_array = np.full((rows, cols), np.nan)
- return (
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- np.nan,
- np.nan,
- 0,
- CI,
- nan_array.copy(),
- firstdaytime,
- timestepdec,
- timeadd,
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- TgOut1,
- nan_array.copy(),
- radI,
- radD,
- nan_array.copy(),
- None,
- CI,
- CI,
- nan_array.copy(),
- nan_array.copy(),
- nan_array.copy(),
- steradians,
- voxelTable,
- )
-
- rows_valid = np.any(valid_mask, axis=1)
- cols_valid = np.any(valid_mask, axis=0)
- rmin, rmax = np.where(rows_valid)[0][[0, -1]]
- cmin, cmax = np.where(cols_valid)[0][[0, -1]]
- rmax += 1
- cmax += 1
-
- orig_rows, orig_cols = rows, cols
- is_cropped = (rmin > 0) or (rmax < rows) or (cmin > 0) or (cmax < cols)
-
- if is_cropped:
- sl = (slice(rmin, rmax), slice(cmin, cmax))
- rows = rmax - rmin
- cols = cmax - cmin
-
- # Crop inputs
- dsm = dsm[sl]
- svf = svf[sl]
- svfN = svfN[sl]
- svfW = svfW[sl]
- svfE = svfE[sl]
- svfS = svfS[sl]
- svfveg = svfveg[sl]
- svfNveg = svfNveg[sl]
- svfEveg = svfEveg[sl]
- svfSveg = svfSveg[sl]
- svfWveg = svfWveg[sl]
- svfaveg = svfaveg[sl]
- svfEaveg = svfEaveg[sl]
- svfSaveg = svfSaveg[sl]
- svfWaveg = svfWaveg[sl]
- svfNaveg = svfNaveg[sl]
- vegdem = vegdem[sl]
- vegdem2 = vegdem2[sl]
- buildings = buildings[sl]
- if lc_grid is not None:
- lc_grid = lc_grid[sl]
- dirwalls = dirwalls[sl]
- walls = walls[sl]
- bush = bush[sl]
- alb_grid = alb_grid[sl]
- emis_grid = emis_grid[sl]
- TgK = TgK[sl]
- Tstart = Tstart[sl]
- TmaxLST = TmaxLST[sl]
- # Note: TgK_wall, Tstart_wall, TmaxLST_wall are scalars, not arrays
- svfalfa = svfalfa[sl]
- svfbuveg = svfbuveg[sl]
- Tgmap1 = Tgmap1[sl]
- Tgmap1E = Tgmap1E[sl]
- Tgmap1S = Tgmap1S[sl]
- Tgmap1W = Tgmap1W[sl]
- Tgmap1N = Tgmap1N[sl]
- if np.ndim(TgOut1) >= 2:
- TgOut1 = TgOut1[sl]
- if diffsh is not None:
- diffsh = diffsh[sl]
- if shmat is not None:
- shmat = shmat[sl]
- if vegshmat is not None:
- vegshmat = vegshmat[sl]
- if vbshvegshmat is not None:
- vbshvegshmat = vbshvegshmat[sl]
- asvf = asvf[sl]
- if voxelMaps is not None:
- voxelMaps = voxelMaps[sl]
- if voxelTable is not None:
- voxelTable = voxelTable[sl]
- walls_scheme = walls_scheme[sl]
- dirwalls_scheme = dirwalls_scheme[sl]
-
- # Instrument offset in degrees
- t = 0.0
-
- # Stefan Bolzmans Constant
- SBC = 5.67051e-8
-
- # Degrees to radians
- deg2rad = np.pi / 180
-
- # Find sunrise decimal hour - new from 2014a
- _, _, _, SNUP = daylen(jday, location["latitude"])
-
- # Vapor pressure
- ea = 6.107 * 10 ** ((7.5 * Ta) / (237.3 + Ta)) * (RH / 100.0)
-
- # Determination of clear - sky emissivity from Prata (1996)
- msteg = 46.5 * (ea / (Ta + 273.15))
- esky = (1 - (1 + msteg) * np.exp(-((1.2 + 3.0 * msteg) ** 0.5))) + elvis # -0.04 old error from Jonsson et al.2006
-
- if altitude > 0: # # # # # # DAYTIME # # # # # #
- # Clearness Index on Earth's surface after Crawford and Dunchon (1999) with a correction
- # factor for low sun elevations after Lindberg et al.(2008)
- I0, CI, Kt, I0et, CIuncorr = clearnessindex_2013b(zen, jday, Ta, RH / 100.0, radG, location, P)
- if (CI > 1) or (np.inf == CI):
- CI = 1
-
- # Estimation of radD and radI if not measured after Reindl et al.(1990)
- if onlyglobal == 1:
- I0, CI, Kt, I0et, CIuncorr = clearnessindex_2013b(zen, jday, Ta, RH / 100.0, radG, location, P)
- if (CI > 1) or (np.inf == CI):
- CI = 1
-
- radI, radD = diffusefraction(radG, altitude, Kt, Ta, RH)
-
- # Diffuse Radiation
- # Anisotropic Diffuse Radiation after Perez et al. 1993
- if anisotropic_sky == 1:
- patchchoice = 1
- zenDeg = zen * (180 / np.pi)
- # Relative luminance
- lv, pc_, pb_ = Perez_v3(zenDeg, azimuth, radD, radI, jday, patchchoice, patch_option)
- # Total relative luminance from sky, i.e. from each patch, into each cell
- aniLum = np.zeros((rows, cols))
- for idx in range(lv.shape[0]):
- aniLum += diffsh[:, :, idx] * lv[idx, 2]
-
- dRad = aniLum * radD # Total diffuse radiation from sky into each cell
- else:
- dRad = radD * svfbuveg
- patchchoice = 1
- lv = None
-
- # Shadow images
- if usevegdem == 1:
- result = shadowing.calculate_shadows_wall_ht_25(
- azimuth,
- altitude,
- scale,
- amaxvalue,
- dsm.astype(np.float32),
- vegdem.astype(np.float32),
- vegdem2.astype(np.float32),
- bush.astype(np.float32),
- walls.astype(np.float32),
- (dirwalls * np.pi / 180.0).astype(np.float32),
- walls_scheme.astype(np.float32),
- (dirwalls_scheme * np.pi / 180.0).astype(np.float32),
- None,
- )
- vegsh = result.veg_sh
- sh = result.bldg_sh
- wallsh = result.wall_sh
- wallsun = result.wall_sun
- wallshve = result.wall_sh_veg
- facesun = result.face_sun
- wallsh_ = result.face_sh
- shadow = result.bldg_sh - (1 - result.veg_sh) * (1 - psi)
- else:
- result = shadowing.calculate_shadows_wall_ht_25(
- azimuth,
- altitude,
- scale,
- dsm.astype(np.float32),
- None,
- None,
- None,
- walls.astype(np.float32),
- (dirwalls * np.pi / 180.0).astype(np.float32),
- None,
- None,
- None,
- )
- sh = result.bldg_sh
- wallsh = result.wall_sh
- wallsun = result.wall_sun
- facesh = result.face_sh
- facesun = result.face_sun
- shadow = result.bldg_sh
-
- # # # Surface temperature parameterisation during daytime # # # #
- # new using max sun alt.instead of dfm
- # Tgamp = (TgK * altmax - Tstart) + Tstart # Old
- Tgamp = TgK * altmax + Tstart # Fixed 2021
- # Tgampwall = (TgK_wall * altmax - (Tstart_wall)) + (Tstart_wall) # Old
- Tgampwall = TgK_wall * altmax + Tstart_wall
- Tg = Tgamp * np.sin(
- (((dectime - np.floor(dectime)) - SNUP / 24) / (TmaxLST / 24 - SNUP / 24)) * np.pi / 2
- ) # 2015 a, based on max sun altitude
- Tgwall = Tgampwall * np.sin(
- (((dectime - np.floor(dectime)) - SNUP / 24) / (TmaxLST_wall / 24 - SNUP / 24)) * np.pi / 2
- ) # 2015a, based on max sun altitude
-
- if Tgwall < 0: # temporary for removing low Tg during morning 20130205
- # Tg = 0
- Tgwall = 0
-
- # New estimation of Tg reduction for non - clear situation based on Reindl et al.1990
- radI0, _ = diffusefraction(I0, altitude, 1.0, Ta, RH)
- corr = 0.1473 * np.log(90 - (zen / np.pi * 180)) + 0.3454 # 20070329 correction of lat, Lindberg et al. 2008
- CI_Tg = (radG / radI0) + (1 - corr)
- if (CI_Tg > 1) or (CI_Tg == np.inf):
- CI_Tg = 1
-
- radG0 = radI0 * (np.sin(altitude * deg2rad)) + _
- CI_TgG = (radG / radG0) + (1 - corr)
- if (CI_TgG > 1) or (CI_TgG == np.inf):
- CI_TgG = 1
-
- # Tg = Tg * CI_Tg # new estimation
- # Tgwall = Tgwall * CI_Tg
- Tg = Tg * CI_TgG # new estimation
- Tgwall = Tgwall * CI_TgG
- if landcover == 1:
- Tg[Tg < 0] = 0 # temporary for removing low Tg during morning 20130205
-
- # # # # Ground View Factors # # # #
- gvf_result = gvf.gvf_calc(
- wallsun.astype(np.float32),
- walls.astype(np.float32),
- buildings.astype(np.float32),
- scale,
- shadow.astype(np.float32),
- first,
- second,
- dirwalls.astype(np.float32),
- Tg.astype(np.float32),
- Tgwall,
- Ta,
- emis_grid.astype(np.float32),
- ewall,
- alb_grid.astype(np.float32),
- SBC,
- albedo_b,
- Twater,
- lc_grid.astype(np.float32) if lc_grid is not None else None,
- landcover,
- )
-
- # # # # Lup, daytime # # # #
- # Surface temperature wave delay - new as from 2014a
- Lup, timeaddnotused, Tgmap1 = TsWaveDelay_2015a(gvf_result.gvf_lup, firstdaytime, timeadd, timestepdec, Tgmap1)
- LupE, timeaddnotused, Tgmap1E = TsWaveDelay_2015a(
- gvf_result.gvf_lup_e, firstdaytime, timeadd, timestepdec, Tgmap1E
- )
- LupS, timeaddnotused, Tgmap1S = TsWaveDelay_2015a(
- gvf_result.gvf_lup_s, firstdaytime, timeadd, timestepdec, Tgmap1S
- )
- LupW, timeaddnotused, Tgmap1W = TsWaveDelay_2015a(
- gvf_result.gvf_lup_w, firstdaytime, timeadd, timestepdec, Tgmap1W
- )
- LupN, timeaddnotused, Tgmap1N = TsWaveDelay_2015a(
- gvf_result.gvf_lup_n, firstdaytime, timeadd, timestepdec, Tgmap1N
- )
-
- # # For Tg output in POIs
- TgTemp = Tg * shadow + Ta
- TgOut, timeadd, TgOut1 = TsWaveDelay_2015a(
- TgTemp, firstdaytime, timeadd, timestepdec, TgOut1
- ) # timeadd only here v2021a
-
- # Building height angle from svf
- F_sh = cylindric_wedge(zen, svfalfa, rows, cols) # Fraction shadow on building walls based on sun alt and svf
- F_sh[np.isnan(F_sh)] = 0.5
-
- # # # # # # # Calculation of shortwave daytime radiative fluxes # # # # # # #
- Kdown = (
- radI * shadow * np.sin(altitude * (np.pi / 180))
- + dRad
- + albedo_b * (1 - svfbuveg) * (radG * (1 - F_sh) + radD * F_sh)
- ) # *sin(altitude(i) * (pi / 180))
-
- Kup, KupE, KupS, KupW, KupN = Kup_veg_2015a(
- radI,
- radD,
- radG,
- altitude,
- svfbuveg,
- albedo_b,
- F_sh,
- gvf_result.gvfalb,
- gvf_result.gvfalb_e,
- gvf_result.gvfalb_s,
- gvf_result.gvfalb_w,
- gvf_result.gvfalb_n,
- gvf_result.gvfalbnosh,
- gvf_result.gvfalbnosh_e,
- gvf_result.gvfalbnosh_s,
- gvf_result.gvfalbnosh_w,
- gvf_result.gvfalbnosh_n,
- )
-
- kside_result = vegetation.kside_veg(
- radI,
- radD,
- radG,
- shadow.astype(np.float32),
- svfS,
- svfW,
- svfN,
- svfE,
- svfEveg,
- svfSveg,
- svfWveg,
- svfNveg,
- azimuth,
- altitude,
- psi,
- t,
- albedo_b,
- F_sh.astype(np.float32),
- KupE.astype(np.float32),
- KupS.astype(np.float32),
- KupW.astype(np.float32),
- KupN.astype(np.float32),
- bool(cyl),
- lv.astype(np.float32) if lv is not None else None,
- bool(anisotropic_sky),
- diffsh,
- asvf,
- shmat,
- vegshmat,
- vbshvegshmat,
- )
- Keast = kside_result.keast
- Ksouth = kside_result.ksouth
- Kwest = kside_result.kwest
- Knorth = kside_result.knorth
- KsideI = kside_result.kside_i
- KsideD = kside_result.kside_d
- Kside = kside_result.kside
-
- firstdaytime = 0
-
- else: # # # # # # # NIGHTTIME # # # # # # # #
- Tgwall = 0
- # CI_Tg = -999 # F_sh = []
-
- # Nocturnal K fluxes set to 0
- Knight = np.zeros((rows, cols))
- Kdown = np.zeros((rows, cols))
- Kwest = np.zeros((rows, cols))
- Kup = np.zeros((rows, cols))
- Keast = np.zeros((rows, cols))
- Ksouth = np.zeros((rows, cols))
- Knorth = np.zeros((rows, cols))
- KsideI = np.zeros((rows, cols))
- KsideD = np.zeros((rows, cols))
- F_sh = np.zeros((rows, cols))
- Tg = np.zeros((rows, cols))
- shadow = np.zeros((rows, cols))
- CI_Tg = deepcopy(CI)
- CI_TgG = deepcopy(CI)
- dRad = np.zeros((rows, cols))
- Kside = np.zeros((rows, cols))
-
- # # # # Lup # # # #
- Lup = SBC * emis_grid * ((Knight + Ta + Tg + 273.15) ** 4)
- if landcover == 1:
- Lup[lc_grid == 3] = SBC * 0.98 * (Twater + 273.15) ** 4 # nocturnal Water temp
-
- LupE = Lup
- LupS = Lup
- LupW = Lup
- LupN = Lup
-
- # # For Tg output in POIs
- TgOut = Ta + Tg
-
- I0 = 0
- timeadd = 0
- firstdaytime = 1
-
- # # # # Ldown # # # #
- Ldown = (
- (svf + svfveg - 1) * esky * SBC * ((Ta + 273.15) ** 4)
- + (2 - svfveg - svfaveg) * ewall * SBC * ((Ta + 273.15) ** 4)
- + (svfaveg - svf) * ewall * SBC * ((Ta + 273.15 + Tgwall) ** 4)
- + (2 - svf - svfveg) * (1 - ewall) * esky * SBC * ((Ta + 273.15) ** 4)
- ) # Jonsson et al.(2006)
- # Ldown = Ldown - 25 # Shown by Jonsson et al.(2006) and Duarte et al.(2006)
-
- if CI < 0.95: # non - clear conditions
- c = 1 - CI
- Ldown = Ldown * (1 - c) + c * (
- (svf + svfveg - 1) * SBC * ((Ta + 273.15) ** 4)
- + (2 - svfveg - svfaveg) * ewall * SBC * ((Ta + 273.15) ** 4)
- + (svfaveg - svf) * ewall * SBC * ((Ta + 273.15 + Tgwall) ** 4)
- + (2 - svf - svfveg) * (1 - ewall) * SBC * ((Ta + 273.15) ** 4)
- ) # NOT REALLY TESTED!!! BUT MORE CORRECT?
-
- # # # # Lside # # # #
- lside_veg_result = vegetation.lside_veg(
- svfS,
- svfW,
- svfN,
- svfE,
- svfEveg,
- svfSveg,
- svfWveg,
- svfNveg,
- svfEaveg,
- svfSaveg,
- svfWaveg,
- svfNaveg,
- azimuth,
- altitude,
- Ta,
- Tgwall,
- SBC,
- ewall,
- Ldown.astype(np.float32),
- esky,
- t,
- F_sh.astype(np.float32),
- CI,
- LupE.astype(np.float32),
- LupS.astype(np.float32),
- LupW.astype(np.float32),
- LupN.astype(np.float32),
- bool(anisotropic_sky),
- )
- Least = lside_veg_result.least
- Lsouth = lside_veg_result.lsouth
- Lwest = lside_veg_result.lwest
- Lnorth = lside_veg_result.lnorth
-
- # New parameterization scheme for wall temperatures
- if wallScheme == 1:
- # albedo_g = 0.15 #TODO Change to correct
- if altitude < 0:
- wallsh_ = 0
- voxelTable = wall_surface_temperature(
- voxelTable, wallsh_, altitude, azimuth, timeStep, radI, radD, radG, Ldown, Lup, Ta, esky
- )
- # Anisotropic sky
- if anisotropic_sky == 1:
- if "lv" not in locals():
- # Creating skyvault of patches of constant radians (Tregeneza and Sharples, 1993)
- skyvaultalt, skyvaultazi, _, _, _, _, _ = create_patches(patch_option)
-
- patch_emissivities = np.zeros(skyvaultalt.shape[0])
-
- x = np.transpose(np.atleast_2d(skyvaultalt))
- y = np.transpose(np.atleast_2d(skyvaultazi))
- z = np.transpose(np.atleast_2d(patch_emissivities))
-
- L_patches = np.append(np.append(x, y, axis=1), z, axis=1)
-
- else:
- L_patches = deepcopy(lv)
-
- # Calculate steradians for patches if it is the first model iteration
- if i == 0:
- steradians, skyalt, patch_altitude = patch_steradians(L_patches)
-
- # Create lv from L_patches if nighttime, i.e. lv does not exist
- if altitude < 0:
- # CI = deepcopy(CI)
- lv = deepcopy(L_patches)
- KupE = np.zeros_like(lv)
- KupS = np.zeros_like(lv)
- KupW = np.zeros_like(lv)
- KupN = np.zeros_like(lv)
-
- # Adjust sky emissivity under semi-cloudy/hazy/cloudy/overcast conditions, i.e. CI lower than 0.95
- if CI < 0.95:
- esky_c = CI * esky + (1 - CI) * 1.0
- esky = esky_c
-
- ani_sky_result = sky.anisotropic_sky(
- shmat,
- vegshmat,
- vbshvegshmat,
- altitude,
- azimuth,
- asvf,
- bool(cyl),
- esky,
- L_patches.astype(np.float32),
- bool(wallScheme),
- voxelTable.astype(np.float32) if voxelTable is not None else None,
- voxelMaps.astype(np.float32) if voxelMaps is not None else None,
- steradians.astype(np.float32),
- Ta,
- Tgwall,
- ewall,
- Lup.astype(np.float32),
- radI,
- radD,
- radG,
- lv.astype(np.float32),
- albedo_b,
- False,
- diffsh,
- shadow.astype(np.float32),
- KupE.astype(np.float32),
- KupS.astype(np.float32),
- KupW.astype(np.float32),
- KupN.astype(np.float32),
- i,
- )
- Ldown = ani_sky_result.ldown
- Lside = ani_sky_result.lside
- Lside_sky = ani_sky_result.lside_sky
- Lside_veg = ani_sky_result.lside_veg
- Lside_sh = ani_sky_result.lside_sh
- Lside_sun = ani_sky_result.lside_sun
- Lside_ref = ani_sky_result.lside_ref
- Least_ = ani_sky_result.least
- Lwest_ = ani_sky_result.lwest
- Lnorth_ = ani_sky_result.lnorth
- Lsouth_ = ani_sky_result.lsouth
- Keast = ani_sky_result.keast
- Ksouth = ani_sky_result.ksouth
- Kwest = ani_sky_result.kwest
- Knorth = ani_sky_result.knorth
- KsideI = ani_sky_result.kside_i
- KsideD = ani_sky_result.kside_d
- Kside = ani_sky_result.kside
- steradians = ani_sky_result.steradians
- skyalt = ani_sky_result.skyalt
- else:
- Lside = np.zeros((rows, cols))
- L_patches = None
-
- # Box and anisotropic longwave
- if cyl == 0 and anisotropic_sky == 1:
- Least += Least_
- Lwest += Lwest_
- Lnorth += Lnorth_
- Lsouth += Lsouth_
-
- # # # # Calculation of radiant flux density and Tmrt # # # #
- # Human body considered as a cylinder with isotropic all-sky diffuse
- if cyl == 1 and anisotropic_sky == 0:
- Sstr = absK * (KsideI * Fcyl + (Kdown + Kup) * Fup + (Knorth + Keast + Ksouth + Kwest) * Fside) + absL * (
- (Ldown + Lup) * Fup + (Lnorth + Least + Lsouth + Lwest) * Fside
- )
- # Human body considered as a cylinder with Perez et al. (1993) (anisotropic sky diffuse)
- # and Martin and Berdahl (1984) (anisotropic sky longwave)
- elif cyl == 1 and anisotropic_sky == 1:
- Sstr = absK * (Kside * Fcyl + (Kdown + Kup) * Fup + (Knorth + Keast + Ksouth + Kwest) * Fside) + absL * (
- (Ldown + Lup) * Fup + Lside * Fcyl + (Lnorth + Least + Lsouth + Lwest) * Fside
- )
- # Knorth = nan Ksouth = nan Kwest = nan Keast = nan
- else: # Human body considered as a standing cube
- Sstr = absK * ((Kdown + Kup) * Fup + (Knorth + Keast + Ksouth + Kwest) * Fside) + absL * (
- (Ldown + Lup) * Fup + (Lnorth + Least + Lsouth + Lwest) * Fside
- )
-
- Tmrt = np.sqrt(np.sqrt(Sstr / (absL * SBC))) - 273.2
-
- # Add longwave to cardinal directions for output in POI
- if (cyl == 1) and (anisotropic_sky == 1):
- Least += Least_
- Lwest += Lwest_
- Lnorth += Lnorth_
- Lsouth += Lsouth_
-
- if is_cropped:
-
- def uncrop(arr):
- if arr is None:
- return None
- if np.isscalar(arr):
- return arr
- arr = np.asarray(arr)
- if arr.ndim < 2:
- return arr
- # Check if it matches the cropped shape (rows, cols)
- if arr.shape[0] != rows or arr.shape[1] != cols:
- return arr
-
- new_shape = (orig_rows, orig_cols) + arr.shape[2:]
- full = np.full(new_shape, np.nan, dtype=arr.dtype)
- full[sl] = arr
- return full
-
- Tmrt = uncrop(Tmrt)
- Kdown = uncrop(Kdown)
- Kup = uncrop(Kup)
- Ldown = uncrop(Ldown)
- Lup = uncrop(Lup)
- Tg = uncrop(Tg)
- shadow = uncrop(shadow)
- Tgmap1 = uncrop(Tgmap1)
- Tgmap1E = uncrop(Tgmap1E)
- Tgmap1S = uncrop(Tgmap1S)
- Tgmap1W = uncrop(Tgmap1W)
- Tgmap1N = uncrop(Tgmap1N)
- Keast = uncrop(Keast)
- Ksouth = uncrop(Ksouth)
- Kwest = uncrop(Kwest)
- Knorth = uncrop(Knorth)
- Least = uncrop(Least)
- Lsouth = uncrop(Lsouth)
- Lwest = uncrop(Lwest)
- Lnorth = uncrop(Lnorth)
- KsideI = uncrop(KsideI)
- TgOut1 = uncrop(TgOut1)
- TgOut = uncrop(TgOut)
- Lside = uncrop(Lside)
- KsideD = uncrop(KsideD)
- dRad = uncrop(dRad)
- Kside = uncrop(Kside)
- voxelTable = uncrop(voxelTable)
-
- return (
- Tmrt,
- Kdown,
- Kup,
- Ldown,
- Lup,
- Tg,
- ea,
- esky,
- I0,
- CI,
- shadow,
- firstdaytime,
- timestepdec,
- timeadd,
- Tgmap1,
- Tgmap1E,
- Tgmap1S,
- Tgmap1W,
- Tgmap1N,
- Keast,
- Ksouth,
- Kwest,
- Knorth,
- Least,
- Lsouth,
- Lwest,
- Lnorth,
- KsideI,
- TgOut1,
- TgOut,
- radI,
- radD,
- Lside,
- L_patches,
- CI_Tg,
- CI_TgG,
- KsideD,
- dRad,
- Kside,
- steradians,
- voxelTable,
- )
diff --git a/pysrc/umepr/hybrid/svf.py b/pysrc/umepr/hybrid/svf.py
deleted file mode 100644
index 9aa5f61..0000000
--- a/pysrc/umepr/hybrid/svf.py
+++ /dev/null
@@ -1,220 +0,0 @@
-"""
-SVF hybrid - Python implementation of the SVF algorithm which calls Rust for the shadowing calculations.
-
-NOTE: Used for testing.
-There is a full Rust implementation which should be used instead.
-"""
-
-import numpy as np
-from tqdm import tqdm
-from umep.util import shadowingfunctions as shadow
-from umep.util.SEBESOLWEIGCommonFiles.create_patches import create_patches
-
-from ..rustalgos import shadowing
-
-
-def annulus_weight(altitude, aziinterval):
- n = 90.0
- steprad = (360.0 / aziinterval) * (np.pi / 180.0)
- annulus = 91.0 - altitude
- w = (1.0 / (2.0 * np.pi)) * np.sin(np.pi / (2.0 * n)) * np.sin((np.pi * (2.0 * annulus - 1.0)) / (2.0 * n))
- weight = steprad * w
-
- return weight
-
-
-def svfForProcessing153_rust_shdw(dsm, vegdem, vegdem2, scale, usevegdem, amax):
- # setup
- rows = dsm.shape[0]
- cols = dsm.shape[1]
- svf = np.zeros([rows, cols], dtype=np.float32)
- svfE = np.zeros([rows, cols], dtype=np.float32)
- svfS = np.zeros([rows, cols], dtype=np.float32)
- svfW = np.zeros([rows, cols], dtype=np.float32)
- svfN = np.zeros([rows, cols], dtype=np.float32)
- svfveg = np.zeros((rows, cols), dtype=np.float32)
- svfEveg = np.zeros((rows, cols), dtype=np.float32)
- svfSveg = np.zeros((rows, cols), dtype=np.float32)
- svfWveg = np.zeros((rows, cols), dtype=np.float32)
- svfNveg = np.zeros((rows, cols), dtype=np.float32)
- svfaveg = np.zeros((rows, cols), dtype=np.float32)
- svfEaveg = np.zeros((rows, cols), dtype=np.float32)
- svfSaveg = np.zeros((rows, cols), dtype=np.float32)
- svfWaveg = np.zeros((rows, cols), dtype=np.float32)
- svfNaveg = np.zeros((rows, cols), dtype=np.float32)
-
- # % Elevation vegdems if buildingDSM inclused ground heights
- # vegdem = vegdem + dsm
- # vegdem[vegdem == dsm] = 0
- # vegdem2 = vegdem2 + dsm
- # vegdem2[vegdem2 == dsm] = 0
-
- # % Bush separation
- # bush = np.logical_not(vegdem2 * vegdem) * vegdem
- bush = np.copy(vegdem)
- bush[vegdem2 > 0] = 0.0
-
- index = 0
-
- # patch_option = 1 # 145 patches
- patch_option = 2 # 153 patches
- # patch_option = 3 # 306 patches
- # patch_option = 4 # 612 patches
-
- # Create patches based on patch_option
- (
- skyvaultalt,
- skyvaultazi,
- annulino,
- skyvaultaltint,
- aziinterval,
- skyvaultaziint,
- azistart,
- ) = create_patches(patch_option)
-
- skyvaultaziint = np.array([360 / patches for patches in aziinterval])
- iazimuth = np.hstack(np.zeros((1, np.sum(aziinterval)))) # Nils
-
- # float 32 for memory
- shmat = np.zeros((rows, cols, np.sum(aziinterval)), dtype=np.float32)
- vegshmat = np.zeros((rows, cols, np.sum(aziinterval)), dtype=np.float32)
- vbshvegshmat = np.zeros((rows, cols, np.sum(aziinterval)), dtype=np.float32)
-
- for j in range(0, skyvaultaltint.shape[0]):
- for k in range(0, int(360 / skyvaultaziint[j])):
- iazimuth[index] = k * skyvaultaziint[j] + azistart[j]
- if iazimuth[index] > 360.0:
- iazimuth[index] = iazimuth[index] - 360.0
- index = index + 1
-
- # NOTE: total for progress
- total = 0
- for i in range(0, skyvaultaltint.shape[0]):
- for j in np.arange(0, aziinterval[int(i)]):
- total += 1
- progress = tqdm(total=total)
- #
- aziintervalaniso = np.ceil(aziinterval / 2.0)
- index = 0
- for i in range(0, skyvaultaltint.shape[0]):
- for j in np.arange(0, aziinterval[int(i)]):
- altitude = skyvaultaltint[int(i)]
- azimuth = iazimuth[int(index)]
-
- # Casting shadow
- if usevegdem == 1:
- # numba doesn't seem to offer notable gains in this instance
- result = shadowing.calculate_shadows_wall_ht_25(
- azimuth,
- altitude,
- scale,
- amax,
- dsm,
- vegdem,
- vegdem2,
- bush,
- None,
- None,
- None,
- None,
- None,
- )
- vegsh = result.veg_sh
- vbshvegsh = result.veg_blocks_bldg_sh
- sh = result.bldg_sh
- vegshmat[:, :, index] = vegsh
- vbshvegshmat[:, :, index] = vbshvegsh
- else:
- sh = shadow.shadowingfunctionglobalradiation(dsm, azimuth, altitude, scale, 1)
- shmat[:, :, index] = sh
-
- # Calculate svfs
- for k in np.arange(annulino[int(i)] + 1, (annulino[int(i + 1.0)]) + 1):
- weight = annulus_weight(k, aziinterval[i]) * sh
- svf = svf + weight
- weight = annulus_weight(k, aziintervalaniso[i]) * sh
- if (azimuth >= 0) and (azimuth < 180):
- svfE = svfE + weight
- if (azimuth >= 90) and (azimuth < 270):
- svfS = svfS + weight
- if (azimuth >= 180) and (azimuth < 360):
- svfW = svfW + weight
- if (azimuth >= 270) or (azimuth < 90):
- svfN = svfN + weight
-
- if usevegdem == 1:
- for k in np.arange(annulino[int(i)] + 1, (annulino[int(i + 1.0)]) + 1):
- # % changed to include 90
- weight = annulus_weight(k, aziinterval[i])
- svfveg = svfveg + weight * vegsh
- svfaveg = svfaveg + weight * vbshvegsh
- weight = annulus_weight(k, aziintervalaniso[i])
- if (azimuth >= 0) and (azimuth < 180):
- svfEveg = svfEveg + weight * vegsh
- svfEaveg = svfEaveg + weight * vbshvegsh
- if (azimuth >= 90) and (azimuth < 270):
- svfSveg = svfSveg + weight * vegsh
- svfSaveg = svfSaveg + weight * vbshvegsh
- if (azimuth >= 180) and (azimuth < 360):
- svfWveg = svfWveg + weight * vegsh
- svfWaveg = svfWaveg + weight * vbshvegsh
- if (azimuth >= 270) or (azimuth < 90):
- svfNveg = svfNveg + weight * vegsh
- svfNaveg = svfNaveg + weight * vbshvegsh
-
- index += 1
-
- # track progress
- progress.update(1)
-
- svfS = svfS + 3.0459e-004
- svfW = svfW + 3.0459e-004
- # % Last azimuth is 90. Hence, manual add of last annuli for svfS and SVFW
- # %Forcing svf not be greater than 1 (some MATLAB crazyness)
- svf[(svf > 1.0)] = 1.0
- svfE[(svfE > 1.0)] = 1.0
- svfS[(svfS > 1.0)] = 1.0
- svfW[(svfW > 1.0)] = 1.0
- svfN[(svfN > 1.0)] = 1.0
-
- if usevegdem == 1:
- last = np.zeros((rows, cols))
- last[(vegdem2 == 0.0)] = 3.0459e-004
- svfSveg = svfSveg + last
- svfWveg = svfWveg + last
- svfSaveg = svfSaveg + last
- svfWaveg = svfWaveg + last
- # %Forcing svf not be greater than 1 (some MATLAB crazyness)
- svfveg[(svfveg > 1.0)] = 1.0
- svfEveg[(svfEveg > 1.0)] = 1.0
- svfSveg[(svfSveg > 1.0)] = 1.0
- svfWveg[(svfWveg > 1.0)] = 1.0
- svfNveg[(svfNveg > 1.0)] = 1.0
- svfaveg[(svfaveg > 1.0)] = 1.0
- svfEaveg[(svfEaveg > 1.0)] = 1.0
- svfSaveg[(svfSaveg > 1.0)] = 1.0
- svfWaveg[(svfWaveg > 1.0)] = 1.0
- svfNaveg[(svfNaveg > 1.0)] = 1.0
-
- svfresult = {
- "svf": svf,
- "svfE": svfE,
- "svfS": svfS,
- "svfW": svfW,
- "svfN": svfN,
- "svfveg": svfveg,
- "svfEveg": svfEveg,
- "svfSveg": svfSveg,
- "svfWveg": svfWveg,
- "svfNveg": svfNveg,
- "svfaveg": svfaveg,
- "svfEaveg": svfEaveg,
- "svfSaveg": svfSaveg,
- "svfWaveg": svfWaveg,
- "svfNaveg": svfNaveg,
- "shmat": shmat,
- "vegshmat": vegshmat,
- "vbshvegshmat": vbshvegshmat,
- }
-
- return svfresult
diff --git a/pysrc/umepr/shadows.py b/pysrc/umepr/shadows.py
deleted file mode 100644
index c23c55b..0000000
--- a/pysrc/umepr/shadows.py
+++ /dev/null
@@ -1,133 +0,0 @@
-"""
-Shadow wrapper for Python.
-
-daily_shading import internally calls the Rust implementation for shadow calculations.
-"""
-
-import datetime
-from pathlib import Path
-
-import pyproj
-from rasterio.transform import Affine, xy
-
-from umep import common
-from .functions import daily_shading as dsh
-
-
-def generate_shadows(
- dsm_path: str,
- shadow_date_Ymd: str, # %Y-%m-%d"
- wall_ht_path: str,
- wall_aspect_path: str,
- bbox: list[int, int, int, int],
- out_dir: str,
- shadow_time_HM: int | None = None, # "%H:%M"
- time_interval_M=30,
- veg_dsm_path: str | None = None,
- trans_veg: float = 3,
- trunk_zone_ht_perc: float = 0.25,
-):
- dsm, dsm_transf, dsm_crs, _dsm_nd = common.load_raster(dsm_path, bbox)
- dsm_height, dsm_width = dsm.shape # y rows by x cols
- dsm_scale = 1 / dsm_transf[1]
- # y is flipped - so return max for lower row
- minx, miny = xy(Affine.from_gdal(*dsm_transf), dsm.shape[0], 0)
- # Define the source and target CRS
- source_crs = pyproj.CRS(dsm_crs)
- target_crs = pyproj.CRS(4326) # WGS 84
- # Create a transformer object
- transformer = pyproj.Transformer.from_crs(source_crs, target_crs, always_xy=True)
- # Perform the transformation
- lon, lat = transformer.transform(minx, miny)
-
- # veg transmissivity as percentage
- if not trans_veg >= 0 and trans_veg <= 100:
- raise ValueError("Vegetation transmissivity should be a number between 0 and 100")
- trans = trans_veg / 100.0
-
- if veg_dsm_path is not None:
- usevegdem = 1
- veg_dsm, veg_dsm_transf, veg_dsm_crs, _veg_dsm_nd = common.load_raster(veg_dsm_path, bbox)
- veg_dsm_height, veg_dsm_width = veg_dsm.shape
- if not (veg_dsm_width == dsm_width) & (veg_dsm_height == dsm_height):
- raise ValueError("Error in Vegetation Canopy DSM: All rasters must be of same extent and resolution")
- trunkratio = trunk_zone_ht_perc / 100.0
- veg_dsm_2 = veg_dsm * trunkratio
- veg_dsm_2_height, veg_dsm_2_width = veg_dsm_2.shape
- if not (veg_dsm_2_width == dsm_width) & (veg_dsm_2_height == dsm_height):
- raise ValueError("Error in Trunk Zone DSM: All rasters must be of same extent and resolution")
- else:
- usevegdem = 0
- veg_dsm = 0
- veg_dsm_2 = 0
-
- if wall_aspect_path and wall_ht_path:
- print("Facade shadow scheme activated")
- wallsh = 1
- wh_rast, wh_transf, wh_crs, _wh_nd = common.load_raster(wall_ht_path, bbox)
- wh_height, wh_width = wh_rast.shape
- if not (wh_width == dsm_width) & (wh_height == dsm_height):
- raise ValueError("Error in Wall height raster: All rasters must be of same extent and resolution")
- wa_rast, wa_transf, wa_crs, _wa_nd = common.load_raster(wall_aspect_path, bbox)
- wa_height, wa_width = wa_rast.shape
- if not (wa_width == dsm_width) & (wa_height == dsm_height):
- raise ValueError("Error in Wall aspect raster: All rasters must be of same extent and resolution")
- else:
- wallsh = 0
- wh_rast = 0
- wa_height = 0
-
- dst = 0
- UTC = 0
- target_date = datetime.datetime.strptime(shadow_date_Ymd, "%Y-%m-%d").date()
- year = target_date.year
- month = target_date.month
- day = target_date.day
- if shadow_time_HM is not None:
- onetime = 1
- onetimetime = datetime.datetime.strptime(shadow_time_HM, "%H:%M")
- hour = onetimetime.hour
- minu = onetimetime.minute
- sec = onetimetime.second
- else:
- onetime = 0
- hour = 0
- minu = 0
- sec = 0
-
- tv = [year, month, day, hour, minu, sec]
-
- out_path = Path(out_dir)
- out_path.mkdir(parents=True, exist_ok=True)
- out_path_str = str(out_path)
-
- Path.mkdir(out_path / "facade_shdw_bldgs", parents=True, exist_ok=True)
- Path.mkdir(out_path / "facade_shdw_veg", parents=True, exist_ok=True)
- Path.mkdir(out_path / "shadow_ground", parents=True, exist_ok=True)
-
- shadowresult = dsh.daily_shading(
- dsm.astype("float32"),
- veg_dsm.astype("float32"),
- veg_dsm_2.astype("float32"),
- dsm_scale,
- lon,
- lat,
- dsm_width,
- dsm_height,
- tv,
- UTC,
- usevegdem,
- time_interval_M,
- onetime,
- out_path_str,
- dsm_transf,
- dsm_crs,
- trans,
- dst,
- wallsh,
- wh_rast.astype("float32"),
- wa_rast.astype("float32"),
- )
-
- shfinal = shadowresult["shfinal"]
- common.save_raster(out_path_str + "/shadow_composite.tif", shfinal, dsm_transf, dsm_crs)
diff --git a/pysrc/umepr/solweig_runner_rust.py b/pysrc/umepr/solweig_runner_rust.py
deleted file mode 100644
index 2971486..0000000
--- a/pysrc/umepr/solweig_runner_rust.py
+++ /dev/null
@@ -1,123 +0,0 @@
-"""
-Subclasses SolweigRunCore - swaps in solweig function which calls Rust implementations of shadowing and GVF calculations
-"""
-
-from typing import Any
-
-from umep.functions.SOLWEIGpython.solweig_runner_core import SolweigRunCore
-
-from .functions.solweig import Solweig_2025a_calc as Solweig_2025a_calc_hybrid
-
-
-class SolweigRunRust(SolweigRunCore):
- """Class to run the SOLWEIG algorithm with Rust optimisations."""
-
- def calc_solweig(
- self,
- iter: int,
- elvis: float,
- first: float,
- second: float,
- firstdaytime: float,
- timeadd: float,
- timestepdec: float,
- posture: Any,
- ):
- """
- Calculate SOLWEIG results for the given iteration.
- Uses variant with GVF and Shadows rust optimisations.
- """
- return Solweig_2025a_calc_hybrid( # type: ignore
- iter,
- self.raster_data.dsm,
- self.raster_data.scale,
- self.raster_data.rows,
- self.raster_data.cols,
- self.svf_data.svf,
- self.svf_data.svf_north,
- self.svf_data.svf_west,
- self.svf_data.svf_east,
- self.svf_data.svf_south,
- self.svf_data.svf_veg,
- self.svf_data.svf_veg_north,
- self.svf_data.svf_veg_east,
- self.svf_data.svf_veg_south,
- self.svf_data.svf_veg_west,
- self.svf_data.svf_veg_blocks_bldg_sh,
- self.svf_data.svf_veg_blocks_bldg_sh_east,
- self.svf_data.svf_veg_blocks_bldg_sh_south,
- self.svf_data.svf_veg_blocks_bldg_sh_west,
- self.svf_data.svf_veg_blocks_bldg_sh_north,
- self.raster_data.cdsm,
- self.raster_data.tdsm,
- self.params.Albedo.Effective.Value.Walls,
- self.params.Tmrt_params.Value.absK,
- self.params.Tmrt_params.Value.absL,
- self.params.Emissivity.Value.Walls,
- posture.Fside,
- posture.Fup,
- posture.Fcyl,
- self.environ_data.altitude[iter],
- self.environ_data.azimuth[iter],
- self.environ_data.zen[iter],
- self.environ_data.jday[iter],
- self.config.use_veg_dem,
- self.config.only_global,
- self.raster_data.buildings,
- self.location,
- self.environ_data.psi[iter],
- self.config.use_landcover,
- self.raster_data.lcgrid,
- self.environ_data.dectime[iter],
- self.environ_data.altmax[iter],
- self.raster_data.wallaspect,
- self.raster_data.wallheight,
- int(self.config.person_cylinder), # expects int though should work either way
- elvis,
- self.environ_data.Ta[iter],
- self.environ_data.RH[iter],
- self.environ_data.radG[iter],
- self.environ_data.radD[iter],
- self.environ_data.radI[iter],
- self.environ_data.P[iter],
- self.raster_data.amaxvalue,
- self.raster_data.bush,
- self.environ_data.Twater[iter],
- self.tg_maps.TgK,
- self.tg_maps.Tstart,
- self.tg_maps.alb_grid,
- self.tg_maps.emis_grid,
- self.tg_maps.TgK_wall,
- self.tg_maps.Tstart_wall,
- self.tg_maps.TmaxLST,
- self.tg_maps.TmaxLST_wall,
- first,
- second,
- self.svf_data.svfalfa,
- self.raster_data.svfbuveg,
- firstdaytime,
- timeadd,
- timestepdec,
- self.tg_maps.Tgmap1,
- self.tg_maps.Tgmap1E,
- self.tg_maps.Tgmap1S,
- self.tg_maps.Tgmap1W,
- self.tg_maps.Tgmap1N,
- self.environ_data.CI[iter],
- self.tg_maps.TgOut1,
- self.shadow_mats.diffsh,
- self.shadow_mats.shmat,
- self.shadow_mats.vegshmat,
- self.shadow_mats.vbshvegshmat,
- int(self.config.use_aniso), # expects int though should work either way
- self.shadow_mats.asvf,
- self.shadow_mats.patch_option,
- self.walls_data.voxelMaps,
- self.walls_data.voxelTable,
- self.environ_data.Ws[iter],
- self.config.use_wall_scheme,
- self.walls_data.timeStep,
- self.shadow_mats.steradians,
- self.walls_data.walls_scheme,
- self.walls_data.dirwalls_scheme,
- )
diff --git a/pysrc/umepr/svf.py b/pysrc/umepr/svf.py
deleted file mode 100644
index 8955c92..0000000
--- a/pysrc/umepr/svf.py
+++ /dev/null
@@ -1,526 +0,0 @@
-"""
-SVF wrapper for Python - calls full Rust SVF via skyview rust module.
-"""
-
-# %%
-import logging
-import os
-import shutil
-import tempfile
-import zipfile
-from pathlib import Path
-
-import numpy as np
-from umep import class_configs, common
-from umep.tile_manager import TileManager
-
-from .rustalgos import skyview
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-# %%
-def generate_svf(
- dsm_path: str,
- bbox: list[int],
- out_dir: str,
- dem_path: str | None = None,
- cdsm_path: str | None = None,
- trans_veg_perc: float = 3,
- trunk_ratio_perc: float = 25,
- amax_local_window_m: int = 100,
- amax_local_perc: float = 99.9,
- use_tiled_loading: bool = False,
- tile_size: int = 1000,
- save_shadowmats: bool = True,
-):
- """
- Generate Sky View Factor outputs.
-
- Args:
- save_shadowmats: Save shadow matrices (required for SOLWEIG anisotropic sky).
- Saved as uint8 (75% smaller than float32). Set to False only
- if you don't need SOLWEIG's anisotropic modeling.
- """
- out_path = Path(out_dir)
- out_path.mkdir(parents=True, exist_ok=True)
- out_path_str = str(out_path)
-
- # Open the DSM file to get metadata
- # If tiled, we only load metadata first
- if use_tiled_loading:
- dsm_meta = common.get_raster_metadata(dsm_path)
- dsm_trf = dsm_meta["transform"]
- dsm_crs = dsm_meta["crs"]
- dsm_nd = dsm_meta["nodata"]
- rows = dsm_meta["rows"]
- cols = dsm_meta["cols"]
-
- # Handle rasterio vs GDAL transform
- if "res" in dsm_meta:
- # Convert Rasterio Affine to GDAL transform
- # Affine: (a, b, c, d, e, f) -> GDAL: (c, a, b, f, d, e)
- t = dsm_trf
- dsm_trf = [t.c, t.a, t.b, t.f, t.d, t.e]
-
- dsm_pix_size = dsm_trf[1]
- dsm_scale = 1 / dsm_pix_size
-
- # Calculate conservative global amax for buffer estimation
- # Load sample data to estimate terrain complexity
- sample_dsm, _, _, _ = common.load_raster(dsm_path, bbox=None, coerce_f64_to_f32=True)
-
- if dem_path is None:
- # Without DEM, use DSM range as conservative estimate
- global_amax = float(np.nanmax(sample_dsm) - np.nanmin(sample_dsm))
- else:
- # With DEM, estimate from height differences
- sample_dem, _, _, _ = common.load_raster(dem_path, bbox=None, coerce_f64_to_f32=True)
- height_diff = sample_dsm - sample_dem
- global_amax = float(np.nanpercentile(height_diff[~np.isnan(height_diff)], 99.9))
- del sample_dem
-
- # Add safety margin and cap at reasonable maximum
- global_amax = min(global_amax * 1.2, 200.0) # 20% safety margin, max 200m
- del sample_dsm
-
- logger.info(f"Estimated global amax: {global_amax:.1f}m for buffer calculation")
-
- # Initialize TileManager with calculated buffer
- tile_manager = TileManager(rows, cols, tile_size, dsm_pix_size, buffer_dist=global_amax)
-
- if len(tile_manager.tiles) == 0:
- raise ValueError(f"TileManager generated 0 tiles for {rows}x{cols} raster with tile_size={tile_size}")
-
- logger.info(f"Initialized TileManager with {len(tile_manager.tiles)} tiles.")
-
- # Initialize output rasters
- # We need to create empty rasters for all outputs
- output_files = ["input-dsm.tif", "svf.tif", "svfE.tif", "svfS.tif", "svfW.tif", "svfN.tif"]
- if dem_path:
- output_files.append("input-dem.tif")
- if cdsm_path:
- output_files.extend(
- [
- "input-cdsm.tif",
- "input-tdsm.tif",
- "svfveg.tif",
- "svfEveg.tif",
- "svfSveg.tif",
- "svfWveg.tif",
- "svfNveg.tif",
- "svfaveg.tif",
- "svfEaveg.tif",
- "svfSaveg.tif",
- "svfWaveg.tif",
- "svfNaveg.tif",
- "svf_total.tif",
- ]
- )
-
- for fname in output_files:
- common.create_empty_raster(out_path_str + "/" + fname, rows, cols, dsm_trf, dsm_crs, nodata=-9999.0)
-
- # Initialize memory-mapped arrays for shadow matrices (only if needed)
- if save_shadowmats:
- # 153 patches is standard for this algorithm
- patches = 153
- shmat_shape = (rows, cols, patches)
-
- # Create temp file paths
- temp_dir = tempfile.mkdtemp(dir=out_path_str)
- shmat_path = os.path.join(temp_dir, "shmat.dat")
- vegshmat_path = os.path.join(temp_dir, "vegshmat.dat")
- vbshvegshmat_path = os.path.join(temp_dir, "vbshvegshmat.dat")
-
- # Use uint8 instead of float32 for 75% space savings (shadow mats are binary 0/1)
- # Calculate memory requirements
- memmap_size_mb = (shmat_shape[0] * shmat_shape[1] * shmat_shape[2] * 1) / (1024 * 1024)
- logger.info(f"Creating memory-mapped arrays: {memmap_size_mb * 3:.1f} MB total (3 arrays, uint8)")
-
- # Create memmapped arrays with error handling
- try:
- shmat_mem = np.memmap(shmat_path, dtype="uint8", mode="w+", shape=shmat_shape)
- vegshmat_mem = np.memmap(vegshmat_path, dtype="uint8", mode="w+", shape=shmat_shape)
- vbshvegshmat_mem = np.memmap(vbshvegshmat_path, dtype="uint8", mode="w+", shape=shmat_shape)
- except OSError as e:
- shutil.rmtree(temp_dir, ignore_errors=True)
- raise OSError(
- f"Failed to create memory-mapped arrays ({memmap_size_mb * 3:.1f} MB). "
- f"Check disk space and permissions in {out_path_str}. Error: {e}"
- ) from e
-
- trans_veg = trans_veg_perc / 100.0
- trunk_ratio = trunk_ratio_perc / 100.0
-
- # Iterate over tiles
- for i, tile in enumerate(tile_manager.get_tiles()):
- logger.info(f"Processing tile {i + 1}/{len(tile_manager.tiles)}")
-
- # Load inputs for tile (with overlap)
- dsm_tile = common.read_raster_window(dsm_path, tile.full_slice, band=1)
-
- dem_tile = None
- if dem_path:
- dem_tile = common.read_raster_window(dem_path, tile.full_slice, band=1)
-
- cdsm_tile = None
- if cdsm_path:
- cdsm_tile = common.read_raster_window(cdsm_path, tile.full_slice, band=1)
-
- # Preprocess
- dsm_tile, dem_tile, cdsm_tile, tdsm_tile, amax = class_configs.raster_preprocessing(
- dsm_tile,
- dem_tile,
- cdsm_tile,
- None,
- trunk_ratio,
- dsm_pix_size,
- amax_local_window_m=amax_local_window_m,
- amax_local_perc=amax_local_perc,
- quiet=True,
- )
-
- # Compute SVF using Rust skyview module
- use_cdsm_bool = cdsm_path is not None
- runner = skyview.SkyviewRunner()
- ret = runner.calculate_svf(
- dsm_tile.astype(np.float32),
- cdsm_tile.astype(np.float32) if cdsm_tile is not None else None,
- tdsm_tile.astype(np.float32) if tdsm_tile is not None else None,
- dsm_scale,
- use_cdsm_bool,
- amax,
- 2, # 153 patches
- 5.0, # min_sun_elev_deg
- )
-
- # Write outputs (core only)
- core_slice = tile.core_slice()
- write_win = tile.write_window.to_slices()
-
- # Helper to write core - bind loop vars with default args
- def write_core(fname, data, cs=core_slice, ww=write_win):
- core_data = data[cs]
- common.write_raster_window(out_path_str + "/" + fname, core_data, ww)
-
- write_core("input-dsm.tif", dsm_tile)
- if dem_tile is not None:
- write_core("input-dem.tif", dem_tile)
- if cdsm_tile is not None:
- write_core("input-cdsm.tif", cdsm_tile)
- write_core("input-tdsm.tif", tdsm_tile)
-
- write_core("svf.tif", ret.svf)
- write_core("svfE.tif", ret.svf_east)
- write_core("svfS.tif", ret.svf_south)
- write_core("svfW.tif", ret.svf_west)
- write_core("svfN.tif", ret.svf_north)
-
- if use_cdsm_bool:
- write_core("svfveg.tif", ret.svf_veg)
- write_core("svfEveg.tif", ret.svf_veg_east)
- write_core("svfSveg.tif", ret.svf_veg_south)
- write_core("svfWveg.tif", ret.svf_veg_west)
- write_core("svfNveg.tif", ret.svf_veg_north)
- write_core("svfaveg.tif", ret.svf_veg_blocks_bldg_sh)
- write_core("svfEaveg.tif", ret.svf_veg_blocks_bldg_sh_east)
- write_core("svfSaveg.tif", ret.svf_veg_blocks_bldg_sh_south)
- write_core("svfWaveg.tif", ret.svf_veg_blocks_bldg_sh_west)
- write_core("svfNaveg.tif", ret.svf_veg_blocks_bldg_sh_north)
-
- # Calculate total SVF
- svftotal_tile = ret.svf - (1 - ret.svf_veg) * (1 - trans_veg)
- write_core("svf_total.tif", svftotal_tile)
-
- # Write shadow matrices to memmap (if saving)
- if save_shadowmats:
- # Extract core for 3D arrays - use core_slice with added dimension
- core_slice_3d = core_slice + (slice(None),)
-
- # Destination slice in memmap - use write_window directly
- write_slice_3d = tile.write_window.to_slices() + (slice(None),)
-
- # Convert to uint8 (shadow matrices are binary 0/1)
- shmat_mem[write_slice_3d] = (ret.bldg_sh_matrix[core_slice_3d] * 255).astype(np.uint8)
- vegshmat_mem[write_slice_3d] = (ret.veg_sh_matrix[core_slice_3d] * 255).astype(np.uint8)
- vbshvegshmat_mem[write_slice_3d] = (ret.veg_blocks_bldg_sh_matrix[core_slice_3d] * 255).astype(np.uint8)
-
- # Flush memmaps periodically?
- if i % 10 == 0:
- shmat_mem.flush()
- vegshmat_mem.flush()
- vbshvegshmat_mem.flush()
-
- # Save shadow matrices (if requested)
- if save_shadowmats:
- # Flush final
- shmat_mem.flush()
- vegshmat_mem.flush()
- vbshvegshmat_mem.flush()
-
- # Save shadow matrices as compressed npz (uint8 format)
- # We read from the memmapped files
- logger.info("Saving shadow matrices to npz (uint8 format, 75% smaller)...")
- np.savez_compressed(
- out_path_str + "/" + "shadowmats.npz",
- shadowmat=shmat_mem,
- vegshadowmat=vegshmat_mem,
- vbshmat=vbshvegshmat_mem,
- dtype="uint8", # Store metadata about dtype
- )
-
- # Cleanup temp
- del shmat_mem
- del vegshmat_mem
- del vbshvegshmat_mem
- shutil.rmtree(temp_dir)
- else:
- logger.info("Skipping shadow matrix save (not needed for this workflow)")
-
- # Zip SVF files (same as standard)
- zip_filepath = out_path_str + "/" + "svfs.zip"
- if os.path.isfile(zip_filepath):
- os.remove(zip_filepath)
-
- with zipfile.ZipFile(zip_filepath, "a") as zippo:
- zippo.write(out_path_str + "/" + "svf.tif", "svf.tif")
- zippo.write(out_path_str + "/" + "svfE.tif", "svfE.tif")
- zippo.write(out_path_str + "/" + "svfS.tif", "svfS.tif")
- zippo.write(out_path_str + "/" + "svfW.tif", "svfW.tif")
- zippo.write(out_path_str + "/" + "svfN.tif", "svfN.tif")
-
- if cdsm_path:
- zippo.write(out_path_str + "/" + "svfveg.tif", "svfveg.tif")
- zippo.write(out_path_str + "/" + "svfEveg.tif", "svfEveg.tif")
- zippo.write(out_path_str + "/" + "svfSveg.tif", "svfSveg.tif")
- zippo.write(out_path_str + "/" + "svfWveg.tif", "svfWveg.tif")
- zippo.write(out_path_str + "/" + "svfNveg.tif", "svfNveg.tif")
- zippo.write(out_path_str + "/" + "svfaveg.tif", "svfaveg.tif")
- zippo.write(out_path_str + "/" + "svfEaveg.tif", "svfEaveg.tif")
- zippo.write(out_path_str + "/" + "svfSaveg.tif", "svfSaveg.tif")
- zippo.write(out_path_str + "/" + "svfWaveg.tif", "svfWaveg.tif")
- zippo.write(out_path_str + "/" + "svfNaveg.tif", "svfNaveg.tif")
-
- # Remove individual files
- files_to_remove = ["svf.tif", "svfE.tif", "svfS.tif", "svfW.tif", "svfN.tif"]
- if cdsm_path:
- files_to_remove.extend(
- [
- "svfveg.tif",
- "svfEveg.tif",
- "svfSveg.tif",
- "svfWveg.tif",
- "svfNveg.tif",
- "svfaveg.tif",
- "svfEaveg.tif",
- "svfSaveg.tif",
- "svfWaveg.tif",
- "svfNaveg.tif",
- ]
- )
-
- for f in files_to_remove:
- try:
- os.remove(out_path_str + "/" + f)
- except OSError as e:
- logger.warning(f"Could not remove temporary file {f}: {e}")
-
- return
-
- # Standard execution (non-tiled)
- # Open the DSM file
- dsm, dsm_trf, dsm_crs, dsm_nd = common.load_raster(dsm_path, bbox, coerce_f64_to_f32=True)
- dsm_pix_size = dsm_trf[1]
- dsm_scale = 1 / dsm_pix_size
-
- dem = None
- if dem_path is not None:
- dem, dem_trf, dem_crs, _dem_nd = common.load_raster(dem_path, bbox, coerce_f64_to_f32=True)
- assert dem.shape == dsm.shape, "Mismatching raster shapes for DSM and DEM."
- assert np.allclose(dsm_trf, dem_trf), "Mismatching spatial transform for DSM and DEM."
- assert dem_crs == dsm_crs, "Mismatching CRS for DSM and DEM."
-
- use_cdsm = False
- cdsm = None
- if cdsm_path is not None:
- use_cdsm = True
- cdsm, cdsm_trf, cdsm_crs, _cdsm_nd = common.load_raster(cdsm_path, bbox, coerce_f64_to_f32=True)
- assert cdsm.shape == dsm.shape, "Mismatching raster shapes for DSM and CDSM."
- assert np.allclose(dsm_trf, cdsm_trf), "Mismatching spatial transform for DSM and CDSM."
- assert cdsm_crs == dsm_crs, "Mismatching CRS for DSM and CDSM."
-
- # veg transmissivity as percentage
- if not (0 <= trans_veg_perc <= 100):
- raise ValueError("Vegetation transmissivity should be a number between 0 and 100")
-
- trans_veg = trans_veg_perc / 100.0
- trunk_ratio = trunk_ratio_perc / 100.0
-
- dsm, dem, cdsm, tdsm, amax = class_configs.raster_preprocessing(
- dsm,
- dem,
- cdsm,
- None,
- trunk_ratio,
- dsm_pix_size,
- amax_local_window_m=amax_local_window_m,
- amax_local_perc=amax_local_perc,
- )
-
- common.save_raster(
- out_path_str + "/input-dsm.tif",
- dsm,
- dsm_trf,
- dsm_crs,
- dsm_nd,
- coerce_f64_to_f32=True,
- )
- if dem is not None:
- common.save_raster(
- out_path_str + "/input-dem.tif",
- dem,
- dsm_trf,
- dsm_crs,
- dsm_nd,
- coerce_f64_to_f32=True,
- )
- if use_cdsm:
- common.save_raster(
- out_path_str + "/input-cdsm.tif",
- cdsm,
- dsm_trf,
- dsm_crs,
- dsm_nd,
- coerce_f64_to_f32=True,
- )
- common.save_raster(
- out_path_str + "/input-tdsm.tif",
- tdsm,
- dsm_trf,
- dsm_crs,
- dsm_nd,
- coerce_f64_to_f32=True,
- )
-
- # compute using Rust skyview module
- runner = skyview.SkyviewRunner()
- ret = runner.calculate_svf(
- dsm.astype(np.float32),
- cdsm.astype(np.float32) if cdsm is not None else None,
- tdsm.astype(np.float32) if tdsm is not None else None,
- dsm_scale,
- use_cdsm,
- amax,
- 2, # 153 patches
- 5.0, # min_sun_elev_deg
- )
-
- svfbu = ret.svf
- svfbuE = ret.svf_east
- svfbuS = ret.svf_south
- svfbuW = ret.svf_west
- svfbuN = ret.svf_north
-
- # Save the rasters using rasterio
- common.save_raster(out_path_str + "/" + "svf.tif", svfbu, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfE.tif", svfbuE, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfS.tif", svfbuS, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfW.tif", svfbuW, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfN.tif", svfbuN, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
-
- # Create or update the ZIP file
- zip_filepath = out_path_str + "/" + "svfs.zip"
- if os.path.isfile(zip_filepath):
- os.remove(zip_filepath)
-
- with zipfile.ZipFile(zip_filepath, "a") as zippo:
- zippo.write(out_path_str + "/" + "svf.tif", "svf.tif")
- zippo.write(out_path_str + "/" + "svfE.tif", "svfE.tif")
- zippo.write(out_path_str + "/" + "svfS.tif", "svfS.tif")
- zippo.write(out_path_str + "/" + "svfW.tif", "svfW.tif")
- zippo.write(out_path_str + "/" + "svfN.tif", "svfN.tif")
-
- # Remove the individual TIFF files after zipping
- os.remove(out_path_str + "/" + "svf.tif")
- os.remove(out_path_str + "/" + "svfE.tif")
- os.remove(out_path_str + "/" + "svfS.tif")
- os.remove(out_path_str + "/" + "svfW.tif")
- os.remove(out_path_str + "/" + "svfN.tif")
-
- if use_cdsm == 0:
- svftotal = svfbu
- else:
- # Report the vegetation-related results
- svfveg = ret.svf_veg
- svfEveg = ret.svf_veg_east
- svfSveg = ret.svf_veg_south
- svfWveg = ret.svf_veg_west
- svfNveg = ret.svf_veg_north
- svfaveg = ret.svf_veg_blocks_bldg_sh
- svfEaveg = ret.svf_veg_blocks_bldg_sh_east
- svfSaveg = ret.svf_veg_blocks_bldg_sh_south
- svfWaveg = ret.svf_veg_blocks_bldg_sh_west
- svfNaveg = ret.svf_veg_blocks_bldg_sh_north
-
- # Save vegetation rasters
- common.save_raster(out_path_str + "/" + "svfveg.tif", svfveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfEveg.tif", svfEveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfSveg.tif", svfSveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfWveg.tif", svfWveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfNveg.tif", svfNveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfaveg.tif", svfaveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfEaveg.tif", svfEaveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfSaveg.tif", svfSaveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfWaveg.tif", svfWaveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
- common.save_raster(out_path_str + "/" + "svfNaveg.tif", svfNaveg, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
-
- # Add vegetation rasters to the ZIP file
- with zipfile.ZipFile(zip_filepath, "a") as zippo:
- zippo.write(out_path_str + "/" + "svfveg.tif", "svfveg.tif")
- zippo.write(out_path_str + "/" + "svfEveg.tif", "svfEveg.tif")
- zippo.write(out_path_str + "/" + "svfSveg.tif", "svfSveg.tif")
- zippo.write(out_path_str + "/" + "svfWveg.tif", "svfWveg.tif")
- zippo.write(out_path_str + "/" + "svfNveg.tif", "svfNveg.tif")
- zippo.write(out_path_str + "/" + "svfaveg.tif", "svfaveg.tif")
- zippo.write(out_path_str + "/" + "svfEaveg.tif", "svfEaveg.tif")
- zippo.write(out_path_str + "/" + "svfSaveg.tif", "svfSaveg.tif")
- zippo.write(out_path_str + "/" + "svfWaveg.tif", "svfWaveg.tif")
- zippo.write(out_path_str + "/" + "svfNaveg.tif", "svfNaveg.tif")
-
- # Remove the individual TIFF files after zipping
- os.remove(out_path_str + "/" + "svfveg.tif")
- os.remove(out_path_str + "/" + "svfEveg.tif")
- os.remove(out_path_str + "/" + "svfSveg.tif")
- os.remove(out_path_str + "/" + "svfWveg.tif")
- os.remove(out_path_str + "/" + "svfNveg.tif")
- os.remove(out_path_str + "/" + "svfaveg.tif")
- os.remove(out_path_str + "/" + "svfEaveg.tif")
- os.remove(out_path_str + "/" + "svfSaveg.tif")
- os.remove(out_path_str + "/" + "svfWaveg.tif")
- os.remove(out_path_str + "/" + "svfNaveg.tif")
-
- # Calculate final total SVF
- svftotal = svfbu - (1 - svfveg) * (1 - trans_veg)
-
- # Save the final svftotal raster
- common.save_raster(out_path_str + "/" + "svf_total.tif", svftotal, dsm_trf, dsm_crs, coerce_f64_to_f32=True)
-
- # Save shadow matrices as compressed npz (only if requested)
- if save_shadowmats:
- shmat = ret.bldg_sh_matrix
- vegshmat = ret.veg_sh_matrix
- vbshvegshmat = ret.veg_blocks_bldg_sh_matrix
-
- # Convert to uint8 for 75% space savings (shadow matrices are binary 0/1)
- logger.info("Saving shadow matrices to npz (uint8 format, 75% smaller)...")
- np.savez_compressed(
- out_path_str + "/" + "shadowmats.npz",
- shadowmat=(shmat * 255).astype(np.uint8),
- vegshadowmat=(vegshmat * 255).astype(np.uint8),
- vbshmat=(vbshvegshmat * 255).astype(np.uint8),
- dtype="uint8", # Store metadata about dtype
- )
- else:
- logger.info("Skipping shadow matrix save (not needed for this workflow)")
diff --git a/qgis_plugin/README.md b/qgis_plugin/README.md
new file mode 100644
index 0000000..ae51bd3
--- /dev/null
+++ b/qgis_plugin/README.md
@@ -0,0 +1,353 @@
+# SOLWEIG QGIS Plugin
+
+QGIS Processing plugin for SOLWEIG (Solar and Longwave Environmental Irradiance Geometry model).
+
+## Overview
+
+This plugin wraps SOLWEIG's Python API to provide native QGIS Processing framework integration. It enables calculation of Mean Radiant Temperature (Tmrt), UTCI, and PET thermal comfort indices directly within QGIS.
+
+**Key Features:**
+
+- Native QGIS Processing Toolbox integration
+- Model Builder and batch mode support
+- Auto-detects GDAL backend (no rasterio required in QGIS/OSGeo4W)
+- Progress reporting via QgsProcessingFeedback
+- Outputs auto-load to canvas with thermal comfort color ramps
+
+## Installation
+
+1. Copy the `solweig_qgis/` directory to your QGIS plugins folder:
+ - Windows: `%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\`
+ - macOS: `~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins/`
+ - Linux: `~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/`
+
+2. Enable the plugin in QGIS: Plugins → Manage and Install Plugins → Installed → SOLWEIG
+
+3. Access algorithms via Processing Toolbox → SOLWEIG
+
+## Algorithms
+
+### Preprocessing
+
+| Algorithm | Description |
+| --------------------------- | ------------------------------------------------- |
+| **Compute Sky View Factor** | Pre-compute SVF arrays for reuse across timesteps |
+
+### Calculation
+
+| Algorithm | Description |
+| ------------------------------------ | ---------------------------------------------------------- |
+| **Calculate Tmrt (Single Timestep)** | Calculate Mean Radiant Temperature for one datetime |
+| **Calculate Tmrt (Timeseries)** | Multi-timestep calculation with thermal state accumulation |
+| **Calculate Tmrt (Large Rasters)** | Memory-efficient tiled processing for large areas |
+
+### Post-Processing
+
+| Algorithm | Description |
+| ---------------- | ----------------------------------------------------- |
+| **Compute UTCI** | Universal Thermal Climate Index (fast polynomial) |
+| **Compute PET** | Physiological Equivalent Temperature (detailed model) |
+
+### Utilities
+
+| Algorithm | Description |
+| --------------------------- | --------------------------------------------- |
+| **Import EPW Weather File** | Preview and validate EnergyPlus weather files |
+
+## Directory Structure
+
+```
+qgis_plugin/
+├── README.md # This file
+├── build_plugin.py # Build script for bundled distribution
+│
+└── solweig_qgis/ # Plugin package (install this to QGIS)
+ ├── __init__.py # Plugin entry point with classFactory()
+ ├── metadata.txt # QGIS plugin metadata
+ ├── provider.py # SolweigProvider (registers algorithms)
+ ├── _bundled/ # Bundled SOLWEIG library (for distribution)
+ │
+ ├── algorithms/
+ │ ├── __init__.py
+ │ ├── base.py # SolweigAlgorithmBase (shared utilities)
+ │ │
+ │ ├── preprocess/
+ │ │ ├── __init__.py
+ │ │ └── svf_preprocessing.py # "Compute Sky View Factor"
+ │ │
+ │ ├── calculation/
+ │ │ ├── __init__.py
+ │ │ ├── single_timestep.py # "Calculate Tmrt (Single Timestep)"
+ │ │ ├── timeseries.py # "Calculate Tmrt (Timeseries)"
+ │ │ └── tiled_processing.py # "Calculate Tmrt (Large Rasters)"
+ │ │
+ │ ├── postprocess/
+ │ │ ├── __init__.py
+ │ │ ├── utci.py # "Compute UTCI"
+ │ │ └── pet.py # "Compute PET"
+ │ │
+ │ └── utilities/
+ │ ├── __init__.py
+ │ └── epw_import.py # "Import EPW Weather File"
+ │
+ └── utils/
+ ├── __init__.py
+ ├── parameters.py # Common parameter builders
+ └── converters.py # QGIS ↔ solweig dataclass conversion
+```
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Plugin Skeleton ✅
+
+- [x] **1.1** Create `__init__.py` with `classFactory()` entry point
+- [x] **1.2** Create `metadata.txt` with plugin metadata
+- [x] **1.3** Create `provider.py` with `SolweigProvider` class
+- [ ] **1.4** Create placeholder icon.png
+- [ ] **1.5** Test plugin loads in QGIS (empty provider)
+
+### Phase 2: Shared Utilities ✅
+
+- [x] **2.1** Create `algorithms/__init__.py`
+- [x] **2.2** Create `algorithms/base.py` with `SolweigAlgorithmBase`:
+ - [x] `load_raster_from_layer()` - QGIS layer → numpy array via GDAL
+ - [x] `load_optional_raster()` - Handle optional raster parameters
+ - [x] `save_georeferenced_output()` - Save with CRS/transform via solweig.io
+ - [x] `add_raster_to_canvas()` - Add layer to QGIS project
+ - [x] `apply_thermal_comfort_style()` - Apply UTCI/Tmrt color ramps
+- [x] **2.3** Create `utils/__init__.py`
+- [x] **2.4** Create `utils/parameters.py` with common parameter builders:
+ - [x] `add_surface_parameters()` - DSM, CDSM, DEM, TDSM, LAND_COVER
+ - [x] `add_location_parameters()` - LAT, LON, UTC_OFFSET, AUTO_EXTRACT
+ - [x] `add_weather_parameters()` - DATETIME, TA, RH, RAD, WIND
+ - [x] `add_human_parameters()` - POSTURE, ABS_K
+- [x] **2.5** Create `utils/converters.py`:
+ - [x] `create_surface_from_parameters()` - Build SurfaceData from QGIS params
+ - [x] `create_location_from_parameters()` - Build Location from params
+ - [x] `create_weather_from_parameters()` - Build Weather from params
+
+### Phase 3: Single Timestep Algorithm ✅
+
+- [x] **3.1** Create `algorithms/calculation/__init__.py`
+- [x] **3.2** Create `algorithms/calculation/single_timestep.py`:
+ - [x] Define all input parameters (surface, location, weather, human, options)
+ - [x] Define output parameters (TMRT, optional SHADOW, KDOWN)
+ - [x] Implement `processAlgorithm()`:
+ - [x] Load rasters from QGIS layers
+ - [x] Create SurfaceData, Location, Weather, HumanParams
+ - [x] Handle height conversion (relative → absolute)
+ - [x] Call `solweig.calculate()`
+ - [x] Save output GeoTIFF
+ - [x] Add to canvas with styling
+- [x] **3.3** Register in provider
+- [ ] **3.4** Test in QGIS with Gothenburg test data
+
+### Phase 4: SVF Preprocessing Algorithm ✅
+
+- [x] **4.1** Create `algorithms/preprocess/__init__.py`
+- [x] **4.2** Create `algorithms/preprocess/svf_preprocessing.py`:
+ - [x] Define input parameters (DSM, CDSM, DEM, TDSM, TRANS_VEG, OUTPUT_DIR)
+ - [x] Define output parameters (SVF_DIR, SVF_FILE)
+ - [x] Implement `processAlgorithm()`:
+ - [x] Load rasters
+ - [x] Create SurfaceData
+ - [x] Call `surface.prepare()` with working_dir
+ - [x] Report progress via feedback
+- [x] **4.3** Register in provider
+- [ ] **4.4** Test SVF computation and caching
+
+### Phase 5: Timeseries Algorithm ✅
+
+- [x] **5.1** Create `algorithms/calculation/timeseries.py`:
+ - [x] Add EPW_FILE, START_DATE, END_DATE, HOURS_FILTER parameters
+ - [x] Add OUTPUT_DIR, OUTPUTS selection parameters
+ - [x] Implement `processAlgorithm()`:
+ - [x] Load and filter weather from EPW
+ - [x] Create surface and location
+ - [x] Call `solweig.calculate_timeseries()`
+ - [x] Report progress per timestep
+ - [x] Handle cancellation
+- [x] **5.2** Register in provider
+- [ ] **5.3** Test with multi-day EPW data
+
+### Phase 6: UTCI Algorithm ✅
+
+- [x] **6.1** Create `algorithms/postprocess/__init__.py`
+- [x] **6.2** Create `algorithms/postprocess/utci.py`:
+ - [x] Define TMRT_DIR, EPW_FILE, OUTPUT_DIR parameters
+ - [x] Implement `processAlgorithm()`:
+ - [x] Load weather series from EPW
+ - [x] Call `solweig.compute_utci()`
+ - [x] Report file count
+- [x] **6.3** Register in provider
+- [ ] **6.4** Test UTCI computation
+
+### Phase 7: PET Algorithm ✅
+
+- [x] **7.1** Create `algorithms/postprocess/pet.py`:
+ - [x] Add human body parameters (AGE, WEIGHT, HEIGHT, SEX, ACTIVITY, CLOTHING)
+ - [x] Implement `processAlgorithm()` calling `solweig.compute_pet()`
+- [x] **7.2** Register in provider
+- [ ] **7.3** Test PET computation
+
+### Phase 8: EPW Import Utility ✅
+
+- [x] **8.1** Create `algorithms/utilities/__init__.py`
+- [x] **8.2** Create `algorithms/utilities/epw_import.py`:
+ - [x] Define EPW_FILE input parameter
+ - [x] Implement `processAlgorithm()`:
+ - [x] Parse EPW with `solweig.io.read_epw()`
+ - [x] Generate HTML report with location, date range, statistics
+- [x] **8.3** Register in provider
+- [ ] **8.4** Test with sample EPW files
+
+### Phase 9: Tiled Processing Algorithm ✅
+
+- [x] **9.1** Create `algorithms/calculation/tiled_processing.py`:
+ - [x] Add TILE_SIZE, AUTO_TILE_SIZE parameters
+ - [x] Implement `processAlgorithm()` calling `solweig.calculate_tiled()`
+- [x] **9.2** Register in provider
+- [ ] **9.3** Test with large raster
+
+### Phase 10: Build & Distribution ✅
+
+- [x] **10.1** Create `build_plugin.py` build script
+- [x] **10.2** Set up `_bundled/` directory support in `__init__.py`
+- [x] **10.3** Create GitHub Actions workflow for cross-platform builds
+- [x] **10.4** Update README with build instructions
+
+### Phase 11: Testing & Polish (Pending)
+
+- [ ] **11.1** Add docstrings to all algorithms
+- [ ] **11.2** Create help strings for QGIS Help panel
+- [ ] **11.3** Test full workflow in QGIS
+- [ ] **11.4** Verify outputs match standalone Python execution
+- [ ] **11.5** Create icon.png
+- [ ] **11.6** Update this README with usage examples
+
+---
+
+## Building & Distribution
+
+The plugin can be distributed in two ways:
+
+### Option A: Bundled Distribution (Recommended for Users)
+
+This bundles the compiled Rust extension and Python modules into the plugin, so users don't need to install anything separately.
+
+```bash
+# Build for your current platform
+cd qgis_plugin
+python build_plugin.py
+
+# Create distributable ZIP
+python build_plugin.py --package --version 0.1.0
+
+# Clean build artifacts
+python build_plugin.py --clean
+```
+
+This creates a platform-specific ZIP file (e.g., `solweig-qgis-0.1.0-linux_x86_64.zip`) that can be installed directly in QGIS.
+
+**Supported platforms (CI builds):**
+
+- Linux x86_64
+- Windows x86_64
+- macOS x86_64
+- macOS aarch64 (Apple Silicon)
+
+### Option B: Development Setup
+
+For development or if you have SOLWEIG installed via pip:
+
+1. Install SOLWEIG in your Python environment:
+
+ ```bash
+ pip install solweig
+ # or for development
+ cd /path/to/solweig && pip install -e .
+ ```
+
+2. Symlink the plugin to QGIS:
+
+ ```bash
+ # Linux
+ ln -s /path/to/solweig/qgis_plugin/solweig_qgis ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/solweig_qgis
+
+ # macOS
+ ln -s /path/to/solweig/qgis_plugin/solweig_qgis ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins/solweig_qgis
+
+ # Windows (run as admin)
+ mklink /D "%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\solweig_qgis" "C:\path\to\solweig\qgis_plugin\solweig_qgis"
+ ```
+
+The plugin auto-detects SOLWEIG in this order:
+
+1. Bundled (`_bundled/` directory)
+2. System-installed (via pip)
+3. Development path (`../pysrc/solweig`)
+
+### CI/CD Automated Builds (Universal Plugin)
+
+The GitHub Actions workflow (`.github/workflows/build-qgis-plugin.yml`) automatically builds a **universal multi-platform plugin**:
+
+**Triggers:**
+
+- Version tags (e.g., `v0.1.0`)
+- Manual workflow dispatch
+
+**Build process:**
+
+1. Builds Rust wheels for all 4 platforms (Linux, Windows, macOS Intel, macOS ARM)
+2. Extracts Python modules from one wheel (identical across platforms)
+3. Extracts platform-specific `rustalgos` binaries to `_native//`
+4. Creates single ZIP: `solweig-qgis-{version}-universal.zip`
+
+**At runtime**, the plugin auto-detects the platform and loads the correct binary from `_native/`
+
+**Result:** One ZIP works on all platforms - no need for separate downloads per OS
+
+## Dependencies
+
+**For bundled distribution:** No external dependencies required.
+
+**For development:** The plugin requires the SOLWEIG Python package:
+
+```bash
+pip install solweig
+```
+
+Or point to development source:
+
+```python
+import sys
+sys.path.insert(0, '/path/to/solweig/pysrc')
+```
+
+## Core Library Files Referenced
+
+| File | Purpose |
+| --------------------------------- | ----------------------------------------------------- |
+| `pysrc/solweig/api.py` | Entry points: `calculate()`, `calculate_timeseries()` |
+| `pysrc/solweig/progress.py` | QgsProcessingFeedback integration |
+| `pysrc/solweig/io.py` | GDAL backend, EPW parser |
+| `pysrc/solweig/models/surface.py` | SurfaceData with height conversion |
+| `pysrc/solweig/models/weather.py` | Weather.from_epw() |
+
+## Citation
+
+If you use SOLWEIG in your research, please cite the original UMEP paper:
+
+> Lindberg F, Grimmond CSB, Gabey A, Huang B, Kent CW, Sun T, Theeuwes N, Järvi L, Ward H, Capel-Timms I, Chang YY, Jonsson P, Krave N, Liu D, Meyer D, Olofson F, Tan JG, Wästberg D, Xue L, Zhang Z (2018) Urban Multi-scale Environmental Predictor (UMEP) - An integrated tool for city-based climate services. Environmental Modelling and Software 99, 70-87 [doi:10.1016/j.envsoft.2017.09.020](https://doi.org/10.1016/j.envsoft.2017.09.020)
+
+## Original Code
+
+This plugin is adapted from the GPLv3-licensed [UMEP-processing](https://github.com/UMEP-dev/UMEP-processing) by Fredrik Lindberg, Ting Sun, Sue Grimmond, Yihao Tang, and Nils Wallenberg.
+
+SOLWEIG plugin maintained by Gareth Simons and the SOLWEIG Development Team.
+
+## License
+
+GNU General Public License v3.0. Same license as SOLWEIG core library and original UMEP code.
diff --git a/qgis_plugin/build_plugin.py b/qgis_plugin/build_plugin.py
new file mode 100644
index 0000000..84d22f1
--- /dev/null
+++ b/qgis_plugin/build_plugin.py
@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Build script for SOLWEIG QGIS plugin.
+
+Packages the plugin into a distributable ZIP for the QGIS Plugin Repository.
+The solweig library itself is installed separately via pip (auto-prompted on
+first use, or manually with ``pip install solweig``).
+
+The version is read from pyproject.toml (single source of truth) and stamped
+into metadata.txt before packaging.
+
+Usage:
+ python build_plugin.py # Create distributable ZIP
+ python build_plugin.py --version 0.2.0 # Override version
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import shutil
+import zipfile
+from pathlib import Path
+
+# Paths
+SCRIPT_DIR = Path(__file__).parent
+PROJECT_ROOT = SCRIPT_DIR.parent
+PLUGIN_DIR = SCRIPT_DIR / "solweig_qgis"
+METADATA_PATH = PLUGIN_DIR / "metadata.txt"
+
+
+def read_pyproject_version() -> str:
+ """Read the version from pyproject.toml (single source of truth)."""
+ pyproject = PROJECT_ROOT / "pyproject.toml"
+ text = pyproject.read_text()
+ match = re.search(r'^version\s*=\s*"([^"]+)"', text, re.MULTILINE)
+ if not match:
+ raise RuntimeError("Could not find version in pyproject.toml")
+ return match.group(1)
+
+
+def pep440_to_qgis(version: str) -> str:
+ """Convert PEP 440 version (0.1.0b5) to QGIS metadata format (0.1.0-beta5)."""
+ version = re.sub(r"a(\d+)", r"-alpha\1", version)
+ version = re.sub(r"b(\d+)", r"-beta\1", version)
+ version = re.sub(r"rc(\d+)", r"-rc\1", version)
+ return version
+
+
+def stamp_metadata_version(version: str):
+ """Update the version in metadata.txt to match pyproject.toml."""
+ qgis_version = pep440_to_qgis(version)
+ text = METADATA_PATH.read_text()
+ new_text = re.sub(r"^version=.*$", f"version={qgis_version}", text, flags=re.MULTILINE)
+ if new_text == text and f"version={qgis_version}" not in text:
+ raise RuntimeError(f"Failed to update version in {METADATA_PATH}")
+ METADATA_PATH.write_text(new_text)
+ print(f" Stamped metadata.txt version={qgis_version}")
+
+ # Warn if changelog doesn't mention this version
+ if qgis_version not in new_text.split("changelog=")[-1]:
+ print(f" WARNING: changelog in metadata.txt has no entry for {qgis_version}")
+
+
+def copy_license():
+ """Copy LICENSE from project root into the plugin directory (required by QGIS repo)."""
+ src = PROJECT_ROOT / "LICENSE"
+ dest = PLUGIN_DIR / "LICENSE"
+ if src.exists():
+ shutil.copy2(src, dest)
+ print(f" Copied LICENSE into {PLUGIN_DIR.name}/")
+ else:
+ print(" WARNING: No LICENSE file found at project root")
+
+
+def create_package_zip(version: str) -> Path:
+ """Create distributable ZIP file for QGIS Plugin Repository."""
+ qgis_version = pep440_to_qgis(version)
+ zip_name = f"solweig-qgis-{qgis_version}.zip"
+ zip_path = SCRIPT_DIR / zip_name
+
+ print(f"\nCreating {zip_name}...")
+
+ with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+ for file_path in PLUGIN_DIR.rglob("*"):
+ if file_path.is_file():
+ # Skip __pycache__, .pyc, and macOS metadata files
+ if "__pycache__" in str(file_path) or file_path.suffix == ".pyc":
+ continue
+ if file_path.name in (".DS_Store", "._DS_Store"):
+ continue
+ arcname = file_path.relative_to(SCRIPT_DIR)
+ zf.write(file_path, arcname)
+
+ size_kb = zip_path.stat().st_size / 1024
+ print(f" Created: {zip_path.name} ({size_kb:.0f} KB)")
+ return zip_path
+
+
+def main():
+ parser = argparse.ArgumentParser(description="Build SOLWEIG QGIS plugin")
+ parser.add_argument(
+ "--version",
+ default=None,
+ help="Override version (default: read from pyproject.toml)",
+ )
+ parser.add_argument("--clean", action="store_true", help="Clean old ZIP artifacts")
+ args = parser.parse_args()
+
+ print("=" * 60)
+ print("SOLWEIG QGIS Plugin Builder")
+ print("=" * 60)
+
+ if args.clean:
+ print("\nCleaning build artifacts...")
+ for zip_file in SCRIPT_DIR.glob("solweig-qgis-*.zip"):
+ zip_file.unlink()
+ print(f" Removed: {zip_file.name}")
+ print("Done!")
+ return
+
+ version = args.version or read_pyproject_version()
+ print(f"\n Version: {version} (from {'--version flag' if args.version else 'pyproject.toml'})")
+
+ stamp_metadata_version(version)
+ copy_license()
+ zip_path = create_package_zip(version)
+
+ print("\n" + "=" * 60)
+ print("Build complete!")
+ print("=" * 60)
+ print(f"\nPackage: {zip_path}")
+ print("\nTo install in QGIS:")
+ print(" 1. Plugins > Manage and Install Plugins > Install from ZIP")
+ print(f" 2. Select {zip_path.name}")
+ print(" 3. The plugin will prompt to install the solweig library on first use")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/qgis_plugin/solweig_qgis/LICENSE b/qgis_plugin/solweig_qgis/LICENSE
new file mode 100644
index 0000000..e72bfdd
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/LICENSE
@@ -0,0 +1,674 @@
+ GNU GENERAL PUBLIC LICENSE
+ Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+ The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users. We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors. You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+ To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. You must make sure that they, too, receive
+or can get the source code. And you must show them these terms so they
+know their rights.
+
+ Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+ For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+ Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so. This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software. The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable. Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products. If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+ Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary. To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS
+
+ 0. Definitions.
+
+ "This License" refers to version 3 of the GNU General Public License.
+
+ "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+ "The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+ To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+ A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+ To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+ To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+ An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+ 1. Source Code.
+
+ The "source code" for a work means the preferred form of the work
+for making modifications to it. "Object code" means any non-source
+form of a work.
+
+ A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+ The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+ The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+ The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+ The Corresponding Source for a work in source code form is that
+same work.
+
+ 2. Basic Permissions.
+
+ All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+ You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force. You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright. Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+ Conveying under any other circumstances is permitted solely under
+the conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+ No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+ When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+ 4. Conveying Verbatim Copies.
+
+ You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+ You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+ 5. Conveying Modified Source Versions.
+
+ You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+ a) The work must carry prominent notices stating that you modified
+ it, and giving a relevant date.
+
+ b) The work must carry prominent notices stating that it is
+ released under this License and any conditions added under section
+ 7. This requirement modifies the requirement in section 4 to
+ "keep intact all notices".
+
+ c) You must license the entire work, as a whole, under this
+ License to anyone who comes into possession of a copy. This
+ License will therefore apply, along with any applicable section 7
+ additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no
+ permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+
+ d) If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your
+ work need not make them do so.
+
+ A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+ 6. Conveying Non-Source Forms.
+
+ You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+ a) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by the
+ Corresponding Source fixed on a durable physical medium
+ customarily used for software interchange.
+
+ b) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by a
+ written offer, valid for at least three years and valid for as
+ long as you offer spare parts or customer support for that product
+ model, to give anyone who possesses the object code either (1) a
+ copy of the Corresponding Source for all the software in the
+ product that is covered by this License, on a durable physical
+ medium customarily used for software interchange, for a price no
+ more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the
+ Corresponding Source from a network server at no charge.
+
+ c) Convey individual copies of the object code with a copy of the
+ written offer to provide the Corresponding Source. This
+ alternative is allowed only occasionally and noncommercially, and
+ only if you received the object code with such an offer, in accord
+ with subsection 6b.
+
+ d) Convey the object code by offering access from a designated
+ place (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to
+ copy the object code is a network server, the Corresponding Source
+ may be on a different server (operated by you or a third party)
+ that supports equivalent copying facilities, provided you maintain
+ clear directions next to the object code saying where to find the
+ Corresponding Source. Regardless of what server hosts the
+ Corresponding Source, you remain obligated to ensure that it is
+ available for as long as needed to satisfy these requirements.
+
+ e) Convey the object code using peer-to-peer transmission, provided
+ you inform other peers where the object code and Corresponding
+ Source of the work are being offered to the general public at no
+ charge under subsection 6d.
+
+ A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+ A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage. For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product. A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+ "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source. The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+ If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+ The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+ Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+ 7. Additional Terms.
+
+ "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+ When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+ Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+ a) Disclaiming warranty or limiting liability differently from the
+ terms of sections 15 and 16 of this License; or
+
+ b) Requiring preservation of specified reasonable legal notices or
+ author attributions in that material or in the Appropriate Legal
+ Notices displayed by works containing it; or
+
+ c) Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+
+ d) Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+
+ e) Declining to grant rights under trademark law for use of some
+ trade names, trademarks, or service marks; or
+
+ f) Requiring indemnification of licensors and authors of that
+ material by anyone who conveys the material (or modified versions of
+ it) with contractual assumptions of liability to the recipient, for
+ any liability that these contractual assumptions directly impose on
+ those licensors and authors.
+
+ All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+ If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+ Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+ 8. Termination.
+
+ You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+ However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+ Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+ 9. Acceptance Not Required for Having Copies.
+
+ You are not required to accept this License in order to receive or
+run a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+ 10. Automatic Licensing of Downstream Recipients.
+
+ Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+ An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+ You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+ 11. Patents.
+
+ A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+ A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+ In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+ If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+ If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+ A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License. You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+ Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+ 12. No Surrender of Others' Freedom.
+
+ If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all. For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+ 13. Use with the GNU Affero General Public License.
+
+ Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+ 14. Revised Versions of this License.
+
+ The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+ If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+ Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+ 15. Disclaimer of Warranty.
+
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+ 16. Limitation of Liability.
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+ 17. Interpretation of Sections 15 and 16.
+
+ If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+
+ Copyright (C)
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+ Copyright (C)
+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+.
+
+ The GNU General Public License does not permit incorporating your program
+into proprietary programs. If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License. But first, please read
+.
\ No newline at end of file
diff --git a/qgis_plugin/solweig_qgis/__init__.py b/qgis_plugin/solweig_qgis/__init__.py
new file mode 100644
index 0000000..a304dbd
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/__init__.py
@@ -0,0 +1,476 @@
+"""
+SOLWEIG QGIS Plugin
+
+Provides QGIS Processing algorithms for calculating Mean Radiant Temperature (Tmrt),
+UTCI, and PET thermal comfort indices using the SOLWEIG model.
+
+Adapted from UMEP (Urban Multi-scale Environmental Predictor).
+Original code by Fredrik Lindberg, Ting Sun, Sue Grimmond, Yihao Tang, and Nils Wallenberg.
+
+Citation:
+ Lindberg F, Grimmond CSB, Gabey A, Huang B, Kent CW, Sun T, Theeuwes N, Järvi L,
+ Ward H, Capel-Timms I, Chang YY, Jonsson P, Krave N, Liu D, Meyer D, Olofson F,
+ Tan JG, Wästberg D, Xue L, Zhang Z (2018) Urban Multi-scale Environmental Predictor
+ (UMEP) - An integrated tool for city-based climate services.
+ Environmental Modelling and Software 99, 70-87
+ https://doi.org/10.1016/j.envsoft.2017.09.020
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Dependency management
+# ---------------------------------------------------------------------------
+
+_PLUGIN_DIR = Path(__file__).resolve().parent
+
+
+def _read_required_version() -> str:
+ """
+ Read the required solweig version from metadata.txt.
+
+ The plugin version in metadata.txt is kept in sync with the solweig library
+ version by build_plugin.py, which reads pyproject.toml as the single source
+ of truth. The QGIS metadata format uses hyphens (0.1.0-beta5) while PEP 440
+ uses letters (0.1.0b5), so we normalize here.
+ """
+ import configparser
+
+ metadata_path = _PLUGIN_DIR / "metadata.txt"
+ config = configparser.ConfigParser()
+ config.read(metadata_path)
+ qgis_version = config.get("general", "version", fallback="0.0.0")
+
+ # Normalize QGIS format (0.1.0-beta5) to PEP 440 (0.1.0b5)
+ import re
+
+ normalized = re.sub(r"-?alpha", "a", qgis_version)
+ normalized = re.sub(r"-?beta", "b", normalized)
+ normalized = re.sub(r"-?rc", "rc", normalized)
+ return normalized
+
+
+_REQUIRED_SOLWEIG_VERSION = _read_required_version()
+_SOLWEIG_AVAILABLE = False
+_SOLWEIG_OUTDATED = False # True when installed but too old
+_SOLWEIG_SOURCE = None # "system", "development", or None
+_SOLWEIG_IMPORT_ERROR = None
+_SOLWEIG_INSTALLED_VERSION = None
+
+
+def _parse_version(version_str: str) -> tuple:
+ """
+ Parse a PEP 440 version string into a comparable tuple.
+
+ Handles release versions (0.1.0) and pre-release versions (0.1.0b5, 0.1.0a1, 0.1.0rc1).
+ Pre-release versions sort before their release (0.1.0b5 < 0.1.0).
+ """
+ import re
+
+ match = re.match(r"^(\d+(?:\.\d+)*)(?:(a|b|rc)(\d+))?", version_str)
+ if not match:
+ return (0, 0, 0, "z", 0) # unparseable sorts high to avoid false outdated
+
+ release = tuple(int(x) for x in match.group(1).split("."))
+ pre_type = match.group(2) # "a", "b", "rc", or None
+ pre_num = int(match.group(3)) if match.group(3) else 0
+
+ # "z" sorts after "a", "b", "rc" — so final releases are higher than pre-releases
+ pre_key = pre_type if pre_type else "z"
+ return release + (pre_key, pre_num)
+
+
+def _check_version(solweig_module) -> bool:
+ """
+ Check if the imported solweig module meets the minimum version requirement.
+
+ Sets _SOLWEIG_OUTDATED and _SOLWEIG_IMPORT_ERROR if the version is too old.
+
+ Returns:
+ True if version is acceptable, False if outdated.
+ """
+ global _SOLWEIG_OUTDATED, _SOLWEIG_IMPORT_ERROR, _SOLWEIG_INSTALLED_VERSION
+
+ installed = getattr(solweig_module, "__version__", None) or "0.0.0"
+ _SOLWEIG_INSTALLED_VERSION = installed
+
+ # Version check (prefer robust PEP 440 parsing when available)
+ try:
+ from packaging.version import Version
+
+ if Version(installed) < Version(_REQUIRED_SOLWEIG_VERSION):
+ _SOLWEIG_OUTDATED = True
+ _SOLWEIG_IMPORT_ERROR = (
+ f"solweig {installed} is installed but this plugin requires >= {_REQUIRED_SOLWEIG_VERSION}"
+ )
+ return False
+ except Exception:
+ # Fallback for minimal environments (should be rare)
+ if _parse_version(installed) < _parse_version(_REQUIRED_SOLWEIG_VERSION):
+ _SOLWEIG_OUTDATED = True
+ _SOLWEIG_IMPORT_ERROR = (
+ f"solweig {installed} is installed but this plugin requires >= {_REQUIRED_SOLWEIG_VERSION}"
+ )
+ return False
+
+ # Feature check: ensure the imported SurfaceData supports the API used by this plugin.
+ # This guards against environments where a different/old `solweig` package is importable
+ # (or where version strings are missing/non-standard).
+ missing: list[str] = []
+ surface_cls = getattr(solweig_module, "SurfaceData", None)
+ if surface_cls is None:
+ missing.append("SurfaceData")
+ else:
+ for method_name in ("preprocess", "fill_nan", "compute_valid_mask", "apply_valid_mask", "crop_to_valid_bbox"):
+ if not hasattr(surface_cls, method_name):
+ missing.append(f"SurfaceData.{method_name}()")
+
+ if missing:
+ _SOLWEIG_OUTDATED = True
+ _SOLWEIG_IMPORT_ERROR = (
+ "The imported solweig package is missing required APIs: "
+ + ", ".join(missing)
+ + f". Please upgrade solweig to >= {_REQUIRED_SOLWEIG_VERSION} and restart QGIS."
+ )
+ return False
+
+ return True
+
+
+def _setup_solweig_path():
+ """
+ Set up the import path for solweig library.
+
+ Priority:
+ 1. System-installed solweig (via pip)
+ 2. Development path (for local development)
+ """
+ global _SOLWEIG_AVAILABLE, _SOLWEIG_OUTDATED, _SOLWEIG_SOURCE, _SOLWEIG_IMPORT_ERROR, _SOLWEIG_INSTALLED_VERSION
+
+ # Already found in a previous call
+ if _SOLWEIG_AVAILABLE:
+ return
+
+ def _try_import_system() -> bool:
+ global _SOLWEIG_AVAILABLE, _SOLWEIG_SOURCE, _SOLWEIG_IMPORT_ERROR
+ try:
+ import solweig # noqa: F401
+
+ if not _check_version(solweig):
+ return False
+ _SOLWEIG_AVAILABLE = True
+ _SOLWEIG_SOURCE = "system"
+ _SOLWEIG_IMPORT_ERROR = None
+ return True
+ except ImportError:
+ return False
+
+ def _try_import_dev(dev_path: Path) -> bool:
+ global _SOLWEIG_AVAILABLE, _SOLWEIG_SOURCE, _SOLWEIG_IMPORT_ERROR
+ if not (dev_path.exists() and (dev_path / "solweig").exists()):
+ return False
+ inserted = False
+ if str(dev_path) not in sys.path:
+ sys.path.insert(0, str(dev_path))
+ inserted = True
+ try:
+ # If solweig was already imported (e.g. from a system install),
+ # remove the cached module so Python re-discovers it from pysrc/.
+ if "solweig" in sys.modules:
+ # Remove the main module and all submodules so the fresh
+ # import picks up the development source tree.
+ stale = [k for k in sys.modules if k == "solweig" or k.startswith("solweig.")]
+ for k in stale:
+ del sys.modules[k]
+
+ import solweig # noqa: F401
+
+ if not _check_version(solweig):
+ return False
+ _SOLWEIG_AVAILABLE = True
+ _SOLWEIG_SOURCE = "development"
+ _SOLWEIG_IMPORT_ERROR = None
+ return True
+ except ImportError:
+ _SOLWEIG_IMPORT_ERROR = "development import failed"
+ return False
+ finally:
+ # If dev import didn't succeed, keep sys.path clean.
+ if not _SOLWEIG_AVAILABLE and inserted and str(dev_path) in sys.path:
+ sys.path.remove(str(dev_path))
+
+ # Development mode - look for pysrc in parent directories
+ dev_paths = [
+ _PLUGIN_DIR.parent.parent / "pysrc", # repo_root/pysrc
+ _PLUGIN_DIR.parent.parent.parent / "pysrc", # One more level up
+ ]
+
+ # If we're running from a repository checkout (symlinked plugin), prefer local pysrc
+ # to avoid accidentally using an older system-installed solweig.
+ repo_root = _PLUGIN_DIR.parent.parent
+ prefer_dev = (repo_root / "pyproject.toml").exists() and (repo_root / "pysrc" / "solweig").exists()
+
+ if prefer_dev:
+ for dev_path in dev_paths:
+ if _try_import_dev(dev_path):
+ return
+ if _try_import_system():
+ return
+ else:
+ if _try_import_system():
+ return
+ for dev_path in dev_paths:
+ if _try_import_dev(dev_path):
+ return
+
+ # No solweig found
+ _SOLWEIG_AVAILABLE = False
+ _SOLWEIG_SOURCE = None
+ if _SOLWEIG_IMPORT_ERROR is None:
+ _SOLWEIG_IMPORT_ERROR = "solweig package not installed"
+
+
+def _install_solweig() -> tuple[bool, str]:
+ """
+ Install or upgrade solweig via pip in-process.
+
+ Uses pip's internal API rather than subprocess because QGIS embeds Python
+ and sys.executable points to the QGIS binary, not a usable Python interpreter.
+ See: https://github.com/qgis/QGIS/issues/45646
+
+ Returns:
+ Tuple of (success, message).
+ """
+ import contextlib
+ import io
+
+ try:
+ from pip._internal.cli.main import main as pip_main
+ except ImportError:
+ return False, "pip is not available in this QGIS Python environment."
+
+ try:
+ output = io.StringIO()
+ with contextlib.redirect_stdout(output), contextlib.redirect_stderr(output):
+ exit_code = pip_main(["install", "--upgrade", "solweig"])
+ if exit_code == 0:
+ return True, "SOLWEIG installed successfully."
+ return False, f"pip install failed (exit code {exit_code}):\n{output.getvalue()}"
+ except Exception as e:
+ return False, f"Installation failed: {e}"
+
+
+# Force GDAL backend before importing solweig — we know we're in QGIS,
+# so bypass _compat.py heuristic detection to avoid rasterio/numpy crashes.
+os.environ["UMEP_USE_GDAL"] = "1"
+
+# Run setup on module load
+_setup_solweig_path()
+
+
+def check_dependencies() -> tuple[bool, str]:
+ """
+ Check if all required dependencies are available.
+
+ Returns:
+ Tuple of (success, message)
+ """
+ if _SOLWEIG_AVAILABLE:
+ return True, f"SOLWEIG library loaded ({_SOLWEIG_SOURCE})"
+
+ if _SOLWEIG_OUTDATED:
+ msg = (
+ f"SOLWEIG {_SOLWEIG_INSTALLED_VERSION} is installed but this plugin "
+ f"requires >= {_REQUIRED_SOLWEIG_VERSION}.\n\n"
+ "To upgrade manually:\n\n"
+ " In OSGeo4W Shell (Windows) or Terminal (macOS/Linux):\n"
+ " pip install --upgrade solweig\n\n"
+ "After upgrading, restart QGIS."
+ )
+ return False, msg
+
+ error_hint = f"\nLast import error: {_SOLWEIG_IMPORT_ERROR}\n" if _SOLWEIG_IMPORT_ERROR else ""
+
+ msg = f"""SOLWEIG library not found.{error_hint}
+
+To install SOLWEIG manually:
+
+ In OSGeo4W Shell (Windows) or Terminal (macOS/Linux):
+ pip install solweig
+
+After installation, restart QGIS and re-enable the plugin.
+"""
+ return False, msg
+
+
+def _prompt_install():
+ """Offer to auto-install or upgrade solweig if it's missing or outdated."""
+ global _SOLWEIG_AVAILABLE, _SOLWEIG_OUTDATED, _SOLWEIG_SOURCE, _SOLWEIG_IMPORT_ERROR, _SOLWEIG_INSTALLED_VERSION
+
+ success, message = check_dependencies()
+ if success:
+ return
+
+ try:
+ from qgis.PyQt.QtWidgets import QMessageBox
+
+ if _SOLWEIG_OUTDATED:
+ title = "SOLWEIG Plugin - Update Required"
+ prompt = (
+ f"SOLWEIG {_SOLWEIG_INSTALLED_VERSION} is installed but this plugin "
+ f"requires >= {_REQUIRED_SOLWEIG_VERSION}.\n\n"
+ "Would you like to upgrade now?\n\n"
+ "This will run: pip install --upgrade solweig"
+ )
+ decline_msg = (
+ "SOLWEIG was not upgraded. You can upgrade manually:\n\n"
+ " pip install --upgrade solweig\n\n"
+ "Then restart QGIS."
+ )
+ else:
+ title = "SOLWEIG Plugin - Install Dependencies"
+ prompt = (
+ "The SOLWEIG library is required but not installed.\n\n"
+ "Would you like to install it now?\n\n"
+ "This will run: pip install solweig"
+ )
+ decline_msg = (
+ "SOLWEIG was not installed. You can install it manually:\n\n pip install solweig\n\nThen restart QGIS."
+ )
+
+ reply = QMessageBox.question(
+ None,
+ title,
+ prompt,
+ QMessageBox.Yes | QMessageBox.No,
+ QMessageBox.Yes,
+ )
+
+ if reply != QMessageBox.Yes:
+ QMessageBox.information(None, "SOLWEIG Plugin", decline_msg)
+ return
+
+ # Show a wait cursor while installing
+ from qgis.PyQt.QtCore import Qt
+ from qgis.PyQt.QtWidgets import QApplication
+
+ QApplication.setOverrideCursor(Qt.WaitCursor)
+ try:
+ ok, install_msg = _install_solweig()
+ finally:
+ QApplication.restoreOverrideCursor()
+
+ if ok:
+ # Reset state so _setup_solweig_path() can re-check
+ _SOLWEIG_AVAILABLE = False
+ _SOLWEIG_OUTDATED = False
+ _SOLWEIG_IMPORT_ERROR = None
+ _SOLWEIG_INSTALLED_VERSION = None
+
+ # Reload the module if it was already imported (upgrade case)
+ if "solweig" in sys.modules:
+ import importlib
+
+ importlib.reload(sys.modules["solweig"])
+
+ _setup_solweig_path()
+ if _SOLWEIG_AVAILABLE:
+ QMessageBox.information(
+ None,
+ "SOLWEIG Plugin",
+ "SOLWEIG installed successfully! The plugin is ready to use.",
+ )
+ else:
+ QMessageBox.information(
+ None,
+ "SOLWEIG Plugin",
+ "SOLWEIG installed successfully.\n\nPlease restart QGIS to complete setup.",
+ )
+ else:
+ QMessageBox.warning(
+ None,
+ "SOLWEIG Plugin - Installation Failed",
+ f"{install_msg}\n\nYou can try installing manually:\n\n pip install solweig\n\nThen restart QGIS.",
+ )
+
+ except ImportError:
+ # Not in QGIS environment
+ print(f"WARNING: {message}")
+
+
+# ---------------------------------------------------------------------------
+# Plugin entry point
+# ---------------------------------------------------------------------------
+
+from .provider import SolweigProvider # noqa: E402
+
+
+def classFactory(iface):
+ """
+ QGIS plugin entry point.
+
+ Called by QGIS when the plugin is loaded. Returns the provider instance
+ that will register all processing algorithms.
+
+ Args:
+ iface: QgisInterface instance providing access to QGIS components.
+
+ Returns:
+ SolweigPlugin instance that manages the processing provider.
+ """
+ return SolweigPlugin(iface)
+
+
+class SolweigPlugin:
+ """
+ Main plugin class that manages the SOLWEIG processing provider.
+
+ This class handles plugin lifecycle (load/unload) and registers
+ the SolweigProvider with QGIS Processing framework.
+ """
+
+ def __init__(self, iface):
+ self.iface = iface
+ self.provider = None
+
+ def initProcessing(self):
+ """Initialize the processing provider."""
+ from qgis.core import QgsApplication
+
+ self.provider = SolweigProvider()
+ QgsApplication.processingRegistry().addProvider(self.provider)
+
+ def initGui(self):
+ """Initialize the plugin GUI (called when plugin is activated)."""
+ # Register the Processing provider first — unconditionally — so
+ # SOLWEIG always appears in the Processing Toolbox even when the
+ # library isn't installed yet. Showing a QMessageBox during
+ # initGui() can fail or block on some platforms (especially macOS),
+ # which would prevent initProcessing() from ever being called.
+ self.initProcessing()
+
+ if not _SOLWEIG_AVAILABLE or _SOLWEIG_OUTDATED:
+ # Defer the install prompt to after the event loop starts,
+ # so it doesn't block plugin registration.
+ from qgis.PyQt.QtCore import QTimer
+
+ QTimer.singleShot(500, _prompt_install)
+
+ def unload(self):
+ """Unload the plugin (called when plugin is deactivated)."""
+ from qgis.core import QgsApplication
+
+ if self.provider:
+ QgsApplication.processingRegistry().removeProvider(self.provider)
+
+
+# ---------------------------------------------------------------------------
+# Module-level info for debugging
+# ---------------------------------------------------------------------------
+
+__solweig_available__ = _SOLWEIG_AVAILABLE
+__solweig_source__ = _SOLWEIG_SOURCE
diff --git a/qgis_plugin/solweig_qgis/_make_icon.py b/qgis_plugin/solweig_qgis/_make_icon.py
new file mode 100644
index 0000000..a10674c
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/_make_icon.py
@@ -0,0 +1,228 @@
+"""Generate the SOLWEIG QGIS plugin icon using Pillow.
+
+A fun sun-with-sunglasses over a city skyline with a thermometer.
+Palette: dark charcoal buildings, golden sun, red thermometer accent, white details.
+Run once to produce icon.png, then delete this script.
+"""
+
+import math
+import os
+
+from PIL import Image, ImageDraw
+
+# =============================================================================
+# Palette — at most 4 colours + sky gradient
+# =============================================================================
+DARK = (38, 42, 48) # charcoal — buildings, ground, sunglasses
+MID = (58, 64, 72) # lighter charcoal — alternate buildings
+GOLD = (255, 210, 50) # sun, rays, window glow
+RED = (230, 60, 50) # thermometer, antenna blink, grin
+WHITE = (255, 255, 255) # thermometer body, text, highlights
+
+SKY_TOP = (255, 107, 53) # warm orange (gradient only)
+SKY_MID = (247, 201, 72) # golden (gradient only)
+SKY_BOT = (135, 206, 235) # light blue (gradient only)
+
+
+def lerp_color(c1, c2, t):
+ return tuple(int(a + (b - a) * t) for a, b in zip(c1, c2))
+
+
+def draw_icon(size=128):
+ img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+ d = ImageDraw.Draw(img)
+ s = size / 64 # scale factor relative to 64px design
+
+ # --- Sky gradient background ---
+ for y in range(size):
+ t = y / size
+ color = lerp_color(SKY_TOP, SKY_MID, t / 0.5) if t < 0.5 else lerp_color(SKY_MID, SKY_BOT, (t - 0.5) / 0.5)
+ d.line([(0, y), (size - 1, y)], fill=color)
+
+ # Rounded corners mask
+ mask = Image.new("L", (size, size), 0)
+ mask_d = ImageDraw.Draw(mask)
+ mask_d.rounded_rectangle([0, 0, size - 1, size - 1], radius=int(8 * s), fill=255)
+ img.putalpha(mask)
+ d = ImageDraw.Draw(img)
+
+ # --- Sun glow ---
+ glow_img = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+ glow_d = ImageDraw.Draw(glow_img)
+ cx_sun, cy_sun = int(32 * s), int(13 * s)
+ for radius in range(int(22 * s), 0, -1):
+ t = radius / (22 * s)
+ alpha = int(55 * (1 - t))
+ glow_d.ellipse(
+ [cx_sun - radius, cy_sun - radius, cx_sun + radius, cy_sun + radius],
+ fill=(*GOLD[:3], alpha),
+ )
+ img = Image.alpha_composite(img, glow_img)
+ d = ImageDraw.Draw(img)
+
+ # --- Sun body ---
+ sr = int(9 * s)
+ d.ellipse(
+ [cx_sun - sr, cy_sun - sr, cx_sun + sr, cy_sun + sr],
+ fill=GOLD,
+ outline=(220, 180, 30),
+ width=max(1, int(s)),
+ )
+
+ # --- Sun rays ---
+ ray_inner = int(10.5 * s)
+ ray_outer = int(13 * s)
+ ray_w = max(1, int(1.8 * s))
+ for angle_deg in range(0, 360, 45):
+ if angle_deg == 180:
+ continue
+ a = math.radians(angle_deg)
+ x1 = cx_sun + int(ray_inner * math.sin(a))
+ y1 = cy_sun - int(ray_inner * math.cos(a))
+ x2 = cx_sun + int(ray_outer * math.sin(a))
+ y2 = cy_sun - int(ray_outer * math.cos(a))
+ d.line([(x1, y1), (x2, y2)], fill=GOLD, width=ray_w)
+
+ # --- Sunglasses (DARK) ---
+ gw, gh = int(3.2 * s), int(2.4 * s)
+ lx, ly = int(29 * s), int(12 * s)
+ rx, ry = int(35 * s), int(12 * s)
+ d.ellipse([lx - gw, ly - gh, lx + gw, ly + gh], fill=DARK)
+ d.ellipse([rx - gw, ry - gh, rx + gw, ry + gh], fill=DARK)
+ # Bridge + arms
+ bw = max(1, int(1.2 * s))
+ d.line([(lx + gw - int(s), ly), (rx - gw + int(s), ry)], fill=DARK, width=bw)
+ aw = max(1, int(s))
+ d.line([(lx - gw, ly - int(0.5 * s)), (lx - gw - int(2.5 * s), ly - int(2 * s))], fill=DARK, width=aw)
+ d.line([(rx + gw, ry - int(0.5 * s)), (rx + gw + int(2.5 * s), ry - int(2 * s))], fill=DARK, width=aw)
+ # Lens shine
+ shr = int(1.2 * s)
+ d.ellipse(
+ [lx - int(1.5 * s) - shr, ly - int(0.8 * s) - shr, lx - int(1.5 * s) + shr, ly - int(0.8 * s) + shr],
+ fill=(255, 255, 255, 70),
+ )
+ d.ellipse(
+ [rx - int(1.5 * s) - shr, ry - int(0.8 * s) - shr, rx - int(1.5 * s) + shr, ry - int(0.8 * s) + shr],
+ fill=(255, 255, 255, 70),
+ )
+
+ # --- Cheeky grin (RED) ---
+ d.arc([int(28.5 * s), int(14.5 * s), int(35.5 * s), int(19 * s)], 0, 180, fill=RED, width=max(1, int(1.3 * s)))
+
+ # --- Heat shimmer wavy lines (RED, semi-transparent) ---
+ heat_color = (*RED[:3], 90)
+ for hx in [int(15 * s), int(38 * s), int(52 * s)]:
+ for yy in range(int(22 * s), int(37 * s), int(1.5 * s) or 1):
+ offset = int(2 * s * math.sin(yy * 0.25))
+ for dx in range(max(1, int(0.8 * s))):
+ d.point((hx + offset + dx, yy), fill=heat_color)
+
+ # --- City skyline (DARK / MID only, GOLD windows) ---
+ # Buildings extend to y=64 (full bottom) so rounded mask clips them cleanly
+ buildings = [
+ # (x, y, w, h, color)
+ (4, 32, 8, 32, DARK),
+ (13, 37, 10, 27, MID),
+ (31, 30, 9, 34, DARK),
+ (41, 42, 10, 22, MID),
+ (52, 35, 8, 29, DARK),
+ ]
+
+ for bx, by, bw, bh, color in buildings:
+ x1, y1 = int(bx * s), int(by * s)
+ x2, y2 = int((bx + bw) * s), int((by + bh) * s)
+ d.rectangle([x1, y1, x2, y2], fill=color)
+
+ # Windows — GOLD only, varying alpha for life
+ wy = y1 + int(2 * s)
+ win_idx = 0
+ while wy + int(2 * s) < y2 - int(1 * s):
+ wx = x1 + int(1.5 * s)
+ while wx + int(2 * s) < x2 - int(0.5 * s):
+ alpha = [210, 140, 180, 100, 220, 160][win_idx % 6]
+ d.rectangle(
+ [wx, wy, wx + int(2 * s), wy + int(2 * s)],
+ fill=(*GOLD[:3], alpha),
+ )
+ wx += int(3.5 * s)
+ win_idx += 1
+ wy += int(4 * s)
+
+ # --- Tree (DARK trunk, MID canopy — stays monochromatic) ---
+ trunk_x = int(25.5 * s)
+ trunk_w = max(1, int(1 * s))
+ d.rectangle(
+ [trunk_x - trunk_w, int(48 * s), trunk_x + trunk_w, int(64 * s)],
+ fill=DARK,
+ )
+ tree_r = int(4.5 * s)
+ d.ellipse(
+ [trunk_x - tree_r, int(45 * s) - tree_r, trunk_x + tree_r, int(45 * s) + tree_r],
+ fill=MID,
+ )
+ d.ellipse(
+ [trunk_x - int(3 * s), int(46.5 * s) - int(3 * s), trunk_x + int(1 * s), int(46.5 * s) + int(3 * s)],
+ fill=(68, 75, 84), # slightly lighter MID variant
+ )
+ d.ellipse(
+ [trunk_x - int(1 * s), int(46.5 * s) - int(3 * s), trunk_x + int(3.5 * s), int(46.5 * s) + int(3 * s)],
+ fill=MID,
+ )
+
+ # --- Antenna on building 3 (DARK pole, RED blink) ---
+ ant_x = int(35.5 * s)
+ d.line([(ant_x, int(30 * s)), (ant_x, int(25 * s))], fill=MID, width=max(1, int(1.2 * s)))
+ br = int(1.2 * s)
+ d.ellipse([ant_x - br, int(25 * s) - br, ant_x + br, int(25 * s) + br], fill=RED)
+
+ # --- Ground strip (DARK, semi-transparent) — full width to bottom edge ---
+ d.rectangle([0, int(56 * s), size - 1, size - 1], fill=(*DARK[:3], 100))
+
+ # --- Thermometer (WHITE body, RED mercury) ---
+ tx = int(57 * s)
+ ty_top, ty_bot = int(3 * s), int(19 * s)
+ tw = int(1.8 * s)
+ bulb_r = int(3 * s)
+
+ # White body
+ d.rounded_rectangle(
+ [tx - tw, ty_top, tx + tw, ty_bot],
+ radius=tw,
+ fill=WHITE,
+ outline=(*DARK[:3], 120),
+ width=max(1, int(0.5 * s)),
+ )
+ # Red mercury
+ d.rounded_rectangle(
+ [tx - int(1 * s), int(6 * s), tx + int(1 * s), ty_bot],
+ radius=int(1 * s),
+ fill=RED,
+ )
+ # Red bulb
+ d.ellipse(
+ [tx - bulb_r, ty_bot - int(1 * s), tx + bulb_r, ty_bot + bulb_r + int(1 * s)],
+ fill=RED,
+ outline=(*DARK[:3], 120),
+ width=max(1, int(0.5 * s)),
+ )
+ # Tick marks (DARK)
+ for tick_y in [int(6 * s), int(9 * s), int(12 * s), int(15 * s)]:
+ d.line(
+ [(tx - tw - int(1 * s), tick_y), (tx - tw + int(0.5 * s), tick_y)],
+ fill=(*DARK[:3], 150),
+ width=max(1, int(0.5 * s)),
+ )
+
+ return img
+
+
+if __name__ == "__main__":
+ here = os.path.dirname(os.path.abspath(__file__))
+
+ icon_128 = draw_icon(128)
+ icon_128.save(os.path.join(here, "icon_128.png"))
+ print("Saved icon_128.png")
+
+ icon_64 = icon_128.resize((64, 64), Image.Resampling.LANCZOS)
+ icon_64.save(os.path.join(here, "icon.png"))
+ print("Saved icon.png (64x64)")
diff --git a/qgis_plugin/solweig_qgis/algorithms/__init__.py b/qgis_plugin/solweig_qgis/algorithms/__init__.py
new file mode 100644
index 0000000..ef34e4d
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/algorithms/__init__.py
@@ -0,0 +1 @@
+"""SOLWEIG Processing Algorithms."""
diff --git a/qgis_plugin/solweig_qgis/algorithms/base.py b/qgis_plugin/solweig_qgis/algorithms/base.py
new file mode 100644
index 0000000..5375ae5
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/algorithms/base.py
@@ -0,0 +1,438 @@
+"""
+Base algorithm class for SOLWEIG processing algorithms.
+
+Provides shared utilities for loading rasters, saving outputs,
+and integrating with QGIS.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+from osgeo import gdal
+from qgis.core import (
+ QgsProcessingAlgorithm,
+ QgsProcessingContext,
+ QgsProcessingException,
+ QgsProcessingFeedback,
+ QgsProject,
+ QgsRasterLayer,
+)
+from qgis.PyQt.QtCore import QCoreApplication
+
+if TYPE_CHECKING:
+ from numpy.typing import NDArray
+
+
+class SolweigAlgorithmBase(QgsProcessingAlgorithm):
+ """
+ Base class for all SOLWEIG processing algorithms.
+
+ Provides common functionality:
+ - Raster loading via GDAL
+ - Georeferenced output saving
+ - Thermal comfort styling for outputs
+ - Translation support
+ """
+
+ def tr(self, string: str) -> str:
+ """Translate string to current locale."""
+ return QCoreApplication.translate("SolweigProcessing", string)
+
+ def createInstance(self):
+ """Return new instance of algorithm."""
+ return self.__class__()
+
+ def group(self) -> str:
+ """Return algorithm group name (empty = directly under provider)."""
+ return ""
+
+ def groupId(self) -> str:
+ """Return algorithm group ID (empty = directly under provider)."""
+ return ""
+
+ def helpUrl(self) -> str:
+ """Return URL to algorithm documentation."""
+ return "https://umep-docs.readthedocs.io/"
+
+ # -------------------------------------------------------------------------
+ # SOLWEIG Import Helper
+ # -------------------------------------------------------------------------
+
+ def import_solweig(self):
+ """
+ Import the solweig library.
+
+ Returns:
+ The imported solweig module.
+
+ Raises:
+ QgsProcessingException: If solweig cannot be imported.
+ """
+ try:
+ from .. import check_dependencies
+
+ success, message = check_dependencies()
+ if not success:
+ raise QgsProcessingException(message)
+
+ import solweig
+
+ return solweig
+ except QgsProcessingException:
+ raise
+ except Exception as e:
+ raise QgsProcessingException("SOLWEIG library not found. Install it with: pip install solweig") from e
+
+ # -------------------------------------------------------------------------
+ # Raster Loading
+ # -------------------------------------------------------------------------
+
+ def load_raster_from_layer(self, layer: QgsRasterLayer) -> tuple[NDArray[np.floating], list[float], str]:
+ """
+ Load QGIS raster layer to numpy array using GDAL.
+
+ Args:
+ layer: QGIS raster layer to load.
+
+ Returns:
+ tuple of (array, geotransform, crs_wkt):
+ - array: 2D numpy float32 array
+ - geotransform: GDAL 6-tuple [x_origin, x_res, 0, y_origin, 0, -y_res]
+ - crs_wkt: Coordinate reference system as WKT string
+
+ Raises:
+ QgsProcessingException: If raster cannot be opened.
+ """
+ source = layer.source()
+ ds = gdal.Open(source, gdal.GA_ReadOnly)
+ if ds is None:
+ raise QgsProcessingException(f"Cannot open raster: {source}")
+
+ try:
+ band = ds.GetRasterBand(1)
+ array = band.ReadAsArray().astype(np.float32)
+
+ # Handle nodata — only honor negative sentinel values (e.g. -9999)
+ # to avoid converting valid zero-height pixels to NaN
+ nodata = band.GetNoDataValue()
+ if nodata is not None and nodata < 0:
+ array = np.where(array == nodata, np.nan, array)
+
+ geotransform = list(ds.GetGeoTransform())
+ crs_wkt = ds.GetProjection()
+
+ return array, geotransform, crs_wkt
+ finally:
+ ds = None # Close dataset
+
+ def load_optional_raster(
+ self,
+ parameters: dict[str, Any],
+ param_name: str,
+ context: QgsProcessingContext,
+ ) -> NDArray[np.floating] | None:
+ """
+ Load optional raster parameter, return None if not provided.
+
+ Args:
+ parameters: Algorithm parameters dict.
+ param_name: Name of the raster parameter.
+ context: Processing context.
+
+ Returns:
+ Numpy array if parameter provided, None otherwise.
+ """
+ if param_name not in parameters or not parameters[param_name]:
+ return None
+
+ layer = self.parameterAsRasterLayer(parameters, param_name, context)
+ if layer is None:
+ return None
+
+ array, _, _ = self.load_raster_from_layer(layer)
+ return array
+
+ def get_pixel_size_from_layer(self, layer: QgsRasterLayer) -> float:
+ """
+ Extract pixel size from raster layer.
+
+ Args:
+ layer: QGIS raster layer.
+
+ Returns:
+ Pixel size in meters (assumes square pixels).
+ """
+ source = layer.source()
+ ds = gdal.Open(source, gdal.GA_ReadOnly)
+ if ds is None:
+ raise QgsProcessingException(f"Cannot open raster: {source}")
+
+ try:
+ gt = ds.GetGeoTransform()
+ # gt[1] is x pixel size, gt[5] is y pixel size (negative)
+ pixel_size = abs(gt[1])
+ return pixel_size
+ finally:
+ ds = None
+
+ # -------------------------------------------------------------------------
+ # Output Saving
+ # -------------------------------------------------------------------------
+
+ def save_georeferenced_output(
+ self,
+ array: NDArray[np.floating],
+ output_path: str | Path,
+ geotransform: list[float],
+ crs_wkt: str,
+ nodata: float = -9999.0,
+ feedback: QgsProcessingFeedback | None = None,
+ ) -> str:
+ """
+ Save numpy array to GeoTIFF with proper georeferencing.
+
+ Uses Cloud-Optimized GeoTIFF (COG) format with LZW compression.
+
+ Args:
+ array: 2D numpy array to save.
+ output_path: Path for output GeoTIFF.
+ geotransform: GDAL geotransform [x_origin, x_res, 0, y_origin, 0, -y_res].
+ crs_wkt: Coordinate reference system as WKT string.
+ nodata: NoData value to use. Default -9999.
+ feedback: Optional feedback for progress reporting.
+
+ Returns:
+ Path to saved file.
+ """
+ output_path = str(output_path)
+
+ # Replace NaN with nodata
+ array_out = np.where(np.isnan(array), nodata, array).astype(np.float32)
+
+ # Create output directory if needed
+ os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
+
+ # Create GeoTIFF
+ driver = gdal.GetDriverByName("GTiff")
+ rows, cols = array_out.shape
+ ds = driver.Create(
+ output_path,
+ cols,
+ rows,
+ 1, # bands
+ gdal.GDT_Float32,
+ options=["COMPRESS=LZW", "TILED=YES"],
+ )
+
+ if ds is None:
+ raise QgsProcessingException(f"Cannot create output raster: {output_path}")
+
+ try:
+ ds.SetGeoTransform(geotransform)
+ ds.SetProjection(crs_wkt)
+
+ band = ds.GetRasterBand(1)
+ band.WriteArray(array_out)
+ band.SetNoDataValue(nodata)
+ band.FlushCache()
+ finally:
+ ds = None # Close and flush
+
+ if feedback:
+ feedback.pushInfo(f"Saved: {output_path}")
+
+ return output_path
+
+ def get_output_path(
+ self,
+ parameters: dict[str, Any],
+ param_name: str,
+ default_name: str,
+ context: QgsProcessingContext,
+ ) -> str:
+ """
+ Get output path from parameter or create temp file.
+
+ Args:
+ parameters: Algorithm parameters.
+ param_name: Output parameter name.
+ default_name: Default filename if not specified.
+ context: Processing context.
+
+ Returns:
+ Path for output file.
+ """
+ if param_name in parameters and parameters[param_name]:
+ output_dest = self.parameterAsOutputLayer(parameters, param_name, context)
+ if output_dest:
+ return output_dest
+
+ # Create temp file
+ temp_dir = Path(tempfile.gettempdir()) / "solweig_qgis_output"
+ temp_dir.mkdir(parents=True, exist_ok=True)
+ return str(temp_dir / default_name)
+
+ # -------------------------------------------------------------------------
+ # Canvas Integration
+ # -------------------------------------------------------------------------
+
+ def add_raster_to_canvas(
+ self,
+ path: str,
+ layer_name: str,
+ style: str | None = None,
+ context: QgsProcessingContext | None = None,
+ ) -> QgsRasterLayer:
+ """
+ Add raster layer to QGIS canvas with optional styling.
+
+ Args:
+ path: Path to raster file.
+ layer_name: Display name in layer panel.
+ style: Style preset ('tmrt', 'utci', 'pet', 'shadow', or None).
+ context: Processing context.
+
+ Returns:
+ The created QgsRasterLayer.
+
+ Raises:
+ QgsProcessingException: If layer cannot be loaded.
+ """
+ layer = QgsRasterLayer(path, layer_name)
+ if not layer.isValid():
+ raise QgsProcessingException(f"Cannot load output layer: {path}")
+
+ # Apply thermal comfort color ramp if requested
+ if style in ("tmrt", "utci", "pet"):
+ self.apply_thermal_comfort_style(layer, style)
+ elif style == "shadow":
+ self.apply_shadow_style(layer)
+
+ # Add to project
+ QgsProject.instance().addMapLayer(layer)
+
+ return layer
+
+ def apply_thermal_comfort_style(self, layer: QgsRasterLayer, style_type: str) -> None:
+ """
+ Apply thermal comfort color ramp for visualization.
+
+ Args:
+ layer: QgsRasterLayer to style.
+ style_type: 'tmrt', 'utci', or 'pet'.
+ """
+ from qgis.core import (
+ QgsColorRampShader,
+ QgsRasterShader,
+ QgsSingleBandPseudoColorRenderer,
+ )
+ from qgis.PyQt.QtGui import QColor
+
+ # Define color ramps based on style type
+ if style_type == "utci":
+ # UTCI thermal stress categories (ISO 7730 / Jendritzky et al. 2012)
+ color_points = [
+ (-40, QColor(0, 0, 128), "Extreme cold stress"),
+ (-27, QColor(0, 100, 200), "Very strong cold stress"),
+ (-13, QColor(51, 153, 255), "Strong cold stress"),
+ (0, QColor(153, 204, 255), "Moderate cold stress"),
+ (9, QColor(204, 255, 204), "Slight cold stress"),
+ (26, QColor(255, 255, 102), "No thermal stress"),
+ (32, QColor(255, 204, 51), "Moderate heat stress"),
+ (38, QColor(255, 128, 0), "Strong heat stress"),
+ (46, QColor(255, 51, 51), "Very strong heat stress"),
+ (60, QColor(128, 0, 0), "Extreme heat stress"),
+ ]
+ else: # tmrt, pet - use generic thermal ramp
+ color_points = [
+ (0, QColor(0, 0, 200), "Cold"),
+ (15, QColor(51, 153, 255), "Cool"),
+ (25, QColor(153, 255, 153), "Comfortable"),
+ (35, QColor(255, 255, 102), "Warm"),
+ (45, QColor(255, 153, 51), "Hot"),
+ (55, QColor(255, 51, 51), "Very hot"),
+ (70, QColor(128, 0, 0), "Extreme"),
+ ]
+
+ # Create shader
+ shader = QgsRasterShader()
+ ramp_shader = QgsColorRampShader()
+ ramp_shader.setColorRampType(QgsColorRampShader.Interpolated)
+
+ items = []
+ for value, color, label in color_points:
+ items.append(QgsColorRampShader.ColorRampItem(value, color, label))
+
+ ramp_shader.setColorRampItemList(items)
+ shader.setRasterShaderFunction(ramp_shader)
+
+ # Apply renderer
+ renderer = QgsSingleBandPseudoColorRenderer(
+ layer.dataProvider(),
+ 1, # band
+ shader,
+ )
+ layer.setRenderer(renderer)
+ layer.triggerRepaint()
+
+ def apply_shadow_style(self, layer: QgsRasterLayer) -> None:
+ """
+ Apply shadow mask styling (binary: sunlit/shadow).
+
+ Args:
+ layer: QgsRasterLayer to style.
+ """
+ from qgis.core import (
+ QgsColorRampShader,
+ QgsRasterShader,
+ QgsSingleBandPseudoColorRenderer,
+ )
+ from qgis.PyQt.QtGui import QColor
+
+ shader = QgsRasterShader()
+ ramp_shader = QgsColorRampShader()
+ ramp_shader.setColorRampType(QgsColorRampShader.Interpolated)
+
+ items = [
+ QgsColorRampShader.ColorRampItem(0, QColor(255, 255, 153), "Sunlit"),
+ QgsColorRampShader.ColorRampItem(1, QColor(102, 102, 102), "Shadow"),
+ ]
+
+ ramp_shader.setColorRampItemList(items)
+ shader.setRasterShaderFunction(ramp_shader)
+
+ renderer = QgsSingleBandPseudoColorRenderer(layer.dataProvider(), 1, shader)
+ layer.setRenderer(renderer)
+ layer.triggerRepaint()
+
+ # -------------------------------------------------------------------------
+ # Validation Helpers
+ # -------------------------------------------------------------------------
+
+ def check_grid_shapes_match(
+ self,
+ reference_shape: tuple[int, int],
+ arrays: dict[str, NDArray | None],
+ feedback: QgsProcessingFeedback,
+ ) -> None:
+ """
+ Verify all provided arrays match reference shape.
+
+ Args:
+ reference_shape: Expected (rows, cols) shape.
+ arrays: Dict of {name: array} to check (None values skipped).
+ feedback: For reporting errors.
+
+ Raises:
+ QgsProcessingException: If shapes don't match.
+ """
+ for name, arr in arrays.items():
+ if arr is not None and arr.shape != reference_shape:
+ raise QgsProcessingException(
+ f"Grid shape mismatch: {name} has shape {arr.shape}, expected {reference_shape} (matching DSM)"
+ )
diff --git a/qgis_plugin/solweig_qgis/algorithms/calculation/__init__.py b/qgis_plugin/solweig_qgis/algorithms/calculation/__init__.py
new file mode 100644
index 0000000..4567fce
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/algorithms/calculation/__init__.py
@@ -0,0 +1 @@
+"""Unified SOLWEIG calculation algorithm."""
diff --git a/qgis_plugin/solweig_qgis/algorithms/calculation/solweig_calculation.py b/qgis_plugin/solweig_qgis/algorithms/calculation/solweig_calculation.py
new file mode 100644
index 0000000..46db32b
--- /dev/null
+++ b/qgis_plugin/solweig_qgis/algorithms/calculation/solweig_calculation.py
@@ -0,0 +1,845 @@
+"""
+Unified SOLWEIG Calculation Algorithm
+
+Supports single timestep, EPW timeseries, or UMEP met timeseries,
+with optional tiled processing and UTCI/PET post-processing.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import numpy as np
+from qgis.core import (
+ QgsProcessingContext,
+ QgsProcessingException,
+ QgsProcessingFeedback,
+ QgsProcessingOutputFolder,
+ QgsProcessingOutputNumber,
+ QgsProcessingParameterBoolean,
+ QgsProcessingParameterDefinition,
+ QgsProcessingParameterEnum,
+ QgsProcessingParameterFile,
+ QgsProcessingParameterFolderDestination,
+)
+
+from ...utils.converters import (
+ create_human_params_from_parameters,
+ create_location_from_parameters,
+ create_weather_from_parameters,
+ load_prepared_surface,
+ load_weather_from_epw,
+ load_weather_from_umep_met,
+)
+from ...utils.parameters import (
+ add_date_filter_parameters,
+ add_epw_parameters,
+ add_human_body_parameters,
+ add_human_parameters,
+ add_location_parameters,
+ add_options_parameters,
+ add_umep_met_parameters,
+ add_weather_parameters,
+)
+from ..base import SolweigAlgorithmBase
+
+
+class SolweigCalculationAlgorithm(SolweigAlgorithmBase):
+ """
+ Unified SOLWEIG calculation algorithm.
+
+ Combines single timestep, timeseries, and optional UTCI/PET post-processing
+ into a single Processing algorithm. Large rasters are automatically tiled.
+ """
+
+ # Weather source enum values
+ WEATHER_SINGLE = 0
+ WEATHER_EPW = 1
+ WEATHER_UMEP = 2
+
+ def name(self) -> str:
+ return "solweig_calculation"
+
+ def displayName(self) -> str:
+ return self.tr("3. SOLWEIG Calculation")
+
+ def shortHelpString(self) -> str:
+ return self.tr(
+ """Calculate Mean Radiant Temperature (Tmrt) with SOLWEIG.
+
+Surface data:
+Provide the prepared surface directory from "Prepare Surface Data".
+All rasters (DSM, CDSM, DEM, walls) are loaded automatically.
+
+Weather modes:
+
+
Single timestep: Manual weather input for one date/time
+
EPW weather file: Load hourly data from an EnergyPlus Weather file
+
UMEP met file: Load from UMEP/SUEWS meteorological forcing files
+
+For timeseries modes, thermal state (ground heating/cooling) accumulates
+across timesteps for physically accurate results. Large rasters are
+automatically processed using overlapping tiles to manage memory.
+
+Post-processing (optional):
+
+
UTCI - fast polynomial (~200 timesteps/sec)
+
PET - iterative heat balance (~4 timesteps/sec, ~50x slower than UTCI)
+
+
+Outputs:
+GeoTIFF files organised into subfolders of the output directory:
+