primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
# BarraCuda WGSL Shader Library


**749 Production WGSL Shaders** (826 total including ops/) | 15-Tier Precision Continuum (Binary→DF128) | Cross-Vendor Compatible

---

## Directory Structure


All shaders are organized by function category for easy discovery and reuse.

```
src/shaders/
├── activation/       40  Non-linear activations (ReLU, GELU, Swish, Sigmoid, etc.)
├── attention/        19  Attention mechanisms (MHA, GQA, Flash, Causal, etc.)
├── audio/             9  Audio/signal processing (STFT, MFCC, Mel, Griffin-Lim, etc.)
├── augmentation/     10  Data augmentation (CutMix, Mixup, Random transforms, etc.)
├── bio/              39  Bioinformatics (Smith-Waterman, HMM, phylogenetics, etc.)
├── conv/             11  Convolution operations (1D/2D/3D, Depthwise, Dilated, etc.)
├── detection/         5  Object detection primitives (NMS, Anchors, BBox, IoU, etc.)
├── dropout/           2  Regularization (Dropout, Spatial dropout)
├── folding/          15  Protein folding (AlphaFold2 components)
├── gnn/               6  Graph neural networks (GCN, GAT, GIN, SAGE, etc.)
├── gradient/          1  Gradient manipulation (Clip norm, clip value)
├── grid/              9  Grid/mesh operations
├── interpolation/     3  Interpolation kernels (RBF, LOO-CV)
├── lattice/          36  Lattice QCD (SU(3), Wilson, Dirac, HMC)
├── linalg/           32  Linear algebra (Cholesky, Eigh, LinSolve, Inverse, etc.)
├── loss/             34  Loss functions (Focal, Dice, IoU, BCE, MSE, etc.)
├── math/            106  Element-wise math (Trig, Exp, Log, Floor, Sqrt, etc.)
├── md/                5  Molecular dynamics (forces, integrators, PBC)
├── misc/             74  Utilities (MatMul, Embedding, Quantize, etc.)
├── ml/                8  Machine learning (ESN, reservoir, etc.)
├── norm/             28  Normalization (BatchNorm, LayerNorm, GroupNorm, etc.)
├── numerical/         7  Numerical methods (ODE, integration)
├── optimizer/        18  Weight update rules (Adam, SGD, RMSProp, etc.)
├── pooling/          17  Spatial reduction (MaxPool, AvgPool, Adaptive, etc.)
├── reduce/           28  Tensor reduction (Sum, Mean, Argmax, Logsumexp, etc.)
├── rnn/               4  Recurrent networks (LSTM, GRU, BiLSTM)
├── sample/            4  Sampling methods (LHS, Sobol, etc.)
├── science/          16  Scientific compute (batched elementwise, hydrology, etc.)
├── sparse/            5  Sparse linear algebra (SpMV, CG)
├── special/          40  Special functions (Bessel, Gamma, Erf, etc.)
├── spectral/          3  Spectral analysis (Anderson, Lanczos)
├── stats/             5  Statistical operations (bootstrap, diversity, etc.)
└── tensor/           43  Shape manipulation (Concat, Slice, Reshape, Transpose, etc.)
```

**2 additional tooling directories** (`precision/`, `sovereign/`)
contain precision infrastructure and DF64 rewrite tooling rather than standalone shaders.

---

## Quick Reference


### By Use Case


**Deep Learning Training:**
- **Activation**: `activation/gelu.wgsl`, `activation/silu.wgsl`, `activation/relu.wgsl`
- **Loss**: `loss/focal_loss.wgsl`, `loss/cross_entropy.wgsl`, `loss/mse_loss.wgsl`
- **Optimizer**: `optimizer/adam.wgsl`, `optimizer/adamw.wgsl`, `optimizer/sgd.wgsl`
- **Norm**: `norm/batch_norm.wgsl`, `norm/layer_norm.wgsl`, `norm/group_norm.wgsl`

**Vision/CNN:**
- **Conv**: `conv/conv2d.wgsl`, `conv/depthwise_conv2d.wgsl`, `conv/grouped_conv2d.wgsl`
- **Pooling**: `pooling/maxpool2d.wgsl`, `pooling/avgpool2d.wgsl`, `pooling/adaptive_avgpool2d.wgsl`
- **Detection**: `detection/nms.wgsl`, `detection/anchor_generator.wgsl`, `detection/box_iou.wgsl`
- **Augment**: `augmentation/cutmix.wgsl`, `augmentation/mixup.wgsl`, `augmentation/color_jitter.wgsl`

**NLP/Transformers:**
- **Attention**: `attention/attention_matmul.wgsl`, `attention/flash_attention.wgsl`, `attention/gqa_matmul.wgsl`
- **RNN**: `rnn/lstm_cell.wgsl`, `rnn/gru_cell.wgsl`, `rnn/bi_lstm.wgsl`
- **Embedding**: `misc/embedding.wgsl`

