nuts_rs/transform/

low_rank.rs

//! Augment the diagonal transformation with a low-rank spectral correction for correlated posteriors.

use std::fmt::Debug;
use std::iter::repeat_n;

use faer::{Col, ColRef, Mat, MatRef};
use nuts_derive::Storable;
use serde::{Deserialize, Serialize};

use crate::transform::{DiagMassMatrix, Transformation};
use crate::{Math, sampler_stats::SamplerStats};

pub fn mat_all_finite(mat: &MatRef<f64>) -> bool {
    let mut ok = true;
    faer::zip!(mat).for_each(|faer::unzip!(val)| ok &= val.is_finite());
    ok
}

fn col_all_finite(mat: &ColRef<f64>) -> bool {
    let mut ok = true;
    faer::zip!(mat).for_each(|faer::unzip!(val)| ok &= val.is_finite());
    ok
}

/// The low-rank correction to the affine transformation.
///
/// Stores U (eigenvectors), λ^{1/2} (used for F and J_F), λ^{-1/2} (used for F⁻¹), and
/// the precomputed low-rank contribution to log|det J_{F⁻¹}|.
struct InnerMatrix<M: Math> {
    vecs: M::EigVectors,
    /// λ^{1/2} — used for the forward map F and its Jacobian J_F
    vals_sqrt: M::EigValues,
    /// λ^{-1/2} — used for the inverse position transform F⁻¹
    vals_sqrt_inv: M::EigValues,
    /// -½ Σ log(λᵢ) — low-rank contribution to log|det J_{F⁻¹}|, precomputed
    /// so we never need to pull eigenvalues back from a device (e.g. GPU).
    logdet_contribution: f64,
    mu: M::Vector,
    num_eigenvalues: u64,
}

impl<M: Math> Debug for InnerMatrix<M> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("InnerMatrix")
            .field("vecs", &"<eig vectors>")
            .field("vals_sqrt", &"<sqrt eig values>")
            .field("vals_sqrt_inv", &"<inv sqrt eig values>")
            .field("logdet_contribution", &self.logdet_contribution)
            .field("num_eigenvalues", &self.num_eigenvalues)
            .field("mu", &self.mu)
            .finish()
    }
}

impl<M: Math> InnerMatrix<M> {
    fn new(math: &mut M, mut vals: Col<f64>, vecs: Mat<f64>, mu: Col<f64>) -> Self {
        // Precompute -½ Σ log(λᵢ) while vals still holds the raw eigenvalues.
        let logdet_contribution: f64 = vals.iter().map(|&v| -0.5 * v.ln()).sum();
        let num_eigenvalues = vals.nrows() as u64;

        let vecs = math.new_eig_vectors(
            vecs.col_iter()
                .map(|col| col.try_as_col_major().unwrap().as_slice()),
        );

        // λ^{1/2} — needed for the forward map F and its Jacobian J_F
        vals.iter_mut().for_each(|x| *x = x.sqrt());
        let vals_sqrt = math.new_eig_values(vals.try_as_col_major().unwrap().as_slice());

        // λ^{-1/2} — needed for the inverse position transform F⁻¹
        vals.iter_mut().for_each(|x| *x = x.recip());
        let vals_sqrt_inv = math.new_eig_values(vals.try_as_col_major().unwrap().as_slice());

        let mu = {
            let mut array = math.new_array();
            math.read_from_slice(&mut array, mu.try_as_col_major().unwrap().as_slice());
            array
        };

        Self {
            vecs,
            vals_sqrt,
            vals_sqrt_inv,
            logdet_contribution,
            mu,
            num_eigenvalues,
        }
    }

    fn logdet(&self) -> f64 {
        self.logdet_contribution
    }
}

