krylovscope 0.1.0

GPU-resident Krylov spectral endpoint estimation for large symmetric operators
Documentation
//! High-level sparse-matrix session for application integration.

use crate::{
    estimator::{
        EnsembleEstimate, Estimate, EstimatorConfig, PreparationReport, SpectralEstimator,
    },
    sparse::{
        validate_and_upload, HostSparseOperator, UploadedResidentOperator, ValidationPolicy,
        ValidationReport,
    },
};
use cubecl::prelude::Runtime;
use std::time::Instant;

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum IndexConversion {
    BorrowedU32,
    UsizeToU32,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ValueConversion {
    BorrowedF32,
    F64ToF32,
}

#[derive(Clone, Copy, Debug)]
pub enum SparseView<'a> {
    CsrF32U32 {
        row_ptr: &'a [u32],
        col_idx: &'a [u32],
        values: &'a [f32],
    },
    CsrF64Usize {
        row_ptr: &'a [usize],
        col_idx: &'a [usize],
        values: &'a [f64],
    },
    Pdsm32F32U32 {
        base_col: &'a [u32],
        bitmap: &'a [u32],
        row_value_offset: &'a [u32],
        values: &'a [f32],
    },
    Pdsm32F64Usize {
        base_col: &'a [usize],
        bitmap: &'a [u32],
        row_value_offset: &'a [usize],
        values: &'a [f64],
    },
}
#[derive(Clone, Copy, Debug, Default)]
pub struct SparseSessionConfig {
    pub estimator: EstimatorConfig,
    pub validation: ValidationPolicy,
}
#[derive(Clone, Debug)]
pub struct SparseSessionReport {
    pub kind: &'static str,
    pub n: usize,
    pub nnz: usize,
    pub index_conversion: IndexConversion,
    pub value_conversion: ValueConversion,
    pub max_value_quant_abs: f64,
    pub max_value_quant_rel: f64,
    pub setup_ms: f64,
    pub validation: ValidationReport,
}
fn u32s(x: &[usize], label: &str) -> Result<Vec<u32>, String> {
    x.iter()
        .enumerate()
        .map(|(i, &v)| {
            u32::try_from(v).map_err(|_| format!("krylovscope: {label}[{i}]={v} exceeds u32"))
        })
        .collect()
}
fn f32s(x: &[f64], label: &str) -> Result<(Vec<f32>, f64, f64), String> {
    let mut o = Vec::with_capacity(x.len());
    let (mut a, mut r) = (0.0_f64, 0.0_f64);
    for (i, &v) in x.iter().enumerate() {
        if !v.is_finite() {
            return Err(format!("krylovscope: {label}[{i}] is non-finite"));
        }
        let q = v as f32;
        if !q.is_finite() {
            return Err(format!(
                "krylovscope: {label}[{i}] not representable as finite f32"
            ));
        }
        let e = (q as f64 - v).abs();
        a = a.max(e);
        r = r.max(e / v.abs().max(1e-300));
        o.push(q);
    }
    Ok((o, a, r))
}

