primal-barracuda 0.4.0

barraCuda — BARrier-free Rust Abstracted Cross-platform Unified Dimensional Algebra. Vendor-agnostic GPU compute via WGSL.
Documentation
// SPDX-License-Identifier: AGPL-3.0-or-later
// Finite-Difference Gradient Operations on Structured Grids (f64)
//
// Generic gradient computation using central finite differences:
//   ∂f/∂x = (f[i+1] - f[i-1]) / (2·Δx)    (central)
//   ∂f/∂x = (f[i+1] - f[i]) / Δx          (forward, at boundaries)
//   ∂f/∂x = (f[i] - f[i-1]) / Δx          (backward, at boundaries)
//
// Applications: fluid dynamics, heat transfer, wave propagation,
//   electrostatics, image processing, molecular dynamics, nuclear structure
// Validated by: hotSpring nuclear EOS study (169/169 acceptance checks)
//
// Grid types supported:
//   - 1D: linear array
//   - 2D: row-major [nx × ny] or column-major
//   - 3D: row-major [nx × ny × nz]
//   - Cylindrical: (ρ, z) with ρ ∈ [dρ, ρ_max], z ∈ [z_min, z_max]
//
// Deep Debt: pure WGSL, f64, self-contained, physics-agnostic

// ═══════════════════════════════════════════════════════════════════
// 1D Gradient
// ═══════════════════════════════════════════════════════════════════

struct Grad1DParams {
    n: u32,         // Grid size
    _pad0: u32,
    _pad1: u32,
    _pad2: u32,
    dx: f64,        // Grid spacing
}

@group(0) @binding(0) var<uniform> grad1d_params: Grad1DParams;
@group(0) @binding(1) var<storage, read> input_1d: array<f64>;
@group(0) @binding(2) var<storage, read_write> grad_1d: array<f64>;

@compute @workgroup_size(256)
fn gradient_1d(@builtin(global_invocation_id) gid: vec3<u32>) {
    let i = gid.x;
    if (i >= grad1d_params.n) { return; }

    var deriv: f64;
    if (i == 0u) {
        // Forward difference at left boundary
        deriv = (input_1d[1u] - input_1d[0u]) / grad1d_params.dx;
    } else if (i == grad1d_params.n - 1u) {
        // Backward difference at right boundary
        deriv = (input_1d[i] - input_1d[i - 1u]) / grad1d_params.dx;
    } else {
        // Central difference in interior
        deriv = (input_1d[i + 1u] - input_1d[i - 1u]) / (f64(2.0) * grad1d_params.dx);
    }

    grad_1d[i] = deriv;
}

// ═══════════════════════════════════════════════════════════════════
// 2D Gradient (both components)
// ═══════════════════════════════════════════════════════════════════

struct Grad2DParams {
    nx: u32,        // Grid size in x
    ny: u32,        // Grid size in y
    _pad0: u32,
    _pad1: u32,
    dx: f64,        // Grid spacing in x
    dy: f64,        // Grid spacing in y
}

@group(0) @binding(0) var<uniform> grad2d_params: Grad2DParams;
@group(0) @binding(1) var<storage, read> input_2d: array<f64>;     // [nx × ny] row-major
@group(0) @binding(2) var<storage, read_write> grad_x: array<f64>; // ∂f/∂x
@group(0) @binding(3) var<storage, read_write> grad_y: array<f64>; // ∂f/∂y

@compute @workgroup_size(16, 16, 1)
fn gradient_2d(@builtin(global_invocation_id) gid: vec3<u32>) {
    let ix = gid.x;
    let iy = gid.y;
    let nx = grad2d_params.nx;
    let ny = grad2d_params.ny;

    if (ix >= nx || iy >= ny) { return; }

    let idx = ix * ny + iy;  // Row-major indexing

    // ∂f/∂x
    var df_dx: f64;
    if (ix == 0u) {
        df_dx = (input_2d[1u * ny + iy] - input_2d[idx]) / grad2d_params.dx;
    } else if (ix == nx - 1u) {
        df_dx = (input_2d[idx] - input_2d[(ix - 1u) * ny + iy]) / grad2d_params.dx;
    } else {
        df_dx = (input_2d[(ix + 1u) * ny + iy] - input_2d[(ix - 1u) * ny + iy])
                / (f64(2.0) * grad2d_params.dx);
    }

    // ∂f/∂y
    var df_dy: f64;
    if (iy == 0u) {
        df_dy = (input_2d[ix * ny + 1u] - input_2d[idx]) / grad2d_params.dy;
    } else if (iy == ny - 1u) {
        df_dy = (input_2d[idx] - input_2d[ix * ny + iy - 1u]) / grad2d_params.dy;
    } else {
        df_dy = (input_2d[ix * ny + iy + 1u] - input_2d[ix * ny + iy - 1u])
                / (f64(2.0) * grad2d_params.dy);
    }

    grad_x[idx] = df_dx;
    grad_y[idx] = df_dy;
}

