Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Fixed-rank randomized factorization

Use tensor4all_core::randomized_svd when a dense local tensor needs only a small number of singular triplets. randomized_range returns an orthonormal basis Q instead, so a caller can explicitly insert the bond projector Q Q†. Both support f64 and Complex64 and consume a caller-owned RNG directly. f32 and Complex32 (c32) are unsupported, including through Fit and Zipup; they return FactorizeError::UnsupportedStorage rather than converting types.

The example below is also a runnable TreeTN example and a checked doctest. It reconstructs an exactly rank-one matrix and verifies a known MPO product.

use rand::SeedableRng;
use rand_chacha::ChaCha8Rng;
use tensor4all_core::{
    randomized_svd, DynIndex, FactorizeAlg, IdxTensor, RsvdOptions, TensorContractionLike,
};
use tensor4all_treetn::{
    contraction::{contract_with_rng, ContractionOptions},
    TreeTN,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut rng = ChaCha8Rng::seed_from_u64(1108);
    let i = DynIndex::new_dyn(2);
    let j = DynIndex::new_dyn(2);
    let matrix = IdxTensor::from_dense(vec![i.clone(), j], vec![3., 0., 0., 0.])?;
    let result = randomized_svd(&matrix, &[i], &RsvdOptions::new(1), &mut rng)?;
    let reconstructed = result
        .u
        .contract_pair(&result.s)?
        .contract_pair(&result.vh)?;
    assert!(matrix.sub(&reconstructed)?.maxabs()? < 1e-12);

    let shared: Vec<_> = (0..2).map(|_| DynIndex::new_dyn(2)).collect();
    let make = || -> Result<TreeTN<IdxTensor, usize>, Box<dyn std::error::Error>> {
        let bond = DynIndex::new_dyn(1);
        let tensors = shared
            .iter()
            .map(|site| {
                IdxTensor::from_dense(
                    vec![site.clone(), DynIndex::new_dyn(2), bond.clone()],
                    vec![1.; 4],
                )
            })
            .collect::<Result<Vec<_>, _>>()?;
        Ok(TreeTN::from_tensors(tensors, vec![0, 1])?)
    };
    let (a, b) = (make()?, make()?);
    for options in [
        ContractionOptions::zipup(),
        ContractionOptions::fit().with_nfullsweeps(2),
    ] {
        let options = options
            .with_factorize_alg(FactorizeAlg::RSVD)
            .with_max_bond_dim(1);
        let result = contract_with_rng(&a, &b, &0, options, &mut rng)?;
        // Each shared two-dimensional site contributes 2, hence 2 * 2 = 4.
        assert!(result
            .to_dense()?
            .to_vec::<f64>()?
            .iter()
            .all(|&value| (value - 4.).abs() < 1e-11));
    }
    Ok(())
}

RsvdOptions::new(rank) requests min(rank, rows, columns) triplets. Its range field controls oversampling (default 8) and stabilized power iterations (default 1). More power iterations cost extra GEMMs and QR factorizations. The range finder returns min(rank + oversampling, rows, columns) columns; set oversampling to zero when the projector must have exactly rank columns. Index splits compare the complete index, including prime levels and tags.

FactorizeOptions::rsvd(rank) selects the same algorithm through factorize. Choose Canonical::Left or Canonical::Right as usual. The seeded convenience call uses rsvd_seed (default zero); factorize_with_rng consumes a supplied stream instead. Fit and Zipup select RSVD with FactorizeAlg::RSVD and a positive max_bond_dim. Their randomized and rsvd_seed options configure the convenience calls. contract_with_rng advances one supplied stream across initialization, all sites and every sweep.

RSVD ignores global QR/SVD truncation defaults. An explicit rtol or cutoff policy returns FactorizeError::UnsupportedTruncationPolicy, with no automatic fallback. Specify a fixed rank or select deterministic SVD for threshold policies. Singular values of the projected matrix omit the range-finding error and therefore do not certify the full approximation error.

Caller-owned execution contexts use randomized_range_in, factorize_with_rng_in, and contract_with_rng_in. Plain held sessions use randomized_range_on_session or factorize_with_rng_on_session; tracked or resident inputs are refused there. TreeTN context RSVD also refuses tracked inputs because its current execution leaves publish plain factors. The implicit CPU path preserves AD through the backend’s supported operations, with a finite-difference regression for partial-rank RSVD.

The current Fit remains site-canonical. Environment projection requires the future inverse-canonical parallel Fit and is not performed automatically. RSVD still materializes the local two-site tensor; it does not implement a matrix-free contraction.