pub struct SparseSession<R: Runtime> {
    estimator: SpectralEstimator<R, UploadedResidentOperator<R>>,
    report: SparseSessionReport,
}
impl<R: Runtime> SparseSession<R> {
    pub fn new(
        device: &R::Device,
        view: SparseView<'_>,
        config: SparseSessionConfig,
    ) -> Result<Self, String> {
        Self::new_impl(device, view, config, None)
    }
    pub fn new_masked(
        device: &R::Device,
        view: SparseView<'_>,
        config: SparseSessionConfig,
        free_mask: Vec<u32>,
    ) -> Result<Self, String> {
        Self::new_impl(device, view, config, Some(free_mask))
    }
    fn new_impl(
        device: &R::Device,
        view: SparseView<'_>,
        config: SparseSessionConfig,
        mask: Option<Vec<u32>>,
    ) -> Result<Self, String> {
        let t = Instant::now();
        let client = R::client(device);
        let (op, validation, kind, ic, vc, qa, qr) = match view {
            SparseView::CsrF32U32 {
                row_ptr,
                col_idx,
                values,
            } => {
                let h = HostSparseOperator::CsrF32 {
                    row_ptr,
                    col_idx,
                    values,
                };
                let (o, r) = validate_and_upload(&client, h, config.validation)?;
                (
                    o,
                    r,
                    "csr-f32/u32",
                    IndexConversion::BorrowedU32,
                    ValueConversion::BorrowedF32,
                    0.0,
                    0.0,
                )
            }
            SparseView::CsrF64Usize {
                row_ptr,
                col_idx,
                values,
            } => {
                let rp = u32s(row_ptr, "csr.row_ptr")?;
                let ci = u32s(col_idx, "csr.col_idx")?;
                let (v, qa, qr) = f32s(values, "csr.values")?;
                let h = HostSparseOperator::CsrF32 {
                    row_ptr: &rp,
                    col_idx: &ci,
                    values: &v,
                };
                let (o, r) = validate_and_upload(&client, h, config.validation)?;
                (
                    o,
                    r,
                    "csr-f64/usize->f32/u32",
                    IndexConversion::UsizeToU32,
                    ValueConversion::F64ToF32,
                    qa,
                    qr,
                )
            }
            SparseView::Pdsm32F32U32 {
                base_col,
                bitmap,
                row_value_offset,
                values,
            } => {
                let h = HostSparseOperator::Pdsm32F32 {
                    base_col,
                    bitmap,
                    row_value_offset,
                    values,
                };
                let (o, r) = validate_and_upload(&client, h, config.validation)?;
                (
                    o,
                    r,
                    "pdsm32-f32/u32",
                    IndexConversion::BorrowedU32,
                    ValueConversion::BorrowedF32,
                    0.0,
                    0.0,
                )
            }
            SparseView::Pdsm32F64Usize {
                base_col,
                bitmap,
                row_value_offset,
                values,
            } => {
                let bc = u32s(base_col, "pdsm.base_col")?;
                let ro = u32s(row_value_offset, "pdsm.row_value_offset")?;
                let (v, qa, qr) = f32s(values, "pdsm.values")?;
                let h = HostSparseOperator::Pdsm32F32 {
                    base_col: &bc,
                    bitmap,
                    row_value_offset: &ro,
                    values: &v,
                };
                let (o, r) = validate_and_upload(&client, h, config.validation)?;
                (
                    o,
                    r,
                    "pdsm32-f64/usize->f32/u32",
                    IndexConversion::UsizeToU32,
                    ValueConversion::F64ToF32,
                    qa,
                    qr,
                )
            }
        };
        let n = validation.n;
        let nnz = validation.nnz;
        let estimator = match mask {
            Some(m) => SpectralEstimator::new_masked(device, op, config.estimator, m)?,
            None => SpectralEstimator::new(device, op, config.estimator)?,
        };
        let report = SparseSessionReport {
            kind,
            n,
            nnz,
            index_conversion: ic,
            value_conversion: vc,
            max_value_quant_abs: qa,
            max_value_quant_rel: qr,
            setup_ms: t.elapsed().as_secs_f64() * 1e3,
            validation,
        };
        Ok(Self { estimator, report })
    }
    pub fn prepare(&mut self, seed: u64) -> Result<PreparationReport, String> {
        self.estimator.prepare(seed)
    }
    pub fn estimate_prepared(&mut self, seed: u64) -> Result<Estimate, String> {
        self.estimator.estimate_prepared(seed)
    }
    pub fn estimate_ensemble_prepared(
        &mut self,
        seeds: &[u64],
    ) -> Result<EnsembleEstimate, String> {
        self.estimator.estimate_ensemble_prepared(seeds)
    }
    pub fn report(&self) -> &SparseSessionReport {
        &self.report
    }
    pub fn is_prepared(&self) -> bool {
        self.estimator.is_prepared()
    }
}