// ═══════════════════════════════════════════════════════════════════
// 2D Gradient Magnitude: |∇f| = sqrt((∂f/∂x)² + (∂f/∂y)²)
// ═══════════════════════════════════════════════════════════════════

@group(0) @binding(4) var<storage, read_write> grad_mag: array<f64>;

@compute @workgroup_size(16, 16, 1)
fn gradient_magnitude_2d(@builtin(global_invocation_id) gid: vec3<u32>) {
    let ix = gid.x;
    let iy = gid.y;
    let nx = grad2d_params.nx;
    let ny = grad2d_params.ny;

    if (ix >= nx || iy >= ny) { return; }

    let idx = ix * ny + iy;
    let gx = grad_x[idx];
    let gy = grad_y[idx];
    grad_mag[idx] = sqrt(gx * gx + gy * gy);
}

// ═══════════════════════════════════════════════════════════════════
// 2D Laplacian: ∇²f = ∂²f/∂x² + ∂²f/∂y²
// ═══════════════════════════════════════════════════════════════════

@group(0) @binding(5) var<storage, read_write> laplacian: array<f64>;

@compute @workgroup_size(16, 16, 1)
fn laplacian_2d(@builtin(global_invocation_id) gid: vec3<u32>) {
    let ix = gid.x;
    let iy = gid.y;
    let nx = grad2d_params.nx;
    let ny = grad2d_params.ny;

    if (ix >= nx || iy >= ny) { return; }

    let idx = ix * ny + iy;
    let f_c = input_2d[idx];  // center

    // ∂²f/∂x² = (f[i+1] - 2f[i] + f[i-1]) / dx²
    var d2f_dx2: f64;
    if (ix == 0u || ix == nx - 1u) {
        d2f_dx2 = f64(0.0);  // Zero at boundaries (Dirichlet-like)
    } else {
        let f_xp = input_2d[(ix + 1u) * ny + iy];
        let f_xm = input_2d[(ix - 1u) * ny + iy];
        d2f_dx2 = (f_xp - f64(2.0) * f_c + f_xm) / (grad2d_params.dx * grad2d_params.dx);
    }

    // ∂²f/∂y²
    var d2f_dy2: f64;
    if (iy == 0u || iy == ny - 1u) {
        d2f_dy2 = f64(0.0);
    } else {
        let f_yp = input_2d[ix * ny + iy + 1u];
        let f_ym = input_2d[ix * ny + iy - 1u];
        d2f_dy2 = (f_yp - f64(2.0) * f_c + f_ym) / (grad2d_params.dy * grad2d_params.dy);
    }

    laplacian[idx] = d2f_dx2 + d2f_dy2;
}

// ═══════════════════════════════════════════════════════════════════
// Cylindrical (ρ, z) Gradient — for axially symmetric problems
//
// Grid: [n_rho × n_z], ρ starts at d_rho (not 0), row-major
//   index(i_rho, i_z) = i_rho * n_z + i_z
// ═══════════════════════════════════════════════════════════════════

struct CylParams {
    n_rho: u32,
    n_z: u32,
    _pad0: u32,
    _pad1: u32,
    d_rho: f64,
    d_z: f64,
    z_min: f64,     // z grid starts at z_min + 0.5*d_z
}

@group(0) @binding(0) var<uniform> cyl_params: CylParams;
@group(0) @binding(1) var<storage, read> cyl_input: array<f64>;
@group(0) @binding(2) var<storage, read_write> grad_rho: array<f64>;  // ∂f/∂ρ
@group(0) @binding(3) var<storage, read_write> grad_z_out: array<f64>;   // ∂f/∂z

