primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
// SPDX-License-Identifier: AGPL-3.0-or-later

//! Self-routing precision brain — absorbed from hotSpring v0.6.25.
//!
//! Routes physics workloads to the best available precision tier, never
//! touching a tier that failed probing. Probe-first, data-driven,
//! domain-aware.
//!
//! # Design principles
//!
//! 1. **Probe-first**: Never assume a tier works. The RTX 3090 NVVM failure
//!    demonstrated that a single bad DF64 compilation poisons the wgpu device.
//! 2. **Data-driven**: Routing decisions from calibration data, not static
//!    driver-name heuristics.
//! 3. **Domain-aware**: Physics requirements (FMA sensitivity, precision floor)
//!    combined with hardware capability.
//! 4. **Portable**: Works in any spring that can construct a `WgpuDevice`.
//!
//! # Usage
//!
//! ```rust,ignore
//! let device = WgpuDevice::new().await?;
//! let brain = PrecisionBrain::from_device(&device);
//! let tier = brain.route(PhysicsDomain::Dielectric);
//! let module = brain.compile(&device, PhysicsDomain::LatticeQcd, &source, "my_shader");
//! ```

use super::WgpuDevice;
use super::capabilities::DeviceCapabilities;
use super::driver_profile::PrecisionRoutingAdvice as HwAdvice;
use super::hardware_calibration::HardwareCalibration;
use super::precision_tier::{PhysicsDomain, PrecisionBrainAdvice, PrecisionTier};

/// Number of registered domains for the routing table.
const NUM_DOMAINS: usize = 15;

const ALL_DOMAINS: [PhysicsDomain; NUM_DOMAINS] = [
    PhysicsDomain::LatticeQcd,
    PhysicsDomain::GradientFlow,
    PhysicsDomain::Dielectric,
    PhysicsDomain::KineticFluid,
    PhysicsDomain::Eigensolve,
    PhysicsDomain::MolecularDynamics,
    PhysicsDomain::NuclearEos,
    PhysicsDomain::PopulationPk,
    PhysicsDomain::Bioinformatics,
    PhysicsDomain::Hydrology,
    PhysicsDomain::Statistics,
    PhysicsDomain::General,
    PhysicsDomain::Inference,
    PhysicsDomain::Training,
    PhysicsDomain::Hashing,
];

/// Self-routing precision brain for a single GPU.
///
/// Constructed once at startup. All subsequent routing calls are O(1) lookups.
pub struct PrecisionBrain {
    /// The calibration data from probing.
    pub calibration: HardwareCalibration,
    route_table: [PrecisionTier; NUM_DOMAINS],
    hw_native: bool,
    /// Whether coralReef sovereign compilation is available for f64 lowering.
    /// When true, F64 tiers are accessible even when hardware native
    /// transcendentals fail — coralReef provides software polyfills in the
    /// compiled native binary.
    coral_f64_lowering: bool,
}

impl PrecisionBrain {
    /// Build the brain from a `WgpuDevice`, probing hardware and constructing
    /// the routing table.
    #[must_use]
    pub fn from_device(device: &WgpuDevice) -> Self {
        let caps = DeviceCapabilities::from_device(device);
        let calibration = HardwareCalibration::from_capabilities(&caps, device);
        Self::from_capabilities(calibration, &caps)
    }

    /// Build the brain with coralReef f64 lowering awareness.
    ///
    /// When `coral_f64_lowering` is true, the brain routes more aggressively
    /// to F64/DF64 tiers because coralReef provides software polyfills for
    /// transcendentals that hardware probes report as broken. The sovereign
    /// compilation pipeline bypasses naga/NVVM, so driver bugs are irrelevant.
    #[must_use]
    pub fn from_device_with_coral(device: &WgpuDevice, coral_f64_lowering: bool) -> Self {
        let caps = DeviceCapabilities::from_device(device);
        let calibration = HardwareCalibration::from_capabilities(&caps, device);
        Self::from_capabilities_with_coral(calibration, &caps, coral_f64_lowering)
    }