/// Low-rank + diagonal affine transformation.
///
/// The full forward map (adapted → target) is
///
///   F(y) = σ ⊙ (I + U (diag(λ)^{1/2} − I) Uᵀ) y + μ
///
/// so the inverse (target → adapted) is
///
///   F⁻¹(x) = (I + U (diag(λ)^{-1/2} − I) Uᵀ) ((x − μ) ⊙ σ⁻¹)
///
/// The Jacobian of F is  J_F = diag(σ) (I + U (diag(λ)^{1/2} − I) Uᵀ),
/// so  log|det J_{F⁻¹}| = Σ log(σᵢ⁻¹) − ½ Σ log(λᵢ).
///
/// In the adapted space the mass matrix is the identity; leapfrog steps
/// operate entirely in that space.  When no eigenvectors are available
/// (early adaptation) the transform falls back to the pure diagonal case.
pub struct LowRankMassMatrix<M: Math> {
    diag: DiagMassMatrix<M>,
    inner: Option<InnerMatrix<M>>,
    settings: LowRankSettings,
    logdet: f64,
    /// Monotonically increasing id; bumped whenever the matrix changes.
    id: i64,
}

impl<M: Math> Debug for LowRankMassMatrix<M> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LowRankMassMatrix")
            .field("diag", &self.diag)
            .field("inner", &self.inner)
            .field("settings", &self.settings)
            .field("id", &self.id)
            .finish()
    }
}

impl<M: Math> LowRankMassMatrix<M> {
    pub fn new(math: &mut M, settings: LowRankSettings) -> Self {
        Self {
            diag: DiagMassMatrix::new(math, settings.store_mass_matrix),
            settings,
            logdet: 0f64,
            inner: None,
            id: -1,
        }
    }

    /// Initialise from the gradient at the first draw only (no mean / covariance information yet).
    pub fn update_from_grad(
        &mut self,
        math: &mut M,
        pos: &M::Vector,
        grad: &M::Vector,
        fill_invalid: f64,
        clamp: (f64, f64),
    ) {
        self.inner = None;
        self.diag
            .update_diag_grad(math, pos, grad, fill_invalid, clamp);
        self.logdet = self.diag.logdet();
        self.id += 1;
    }

    /// Full update from a window of draws and scores.
    ///
    /// * `stds`  — diagonal scales σ
    /// * `mean`  — optimal translation μ* = x̄ + σ² ⊙ ᾱ (in target space)
    /// * `vals`  — filtered eigenvalues λ of the SPD geometric mean
    /// * `vecs`  — corresponding eigenvectors U (columns, back-projected to ℝᵈ)
    pub fn update(
        &mut self,
        math: &mut M,
        stds: Col<f64>,
        mean: Col<f64>,
        vals: Col<f64>,
        vecs: Mat<f64>,
        mean_low_rank: Col<f64>,
    ) {
        if (!col_all_finite(&stds.as_ref())) | (!col_all_finite(&mean.as_ref())) {
            return;
        }
        if (!col_all_finite(&vals.as_ref())) | (!mat_all_finite(&vecs.as_ref())) {
            return;
        }

        let mut stds_array = math.new_array();
        math.read_from_slice(&mut stds_array, stds.try_as_col_major().unwrap().as_slice());
        let mut mean_array = math.new_array();
        math.read_from_slice(&mut mean_array, mean.try_as_col_major().unwrap().as_slice());
        self.diag.set_transform(math, &stds_array, &mean_array);

        let inner = InnerMatrix::new(math, vals, vecs, mean_low_rank);
        self.logdet = inner.logdet() + self.diag.logdet();
        self.inner = Some(inner);
        self.id += 1;
    }
}

#[derive(Clone, Debug, Copy, Serialize, Deserialize)]
pub struct LowRankSettings {
    pub store_mass_matrix: bool,
    pub gamma: f64,
    pub eigval_cutoff: f64,
}

impl Default for LowRankSettings {
    fn default() -> Self {
        Self {
            store_mass_matrix: false,
            gamma: 1e-5,
            eigval_cutoff: 2f64,
        }
    }
}