@compute @workgroup_size(256)
fn gradient_cylindrical(@builtin(global_invocation_id) gid: vec3<u32>) {
    let idx = gid.x;
    let n_grid = cyl_params.n_rho * cyl_params.n_z;
    if (idx >= n_grid) { return; }

    let i_rho = idx / cyl_params.n_z;
    let i_z = idx % cyl_params.n_z;

    // ∂f/∂ρ
    var df_drho: f64;
    if (i_rho == 0u) {
        df_drho = (cyl_input[1u * cyl_params.n_z + i_z] - cyl_input[idx]) / cyl_params.d_rho;
    } else if (i_rho == cyl_params.n_rho - 1u) {
        df_drho = (cyl_input[idx] - cyl_input[(i_rho - 1u) * cyl_params.n_z + i_z]) / cyl_params.d_rho;
    } else {
        df_drho = (cyl_input[(i_rho + 1u) * cyl_params.n_z + i_z]
                 - cyl_input[(i_rho - 1u) * cyl_params.n_z + i_z])
                 / (f64(2.0) * cyl_params.d_rho);
    }

    // ∂f/∂z
    var df_dz: f64;
    if (i_z == 0u) {
        df_dz = (cyl_input[i_rho * cyl_params.n_z + 1u] - cyl_input[idx]) / cyl_params.d_z;
    } else if (i_z == cyl_params.n_z - 1u) {
        df_dz = (cyl_input[idx] - cyl_input[i_rho * cyl_params.n_z + i_z - 1u]) / cyl_params.d_z;
    } else {
        df_dz = (cyl_input[i_rho * cyl_params.n_z + i_z + 1u]
               - cyl_input[i_rho * cyl_params.n_z + i_z - 1u])
               / (f64(2.0) * cyl_params.d_z);
    }

    grad_rho[idx] = df_drho;
    grad_z_out[idx] = df_dz;
}

// ═══════════════════════════════════════════════════════════════════
// Cylindrical Laplacian: ∇²f = ∂²f/∂ρ² + (1/ρ)∂f/∂ρ + ∂²f/∂z²
// ═══════════════════════════════════════════════════════════════════

@group(0) @binding(4) var<storage, read_write> cyl_laplacian: array<f64>;

@compute @workgroup_size(256)
fn laplacian_cylindrical(@builtin(global_invocation_id) gid: vec3<u32>) {
    let idx = gid.x;
    let n_grid = cyl_params.n_rho * cyl_params.n_z;
    if (idx >= n_grid) { return; }

    let i_rho = idx / cyl_params.n_z;
    let i_z = idx % cyl_params.n_z;
    let rho = f64(i_rho + 1u) * cyl_params.d_rho;  // ρ starts at d_rho
    let f_c = cyl_input[idx];

    // ∂²f/∂ρ² + (1/ρ)∂f/∂ρ
    var lap_rho: f64;
    if (i_rho == 0u || i_rho == cyl_params.n_rho - 1u) {
        lap_rho = f64(0.0);
    } else {
        let f_rp = cyl_input[(i_rho + 1u) * cyl_params.n_z + i_z];
        let f_rm = cyl_input[(i_rho - 1u) * cyl_params.n_z + i_z];
        let d2f_drho2 = (f_rp - f64(2.0) * f_c + f_rm) / (cyl_params.d_rho * cyl_params.d_rho);
        let df_drho = (f_rp - f_rm) / (f64(2.0) * cyl_params.d_rho);
        lap_rho = d2f_drho2 + df_drho / rho;
    }

    // ∂²f/∂z²
    var d2f_dz2: f64;
    if (i_z == 0u || i_z == cyl_params.n_z - 1u) {
        d2f_dz2 = f64(0.0);
    } else {
        let f_zp = cyl_input[i_rho * cyl_params.n_z + i_z + 1u];
        let f_zm = cyl_input[i_rho * cyl_params.n_z + i_z - 1u];
        d2f_dz2 = (f_zp - f64(2.0) * f_c + f_zm) / (cyl_params.d_z * cyl_params.d_z);
    }

    cyl_laplacian[idx] = lap_rho + d2f_dz2;
}