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

//! Hill Gate — Two-input Hill AND gate (f64 pipeline).
//!
//! Computes f(a, b) = vmax × H(a, `K_a`, `n_a`) × H(b, `K_b`, `n_b`) where
//! H(x, K, n) = x^n / (K^n + x^n) is the Hill function. Used for regulatory
//! network signal integration.
//!
//! Provenance: neuralSpring metalForge → toadStool absorption

use std::sync::Arc;

use wgpu::util::DeviceExt;

use crate::device::WgpuDevice;
use crate::device::capabilities::WORKGROUP_SIZE_1D;

/// WGSL source for f32 Hill gate (paired or grid mode).
pub const WGSL_HILL_GATE: &str = include_str!("../../shaders/bio/hill_gate.wgsl");

/// f64 version for universal math library portability.
pub const WGSL_HILL_GATE_F64: &str = include_str!("../../shaders/bio/hill_gate_f64.wgsl");

/// Parameters for Hill gate GPU kernel.
#[repr(C)]
#[derive(Copy, Clone, bytemuck::Pod, bytemuck::Zeroable)]
pub struct HillGateParams {
    /// Size of input A (or rows in grid mode)
    pub n_a: u32,
    /// Size of input B (or cols in grid mode)
    pub n_b: u32,
    /// 0 = paired (output[i] = f(a[i], b[i])), 1 = grid
    pub mode: u32,
    /// Padding for alignment
    pub _pad: u32,
    /// Hill coefficient `K_a` for input A
    pub k_a: f64,
    /// Hill coefficient `K_b` for input B
    pub k_b: f64,
    /// Precomputed `n_a^exponent`
    pub n_a_exp: f64,
    /// Precomputed `n_b^exponent`
    pub n_b_exp: f64,
    /// Maximum output value
    pub vmax: f64,
    /// Padding for alignment
    pub _pad2: f64,
}

/// Hill gate GPU kernel (f64 pipeline).
pub struct HillGateGpu {
    pipeline: wgpu::ComputePipeline,
    bgl: wgpu::BindGroupLayout,
    device: Arc<WgpuDevice>,
}

impl HillGateGpu {
    /// Create new Hill gate GPU kernel.
    #[must_use]
    pub fn new(device: Arc<WgpuDevice>) -> Self {
        let d = device.device();

        let bgl = d.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            label: Some("HillGate BGL"),
            entries: &[
                wgpu::BindGroupLayoutEntry {
                    binding: 0,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: true },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 1,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: true },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 2,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Storage { read_only: false },
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
                wgpu::BindGroupLayoutEntry {
                    binding: 3,
                    visibility: wgpu::ShaderStages::COMPUTE,
                    ty: wgpu::BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
            ],
        });

        let layout = d.create_pipeline_layout(&wgpu::PipelineLayoutDescriptor {
            label: Some("HillGate Layout"),
            bind_group_layouts: &[&bgl],
            immediate_size: 0,
        });

        let module = device.compile_shader_f64(WGSL_HILL_GATE_F64, Some("HillGate f64"));

        let pipeline = d.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
            label: Some("HillGate Pipeline"),
            layout: Some(&layout),
            module: &module,
            entry_point: Some("main"),
            compilation_options: Default::default(),
            cache: None,
        });

        Self {
            pipeline,
            bgl,
            device,
        }
    }

    /// Compute Hill gate. Mode 0: paired (output[i] = f(a[i], b[i])).
    /// Mode 1: grid (output[ix*`n_b` + iy] = f(a[ix], b[iy])).
    pub fn dispatch(
        &self,
        input_a: &wgpu::Buffer,
        input_b: &wgpu::Buffer,
        output: &wgpu::Buffer,
        params: &HillGateParams,
    ) {
        let d = self.device.device();
        let q = self.device.queue();

        let params_buf = d.create_buffer_init(&wgpu::util::BufferInitDescriptor {
            label: Some("HillGate Params"),
            contents: bytemuck::bytes_of(params),
            usage: wgpu::BufferUsages::UNIFORM,
        });

        let workgroups = if params.mode == 0 {
            params.n_a.div_ceil(WORKGROUP_SIZE_1D)
        } else {
            (params.n_a * params.n_b).div_ceil(WORKGROUP_SIZE_1D)
        };

        let bg = d.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("HillGate BG"),
            layout: &self.bgl,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: input_a.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: input_b.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: output.as_entire_binding(),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: params_buf.as_entire_binding(),
                },
            ],
        });

        let mut encoder = self
            .device
            .create_encoder_guarded(&wgpu::CommandEncoderDescriptor {
                label: Some("HillGate Encoder"),
            });
        {
            let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor {
                label: Some("HillGate Pass"),
                timestamp_writes: None,
            });
            pass.set_pipeline(&self.pipeline);
            pass.set_bind_group(0, Some(&bg), &[]);
            pass.dispatch_workgroups(workgroups, 1, 1);
        }
        q.submit(std::iter::once(encoder.finish()));
    }
}

#[cfg(test)]
mod tests {
    use super::{HillGateGpu, HillGateParams, WGSL_HILL_GATE, WGSL_HILL_GATE_F64};

    #[test]
    fn sanity_constants_exported() {
        assert!(!WGSL_HILL_GATE.is_empty());
        assert!(WGSL_HILL_GATE.contains("fn main"));
        assert!(WGSL_HILL_GATE.contains("HillGateParams"));
        assert!(std::any::type_name::<HillGateGpu>().contains("HillGateGpu"));
        assert!(std::any::type_name::<HillGateParams>().contains("HillGateParams"));
    }

    #[test]
    fn f64_shader_contains_main() {
        assert!(WGSL_HILL_GATE_F64.contains("fn main"));
        assert!(WGSL_HILL_GATE_F64.contains("f64"));
    }

    #[test]
    fn f64_shader_compiles_via_naga() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available_sync()
        else {
            return;
        };
        let _ = device.compile_shader_f64(WGSL_HILL_GATE_F64, Some("hill_gate_f64"));
    }
}