#[derive(Debug, Storable)]
pub struct MatrixStats {
    /// The transformation version counter at the time of this update.
    /// `Some` only on draws where the transformation changed.
    #[storable(event = "transformation_update")]
    pub transformation_update_id: Option<i64>,
    #[storable(event = "transformation_update", dims("unconstrained_parameter"))]
    pub mass_matrix_eigvals: Option<Vec<f64>>,
    #[storable(event = "transformation_update", dims("unconstrained_parameter"))]
    pub mass_matrix_stds: Option<Vec<f64>>,
    #[storable(event = "transformation_update")]
    pub num_eigenvalues: Option<u64>,
}

impl<M: Math> SamplerStats<M> for LowRankMassMatrix<M> {
    type Stats = MatrixStats;
    type StatsOptions = i64;

    fn extract_stats(&self, math: &mut M, last_id: Self::StatsOptions) -> Self::Stats {
        if self.id != last_id {
            let num_eigenvalues = Some(
                self.inner
                    .as_ref()
                    .map(|inner| inner.num_eigenvalues)
                    .unwrap_or(0),
            );
            if self.settings.store_mass_matrix {
                let stds = Some(math.box_array(self.diag.stds()));
                let eigvals = self
                    .inner
                    .as_ref()
                    .map(|inner| math.eigs_as_array(&inner.vals_sqrt));
                let mut eigvals = eigvals.map(|x| x.into_vec());
                if let Some(ref mut eigvals) = eigvals {
                    eigvals.extend(repeat_n(
                        f64::NAN,
                        stds.as_ref().unwrap().len() - eigvals.len(),
                    ));
                }
                MatrixStats {
                    transformation_update_id: Some(self.id),
                    mass_matrix_eigvals: eigvals,
                    mass_matrix_stds: stds.map(|x| x.into_vec()),
                    num_eigenvalues,
                }
            } else {
                MatrixStats {
                    transformation_update_id: Some(self.id),
                    mass_matrix_eigvals: None,
                    mass_matrix_stds: None,
                    num_eigenvalues,
                }
            }
        } else {
            MatrixStats {
                transformation_update_id: None,
                mass_matrix_eigvals: None,
                mass_matrix_stds: None,
                num_eigenvalues: None,
            }
        }
    }
}

impl<M: Math> Transformation<M> for LowRankMassMatrix<M> {
    fn init_from_untransformed_position(
        &self,
        math: &mut M,
        untransformed_position: &M::Vector,
        untransformed_gradient: &mut M::Vector,
        transformed_position: &mut M::Vector,
        transformed_gradient: &mut M::Vector,
    ) -> Result<(f64, f64), M::LogpErr> {
        let logp = math.logp_array(untransformed_position, untransformed_gradient)?;
        self.compute_transformed_position(math, untransformed_position, transformed_position);
        self.compute_transformed_gradient(math, untransformed_gradient, transformed_gradient);
        Ok((logp, self.logdet(math)))
    }

    fn init_from_transformed_position(
        &self,
        math: &mut M,
        untransformed_position: &mut M::Vector,
        untransformed_gradient: &mut M::Vector,
        transformed_position: &M::Vector,
        transformed_gradient: &mut M::Vector,
    ) -> Result<(f64, f64), M::LogpErr> {
        self.compute_untransformed_position(math, transformed_position, untransformed_position);
        let logp = math.logp_array(untransformed_position, untransformed_gradient)?;
        self.compute_transformed_gradient(math, untransformed_gradient, transformed_gradient);
        Ok((logp, self.logdet(math)))
    }

    fn inv_transform_normalize(
        &self,
        math: &mut M,
        untransformed_position: &M::Vector,
        untransformed_gradient: &M::Vector,
        transformed_position: &mut M::Vector,
        transformed_gradient: &mut M::Vector,
    ) -> Result<f64, M::LogpErr> {
        self.compute_transformed_position(math, untransformed_position, transformed_position);
        self.compute_transformed_gradient(math, untransformed_gradient, transformed_gradient);
        Ok(self.logdet(math))
    }

    fn transformation_id(&self, _math: &mut M) -> i64 {
        self.id
    }

    fn next_stats_options(&self, _math: &mut M, _current: i64) -> i64 {
        self.id
    }
}