    /// Build the brain from pre-computed calibration and capabilities.
    #[must_use]
    pub fn from_capabilities(calibration: HardwareCalibration, caps: &DeviceCapabilities) -> Self {
        Self::from_capabilities_with_coral(calibration, caps, false)
    }

    /// Build the brain with explicit coralReef lowering flag.
    #[must_use]
    pub fn from_capabilities_with_coral(
        calibration: HardwareCalibration,
        caps: &DeviceCapabilities,
        coral_f64_lowering: bool,
    ) -> Self {
        let hw_native = matches!(
            caps.precision_routing(),
            HwAdvice::F64Native | HwAdvice::F64NativeNoSharedMem
        );

        let route_table = ALL_DOMAINS
            .map(|domain| route_domain(domain, &calibration, hw_native, coral_f64_lowering));

        tracing::info!(
            "PrecisionBrain[{}]: {calibration} (coral_f64_lowering={coral_f64_lowering})",
            calibration.adapter_name
        );
        for (i, domain) in ALL_DOMAINS.iter().enumerate() {
            tracing::debug!("  {domain:?} → {:?}", route_table[i]);
        }

        Self {
            calibration,
            route_table,
            hw_native,
            coral_f64_lowering,
        }
    }

    /// Route a physics domain to the best available precision tier.
    /// O(1) lookup.
    #[must_use]
    pub fn route(&self, domain: PhysicsDomain) -> PrecisionTier {
        self.route_table[domain_index(domain)]
    }

    /// Route and return full advice (tier + rationale + FMA safety).
    #[must_use]
    pub fn route_advice(&self, domain: PhysicsDomain) -> PrecisionBrainAdvice {
        let tier = self.route(domain);
        let (fma_safe, rationale) = domain_requirements(domain, tier);
        PrecisionBrainAdvice {
            tier,
            fma_safe,
            rationale,
        }
    }

    /// Compile a shader at the brain-selected tier for the given domain.
    ///
    /// Scale-down tiers (Binary through Bf16) and F32 use the universal
    /// `compile_shader` path — compute is in f32 after dequantization.
    /// Scale-up tiers route to their respective compilation paths.
    /// QF128 uses the f32 path (all f32 arithmetic, no f64 hardware needed).
    /// DF128 uses the f64 path (Dekker double-double on f64).
    #[must_use]
    pub fn compile(
        &self,
        device: &WgpuDevice,
        domain: PhysicsDomain,
        shader_source: &str,
        label: &str,
    ) -> wgpu::ShaderModule {
        let tier = self.route(domain);
        match tier {
            PrecisionTier::Binary
            | PrecisionTier::Int2
            | PrecisionTier::Quantized4
            | PrecisionTier::Quantized8
            | PrecisionTier::Fp8E5M2
            | PrecisionTier::Fp8E4M3
            | PrecisionTier::Bf16
            | PrecisionTier::F16
            | PrecisionTier::Tf32
            | PrecisionTier::F32
            | PrecisionTier::QF128 => device.compile_shader(shader_source, Some(label)),
            PrecisionTier::F64 | PrecisionTier::F64Precise | PrecisionTier::DF128 => {
                device.compile_shader_f64(shader_source, Some(label))
            }
            PrecisionTier::DF64 => device.compile_shader_df64(shader_source, Some(label)),
        }
    }

    /// Check if a specific tier is safe on this hardware.
    #[must_use]
    pub fn tier_safe(&self, tier: PrecisionTier) -> bool {
        self.calibration.tier_safe(tier)
    }

    /// Whether this hardware has native f64 capability.
    #[must_use]
    pub fn has_native_f64(&self) -> bool {
        self.hw_native
    }

    /// Whether coralReef sovereign f64 lowering is available.
    #[must_use]
    pub fn has_coral_f64_lowering(&self) -> bool {
        self.coral_f64_lowering
    }

    /// Adapter name.
    #[must_use]
    pub fn adapter_name(&self) -> &str {
        &self.calibration.adapter_name
    }

