"""Deterministic monotone LightGBM alternative; concavity is not guaranteed.
Irradiance is constrained increasing and temperature decreasing. Tree-based
monotonicity is weaker than the analytic concavity of the physics model. Fit
only the accepted training partition and evaluate later chronological data.
Cite Ke et al. (2017) for LightGBM and Ascencio-Vásquez et al. (2020) for the
PV application. The thesis provides related project context; see REFERENCE_IDS
and energy_methods.references.
"""
from __future__ import annotations
from dataclasses import asdict, dataclass
import numpy as np
from lightgbm import LGBMRegressor
from numpy.typing import ArrayLike
from energy_methods._arrays import BoolArray, FloatArray, aligned
from energy_methods._regression import feature_labels, feature_matrix, training_arrays
REFERENCE_IDS = (
"ascencio_vasquez_2021_thesis",
"ascencio_vasquez_2020_modelling",
"ke_2017_lightgbm",
"lightgbm_parameters",
)
[docs]
@dataclass(frozen=True, slots=True)
class LightGBMConfig:
n_estimators: int = 200
learning_rate: float = 0.04
num_leaves: int = 15
min_child_samples: int = 20
min_samples: int = 48
n_jobs: int = 1
random_state: int = 42
def __post_init__(self) -> None:
if min(self.n_estimators, self.min_child_samples, self.min_samples, self.n_jobs) < 1:
raise ValueError(
"Training and worker counts must be positive; unlimited threads forbidden"
)
if not 0 < self.learning_rate <= 1 or self.num_leaves < 2:
raise ValueError("Invalid learning rate or tree size")
[docs]
@dataclass(slots=True)
class LightGBMModel:
estimator: LGBMRegressor
config: LightGBMConfig
training_scale_mwh: float
training_rows: int
poa_support_wm2: tuple[float, float]
temperature_support_c: tuple[float, float]
[docs]
def to_dict(self) -> dict[str, object]:
"""Export LightGBM's text model rather than unsafe pickle objects."""
return {
"method": "monotone_lightgbm",
"reference_ids": list(REFERENCE_IDS),
"config": asdict(self.config),
"model_text": self.estimator.booster_.model_to_string(),
"feature_order": ["poa_wm2", "temperature_c"],
"training_scale_mwh": self.training_scale_mwh,
"training_rows": self.training_rows,
"poa_support_wm2": list(self.poa_support_wm2),
"temperature_support_c": list(self.temperature_support_c),
"monotone_constraints": [1, -1],
"irradiance_concavity": "not_guaranteed",
}
[docs]
def predict(self, poa_wm2: ArrayLike, temperature_c: ArrayLike) -> FloatArray:
"""Mask invalid/out-of-domain weather and enforce the declared startup zero."""
poa, temperature = aligned(poa_wm2, temperature_c)
valid = np.isfinite(poa) & np.isfinite(temperature)
valid &= (poa >= 0) & (poa <= 1300) & (temperature >= -20) & (temperature <= 60)
result = np.full(len(poa), np.nan)
if valid.any():
prediction = np.asarray(
self.estimator.booster_.predict(
np.column_stack((poa[valid], temperature[valid])),
num_threads=self.config.n_jobs,
),
dtype=np.float64,
)
result[valid] = np.maximum(prediction, 0.0)
result[valid & (poa <= 1)] = 0.0
return result
[docs]
def weather_support(self, poa_wm2: ArrayLike, temperature_c: ArrayLike) -> BoolArray:
poa, temperature = aligned(poa_wm2, temperature_c)
return (
np.isfinite(poa)
& np.isfinite(temperature)
& (poa >= self.poa_support_wm2[0])
& (poa <= self.poa_support_wm2[1])
& (temperature >= self.temperature_support_c[0])
& (temperature <= self.temperature_support_c[1])
)
DEFAULT_CONFIG = LightGBMConfig()
[docs]
@dataclass(slots=True)
class LightGBMFeatureModel:
"""General forecast-feature regression; distinct from the monotone PV interface."""
estimator: LGBMRegressor
config: LightGBMConfig
feature_names: tuple[str, ...]
training_rows: int
[docs]
def predict(self, features: ArrayLike) -> FloatArray:
values = feature_matrix(features, len(self.feature_names))
return np.asarray(
self.estimator.booster_.predict(values, num_threads=self.config.n_jobs),
dtype=np.float64,
)
[docs]
def to_dict(self) -> dict[str, object]:
"""Export native model text; no unit transformation or implicit clipping."""
return {
"method": "lightgbm_feature_regression",
"reference_ids": ["ke_2017_lightgbm", "lightgbm_parameters"],
"config": asdict(self.config),
"model_text": self.estimator.booster_.model_to_string(),
"feature_names": list(self.feature_names),
"training_rows": self.training_rows,
}
[docs]
def fit_lightgbm_features(
features: ArrayLike,
target: ArrayLike,
*,
feature_names: tuple[str, ...] | None = None,
config: LightGBMConfig = DEFAULT_CONFIG,
) -> LightGBMFeatureModel:
"""Fit arbitrary finite forecast features without PV-only monotonic assumptions.
The existing ``fit_lightgbm(poa, temperature, actual)`` API is unchanged.
This interface also supports wind, lags and calendar variables. Feature
creation and chronological splitting remain the caller's responsibility.
"""
x, y = training_arrays(features, target, config.min_samples)
names = feature_labels(feature_names, x.shape[1])
estimator = LGBMRegressor(
objective="regression",
n_estimators=config.n_estimators,
learning_rate=config.learning_rate,
num_leaves=config.num_leaves,
min_child_samples=config.min_child_samples,
random_state=config.random_state,
n_jobs=config.n_jobs,
deterministic=True,
force_col_wise=True,
verbosity=-1,
)
estimator.fit(x, y)
return LightGBMFeatureModel(estimator, config, names, len(y))
[docs]
def fit_lightgbm(
poa_wm2: ArrayLike,
temperature_c: ArrayLike,
actual_mwh: ArrayLike,
*,
config: LightGBMConfig = DEFAULT_CONFIG,
) -> LightGBMModel:
"""Fit without random train/test splitting, early stopping or test-label access."""
poa, temperature, actual = aligned(poa_wm2, temperature_c, actual_mwh)
valid = np.isfinite(poa) & np.isfinite(temperature) & np.isfinite(actual) & (actual >= 0)
valid &= (poa >= 0) & (poa <= 1300) & (temperature >= -20) & (temperature <= 60)
if int(valid.sum()) < config.min_samples:
raise ValueError("Insufficient accepted finite LightGBM training rows")
poa, temperature, actual = poa[valid], temperature[valid], actual[valid]
scale = float(np.quantile(actual, 0.95, method="linear"))
if scale <= 0:
raise ValueError("Accepted-training Q95 energy must be positive")
estimator = LGBMRegressor(
objective="regression",
n_estimators=config.n_estimators,
learning_rate=config.learning_rate,
num_leaves=config.num_leaves,
min_child_samples=config.min_child_samples,
random_state=config.random_state,
n_jobs=config.n_jobs,
deterministic=True,
force_col_wise=True,
monotone_constraints=[1, -1],
monotone_constraints_method="advanced",
verbosity=-1,
)
estimator.fit(np.column_stack((poa, temperature)), actual)
return LightGBMModel(
estimator,
config,
scale,
len(actual),
(float(poa.min()), float(poa.max())),
(float(temperature.min()), float(temperature.max())),
)