impl<M: Math> LowRankMassMatrix<M> {
    fn compute_transformed_position(
        &self,
        math: &mut M,
        untransformed_position: &M::Vector,
        transformed_position: &mut M::Vector,
    ) {
        math.axpy_out(
            &self.diag.mean(),
            &untransformed_position,
            -1.0,
            transformed_position,
        );
        math.array_mult_inplace(transformed_position, self.diag.inv_stds());

        if let Some(inner) = &self.inner {
            math.axpy(&inner.mu, transformed_position, -1.0);
            math.apply_lowrank_transform_inplace(
                &inner.vecs,
                &inner.vals_sqrt_inv,
                transformed_position,
            );
        }
    }

    fn compute_untransformed_position(
        &self,
        math: &mut M,
        transformed_position: &M::Vector,
        untransformed_position: &mut M::Vector,
    ) {
        match &self.inner {
            None => {
                math.array_mult(
                    transformed_position,
                    &self.diag.stds(),
                    untransformed_position,
                );
            }
            Some(inner) => {
                math.apply_lowrank_transform(
                    &inner.vecs,
                    &inner.vals_sqrt,
                    transformed_position,
                    untransformed_position,
                );

                math.axpy(&inner.mu, untransformed_position, 1.0);
                math.array_mult_inplace(untransformed_position, &self.diag.stds());
            }
        }
        math.axpy(&self.diag.mean(), untransformed_position, 1.0);
    }

    fn compute_transformed_gradient(
        &self,
        math: &mut M,
        untransformed_gradient: &M::Vector,
        transformed_gradient: &mut M::Vector,
    ) {
        math.array_mult(
            untransformed_gradient,
            self.diag.stds(),
            transformed_gradient,
        );

        if let Some(inner) = &self.inner {
            math.apply_lowrank_transform_inplace(
                &inner.vecs,
                &inner.vals_sqrt,
                transformed_gradient,
            );
        }
    }

    /// log|det J_{F⁻¹}| = Σ log(σᵢ⁻¹) − ½ Σ log(λᵢ)
    fn logdet(&self, _math: &mut M) -> f64 {
        self.logdet
    }
}

#[cfg(test)]
mod tests {
    use faer::{Col, Mat};

    use crate::Math;
    use crate::math::CpuMath;
    use crate::math::test_logps::NormalLogp;

    use super::{LowRankMassMatrix, LowRankSettings};

    fn make_math(dim: usize) -> CpuMath<NormalLogp> {
        CpuMath::new(NormalLogp::new(dim, 0.0))
    }

    fn assert_close(a: &[f64], b: &[f64], tol: f64) {
        assert_eq!(a.len(), b.len());
        for (i, (ai, bi)) in a.iter().zip(b.iter()).enumerate() {
            assert!(
                (ai - bi).abs() <= tol,
                "index {i}: {ai} vs {bi} (tol {tol})"
            );
        }
    }

    fn read_vec(math: &mut CpuMath<NormalLogp>, v: &Col<f64>) -> Vec<f64> {
        let mut out = vec![0f64; math.dim()];
        math.write_to_slice(v, &mut out);
        out
    }

    /// diagonal-only: compute_transformed_position ∘ compute_untransformed_position = id
    #[test]
    fn test_diagonal_round_trip() {
        let mut math = make_math(3);
        let stds = Col::from_fn(3, |i| [1.0f64, 2.0, 3.0][i]);
        let mean = Col::from_fn(3, |i| [0.5f64, -1.0, 2.0][i]);
        let vals = Col::zeros(0);
        let vecs = Mat::zeros(3, 0);
        let mu = Col::zeros(3);
        let mut mass = LowRankMassMatrix::new(&mut math, LowRankSettings::default());
        mass.update(&mut math, stds, mean, vals, vecs, mu);

        let x_orig = [1.5f64, -0.3, 4.2];
        let mut untransformed = math.new_array();
        let mut transformed = math.new_array();
        let mut recovered = math.new_array();
        math.read_from_slice(&mut untransformed, &x_orig);

        mass.compute_transformed_position(&mut math, &untransformed, &mut transformed);
        mass.compute_untransformed_position(&mut math, &transformed, &mut recovered);

        assert_close(&read_vec(&mut math, &recovered), &x_orig, 1e-12);
    }

