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

//! GPU population PK Monte Carlo simulation.
//!
//! Each thread simulates one virtual patient with per-patient clearance
//! variation via Wang hash + xorshift32 PRNG.
//!
//! Absorbed from healthSpring V44 (March 2026).

use crate::device::WgpuDevice;
use crate::device::capabilities::WORKGROUP_SIZE_1D;
use crate::error::Result;
use bytemuck::{Pod, Zeroable};
use std::sync::Arc;

const PRNG: &str = include_str!("../../shaders/health/prng_wang_f64.wgsl");
const SHADER_BODY: &str = include_str!("../../shaders/health/population_pk_f64.wgsl");

#[repr(C)]
#[derive(Copy, Clone, Pod, Zeroable)]
struct PopPkParams {
    n_patients: u32,
    base_seed: u32,
    dose_mg: f64,
    f_bioavail: f64,
}

/// Population PK simulation configuration.
#[derive(Debug, Clone, Copy)]
pub struct PopPkConfig {
    /// Number of virtual patients.
    pub n_patients: u32,
    /// PRNG base seed.
    pub seed: u32,
    /// Dose in milligrams.
    pub dose_mg: f64,
    /// Bioavailability fraction (0..1).
    pub f_bioavail: f64,
}

/// GPU-accelerated population PK Monte Carlo.
pub struct PopulationPkGpu {
    device: Arc<WgpuDevice>,
}

impl PopulationPkGpu {
    /// Create a new `PopulationPkGpu` for the given device.
    #[must_use]
    pub const fn new(device: Arc<WgpuDevice>) -> Self {
        Self { device }
    }

    /// Run population PK simulation, returning per-patient AUC values.
    ///
    /// # Errors
    /// Returns [`Err`] on pipeline creation, dispatch, or readback failure.
    pub fn simulate(&self, config: &PopPkConfig) -> Result<Vec<f64>> {
        let params = PopPkParams {
            n_patients: config.n_patients,
            base_seed: config.seed,
            dose_mg: config.dose_mg,
            f_bioavail: config.f_bioavail,
        };

        let n = config.n_patients as usize;
        let out_buf = self.device.create_buffer_f64(n)?;
        let params_buf = self.device.create_uniform_buffer("pop_pk:params", &params);

        let wg_count = config.n_patients.div_ceil(WORKGROUP_SIZE_1D);
        let shader = format!("{PRNG}\n{SHADER_BODY}");

        crate::device::compute_pipeline::ComputeDispatch::new(&self.device, "population_pk")
            .shader(&shader, "main")
            .f64()
            .storage_rw(0, &out_buf)
            .uniform(1, &params_buf)
            .dispatch(wg_count, 1, 1)
            .submit()?;

        self.device.read_f64_buffer(&out_buf, n)
    }
}

/// CPU reference: single-compartment AUC = F * Dose / CL.
///
/// Uses the same Wang hash + xorshift32 PRNG as the GPU for parity.
#[must_use]
pub fn population_pk_cpu(config: &PopPkConfig) -> Vec<f64> {
    let mut results = Vec::with_capacity(config.n_patients as usize);
    for idx in 0..config.n_patients {
        let mut state = wang_hash(config.seed.wrapping_add(idx));
        if state == 0 {
            state = 1;
        }
        let bits = xorshift32(state);
        let u = bits as f64 / 4_294_967_295.0;
        let cl_factor = 0.5 + u;
        let cl = 10.0 * cl_factor;
        let auc = config.f_bioavail * config.dose_mg / cl;
        results.push(auc);
    }
    results
}

#[must_use]
const fn wang_hash(input: u32) -> u32 {
    let mut x = input;
    x = (x ^ 0x3D) ^ (x >> 16);
    x = x.wrapping_mul(9);
    x = x ^ (x >> 4);
    x = x.wrapping_mul(0x27d4_eb2d);
    x = x ^ (x >> 15);
    x
}

