Skip to main content

deq_runtime/
decoder.rs

1#[cfg(feature = "cli")]
2use crate::misc::util::help_message;
3#[cfg(feature = "cli")]
4use clap::ValueEnum;
5use serde::Serialize;
6use std::sync::Arc;
7#[cfg(feature = "cli")]
8use tonic::transport::server::Router;
9use tonic::{Request, Status};
10
11#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Debug)]
12#[cfg_attr(feature = "cli", derive(ValueEnum))]
13pub enum DecoderType {
14    /// a naive decoder that returns no errors
15    #[cfg_attr(feature = "cli", value(name = "naive", alias = "black-box-naive"))]
16    BlackBoxNaive,
17    /// using the native `fusion-blossom` MWPM decoder
18    #[cfg(feature = "mwpm")]
19    #[cfg_attr(feature = "cli", value(name = "mwpm", alias = "black-box-mwpm"))]
20    BlackBoxMwpm,
21    /// using the native hypergraph MWPF decoder
22    #[cfg(feature = "mwpf")]
23    #[cfg_attr(feature = "cli", value(name = "mwpf", alias = "black-box-mwpf"))]
24    BlackBoxMwpf,
25    /// using Fusion Blossom in union-find mode
26    #[cfg(feature = "mwpm")]
27    #[cfg_attr(feature = "cli", value(name = "uf", alias = "black-box-uf"))]
28    BlackBoxUf,
29    /// using MWPF in hypergraph union-find mode
30    #[cfg(feature = "mwpf")]
31    #[cfg_attr(feature = "cli", value(name = "huf", alias = "black-box-huf"))]
32    BlackBoxHuf,
33    /// using the public `relay-bp` crate as a blackbox (default f64)
34    #[cfg(feature = "relay-bp")]
35    #[cfg_attr(feature = "cli", value(name = "relay-bp", alias = "black-box-relay-bp"))]
36    BlackBoxRelayBP,
37    #[cfg(feature = "relay-bp")]
38    #[cfg_attr(feature = "cli", value(name = "relay-bp-f32", alias = "black-box-relay-bp-f32"))]
39    BlackBoxRelayBpF32,
40    /// using a Python-defined decoder as a blackbox
41    #[cfg(feature = "python")]
42    #[cfg_attr(feature = "cli", value(name = "python", alias = "black-box-python"))]
43    BlackBoxPython,
44    /// using Google's Tesseract beam-search decoder as a blackbox
45    #[cfg(feature = "tesseract")]
46    #[cfg_attr(feature = "cli", value(name = "tesseract", alias = "black-box-tesseract"))]
47    BlackBoxTesseract,
48    /// loading a decoder from a binary-only shared library at runtime via the C ABI
49    #[cfg(feature = "dylib")]
50    #[cfg_attr(feature = "cli", value(name = "dyn-lib", alias = "black-box-dyn-lib"))]
51    BlackBoxDynLib,
52    /// a mock decoder that returns no errors, with configurable latency
53    Mock,
54}
55
56impl crate::controller::ParseByName for DecoderType {
57    fn from_name(name: &str) -> Option<Self> {
58        match name {
59            "naive" | "black-box-naive" => Some(Self::BlackBoxNaive),
60            #[cfg(feature = "mwpm")]
61            "mwpm" | "black-box-mwpm" => Some(Self::BlackBoxMwpm),
62            #[cfg(feature = "mwpf")]
63            "mwpf" | "black-box-mwpf" => Some(Self::BlackBoxMwpf),
64            #[cfg(feature = "mwpm")]
65            "uf" | "black-box-uf" => Some(Self::BlackBoxUf),
66            #[cfg(feature = "mwpf")]
67            "huf" | "black-box-huf" => Some(Self::BlackBoxHuf),
68            #[cfg(feature = "relay-bp")]
69            "relay-bp" | "black-box-relay-bp" => Some(Self::BlackBoxRelayBP),
70            #[cfg(feature = "relay-bp")]
71            "relay-bp-f32" | "black-box-relay-bp-f32" => Some(Self::BlackBoxRelayBpF32),
72            #[cfg(feature = "python")]
73            "python" | "black-box-python" => Some(Self::BlackBoxPython),
74            #[cfg(feature = "tesseract")]
75            "tesseract" | "black-box-tesseract" => Some(Self::BlackBoxTesseract),
76            #[cfg(feature = "dylib")]
77            "dyn-lib" | "black-box-dyn-lib" => Some(Self::BlackBoxDynLib),
78            "mock" => Some(Self::Mock),
79            _ => None,
80        }
81    }
82
83    fn variant_names() -> Vec<&'static str> {
84        #[allow(unused_mut)]
85        let mut names = vec!["naive", "black-box-naive"];
86        #[cfg(feature = "relay-bp")]
87        names.extend(["relay-bp", "relay-bp-f32", "black-box-relay-bp", "black-box-relay-bp-f32"]);
88        #[cfg(feature = "mwpm")]
89        names.extend(["mwpm", "uf", "black-box-mwpm", "black-box-uf"]);
90        #[cfg(feature = "mwpf")]
91        names.extend(["mwpf", "huf", "black-box-mwpf", "black-box-huf"]);
92        #[cfg(feature = "python")]
93        names.extend(["python", "black-box-python"]);
94        #[cfg(feature = "tesseract")]
95        names.extend(["tesseract", "black-box-tesseract"]);
96        #[cfg(feature = "dylib")]
97        names.extend(["dyn-lib", "black-box-dyn-lib"]);
98        names.push("mock");
99        names
100    }
101}
102
103pub mod blackbox_decoder {
104    include!("proto/deq.decoder.blackbox_decoder.rs");
105}
106
107pub mod blackbox_util;
108pub mod decoder_features;
109pub use decoder_features::DecoderFeatures;
110pub mod mock_decoder;
111pub mod test_harness;
112pub mod test_problems;
113pub mod thread_pooling;
114
115pub mod naive_decoder;
116pub use mock_decoder::MockDecoder;
117pub use naive_decoder::NaiveDecoder;
118
119#[cfg(feature = "mwpm")]
120pub mod mwpm_decoder;
121#[cfg(feature = "mwpm")]
122pub use mwpm_decoder::MwpmDecoder;
123
124#[cfg(feature = "mwpf")]
125pub mod mwpf_decoder;
126#[cfg(feature = "mwpf")]
127pub use mwpf_decoder::MwpfDecoder;
128
129#[cfg(feature = "mwpm")]
130pub mod uf_decoder;
131#[cfg(feature = "mwpm")]
132pub use uf_decoder::UfDecoder;
133
134#[cfg(feature = "mwpf")]
135pub mod huf_decoder;
136#[cfg(feature = "mwpf")]
137pub use huf_decoder::HufDecoder;
138
139#[cfg(feature = "relay-bp")]
140pub mod relay_bp_decoder;
141#[cfg(feature = "relay-bp")]
142pub use relay_bp_decoder::RelayBPDecoder;
143
144#[cfg(feature = "dylib")]
145pub mod dyn_lib_decoder;
146#[cfg(feature = "dylib")]
147pub use dyn_lib_decoder::DynLibDecoder;
148
149#[cfg(feature = "python")]
150pub mod python_decoder;
151#[cfg(feature = "python")]
152pub use python_decoder::PythonDecoder;
153
154#[cfg(feature = "tesseract")]
155pub mod tesseract_decoder;
156#[cfg(feature = "tesseract")]
157mod tesseract_ffi;
158#[cfg(feature = "tesseract")]
159pub use tesseract_decoder::TesseractDecoder;
160
161impl DecoderType {
162    pub fn create(&self, config: serde_json::Value) -> DynDecoder {
163        self.create_with_thread_pool(config, None)
164    }
165
166    pub(crate) fn create_with_thread_pool(
167        self,
168        config: serde_json::Value,
169        thread_pool: Option<Arc<rayon::ThreadPool>>,
170    ) -> DynDecoder {
171        #[cfg(not(any(
172            feature = "mwpm",
173            feature = "mwpf",
174            feature = "relay-bp",
175            feature = "python",
176            feature = "tesseract",
177            feature = "dylib"
178        )))]
179        let _ = thread_pool;
180        match self {
181            Self::BlackBoxNaive => DynDecoder::BlackBoxNaive(Arc::new(NaiveDecoder::new(config))),
182            #[cfg(feature = "mwpm")]
183            Self::BlackBoxMwpm => DynDecoder::BlackBoxMwpm(Arc::new(MwpmDecoder::with_thread_pool(config, thread_pool))),
184            #[cfg(feature = "mwpf")]
185            Self::BlackBoxMwpf => DynDecoder::BlackBoxMwpf(Arc::new(MwpfDecoder::with_thread_pool(config, thread_pool))),
186            #[cfg(feature = "mwpm")]
187            Self::BlackBoxUf => DynDecoder::BlackBoxUf(Arc::new(UfDecoder::with_thread_pool(config, thread_pool))),
188            #[cfg(feature = "mwpf")]
189            Self::BlackBoxHuf => DynDecoder::BlackBoxHuf(Arc::new(HufDecoder::with_thread_pool(config, thread_pool))),
190            #[cfg(feature = "relay-bp")]
191            Self::BlackBoxRelayBP => {
192                DynDecoder::BlackBoxRelayBP(Arc::new(RelayBPDecoder::with_thread_pool(config, thread_pool)))
193            }
194            #[cfg(feature = "relay-bp")]
195            Self::BlackBoxRelayBpF32 => {
196                DynDecoder::BlackBoxRelayBpF32(Arc::new(RelayBPDecoder::<f32>::with_thread_pool(config, thread_pool)))
197            }
198            #[cfg(feature = "python")]
199            Self::BlackBoxPython => {
200                DynDecoder::BlackBoxPython(Arc::new(PythonDecoder::with_thread_pool(config, thread_pool)))
201            }
202            #[cfg(feature = "tesseract")]
203            Self::BlackBoxTesseract => {
204                DynDecoder::BlackBoxTesseract(Arc::new(TesseractDecoder::with_thread_pool(config, thread_pool)))
205            }
206            #[cfg(feature = "dylib")]
207            Self::BlackBoxDynLib => {
208                DynDecoder::BlackBoxDynLib(Arc::new(DynLibDecoder::with_thread_pool(config, thread_pool)))
209            }
210            Self::Mock => DynDecoder::Mock(Arc::new(MockDecoder::from_config(config))),
211        }
212    }
213
214    #[cfg(feature = "cli")]
215    pub fn config_help() -> String {
216        help_message::<naive_decoder::NaiveDecoderConfig>("NaiveDecoderConfig:")
217            + &*{
218                #[cfg(feature = "mwpm")]
219                {
220                    help_message::<mwpm_decoder::MwpmDecoderConfig>("MwpmDecoderConfig:")
221                        + &*help_message::<uf_decoder::UfDecoderConfig>("UfDecoderConfig:")
222                }
223                #[cfg(not(feature = "mwpm"))]
224                {
225                    String::new()
226                }
227            }
228            + &*{
229                #[cfg(feature = "mwpf")]
230                {
231                    help_message::<mwpf_decoder::MwpfDecoderConfig>("MwpfDecoderConfig:")
232                        + &*help_message::<huf_decoder::HufDecoderConfig>("HufDecoderConfig:")
233                }
234                #[cfg(not(feature = "mwpf"))]
235                {
236                    String::new()
237                }
238            }
239            + &*{
240                #[cfg(feature = "relay-bp")]
241                {
242                    help_message::<relay_bp_decoder::RelayBPDecoderConfig>("RelayBPDecoderConfig:")
243                }
244                #[cfg(not(feature = "relay-bp"))]
245                {
246                    String::new()
247                }
248            }
249            + &*{
250                #[cfg(feature = "python")]
251                {
252                    help_message::<python_decoder::PythonDecoderConfig>("PythonDecoderConfig:")
253                }
254                #[cfg(not(feature = "python"))]
255                {
256                    String::new()
257                }
258            }
259            + &*{
260                #[cfg(feature = "tesseract")]
261                {
262                    help_message::<tesseract_decoder::TesseractDecoderConfig>("TesseractDecoderConfig:")
263                }
264                #[cfg(not(feature = "tesseract"))]
265                {
266                    String::new()
267                }
268            }
269            + &*{
270                #[cfg(feature = "dylib")]
271                {
272                    help_message::<dyn_lib_decoder::DynLibDecoderConfig>("DynLibDecoderConfig:")
273                }
274                #[cfg(not(feature = "dylib"))]
275                {
276                    String::new()
277                }
278            }
279            + &*help_message::<mock_decoder::MockDecoderConfig>("MockDecoderConfig:")
280    }
281
282    #[cfg(not(feature = "cli"))]
283    pub fn config_help() -> String {
284        String::new()
285    }
286}
287
288#[derive(Clone)]
289pub enum DynDecoder {
290    BlackBoxNaive(Arc<NaiveDecoder>),
291    #[cfg(feature = "mwpm")]
292    BlackBoxMwpm(Arc<MwpmDecoder>),
293    #[cfg(feature = "mwpf")]
294    BlackBoxMwpf(Arc<MwpfDecoder>),
295    #[cfg(feature = "mwpm")]
296    BlackBoxUf(Arc<UfDecoder>),
297    #[cfg(feature = "mwpf")]
298    BlackBoxHuf(Arc<HufDecoder>),
299    #[cfg(feature = "relay-bp")]
300    BlackBoxRelayBP(Arc<RelayBPDecoder>),
301    #[cfg(feature = "relay-bp")]
302    BlackBoxRelayBpF32(Arc<RelayBPDecoder<f32>>),
303    #[cfg(feature = "python")]
304    BlackBoxPython(Arc<PythonDecoder>),
305    #[cfg(feature = "tesseract")]
306    BlackBoxTesseract(Arc<TesseractDecoder>),
307    #[cfg(feature = "dylib")]
308    BlackBoxDynLib(Arc<DynLibDecoder>),
309    Mock(Arc<MockDecoder>),
310}
311
312impl DynDecoder {
313    #[cfg(feature = "cli")]
314    pub(crate) fn thread_pool(&self) -> Option<&Arc<rayon::ThreadPool>> {
315        match self {
316            Self::BlackBoxNaive(_) | Self::Mock(_) => None,
317            #[cfg(feature = "mwpm")]
318            Self::BlackBoxMwpm(decoder) => Some(&decoder.thread_pool),
319            #[cfg(feature = "mwpf")]
320            Self::BlackBoxMwpf(decoder) => Some(&decoder.thread_pool),
321            #[cfg(feature = "mwpm")]
322            Self::BlackBoxUf(decoder) => Some(&decoder.thread_pool),
323            #[cfg(feature = "mwpf")]
324            Self::BlackBoxHuf(decoder) => Some(&decoder.thread_pool),
325            #[cfg(feature = "relay-bp")]
326            Self::BlackBoxRelayBP(decoder) => Some(&decoder.thread_pool),
327            #[cfg(feature = "relay-bp")]
328            Self::BlackBoxRelayBpF32(decoder) => Some(&decoder.thread_pool),
329            #[cfg(feature = "python")]
330            Self::BlackBoxPython(decoder) => Some(&decoder.thread_pool),
331            #[cfg(feature = "tesseract")]
332            Self::BlackBoxTesseract(decoder) => Some(&decoder.thread_pool),
333            #[cfg(feature = "dylib")]
334            Self::BlackBoxDynLib(decoder) => Some(&decoder.thread_pool),
335        }
336    }
337
338    #[cfg(feature = "cli")]
339    pub fn add_service(&self, router: Router) -> Router {
340        match self {
341            DynDecoder::BlackBoxNaive(decoder) => NaiveDecoder::add_service(decoder, router),
342            #[cfg(feature = "mwpm")]
343            DynDecoder::BlackBoxMwpm(decoder) => MwpmDecoder::add_service(decoder, router),
344            #[cfg(feature = "mwpf")]
345            DynDecoder::BlackBoxMwpf(decoder) => MwpfDecoder::add_service(decoder, router),
346            #[cfg(feature = "mwpm")]
347            DynDecoder::BlackBoxUf(decoder) => UfDecoder::add_service(decoder, router),
348            #[cfg(feature = "mwpf")]
349            DynDecoder::BlackBoxHuf(decoder) => HufDecoder::add_service(decoder, router),
350            #[cfg(feature = "relay-bp")]
351            DynDecoder::BlackBoxRelayBP(decoder) => RelayBPDecoder::add_service(decoder, router),
352            #[cfg(feature = "relay-bp")]
353            DynDecoder::BlackBoxRelayBpF32(decoder) => RelayBPDecoder::<f32>::add_service(decoder, router),
354            #[cfg(feature = "python")]
355            DynDecoder::BlackBoxPython(decoder) => PythonDecoder::add_service(decoder, router),
356            #[cfg(feature = "tesseract")]
357            DynDecoder::BlackBoxTesseract(decoder) => TesseractDecoder::add_service(decoder, router),
358            #[cfg(feature = "dylib")]
359            DynDecoder::BlackBoxDynLib(decoder) => DynLibDecoder::add_service(decoder, router),
360            DynDecoder::Mock(decoder) => MockDecoder::add_service(decoder, router),
361        }
362    }
363
364    fn inner(&self) -> &dyn blackbox_decoder::black_box_decoder_server::BlackBoxDecoder {
365        match self {
366            DynDecoder::BlackBoxNaive(decoder) => decoder.as_ref(),
367            #[cfg(feature = "mwpm")]
368            DynDecoder::BlackBoxMwpm(decoder) => decoder.as_ref(),
369            #[cfg(feature = "mwpf")]
370            DynDecoder::BlackBoxMwpf(decoder) => decoder.as_ref(),
371            #[cfg(feature = "mwpm")]
372            DynDecoder::BlackBoxUf(decoder) => decoder.as_ref(),
373            #[cfg(feature = "mwpf")]
374            DynDecoder::BlackBoxHuf(decoder) => decoder.as_ref(),
375            #[cfg(feature = "relay-bp")]
376            DynDecoder::BlackBoxRelayBP(decoder) => decoder.as_ref(),
377            #[cfg(feature = "relay-bp")]
378            DynDecoder::BlackBoxRelayBpF32(decoder) => decoder.as_ref(),
379            #[cfg(feature = "python")]
380            DynDecoder::BlackBoxPython(decoder) => decoder.as_ref(),
381            #[cfg(feature = "tesseract")]
382            DynDecoder::BlackBoxTesseract(decoder) => decoder.as_ref(),
383            #[cfg(feature = "dylib")]
384            DynDecoder::BlackBoxDynLib(decoder) => decoder.as_ref(),
385            DynDecoder::Mock(decoder) => decoder.as_ref(),
386        }
387    }
388
389    #[must_use]
390    pub fn features(&self) -> DecoderFeatures {
391        match self {
392            DynDecoder::BlackBoxNaive(decoder) => decoder.supported_features(),
393            #[cfg(feature = "mwpm")]
394            DynDecoder::BlackBoxMwpm(decoder) => decoder.features(),
395            #[cfg(feature = "mwpf")]
396            DynDecoder::BlackBoxMwpf(decoder) => decoder.features(),
397            #[cfg(feature = "mwpm")]
398            DynDecoder::BlackBoxUf(decoder) => decoder.features(),
399            #[cfg(feature = "mwpf")]
400            DynDecoder::BlackBoxHuf(decoder) => decoder.features(),
401            #[cfg(feature = "relay-bp")]
402            DynDecoder::BlackBoxRelayBP(decoder) => decoder.features(),
403            #[cfg(feature = "relay-bp")]
404            DynDecoder::BlackBoxRelayBpF32(decoder) => decoder.features(),
405            #[cfg(feature = "python")]
406            DynDecoder::BlackBoxPython(decoder) => decoder.features(),
407            #[cfg(feature = "tesseract")]
408            DynDecoder::BlackBoxTesseract(decoder) => decoder.features(),
409            #[cfg(feature = "dylib")]
410            DynDecoder::BlackBoxDynLib(decoder) => decoder.features(),
411            DynDecoder::Mock(decoder) => decoder.supported_features(),
412        }
413    }
414
415    fn require_features(&self, required: DecoderFeatures) -> Result<(), Status> {
416        required
417            .require_supported_by(self.features())
418            .map_err(|unsupported| Status::failed_precondition(format!("unsupported decoder features: {unsupported}")))
419    }
420
421    pub async fn decode(
422        &self,
423        problem: blackbox_decoder::DecodingProblem,
424    ) -> Result<blackbox_decoder::ParityFactor, Status> {
425        self.require_features(DecoderFeatures::required(
426            problem.decoder_seed.is_some(),
427            false,
428            problem.loss.is_some(),
429        ))?;
430        self.inner().decode(Request::new(problem)).await.map(|v| v.into_inner())
431    }
432
433    pub async fn load_hypergraph(
434        &self,
435        hypergraph: blackbox_decoder::DecodingHypergraph,
436    ) -> Result<blackbox_decoder::LoadHypergraphResponse, Status> {
437        self.inner()
438            .load_hypergraph(Request::new(hypergraph))
439            .await
440            .map(|v| v.into_inner())
441    }
442
443    pub async fn decode_loaded(
444        &self,
445        problem: blackbox_decoder::LoadedDecodingProblem,
446    ) -> Result<blackbox_decoder::ParityFactor, Status> {
447        let required = DecoderFeatures::required(
448            problem.decoder_seed.is_some(),
449            !problem.reweights.is_empty(),
450            problem.loss.is_some(),
451        );
452        self.require_features(required)?;
453        self.inner()
454            .decode_loaded(Request::new(problem))
455            .await
456            .map(|v| v.into_inner())
457    }
458
459    pub async fn reset(&self, flags: blackbox_decoder::ResetRequest) -> Result<(), Status> {
460        self.inner().reset(Request::new(flags)).await.map(|_| ())
461    }
462}
463
464#[cfg(test)]
465mod tests {
466    use super::*;
467    use crate::controller::ParseByName;
468
469    #[test]
470    fn manual_parser_accepts_short_and_legacy_names() {
471        let names = [
472            ("naive", "black-box-naive", DecoderType::BlackBoxNaive),
473            #[cfg(feature = "mwpm")]
474            ("mwpm", "black-box-mwpm", DecoderType::BlackBoxMwpm),
475            #[cfg(feature = "mwpf")]
476            ("mwpf", "black-box-mwpf", DecoderType::BlackBoxMwpf),
477            #[cfg(feature = "mwpm")]
478            ("uf", "black-box-uf", DecoderType::BlackBoxUf),
479            #[cfg(feature = "mwpf")]
480            ("huf", "black-box-huf", DecoderType::BlackBoxHuf),
481            #[cfg(feature = "relay-bp")]
482            ("relay-bp", "black-box-relay-bp", DecoderType::BlackBoxRelayBP),
483            #[cfg(feature = "relay-bp")]
484            ("relay-bp-f32", "black-box-relay-bp-f32", DecoderType::BlackBoxRelayBpF32),
485            #[cfg(feature = "python")]
486            ("python", "black-box-python", DecoderType::BlackBoxPython),
487            #[cfg(feature = "tesseract")]
488            ("tesseract", "black-box-tesseract", DecoderType::BlackBoxTesseract),
489            #[cfg(feature = "dylib")]
490            ("dyn-lib", "black-box-dyn-lib", DecoderType::BlackBoxDynLib),
491        ];
492        for (short, legacy, expected) in names {
493            assert_eq!(DecoderType::from_name(short), Some(expected));
494            assert_eq!(DecoderType::from_name(legacy), Some(expected));
495            assert!(DecoderType::variant_names().contains(&short));
496            assert!(DecoderType::variant_names().contains(&legacy));
497        }
498    }
499}