"""Solar Post-Processing and Capacity-Scaled Evaluation Pipeline. Converts dimensionless Capacity Factor (0.0 ~ 1.0) into physical Grid Units: 1. Power (kW) = CF * DC Capacity (kWp) 2. Inverter AC Clipping (derating if DC/AC ratio > 1.0) 3. Energy (kWh) = Power (kW) * Time Interval (hours) 4. Non-crossing Quantiles (P10 <= P50 <= P90) Power Scaling 5. Grid-Scale Error Metrics (kW and kWh scale MAE, RMSE, WAPE) """ from typing import Any, Optional import numpy as np from solarlab.geometry.solar_calculator import NIGHT_ZENITH_THRESHOLD_DEG def post_process_solar_predictions( capacity_factor: float | np.ndarray, capacity_kw: float | np.ndarray, sza_deg: Optional[float | np.ndarray] = None, interval_hours: float = 1.0, inverter_ac_kw: Optional[float | np.ndarray] = None, quantiles_cf: Optional[dict[str, float | np.ndarray]] = None, ) -> dict[str, Any]: """Apply physical post-processing and scale dimensionless predictions to physical units. Parameters ---------- capacity_factor : float or np.ndarray Model output capacity factor (0.0 ~ 1.0). capacity_kw : float or np.ndarray Installed DC solar capacity in kWp. sza_deg : float or np.ndarray, optional Solar zenith angle in degrees. If > 88°, power is forced to 0.0. interval_hours : float, default 1.0 Time interval (1.0 for hourly data, 0.5 for 30-min data). inverter_ac_kw : float or np.ndarray, optional Inverter AC maximum capacity limit. quantiles_cf : dict of str to float or ndarray, optional Predicted CF quantiles (e.g. {'P10': ..., 'P50': ..., 'P90': ...}). Returns ------- dict Dictionary containing physical post-processed outputs (power_kw, energy_kwh, etc.) """ cf_arr = np.clip(np.asarray(capacity_factor, dtype=np.float32), 0.0, 1.0) cap_arr = np.asarray(capacity_kw, dtype=np.float32) # 1. Night-time Zeroing Force if sza_deg is not None: sza_arr = np.asarray(sza_deg, dtype=np.float32) is_night = sza_arr > NIGHT_ZENITH_THRESHOLD_DEG cf_arr = np.where(is_night, 0.0, cf_arr) # 2. Power Conversion (kW) power_kw = cf_arr * cap_arr # 3. Inverter AC Limit Clipping if inverter_ac_kw is not None: inv_limit = np.asarray(inverter_ac_kw, dtype=np.float32) power_kw = np.minimum(power_kw, inv_limit) # Recalculate effective CF after inverter clipping cf_arr = np.where(cap_arr > 0, power_kw / cap_arr, 0.0) # 4. Energy Conversion (kWh) energy_kwh = power_kw * interval_hours # 5. Quantiles Scaling scaled_quantiles_power = {} scaled_quantiles_energy = {} if quantiles_cf: for q_name, q_val in quantiles_cf.items(): q_cf_clipped = np.clip(np.asarray(q_val, dtype=np.float32), 0.0, 1.0) if sza_deg is not None: q_cf_clipped = np.where(is_night, 0.0, q_cf_clipped) q_power = q_cf_clipped * cap_arr if inverter_ac_kw is not None: q_power = np.minimum(q_power, inv_limit) scaled_quantiles_power[q_name] = q_power scaled_quantiles_energy[q_name] = q_power * interval_hours is_scalar = np.ndim(capacity_factor) == 0 if is_scalar: return { "capacity_factor": float(np.round(cf_arr, 4)), "power_kw": float(np.round(power_kw, 3)), "energy_kwh": float(np.round(energy_kwh, 3)), "quantiles_power_kw": { k: float(np.round(v, 3)) for k, v in scaled_quantiles_power.items() }, "quantiles_energy_kwh": { k: float(np.round(v, 3)) for k, v in scaled_quantiles_energy.items() }, } return { "capacity_factor": cf_arr, "power_kw": power_kw, "energy_kwh": energy_kwh, "quantiles_power_kw": scaled_quantiles_power, "quantiles_energy_kwh": scaled_quantiles_energy, } def compute_capacity_scaled_metrics( y_true_cf: np.ndarray, y_pred_cf: np.ndarray, capacities_kw: np.ndarray, interval_hours: float = 1.0, ) -> dict[str, float]: """Compute grid-scale performance metrics in physical units (kW and kWh). Allows plant operators to directly view errors in tangible power and energy terms. """ y_true_cf = np.clip(np.asarray(y_true_cf, dtype=np.float64), 0.0, 1.0) y_pred_cf = np.clip(np.asarray(y_pred_cf, dtype=np.float64), 0.0, 1.0) capacities = np.asarray(capacities_kw, dtype=np.float64) # Actual and predicted power in kW p_true = y_true_cf * capacities p_pred = y_pred_cf * capacities # Actual and predicted energy in kWh e_true = p_true * interval_hours e_pred = p_pred * interval_hours # 1. Power-scale metrics (kW) mae_kw = float(np.mean(np.abs(p_true - p_pred))) rmse_kw = float(np.sqrt(np.mean((p_true - p_pred) ** 2))) sum_p_true = float(np.sum(p_true)) wape_kw_pct = float(np.sum(np.abs(p_true - p_pred)) / (sum_p_true + 1e-8)) * 100.0 # 2. Energy-scale metrics (kWh) mae_kwh = float(np.mean(np.abs(e_true - e_pred))) total_energy_true_kwh = float(np.sum(e_true)) total_energy_pred_kwh = float(np.sum(e_pred)) energy_bias_pct = ( float((total_energy_pred_kwh - total_energy_true_kwh) / (total_energy_true_kwh + 1e-8)) * 100.0 ) return { "mae_kw": round(mae_kw, 3), "rmse_kw": round(rmse_kw, 3), "wape_pct": round(wape_kw_pct, 2), "mae_kwh": round(mae_kwh, 3), "total_energy_true_kwh": round(total_energy_true_kwh, 1), "total_energy_pred_kwh": round(total_energy_pred_kwh, 1), "energy_bias_pct": round(energy_bias_pct, 2), }