scirs2_optimize/kaczmarz/
types.rs

1//! Types for Kaczmarz and sketched projection methods
2//!
3//! Provides configuration structs and result types for Kaczmarz iterations,
4//! sketch-based solvers, and sparse sketching transforms.
5
6/// Variant of the Kaczmarz algorithm (extended set).
7#[non_exhaustive]
8#[derive(Debug, Clone, PartialEq)]
9pub enum KaczmarzVariantExt {
10    /// Classical cyclic Kaczmarz: iterate rows in order 0, 1, ..., m-1, 0, ...
11    Classical,
12    /// Randomized Kaczmarz (Strohmer-Vershynin): sample row i with probability
13    /// proportional to ||a_i||^2 / ||A||_F^2.
14    Randomized,
15    /// Block Kaczmarz: project onto `block_size` rows simultaneously by solving
16    /// a small least-squares sub-problem.
17    Block,
18    /// Greedy Kaczmarz: select the row with the largest absolute residual
19    /// |b_i - a_i^T x|.
20    Greedy,
21    /// Randomized Extended Kaczmarz (REK): alternates a column-space projection
22    /// (to handle inconsistency) with a standard row projection. Converges to
23    /// the least-squares solution even for inconsistent systems.
24    REK,
25}
26
27impl Default for KaczmarzVariantExt {
28    fn default() -> Self {
29        Self::Randomized
30    }
31}
32
33/// Configuration for the extended Kaczmarz solver.
34#[derive(Debug, Clone)]
35pub struct KaczmarzConfigExt {
36    /// Maximum number of row-update iterations.
37    pub max_iter: usize,
38    /// Convergence tolerance on residual norm ||Ax - b||.
39    pub tol: f64,
40    /// Algorithm variant.
41    pub variant: KaczmarzVariantExt,
42    /// Block size for the Block variant (ignored for other variants).
43    pub block_size: usize,
44    /// Random seed for reproducibility.
45    pub seed: u64,
46    /// Relaxation parameter omega in (0, 2). omega = 1.0 gives standard update.
47    pub relaxation: f64,
48}
49
50impl Default for KaczmarzConfigExt {
51    fn default() -> Self {
52        Self {
53            max_iter: 10_000,
54            tol: 1e-6,
55            variant: KaczmarzVariantExt::Randomized,
56            block_size: 32,
57            seed: 42,
58            relaxation: 1.0,
59        }
60    }
61}
62
63/// Type of sketch matrix.
64#[non_exhaustive]
65#[derive(Debug, Clone, PartialEq)]
66pub enum SketchTypeExt {
67    /// Dense Gaussian sketch: S_{ij} ~ N(0, 1/sqrt(s)).
68    Gaussian,
69    /// Subsampled Randomized Hadamard Transform: S = sqrt(n/s) R H D.
70    SRHT,
71    /// Count sketch: each column mapped to one row with random sign.
72    CountSketch,
73    /// OSNAP (Oblivious Subspace Embedding): block-diagonal sparse sketch.
74    OSNAP,
75    /// Sparse Johnson-Lindenstrauss transform.
76    SparseJL,
77}
78
79impl Default for SketchTypeExt {
80    fn default() -> Self {
81        Self::Gaussian
82    }
83}
84
85/// Configuration for sketch-based solvers.
86#[derive(Debug, Clone)]
87pub struct SketchConfig {
88    /// Type of sketch matrix to generate.
89    pub sketch_type: SketchTypeExt,
90    /// Number of rows in the sketch (sketch dimension s).
91    pub sketch_size: usize,
92    /// Random seed for reproducibility.
93    pub seed: u64,
94    /// Maximum iterations for iterative sketching.
95    pub max_iter: usize,
96    /// Convergence tolerance for iterative methods.
97    pub tol: f64,
98    /// Sparsity parameter for SparseJL (entries per column). If 0, uses O(log n).
99    pub sparse_jl_sparsity: usize,
100    /// Block count for OSNAP. If 0, chosen automatically.
101    pub osnap_blocks: usize,
102}
103
104impl Default for SketchConfig {
105    fn default() -> Self {
106        Self {
107            sketch_type: SketchTypeExt::Gaussian,
108            sketch_size: 128,
109            seed: 42,
110            max_iter: 100,
111            tol: 1e-6,
112            sparse_jl_sparsity: 0,
113            osnap_blocks: 0,
114        }
115    }
116}
117
118/// Result of a projection-based or sketch-based solver.
119#[derive(Debug, Clone)]
120pub struct ProjectionResult {
121    /// Approximate solution vector.
122    pub solution: Vec<f64>,
123    /// Euclidean norm of the final residual ||Ax - b||.
124    pub residual_norm: f64,
125    /// Number of iterations performed.
126    pub iterations: usize,
127    /// Whether the algorithm converged within the tolerance.
128    pub converged: bool,
129}
scirs2_optimize/kaczmarz/types.rs

scirs2_optimize/kaczmarz/
types.rs
