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#[derive(Debug, Eq, PartialEq)]
34pub enum GpuFreezeError {
35 AlphabetTooWide(usize),
37 SequenceTooLong(usize),
39 OutputLayers {
41 expected: usize,
43 actual: usize,
45 },
46 OutputPlaneWords {
48 depth: usize,
50 expected: usize,
52 actual: usize,
54 },
55 CodeOutOfAlphabet {
57 position: usize,
59 code: u32,
61 alphabet_size: usize,
63 },
64 GeometryOverflow(&'static str),
66 Device(String),
68 ReadbackSize {
70 expected: usize,
72 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}