    /// Whether the routed tier for this domain requires sovereign compilation.
    ///
    /// Returns `true` when the domain routes to an f64-class tier and the
    /// hardware doesn't natively support it, but coralReef lowering
    /// makes it viable. In this case, the caller should prefer the coralReef
    /// `compile_wgsl_direct` path over the wgpu/naga path.
    #[must_use]
    pub fn needs_sovereign_compile(&self, domain: PhysicsDomain) -> bool {
        if !self.coral_f64_lowering {
            return false;
        }
        let tier = self.route(domain);
        matches!(
            tier,
            PrecisionTier::F64
                | PrecisionTier::F64Precise
                | PrecisionTier::DF64
                | PrecisionTier::DF128
        ) && !self.hw_native
    }
}

impl std::fmt::Display for PrecisionBrain {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        writeln!(f, "PrecisionBrain[{}]:", self.calibration.adapter_name)?;
        for (i, domain) in ALL_DOMAINS.iter().enumerate() {
            writeln!(f, "  {domain:?} → {:?}", self.route_table[i])?;
        }
        Ok(())
    }
}

// ── Routing table construction ──────────────────────────────────────────────

const fn domain_index(domain: PhysicsDomain) -> usize {
    match domain {
        PhysicsDomain::LatticeQcd => 0,
        PhysicsDomain::GradientFlow => 1,
        PhysicsDomain::Dielectric => 2,
        PhysicsDomain::KineticFluid => 3,
        PhysicsDomain::Eigensolve => 4,
        PhysicsDomain::MolecularDynamics => 5,
        PhysicsDomain::NuclearEos => 6,
        PhysicsDomain::PopulationPk => 7,
        PhysicsDomain::Bioinformatics => 8,
        PhysicsDomain::Hydrology => 9,
        PhysicsDomain::Statistics => 10,
        PhysicsDomain::General => 11,
        PhysicsDomain::Inference => 12,
        PhysicsDomain::Training => 13,
        PhysicsDomain::Hashing => 14,
    }
}

fn route_domain(
    domain: PhysicsDomain,
    cal: &HardwareCalibration,
    hw_native: bool,
    coral_f64_lowering: bool,
) -> PrecisionTier {
    let f64_safe = cal.tier_safe(PrecisionTier::F64) || coral_f64_lowering;
    let df64_safe = cal.tier_safe(PrecisionTier::DF64) || coral_f64_lowering;
    let precise_safe = cal.tier_safe(PrecisionTier::F64Precise) || coral_f64_lowering;
    let f16_safe = cal.tier_safe(PrecisionTier::F16);
    let bf16_safe = cal.tier_safe(PrecisionTier::Bf16);

    match domain {
        // Precision-critical: prefer F64Precise, cascade through tiers
        PhysicsDomain::Dielectric | PhysicsDomain::Eigensolve => {
            if (hw_native || coral_f64_lowering) && precise_safe {
                PrecisionTier::F64Precise
            } else if f64_safe {
                PrecisionTier::F64
            } else if df64_safe {
                PrecisionTier::DF64
            } else {
                PrecisionTier::F32
            }
        }

        // Moderate precision: prefer F64, cascade to DF64
        PhysicsDomain::GradientFlow
        | PhysicsDomain::NuclearEos
        | PhysicsDomain::PopulationPk
        | PhysicsDomain::Hydrology => {
            if f64_safe {
                PrecisionTier::F64
            } else if df64_safe {
                PrecisionTier::DF64
            } else {
                PrecisionTier::F32
            }
        }

        // Throughput-bound: F64 if fast, else DF64 for throughput
        PhysicsDomain::LatticeQcd
        | PhysicsDomain::KineticFluid
        | PhysicsDomain::MolecularDynamics
        | PhysicsDomain::Bioinformatics
        | PhysicsDomain::Statistics
        | PhysicsDomain::General => {
            if f64_safe {
                PrecisionTier::F64
            } else if df64_safe {
                PrecisionTier::DF64
            } else {
                PrecisionTier::F32
            }
        }

        // Inference: maximize throughput with quantized/reduced precision.
        // Q4 → Q8 → FP8 → F16 → BF16 → F32 cascade.
        PhysicsDomain::Inference => {
            if cal.tier_safe(PrecisionTier::Quantized4) {
                PrecisionTier::Quantized4
            } else if cal.tier_safe(PrecisionTier::Quantized8) {
                PrecisionTier::Quantized8
            } else if cal.tier_safe(PrecisionTier::Fp8E4M3) {
                PrecisionTier::Fp8E4M3
            } else if f16_safe {
                PrecisionTier::F16
            } else if bf16_safe {
                PrecisionTier::Bf16
            } else {
                PrecisionTier::F32
            }
        }

        // Training: mixed precision with accumulation in f32.
        // BF16 → F16 → F32 → DF64 cascade.
        PhysicsDomain::Training => {
            if bf16_safe {
                PrecisionTier::Bf16
            } else if f16_safe {
                PrecisionTier::F16
            } else if df64_safe {
                PrecisionTier::DF64
            } else {
                PrecisionTier::F32
            }
        }

        // Hashing: binary XNOR+popcount.
        PhysicsDomain::Hashing => PrecisionTier::Binary,
    }
}

