File size: 5,738 Bytes
833e75f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
"""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),
    }