rustdf: address Codex review of the calibration converter

- tof_to_mz: solve the ModelType-2 quadratic in the numerically stable
  ("citardauq") form instead of Newton / the naive quadratic formula, which
  lost precision to cancellation when |c2| is tiny (kept ModelType-1 bit-exact).
- from_d_folder: reject unsupported MzCalibration/TimsCalibration ModelType
  values instead of silently falling through to the model-2 branch.
- Document BrukerFormulaConverter as a fixed-calibration converter that ignores
  the per-call frame_id (consistent with the other SDK-free converters).
- Fix stale read_mz_calibration comment that still claimed model 2 ignores c2.

Deferred (defensive-only / matches existing style): fallible constructors vs
.unwrap() on metadata reads, and guards for non-finite/zero coefficients that
real instrument calibration never produces.

Author: theGreatHerrLebert

rustdf/src/data/calibration.rs

@@ -91,10 +91,11 @@ impl MzCalibrator {
     /// TOF index -> m/z. Inverts `t = C0 + b*s + c2*s^2 + c3*s^3` for `s`.
     pub fn tof_to_mz(&self, tof_index: u32) -> f64 {
         let t = self.tof_index_to_time(tof_index as f64);
-        // Base (linear-in-sqrt) closed form, exact when c2 = c3 = 0.
-        let mut s = (t - self.c0) / self.b;
-        if self.c2 != 0.0 || self.c3 != 0.0 {
-            // Newton refinement for the ModelType-1 cubic curve.
+        // Linear-in-sqrt estimate; exact when c2 = c3 = 0.
+        let s0 = (t - self.c0) / self.b;
+        let s = if self.c3 != 0.0 {
+            // ModelType-1 cubic: Newton refinement from the linear estimate.
+            let mut s = s0;
             for _ in 0..8 {
                 let f = self.c0 + self.b * s + self.c2 * s * s + self.c3 * s * s * s - t;
                 let df = self.b + 2.0 * self.c2 * s + 3.0 * self.c3 * s * s;
@@ -107,7 +108,23 @@ impl MzCalibrator {
                     break;
                 }
             }
-        }
+            s
+        } else if self.c2 != 0.0 {
+            // ModelType-2 quadratic `c2*s^2 + b*s + (c0 - t) = 0`, solved in the
+            // numerically stable ("citardauq") form so the physical root does not
+            // lose precision to cancellation when |c2| is tiny. b > 0 always, so
+            // q < 0 and is never zero. Falls back to the linear estimate if the
+            // discriminant is negative (out-of-range tof).
+            let disc = self.b * self.b - 4.0 * self.c2 * (self.c0 - t);
+            if disc < 0.0 {
+                s0
+            } else {
+                let q = -0.5 * (self.b + disc.sqrt());
+                (self.c0 - t) / q
+            }
+        } else {
+            s0
+        };
         s * s - self.c4
     }
 

rustdf/src/data/handle.rs

@@ -363,6 +363,13 @@ impl IndexConverter for BrukerLibTimsDataConverter {
 ///     the same C0/C1/C2 quadratic-in-sqrt(m) curve and reproduces the SDK to a
 ///     few ppm (the proprietary ModelType-2 C8..C14 fine correction is not
 ///     modelled).
+///
+/// This is a **fixed-calibration** converter: it captures one frame's
+/// calibration rows + temperatures at build time and applies them to every
+/// frame, ignoring the per-call `frame_id` (like the other SDK-free converters
+/// `Simple`/`Calibrated`/`Lookup`). Valid because the coefficients are
+/// effectively constant across a run; use the SDK-backed `BrukerLib` converter
+/// if a run genuinely carries multiple calibration rows.
 pub struct BrukerFormulaConverter {
     pub mz: crate::data::calibration::MzCalibrator,
     pub im: crate::data::calibration::MobilityCalibrator,
@@ -396,6 +403,15 @@ impl BrukerFormulaConverter {
             .find(|c| c.id == tims_id)
             .ok_or("TimsCalibration row not found")?;
 
+        // Reject calibration models this converter does not implement, rather
+        // than silently mis-computing (m/z model 2 is the default branch).
+        if mzc.model_type != 1 && mzc.model_type != 2 {
+            return Err(format!("unsupported MzCalibration ModelType {}", mzc.model_type).into());
+        }
+        if tc.model_type != 2 {
+            return Err(format!("unsupported TimsCalibration ModelType {}", tc.model_type).into());
+        }
+
         let mz = MzCalibrator::new(
             mzc.model_type,
             mzc.digitizer_timebase,

rustdf/src/data/meta.rs

@@ -440,10 +440,10 @@ pub fn read_dia_ms_ms_windows(
 ///   tof_time = c0 + b*sqrt(m) + c2*m + c3*m^1.5,   b = sqrt(1e12 / c1)
 /// inverted to give m/z from a TOF index (see `data::calibration::MzCalibrator`).
 ///
-/// For model_type 2 (modern instruments) the base curve reduces to
-///   sqrt(mz) = (tof_time - c0) / sqrt(1e12 / c1)
-/// (c2/c3 are NOT curve terms in model 2). This base is accurate to ~10 ppm; the
-/// remaining error is a proprietary degree-6 correction polynomial in c8..c14.
+/// Model 2 (modern instruments) uses the same `c0 + b*sqrt(m) + c2*m` curve
+/// (c2 IS a curve term; only the c3 cubic term is model-1 only). That base is
+/// accurate to a few ppm; the remaining error is a proprietary correction in
+/// c8..c14 (windowed to [c5, c6]) that is not modelled.
 pub fn read_mz_calibration(
     bruker_d_folder_name: &str,
 ) -> Result<Vec<MzCalibration>, Box<dyn std::error::Error>> {