fn domain_requirements(domain: PhysicsDomain, tier: PrecisionTier) -> (bool, &'static str) {
    if domain.fma_sensitive() {
        return match tier {
            PrecisionTier::F64Precise => (
                false,
                "FMA-free f64: cancellation-safe for complex arithmetic",
            ),
            PrecisionTier::F64 | PrecisionTier::DF128 => (
                true,
                "Native f64 (FMA-free unavailable, acceptable precision)",
            ),
            PrecisionTier::DF64 | PrecisionTier::QF128 => (
                false,
                "Emulated precision: ~14+ digits, sufficient for most physics",
            ),
            _ => (true, "Reduced precision fallback: validation recommended"),
        };
    }

    if domain.throughput_bound() {
        return match tier {
            PrecisionTier::F64 | PrecisionTier::F64Precise | PrecisionTier::DF128 => {
                (true, "Native f64 for compute-bound domains")
            }
            PrecisionTier::DF64 | PrecisionTier::QF128 => (
                true,
                "Emulated precision throughput mode: f32 cores for max dispatch rate",
            ),
            PrecisionTier::Binary => (true, "Binary XNOR+popcount: maximum throughput"),
            PrecisionTier::Int2 | PrecisionTier::Quantized4 | PrecisionTier::Quantized8 => {
                (true, "Quantized fast path: dequantize→f32 compute")
            }
            PrecisionTier::Fp8E4M3 | PrecisionTier::Fp8E5M2 => {
                (true, "FP8 fast path: 4× throughput over f32")
            }
            PrecisionTier::Bf16 => (true, "BF16 mixed precision: training fast path"),
            PrecisionTier::F16 => (true, "F16 tensor core fast path: max throughput"),
            PrecisionTier::Tf32 => (true, "TF32 tensor core: f32 range, reduced mantissa"),
            PrecisionTier::F32 => (true, "F32 screening/preview mode"),
        };
    }

    match tier {
        PrecisionTier::F64 | PrecisionTier::F64Precise | PrecisionTier::DF128 => {
            (true, "Native f64 for moderate precision needs")
        }
        PrecisionTier::DF64 | PrecisionTier::QF128 => {
            (true, "Emulated precision provides sufficient accuracy")
        }
        PrecisionTier::F16 => (true, "F16 fast path: screening/ML inference"),
        PrecisionTier::Bf16 => (
            true,
            "BF16: ML training, range-preserving reduced precision",
        ),
        PrecisionTier::Fp8E4M3 | PrecisionTier::Fp8E5M2 => (true, "FP8: ultra-low precision ML"),
        PrecisionTier::Binary | PrecisionTier::Int2 => (true, "Integer quantized: exact discrete"),
        PrecisionTier::Quantized4 | PrecisionTier::Quantized8 => {
            (true, "Block quantized: dequantize→compute→quantize")
        }
        PrecisionTier::Tf32 => (true, "TF32: tensor core internal format"),
        PrecisionTier::F32 => (true, "F32 fallback: validate results"),
    }
}

#[cfg(test)]
#[path = "precision_brain_tests.rs"]
mod tests;