**Scientific Computing:**
- **LinAlg**: `linalg/cholesky.wgsl`, `linalg/eigh.wgsl`, `linalg/linsolve.wgsl`, `linalg/triangular_solve.wgsl`
- **Special**: `special/bessel_j0.wgsl`, `special/bessel_i0.wgsl`, `special/spherical_harmonics.wgsl`
- **MD Forces**: `../ops/md/forces/coulomb.wgsl`, `../ops/md/forces/lennard_jones.wgsl`
- **MD Integrators**: `../ops/md/integrators/velocity_verlet.wgsl`, `../ops/md/integrators/rk4.wgsl`
- **Interpolation**: `interpolation/rbf_kernel.wgsl`, `interpolation/loo_cv.wgsl`

**Audio/Signal:**
- **Audio**: `audio/stft.wgsl`, `audio/istft.wgsl`, `audio/mfcc.wgsl`, `audio/mel_scale.wgsl`
- **FFT**: `../ops/fft/fft_1d.wgsl`

**Graph Neural Networks:**
- **GNN**: `gnn/gcn_conv.wgsl`, `gnn/gat_conv.wgsl`, `gnn/gin_conv.wgsl`, `gnn/edge_conv.wgsl`

**Cryptography:**
- **FHE**: `../ops/fhe_ntt.wgsl`, `../ops/fhe_poly_add.wgsl`, `../ops/fhe_and.wgsl`
- **Complex**: `../ops/complex/add.wgsl`, `../ops/complex/mul.wgsl`, `../ops/complex/exp.wgsl`

---

## Usage Patterns


### Including Shaders in Rust


**From ops at `src/ops/{name}.rs`:**
```rust
const SHADER: &str = include_str!("../shaders/{category}/{name}.wgsl");
```

**From ops subdirectory at `src/ops/{subdir}/mod.rs`:**
```rust
const SHADER: &str = include_str!("../../shaders/{category}/{name}.wgsl");
```

**Example:**
```rust
// src/ops/gelu.rs
const SHADER: &str = include_str!("../shaders/activation/gelu.wgsl");

// src/ops/attention/mod.rs
const ATTENTION_MATMUL: &str = include_str!("../../shaders/attention/attention_matmul.wgsl");
```

### Common Shader Patterns


**Point-wise operations (element-wise):**
- Input: `@binding(0) var<storage, read> input: array<f32>`
- Output: `@binding(1) var<storage, read_write> output: array<f32>`
- Workgroup: `@workgroup_size(256)` typically

**Reduction operations:**
- Shared memory: `var<workgroup> shared: array<f32, 256>`
- Synchronization: `workgroupBarrier()`
- Tree reduction pattern

**2D spatial operations (conv, pool):**
- Input shape: `(batch, channels, height, width)`
- Output shape calculated from input + kernel + stride + padding

**Attention patterns:**
- Q, K, V matrices
- Softmax normalization
- Causal masking for autoregressive models

---

## Adding New Shaders


### 1. Determine Category


Choose the most specific category:
- **Activation** if it's a non-linear point-wise function
- **Loss** if it's a training objective
- **Math** if it's a general mathematical operation
- **Tensor** if it's primarily about shape manipulation
- **Misc** if it doesn't fit elsewhere

### 2. Create Shader File


```bash
# Example: adding a new activation

cd crates/barracuda/src/shaders/activation
vim my_new_activation.wgsl
```

### 3. Create Rust Wrapper


```bash
cd crates/barracuda/src/ops
vim my_new_activation.rs
```

### 4. Template


```rust
use crate::prelude::*;

const SHADER: &str = include_str!("../shaders/activation/my_new_activation.wgsl");

pub struct MyNewActivation {
    input: Tensor,
}

impl MyNewActivation {
    pub fn new(input: Tensor) -> BarracudaResult<Self> {
        Ok(Self { input })
    }

    pub fn execute(self) -> BarracudaResult<Vec<f32>> {
        let device = &self.input.device;
        let size = self.input.total_size();
        
        device.execute_shader(
            SHADER,
            "MyNewActivation",
            &[&self.input.buffer],
            size,
            256,
        )
    }
}

#[cfg(test)]

mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_my_new_activation() {
        // Test implementation
    }
}
```

### 5. Register in `mod.rs`


```rust
// In src/ops/mod.rs
pub mod my_new_activation;
pub use my_new_activation::MyNewActivation;
```

---

## Shader Standards


All shaders follow these conventions:

### Naming

- **File**: `snake_case.wgsl`
- **Entry point**: Usually `@compute` with function name `main`

### Bindings

- **Read-only inputs**: `@binding(N) var<storage, read>`
- **Read-write outputs**: `@binding(N) var<storage, read_write>`
- **Uniforms**: `@binding(N) var<uniform>`

### Workgroup Size

- **1D ops**: `@workgroup_size(256)` (or 128, 512)
- **2D ops**: `@workgroup_size(16, 16)` typically
- **3D ops**: `@workgroup_size(8, 8, 8)` typically

