Skip to main content

photonlayer_ruvector/
embedding.rs

1//! Experiment embeddings for optical mask + detector frame (ADR-260 ยง12).
2//!
3//! A 32-dimensional L2-normalised embedding is built by concatenating:
4//! - 16 bins from [`PhaseMask::phase_histogram`]  (mask signature)
5//! - 16 bins from [`frame_spectrum_embedding`]     (detector frame signature)
6//!
7//! The same dimensionality is used for mask-only embeddings (just the
8//! histogram, padded to 32 dims with zeros) so every embedding lives in the
9//! same inner-product space.
10
11use photonlayer_core::prelude::{frame_spectrum_embedding, OpticalFrame, PhaseMask};
12
13/// Number of histogram bins contributed by the mask half.
14pub const MASK_BINS: usize = 16;
15/// Number of spectrum bins contributed by the frame half.
16pub const FRAME_BINS: usize = 16;
17/// Total embedding dimension.
18pub const EMBED_DIM: usize = MASK_BINS + FRAME_BINS;
19
20/// Normalise a mutable slice to unit L2 norm (in-place). No-op when all-zero.
21pub fn l2_normalize(v: &mut [f32]) {
22    let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
23    if norm > f32::EPSILON {
24        for x in v.iter_mut() {
25            *x /= norm;
26        }
27    }
28}
29
30/// Build the full 32-dim experiment embedding from a mask + detector frame.
31///
32/// The returned vector is L2-normalised.
33pub fn experiment_embedding(mask: &PhaseMask, frame: &OpticalFrame) -> Vec<f32> {
34    let mut emb = Vec::with_capacity(EMBED_DIM);
35    emb.extend_from_slice(&mask.phase_histogram(MASK_BINS));
36    emb.extend_from_slice(&frame_spectrum_embedding(frame, FRAME_BINS));
37    l2_normalize(&mut emb);
38    emb
39}
40
41/// Build a mask-only embedding (32 dims: histogram + 16 zeros), L2-normalised.
42///
43/// Useful when only the mask is known (e.g. for coherence family comparison).
44pub fn mask_embedding(mask: &PhaseMask) -> Vec<f32> {
45    let mut emb = Vec::with_capacity(EMBED_DIM);
46    emb.extend_from_slice(&mask.phase_histogram(MASK_BINS));
47    emb.extend(std::iter::repeat(0.0f32).take(FRAME_BINS));
48    l2_normalize(&mut emb);
49    emb
50}
51
52#[cfg(test)]
53mod tests {
54    use super::*;
55    use photonlayer_core::prelude::{
56        InputImage, OpticalConfig, OpticalSimulator, PhaseMask, ScalarSimulator,
57    };
58
59    fn make_frame(seed: u64) -> (PhaseMask, OpticalFrame) {
60        let n = 16;
61        let pixels: Vec<f32> = (0..n * n).map(|i| (i % n) as f32 / n as f32).collect();
62        let img = InputImage::from_norm_f32(n, n, pixels).unwrap();
63        let mask = PhaseMask::random(n, n, seed);
64        let cfg = OpticalConfig::demo(n, n);
65        let frame = ScalarSimulator.simulate(&img, &mask, &cfg).unwrap();
66        (mask, frame)
67    }
68
69    #[test]
70    fn embedding_has_correct_dimension() {
71        let (mask, frame) = make_frame(1);
72        let emb = experiment_embedding(&mask, &frame);
73        assert_eq!(emb.len(), EMBED_DIM);
74    }
75
76    #[test]
77    fn embedding_is_unit_norm() {
78        let (mask, frame) = make_frame(2);
79        let emb = experiment_embedding(&mask, &frame);
80        let norm: f32 = emb.iter().map(|x| x * x).sum::<f32>().sqrt();
81        assert!((norm - 1.0).abs() < 1e-5, "norm = {norm}");
82    }
83
84    #[test]
85    fn embedding_is_deterministic() {
86        let (mask, frame) = make_frame(3);
87        let a = experiment_embedding(&mask, &frame);
88        let b = experiment_embedding(&mask, &frame);
89        assert_eq!(a, b);
90    }
91
92    #[test]
93    fn mask_embedding_has_correct_dimension() {
94        let mask = PhaseMask::random(16, 16, 42);
95        let emb = mask_embedding(&mask);
96        assert_eq!(emb.len(), EMBED_DIM);
97    }
98
99    #[test]
100    fn different_masks_differ() {
101        let a = mask_embedding(&PhaseMask::random(16, 16, 100));
102        let b = mask_embedding(&PhaseMask::random(16, 16, 200));
103        let dot: f32 = a.iter().zip(&b).map(|(x, y)| x * y).sum();
104        // Different random masks should not be identical
105        assert!(
106            dot < 0.9999,
107            "embeddings unexpectedly identical: dot = {dot}"
108        );
109    }
110}