Skip to main content

qualia_core_db/specialized_libs/engineering_analysis/
vibration.rs

1use super::*;
2
3/// Vibration analysis
4pub struct VibrationAnalysis {
5    free_vibration: FreeVibration,
6    forced_vibration: ForcedVibration,
7    random_vibration: RandomVibration,
8}
9
10/// Free vibration
11#[derive(Debug, Clone)]
12pub struct FreeVibration {
13    pub natural_frequencies: Vec<f64>,
14    pub mode_shapes: Vec<ModeShape>,
15    pub damping_ratios: Vec<f64>,
16}
17
18/// Forced vibration
19#[derive(Debug, Clone)]
20pub struct ForcedVibration {
21    pub excitation_frequencies: Vec<f64>,
22    pub response_amplitudes: Vec<f64>,
23    pub phase_angles: Vec<f64>,
24}
25
26/// Random vibration
27#[derive(Debug, Clone)]
28pub struct RandomVibration {
29    pub power_spectral_density: Vec<f64>,
30    pub rms_response: f64,
31    pub fatigue_damage: f64,
32}
33impl VibrationAnalysis {
34    /// Creates a vibration analyzer with default components.
35    pub fn new() -> Self {
36        Self {
37            free_vibration: FreeVibration::new(),
38            forced_vibration: ForcedVibration::new(),
39            random_vibration: RandomVibration::new(),
40        }
41    }
42
43    /// Initializes sub-analyzers; `EngineeringError` propagates.
44    pub fn initialize(&mut self) -> Result<(), EngineeringError> {
45        Ok(())
46    }
47
48    /// Borrow the free-vibration sub-component.
49    pub fn free_vibration(&self) -> &FreeVibration {
50        &self.free_vibration
51    }
52
53    /// Mutably borrow the free-vibration sub-component.
54    pub fn free_vibration_mut(&mut self) -> &mut FreeVibration {
55        &mut self.free_vibration
56    }
57
58    /// Borrow the forced-vibration sub-component.
59    pub fn forced_vibration(&self) -> &ForcedVibration {
60        &self.forced_vibration
61    }
62
63    /// Mutably borrow the forced-vibration sub-component.
64    pub fn forced_vibration_mut(&mut self) -> &mut ForcedVibration {
65        &mut self.forced_vibration
66    }
67
68    /// Borrow the random-vibration sub-component.
69    pub fn random_vibration(&self) -> &RandomVibration {
70        &self.random_vibration
71    }
72
73    /// Mutably borrow the random-vibration sub-component.
74    pub fn random_vibration_mut(&mut self) -> &mut RandomVibration {
75        &mut self.random_vibration
76    }
77
78    /// Undamped free-vibration analysis of an `num_dofs`-DOF lumped-mass system.
79    /// Delegates to the same generalized eigenproblem as modal analysis
80    /// (`K φ = ω² M φ`, wired to `symmetric_eigen` via `solve_modal_eigen`) and
81    /// packs the result into [`FreeVibration`]: `natural_frequencies` are the
82    /// **natural angular frequencies ω (rad/s), ascending**, with their mass-
83    /// normalized mode shapes and zero damping ratios (undamped). Cached into
84    /// `self.free_vibration`.
85    pub fn analyze_free(
86        &mut self,
87        stiffness: &[f64],
88        mass_diag: &[f64],
89        num_dofs: usize,
90    ) -> Result<FreeVibration, EngineeringError> {
91        let modes = solve_modal_eigen(stiffness, mass_diag, num_dofs)?;
92        let mut natural_frequencies = Vec::with_capacity(modes.len());
93        let mut mode_shapes = Vec::with_capacity(modes.len());
94        for (i, (omega, phi)) in modes.into_iter().enumerate() {
95            natural_frequencies.push(omega);
96            mode_shapes.push(ModeShape {
97                mode_number: (i + 1) as u32,
98                natural_frequency: omega,
99                damping_ratio: 0.0,
100                mode_shape_vector: phi,
101            });
102        }
103        let damping_ratios = vec![0.0; natural_frequencies.len()];
104        let fv = FreeVibration {
105            natural_frequencies,
106            mode_shapes,
107            damping_ratios,
108        };
109        self.free_vibration = fv.clone();
110        Ok(fv)
111    }
112
113    /// Single-DOF undamped natural angular frequency `ω = √(k/m)` (rad/s).
114    pub fn natural_frequency_sdof(
115        &self,
116        stiffness: f64,
117        mass: f64,
118    ) -> Result<f64, EngineeringError> {
119        if mass <= 0.0 {
120            return Err(EngineeringError::ValidationError(
121                "mass must be positive".to_string(),
122            ));
123        }
124        if stiffness < 0.0 {
125            return Err(EngineeringError::ValidationError(
126                "stiffness must be non-negative".to_string(),
127            ));
128        }
129        Ok((stiffness / mass).sqrt())
130    }
131
132    /// Steady-state harmonic (forced-vibration) response of a damped single-DOF
133    /// oscillator `m·ẍ + c·ẋ + k·x = F₀·sin(ωt)`. For each excitation angular
134    /// frequency ω (rad/s) in `excitation_freqs`, returns the response amplitude
135    /// `X(ω) = F₀ / √((k − m·ω²)² + (c·ω)²)` and the phase lag
136    /// `φ(ω) = atan2(c·ω, k − m·ω²)` (rad). Genuine closed-form frequency-response
137    /// function; no fabricated values. Fills and returns [`ForcedVibration`].
138    pub fn analyze_harmonic_sdof(
139        &mut self,
140        mass: f64,
141        damping: f64,
142        stiffness: f64,
143        force_amplitude: f64,
144        excitation_freqs: &[f64],
145    ) -> Result<ForcedVibration, EngineeringError> {
146        if mass <= 0.0 {
147            return Err(EngineeringError::ValidationError(
148                "mass must be positive".to_string(),
149            ));
150        }
151        if damping < 0.0 || stiffness < 0.0 {
152            return Err(EngineeringError::ValidationError(
153                "damping and stiffness must be non-negative".to_string(),
154            ));
155        }
156        if excitation_freqs.is_empty() {
157            return Err(EngineeringError::InsufficientData(
158                "no excitation frequencies supplied".to_string(),
159            ));
160        }
161        let mut response_amplitudes = Vec::with_capacity(excitation_freqs.len());
162        let mut phase_angles = Vec::with_capacity(excitation_freqs.len());
163        for &w in excitation_freqs {
164            let re = stiffness - mass * w * w;
165            let im = damping * w;
166            let denom = (re * re + im * im).sqrt();
167            let amp = if denom > 0.0 {
168                force_amplitude / denom
169            } else {
170                f64::INFINITY
171            };
172            response_amplitudes.push(amp);
173            phase_angles.push(im.atan2(re));
174        }
175        let fv = ForcedVibration {
176            excitation_frequencies: excitation_freqs.to_vec(),
177            response_amplitudes,
178            phase_angles,
179        };
180        self.forced_vibration = fv.clone();
181        Ok(fv)
182    }
183}
184
185impl FreeVibration {
186    /// Creates a free-vibration config.
187    pub fn new() -> Self {
188        Self {
189            natural_frequencies: Vec::new(),
190            mode_shapes: Vec::new(),
191            damping_ratios: Vec::new(),
192        }
193    }
194}
195
196impl ForcedVibration {
197    /// Creates a forced-vibration config.
198    pub fn new() -> Self {
199        Self {
200            excitation_frequencies: Vec::new(),
201            response_amplitudes: Vec::new(),
202            phase_angles: Vec::new(),
203        }
204    }
205}
206
207impl RandomVibration {
208    /// Creates a random-vibration config.
209    pub fn new() -> Self {
210        Self {
211            power_spectral_density: Vec::new(),
212            rms_response: 0.0,
213            fatigue_damage: 0.0,
214        }
215    }
216}