### Precision (15-Tier Continuum — `PrecisionBrain` + coralReef Strategy Mapping)

- **Canonical**: All shaders are f64-canonical WGSL — pure math, conceptually infinite precision.
- **15 tiers**: Binary → Int2 → Q4 → Q8 → FP8-E5M2 → FP8-E4M3 → BF16 → F16 → TF32 → F32 → DF64 → F64 → F64Precise → QF128 → DF128.
- **Compile paths**: `compile_shader()` (f32 + sub-f32), `compile_shader_f64()` (f64/DF128), `compile_shader_df64()` (df64).
- **Routing**: `PrecisionBrain` routes `PhysicsDomain` to optimal tier based on `HardwareCalibration` probing.
- **DF64**: `compile_shader_df64()` auto-injects `df64_core.wgsl` + `df64_transcendentals.wgsl`.
- **Scale-up**: QF128 (Bailey quad-double on f32), DF128 (double-double on f64).
- **Scale-down**: BF16/FP8 compute in f32 with pack/unpack helpers; Q4/Q8/Int2/Binary dequantize to f32.
- **FHE**: `u32` for modular arithmetic

---

## Performance Tips


### Choosing the Right Shader


| Operation Type | Prefer | Avoid |
|----------------|--------|-------|
| Element-wise math | `math/` shaders | Custom implementations |
| Matrix multiply | `misc/matmul_tiled.wgsl` | Naive matmul |
| Convolution | `conv/conv2d.wgsl` | Im2col + matmul |
| Attention (large) | `attention/flash_attention.wgsl` | Naive attention |
| Reduction | `reduce/` shaders with tree reduction | Sequential reduction |

### Memory Access Patterns

- **Coalesced**: Access consecutive elements in a warp
- **Shared memory**: For data reuse within workgroup
- **Uniform buffers**: For small constant data

### Workgroup Size

- **NVIDIA**: Multiples of 32 (warp size)
- **AMD**: Multiples of 64 (wavefront size)
- **Intel**: Multiples of 16 (SIMD width)
- **Safe default**: 256 for 1D, (16,16) for 2D

---

## Shader Categories Explained


### activation/ (40 shaders)

Non-linear activation functions. All are element-wise operations.

**Common**: ReLU, GELU, Swish, Sigmoid, Tanh  
**Advanced**: Mish, CELU, Hardswish, PReLU, RReLU  
**Pattern**: `f(x) → y` where `x` and `y` are same shape

### attention/ (19 shaders)

Attention mechanism components for transformers.

**Core**: Attention matmul, softmax, apply  
**Variants**: Causal, cross, local, sparse  
**Advanced**: Flash attention, GQA (grouped query attention)  
**Pattern**: Q, K, V → Attention(Q,K,V)

### linalg/ (32 shaders)

Linear algebra operations for scientific computing.

**Decompositions**: Cholesky, Eigh (eigenvalue), QR, LU, SVD  
**Solvers**: LinSolve (Ax=b), triangular solve  
**Operations**: Inverse, determinant, trace  
**Pattern**: Dense matrices → decomposition or solution

### loss/ (34 shaders)

Training objectives and distance metrics.

**Classification**: Cross-entropy, focal loss, NLL  
**Detection**: IoU loss, GIoU loss, dice loss  
**Contrastive**: Triplet loss, contrastive loss, center loss  
**Regression**: MSE, MAE, Huber, smooth L1  
**Pattern**: (predictions, targets) → scalar loss

### tensor/ (43 shaders)

Shape manipulation and indexing operations.

**Combine**: Concat, stack, tile, repeat  
**Split**: Chunk, slice, split, narrow  
**Reshape**: Reshape, view, flatten, squeeze  
**Index**: Gather, scatter, index_select, masked_fill  
**Pattern**: Shape transformation without computation

---

## Finding Similar Shaders


**Need activation?** → `activation/`  
**Need loss function?** → `loss/`  
**Need matrix operation?** → `linalg/` or `misc/matmul*`  
**Need convolution?** → `conv/`  
**Need pooling?** → `pooling/`  
**Need attention?** → `attention/`  
**Need normalization?** → `norm/`  
**Need reduction?** → `reduce/`  
**Need element-wise math?** → `math/`  
**Need shape manipulation?** → `tensor/`  
**Need optimizer?** → `optimizer/`  

When in doubt, check `misc/` for general utilities.

---

## Maintenance


### Testing New Shaders

```bash
cargo test -p barracuda --lib {test_name}
```

### Benchmarking

```bash
cargo bench -p barracuda --bench {shader_category}
```

### Cross-Vendor Validation

```bash
# Run on all available GPUs

cargo test -p barracuda --lib --release
```

---

**Last Updated**: April 28, 2026  
**Shader Count**: 741 in shaders/ (816 total with ops/) — organized by domain, all f64 canonical. DF64 emulated double-precision on hardware without native f64.  
**Categories**: 41 directories  
**Status**: Production — dual-layer universal precision operational, 15-function DF64 transcendental suite complete