qualia_core_db/q42/material_coupling/
dispersion.rs1use std::f64::consts::PI;
5
6use super::constitutive::{
7 Complex64, ConstitutiveError, ConstitutiveModel, C_0_M_PER_S, EPSILON_0_F_PER_M, MU_0_H_PER_M,
8};
9
10#[derive(Clone, Copy, Debug, PartialEq)]
12pub enum DispersionError {
13 Constitutive(ConstitutiveError),
14 EmptyOrInvalidFrequencyGrid,
15 PassivityViolation {
16 omega_rad_s: f64,
17 omega_im_epsilon: f64,
18 omega_im_mu: f64,
19 },
20 KramersKronigMismatch {
21 omega_rad_s: f64,
22 analytic_re_chi: f64,
23 reconstructed_re_chi: f64,
24 abs_error: f64,
25 tolerance: f64,
26 },
27 NegativeDispersiveEnergyDensity {
28 omega_rad_s: f64,
29 electric_term: f64,
30 magnetic_term: f64,
31 total_j_per_m3: f64,
32 },
33 ZeroFrequencyWavelengthRejected,
34 NonFiniteFieldComponent,
35}
36
37impl From<ConstitutiveError> for DispersionError {
38 fn from(e: ConstitutiveError) -> Self {
39 Self::Constitutive(e)
40 }
41}
42
43#[derive(Clone, Copy, Debug, PartialEq)]
45pub struct KramersKronigReport {
46 pub grid_points_checked: usize,
47 pub min_omega_im_eps_r: f64,
48 pub min_omega_im_mu_r: f64,
49 pub max_electric_kk_abs_error: f64,
50 pub max_magnetic_kk_abs_error: f64,
51 pub passivity_satisfied: bool,
52 pub causality_satisfied: bool,
53}
54
55pub fn verify_passivity_on_grid(
58 model: &ConstitutiveModel,
59 omega_grid_rad_s: &[f64],
60) -> Result<(f64, f64), DispersionError> {
61 model.validate()?;
62 if omega_grid_rad_s.is_empty() {
63 return Err(DispersionError::EmptyOrInvalidFrequencyGrid);
64 }
65 let mut min_e = f64::INFINITY;
66 let mut min_m = f64::INFINITY;
67 let mut prev = 0.0;
68 for &w in omega_grid_rad_s {
69 if !w.is_finite() || w <= prev {
70 return Err(DispersionError::EmptyOrInvalidFrequencyGrid);
71 }
72 prev = w;
73 let eps_r = model.relative_permittivity(w)?;
74 let mu_r = model.relative_permeability(w)?;
75 let w_im_e = w * eps_r.im;
76 let w_im_m = w * mu_r.im;
77 if w_im_e < -1e-15 || w_im_m < -1e-15 {
78 return Err(DispersionError::PassivityViolation {
79 omega_rad_s: w,
80 omega_im_epsilon: w_im_e * EPSILON_0_F_PER_M,
81 omega_im_mu: w_im_m * MU_0_H_PER_M,
82 });
83 }
84 min_e = min_e.min(w_im_e);
85 min_m = min_m.min(w_im_m);
86 }
87 Ok((min_e, min_m))
88}
89
90pub fn kramers_kronig_re_from_im<F>(
95 omega_target: f64,
96 omega_min: f64,
97 omega_max: f64,
98 quadrature_panels: usize,
99 im_chi_fn: F,
100) -> Result<f64, DispersionError>
101where
102 F: Fn(f64) -> Result<f64, ConstitutiveError>,
103{
104 if !omega_target.is_finite()
105 || !omega_min.is_finite()
106 || !omega_max.is_finite()
107 || omega_min <= 0.0
108 || omega_target <= omega_min
109 || omega_target >= omega_max
110 || quadrature_panels < 16
111 {
112 return Err(DispersionError::EmptyOrInvalidFrequencyGrid);
113 }
114
115 let im_target = im_chi_fn(omega_target)?;
116 let w_sq = omega_target * omega_target;
117 let h = (omega_max - omega_min) / (quadrature_panels as f64);
118
119 let mut integral = 0.0;
121 for i in 0..quadrature_panels {
122 let wp = omega_min + (i as f64 + 0.5) * h;
123 let diff = wp * wp - w_sq;
124 let integrand = if diff.abs() < 1e-12 * w_sq {
125 let delta = (1e-6 * omega_target).max(1e-9);
127 let im_plus = im_chi_fn(wp + delta)?;
128 let im_minus = im_chi_fn((wp - delta).max(0.5 * omega_min))?;
129 let d_im = (im_plus - im_minus) / (2.0 * delta);
130 (im_target + omega_target * d_im) / (2.0 * omega_target)
131 } else {
132 let im_wp = im_chi_fn(wp)?;
133 (wp * im_wp - omega_target * im_target) / diff
134 };
135 integral += integrand * h;
136 }
137
138 let log_arg = ((omega_max - omega_target) / (omega_max + omega_target))
139 * ((omega_min + omega_target) / (omega_target - omega_min));
140 let singular_term = (im_target / PI) * log_arg.abs().ln();
141
142 Ok((2.0 / PI) * integral + singular_term)
143}
144
145pub fn kramers_kronig_im_from_re<F>(
149 omega_target: f64,
150 omega_min: f64,
151 omega_max: f64,
152 quadrature_panels: usize,
153 re_chi_fn: F,
154) -> Result<f64, DispersionError>
155where
156 F: Fn(f64) -> Result<f64, ConstitutiveError>,
157{
158 if !omega_target.is_finite()
159 || !omega_min.is_finite()
160 || !omega_max.is_finite()
161 || omega_min <= 0.0
162 || omega_target <= omega_min
163 || omega_target >= omega_max
164 || quadrature_panels < 16
165 {
166 return Err(DispersionError::EmptyOrInvalidFrequencyGrid);
167 }
168
169 let re_target = re_chi_fn(omega_target)?;
170 let w_sq = omega_target * omega_target;
171 let h = (omega_max - omega_min) / (quadrature_panels as f64);
172
173 let mut integral = 0.0;
174 for i in 0..quadrature_panels {
175 let wp = omega_min + (i as f64 + 0.5) * h;
176 let diff = wp * wp - w_sq;
177 let integrand = if diff.abs() < 1e-12 * w_sq {
178 let delta = (1e-6 * omega_target).max(1e-9);
179 let re_plus = re_chi_fn(wp + delta)?;
180 let re_minus = re_chi_fn((wp - delta).max(0.5 * omega_min))?;
181 let d_re = (re_plus - re_minus) / (2.0 * delta);
182 d_re / (2.0 * omega_target)
183 } else {
184 let re_wp = re_chi_fn(wp)?;
185 (re_wp - re_target) / diff
186 };
187 integral += integrand * h;
188 }
189
190 let log_arg = ((omega_max - omega_target) / (omega_max + omega_target))
191 * ((omega_min + omega_target) / (omega_target - omega_min));
192 let singular_term = (re_target / PI) * log_arg.abs().ln();
193
194 Ok(-(2.0 * omega_target / PI) * integral - singular_term)
195}
196
197pub fn verify_kramers_kronig_consistency(
200 model: &ConstitutiveModel,
201 eval_omegas_rad_s: &[f64],
202 omega_min: f64,
203 omega_max: f64,
204 quadrature_panels: usize,
205 abs_tolerance: f64,
206) -> Result<KramersKronigReport, DispersionError> {
207 let (min_e, min_m) = verify_passivity_on_grid(model, eval_omegas_rad_s)?;
208 let mut max_e_err = 0.0f64;
209 let mut max_m_err = 0.0f64;
210
211 for &w in eval_omegas_rad_s {
212 let chi_e = model.bound_electric_susceptibility(w)?;
213 let recon_re_e = kramers_kronig_re_from_im(
214 w,
215 omega_min,
216 omega_max,
217 quadrature_panels,
218 |wp| Ok(model.bound_electric_susceptibility(wp)?.im),
219 )?;
220 let err_e = (chi_e.re - recon_re_e).abs();
221 if err_e > abs_tolerance {
222 return Err(DispersionError::KramersKronigMismatch {
223 omega_rad_s: w,
224 analytic_re_chi: chi_e.re,
225 reconstructed_re_chi: recon_re_e,
226 abs_error: err_e,
227 tolerance: abs_tolerance,
228 });
229 }
230 max_e_err = max_e_err.max(err_e);
231
232 let chi_m = model.bound_magnetic_susceptibility(w)?;
233 let recon_re_m = kramers_kronig_re_from_im(
234 w,
235 omega_min,
236 omega_max,
237 quadrature_panels,
238 |wp| Ok(model.bound_magnetic_susceptibility(wp)?.im),
239 )?;
240 let err_m = (chi_m.re - recon_re_m).abs();
241 if err_m > abs_tolerance {
242 return Err(DispersionError::KramersKronigMismatch {
243 omega_rad_s: w,
244 analytic_re_chi: chi_m.re,
245 reconstructed_re_chi: recon_re_m,
246 abs_error: err_m,
247 tolerance: abs_tolerance,
248 });
249 }
250 max_m_err = max_m_err.max(err_m);
251 }
252
253 Ok(KramersKronigReport {
254 grid_points_checked: eval_omegas_rad_s.len(),
255 min_omega_im_eps_r: min_e,
256 min_omega_im_mu_r: min_m,
257 max_electric_kk_abs_error: max_e_err,
258 max_magnetic_kk_abs_error: max_m_err,
259 passivity_satisfied: true,
260 causality_satisfied: true,
261 })
262}
263
264pub fn evaluate_brillouin_energy_density_j_per_m3(
269 model: &ConstitutiveModel,
270 omega_rad_s: f64,
271 e_peak_norm_sq: f64,
272 h_peak_norm_sq: f64,
273) -> Result<f64, DispersionError> {
274 if !e_peak_norm_sq.is_finite()
275 || !h_peak_norm_sq.is_finite()
276 || e_peak_norm_sq < 0.0
277 || h_peak_norm_sq < 0.0
278 {
279 return Err(DispersionError::NonFiniteFieldComponent);
280 }
281 let de = model.d_omega_re_epsilon_d_omega(omega_rad_s)?;
282 let dm = model.d_omega_re_mu_d_omega(omega_rad_s)?;
283 let u_e = 0.25 * de * e_peak_norm_sq;
284 let u_m = 0.25 * dm * h_peak_norm_sq;
285 let total = u_e + u_m;
286 if u_e < 0.0 || u_m < 0.0 || total < 0.0 {
287 return Err(DispersionError::NegativeDispersiveEnergyDensity {
288 omega_rad_s,
289 electric_term: u_e,
290 magnetic_term: u_m,
291 total_j_per_m3: total,
292 });
293 }
294 Ok(total)
295}
296
297#[derive(Clone, Copy, Debug, PartialEq)]
299pub struct EmWavePropagation {
300 pub omega_rad_s: f64,
301 pub complex_refractive_index: Complex64,
302 pub complex_impedance_ohms: Complex64,
303 pub complex_wavenumber_rad_per_m: Complex64,
304 pub phase_velocity_m_per_s: f64,
305 pub attenuation_neper_per_m: f64,
306 pub wavelength_m: f64,
307}
308
309pub fn evaluate_wave_propagation(
312 model: &ConstitutiveModel,
313 omega_rad_s: f64,
314) -> Result<EmWavePropagation, DispersionError> {
315 if !omega_rad_s.is_finite() || omega_rad_s <= 0.0 {
316 return Err(DispersionError::ZeroFrequencyWavelengthRejected);
317 }
318 let eps = model.permittivity_f_per_m(omega_rad_s)?;
319 let mu = model.permeability_h_per_m(omega_rad_s)?;
320 let eps_r = model.relative_permittivity(omega_rad_s)?;
321 let mu_r = model.relative_permeability(omega_rad_s)?;
322
323 let n_complex = eps_r.mul(mu_r).sqrt();
324 let z_complex = mu
325 .div(eps)
326 .ok_or(DispersionError::Constitutive(
327 ConstitutiveError::NonFiniteParameter,
328 ))?
329 .sqrt();
330 let k_complex = n_complex.scale(omega_rad_s / C_0_M_PER_S);
331 let re_k = k_complex.re.max(1e-30);
332 let phase_velocity_m_per_s = omega_rad_s / re_k;
333 let wavelength_m = (2.0 * PI) / re_k;
334
335 Ok(EmWavePropagation {
336 omega_rad_s,
337 complex_refractive_index: n_complex,
338 complex_impedance_ohms: z_complex,
339 complex_wavenumber_rad_per_m: k_complex,
340 phase_velocity_m_per_s,
341 attenuation_neper_per_m: k_complex.im,
342 wavelength_m,
343 })
344}
345
346#[derive(Clone, Copy, Debug, PartialEq, Eq)]
348pub enum EmAmplitudeConvention {
349 InstantaneousSnapshot,
350 PeakPhasor,
351 RmsPhasor,
352}
353
354#[derive(Clone, Copy, Debug, PartialEq)]
357pub struct InstantaneousOrPhasorFieldState {
358 pub poynting_w_per_m2: [f64; 3],
359 pub energy_density_j_per_m3: f64,
360 pub magnetic_field_h_a_per_m: [f64; 3],
361}
362
363pub fn evaluate_isotropic_eb_state(
367 e_v_per_m: [f64; 3],
368 b_tesla: [f64; 3],
369 epsilon_relative: f64,
370 mu_relative: f64,
371 convention: EmAmplitudeConvention,
372) -> Result<InstantaneousOrPhasorFieldState, DispersionError> {
373 if e_v_per_m.iter().any(|x| !x.is_finite())
374 || b_tesla.iter().any(|x| !x.is_finite())
375 || !epsilon_relative.is_finite()
376 || !mu_relative.is_finite()
377 || epsilon_relative <= 0.0
378 || mu_relative <= 0.0
379 {
380 return Err(DispersionError::NonFiniteFieldComponent);
381 }
382 let eps = EPSILON_0_F_PER_M * epsilon_relative;
383 let mu = MU_0_H_PER_M * mu_relative;
384 let h = [b_tesla[0] / mu, b_tesla[1] / mu, b_tesla[2] / mu];
385 let cross = [
386 e_v_per_m[1] * h[2] - e_v_per_m[2] * h[1],
387 e_v_per_m[2] * h[0] - e_v_per_m[0] * h[2],
388 e_v_per_m[0] * h[1] - e_v_per_m[1] * h[0],
389 ];
390 let e_sq = e_v_per_m[0] * e_v_per_m[0]
391 + e_v_per_m[1] * e_v_per_m[1]
392 + e_v_per_m[2] * e_v_per_m[2];
393 let h_sq = h[0] * h[0] + h[1] * h[1] + h[2] * h[2];
394
395 let factor = match convention {
396 EmAmplitudeConvention::InstantaneousSnapshot | EmAmplitudeConvention::RmsPhasor => 1.0,
397 EmAmplitudeConvention::PeakPhasor => 0.5,
398 };
399
400 let poynting_w_per_m2 = [cross[0] * factor, cross[1] * factor, cross[2] * factor];
401 let energy_density_j_per_m3 = factor * 0.5 * (eps * e_sq + mu * h_sq);
402
403 Ok(InstantaneousOrPhasorFieldState {
404 poynting_w_per_m2,
405 energy_density_j_per_m3,
406 magnetic_field_h_a_per_m: h,
407 })
408}