kryst 4.1.0

Krylov subspace and preconditioned iterative solvers for dense and sparse linear systems, with shared and distributed memory parallelism.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

#[derive(Clone, Copy, Debug)]
pub(crate) enum ComparisonConfidence {
    Exact,
    Approximate,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct IterationRange {
    pub(crate) min: usize,
    pub(crate) max: usize,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct MatrixExpectation {
    pub(crate) matrix: &'static str,
    pub(crate) solver_families: &'static [&'static str],
    pub(crate) preconditioner_families: &'static [&'static str],
    pub(crate) iteration_range: IterationRange,
    pub(crate) time_note: Option<&'static str>,
    pub(crate) confidence: ComparisonConfidence,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct BenchmarkDelta {
    pub(crate) method_family_match: bool,
    pub(crate) iteration_delta_low: isize,
    pub(crate) iteration_delta_high: isize,
    pub(crate) tolerance_pass: bool,
}

const CATALOG: &[MatrixExpectation] = &[
    // Catalog expectations intentionally track canonical CSR ILU-family methods
    // (ILUK/ILUT via `pc_type=ilu`, plus ILUTP). The row-filter `pc_type=ilut`
    // implementation (`src/preconditioner/ilut.rs`) is experimental and excluded
    // from default comparable benchmark rows.
    MatrixExpectation {
        matrix: "fidap005",
        solver_families: &["cg"],
        preconditioner_families: &["amg"],
        iteration_range: IterationRange { min: 70, max: 140 },
        time_note: Some("prefer AMG setup reuse when running repeated solves"),
        confidence: ComparisonConfidence::Approximate,
    },
    MatrixExpectation {
        matrix: "e05r0100",
        solver_families: &["gmres"],
        preconditioner_families: &["none"],
        iteration_range: IterationRange { min: 180, max: 320 },
        time_note: Some("no-preconditioner baseline is usually fastest on this case"),
        confidence: ComparisonConfidence::Approximate,
    },
    MatrixExpectation {
        matrix: "fidap001",
        solver_families: &["gmres"],
        preconditioner_families: &["ilu", "ilutp"],
        iteration_range: IterationRange { min: 350, max: 700 },
        time_note: None,
        confidence: ComparisonConfidence::Approximate,
    },
    MatrixExpectation {
        matrix: "sherman3",
        solver_families: &["gmres", "fgmres"],
        preconditioner_families: &["ilu", "ilutp"],
        iteration_range: IterationRange { min: 20, max: 80 },
        time_note: Some("ILU-family preconditioners should dominate wall time tradeoffs"),
        confidence: ComparisonConfidence::Approximate,
    },
    MatrixExpectation {
        matrix: "add20",
        solver_families: &["cg", "bicgstab", "gmres"],
        preconditioner_families: &["ilu", "ilutp"],
        iteration_range: IterationRange { min: 2, max: 10 },
        time_note: None,
        confidence: ComparisonConfidence::Exact,
    },
    MatrixExpectation {
        matrix: "memplus",
        solver_families: &["bicgstab", "gmres"],
        preconditioner_families: &["ilu", "ilutp"],
        iteration_range: IterationRange { min: 3, max: 12 },
        time_note: Some("without ILU-family preconditioning this matrix may stall badly"),
        confidence: ComparisonConfidence::Approximate,
    },
];

pub(crate) fn expectation_for(matrix_name: &str) -> Option<&'static MatrixExpectation> {
    CATALOG.iter().find(|entry| entry.matrix == matrix_name)
}

pub(crate) fn compare_best_iterative(
    matrix_name: &str,
    solver: &str,
    preconditioner: &str,
    iterations: usize,
    accepted: bool,
) -> Option<BenchmarkDelta> {
    let expectation = expectation_for(matrix_name)?;
    let method_family_match = family_match(solver, expectation.solver_families)
        && family_match(preconditioner, expectation.preconditioner_families);

    let iteration_delta_low = iterations as isize - expectation.iteration_range.min as isize;
    let iteration_delta_high = iterations as isize - expectation.iteration_range.max as isize;
    let within_range = iterations >= expectation.iteration_range.min
        && iterations <= expectation.iteration_range.max;
    let tolerance_pass = match expectation.confidence {
        ComparisonConfidence::Exact => accepted && method_family_match && within_range,
        ComparisonConfidence::Approximate => {
            accepted
                && method_family_match
                && (within_range || approx_margin_hit(iterations, expectation.iteration_range))
        }
    };

    Some(BenchmarkDelta {
        method_family_match,
        iteration_delta_low,
        iteration_delta_high,
        tolerance_pass,
    })
}

fn normalize_family(value: &str) -> String {
    value
        .chars()
        .filter(|c| c.is_ascii_alphanumeric())
        .collect::<String>()
        .to_ascii_lowercase()
}

fn family_match(actual: &str, expected_families: &[&str]) -> bool {
    let actual_norm = normalize_family(actual);
    expected_families.iter().any(|family| {
        let family_norm = normalize_family(family);
        actual_norm.contains(&family_norm) || family_norm.contains(&actual_norm)
    })
}

fn approx_margin_hit(iterations: usize, range: IterationRange) -> bool {
    let width = range.max.saturating_sub(range.min).max(1);
    let margin = ((width as f64) * 0.25).ceil() as usize;
    let low = range.min.saturating_sub(margin);
    let high = range.max.saturating_add(margin);
    iterations >= low && iterations <= high
}