Skip to main content

qualia_core_db/q42/material_coupling/
dispersion.rs

1//! Kramers-Kronig causality & passivity verification, Brillouin dispersive energy density,
2//! complex wave propagation parameters, and instantaneous vs phasor Poynting/energy relations.
3
4use 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/// Errors detected during Kramers-Kronig causality, passivity, or dispersive energy checks.
11#[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/// Summary report of Kramers-Kronig causality and passivity verification across a frequency grid.
44#[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
55/// Verify thermodynamic passivity ($\omega\operatorname{Im}\varepsilon(\omega) \ge 0$ and
56/// $\omega\operatorname{Im}\mu(\omega) \ge 0$) at every point on a strictly positive frequency grid.
57pub 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
90/// Reconstruct $\operatorname{Re}\chi(\omega)$ from $\operatorname{Im}\chi(\omega')$ via the
91/// Kramers-Kronig Cauchy principal value integral over $[\omega_{\min}, \omega_{\max}]$
92/// using analytical singularity subtraction:
93/// $$\operatorname{Re}\chi(\omega) = \frac{2}{\pi}\int_{\omega_{\min}}^{\omega_{\max}} \frac{\omega'\operatorname{Im}\chi(\omega') - \omega\operatorname{Im}\chi(\omega)}{\omega'^2 - \omega^2}\,d\omega' + \frac{\operatorname{Im}\chi(\omega)}{\pi}\ln\left|\frac{\omega_{\max}-\omega}{\omega_{\max}+\omega}\cdot\frac{\omega_{\min}+\omega}{\omega_{\min}-\omega}\right|$$
94pub 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    // Midpoint composite rule with explicit singularity subtraction avoids division by zero.
120    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            // L'Hopital limit: d/d(wp) [wp * Im(chi(wp))] / (2 * wp) via symmetric finite difference
126            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
145/// Reconstruct $\operatorname{Im}\chi(\omega)$ from $\operatorname{Re}\chi(\omega')$ via the inverse
146/// Kramers-Kronig Cauchy principal value integral over $[\omega_{\min}, \omega_{\max}]$:
147/// $$\operatorname{Im}\chi(\omega) = -\frac{2\omega}{\pi}\mathcal{P}\int_{\omega_{\min}}^{\omega_{\max}} \frac{\operatorname{Re}\chi(\omega') - \operatorname{Re}\chi(\omega)}{\omega'^2 - \omega^2}\,d\omega' - \frac{\operatorname{Re}\chi(\omega)}{\pi}\ln\left|\frac{\omega_{\max}-\omega}{\omega_{\max}+\omega}\cdot\frac{\omega_{\min}+\omega}{\omega_{\min}-\omega}\right|$$
148pub 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
197/// Perform a full Kramers-Kronig causality and passivity verification on `model` across
198/// interior test frequencies `eval_omegas_rad_s` using integration domain `[omega_min, omega_max]`.
199pub 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
264/// Evaluate Brillouin time-averaged stored dispersive electromagnetic energy density (in $\text{J}\cdot\text{m}^{-3}$)
265/// for peak-phasor electric field amplitude $|\mathbf{E}_{\text{peak}}|$ ($\text{V}\cdot\text{m}^{-1}$)
266/// and magnetic field amplitude $|\mathbf{H}_{\text{peak}}|$ ($\text{A}\cdot\text{m}^{-1}$):
267/// $$u_{\text{Brillouin}}(\omega) = \frac{1}{4}\frac{\partial(\omega\operatorname{Re}\varepsilon(\omega))}{\partial\omega}|\mathbf{E}_{\text{peak}}|^2 + \frac{1}{4}\frac{\partial(\omega\operatorname{Re}\mu(\omega))}{\partial\omega}|\mathbf{H}_{\text{peak}}|^2$$
268pub 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/// Wave propagation quantities at angular frequency $\omega > 0$ in a homogeneous isotropic medium.
298#[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
309/// Compute wave impedance, refractive index, wavenumber, phase speed, attenuation, and wavelength.
310/// Rejects zero or negative frequency per C02-C02 ("never evaluate $c/f$ at zero").
311pub 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/// Representation profile for harmonic or instantaneous field observations (C02-C02 / Mode 0).
347#[derive(Clone, Copy, Debug, PartialEq, Eq)]
348pub enum EmAmplitudeConvention {
349    InstantaneousSnapshot,
350    PeakPhasor,
351    RmsPhasor,
352}
353
354/// Instantaneous or cycle-averaged Poynting flux $\mathbf{S}$ ($\text{W}\cdot\text{m}^{-2}$) and
355/// nondispersive energy density $u$ ($\text{J}\cdot\text{m}^{-3}$) for EMF Mode 0 (`0x0100`).
356#[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
363/// Evaluate $\mathbf{H} = \mathbf{B}/\mu$, Poynting flux $\mathbf{S}$, and energy density $u$
364/// from $\mathbf{E}$ ($\text{V}\cdot\text{m}^{-1}$) and $\mathbf{B}$ ($\text{T}$) under an explicit
365/// `EmAmplitudeConvention` (PeakPhasor includes $1/2$, RmsPhasor and InstantaneousSnapshot do not).
366pub 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}