rivrs-sparse 0.1.1

Sparse linear algebra solvers
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

# Examples

rivrs-sparse implements a multifrontal LDL^T solver for sparse symmetric
indefinite systems using A Posteriori Threshold Pivoting (APTP). The solver
exposes a three-phase API:

1. **Analyze** — symbolic factorization (reusable for matrices with the same sparsity pattern)
2. **Factor** — numeric LDL^T factorization with APTP pivoting
3. **Solve** — forward/diagonal/backward substitution

## User Examples

Self-contained examples that require no external data or feature flags.

### basic_usage

Constructs a small symmetric indefinite matrix from triplets, solves `Ax = b`
for a known solution, and validates the result with backward error analysis.
Demonstrates the core `SparseLDLT` API.

```sh
cargo run --example basic_usage
```

### multiple_rhs

Factors a matrix once and solves for multiple right-hand sides, reusing both the
factorization and the solve workspace. Demonstrates the workspace allocation
pattern with `solve_scratch` and `MemBuffer`.

```sh
cargo run --example multiple_rhs
```

### refactorization

Builds a parametric matrix `A(t)` with fixed sparsity and values that depend on
a parameter `t`. Analyzes once, then loops over several `t` values calling
`factor()` each time. Demonstrates symbolic reuse across refactorizations — the
inner-loop pattern for interior-point methods and time-stepping.

```sh
cargo run --example refactorization
```

## Diagnostic Tools

These examples require SuiteSparse test matrices and/or the `diagnostic` feature
flag. They are intended for performance analysis and regression tracking.

### solve_timing

Solves all CI-subset SuiteSparse matrices and reports factorization/solve timing,
backward error, and pivot statistics. Good for a quick end-to-end validation.

Requires the CI test matrices in `test-data/suitesparse-ci/` (checked into git).

```sh
cargo run --example solve_timing --release
```

### profile_matrix

Deep profiling tool for a single matrix. Reports per-phase timing, factorization
statistics, and per-supernode breakdowns. Optionally exports
[Chrome Trace](https://ui.perfetto.dev) JSON for visual analysis.

Requires `--features diagnostic` for per-supernode timing instrumentation.

```sh
# Profile by registry name
cargo run --example profile_matrix --features diagnostic --release -- d_pretok

# Profile by file path
cargo run --example profile_matrix --features diagnostic --release -- --path matrix.mtx

# Export Chrome Trace
cargo run --example profile_matrix --features diagnostic --release -- d_pretok --trace /tmp/trace.json

# List available matrices
cargo run --example profile_matrix --features diagnostic --release -- --list
```

### baseline_collection

Collects structured performance baselines (JSON) across the SuiteSparse test
suite for regression tracking. Records per-phase timing, per-supernode
statistics, peak RSS, and backward error. Supports comparison against a
previously saved baseline to detect regressions.

Requires `--features diagnostic` for per-supernode timing fields.

```sh
# Collect baselines for CI subset
cargo run --example baseline_collection --features diagnostic --release -- --ci-only

# Collect for all available matrices
cargo run --example baseline_collection --features diagnostic --release

# Compare against a previous baseline
cargo run --example baseline_collection --features diagnostic --release -- --compare target/benchmarks/baselines/prev.json
```

JSON output is written to `target/benchmarks/baselines/`.

### parallel_scaling

Measures factorization and solve performance across multiple thread counts.
Produces a structured report showing speedup and efficiency per matrix.

```sh
# Default thread counts (1, 2, 4) on CI subset
cargo run --example parallel_scaling --release -- --ci-only

# Custom thread counts
cargo run --example parallel_scaling --release -- --ci-only --threads 1,2,4,8

# All available matrices
cargo run --example parallel_scaling --release
```

JSON output is written to `target/benchmarks/parallel/`.

## Feature Flags

| Flag | Purpose | Used by |
|------|---------|---------|
| `diagnostic` | Per-supernode timing instrumentation (zero overhead when disabled) | `profile_matrix`, `baseline_collection` |

The `test-util` feature (random matrix generators, benchmarking utilities) is
automatically enabled for examples via the dev-dependency in `Cargo.toml`.

## Test Data

Some diagnostic tools require SuiteSparse test matrices:

| Tier | Path | Size | Git status |
|------|------|------|------------|
| CI subset | `test-data/suitesparse-ci/` | ~19 MB | Tracked |
| Full suite | `test-data/suitesparse/` | ~500 MB | Gitignored |

User examples (`basic_usage`, `multiple_rhs`, `refactorization`) require no
external data.