use alloc::vec::Vec;
use bon::Builder;
use serde::{Deserialize, Serialize};
use super::common::CommodityQuantity;
use super::{Duration, Id, NumberRange, Timestamp};
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum PowerEnvelopeLimitType {
UpperLimit,
LowerLimit,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum PowerEnvelopeConsequenceType {
Vanish,
Defer,
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Builder)]
#[serde(deny_unknown_fields)]
pub struct AllowedLimitRange {
pub commodity_quantity: CommodityQuantity,
pub limit_type: PowerEnvelopeLimitType,
pub range_boundary: NumberRange,
pub abnormal_condition_only: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PowerEnvelopeElement {
pub duration: Duration,
pub upper_limit: f64,
pub lower_limit: f64,
}
impl PowerEnvelopeElement {
#[must_use]
pub const fn new(duration: Duration, lower_limit: f64, upper_limit: f64) -> Self {
Self {
duration,
upper_limit,
lower_limit,
}
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Builder)]
#[serde(deny_unknown_fields)]
pub struct PowerEnvelope {
pub id: Id,
pub commodity_quantity: CommodityQuantity,
pub power_envelope_elements: Vec<PowerEnvelopeElement>,
}
impl PowerEnvelope {
#[must_use]
pub fn total_duration(&self) -> Duration {
self.power_envelope_elements
.iter()
.fold(Duration::ZERO, |acc, e| {
acc.checked_add(e.duration).unwrap_or(acc)
})
}
#[must_use]
pub fn element_at(&self, offset: Duration) -> Option<&PowerEnvelopeElement> {
let mut elapsed = 0u64;
let target = offset.as_millis();
for element in &self.power_envelope_elements {
let end = elapsed.saturating_add(element.duration.as_millis());
if target < end {
return Some(element);
}
elapsed = end;
}
None
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Builder)]
#[serde(deny_unknown_fields)]
pub struct PowerConstraints {
#[cfg_attr(feature = "uuid", builder(default = Id::generate()))]
pub message_id: Id,
pub id: Id,
pub valid_from: Timestamp,
#[serde(skip_serializing_if = "Option::is_none")]
pub valid_until: Option<Timestamp>,
pub consequence_type: PowerEnvelopeConsequenceType,
pub allowed_limit_ranges: Vec<AllowedLimitRange>,
}
impl PowerConstraints {
#[must_use]
pub fn is_valid_at(&self, now: Timestamp) -> bool {
now >= self.valid_from && self.valid_until.is_none_or(|until| now < until)
}
pub fn ranges_for(
&self,
quantity: CommodityQuantity,
limit_type: PowerEnvelopeLimitType,
) -> impl Iterator<Item = &AllowedLimitRange> {
self.allowed_limit_ranges
.iter()
.filter(move |r| r.commodity_quantity == quantity && r.limit_type == limit_type)
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Builder)]
#[serde(deny_unknown_fields)]
pub struct EnergyConstraint {
#[cfg_attr(feature = "uuid", builder(default = Id::generate()))]
pub message_id: Id,
pub id: Id,
pub valid_from: Timestamp,
pub valid_until: Timestamp,
pub upper_average_power: f64,
pub lower_average_power: f64,
pub commodity_quantity: CommodityQuantity,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Builder)]
#[serde(deny_unknown_fields)]
pub struct Instruction {
#[cfg_attr(feature = "uuid", builder(default = Id::generate()))]
pub message_id: Id,
pub id: Id,
pub execution_time: Timestamp,
pub abnormal_condition: bool,
pub power_constraints_id: Id,
pub power_envelopes: Vec<PowerEnvelope>,
}
impl Instruction {
#[must_use]
pub fn envelope_for(&self, quantity: CommodityQuantity) -> Option<&PowerEnvelope> {
self.power_envelopes
.iter()
.find(|e| e.commodity_quantity == quantity)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_pv_example_from_the_docs_parses() {
let json = r#"{
"message_id": "aaaaaaaa-0000-0000-0000-000000000001",
"id": "powerConstraint1",
"valid_from": "2024-08-24T14:15:22Z",
"valid_until": "2024-08-25T14:15:22Z",
"consequence_type": "VANISH",
"allowed_limit_ranges": [
{
"commodity_quantity": "ELECTRIC.POWER.L1",
"limit_type": "LOWER_LIMIT",
"range_boundary": { "start_of_range": -4000, "end_of_range": 0 },
"abnormal_condition_only": false
},
{
"commodity_quantity": "ELECTRIC.POWER.L1",
"limit_type": "UPPER_LIMIT",
"range_boundary": { "start_of_range": 0, "end_of_range": 0 },
"abnormal_condition_only": false
}
]
}"#;
let c: PowerConstraints = serde_json::from_str(json).unwrap();
assert_eq!(c.id, "powerConstraint1");
assert_eq!(c.consequence_type, PowerEnvelopeConsequenceType::Vanish);
let lower: Vec<_> = c
.ranges_for(
CommodityQuantity::ElectricPowerL1,
PowerEnvelopeLimitType::LowerLimit,
)
.collect();
assert_eq!(lower.len(), 1);
assert!(lower[0].range_boundary.contains(-2000.0));
assert!(!lower[0].range_boundary.contains(-5000.0));
}
#[test]
fn validity_window_is_half_open_and_tolerates_an_open_end() {
let from: Timestamp = "2024-08-24T14:00:00Z".parse().unwrap();
let until: Timestamp = "2024-08-24T15:00:00Z".parse().unwrap();
let c = PowerConstraints {
message_id: Id::new_const("m1"),
id: Id::new_const("pc1"),
valid_from: from,
valid_until: Some(until),
consequence_type: PowerEnvelopeConsequenceType::Vanish,
allowed_limit_ranges: Vec::new(),
};
assert!(!c.is_valid_at("2024-08-24T13:59:59Z".parse().unwrap()));
assert!(c.is_valid_at(from));
assert!(c.is_valid_at("2024-08-24T14:59:59Z".parse().unwrap()));
assert!(!c.is_valid_at(until));
let open = PowerConstraints {
valid_until: None,
..c
};
assert!(open.is_valid_at("2099-01-01T00:00:00Z".parse().unwrap()));
}
#[test]
fn an_envelope_runs_out_rather_than_clamping() {
let e = PowerEnvelope {
id: Id::new_const("pe1"),
commodity_quantity: CommodityQuantity::ElectricPowerL1,
power_envelope_elements: alloc::vec![
PowerEnvelopeElement::new(Duration::from_secs(60), -2000.0, 0.0),
PowerEnvelopeElement::new(Duration::from_secs(60), -1000.0, 0.0),
],
};
assert_eq!(e.total_duration(), Duration::from_secs(120));
assert_eq!(e.element_at(Duration::ZERO).unwrap().lower_limit, -2000.0);
assert_eq!(
e.element_at(Duration::from_secs(59)).unwrap().lower_limit,
-2000.0
);
assert_eq!(
e.element_at(Duration::from_secs(60)).unwrap().lower_limit,
-1000.0
);
assert!(e.element_at(Duration::from_secs(120)).is_none());
}
}