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
//! WGSL RK4 kernel code generation for the generic ODE solver.
//!
//! Two templates: f64-typed (via `compile_shader_f64`) and universal-precision
//! (`Scalar`/`op_*` abstraction). Both generate unrolled WGSL because WGSL
//! requires constant indexing for array parameters.

/// f64-typed WGSL RK4 integration kernel.
///
/// Placeholders: `{{N_VARS}}`, `{{N_PARAMS}}`, `{{DERIVATIVE_FN}}`, `{{UNROLLED_*}}`
/// Loops are unrolled because WGSL requires constant indexing for array parameters.
pub fn wgsl_rk4_template(n_vars: usize, n_params: usize, derivative_fn: &str) -> String {
    let unroll_state2_from = |k: &str, coeff: &str| {
        (0..n_vars)
            .map(|i| format!("    state2[{i}u] = state[{i}u] + {coeff} * {k}[{i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_yn = || {
        (0..n_vars)
            .map(|i| {
                format!(
                    "    yn[{i}u] = state[{i}u] + h * sixth * (k1[{i}u] + two * k2[{i}u] + two * k3[{i}u] + k4[{i}u]);"
                )
            })
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_read_state = || {
        (0..n_vars)
            .map(|i| format!("    state[{i}u] = initial_states[s_base + {i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_read_params = || {
        (0..n_params)
            .map(|i| format!("    params[{i}u] = batch_params[p_base + {i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_clamp = || {
        (0..n_vars)
            .map(|i| format!("        state[{i}u] = fclamp(yn[{i}u], cmin, cmax);"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_write = || {
        (0..n_vars)
            .map(|i| format!("    output_states[s_base + {i}u] = state[{i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };

    format!(
        r"// Generic batched ODE RK4 — generated by BatchedOdeRK4<S>
// f64 enabled by compile_shader_f64() preamble injection

const N_VARS:   u32 = {}u;
const N_PARAMS: u32 = {}u;

struct OdeConfig {{
    n_batches:      u32,
    n_steps:        u32,
    _pad0:          u32,
    _pad1:          u32,
    h:              f64,
    t0:             f64,
    clamp_max:      f64,
    clamp_min:      f64,
}}

@group(0) @binding(0) var<uniform>             config:         OdeConfig;
@group(0) @binding(1) var<storage, read>       initial_states: array<f64>;
@group(0) @binding(2) var<storage, read>       batch_params:   array<f64>;
@group(0) @binding(3) var<storage, read_write> output_states:  array<f64>;

fn fclamp(x: f64, lo: f64, hi: f64) -> f64 {{
    if (x < lo) {{ return lo; }}
    if (x > hi) {{ return hi; }}
    return x;
}}

{}

fn rk4_step(state: array<f64, {}>, params: array<f64, {}>, t: f64, h: f64) -> array<f64, {}> {{
    let z = h - h;
    let half = z + 0.5;
    let two = z + 2.0;
    let h2 = h * half;

    let k1 = deriv(state, params, t);
    var state2: array<f64, {}>;
{}
    let k2 = deriv(state2, params, t + h2);

{}
    let k3 = deriv(state2, params, t + h2);

{}
    let k4 = deriv(state2, params, t + h);

    var yn: array<f64, {}>;
    let sixth = (z + 1.0) / (z + 6.0);
{}
    return yn;
}}

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {{
    let b = global_id.x;
    if (b >= config.n_batches) {{ return; }}

    let s_base = b * N_VARS;
    let p_base = b * N_PARAMS;

    var state: array<f64, {}>;
{}
    var params: array<f64, {}>;
{}
    let cmax = config.clamp_max;
    let cmin = config.clamp_min;
    let h = config.h;
    var t = config.t0;

    for (var step = 0u; step < config.n_steps; step = step + 1u) {{
        let yn = rk4_step(state, params, t, h);
{}
        t = t + h;
    }}

{}
}}
",
        n_vars,
        n_params,
        derivative_fn,
        n_vars,
        n_params,
        n_vars,
        n_vars,
        unroll_state2_from("k1", "h2"),
        unroll_state2_from("k2", "h2"),
        unroll_state2_from("k3", "h"),
        n_vars,
        unroll_yn(),
        n_vars,
        unroll_read_state(),
        n_params,
        unroll_read_params(),
        unroll_clamp(),
        unroll_write(),
    )
}

/// Universal precision RK4 template using `Scalar`/`op_*` abstractions.
///
/// Generates WGSL that works with any precision preamble (f32, f64, df64, f16).
/// The derivative function must use `Scalar` instead of `f64`.
/// The appropriate precision preamble is prepended at compilation time.
pub fn wgsl_rk4_template_universal(n_vars: usize, n_params: usize, derivative_fn: &str) -> String {
    let unroll_state2_from = |k: &str, coeff: &str| {
        (0..n_vars)
            .map(|i| format!("    state2[{i}u] = op_add(state[{i}u], op_mul({coeff}, {k}[{i}u]));"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_yn = || {
        (0..n_vars)
            .map(|i| {
                format!(
                    "    yn[{i}u] = op_add(state[{i}u], op_mul(h, op_mul(sixth, op_add(op_add(k1[{i}u], op_mul(two, k2[{i}u])), op_add(op_mul(two, k3[{i}u]), k4[{i}u])))));"
                )
            })
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_read_state = || {
        (0..n_vars)
            .map(|i| format!("    state[{i}u] = initial_states[s_base + {i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_read_params = || {
        (0..n_params)
            .map(|i| format!("    params[{i}u] = batch_params[p_base + {i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_clamp = || {
        (0..n_vars)
            .map(|i| format!("        state[{i}u] = op_max(cmin, op_min(cmax, yn[{i}u]));"))
            .collect::<Vec<_>>()
            .join("\n")
    };
    let unroll_write = || {
        (0..n_vars)
            .map(|i| format!("    output_states[s_base + {i}u] = state[{i}u];"))
            .collect::<Vec<_>>()
            .join("\n")
    };

    format!(
        r"// Generic batched ODE RK4 — universal precision (Scalar/op_*)
// Precision preamble injected at compile time

const N_VARS:   u32 = {n_vars}u;
const N_PARAMS: u32 = {n_params}u;

struct OdeConfig {{
    n_batches:      u32,
    n_steps:        u32,
    _pad0:          u32,
    _pad1:          u32,
    h:              Scalar,
    t0:             Scalar,
    clamp_max:      Scalar,
    clamp_min:      Scalar,
}}

@group(0) @binding(0) var<uniform>             config:         OdeConfig;
@group(0) @binding(1) var<storage, read>       initial_states: array<Scalar>;
@group(0) @binding(2) var<storage, read>       batch_params:   array<Scalar>;
@group(0) @binding(3) var<storage, read_write> output_states:  array<Scalar>;

{derivative_fn}

fn rk4_step(state: array<Scalar, {n_vars}>, params: array<Scalar, {n_params}>, t: Scalar, h: Scalar) -> array<Scalar, {n_vars}> {{
    let half = op_from_f32(0.5);
    let two  = op_from_f32(2.0);
    let h2   = op_mul(h, half);

    let k1 = deriv(state, params, t);
    var state2: array<Scalar, {n_vars}>;
{unroll_k1}
    let k2 = deriv(state2, params, op_add(t, h2));

{unroll_k2}
    let k3 = deriv(state2, params, op_add(t, h2));

{unroll_k3}
    let k4 = deriv(state2, params, op_add(t, h));

    var yn: array<Scalar, {n_vars}>;
    let sixth = op_div(op_one(), op_from_f32(6.0));
{unroll_yn}
    return yn;
}}

@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {{
    let b = global_id.x;
    if (b >= config.n_batches) {{ return; }}

    let s_base = b * N_VARS;
    let p_base = b * N_PARAMS;

    var state: array<Scalar, {n_vars}>;
{read_state}
    var params: array<Scalar, {n_params}>;
{read_params}
    let cmax = config.clamp_max;
    let cmin = config.clamp_min;
    let h = config.h;
    var t = config.t0;

    for (var step = 0u; step < config.n_steps; step = step + 1u) {{
        let yn = rk4_step(state, params, t, h);
{clamp}
        t = op_add(t, h);
    }}

{write}
}}
",
        unroll_k1 = unroll_state2_from("k1", "h2"),
        unroll_k2 = unroll_state2_from("k2", "h2"),
        unroll_k3 = unroll_state2_from("k3", "h"),
        unroll_yn = unroll_yn(),
        read_state = unroll_read_state(),
        read_params = unroll_read_params(),
        clamp = unroll_clamp(),
        write = unroll_write(),
    )
}