Skip to main content

photonlayer_ruvector/
boundary.rs

1//! Pass/fail boundary analysis using spectral graph partitioning (ADR-260 ยง13).
2//!
3//! [`explain_boundary`] builds a cosine-similarity graph over the union of
4//! pass and fail experiment embeddings, computes the Fiedler partition via
5//! [`ruvector_coherence::spectral`], and identifies which [`OpticalConfig`]
6//! variable most consistently separates the two outcome groups.
7
8use photonlayer_core::prelude::OpticalConfig;
9use ruvector_coherence::cosine_similarity;
10use ruvector_coherence::spectral::{
11    estimate_fiedler, estimate_largest_eigenvalue, estimate_spectral_gap, CsrMatrixView,
12};
13use serde::{Deserialize, Serialize};
14
15use crate::memory::ExperimentMemory;
16
17/// Threshold above which a cosine similarity edge is included in the graph.
18const SIM_THRESHOLD: f64 = 0.5;
19
20/// Summary of the pass/fail decision boundary.
21#[derive(Clone, Debug, Serialize, Deserialize)]
22pub struct BoundaryReport {
23    /// Name of the config variable that most consistently separates pass/fail.
24    pub dominant_variable: String,
25    /// Runner-up config variable.
26    pub secondary_variable: String,
27    /// Spectral gap of the similarity graph (larger = clearer boundary).
28    pub spectral_gap: f64,
29    /// Human-readable recommendation derived from the analysis.
30    pub recommendation: String,
31}
32
33/// Compute the mean value of a config field across a slice of configs.
34fn mean_f64(configs: &[&OpticalConfig], extract: impl Fn(&OpticalConfig) -> f64) -> f64 {
35    if configs.is_empty() {
36        return 0.0;
37    }
38    configs.iter().map(|c| extract(c)).sum::<f64>() / configs.len() as f64
39}
40
41/// Mean absolute deviation around `mean` for a set of values.
42fn mad(values: impl Iterator<Item = f64>, mean: f64) -> f64 {
43    let vals: Vec<f64> = values.collect();
44    if vals.is_empty() {
45        return 0.0;
46    }
47    vals.iter().map(|v| (v - mean).abs()).sum::<f64>() / vals.len() as f64
48}
49
50/// Score how discriminative a real-valued config field is between two groups.
51///
52/// Returns the absolute difference of group means, normalised by the pooled MAD.
53/// A higher score means the variable separates the groups more cleanly.
54fn discriminability(pass_vals: &[f64], fail_vals: &[f64]) -> f64 {
55    if pass_vals.is_empty() || fail_vals.is_empty() {
56        return 0.0;
57    }
58    let mp: f64 = pass_vals.iter().sum::<f64>() / pass_vals.len() as f64;
59    let mf: f64 = fail_vals.iter().sum::<f64>() / fail_vals.len() as f64;
60    let diff = (mp - mf).abs();
61
62    let all_mean = (mp + mf) / 2.0;
63    let spread = mad(pass_vals.iter().chain(fail_vals.iter()).copied(), all_mean);
64    if spread < 1e-30 {
65        // No within-group spread: if the means differ it is a perfect separator.
66        if diff > 1e-9 {
67            1e9
68        } else {
69            0.0
70        }
71    } else {
72        diff / spread
73    }
74}
75
76/// Analyse the pass/fail boundary in `memory`.
77///
78/// # Arguments
79/// * `memory` โ€” the experiment store to analyse.
80/// * `pass_label` โ€” label string used for successful experiments (e.g. `"pass"`).
81/// * `fail_label` โ€” label string used for failing experiments (e.g. `"fail"`).
82///
83/// Returns a [`BoundaryReport`] identifying the dominant config variable and
84/// the spectral gap of the experiment similarity graph.
85///
86/// If either group is empty the report contains `"insufficient_data"` variables
87/// and a spectral gap of `0.0`.
88pub fn explain_boundary(
89    memory: &ExperimentMemory,
90    pass_label: &str,
91    fail_label: &str,
92) -> BoundaryReport {
93    let pass_records = memory.by_label(pass_label);
94    let fail_records = memory.by_label(fail_label);
95
96    if pass_records.is_empty() || fail_records.is_empty() {
97        return BoundaryReport {
98            dominant_variable: "insufficient_data".to_owned(),
99            secondary_variable: "insufficient_data".to_owned(),
100            spectral_gap: 0.0,
101            recommendation: "Need at least one pass and one fail experiment.".to_owned(),
102        };
103    }
104
105    // ---- build embedding list in a stable order: passes first ----
106    let all_records: Vec<&crate::memory::ExperimentRecord> = pass_records
107        .iter()
108        .chain(fail_records.iter())
109        .copied()
110        .collect();
111    let n = all_records.len();
112
113    // ---- build cosine-similarity graph edges ----
114    let mut edges: Vec<(usize, usize, f64)> = Vec::new();
115    for i in 0..n {
116        for j in (i + 1)..n {
117            let sim = cosine_similarity(&all_records[i].embedding, &all_records[j].embedding);
118            if sim >= SIM_THRESHOLD {
119                edges.push((i, j, sim));
120            }
121        }
122    }
123
124    // ---- build Laplacian and estimate spectral gap ----
125    let lap = CsrMatrixView::build_laplacian(n, &edges);
126    let (fiedler_raw, _fiedler_vec) = estimate_fiedler(&lap, 100, 1e-6);
127    let largest = estimate_largest_eigenvalue(&lap, 100);
128    let spectral_gap = estimate_spectral_gap(fiedler_raw, largest);
129
130    // ---- find which config variable best separates pass / fail ----
131    let pass_cfgs: Vec<&OpticalConfig> = pass_records.iter().map(|r| &r.config).collect();
132    let fail_cfgs: Vec<&OpticalConfig> = fail_records.iter().map(|r| &r.config).collect();
133
134    let pass_prop_mm: Vec<f64> = pass_cfgs.iter().map(|c| c.propagation_mm as f64).collect();
135    let fail_prop_mm: Vec<f64> = fail_cfgs.iter().map(|c| c.propagation_mm as f64).collect();
136
137    let pass_wave: Vec<f64> = pass_cfgs.iter().map(|c| c.wavelength_nm as f64).collect();
138    let fail_wave: Vec<f64> = fail_cfgs.iter().map(|c| c.wavelength_nm as f64).collect();
139
140    let pass_binning: Vec<f64> = pass_cfgs
141        .iter()
142        .map(|c| c.detector.binning as f64)
143        .collect();
144    let fail_binning: Vec<f64> = fail_cfgs
145        .iter()
146        .map(|c| c.detector.binning as f64)
147        .collect();
148
149    let pass_seed: Vec<f64> = pass_cfgs.iter().map(|c| c.seed as f64).collect();
150    let fail_seed: Vec<f64> = fail_cfgs.iter().map(|c| c.seed as f64).collect();
151
152    // Propagation mode as discrete code.
153    let mode_code = |c: &OpticalConfig| {
154        use photonlayer_core::prelude::PropagationMode;
155        match c.propagation {
156            PropagationMode::Fresnel => 0.0,
157            PropagationMode::Fraunhofer => 1.0,
158            PropagationMode::AngularSpectrum => 2.0,
159        }
160    };
161    let pass_mode: Vec<f64> = pass_cfgs.iter().map(|c| mode_code(c)).collect();
162    let fail_mode: Vec<f64> = fail_cfgs.iter().map(|c| mode_code(c)).collect();
163
164    let candidates: &[(&str, f64)] = &[
165        (
166            "propagation_mm",
167            discriminability(&pass_prop_mm, &fail_prop_mm),
168        ),
169        ("wavelength_nm", discriminability(&pass_wave, &fail_wave)),
170        (
171            "detector.binning",
172            discriminability(&pass_binning, &fail_binning),
173        ),
174        ("seed", discriminability(&pass_seed, &fail_seed)),
175        ("propagation_mode", discriminability(&pass_mode, &fail_mode)),
176    ];
177
178    let mut sorted = candidates.to_vec();
179    sorted.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
180
181    let dominant = sorted[0].0.to_owned();
182    let secondary = if sorted.len() > 1 {
183        sorted[1].0.to_owned()
184    } else {
185        "none".to_owned()
186    };
187
188    let pass_mean = mean_f64(&pass_cfgs, |c| c.propagation_mm as f64);
189    let fail_mean = mean_f64(&fail_cfgs, |c| c.propagation_mm as f64);
190
191    let recommendation = format!(
192        "Dominant separator: `{dominant}` (score {:.3}). \
193         Secondary: `{secondary}` (score {:.3}). \
194         Pass propagation_mm mean={pass_mean:.2}, fail mean={fail_mean:.2}. \
195         Spectral gap={spectral_gap:.4}.",
196        sorted[0].1,
197        sorted[1].1.max(0.0),
198    );
199
200    BoundaryReport {
201        dominant_variable: dominant,
202        secondary_variable: secondary,
203        spectral_gap,
204        recommendation,
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211    use photonlayer_core::prelude::{
212        build_receipt, DetectorConfig, InputImage, MetricReport, OpticalConfig, OpticalSimulator,
213        PhaseMask, PropagationMode, Provenance, ScalarSimulator,
214    };
215
216    use crate::{embedding::experiment_embedding, memory::ExperimentRecord};
217
218    fn make_record_with_cfg(
219        id: &str,
220        label: &str,
221        cfg: OpticalConfig,
222        seed: u64,
223    ) -> ExperimentRecord {
224        let n = 16;
225        let pixels: Vec<f32> = (0..n * n).map(|i| (i % n) as f32 / n as f32).collect();
226        let img = InputImage::from_norm_f32(n, n, pixels).unwrap();
227        let mask = PhaseMask::random(n, n, seed);
228        let frame = ScalarSimulator.simulate(&img, &mask, &cfg).unwrap();
229        let metrics = MetricReport::default();
230        let receipt = build_receipt(
231            id,
232            &img,
233            &mask,
234            &cfg,
235            &frame,
236            &metrics,
237            &Provenance::default(),
238        );
239        let embedding = experiment_embedding(&mask, &frame);
240        ExperimentRecord {
241            id: id.to_owned(),
242            label: label.to_owned(),
243            config: cfg,
244            mask_id: mask.mask_id,
245            embedding,
246            receipt,
247            metrics,
248        }
249    }
250
251    #[test]
252    fn boundary_identifies_propagation_mm() {
253        let mut mem = ExperimentMemory::new();
254
255        // Pass group: short propagation.
256        for i in 0..3u64 {
257            let mut cfg = OpticalConfig::demo(16, 16);
258            cfg.propagation_mm = 5.0;
259            mem.remember(make_record_with_cfg(
260                &format!("pass-{i}"),
261                "pass",
262                cfg,
263                i + 1,
264            ));
265        }
266        // Fail group: long propagation.
267        for i in 0..3u64 {
268            let mut cfg = OpticalConfig::demo(16, 16);
269            cfg.propagation_mm = 50.0;
270            mem.remember(make_record_with_cfg(
271                &format!("fail-{i}"),
272                "fail",
273                cfg,
274                i + 10,
275            ));
276        }
277
278        let report = explain_boundary(&mem, "pass", "fail");
279        assert_eq!(
280            report.dominant_variable, "propagation_mm",
281            "expected propagation_mm, got: {:?}",
282            report
283        );
284        assert!(report.spectral_gap >= 0.0);
285    }
286
287    #[test]
288    fn boundary_identifies_propagation_mode() {
289        let mut mem = ExperimentMemory::new();
290
291        for i in 0..3u64 {
292            let mut cfg = OpticalConfig::demo(16, 16);
293            cfg.propagation = PropagationMode::Fresnel;
294            mem.remember(make_record_with_cfg(
295                &format!("pass-{i}"),
296                "pass",
297                cfg,
298                i + 1,
299            ));
300        }
301        for i in 0..3u64 {
302            let mut cfg = OpticalConfig::demo(16, 16);
303            cfg.propagation = PropagationMode::Fraunhofer;
304            mem.remember(make_record_with_cfg(
305                &format!("fail-{i}"),
306                "fail",
307                cfg,
308                i + 10,
309            ));
310        }
311
312        let report = explain_boundary(&mem, "pass", "fail");
313        // Mode is the only thing we changed, so it must be dominant.
314        assert_eq!(
315            report.dominant_variable, "propagation_mode",
316            "got: {:?}",
317            report
318        );
319    }
320
321    #[test]
322    fn boundary_empty_returns_gracefully() {
323        let mem = ExperimentMemory::new();
324        let report = explain_boundary(&mem, "pass", "fail");
325        assert_eq!(report.dominant_variable, "insufficient_data");
326    }
327
328    #[test]
329    fn boundary_identifies_binning() {
330        let mut mem = ExperimentMemory::new();
331
332        for i in 0..3u64 {
333            let mut cfg = OpticalConfig::demo(16, 16);
334            cfg.detector = DetectorConfig {
335                binning: 1,
336                ..DetectorConfig::default()
337            };
338            mem.remember(make_record_with_cfg(
339                &format!("pass-{i}"),
340                "pass",
341                cfg,
342                i + 1,
343            ));
344        }
345        for i in 0..3u64 {
346            let mut cfg = OpticalConfig::demo(16, 16);
347            cfg.detector = DetectorConfig {
348                binning: 4,
349                ..DetectorConfig::default()
350            };
351            mem.remember(make_record_with_cfg(
352                &format!("fail-{i}"),
353                "fail",
354                cfg,
355                i + 10,
356            ));
357        }
358
359        let report = explain_boundary(&mem, "pass", "fail");
360        assert_eq!(
361            report.dominant_variable, "detector.binning",
362            "got: {:?}",
363            report
364        );
365    }
366}