Skip to main content

qualia_core_db/inference/moe/
dispatch.rs

1//! Compatibility adapter for the canonical Etalon routed-expert dispatcher.
2pub use qualia_inference_kernel::moe::dispatch::{evaluate_swiglu_expert_nvfp4, silu, ExpertWeightView, MAX_INTERMEDIATE_DIM, MAX_ROUTED_EXPERTS};
3
4pub fn dispatch_moe_step<F>(
5    input: &[f32],
6    emb_dim: usize,
7    router_weights: &[f32], // [num_experts, emb_dim]
8    num_experts: usize,
9    topk: usize,
10    expert_fetcher: F,
11    shared_expert: Option<&ExpertWeightView<'_>>,
12    shared_gate_weight: f32,
13    scratch_accum: &mut [f32],
14) -> Result<(), String>
15where
16    F: FnMut(u16) -> Option<ExpertWeightView<'static>>,
17{
18    qualia_inference_kernel::moe::dispatch::dispatch_moe_step(input, emb_dim, router_weights, num_experts, topk, expert_fetcher, shared_expert, shared_gate_weight, scratch_accum).map_err(|error| error.to_string())
19}
20
21#[cfg(test)]
22mod tests {
23    use super::*;
24
25    #[test]
26    fn test_silu() {
27        assert_eq!(silu(0.0), 0.0);
28        assert!((silu(1.0) - 0.7310586).abs() < 1e-5);
29    }
30
31    fn make_test_expert<'a>(
32        gate_up_packed: &'a mut [u8],
33        gate_up_scale: &'a mut [u8],
34        down_packed: &'a mut [u8],
35        down_scale: &'a mut [u8],
36        val_byte: u8,
37        emb_dim: usize,
38        intermediate_dim: usize,
39    ) -> ExpertWeightView<'a> {
40        for b in gate_up_packed.iter_mut() {
41            *b = val_byte;
42        }
43        for s in gate_up_scale.iter_mut() {
44            *s = 0x38; // 1.0 in FP8 E4M3
45        }
46
47        for b in down_packed.iter_mut() {
48            *b = val_byte;
49        }
50        for s in down_scale.iter_mut() {
51            *s = 0x38;
52        }
53
54        ExpertWeightView {
55            gate_up_packed,
56            gate_up_scale,
57            gate_up_global: 1.0,
58            down_packed,
59            down_scale,
60            down_global: 1.0,
61            intermediate_dim,
62            emb_dim,
63        }
64    }
65
66    #[test]
67    fn test_swiglu_expert_nvfp4_matches_oracle() {
68        let emb_dim = 16;
69        let inter_dim = 16;
70        let mut gu_packed = vec![0u8; 2 * inter_dim * (emb_dim / 2)];
71        let mut gu_scale = vec![0u8; 2 * inter_dim * (emb_dim / 16)];
72        let mut d_packed = vec![0u8; emb_dim * (inter_dim / 2)];
73        let mut d_scale = vec![0u8; emb_dim * (inter_dim / 16)];
74
75        // val_byte = 0x42: low nibble = 2 (1.0), high nibble = 4 (2.0)
76        let expert = make_test_expert(
77            &mut gu_packed,
78            &mut gu_scale,
79            &mut d_packed,
80            &mut d_scale,
81            0x42,
82            emb_dim,
83            inter_dim,
84        );
85
86        let input = vec![1.0f32; emb_dim];
87        let mut gate_buf = [0.0f32; 16];
88        let mut up_buf = [0.0f32; 16];
89        let mut swiglu_buf = [0.0f32; 16];
90        let mut out = [0.0f32; 16];
91
92        evaluate_swiglu_expert_nvfp4(
93            &input,
94            &expert,
95            &mut gate_buf,
96            &mut up_buf,
97            &mut swiglu_buf,
98            &mut out,
99        )
100        .unwrap();
101
102        // Calculate expected:
103        // Each row of gate and up: 8 pairs of (1.0, 2.0). With input all 1.0:
104        // dot = 8 * (1.0 * 1.0 + 2.0 * 1.0) = 8 * 3.0 = 24.0
105        let expected_gate = 24.0f32;
106        let expected_up = 24.0f32;
107        let expected_swiglu = silu(expected_gate) * expected_up;
108
109        // Down projection: 8 pairs of (1.0, 2.0) with swiglu vector (all expected_swiglu):
110        // out[r] = 8 * (1.0 * expected_swiglu + 2.0 * expected_swiglu) = 24.0 * expected_swiglu
111        let expected_out = 24.0f32 * expected_swiglu;
112
113        for i in 0..inter_dim {
114            assert!((gate_buf[i] - expected_gate).abs() < 1e-4);
115            assert!((up_buf[i] - expected_up).abs() < 1e-4);
116            assert!((swiglu_buf[i] - expected_swiglu).abs() < 1e-4);
117            assert!((out[i] - expected_out).abs() < 1e-3);
118        }
119    }
120
121    #[test]
122    fn test_dispatch_moe_step_routed_and_shared_experts_matches_oracle() {
123        let emb_dim = 16;
124        let inter_dim = 16;
125        let num_experts = 4;
126        let topk = 2;
127
128        // Shared expert: val_byte 0x22 -> low 2 (1.0), high 2 (1.0). dot = 16 * 1.0 = 16.0
129        let mut shared_gu_packed = vec![0u8; 2 * inter_dim * (emb_dim / 2)];
130        let mut shared_gu_scale = vec![0u8; 2 * inter_dim * (emb_dim / 16)];
131        let mut shared_d_packed = vec![0u8; emb_dim * (inter_dim / 2)];
132        let mut shared_d_scale = vec![0u8; emb_dim * (inter_dim / 16)];
133
134        let shared_expert = make_test_expert(
135            &mut shared_gu_packed,
136            &mut shared_gu_scale,
137            &mut shared_d_packed,
138            &mut shared_d_scale,
139            0x22,
140            emb_dim,
141            inter_dim,
142        );
143
144        // Router weights designed to favor expert 1 and expert 3
145        let mut router_weights = vec![0.0f32; num_experts * emb_dim];
146        for d in 0..emb_dim {
147            router_weights[0 * emb_dim + d] = 0.1;
148            router_weights[1 * emb_dim + d] = 2.0; // High
149            router_weights[2 * emb_dim + d] = 0.2;
150            router_weights[3 * emb_dim + d] = 3.0; // Highest
151        }
152
153        let input = vec![1.0f32; emb_dim];
154        let mut scratch_accum = vec![0.0f32; emb_dim];
155
156        // Fetcher returns expert 0..3 with val_byte 0x42
157        let expert_fetcher = |_id: u16| -> Option<ExpertWeightView<'static>> {
158            // Leaking for the lifetime of test
159            let gu_p: &'static mut [u8] = Box::leak(vec![0x42u8; 2 * 16 * 8].into_boxed_slice());
160            let gu_s: &'static mut [u8] = Box::leak(vec![0x38u8; 2 * 16 * 1].into_boxed_slice());
161            let d_p: &'static mut [u8] = Box::leak(vec![0x42u8; 16 * 8].into_boxed_slice());
162            let d_s: &'static mut [u8] = Box::leak(vec![0x38u8; 16 * 1].into_boxed_slice());
163            Some(ExpertWeightView {
164                gate_up_packed: gu_p,
165                gate_up_scale: gu_s,
166                gate_up_global: 1.0,
167                down_packed: d_p,
168                down_scale: d_s,
169                down_global: 1.0,
170                intermediate_dim: 16,
171                emb_dim: 16,
172            })
173        };
174
175        dispatch_moe_step(
176            &input,
177            emb_dim,
178            &router_weights,
179            num_experts,
180            topk,
181            expert_fetcher,
182            Some(&shared_expert),
183            0.5,
184            &mut scratch_accum,
185        )
186        .unwrap();
187
188        // 1. Routed experts: 1 and 3 are selected.
189        // Dot product with router weights:
190        // logit[1] = 16 * 2.0 = 32.0
191        // logit[3] = 16 * 3.0 = 48.0
192        // Softmax over top-2: w1 = exp(32)/(exp(32)+exp(48)), w3 = exp(48)/(exp(32)+exp(48))
193        // Note: softmax normalized sum w1 + w3 == 1.0.
194        // Since both experts 1 and 3 have the identical output val (24.0 * silu(24.0) * 24.0 = ~576.0),
195        // the weighted sum of routed experts is simply 1.0 * expert_out = 24.0 * silu(24.0) * 24.0.
196        let routed_single_out = 24.0f32 * silu(24.0) * 24.0;
197
198        // 2. Shared expert: 0x22 -> low 1.0, high 1.0 -> dot = 16.0
199        // gate = 16.0, up = 16.0 -> swiglu = silu(16.0) * 16.0
200        // down = 16.0 * swiglu -> shared_out = 16.0 * silu(16.0) * 16.0
201        let shared_single_out = 16.0f32 * silu(16.0) * 16.0;
202        let expected_total = routed_single_out + 0.5 * shared_single_out;
203
204        for d in 0..emb_dim {
205            assert!(
206                (scratch_accum[d] - expected_total).abs() < 1e-2,
207                "Dim {d} mismatch: actual={}, expected={}",
208                scratch_accum[d],
209                expected_total
210            );
211        }
212    }
213}