Skip to main content

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}