powerio_matrix/dcopf/limits.rs
1//! The thermal limit an OPF instance carries for one branch.
2//!
3//! Both OPF builders synthesize a bound for an unrated branch from
4//! [`Branch::synthesize_rate_a`](powerio_tx::Branch::synthesize_rate_a), read the
5//! window out of the same two fields, and apply the same unrated test, so the
6//! rule lives here once.
7
8/// The widest angle difference a branch may hold, in radians, from its
9/// converted `angmin`/`angmax` pair.
10///
11/// `angmin == angmax == 0` states no constraint, the MATPOWER spelling that
12/// `BalancedNetwork::to_normalized` widens to a pad, so a raw case and a normalized
13/// one describe the same branch. Reading that pair as a zero wide window would
14/// give a zero synthesized limit, which the instance then reads back as
15/// unlimited. A window wider than the half turn is held at `pi` by
16/// `synthesize_rate_a` itself.
17pub(crate) fn angle_window(angle_min_rad: f64, angle_max_rad: f64) -> f64 {
18 if angle_min_rad == 0.0 && angle_max_rad == 0.0 {
19 return std::f64::consts::PI;
20 }
21 angle_min_rad.abs().max(angle_max_rad.abs())
22}
23
24/// Which angle difference interval a synthesized thermal limit
25/// ([`Branch::synthesize_rate_a`](powerio_tx::Branch::synthesize_rate_a))
26/// spans for a branch the source left unrated.
27#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
28#[serde(rename_all = "snake_case")]
29#[non_exhaustive]
30pub enum SynthesizedLimitWindow {
31 /// The source's stated `angmin`/`angmax`, the window every release
32 /// before this option used.
33 #[default]
34 Stated,
35 /// The angle difference bounds the preparation selects and carries in
36 /// `angle_min`/`angle_max`. PowerModels pads the bounds before
37 /// `calc_thermal_limits!`, so with
38 /// [`AngleDifferenceBounds::PowerModelsPad`](powerio_tx::AngleDifferenceBounds::PowerModelsPad)
39 /// this reproduces its limit for an unconstrained branch.
40 SelectedBounds,
41}
42
43impl SynthesizedLimitWindow {
44 /// Whether this is [`Self::Stated`], the default.
45 #[must_use]
46 pub const fn is_stated(&self) -> bool {
47 matches!(self, Self::Stated)
48 }
49}
50
51/// The rule an OPF builder applies to every branch's thermal bound.
52///
53/// The three fields are settled once per instance, so a builder holds one of
54/// these across its branch loop.
55pub(crate) struct ThermalLimits {
56 /// Whether a branch the source left unrated gets a synthesized bound.
57 pub synthesize_unrated: bool,
58 /// Which angle difference interval a synthesized bound spans.
59 pub window: SynthesizedLimitWindow,
60 /// Multiplier that puts a stated `rate_a` in the selected unit system.
61 pub power_scale: f64,
62 /// Multiplier that puts an admittance in the selected unit system.
63 pub admittance_scale: f64,
64}
65
66impl ThermalLimits {
67 /// The bound for one branch.
68 ///
69 /// A branch the source left unlimited may get a synthesized bound. A
70 /// stated finite zero is never synthesized. That bound is per unit power
71 /// already, so it takes `admittance_scale` where a stated `rate_a` takes
72 /// `power_scale`. `stated` and `selected` are the branch's source angle
73 /// difference interval and the one the preparation carries, radians; the
74 /// synthesized bound spans the one `window` names.
75 pub(crate) fn of(
76 &self,
77 branch: &powerio_tx::Branch,
78 stated: (f64, f64),
79 selected: (f64, f64),
80 from: &powerio_tx::Bus,
81 to: &powerio_tx::Bus,
82 ) -> crate::Result<f64> {
83 let (angle_min_rad, angle_max_rad) = match self.window {
84 SynthesizedLimitWindow::Stated => stated,
85 SynthesizedLimitWindow::SelectedBounds => selected,
86 };
87 let limit = branch.rate_a;
88 if limit.is_nan() || limit < 0.0 {
89 return Err(powerio_tx::Error::InvalidThermalLimit { magnitude: limit }.into());
90 }
91 let (value, scale) = if self.synthesize_unrated && limit == f64::INFINITY {
92 let window = angle_window(angle_min_rad, angle_max_rad);
93 let value =
94 branch.synthesize_rate_a(window, (from.vmin, from.vmax), (to.vmin, to.vmax));
95 (value, self.admittance_scale)
96 } else {
97 (limit, self.power_scale)
98 };
99 let result = value * scale;
100 if !scale.is_finite()
101 || scale <= 0.0
102 || result.is_nan()
103 || result < 0.0
104 || (value.is_finite() && !result.is_finite())
105 || (value > 0.0 && result == 0.0)
106 {
107 return Err(powerio_tx::Error::InvalidThermalLimit { magnitude: result }.into());
108 }
109 Ok(result)
110 }
111}
112
113#[cfg(test)]
114mod tests {
115 use super::angle_window;
116
117 #[test]
118 fn the_window_is_the_wider_of_the_two_magnitudes() {
119 let window = 30.0_f64.to_radians();
120 assert!((angle_window(-window, window) - window).abs() < 1e-15);
121 assert!((angle_window(0.1, window) - window).abs() < 1e-15);
122 assert!((angle_window(-window, 0.1) - window).abs() < 1e-15);
123 }
124
125 #[test]
126 fn a_zero_pair_states_no_constraint() {
127 assert!((angle_window(0.0, 0.0) - std::f64::consts::PI).abs() < 1e-15);
128 }
129}