Skip to main content

qualia_core_db/q42/emf_profiles/
iq.rs

1//! Packet E05: Calibrated RF I/Q baseband and STFT packets (mode 0x0105 / calibrated_iq_stft_v1)
2//! with bit-exact sample preservation, per-record CRC-32C, carrier reconstruction & DFT/STFT.
3
4use super::schemas::{i64_at, SignalKind, WindowKind};
5use super::yee::HarmonicSign;
6use super::*;
7use crate::container_10d::crc32c::crc32c_update;
8use core::f64::consts::PI;
9
10pub const IQ_PROFILE: &str = "calibrated_iq_stft_v1";
11pub const IQ_MODEL_URI: &str = "urn:qualia:emf:calibrated_iq_stft_v1";
12pub const IQ_CONVENTION: &str = "I_plus_iQ_exp_minus_iwt";
13pub const STFT_FFT_NORMALIZATION: &str = "forward-unscaled-inverse-1/N";
14pub const MAX_IQ_SAMPLES: u32 = 4096;
15pub const FLAG_LO_PHASE_KNOWN: u32 = 1 << 0;
16
17#[inline]
18pub fn iq_record_stride(sample_count: u32) -> Result<usize, Error> {
19    if !(1..=MAX_IQ_SAMPLES).contains(&sample_count) {
20        return Err(Error::Shape);
21    }
22    let payload_bytes = (sample_count as usize)
23        .checked_mul(16)
24        .ok_or(Error::Overflow)?;
25    let aligned = (payload_bytes + 63) & !63;
26    64usize.checked_add(aligned).ok_or(Error::Overflow)
27}
28
29pub fn iq_record_crc32c(record_bytes: &[u8]) -> Result<u32, Error> {
30    if record_bytes.len() < 80 {
31        return Err(Error::Shape);
32    }
33    let crc = crc32c_update(0xFFFF_FFFF, &record_bytes[..60]);
34    let crc = crc32c_update(crc, &[0u8; 4]);
35    Ok(!crc32c_update(crc, &record_bytes[64..]))
36}
37
38#[derive(Clone, Copy, Debug, PartialEq)]
39pub struct IqHeader {
40    pub first_sample_tick: i64,
41    pub sample_count: u32,
42    pub channel_index: u32,
43    pub centre_hz: f64,
44    pub lo_phase_rad: f64,
45    pub lo_phase_known: bool,
46    pub units_per_sample: f64,
47    pub calibration_metadata_id: u32,
48    pub acquisition_metadata_id: u32,
49    pub flags: u32,
50    pub record_crc32c: u32,
51}
52
53/// Non-mutating zero-copy view over an admitted mode 0x0105 record preserving original bits.
54#[derive(Clone, Copy, Debug)]
55pub struct IqPacketView<'a> {
56    pub header: IqHeader,
57    raw_iq_bytes: &'a [u8],
58}
59
60impl<'a> IqPacketView<'a> {
61    pub fn parse(bytes: &'a [u8], valid: bool) -> Result<Option<Self>, Error> {
62        if bytes.len() < 80 || !bytes.len().is_multiple_of(64) {
63            return Err(Error::Shape);
64        }
65        let n = u32_at(bytes, 8);
66        let expected_stride = iq_record_stride(n)?;
67        if bytes.len() != expected_stride {
68            return Err(Error::Shape);
69        }
70        zeros(&bytes[52..60])?;
71        let data_end = 64 + (n as usize) * 16;
72        zeros(&bytes[data_end..])?;
73        let stored_crc = u32_at(bytes, 60);
74        if iq_record_crc32c(bytes)? != stored_crc {
75            return Err(Error::Reserved);
76        }
77        if !valid {
78            zeros(&bytes[16..60])?;
79            zeros(&bytes[64..])?;
80            return Ok(None);
81        }
82        let flags = u32_at(bytes, 48);
83        if flags & !FLAG_LO_PHASE_KNOWN != 0 {
84            return Err(Error::Flags);
85        }
86        finite(bytes, 16, 40)?;
87        let centre_hz = f64_at(bytes, 16);
88        let lo_phase_known = flags & FLAG_LO_PHASE_KNOWN != 0;
89        let lo_phase_rad = if lo_phase_known {
90            f64_at(bytes, 24)
91        } else {
92            zeros(&bytes[24..32])?;
93            0.0
94        };
95        let units_per_sample = f64_at(bytes, 32);
96        if centre_hz < 0.0 || units_per_sample <= 0.0 {
97            return Err(Error::Value);
98        }
99        let raw_iq_bytes = &bytes[64..data_end];
100        for pair in raw_iq_bytes.chunks_exact(16) {
101            if !f64_at(pair, 0).is_finite() || !f64_at(pair, 8).is_finite() {
102                return Err(Error::NonFinite);
103            }
104        }
105        Ok(Some(Self {
106            header: IqHeader {
107                first_sample_tick: i64_at(bytes, 0),
108                sample_count: n,
109                channel_index: u32_at(bytes, 12),
110                centre_hz,
111                lo_phase_rad,
112                lo_phase_known,
113                units_per_sample,
114                calibration_metadata_id: u32_at(bytes, 40),
115                acquisition_metadata_id: u32_at(bytes, 44),
116                flags,
117                record_crc32c: stored_crc,
118            },
119            raw_iq_bytes,
120        }))
121    }
122
123    /// Returns exact unmodified IEEE-754 little-endian `(I, Q)` sample payload bytes.
124    pub fn raw_sample_bytes(&self) -> &'a [u8] {
125        self.raw_iq_bytes
126    }
127
128    pub fn raw_sample(&self, index: u32) -> Result<(f64, f64), Error> {
129        if index >= self.header.sample_count {
130            return Err(Error::Index);
131        }
132        let at = index as usize * 16;
133        Ok((f64_at(self.raw_iq_bytes, at), f64_at(self.raw_iq_bytes, at + 8)))
134    }
135
136    pub fn calibrated_sample(&self, index: u32) -> Result<(f64, f64), Error> {
137        let (i, q) = self.raw_sample(index)?;
138        let s = self.header.units_per_sample;
139        Ok((i * s, q * s))
140    }
141
142    pub fn extract_interleaved(&self, apply_scale: bool, out: &mut [(f64, f64)]) -> Result<usize, Error> {
143        let n = self.header.sample_count as usize;
144        if out.len() < n {
145            return Err(Error::Shape);
146        }
147        let s = if apply_scale { self.header.units_per_sample } else { 1.0 };
148        for (k, chunk) in self.raw_iq_bytes.chunks_exact(16).enumerate() {
149            out[k] = (f64_at(chunk, 0) * s, f64_at(chunk, 8) * s);
150        }
151        Ok(n)
152    }
153
154    pub fn extract_split(
155        &self,
156        apply_scale: bool,
157        out_i: &mut [f64],
158        out_q: &mut [f64],
159    ) -> Result<usize, Error> {
160        let n = self.header.sample_count as usize;
161        if out_i.len() < n || out_q.len() < n {
162            return Err(Error::Shape);
163        }
164        let s = if apply_scale { self.header.units_per_sample } else { 1.0 };
165        for (k, chunk) in self.raw_iq_bytes.chunks_exact(16).enumerate() {
166            out_i[k] = f64_at(chunk, 0) * s;
167            out_q[k] = f64_at(chunk, 8) * s;
168        }
169        Ok(n)
170    }
171
172    /// Verifies record metadata binding against Acquisition (136) and Calibration (107) blocks,
173    /// checking channel bounds, carrier consistency, tick validity `[from, until)`, and sample scale.
174    pub fn validate_against_blocks(
175        &self,
176        ext: Block<'_>,
177        acq: Block<'_>,
178        cal: Block<'_>,
179        raw_count_mode: bool,
180    ) -> Result<(), Error> {
181        if acq.schema_type() != 136 || cal.schema_type() != 107 {
182            return Err(Error::Shared(semantics::Error::ReferenceSchema));
183        }
184        if self.header.acquisition_metadata_id != acq.id()
185            || self.header.calibration_metadata_id != cal.id()
186        {
187            return Err(Error::Descriptor);
188        }
189        if scalar32(acq, 6)? != cal.id() {
190            return Err(Error::Descriptor);
191        }
192        if let Some(ext_n) = field(ext, 18) {
193            if u32_at(ext_n.value(), 0) != self.header.sample_count {
194                return Err(Error::Shape);
195            }
196        }
197        if let Some(ch_count) = field(acq, 13) {
198            if self.header.channel_index >= u32_at(ch_count.value(), 0) {
199                return Err(Error::Index);
200            }
201        }
202        if let Some(c_hz) = field(acq, 12) {
203            let expected_fc = f64_at(c_hz.value(), 0);
204            if (expected_fc - self.header.centre_hz).abs() > 1.0e-6 * expected_fc.max(1.0) {
205                return Err(Error::Value);
206            }
207        }
208        let kind = SignalKind::parse(text(required(acq, 4)?)?)?;
209        if kind == SignalKind::ComplexStft {
210            let fft_size = u32_at(required(acq, 9)?.value(), 0);
211            if self.header.sample_count != fft_size {
212                return Err(Error::Shape);
213            }
214        }
215        if !raw_count_mode && text(required(acq, 5)?)? != "counts" {
216            // Pre-calibrated packets carry units_per_sample == 1.0 with calibration as lineage.
217            if (self.header.units_per_sample - 1.0).abs() > 1.0e-12 {
218                return Err(Error::Value);
219            }
220        }
221        if let Some(vt) = field(cal, 8) {
222            let from = i64_at(vt.value(), 0);
223            let until = i64_at(vt.value(), 8);
224            let t = self.header.first_sample_tick;
225            if t < from || t >= until {
226                return Err(Error::Time);
227            }
228        }
229        Ok(())
230    }
231}
232
233pub fn encode_iq_packet(
234    header: &IqHeader,
235    iq_samples: &[(f64, f64)],
236    valid: bool,
237    out: &mut [u8],
238) -> Result<usize, Error> {
239    let n = iq_samples.len();
240    let count_u32 = u32::try_from(n).map_err(|_| Error::Shape)?;
241    if count_u32 != header.sample_count {
242        return Err(Error::Shape);
243    }
244    let stride = iq_record_stride(count_u32)?;
245    if out.len() < stride {
246        return Err(Error::Shape);
247    }
248    let buf = &mut out[..stride];
249    buf.fill(0);
250    buf[0..8].copy_from_slice(&header.first_sample_tick.to_le_bytes());
251    buf[8..12].copy_from_slice(&count_u32.to_le_bytes());
252    buf[12..16].copy_from_slice(&header.channel_index.to_le_bytes());
253    if valid {
254        if !header.centre_hz.is_finite()
255            || !header.lo_phase_rad.is_finite()
256            || !header.units_per_sample.is_finite()
257        {
258            return Err(Error::NonFinite);
259        }
260        if header.centre_hz < 0.0 || header.units_per_sample <= 0.0 {
261            return Err(Error::Value);
262        }
263        if header.flags & !FLAG_LO_PHASE_KNOWN != 0 {
264            return Err(Error::Flags);
265        }
266        let lo_phase = if header.flags & FLAG_LO_PHASE_KNOWN != 0 {
267            header.lo_phase_rad
268        } else {
269            if header.lo_phase_rad.to_bits() != 0 {
270                return Err(Error::Reserved);
271            }
272            0.0
273        };
274        for &(i_v, q_v) in iq_samples {
275            if !i_v.is_finite() || !q_v.is_finite() {
276                return Err(Error::NonFinite);
277            }
278        }
279        buf[16..24].copy_from_slice(&header.centre_hz.to_le_bytes());
280        buf[24..32].copy_from_slice(&lo_phase.to_le_bytes());
281        buf[32..40].copy_from_slice(&header.units_per_sample.to_le_bytes());
282        buf[40..44].copy_from_slice(&header.calibration_metadata_id.to_le_bytes());
283        buf[44..48].copy_from_slice(&header.acquisition_metadata_id.to_le_bytes());
284        buf[48..52].copy_from_slice(&header.flags.to_le_bytes());
285        for (idx, &(i_v, q_v)) in iq_samples.iter().enumerate() {
286            let at = 64 + idx * 16;
287            buf[at..at + 8].copy_from_slice(&i_v.to_le_bytes());
288            buf[at + 8..at + 16].copy_from_slice(&q_v.to_le_bytes());
289        }
290    }
291    let crc = iq_record_crc32c(buf)?;
292    buf[60..64].copy_from_slice(&crc.to_le_bytes());
293    Ok(stride)
294}
295
296/// Evaluates `s(t_n) = Re(z_n * exp(i * s * (2pi * f_c * (t_n - t_0) + phi_0)))`.
297/// Under canonical `HarmonicSign::MinusIwt`, `s = -1`: `I cos(theta) + Q sin(theta)`.
298pub fn reconstruct_rf_real_signal(
299    iq: &[(f64, f64)],
300    sample_rate_hz: f64,
301    carrier_hz: f64,
302    lo_phase_rad: f64,
303    t0_s: f64,
304    sign: HarmonicSign,
305    out_real: &mut [f64],
306) -> Result<(), Error> {
307    if !sample_rate_hz.is_finite()
308        || !carrier_hz.is_finite()
309        || !lo_phase_rad.is_finite()
310        || !t0_s.is_finite()
311    {
312        return Err(Error::NonFinite);
313    }
314    if sample_rate_hz <= 0.0 || carrier_hz < 0.0 {
315        return Err(Error::Value);
316    }
317    if out_real.len() < iq.len() {
318        return Err(Error::Shape);
319    }
320    let s = sign.sign_factor();
321    for (n, &(i_v, q_v)) in iq.iter().enumerate() {
322        if !i_v.is_finite() || !q_v.is_finite() {
323            return Err(Error::NonFinite);
324        }
325        let dt = (n as f64) / sample_rate_hz - t0_s;
326        let phase = s * (2.0 * PI * carrier_hz * dt + lo_phase_rad);
327        let (sin_p, cos_p) = phase.sin_cos();
328        out_real[n] = i_v * cos_p - q_v * sin_p;
329    }
330    Ok(())
331}
332
333/// Explicitly converts complex baseband between opposite RF carrier-sign conventions (`z -> conj(z)`).
334pub fn convert_carrier_sign_conjugate(src: &[(f64, f64)], dst: &mut [(f64, f64)]) -> Result<(), Error> {
335    if dst.len() < src.len() {
336        return Err(Error::Shape);
337    }
338    for (idx, &(i_v, q_v)) in src.iter().enumerate() {
339        if !i_v.is_finite() || !q_v.is_finite() {
340            return Err(Error::NonFinite);
341        }
342        dst[idx] = (i_v, -q_v);
343    }
344    Ok(())
345}
346
347#[inline]
348pub fn window_weight(kind: WindowKind, sample_idx: usize, length: usize) -> f64 {
349    match kind {
350        WindowKind::Rectangular => 1.0,
351        WindowKind::Hann => {
352            if length == 0 {
353                0.0
354            } else {
355                0.5 * (1.0 - (2.0 * PI * (sample_idx as f64) / (length as f64)).cos())
356            }
357        }
358    }
359}
360
361/// Forward DFT preserving raw signed FFT bin ordering (`forward-unscaled-inverse-1/N`).
362/// Does NOT sort bins or falsely attach schema 132 to signed baseband offsets.
363pub fn iq_dft_forward_unscaled(
364    samples: &[(f64, f64)],
365    window: Option<WindowKind>,
366    out_bins: &mut [(f64, f64)],
367) -> Result<(), Error> {
368    let n = samples.len();
369    if n == 0 || n > MAX_IQ_SAMPLES as usize || out_bins.len() < n {
370        return Err(Error::Shape);
371    }
372    for &(i_v, q_v) in samples {
373        if !i_v.is_finite() || !q_v.is_finite() {
374            return Err(Error::NonFinite);
375        }
376    }
377    let nf = n as f64;
378    for (k, bin) in out_bins[..n].iter_mut().enumerate() {
379        let mut re = 0.0f64;
380        let mut im = 0.0f64;
381        for (m, &(i_v, q_v)) in samples.iter().enumerate() {
382            let w = window.map_or(1.0, |wk| window_weight(wk, m, n));
383            let angle = -2.0 * PI * ((k * m) as f64) / nf;
384            let (s, c) = angle.sin_cos();
385            let xr = i_v * w;
386            let xi = q_v * w;
387            re += xr * c - xi * s;
388            im += xr * s + xi * c;
389        }
390        *bin = (re, im);
391    }
392    Ok(())
393}
394
395/// Inverse DFT with exact `1/N` normalization matching `forward-unscaled-inverse-1/N`.
396pub fn iq_idft_scaled(bins: &[(f64, f64)], out_samples: &mut [(f64, f64)]) -> Result<(), Error> {
397    let n = bins.len();
398    if n == 0 || n > MAX_IQ_SAMPLES as usize || out_samples.len() < n {
399        return Err(Error::Shape);
400    }
401    for &(re, im) in bins {
402        if !re.is_finite() || !im.is_finite() {
403            return Err(Error::NonFinite);
404        }
405    }
406    let nf = n as f64;
407    for (m, sample) in out_samples[..n].iter_mut().enumerate() {
408        let mut re = 0.0f64;
409        let mut im = 0.0f64;
410        for (k, &(br, bi)) in bins.iter().enumerate() {
411            let angle = 2.0 * PI * ((k * m) as f64) / nf;
412            let (s, c) = angle.sin_cos();
413            re += br * c - bi * s;
414            im += br * s + bi * c;
415        }
416        *sample = (re / nf, im / nf);
417    }
418    Ok(())
419}
420
421/// Signed FFT bin baseband frequency offset in Hz without reordering stored bins.
422pub fn signed_baseband_offset_hz(
423    bin_index: usize,
424    fft_size: usize,
425    sample_rate_hz: f64,
426) -> Result<f64, Error> {
427    if !sample_rate_hz.is_finite() {
428        return Err(Error::NonFinite);
429    }
430    if fft_size == 0 || bin_index >= fft_size || sample_rate_hz <= 0.0 {
431        return Err(Error::Shape);
432    }
433    let half = fft_size / 2;
434    let signed_k = if fft_size % 2 == 0 {
435        if bin_index < half {
436            bin_index as isize
437        } else {
438            bin_index as isize - fft_size as isize
439        }
440    } else if bin_index <= half {
441        bin_index as isize
442    } else {
443        bin_index as isize - fft_size as isize
444    };
445    Ok((signed_k as f64) * (sample_rate_hz / fft_size as f64))
446}
447
448/// Explicit permutation from native FFT order to strictly ascending physical frequencies (> 0 Hz).
449/// Fails closed if any mapped frequency is `<= 0 Hz` or if sign convention is not declared.
450pub fn fft_bins_to_ascending_physical(
451    bins: &[(f64, f64)],
452    sample_rate_hz: f64,
453    centre_hz: f64,
454    sign: HarmonicSign,
455    out_freqs_hz: &mut [f64],
456    out_bins: &mut [(f64, f64)],
457) -> Result<(), Error> {
458    let n = bins.len();
459    if n == 0 || out_freqs_hz.len() < n || out_bins.len() < n {
460        return Err(Error::Shape);
461    }
462    if !centre_hz.is_finite() || !sample_rate_hz.is_finite() {
463        return Err(Error::NonFinite);
464    }
465    if centre_hz <= 0.0 || sample_rate_hz <= 0.0 {
466        return Err(Error::Value);
467    }
468    let s = sign.sign_factor();
469    let neg_start = n.div_ceil(2);
470    let pos_top = (n - 1) / 2;
471    // Traverse signed bins in ascending physical frequency order explicitly.
472    for out_idx in 0..n {
473        let src_bin = match sign {
474            HarmonicSign::PlusIwt => (neg_start + out_idx) % n,
475            HarmonicSign::MinusIwt => (pos_top + n - out_idx) % n,
476        };
477        let off = signed_baseband_offset_hz(src_bin, n, sample_rate_hz)?;
478        let f_phys = centre_hz + s * off;
479        if f_phys <= 0.0 {
480            return Err(Error::Value);
481        }
482        if out_idx > 0 && f_phys <= out_freqs_hz[out_idx - 1] {
483            return Err(Error::Value);
484        }
485        out_freqs_hz[out_idx] = f_phys;
486        out_bins[out_idx] = bins[src_bin];
487    }
488    Ok(())
489}
490
491/// Rejects base complex-baseband signals violating Nyquist bound `|bw| <= Fs`
492/// unless explicitly admitted under a declared bandpass-sampling profile.
493pub fn check_complex_nyquist_band(
494    sample_rate_hz: f64,
495    occupied_bandwidth_hz: f64,
496    bandpass_admitted: bool,
497) -> Result<(), Error> {
498    if !sample_rate_hz.is_finite() || !occupied_bandwidth_hz.is_finite() {
499        return Err(Error::NonFinite);
500    }
501    if sample_rate_hz <= 0.0 || occupied_bandwidth_hz < 0.0 {
502        return Err(Error::Value);
503    }
504    if !bandpass_admitted && occupied_bandwidth_hz > sample_rate_hz {
505        return Err(Error::Value);
506    }
507    Ok(())
508}