Skip to main content

qualia_core_db/tensor/
volume_gpu.rs

1//! GPU tensor volume search (B8) — mirrors `visit_tensor_search_into` on U1 queue lane.
2
3use bytemuck::{Pod, Zeroable};
4
5#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
6use super::resident_substrate::{global_resident_substrate, MAX_KNN_HITS, MAX_RESIDENT_NODES};
7use super::Tensor10D;
8
9pub const TENSOR_VOLUME_STRIDE_FLOATS: u32 = 10;
10
11#[repr(C)]
12#[derive(Clone, Copy, Pod, Zeroable)]
13struct VolumeGpuParams {
14    node_count: u32,
15    max_distance: f32,
16    stride_floats: u32,
17    max_hits: u32,
18}
19
20#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
21pub struct TensorVolumeGpu {
22    pipeline: etalon::ComputePipeline,
23    query_buf: etalon::Buffer,
24    nodes_buf: etalon::Buffer,
25    params_buf: etalon::Buffer,
26    hits_buf: etalon::Buffer,
27    count_buf: etalon::Buffer,
28    staging_hits: etalon::Buffer,
29    staging_count: etalon::Buffer,
30    max_nodes: u32,
31}
32
33#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
34impl TensorVolumeGpu {
35    /// Tries `new`.
36    pub fn try_new(device: &etalon::Device) -> Option<Self> {
37        let shader = device.create_shader_module(etalon::ShaderModuleDescriptor {
38            label: Some("TensorVolumeShader"),
39            source: etalon::ShaderSource::Wgsl(include_str!("../shaders/tensor_volume.wgsl").into()),
40        });
41        let pipeline = device.create_compute_pipeline(&etalon::ComputePipelineDescriptor {
42            label: Some("TensorVolumePipeline"),
43            layout: None,
44            module: &shader,
45            entry_point: Some("main"),
46            compilation_options: Default::default(),
47            cache: None,
48        });
49        let max_nodes = MAX_RESIDENT_NODES as u32;
50        let node_floats = max_nodes * TENSOR_VOLUME_STRIDE_FLOATS;
51        Some(Self {
52            pipeline,
53            query_buf: device.create_buffer(&etalon::BufferDescriptor {
54                label: Some("TensorVolumeQuery"),
55                size: std::mem::size_of::<Tensor10D>() as etalon::BufferAddress,
56                usage: etalon::BufferUsages::UNIFORM | etalon::BufferUsages::COPY_DST,
57                mapped_at_creation: false,
58            }),
59            nodes_buf: device.create_buffer(&etalon::BufferDescriptor {
60                label: Some("TensorVolumeNodes"),
61                size: (node_floats as usize * 4) as etalon::BufferAddress,
62                usage: etalon::BufferUsages::STORAGE | etalon::BufferUsages::COPY_DST,
63                mapped_at_creation: false,
64            }),
65            params_buf: device.create_buffer(&etalon::BufferDescriptor {
66                label: Some("TensorVolumeParams"),
67                size: std::mem::size_of::<VolumeGpuParams>() as etalon::BufferAddress,
68                usage: etalon::BufferUsages::UNIFORM | etalon::BufferUsages::COPY_DST,
69                mapped_at_creation: false,
70            }),
71            hits_buf: device.create_buffer(&etalon::BufferDescriptor {
72                label: Some("TensorVolumeHits"),
73                size: (MAX_KNN_HITS * 4) as etalon::BufferAddress,
74                usage: etalon::BufferUsages::STORAGE | etalon::BufferUsages::COPY_SRC,
75                mapped_at_creation: false,
76            }),
77            count_buf: device.create_buffer(&etalon::BufferDescriptor {
78                label: Some("TensorVolumeHitCount"),
79                size: 4,
80                // COPY_DST: reset to 0 each cycle via queue.write_buffer (line ~145);
81                // COPY_SRC: copied to staging_count for readback; STORAGE: shader binding.
82                usage: etalon::BufferUsages::STORAGE
83                    | etalon::BufferUsages::COPY_SRC
84                    | etalon::BufferUsages::COPY_DST,
85                mapped_at_creation: false,
86            }),
87            staging_hits: device.create_buffer(&etalon::BufferDescriptor {
88                label: Some("TensorVolumeHitsStaging"),
89                size: (MAX_KNN_HITS * 4) as etalon::BufferAddress,
90                usage: etalon::BufferUsages::MAP_READ | etalon::BufferUsages::COPY_DST,
91                mapped_at_creation: false,
92            }),
93            staging_count: device.create_buffer(&etalon::BufferDescriptor {
94                label: Some("TensorVolumeCountStaging"),
95                size: 4,
96                usage: etalon::BufferUsages::MAP_READ | etalon::BufferUsages::COPY_DST,
97                mapped_at_creation: false,
98            }),
99            max_nodes,
100        })
101    }
102
103    fn upload_nodes(&self, queue: &etalon::Queue, node_count: u32) -> bool {
104        let substrate = global_resident_substrate();
105        let count = node_count.min(substrate.node_count()).min(self.max_nodes);
106        if count == 0 {
107            return false;
108        }
109        let mut flat = [0f32; MAX_RESIDENT_NODES * TENSOR_VOLUME_STRIDE_FLOATS as usize];
110        for i in 0..count as usize {
111            if let Some(t) = substrate.tensor_at(i as u32) {
112                let base = i * TENSOR_VOLUME_STRIDE_FLOATS as usize;
113                flat[base] = t.q;
114                flat[base + 1] = t.v;
115                flat[base + 2] = t.w;
116                flat[base + 3] = t.x;
117                flat[base + 4] = t.y;
118                flat[base + 5] = t.z;
119                flat[base + 6] = t.t;
120                flat[base + 7] = t.alpha;
121                flat[base + 8] = t.mu;
122                flat[base + 9] = t.sigma;
123            }
124        }
125        let bytes =
126            (count as usize * TENSOR_VOLUME_STRIDE_FLOATS as usize * 4) as etalon::BufferAddress;
127        queue.write_buffer(
128            &self.nodes_buf,
129            0,
130            bytemuck::cast_slice(&flat[..count as usize * 10]),
131        );
132        let _ = bytes;
133        true
134    }
135
136    /// GPU kNN filter; returns hit count written into `out` (caller stack buffer).
137    pub fn tensor_search_into(
138        &self,
139        device: &etalon::Device,
140        queue: &etalon::Queue,
141        query: &Tensor10D,
142        max_distance: f32,
143        out: &mut [usize],
144    ) -> usize {
145        let node_count = global_resident_substrate().node_count().min(self.max_nodes);
146        if node_count == 0 || out.is_empty() || !self.upload_nodes(queue, node_count) {
147            return 0;
148        }
149        self.search_uploaded_into(device, queue, query, max_distance, node_count, out)
150    }
151
152    pub(crate) fn search_uploaded_into(
153        &self,
154        device: &etalon::Device,
155        queue: &etalon::Queue,
156        query: &Tensor10D,
157        max_distance: f32,
158        node_count: u32,
159        out: &mut [usize],
160    ) -> usize {
161        if node_count == 0 || node_count > self.max_nodes || out.is_empty() {
162            return 0;
163        }
164
165        queue.write_buffer(&self.query_buf, 0, bytemuck::bytes_of(query));
166        let params = VolumeGpuParams {
167            node_count,
168            max_distance,
169            stride_floats: TENSOR_VOLUME_STRIDE_FLOATS,
170            max_hits: MAX_KNN_HITS as u32,
171        };
172        queue.write_buffer(&self.params_buf, 0, bytemuck::bytes_of(&params));
173        queue.write_buffer(&self.count_buf, 0, &[0u8; 4]);
174
175        let bind = device.create_bind_group(&etalon::BindGroupDescriptor {
176            label: Some("TensorVolumeBindGroup"),
177            layout: &self.pipeline.get_bind_group_layout(0),
178            entries: &[
179                etalon::BindGroupEntry {
180                    binding: 0,
181                    resource: self.query_buf.as_entire_binding(),
182                },
183                etalon::BindGroupEntry {
184                    binding: 1,
185                    resource: self.nodes_buf.as_entire_binding(),
186                },
187                etalon::BindGroupEntry {
188                    binding: 2,
189                    resource: self.params_buf.as_entire_binding(),
190                },
191                etalon::BindGroupEntry {
192                    binding: 3,
193                    resource: self.hits_buf.as_entire_binding(),
194                },
195                etalon::BindGroupEntry {
196                    binding: 4,
197                    resource: self.count_buf.as_entire_binding(),
198                },
199            ],
200        });
201
202        let wg = (node_count + 63) / 64;
203        let mut encoder = device.create_command_encoder(&etalon::CommandEncoderDescriptor {
204            label: Some("TensorVolumeEncoder"),
205        });
206        {
207            let mut pass = encoder.begin_compute_pass(&etalon::ComputePassDescriptor {
208                label: Some("TensorVolumePass"),
209                timestamp_writes: None,
210            });
211            pass.set_pipeline(&self.pipeline);
212            pass.set_bind_group(0, &bind, &[]);
213            pass.dispatch_workgroups(wg, 1, 1);
214        }
215        encoder.copy_buffer_to_buffer(
216            &self.hits_buf,
217            0,
218            &self.staging_hits,
219            0,
220            (MAX_KNN_HITS * 4) as u64,
221        );
222        encoder.copy_buffer_to_buffer(&self.count_buf, 0, &self.staging_count, 0, 4);
223        queue.submit(Some(encoder.finish()));
224
225        let _ = device.poll(etalon::PollType::wait_indefinitely());
226        let count_slice = self.staging_count.slice(..4);
227        let (tx, rx) = std::sync::mpsc::channel();
228        count_slice.map_async(etalon::MapMode::Read, move |r| {
229            let _ = tx.send(r);
230        });
231        let _ = device.poll(etalon::PollType::wait_indefinitely());
232        if rx.recv().ok().and_then(|r| r.ok()).is_none() {
233            return 0;
234        }
235        let count_data = count_slice
236            .get_mapped_range()
237            .expect("wgpu buffer map_range failed");
238        let total = u32::from_le_bytes(count_data[..4].try_into().unwrap_or([0; 4])) as usize;
239        drop(count_data);
240        self.staging_count.unmap();
241
242        let hits_slice = self.staging_hits.slice(..(MAX_KNN_HITS * 4) as u64);
243        let (tx2, rx2) = std::sync::mpsc::channel();
244        hits_slice.map_async(etalon::MapMode::Read, move |r| {
245            let _ = tx2.send(r);
246        });
247        let _ = device.poll(etalon::PollType::wait_indefinitely());
248        if rx2.recv().ok().and_then(|r| r.ok()).is_none() {
249            return 0;
250        }
251        let hits_data = hits_slice
252            .get_mapped_range()
253            .expect("wgpu buffer map_range failed");
254        let indices: &[u32] = bytemuck::cast_slice(&hits_data);
255        let n = total.min(out.len()).min(indices.len());
256        for i in 0..n {
257            out[i] = indices[i] as usize;
258        }
259        drop(hits_data);
260        self.staging_hits.unmap();
261        n
262    }
263}
264
265#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
266#[path = "owned_volume_gpu.rs"]
267pub(crate) mod owned;
268
269#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
270static VOLUME_GPU: std::sync::OnceLock<Option<TensorVolumeGpu>> = std::sync::OnceLock::new();
271
272/// Try GPU tensor search; returns None when GPU path unavailable (caller uses SIMD).
273#[cfg(all(not(target_arch = "wasm32"), feature = "gpu-runtime"))]
274pub fn try_gpu_tensor_search_into(
275    query: &Tensor10D,
276    max_distance: f32,
277    out: &mut [usize],
278) -> Option<usize> {
279    let gpu_ctx = crate::gpu_context::shared_gpu();
280    let vol = VOLUME_GPU.get_or_init(|| TensorVolumeGpu::try_new(&gpu_ctx.device));
281    let vol = vol.as_ref()?;
282    let n = vol.tensor_search_into(
283        &gpu_ctx.device,
284        crate::gpu_context::shared_gpu()
285            .queue_for_universe(crate::gpu_context::ComputeUniverse::Tensor10D),
286        query,
287        max_distance,
288        out,
289    );
290    if n > 0 {
291        Some(n)
292    } else {
293        None
294    }
295}
296
297#[cfg(not(all(not(target_arch = "wasm32"), feature = "gpu-runtime")))]
298/// Tries `gpu-tensor-search-into`.
299pub fn try_gpu_tensor_search_into(
300    _query: &Tensor10D,
301    _max_distance: f32,
302    _out: &mut [usize],
303) -> Option<usize> {
304    None
305}
306
307/// CPU reference for the GPU tensor-volume search (ALGEBRA_MANIFOLD_PLAN.md Phase 4.2).
308///
309/// A plain linear scan using the CANONICAL `Tensor10D::full_distance` metric — the same
310/// metric `shaders/tensor_volume.wgsl` now ports (chosen by the QUERY's `v` topology
311/// class: euclidean / cyclic / hyperbolic / boundary). All three paths — GPU, this
312/// reference, and the substrate CPU fallback — therefore agree for ALL `v`. Makes the
313/// 10D manifold search testable without a GPU.
314///
315/// Semantics match the shader: a node is a hit iff `distance <= max_distance`; indices
316/// are written into `out` up to its capacity, and the FULL match count is returned
317/// (which may exceed `out.len()`, exactly like the shader's `hit_count`).
318pub fn cpu_tensor_search_into(
319    query: &Tensor10D,
320    nodes: &[Tensor10D],
321    max_distance: f32,
322    out: &mut [usize],
323) -> usize {
324    let mut matches = 0usize;
325    for (idx, node) in nodes.iter().enumerate() {
326        if query.full_distance(node) <= max_distance {
327            if matches < out.len() {
328                out[matches] = idx;
329            }
330            matches += 1;
331        }
332    }
333    matches
334}
335
336#[cfg(test)]
337mod cpu_reference_tests {
338    use super::*;
339
340    #[test]
341    fn cpu_tensor_search_matches_metric() {
342        // Nodes vary along single dimensions; query is the origin tensor. The metric
343        // uses x,y,z,t,alpha,mu,sigma and ignores q,v,w.
344        let zeros = Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
345        let nodes = [
346            zeros,                                                            // 0: dist 0
347            Tensor10D::new(0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), // 1: x=1 → dist 1
348            Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 3.0), // 2: sigma=3 → dist 3
349            // q,v,w set but METRIC-IRRELEVANT → still dist 0, must be a hit.
350            Tensor10D::new(9.0, 9.0, 9.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0), // 3: dist 0
351        ];
352        let mut out = [usize::MAX; 8];
353
354        // radius 1.5 → nodes 0,1,3 (not 2 at dist 3).
355        let n = cpu_tensor_search_into(&zeros, &nodes, 1.5, &mut out);
356        assert_eq!(n, 3);
357        let hits: std::collections::BTreeSet<usize> = out[..n].iter().copied().collect();
358        assert_eq!(hits, [0, 1, 3].into_iter().collect());
359
360        // radius 5 → all four.
361        assert_eq!(cpu_tensor_search_into(&zeros, &nodes, 5.0, &mut out), 4);
362        // radius 0 → only the exact matches (nodes 0 and 3).
363        assert_eq!(cpu_tensor_search_into(&zeros, &nodes, 0.0, &mut out), 2);
364    }
365
366    #[test]
367    fn cpu_tensor_search_honors_topology_class() {
368        // Proves the v-switched metric unification (§4.1). A CYCLIC query (v == 1) wraps
369        // x modulo 1, so x=0 and x=0.9 are 0.1 apart — NOT 0.9 as under euclidean.
370        // new(q, v, w, x, y, z, t, alpha, mu, sigma)
371        let query = Tensor10D::new(0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
372        let near_wrap = Tensor10D::new(0.0, 1.0, 0.0, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
373        let mut out = [usize::MAX; 4];
374        // radius 0.2: cyclic distance 0.1 → HIT (euclidean 0.9 would miss).
375        assert_eq!(
376            cpu_tensor_search_into(&query, &[near_wrap], 0.2, &mut out),
377            1,
378            "cyclic metric must wrap x; node should be within 0.2"
379        );
380        // Same geometry under a euclidean query (v == 0) → MISS at radius 0.2.
381        let euclid_query = Tensor10D::new(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
382        let euclid_node = Tensor10D::new(0.0, 0.0, 0.0, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0);
383        assert_eq!(
384            cpu_tensor_search_into(&euclid_query, &[euclid_node], 0.2, &mut out),
385            0
386        );
387    }
388}