trigivs 0.2.3

Rust library for solving tridiagonal systems of linear equations using Givens rotations
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

# Trigivs


A Rust library for solving **tridiagonal systems of linear equations** using **Givens rotations**. This library is designed to work in both `std` and `no_std` environments, with optional heap allocation.

---

## Features


The library supports three modes of operation, controlled by Cargo features:

| Feature | Description                                                                 |
|---------|-----------------------------------------------------------------------------|
| `std`   | Default mode. Uses standard heap allocation (`Vec<T>`).                   |
| `alloc` | Works in `no_std` environments but requires an allocator for heap usage.   |
| None    | Fully `no_std` mode. No heap allocation; uses fixed-size arrays only.     |

---

## Usage


Add `trigivs` to your `Cargo.toml`:

```toml
[dependencies]
trigivs = "0.2"
```

To use the library in `no_std` mode (no heap allocation):

```toml
[dependencies]
trigivs = { version = "0.2", default-features = false }
```

To use the library with heap allocation but without `std`:

```toml
[dependencies]
trigivs = { version = "0.2", default-features = false, features = ["alloc"] }
```

---

## Examples


```rust
use trigivs::prelude::*;

fn main() {
    // Define a 3x3 tridiagonal system
    let sub = [2.0, 1.0];          // subdiagonal (length n-1)
    let diag = [3.0, 4.0, 5.0];    // main diagonal (length n)
    let sup = [1.0, 2.0];          // superdiagonal (length n-1)
    
    // 1. Compute determinant
    let det = compute_tridiag_determinant(&sup, &diag, &sub);
    println!("Determinant: {}", det);

    // 2. Solve directly
    let rhs = [1.0, 2.0, 3.0];
    let solution = solve_givens(&sup, &diag, &sub, &rhs).unwrap();
    let solution_ruiz = solve_givens_ruiz_precond(&sup, &diag, &sub, &rhs, 3, 0.01);
    println!("Direct solution: {:?}", solution);
    
    // 3. Precompute for multiple RHS
    let precomputed = precompute_givens(&sup, &diag, &sub).unwrap();
    let rhs2 = [4.0, 5.0, 6.0];
    let solution2 = precomputed.solve_givens_rhs(&rhs2).unwrap();
    println!("Solution with precomputed: {:?}", solution2);
    
    // 4. Refine solution iteratively
    // NOTE: Meant for large ill-defined systems or as rare fallback
    let refined = tridiag_iter_kaczmarz(
        &sub, &diag, &sup, &rhs, &solution, 50, 1e-10
    ).unwrap();
    println!("Refined solution: {:?}", refined);
}
```

### Error Handling


`SolverErrors`:
* `InvalidDiagonals` - The superdiagonal and subdiagonal must be equal in length and exactly one element shorter than the main diagonal.
* `InvalidRhsSizing` - The right-hand side (RHS) must match the length of the main diagonal.
* `DivisionByZero`   - Division by zero was attempted during computation. 

---

## License


This project is licensed under the MIT License.