Skip to main content

continuous_blocks/
vco.rs

1/// A voltage-controlled oscillator: given a frequency command (Hz, clamped to `[f_min,
2/// f_max]`), outputs a repeating ramp in `[0, 1)` — the same standard block block-diagram
3/// simulation tools provide (their own "VCO"/"Repeating Sequence" blocks), used here to build a
4/// frequency-modulated PWM carrier. LLC-family resonant converters regulate by switching
5/// *frequency*, not duty, unlike buck/boost, which is why this block exists alongside `Pid`
6/// rather than folding frequency modulation into `Pid` or into `dae-runtime` directly — a
7/// closed loop wires `Sum -> Pid -> Gain -> Vco` as separate, independently reusable blocks,
8/// the same way a real block-diagram tool would, rather than one function that hardcodes the
9/// whole topology.
10///
11/// Deliberately not a [`crate::StateSpace`]: the wraparound is a genuine discontinuity a
12/// linear system can't express, the same reason [`crate::math_ops::saturation`] is evaluated
13/// directly rather than folded into one. Composing `freq = f_nom + k*control` is the caller's
14/// job (chain a [`crate::math_ops::gain`] block, or a `Sum` with a constant, ahead of this
15/// one) — this block's only responsibility is the oscillator itself.
16#[derive(Debug, Clone, Copy, PartialEq)]
17pub struct Vco {
18    pub f_min: f64,
19    pub f_max: f64,
20}
21
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum VcoError {
24    FMinExceedsFMax,
25}
26
27impl Vco {
28    pub fn new(f_min: f64, f_max: f64) -> Result<Self, VcoError> {
29        if f_min > f_max {
30            return Err(VcoError::FMinExceedsFMax);
31        }
32        Ok(Vco { f_min, f_max })
33    }
34
35    /// Advances the oscillator by one step. `phase` is the previous step's output (in `[0,
36    /// 1)`, the block's own state), `freq_command` this step's input (Hz, clamped internally
37    /// to `[f_min, f_max]`), `dt` the step size. Returns the new phase, also in `[0, 1)`.
38    pub fn step(&self, phase: f64, freq_command: f64, dt: f64) -> f64 {
39        let freq = freq_command.clamp(self.f_min, self.f_max);
40        (phase + freq * dt).rem_euclid(1.0)
41    }
42}
43
44#[cfg(test)]
45mod tests {
46    use super::*;
47
48    #[test]
49    fn steps_at_the_commanded_frequency_before_wrapping() {
50        let vco = Vco::new(0.0, 200_000.0).unwrap();
51        let phase = vco.step(0.0, 100_000.0, 1e-8);
52        assert!((phase - 1e-3).abs() < 1e-12);
53    }
54
55    #[test]
56    fn wraps_around_at_one() {
57        let vco = Vco::new(0.0, 200_000.0).unwrap();
58        // freq=100_000, dt=1e-5 -> raw phase advance = 1.0 exactly -> wraps to 0.0
59        let phase = vco.step(0.0, 100_000.0, 1e-5);
60        assert!(phase.abs() < 1e-9);
61        // starting from 0.5, the same step should land back at 0.5
62        let phase2 = vco.step(0.5, 100_000.0, 1e-5);
63        assert!((phase2 - 0.5).abs() < 1e-9);
64    }
65
66    #[test]
67    fn clamps_frequency_command_to_range() {
68        let vco = Vco::new(50_000.0, 100_000.0).unwrap();
69        // command far above f_max should behave as if commanded exactly at f_max
70        let phase_over = vco.step(0.0, 1_000_000.0, 1e-8);
71        let phase_at_max = vco.step(0.0, 100_000.0, 1e-8);
72        assert_eq!(phase_over, phase_at_max);
73        // command far below f_min (even negative) should clamp to f_min
74        let phase_under = vco.step(0.0, -1_000_000.0, 1e-8);
75        let phase_at_min = vco.step(0.0, 50_000.0, 1e-8);
76        assert_eq!(phase_under, phase_at_min);
77    }
78
79    #[test]
80    fn f_min_exceeding_f_max_is_rejected_not_a_panic() {
81        assert_eq!(
82            Vco::new(200_000.0, 100_000.0),
83            Err(VcoError::FMinExceedsFMax)
84        );
85    }
86}