use std::collections::HashMap;
use time::{Duration, OffsetDateTime, UtcOffset};
use crate::domain::{CarbonIntensity, ForecastPoint, HorizonBands, Measurement, ModelVersion};
const BAND_QUANTILE: f64 = 0.1;
pub const CLIMATOLOGY_ID: &str = "climatology";
pub const CLIMATOLOGY_VERSION: u32 = 1;
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ClimatologyParams {
pub step: Duration,
pub tau: Duration,
}
impl Default for ClimatologyParams {
fn default() -> Self {
Self {
step: Duration::minutes(15),
tau: Duration::days(14),
}
}
}
const MAX_STEPS: i64 = 100_000;
pub fn climatology_forecast(
history: &[Measurement],
from: OffsetDateTime,
horizon: Duration,
params: ClimatologyParams,
bands: Option<&HorizonBands>,
) -> Option<Vec<ForecastPoint>> {
let step_secs = params.step.whole_seconds();
let tau_secs = params.tau.whole_seconds() as f64;
if history.is_empty()
|| step_secs <= 0
|| tau_secs <= 0.0
|| horizon <= Duration::ZERO
|| horizon.whole_seconds() / step_secs > MAX_STEPS
{
return None;
}
let anchor = history.iter().max_by_key(|m| m.at)?;
let region = anchor.region;
let methodology = anchor.methodology.clone();
let model = ModelVersion::new(CLIMATOLOGY_ID, CLIMATOLOGY_VERSION);
let t0 = anchor.at;
let o = anchor.intensity.value();
let mut slots: HashMap<i64, Vec<f64>> = HashMap::new();
let mut all: Vec<f64> = Vec::with_capacity(history.len());
for m in history {
let v = m.intensity.value();
slots.entry(week_slot(m.at, step_secs)).or_default().push(v);
all.push(v);
}
all.sort_by(|a, b| a.total_cmp(b));
let end = from + horizon;
let mut points = Vec::new();
let mut t = from;
let climatology = |samples: Option<&Vec<f64>>| -> f64 {
match samples {
Some(s) if !s.is_empty() => s.iter().sum::<f64>() / s.len() as f64,
_ => all.iter().sum::<f64>() / all.len() as f64,
}
};
let bias = o - climatology(slots.get(&week_slot(t0, step_secs)));
while t < end {
let key = week_slot(t, step_secs);
let samples = slots.get(&key);
let mean = climatology(samples);
let dt = (t - t0).abs().whole_seconds() as f64;
let expected_value = (mean + bias * (-dt / tau_secs).exp()).max(0.0);
let (lower_value, upper_value) = match bands.and_then(|b| b.at(t - from)) {
Some((q_low, q_high)) => (
(expected_value + q_low).max(0.0),
(expected_value + q_high).max(expected_value),
),
None => {
let (low_off, high_off) = match samples {
Some(s) if s.len() >= 2 => band_offsets(s, mean),
_ => band_offsets(&all, mean),
};
(
(expected_value - low_off).max(0.0),
expected_value + high_off,
)
}
};
if let (Some(expected), Some(lower), Some(upper)) = (
CarbonIntensity::new(expected_value),
CarbonIntensity::new(lower_value),
CarbonIntensity::new(upper_value),
) {
points.push(ForecastPoint::new(
t,
region,
expected,
lower,
upper,
methodology.clone(),
model.clone(),
));
}
t += params.step;
}
Some(points)
}
pub(crate) fn band_offsets(samples: &[f64], mean: f64) -> (f64, f64) {
let mut sorted: Vec<f64> = samples.to_vec();
sorted.sort_by(|a, b| a.total_cmp(b));
let low = quantile(&sorted, BAND_QUANTILE);
let high = quantile(&sorted, 1.0 - BAND_QUANTILE);
((mean - low).max(0.0), (high - mean).max(0.0))
}
fn quantile(sorted: &[f64], q: f64) -> f64 {
if sorted.len() == 1 {
return sorted[0];
}
let rank = q.clamp(0.0, 1.0) * (sorted.len() - 1) as f64;
let lo = rank.floor() as usize;
let hi = rank.ceil() as usize;
let frac = rank - lo as f64;
sorted[lo] + (sorted[hi] - sorted[lo]) * frac
}
pub fn week_slot(t: OffsetDateTime, step_secs: i64) -> i64 {
let t = t.to_offset(UtcOffset::UTC);
let weekday = t.weekday().number_days_from_monday() as i64;
let secs_in_day = t.hour() as i64 * 3600 + t.minute() as i64 * 60 + t.second() as i64;
let slots_per_day = 86_400 / step_secs;
weekday * slots_per_day + secs_in_day / step_secs
}
#[cfg(test)]
mod tests {
use super::*;
use crate::domain::{Methodology, Region, Vintage};
fn history(
end: OffsetDateTime,
step: Duration,
count: usize,
value: impl Fn(OffsetDateTime) -> f64,
) -> Vec<Measurement> {
(0..count)
.map(|i| {
let at = end - step * ((count - i) as i32);
Measurement {
at,
region: Region::National,
intensity: CarbonIntensity::new(value(at)).unwrap(),
methodology: Methodology::rte_direct(),
vintage: Vintage::Tr,
mix: None,
}
})
.collect()
}
fn hourly_pattern(t: OffsetDateTime) -> f64 {
match t.hour() {
0..=5 => 20.0,
12..=17 => 80.0,
_ => 50.0,
}
}
#[test]
fn empty_history_returns_none() {
let from = OffsetDateTime::UNIX_EPOCH;
assert!(
climatology_forecast(
&[],
from,
Duration::hours(24),
ClimatologyParams::default(),
None
)
.is_none()
);
}
#[test]
fn invalid_params_return_none() {
let from = OffsetDateTime::UNIX_EPOCH;
let h = history(from, Duration::hours(1), 24, |_| 50.0);
assert!(
climatology_forecast(&h, from, Duration::ZERO, ClimatologyParams::default(), None)
.is_none()
);
let bad = ClimatologyParams {
step: Duration::ZERO,
tau: Duration::hours(6),
};
assert!(climatology_forecast(&h, from, Duration::hours(24), bad, None).is_none());
}
#[test]
fn count_matches_horizon_over_step() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(30);
let step = Duration::hours(1);
let h = history(from, step, 14 * 24, hourly_pattern);
let out = climatology_forecast(
&h,
from,
Duration::hours(24),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
assert_eq!(out.len(), 24);
}
#[test]
fn forecast_reproduces_weekly_pattern() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(60);
let step = Duration::hours(1);
let h = history(from, step, 14 * 24, hourly_pattern);
let out = climatology_forecast(
&h,
from,
Duration::hours(24),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
let night = out
.iter()
.find(|m| m.at.hour() == 3)
.unwrap()
.expected
.value();
let day = out
.iter()
.find(|m| m.at.hour() == 14)
.unwrap()
.expected
.value();
assert!((night - 20.0).abs() < 1.0, "nuit = {night}");
assert!((day - 80.0).abs() < 1.0, "jour = {day}");
assert!(night < day);
}
#[test]
fn persistence_correction_decays_with_horizon() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(90);
let step = Duration::hours(1);
let tau = Duration::hours(6);
let mut h = history(from, step, 14 * 24, hourly_pattern);
let anchor = h.last_mut().unwrap();
let anchor_climo = hourly_pattern(anchor.at);
anchor.intensity = CarbonIntensity::new(anchor_climo + 150.0).unwrap();
let out = climatology_forecast(
&h,
from,
Duration::hours(24),
ClimatologyParams { step, tau },
None,
)
.unwrap();
let near = &out[1]; let far = &out[18]; let near_excess = near.expected.value() - hourly_pattern(near.at);
let far_excess = far.expected.value() - hourly_pattern(far.at);
assert!(near_excess > 50.0, "près : excès = {near_excess}");
assert!(far_excess < 5.0, "loin : excès = {far_excess}");
assert!(near_excess > far_excess);
}
#[test]
fn unseen_slot_falls_back_to_overall_mean() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(120);
let step = Duration::hours(1);
let h = history(from, step, 6, |_| 42.0);
let out = climatology_forecast(
&h,
from,
Duration::hours(48),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
let late = out.last().unwrap().expected.value();
assert!((late - 42.0).abs() < 1e-9, "repli moyenne globale = {late}");
}
#[test]
fn forecast_points_carry_region_methodology_and_model() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(150);
let step = Duration::minutes(15);
let h = history(from, step, 96, |_| 30.0);
let out = climatology_forecast(
&h,
from,
Duration::hours(1),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
assert_eq!(out.len(), 4);
for p in &out {
assert_eq!(p.region, Region::National);
assert_eq!(p.methodology, Methodology::rte_direct());
assert_eq!(
p.model,
ModelVersion::new(CLIMATOLOGY_ID, CLIMATOLOGY_VERSION)
);
assert!(p.lower.value() <= p.expected.value());
assert!(p.expected.value() <= p.upper.value());
}
assert_eq!(out[0].at, from);
assert_eq!(out[1].at, from + step);
}
#[test]
fn band_widens_with_slot_dispersion() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(180);
let step = Duration::hours(1);
let h: Vec<Measurement> = (0..14 * 24)
.map(|i: i32| {
let at = from - step * (14 * 24 - i);
let g = if at.hour().is_multiple_of(2) {
if (at.unix_timestamp() / 86_400) % 2 == 0 {
0.0
} else {
100.0
}
} else {
50.0
};
Measurement {
at,
region: Region::National,
intensity: CarbonIntensity::new(g).unwrap(),
methodology: Methodology::rte_direct(),
vintage: Vintage::Tr,
mix: None,
}
})
.collect();
let out = climatology_forecast(
&h,
from,
Duration::hours(24),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
let width = |hour: u8| -> f64 {
let p = out.iter().find(|p| p.at.hour() == hour).unwrap();
p.upper.value() - p.lower.value()
};
assert!(
width(2) > width(3),
"créneau dispersé {} vs constant {}",
width(2),
width(3)
);
}
#[test]
fn never_negative() {
let from = OffsetDateTime::UNIX_EPOCH + Duration::days(200);
let step = Duration::hours(1);
let mut h = history(from, step, 48, |_| 5.0);
h.last_mut().unwrap().intensity = CarbonIntensity::new(0.0).unwrap();
let out = climatology_forecast(
&h,
from,
Duration::hours(6),
ClimatologyParams {
step,
tau: Duration::hours(6),
},
None,
)
.unwrap();
assert!(out.iter().all(|p| p.expected.value() >= 0.0));
assert!(out.iter().all(|p| p.lower.value() >= 0.0));
}
}