Skip to main content

triblespace_gpu/
lib.rs

1#![doc = include_str!("../README.md")]
2
3use std::fmt;
4
5mod succinct_mapping;
6pub use succinct_mapping::BackendSuccinctMapping;
7#[cfg(feature = "cuda")]
8pub use succinct_mapping::CudaSuccinctMapping;
9
10#[cfg(feature = "wgpu")]
11mod batch_confirm;
12#[cfg(any(feature = "wgpu", feature = "cuda"))]
13mod cubecl_backend;
14
15#[cfg(feature = "wgpu")]
16pub use batch_confirm::{
17    WgpuConfirmStats, WgpuContext, WgpuSuccinctArchive, WgpuSuccinctArchiveConstraint,
18    WgpuWaveletMatrix, DEFAULT_MIN_CONFIRM_BATCH,
19};
20#[cfg(any(feature = "wgpu", feature = "cuda"))]
21pub use cubecl_backend::CubeClWaveletFreeze;
22#[cfg(feature = "cuda")]
23pub use cubecl_backend::CudaWaveletFreeze;
24#[cfg(feature = "wgpu")]
25pub use cubecl_backend::WgpuWaveletFreeze;
26
27#[cfg(any(test, feature = "wgpu", feature = "cuda"))]
28const BLOCK_SIZE: u32 = 256;
29#[cfg(any(feature = "wgpu", feature = "cuda"))]
30const THREADS: u32 = 64;
31
32/// Failure to freeze a wavelet rotation on an accelerator.
33#[derive(Debug, Eq, PartialEq)]
34pub enum GpuFreezeError {
35    /// The backend's `u32` codes cannot represent this alphabet cardinality.
36    AlphabetTooWide(usize),
37    /// The current kernels use `u32` positions.
38    SequenceTooLong(usize),
39    /// Core and backend disagreed about the number of packed output layers.
40    OutputLayers {
41        /// Number of layers implied by the alphabet.
42        expected: usize,
43        /// Number of layers supplied by core.
44        actual: usize,
45    },
46    /// Core and backend disagreed about one packed output plane's length.
47    OutputPlaneWords {
48        /// Zero-based wavelet depth.
49        depth: usize,
50        /// Required number of `u64` words.
51        expected: usize,
52        /// Supplied number of `u64` words.
53        actual: usize,
54    },
55    /// A sequence code lies outside the declared alphabet.
56    CodeOutOfAlphabet {
57        /// Position of the invalid code.
58        position: usize,
59        /// Invalid code.
60        code: u32,
61        /// Declared alphabet cardinality.
62        alphabet_size: usize,
63    },
64    /// Checked host-side size or offset arithmetic overflowed a device lane.
65    GeometryOverflow(&'static str),
66    /// A device command or explicit synchronization failed.
67    Device(String),
68    /// The device returned a buffer with an unexpected byte count.
69    ReadbackSize {
70        /// Number of bytes allocated for the readback.
71        expected: usize,
72        /// Number of bytes returned by the runtime.
73        actual: usize,
74    },
75}
76
77impl fmt::Display for GpuFreezeError {
78    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
79        match self {
80            Self::AlphabetTooWide(size) => {
81                write!(f, "alphabet of size {size} exceeds u32 backend codes")
82            }
83            Self::SequenceTooLong(len) => write!(f, "sequence length {len} exceeds u32 positions"),
84            Self::OutputLayers { expected, actual } => write!(
85                f,
86                "core reserved {actual} wavelet layers, backend expected {expected}"
87            ),
88            Self::OutputPlaneWords {
89                depth,
90                expected,
91                actual,
92            } => write!(
93                f,
94                "core reserved {actual} words for wavelet layer {depth}, backend expected {expected}"
95            ),
96            Self::CodeOutOfAlphabet {
97                position,
98                code,
99                alphabet_size,
100            } => write!(
101                f,
102                "sequence code {code} at position {position} lies outside alphabet of size {alphabet_size}"
103            ),
104            Self::GeometryOverflow(quantity) => {
105                write!(f, "GPU wavelet geometry overflows {quantity}")
106            }
107            Self::Device(error) => write!(f, "accelerator operation failed: {error}"),
108            Self::ReadbackSize { expected, actual } => write!(
109                f,
110                "accelerator returned {actual} bytes, expected {expected}"
111            ),
112        }
113    }
114}
115
116impl std::error::Error for GpuFreezeError {}
117
118#[cfg(any(test, feature = "wgpu", feature = "cuda"))]
119#[derive(Clone, Copy, Debug, Eq, PartialEq)]
120struct FreezeGeometry {
121    len: u32,
122    width: u32,
123    words_per_layer: u32,
124    packed_words: u32,
125    packed_bytes: usize,
126    num_blocks: u32,
127}
128
129#[cfg(any(test, feature = "wgpu", feature = "cuda"))]
130impl FreezeGeometry {
131    fn checked(
132        alphabet_size: usize,
133        sequence_len: usize,
134        plane_words: &[usize],
135    ) -> Result<Self, GpuFreezeError> {
136        if alphabet_size > u32::MAX as usize {
137            return Err(GpuFreezeError::AlphabetTooWide(alphabet_size));
138        }
139        let len = u32::try_from(sequence_len)
140            .map_err(|_| GpuFreezeError::SequenceTooLong(sequence_len))?;
141        let width_usize = alphabet_width(alphabet_size);
142        if plane_words.len() != width_usize {
143            return Err(GpuFreezeError::OutputLayers {
144                expected: width_usize,
145                actual: plane_words.len(),
146            });
147        }
148        let expected_plane_words = sequence_len.div_ceil(64);
149        for (depth, &actual) in plane_words.iter().enumerate() {
150            if actual != expected_plane_words {
151                return Err(GpuFreezeError::OutputPlaneWords {
152                    depth,
153                    expected: expected_plane_words,
154                    actual,
155                });
156            }
157        }
158
159        let width = u32::try_from(width_usize)
160            .map_err(|_| GpuFreezeError::GeometryOverflow("wavelet width"))?;
161        let words_per_layer = len.div_ceil(32);
162        let packed_words = width
163            .checked_mul(words_per_layer)
164            .ok_or(GpuFreezeError::GeometryOverflow("packed u32 word count"))?;
165        let packed_bytes = usize::try_from(packed_words)
166            .ok()
167            .and_then(|words| words.checked_mul(std::mem::size_of::<u32>()))
168            .ok_or(GpuFreezeError::GeometryOverflow("packed byte count"))?;
169        sequence_len
170            .checked_mul(std::mem::size_of::<u32>())
171            .ok_or(GpuFreezeError::GeometryOverflow("sequence byte count"))?;
172
173        let num_blocks = len.div_ceil(BLOCK_SIZE);
174        usize::try_from(num_blocks)
175            .ok()
176            .and_then(|blocks| blocks.checked_mul(std::mem::size_of::<u32>()))
177            .ok_or(GpuFreezeError::GeometryOverflow("block-prefix byte count"))?;
178        Ok(Self {
179            len,
180            width,
181            words_per_layer,
182            packed_words,
183            packed_bytes,
184            num_blocks,
185        })
186    }
187}
188
189#[cfg(any(test, feature = "wgpu", feature = "cuda"))]
190fn alphabet_width(size: usize) -> usize {
191    let max_code = size.saturating_sub(1);
192    (usize::BITS - max_code.leading_zeros()).max(1) as usize
193}
194
195#[cfg(test)]
196mod tests {
197    use super::*;
198
199    #[cfg(feature = "wgpu")]
200    #[test]
201    fn wgpu_freeze_is_a_send_sync_core_backend() {
202        use triblespace_core::blob::encodings::succinctarchive::WaveletMatrixFreezeBackend;
203
204        fn assert_backend<T>()
205        where
206            T: WaveletMatrixFreezeBackend<Error = GpuFreezeError> + Send + Sync,
207        {
208        }
209        assert_backend::<WgpuWaveletFreeze>();
210    }
211
212    fn geometry(alphabet_size: usize, len: usize) -> Result<FreezeGeometry, GpuFreezeError> {
213        let planes = vec![len.div_ceil(64); alphabet_width(alphabet_size)];
214        FreezeGeometry::checked(alphabet_size, len, &planes)
215    }
216
217    #[test]
218    fn packing_boundaries_are_exact() {
219        for len in [31usize, 32, 33, 63, 64, 65, 255, 256, 257] {
220            let geometry = geometry(257, len).unwrap();
221            assert_eq!(geometry.width, 9);
222            assert_eq!(geometry.words_per_layer as usize, len.div_ceil(32));
223            assert_eq!(geometry.packed_bytes, 9 * len.div_ceil(32) * 4);
224            assert_eq!(geometry.num_blocks as usize, len.div_ceil(256));
225        }
226    }
227
228    #[test]
229    fn alphabet_width_boundaries_are_exact() {
230        for (alphabet_size, expected) in
231            [(0, 1), (1, 1), (2, 1), (3, 2), (255, 8), (256, 8), (257, 9)]
232        {
233            assert_eq!(geometry(alphabet_size, 65).unwrap().width, expected);
234        }
235    }
236
237    #[cfg(target_pointer_width = "64")]
238    #[test]
239    fn rejects_alphabet_and_sequence_outside_u32_contract() {
240        assert_eq!(
241            geometry(u32::MAX as usize + 1, 1),
242            Err(GpuFreezeError::AlphabetTooWide(u32::MAX as usize + 1))
243        );
244        let too_long = u32::MAX as usize + 1;
245        let planes = vec![too_long.div_ceil(64)];
246        assert_eq!(
247            FreezeGeometry::checked(1, too_long, &planes),
248            Err(GpuFreezeError::SequenceTooLong(too_long))
249        );
250    }
251
252    #[cfg(target_pointer_width = "64")]
253    #[test]
254    fn rejects_packed_offsets_that_do_not_fit_u32() {
255        let len = u32::MAX as usize;
256        let planes = vec![len.div_ceil(64); alphabet_width(u32::MAX as usize)];
257        assert_eq!(
258            FreezeGeometry::checked(u32::MAX as usize, len, &planes),
259            Err(GpuFreezeError::GeometryOverflow("packed u32 word count"))
260        );
261    }
262
263    #[test]
264    fn rejects_malformed_output_shape() {
265        assert_eq!(
266            FreezeGeometry::checked(256, 65, &[2; 9]),
267            Err(GpuFreezeError::OutputLayers {
268                expected: 8,
269                actual: 9,
270            })
271        );
272        let mut planes = [2; 8];
273        planes[4] = 1;
274        assert_eq!(
275            FreezeGeometry::checked(256, 65, &planes),
276            Err(GpuFreezeError::OutputPlaneWords {
277                depth: 4,
278                expected: 2,
279                actual: 1,
280            })
281        );
282    }
283}