1use 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
17const SIM_THRESHOLD: f64 = 0.5;
19
20#[derive(Clone, Debug, Serialize, Deserialize)]
22pub struct BoundaryReport {
23 pub dominant_variable: String,
25 pub secondary_variable: String,
27 pub spectral_gap: f64,
29 pub recommendation: String,
31}
32
33fn 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
41fn 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
50fn 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 if diff > 1e-9 {
67 1e9
68 } else {
69 0.0
70 }
71 } else {
72 diff / spread
73 }
74}
75
76pub 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 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 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 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 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 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 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 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 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}