Skip to main content

qualia_core_db/solvers/calculus/
capabilities.rs

1//! Machine-readable capability truth for the native calculus surface.
2//!
3//! Descriptors are static POD-like metadata: discovery allocates nothing and
4//! never infers mathematical guarantees from a function name.
5
6use crate::q_hash;
7
8#[repr(u8)]
9#[derive(Debug, Clone, Copy, PartialEq, Eq)]
10pub enum ScalarType {
11    F32 = 1,
12    F64 = 2,
13    Complex64 = 3,
14}
15
16#[repr(u8)]
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum AccuracyModel {
19    ExactAlgebraic = 1,
20    FixedOrder = 2,
21    EmbeddedEstimate = 3,
22    ResidualControlled = 4,
23    DiagnosticOnly = 5,
24}
25
26#[repr(u8)]
27#[derive(Debug, Clone, Copy, PartialEq, Eq)]
28pub enum StepControl {
29    NotApplicable = 0,
30    Fixed = 1,
31    Adaptive = 2,
32}
33
34#[repr(u8)]
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum AllocationClass {
37    ZeroHeap = 0,
38    CallerWorkspace = 1,
39    ColdHeap = 2,
40}
41
42#[repr(u8)]
43#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
44pub enum Maturity {
45    Foundation = 0,
46    Verified = 1,
47    Certified = 2,
48}
49
50#[repr(transparent)]
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub struct BackendSet(pub u8);
53
54impl BackendSet {
55    pub const SCALAR_CPU: u8 = 1 << 0;
56    pub const SIMD_CPU: u8 = 1 << 1;
57    pub const GPU: u8 = 1 << 2;
58    pub const WASM: u8 = 1 << 3;
59
60    /// Creates a default `BackendSet`.
61    pub const fn new(bits: u8) -> Self {
62        Self(bits)
63    }
64
65    /// `BackendSet::contains`.
66    pub const fn contains(self, backend: u8) -> bool {
67        self.0 & backend == backend
68    }
69}
70
71#[repr(C)]
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
73pub struct CalculusCapability {
74    pub operation_id: u64,
75    pub name: &'static str,
76    pub minimum_dimension: u16,
77    /// Zero denotes runtime/caller-bounded dimension.
78    pub maximum_dimension: u16,
79    pub scalar: ScalarType,
80    pub accuracy: AccuracyModel,
81    pub formal_order: u8,
82    pub step_control: StepControl,
83    pub allocation: AllocationClass,
84    pub backends: BackendSet,
85    pub maturity: Maturity,
86}
87
88const CPU: BackendSet = BackendSet::new(BackendSet::SCALAR_CPU | BackendSet::WASM);
89const SIMD_CPU: BackendSet =
90    BackendSet::new(BackendSet::SCALAR_CPU | BackendSet::SIMD_CPU | BackendSet::WASM);
91const PORTABLE_GPU: BackendSet =
92    BackendSet::new(BackendSet::SCALAR_CPU | BackendSet::GPU | BackendSet::WASM);
93
94pub const CALCULUS_CAPABILITIES: &[CalculusCapability] = &[
95    CalculusCapability {
96        operation_id: q_hash("q42:calculus:simpson-1-3"),
97        name: "composite Simpson 1/3 quadrature",
98        minimum_dimension: 1,
99        maximum_dimension: 1,
100        scalar: ScalarType::F64,
101        accuracy: AccuracyModel::FixedOrder,
102        formal_order: 4,
103        step_control: StepControl::Fixed,
104        allocation: AllocationClass::ZeroHeap,
105        backends: SIMD_CPU,
106        maturity: Maturity::Verified,
107    },
108    CalculusCapability {
109        operation_id: q_hash("q42:calculus:trapezoid"),
110        name: "composite trapezoidal quadrature",
111        minimum_dimension: 1,
112        maximum_dimension: 1,
113        scalar: ScalarType::F64,
114        accuracy: AccuracyModel::FixedOrder,
115        formal_order: 2,
116        step_control: StepControl::Fixed,
117        allocation: AllocationClass::ZeroHeap,
118        backends: CPU,
119        maturity: Maturity::Verified,
120    },
121    CalculusCapability {
122        operation_id: q_hash("q42:calculus:gpu-simpson-1-3-f32"),
123        name: "portable GPU Simpson 1/3 quadrature",
124        minimum_dimension: 1,
125        maximum_dimension: 1,
126        scalar: ScalarType::F32,
127        accuracy: AccuracyModel::FixedOrder,
128        formal_order: 4,
129        step_control: StepControl::Fixed,
130        allocation: AllocationClass::ColdHeap,
131        backends: PORTABLE_GPU,
132        maturity: Maturity::Foundation,
133    },
134    CalculusCapability {
135        operation_id: q_hash("q42:calculus:rk4-static"),
136        name: "fixed-state classical Runge-Kutta",
137        minimum_dimension: 4,
138        maximum_dimension: 4,
139        scalar: ScalarType::F64,
140        accuracy: AccuracyModel::FixedOrder,
141        formal_order: 4,
142        step_control: StepControl::Fixed,
143        allocation: AllocationClass::ZeroHeap,
144        backends: CPU,
145        maturity: Maturity::Verified,
146    },
147    CalculusCapability {
148        operation_id: q_hash("q42:calculus:rk4-dense"),
149        name: "dynamic classical Runge-Kutta",
150        minimum_dimension: 1,
151        maximum_dimension: 0,
152        scalar: ScalarType::F64,
153        accuracy: AccuracyModel::FixedOrder,
154        formal_order: 4,
155        step_control: StepControl::Fixed,
156        allocation: AllocationClass::ColdHeap,
157        backends: CPU,
158        maturity: Maturity::Verified,
159    },
160    CalculusCapability {
161        operation_id: q_hash("q42:calculus:shooting-newton-static"),
162        name: "fixed-state Newton shooting BVP",
163        minimum_dimension: 4,
164        maximum_dimension: 4,
165        scalar: ScalarType::F64,
166        accuracy: AccuracyModel::ResidualControlled,
167        formal_order: 4,
168        step_control: StepControl::Fixed,
169        allocation: AllocationClass::ZeroHeap,
170        backends: CPU,
171        maturity: Maturity::Verified,
172    },
173    CalculusCapability {
174        operation_id: q_hash("q42:calculus:bdf1"),
175        name: "scalar backward Euler",
176        minimum_dimension: 1,
177        maximum_dimension: 1,
178        scalar: ScalarType::F64,
179        accuracy: AccuracyModel::ResidualControlled,
180        formal_order: 1,
181        step_control: StepControl::Fixed,
182        allocation: AllocationClass::ZeroHeap,
183        backends: CPU,
184        maturity: Maturity::Foundation,
185    },
186    CalculusCapability {
187        operation_id: q_hash("q42:calculus:bdf2"),
188        name: "scalar BDF2",
189        minimum_dimension: 1,
190        maximum_dimension: 1,
191        scalar: ScalarType::F64,
192        accuracy: AccuracyModel::ResidualControlled,
193        formal_order: 2,
194        step_control: StepControl::Fixed,
195        allocation: AllocationClass::ZeroHeap,
196        backends: CPU,
197        maturity: Maturity::Foundation,
198    },
199    CalculusCapability {
200        operation_id: q_hash("q42:calculus:symplectic-separable"),
201        name: "scalar separable symplectic integration",
202        minimum_dimension: 2,
203        maximum_dimension: 2,
204        scalar: ScalarType::F64,
205        accuracy: AccuracyModel::FixedOrder,
206        formal_order: 4,
207        step_control: StepControl::Fixed,
208        allocation: AllocationClass::ColdHeap,
209        backends: CPU,
210        maturity: Maturity::Verified,
211    },
212    CalculusCapability {
213        operation_id: q_hash("q42:calculus:forward-sensitivity-scalar"),
214        name: "scalar forward sensitivity",
215        minimum_dimension: 1,
216        maximum_dimension: 1,
217        scalar: ScalarType::F64,
218        accuracy: AccuracyModel::FixedOrder,
219        formal_order: 4,
220        step_control: StepControl::Fixed,
221        allocation: AllocationClass::ColdHeap,
222        backends: CPU,
223        maturity: Maturity::Verified,
224    },
225    CalculusCapability {
226        operation_id: q_hash("q42:calculus:symbolic-multivariable"),
227        name: "symbolic gradient Jacobian and Hessian",
228        minimum_dimension: 1,
229        maximum_dimension: 0,
230        scalar: ScalarType::F64,
231        accuracy: AccuracyModel::ExactAlgebraic,
232        formal_order: 0,
233        step_control: StepControl::NotApplicable,
234        allocation: AllocationClass::ColdHeap,
235        backends: CPU,
236        maturity: Maturity::Verified,
237    },
238];
239
240/// Capability descriptor.
241pub fn capability(operation_id: u64) -> Option<&'static CalculusCapability> {
242    CALCULUS_CAPABILITIES
243        .iter()
244        .find(|entry| entry.operation_id == operation_id)
245}
246
247#[cfg(test)]
248mod tests {
249    use super::*;
250
251    #[test]
252    fn capability_ids_are_unique_and_backend_claims_are_nonempty() {
253        for (index, capability) in CALCULUS_CAPABILITIES.iter().enumerate() {
254            assert_ne!(capability.operation_id, 0);
255            assert_ne!(capability.backends.0, 0);
256            for other in &CALCULUS_CAPABILITIES[index + 1..] {
257                assert_ne!(capability.operation_id, other.operation_id);
258            }
259        }
260    }
261
262    #[test]
263    fn capability_lookup_is_allocation_free_static_discovery() {
264        let id = q_hash("q42:calculus:simpson-1-3");
265        let descriptor = capability(id).unwrap();
266        assert_eq!(descriptor.formal_order, 4);
267        assert_eq!(descriptor.maturity, Maturity::Verified);
268        assert!(descriptor.backends.contains(BackendSet::SIMD_CPU));
269    }
270}