Skip to main content

deq_runtime/decoder/
decoder_features.rs

1//! Optional capabilities supported or required by a decoder request.
2
3use crate::decoder::blackbox_decoder;
4use std::fmt;
5
6bitflags::bitflags! {
7    /// Bits 0 to 15 mirror the plugin ABI capability bitmask and must keep the
8    /// same numeric values; host-internal flags start at bit 16.
9    #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
10    pub struct DecoderFeatures: u32 {
11        const SEED = 1 << 0;
12        const REWEIGHTS = 1 << 1;
13        const LOSS = 1 << 2;
14        /// Requests model-derived observable effects during graph construction.
15        const OBSERVABLES = 1 << 3;
16    }
17}
18
19impl DecoderFeatures {
20    #[must_use]
21    pub const fn required(has_decoder_seed: bool, has_reweights: bool, has_loss: bool) -> Self {
22        let mut features = Self::empty();
23        if has_decoder_seed {
24            features = features.union(Self::SEED);
25        }
26        if has_reweights {
27            features = features.union(Self::REWEIGHTS);
28        }
29        if has_loss {
30            features = features.union(Self::LOSS);
31        }
32        features
33    }
34
35    #[cfg(any(feature = "python", test))]
36    pub(crate) fn from_protocol_name(name: &str) -> Option<Self> {
37        match name {
38            "reweights" => Some(Self::REWEIGHTS),
39            "loss" => Some(Self::LOSS),
40            "seed" => Some(Self::SEED),
41            "observables" => Some(Self::OBSERVABLES),
42            _ => None,
43        }
44    }
45
46    pub(crate) fn require_supported_by(self, supported: Self) -> Result<(), Self> {
47        let unsupported = self.difference(supported);
48        if unsupported.is_empty() { Ok(()) } else { Err(unsupported) }
49    }
50
51    pub(crate) fn to_proto(self) -> blackbox_decoder::DecoderCapabilities {
52        let mut features = Vec::with_capacity(4);
53        if self.contains(Self::REWEIGHTS) {
54            features.push(blackbox_decoder::DecoderFeature::Reweights as i32);
55        }
56        if self.contains(Self::LOSS) {
57            features.push(blackbox_decoder::DecoderFeature::Loss as i32);
58        }
59        if self.contains(Self::SEED) {
60            features.push(blackbox_decoder::DecoderFeature::Seed as i32);
61        }
62        if self.contains(Self::OBSERVABLES) {
63            features.push(blackbox_decoder::DecoderFeature::Observables as i32);
64        }
65        blackbox_decoder::DecoderCapabilities { features }
66    }
67}
68
69impl fmt::Display for DecoderFeatures {
70    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
71        let mut separator = "";
72        if self.contains(Self::REWEIGHTS) {
73            write!(formatter, "reweights")?;
74            separator = ", ";
75        }
76        if self.contains(Self::LOSS) {
77            write!(formatter, "{separator}loss")?;
78            separator = ", ";
79        }
80        if self.contains(Self::SEED) {
81            write!(formatter, "{separator}seed")?;
82            separator = ", ";
83        }
84        if self.contains(Self::OBSERVABLES) {
85            write!(formatter, "{separator}observables")?;
86        }
87        if self.is_empty() {
88            write!(formatter, "none")?;
89        }
90        Ok(())
91    }
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97
98    #[test]
99    fn required_features_compose_independently() {
100        assert_eq!(DecoderFeatures::required(false, false, false), DecoderFeatures::empty());
101        assert_eq!(DecoderFeatures::required(true, false, false), DecoderFeatures::SEED);
102        assert_eq!(DecoderFeatures::required(false, true, false), DecoderFeatures::REWEIGHTS);
103        assert_eq!(DecoderFeatures::required(false, false, true), DecoderFeatures::LOSS);
104        assert_eq!(
105            DecoderFeatures::required(true, true, true),
106            DecoderFeatures::REWEIGHTS | DecoderFeatures::LOSS | DecoderFeatures::SEED
107        );
108        assert!(
109            DecoderFeatures::LOSS
110                .require_supported_by(DecoderFeatures::REWEIGHTS | DecoderFeatures::LOSS)
111                .is_ok()
112        );
113        assert_eq!(
114            DecoderFeatures::required(false, true, true).require_supported_by(DecoderFeatures::LOSS),
115            Err(DecoderFeatures::REWEIGHTS)
116        );
117    }
118
119    #[test]
120    fn names_and_proto_use_the_protocol_vocabulary() {
121        assert_eq!(
122            DecoderFeatures::from_protocol_name("reweights"),
123            Some(DecoderFeatures::REWEIGHTS)
124        );
125        assert_eq!(DecoderFeatures::from_protocol_name("loss"), Some(DecoderFeatures::LOSS));
126        assert_eq!(DecoderFeatures::from_protocol_name("seed"), Some(DecoderFeatures::SEED));
127        assert_eq!(
128            DecoderFeatures::from_protocol_name("observables"),
129            Some(DecoderFeatures::OBSERVABLES)
130        );
131        assert_eq!(DecoderFeatures::from_protocol_name("unknown"), None);
132        assert_eq!(
133            (DecoderFeatures::REWEIGHTS | DecoderFeatures::LOSS | DecoderFeatures::SEED | DecoderFeatures::OBSERVABLES)
134                .to_proto()
135                .features,
136            vec![
137                blackbox_decoder::DecoderFeature::Reweights as i32,
138                blackbox_decoder::DecoderFeature::Loss as i32,
139                blackbox_decoder::DecoderFeature::Seed as i32,
140                blackbox_decoder::DecoderFeature::Observables as i32,
141            ]
142        );
143        assert_eq!(DecoderFeatures::OBSERVABLES.to_string(), "observables");
144        assert_eq!(
145            (DecoderFeatures::SEED | DecoderFeatures::OBSERVABLES).to_string(),
146            "seed, observables"
147        );
148    }
149}