Remove FactorLabel for simpler u32 representation

Author: leostimpfle

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project follows [Semantic Versioning](https://semver.org/).
 - A warm start that already solves the system reports `WarmStartExact` instead of `ZeroRhs`.
 - **BREAKING:** `ScalingConfig::max_sweeps` is now `max_iterations`, and `BuildWarning::UnscalableComponent` reports `iterations` in place of `sweeps`; the dominance certificate runs reduced CG, not relaxation sweeps.
 - **BREAKING:** The serialized `Preconditioner` wire format changed with the `approx-chol` 0.4 → 0.5 bump (v12 → v13), retention of the complete construction config (v13 → v14), retention of its original build duration (v14 → v15), and the new `LocalSolverConfig::ridge` field (v15 → v16); 0.3.0 bytes no longer decode.
+- **BREAKING:** Coefficient addresses now use caller-visible `u32` factor labels rather than internal `usize` level positions. This affects Rust `CoefficientAddress::level` and the accepted range of Python coefficient layout and unidentified-direction levels.
 
 ### Added
 

README.md

@@ -217,9 +217,8 @@ let r2 = solver.solve(&another_y, &LsmrOptions::default())?;  // reuses precondi
 | `SchurMode` | `Approximate(ApproxSchurConfig)` \| `Exact` |
 | `Preconditioner` | Opaque built handle — reuse via `Solver::new(.., precond)` (owned or `&`) |
 | `Effect` | `Effect::new(levels: &[u32], intercept: bool, slopes: impl IntoIterator<Item = &[f64]>) -> Result<Self, BuildError>` |
-| `FactorLabel` | Opaque caller-visible label; currently constructible from `u32` and readable with `try_as_u32()` |
-| `CoefficientAddress` | `{ channel: Channel { term, column }, level: FactorLabel }` |
-| `CoefficientLayout` | `index(&CoefficientAddress) -> Option<usize>`, `address(usize) -> Option<CoefficientAddress>`, `n_dofs()`, `n_terms()`, `n_levels(term)`, `n_columns(term)` |
+| `CoefficientAddress` | `{ channel: Channel { term, column }, level: u32 }` |
+| `CoefficientLayout` | `index(CoefficientAddress) -> Option<usize>`, `address(usize) -> Option<CoefficientAddress>`, `n_dofs()`, `n_terms()`, `n_levels(term)`, `n_columns(term)` |
 
 ### Varying slopes
 
@@ -241,8 +240,8 @@ let terms = vec![
 let r = solve(terms, &y, None, None, None)?;
 
 // Read firm level 3's x-slope via the layout map (column 0 = intercept, 1 = first slope):
-let at = CoefficientAddress { channel: Channel { term: 0, column: 1 }, level: 3.into() };
-println!("{}", r.x[r.layout.index(&at).unwrap()]);
+let at = CoefficientAddress { channel: Channel { term: 0, column: 1 }, level: 3 };
+println!("{}", r.x[r.layout.index(at).unwrap()]);
 ```
 
 `Solver::new` takes the same `Vec<Effect>`, so a slope design can be reused

crates/within-py/src/results.rs

@@ -117,9 +117,9 @@ impl PyCoefficientLayout {
     fn index(&self, term: usize, level: u32, column: usize) -> PyResult<usize> {
         let at = CoefficientAddress {
             channel: Channel { term, column },
-            level: level.into(),
+            level: level,
         };
-        self.inner.index(&at).ok_or_else(|| {
+        self.inner.index(at).ok_or_else(|| {
             PyIndexError::new_err(format!(
                 "coefficient address (term={term}, level={level}, column={column}) out of range"
             ))
@@ -129,13 +129,7 @@ impl PyCoefficientLayout {
     fn address(&self, index: usize) -> PyResult<(usize, u32, usize)> {
         self.inner
             .address(index)
-            .map(|at| {
-                (
-                    at.channel.term,
-                    at.level.try_as_u32().expect("u32 factor label"),
-                    at.channel.column,
-                )
-            })
+            .map(|at| (at.channel.term, at.level, at.channel.column))
             .ok_or_else(|| {
                 PyIndexError::new_err(format!(
                     "x index {index} out of range (n_dofs={})",
@@ -170,7 +164,7 @@ pub(crate) fn into_py_result(py: Python<'_>, result: SolveResult) -> PySolveResu
             .iter()
             .map(|u| PyUnidentifiedDirection {
                 term: u.channel.term,
-                level: u.level.try_as_u32().expect("u32 factor label"),
+                level: u.level,
                 column: u.channel.column,
             })
             .collect(),
@@ -205,7 +199,7 @@ pub(crate) fn into_py_batch_result(
             .iter()
             .map(|u| PyUnidentifiedDirection {
                 term: u.channel.term,
-                level: u.level.try_as_u32().expect("u32 factor label"),
+                level: u.level,
                 column: u.channel.column,
             })
             .collect(),

crates/within/src/domain.rs

@@ -78,36 +78,6 @@ impl<T> Loading<T> {
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-enum FactorLabelValue {
-    U32(u32),
-}
-
-/// A caller-visible factor label.
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct FactorLabel(FactorLabelValue);
-
-impl FactorLabel {
-    /// Return the label as `u32`, or `None` when it has another representation.
-    pub fn try_as_u32(&self) -> Option<u32> {
-        match self.0 {
-            FactorLabelValue::U32(value) => Some(value),
-        }
-    }
-}
-
-impl From<u32> for FactorLabel {
-    fn from(value: u32) -> Self {
-        Self(FactorLabelValue::U32(value))
-    }
-}
-
-impl From<&FactorLabel> for FactorLabel {
-    fn from(value: &FactorLabel) -> Self {
-        value.clone()
-    }
-}
-
 /// Mapping between caller-visible factor labels and numerical level positions.
 ///
 /// This is an identity mapping for the existing dense `u32` API. Later
@@ -126,16 +96,16 @@ impl FactorEncoding {
         self.n_levels
     }
 
-    pub(crate) fn position(&self, label: &FactorLabel) -> Option<usize> {
-        let position = label.try_as_u32()? as usize;
+    pub(crate) fn position(&self, label: u32) -> Option<usize> {
+        let position = label as usize;
         (position < self.n_levels).then_some(position)
     }
 
-    pub(crate) fn label(&self, position: usize) -> Option<FactorLabel> {
+    pub(crate) fn label(&self, position: usize) -> Option<u32> {
         if position >= self.n_levels {
             return None;
         }
-        u32::try_from(position).ok().map(FactorLabel::from)
+        u32::try_from(position).ok()
     }
 }
 
@@ -484,14 +454,6 @@ mod tests {
         ));
     }
 
-    #[test]
-    fn u32_factor_label_round_trips() {
-        let label = FactorLabel::from(u32::MAX);
-
-        assert_eq!(label.try_as_u32(), Some(u32::MAX));
-        assert_eq!(FactorLabel::from(&label), label);
-    }
-
     #[test]
     fn validate_weights_checks_count_and_finiteness() {
         let design = Design::from_frame(frame(vec![vec![0, 0, 0, 0, 0]], vec![])).unwrap();

crates/within/src/lib.rs

@@ -42,7 +42,7 @@ pub use config::{
     ApproxCholConfig, ApproxSchurConfig, LocalSolverConfig, LsmrOptions, PreconditionerConfig,
     ReductionStrategy, ScalingConfig, ScalingFailure, SchurMode,
 };
-pub use domain::{Design, Effect, FactorLabel};
+pub use domain::{Design, Effect};
 pub use error::{BuildError, BuildWarning, SolveError, WithinError};
 pub use operator::schwarz::Preconditioner;
 pub use solver::{

crates/within/src/solver.rs

@@ -18,7 +18,7 @@ use crate::observation::ObservationFrame;
 use crate::operator::design::gather_apply;
 use crate::operator::schwarz::{build_preconditioner, Preconditioner};
 use crate::operator::DesignOperator;
-use crate::{BuildError, BuildWarning, FactorLabel, SolveError, WithinError};
+use crate::{BuildError, BuildWarning, SolveError, WithinError};
 
 mod reparam;
 #[cfg(test)]
@@ -112,21 +112,21 @@ impl From<&Preconditioner> for PreconditionerInput {
 }
 
 /// One coefficient of the design: a [`Channel`] at one level of its term.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct CoefficientAddress {
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Coefficient<L> {
     /// The coefficient column this address sits in.
     pub channel: Channel,
-    /// Caller-visible factor label.
-    pub level: FactorLabel,
+    /// The level, in whichever space `L` names.
+    pub level: L,
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-struct CoefficientPosition {
-    channel: Channel,
-    level: usize,
-}
+/// A coefficient addressed by the caller's own factor label.
+pub type CoefficientAddress = Coefficient<u32>;
+
+/// A coefficient addressed by its internal compact position.
+type CoefficientPosition = Coefficient<usize>;
 
-impl CoefficientPosition {
+impl Coefficient<usize> {
     fn to_caller_address(self, design: &Design) -> CoefficientAddress {
         let level = design.terms[self.channel.term]
             .encoding
@@ -196,14 +196,14 @@ impl CoefficientLayout {
 
     /// Flat [`SolveResult::x`] index of `at`, or `None` if its term,
     /// column, or caller-visible level label is out of range.
-    pub fn index(&self, at: &CoefficientAddress) -> Option<usize> {
+    pub fn index(&self, at: CoefficientAddress) -> Option<usize> {
         let term = self.terms.get(at.channel.term)?;
 
         if at.channel.column >= term.n_columns {
             return None;
         }
 
-        let position = term.encoding.position(&at.level)?;
+        let position = term.encoding.position(at.level)?;
 
         Some(term.offset + at.channel.column * term.encoding.n_levels() + position)
     }

crates/within/src/solver/tests.rs

@@ -13,7 +13,7 @@ use crate::Effect;
 fn at(term: usize, level: u32, column: usize) -> CoefficientAddress {
     CoefficientAddress {
         channel: Channel { term, column },
-        level: level.into(),
+        level,
     }
 }
 
@@ -75,19 +75,19 @@ fn coefficient_layout_translates_addresses_both_ways() {
     assert_eq!(layout.n_levels(2), None);
 
     // Forward matches the documented `offset + column * n_levels + level`.
-    assert_eq!(layout.index(&at(0, 2, 0)), Some(2));
-    assert_eq!(layout.index(&at(1, 0, 0)), Some(3)); // term-1 intercept, level 0
-    assert_eq!(layout.index(&at(1, 1, 1)), Some(6)); // term-1 slope, level 1
+    assert_eq!(layout.index(at(0, 2, 0)), Some(2));
+    assert_eq!(layout.index(at(1, 0, 0)), Some(3)); // term-1 intercept, level 0
+    assert_eq!(layout.index(at(1, 1, 1)), Some(6)); // term-1 slope, level 1
     assert_eq!(layout.n_dofs(), 7);
 
     // Out-of-range coordinates are rejected, not silently wrapped.
-    assert_eq!(layout.index(&at(1, 2, 0)), None); // level past n_levels
-    assert_eq!(layout.index(&at(1, 0, 2)), None); // column past n_columns
-    assert_eq!(layout.index(&at(2, 0, 0)), None); // term past n_terms
+    assert_eq!(layout.index(at(1, 2, 0)), None); // level past n_levels
+    assert_eq!(layout.index(at(1, 0, 2)), None); // column past n_columns
+    assert_eq!(layout.index(at(2, 0, 0)), None); // term past n_terms
     assert_eq!(layout.address(7), None);
 
     // `address` inverts `index` for every flat slot.
     for i in 0..layout.n_dofs() {
-        assert_eq!(layout.index(&layout.address(i).expect("in range")), Some(i));
+        assert_eq!(layout.index(layout.address(i).expect("in range")), Some(i));
     }
 }

crates/within/tests/metamorphic.rs

@@ -9,7 +9,7 @@ use strategies::{additive_precond, random_fe_problem_strategy};
 fn at(term: usize, level: u32, column: usize) -> CoefficientAddress {
     CoefficientAddress {
         channel: Channel { term, column },
-        level: level.into(),
+        level,
     }
 }
 
@@ -140,7 +140,7 @@ proptest! {
         prop_assert!(result.converged);
 
         for u in &result.unidentified {
-            let slot = result.layout.index(u).unwrap();
+            let slot = result.layout.index(*u).unwrap();
             prop_assert_eq!(
                 result.x[slot],
                 0.0,
@@ -172,7 +172,7 @@ fn saturated_single_factor_recovers_level_means() {
 
     for (level, &mean) in [2.0, 4.0, 5.0].iter().enumerate() {
         let label = u32::try_from(level).expect("fixture level fits u32");
-        let slot = result.layout.index(&at(0, label, 0)).unwrap();
+        let slot = result.layout.index(at(0, label, 0)).unwrap();
         assert!(
             (result.x[slot] - mean).abs() < 1e-6,
             "level {level}: coefficient {} != level mean {mean}",

crates/within/tests/properties.rs

@@ -11,7 +11,7 @@ use strategies::{additive_precond, random_fe_problem_strategy, random_slopes_pro
 fn at(term: usize, level: u32, column: usize) -> CoefficientAddress {
     CoefficientAddress {
         channel: Channel { term, column },
-        level: level.into(),
+        level,
     }
 }
 
@@ -136,11 +136,11 @@ proptest! {
             for i in 0..n_obs {
                 let level = f.levels[i];
                 if f.intercept {
-                    fitted[i] += x[layout.index(&at(t, level, 0)).unwrap()];
+                    fitted[i] += x[layout.index(at(t, level, 0)).unwrap()];
                 }
                 for (s, col) in f.slopes.iter().enumerate() {
                     fitted[i] +=
-                        x[layout.index(&at(t, level, slope_base + s)).unwrap()] * col[i];
+                        x[layout.index(at(t, level, slope_base + s)).unwrap()] * col[i];
                 }
             }
         }
@@ -155,12 +155,12 @@ proptest! {
                 let wr = weights[i] * (y[i] - fitted[i]);
                 let wy = weights[i] * y[i];
                 if f.intercept {
-                    let k = layout.index(&at(t, level, 0)).unwrap();
+                    let k = layout.index(at(t, level, 0)).unwrap();
                     g[k] += wr;
                     g0[k] += wy;
                 }
                 for (s, col) in f.slopes.iter().enumerate() {
-                    let k = layout.index(&at(t, level, slope_base + s)).unwrap();
+                    let k = layout.index(at(t, level, slope_base + s)).unwrap();
                     g[k] += wr * col[i];
                     g0[k] += wy * col[i];
                 }

crates/within/tests/slopes.rs

@@ -89,13 +89,7 @@ fn solve_single(
 fn drops(r: &SolveResult) -> Vec<(usize, u32, usize)> {
     r.unidentified
         .iter()
-        .map(|d| {
-            (
-                d.channel.term,
-                d.level.try_as_u32().expect("u32 factor label"),
-                d.channel.column,
-            )
-        })
+        .map(|d| (d.channel.term, d.level, d.channel.column))
         .collect()
 }
 
@@ -264,13 +258,7 @@ fn batch_solve_shares_unidentified_and_back_transforms_each_rhs() {
     let batch_drops: Vec<_> = batch
         .unidentified
         .iter()
-        .map(|d| {
-            (
-                d.channel.term,
-                d.level.try_as_u32().expect("u32 factor label"),
-                d.channel.column,
-            )
-        })
+        .map(|d| (d.channel.term, d.level, d.channel.column))
         .collect();
     assert_eq!(batch_drops, [(0, 1, 1)]);
     // Each RHS block is bit-identical to its single solve, back-transform included.