    /// diagonal-only: compute_untransformed_position ∘ compute_transformed_position = id
    #[test]
    fn test_diagonal_round_trip_reverse() {
        let mut math = make_math(3);
        let stds = Col::from_fn(3, |i| [1.0f64, 2.0, 3.0][i]);
        let mean = Col::from_fn(3, |i| [0.5f64, -1.0, 2.0][i]);
        let vals = Col::zeros(0);
        let vecs = Mat::zeros(3, 0);
        let mu = Col::zeros(3);
        let mut mass = LowRankMassMatrix::new(&mut math, LowRankSettings::default());
        mass.update(&mut math, stds, mean, vals, vecs, mu);

        let z_orig = [0.7f64, -1.1, 0.3];
        let mut transformed = math.new_array();
        let mut untransformed = math.new_array();
        let mut recovered = math.new_array();
        math.read_from_slice(&mut transformed, &z_orig);

        mass.compute_untransformed_position(&mut math, &transformed, &mut untransformed);
        mass.compute_transformed_position(&mut math, &untransformed, &mut recovered);

        assert_close(&read_vec(&mut math, &recovered), &z_orig, 1e-12);
    }

    /// low-rank: compute_transformed_position ∘ compute_untransformed_position = id
    #[test]
    fn test_lowrank_round_trip() {
        let mut math = make_math(3);
        // rank-1 correction along e_1 with eigenvalue 4
        let stds = Col::full(3, 1.0f64);
        let mean = Col::from_fn(3, |i| [1.0f64, -0.5, 0.0][i]);
        let vals = faer::col![4.0f64];
        let mut vecs = Mat::zeros(3, 1);
        vecs[(0, 0)] = 1.0;
        let mu = Col::from_fn(3, |i| [0.2f64, -0.1, 0.0][i]);
        let mut mass = LowRankMassMatrix::new(&mut math, LowRankSettings::default());
        mass.update(&mut math, stds, mean, vals, vecs, mu);

        let x_orig = [2.0f64, 0.5, -1.3];
        let mut untransformed = math.new_array();
        let mut transformed = math.new_array();
        let mut recovered = math.new_array();
        math.read_from_slice(&mut untransformed, &x_orig);

        mass.compute_transformed_position(&mut math, &untransformed, &mut transformed);
        mass.compute_untransformed_position(&mut math, &transformed, &mut recovered);

        assert_close(&read_vec(&mut math, &recovered), &x_orig, 1e-12);
    }

    /// low-rank: compute_untransformed_position ∘ compute_transformed_position = id
    #[test]
    fn test_lowrank_round_trip_reverse() {
        let mut math = make_math(3);
        let stds = Col::full(3, 1.0f64);
        let mean = Col::from_fn(3, |i| [1.0f64, -0.5, 0.0][i]);
        let vals = faer::col![4.0f64];
        let mut vecs = Mat::zeros(3, 1);
        vecs[(0, 0)] = 1.0;
        let mu = Col::from_fn(3, |i| [0.2f64, -0.1, 0.0][i]);
        let mut mass = LowRankMassMatrix::new(&mut math, LowRankSettings::default());
        mass.update(&mut math, stds, mean, vals, vecs, mu);

        let z_orig = [1.0f64, -0.3, 0.8];
        let mut transformed = math.new_array();
        let mut untransformed = math.new_array();
        let mut recovered = math.new_array();
        math.read_from_slice(&mut transformed, &z_orig);

        mass.compute_untransformed_position(&mut math, &transformed, &mut untransformed);
        mass.compute_transformed_position(&mut math, &untransformed, &mut recovered);

        assert_close(&read_vec(&mut math, &recovered), &z_orig, 1e-12);
    }
}