#[must_use]
const fn xorshift32(state: u32) -> u32 {
    let mut x = state;
    x ^= x << 13;
    x ^= x >> 17;
    x ^= x << 5;
    x
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn params_layout() {
        assert_eq!(std::mem::size_of::<PopPkParams>(), 24);
    }

    #[test]
    fn shader_source_valid() {
        let combined = format!("{PRNG}\n{SHADER_BODY}");
        assert!(combined.contains("wang_hash"));
        assert!(combined.contains("xorshift32"));
        assert!(combined.contains("u32_to_uniform_f64"));
        assert!(combined.contains("Params"));
    }

    #[test]
    fn cpu_reference_produces_positive_auc() {
        let config = PopPkConfig {
            n_patients: 100,
            seed: 42,
            dose_mg: 500.0,
            f_bioavail: 0.8,
        };
        let results = population_pk_cpu(&config);
        assert_eq!(results.len(), 100);
        assert!(results.iter().all(|&v| v > 0.0 && v.is_finite()));
    }

    #[test]
    fn cpu_reference_deterministic() {
        let config = PopPkConfig {
            n_patients: 10,
            seed: 42,
            dose_mg: 300.0,
            f_bioavail: 1.0,
        };
        let a = population_pk_cpu(&config);
        let b = population_pk_cpu(&config);
        assert_eq!(a, b, "same seed should produce same results");
    }

    #[test]
    fn wang_hash_distributes() {
        let h0 = wang_hash(0);
        let h1 = wang_hash(1);
        let h2 = wang_hash(2);
        assert_ne!(h0, h1);
        assert_ne!(h1, h2);
        assert_ne!(h0, h2);
    }

    #[test]
    fn cpu_auc_range() {
        let config = PopPkConfig {
            n_patients: 500,
            seed: 99,
            dose_mg: 200.0,
            f_bioavail: 0.9,
        };
        let results = population_pk_cpu(&config);
        let auc_min = 0.9 * 200.0 / (10.0 * 1.5);
        let auc_max = 0.9 * 200.0 / (10.0 * 0.5);
        for (i, &auc) in results.iter().enumerate() {
            assert!(
                auc >= auc_min && auc <= auc_max,
                "patient {i}: AUC {auc} outside [{auc_min}, {auc_max}]"
            );
        }
    }

    #[test]
    fn cpu_seed_variation() {
        let config_a = PopPkConfig {
            n_patients: 10,
            seed: 1,
            dose_mg: 300.0,
            f_bioavail: 1.0,
        };
        let config_b = PopPkConfig {
            seed: 2,
            ..config_a
        };
        let a = population_pk_cpu(&config_a);
        let b = population_pk_cpu(&config_b);
        assert_ne!(a, b, "different seeds must produce different results");
    }

    #[test]
    fn prng_preamble_concatenation() {
        let combined = format!("{PRNG}\n{SHADER_BODY}");
        assert!(
            combined.contains("wang_hash"),
            "PRNG preamble should provide wang_hash"
        );
        assert!(
            combined.contains("u32_to_uniform_f64"),
            "PRNG preamble should provide u32_to_uniform_f64"
        );
        let body_only = SHADER_BODY;
        assert!(
            !body_only.contains("fn wang_hash"),
            "consumer body should not duplicate PRNG functions"
        );
    }

    #[tokio::test]
    async fn gpu_vs_cpu_parity() {
        let Some(device) = crate::device::test_pool::get_test_device_if_f64_gpu_available().await
        else {
            return;
        };
        let config = PopPkConfig {
            n_patients: 256,
            seed: 42,
            dose_mg: 500.0,
            f_bioavail: 0.8,
        };
        let gpu = PopulationPkGpu::new(device);
        let gpu_results = gpu.simulate(&config).unwrap();

        let any_nonzero = gpu_results.iter().any(|&v| v != 0.0);
        if !any_nonzero {
            tracing::warn!(
                "PopPK GPU test: all outputs zero — driver may not support PRNG \
                 preamble concatenation path; skipping parity check"
            );
            return;
        }

        let cpu_results = population_pk_cpu(&config);
        let tol = crate::tolerances::PHARMA_POP_PK;
        for (i, (&g, &c)) in gpu_results.iter().zip(&cpu_results).enumerate() {
            assert!(
                crate::tolerances::check(g, c, &tol),
                "GPU/CPU mismatch at patient {i}: gpu={g}, cpu={c}"
            );
        }
    }
}