Tip
Need help? Please let us know in the SUEWS Community.
Please report issues with the manual on GitHub Issues (or use Report Issue for This Page for page-specific feedback).
Please cite SUEWS with proper information from our Zenodo page.
6.3.7.5. supy.util.attribute_u10#
- supy.util.attribute_u10(df_output_A: DataFrame, df_output_B: DataFrame, z_ref: float = 10.0, min_ustar: float = 0.01) AttributionResult[source]#
Decompose U10 (10m wind speed) differences between two SUEWS scenarios.
The difference in 10m wind speed is attributed to: - Forcing changes (u* - friction velocity / surface stress) - Roughness changes (z0m, zd - surface roughness characteristics) - Stability changes (psi_m - atmospheric stability correction)
- The attribution uses the logarithmic wind profile:
U10 = (u*/k) * [ln((z-d)/z0m) - psi_m(zeta)]
Where: - u* = friction velocity (m/s) - k = von Karman constant (0.4) - z = reference height (10m) - d = displacement height (m) - z0m = roughness length for momentum (m) - psi_m = stability correction for momentum - zeta = (z-d)/L = stability parameter
- Parameters:
df_output_A (pd.DataFrame) – SUEWS output DataFrame for scenario A (reference/baseline)
df_output_B (pd.DataFrame) – SUEWS output DataFrame for scenario B (modified/test)
z_ref (float, optional) – Reference height for wind speed (m). Default 10.0 m.
min_ustar (float, optional) – Minimum friction velocity threshold (m/s). Timesteps with abs(u*) < min_ustar are flagged. Default 0.01.
- Returns:
Container with contributions timeseries, summary statistics, and metadata.
- Return type:
Notes
The Shapley decomposition for the wind profile f = F * (R + S) where: - F = u*/k (forcing) - R = ln((z-d)/z0m) (roughness) - S = -psi_m (stability)
Yields exact closure: - Phi_forcing = dF * (P_A + P_B) / 2, where P = R + S - Phi_roughness = dR * (F_A + F_B) / 2 - Phi_stability = dS * (F_A + F_B) / 2
Examples
Compare baseline vs. increased roughness scenario:
>>> result = attribute_u10(df_output_baseline, df_output_urban) >>> print(result) U10 Attribution Results ======================================== Mean delta_U10: -1.23 m/s
6.3.7.5. Component Breakdown:#
forcing : -0.42 m/s (34.1%) roughness : -0.65 m/s (52.8%) stability : -0.16 m/s (13.0%)
>>> result.plot(kind="bar") # Visualise contributions