nalgebra_linsys 0.1.1

A library with a type-wrapper around nalgebra::Matrix for solving linear systems
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

#[cfg(any(test, doctest))]
extern crate num_bigint;
#[cfg(any(test, doctest))]
extern crate num_rational;

pub mod err;
mod elem_row_op;
mod row_add;
mod row_mul;
mod row_xchg;

use elem_row_op::ElemRowOp;
use nalgebra::Matrix;

/// Module with types representing [elementary row operations], namely row addition, row exchange, and row multiplication
/// 
/// [elementary row operations]: https://www.math.ucdavis.edu/~linear/old/notes3.pdf
pub mod elem_row_ops {
    pub use crate::row_add::RowAdd;
    pub use crate::row_mul::RowMul;
    pub use crate::row_xchg::RowXchg;
    pub use crate::elem_row_op::ElemRowOp;
}

/// [Matrix representation of a linear system][MRLS].
///
/// # Example
///
/// ```
/// use nalgebra::{Matrix, matrix};
/// use nalgebra_linsys::{
///     MatrixReprOfLinSys as MRLS,
///     elem_row_ops::RowAdd,
/// };
///
/// // x₁ + 2x₂ = 3
/// // 4x₁ + 5x₂ = 6
/// let mut m = MRLS::new(matrix![
///    1, 2, 3;
///    4, 5, 6;
/// ]);
///
/// m.perform_elem_row_op(RowAdd {
///     // The zero-based index of the row to which the scaled second row is added, i.e.
///     // the zero-based index of the "inout row";
///     inout_row_zbi: 1,
///     // The zero-based index of the row whose scaled value is added to the "inout row",
///     // i.e. the zero-based index of the "in row";
///     in_row_zbi: 0,
///     // The factor by which the "in row" is scaled before summation.
///     factor: &-4
/// }).unwrap();
///
/// // x₁ + 2x₂ = 3
/// // -3x₂ = -6
/// assert_eq!(
///   m.0,
///  matrix![
///   1, 2, 3;
///   0, -3, -6;
/// ]);
/// ```
///
/// [MRLS]: http://linear.ups.edu/html/definitions.html
pub struct MatrixReprOfLinSys<T, R, C, S>(pub Matrix<T, R, C, S>);

impl<T, R, C, S> MatrixReprOfLinSys<T, R, C, S> {
    /// Creates a new [matrix representation of a linear system][MRLS] from the given matrix.
    ///
    /// # Example
    ///
    /// ```
    /// use nalgebra::matrix;
    /// use nalgebra_linsys::{MatrixReprOfLinSys as MRLS};
    ///
    /// // x₁ + 2x₂ = 3
    /// // 4x₁ + 5x₂ = 6
    /// let mut a = MRLS::new(matrix![
    ///    1, 2, 3;
    ///    4, 5, 6;
    /// ]);
    /// ```
    ///  
    /// [MRLS]: http://linear.ups.edu/html/definitions.html
    pub fn new(matrix: Matrix<T, R, C, S>) -> Self {
        MatrixReprOfLinSys(matrix)
    }

    /// Turns the given [matrix representation of a linear system][MRLS] into
    /// an object of [nalgebra::Matrix] type.
    ///
    /// # Example
    ///
    /// ```
    /// use nalgebra::matrix;
    /// use nalgebra_linsys::{MatrixReprOfLinSys as MRLS};
    ///
    /// // x₁ + 2x₂ = 3
    /// // 4x₁ + 5x₂ = 6
    /// let mut a = MRLS::new(matrix![
    ///   1, 2, 3;
    ///   4, 5, 6;
    /// ]);
    ///
    /// assert_eq!(
    ///  a.0,
    ///  matrix![
    ///    1, 2, 3;
    ///    4, 5, 6;
    /// ]);
    ///
    /// assert_eq!(
    ///   a.to_matrix(),
    ///   matrix![
    ///     1, 2, 3;
    ///     4, 5, 6;
    /// ]);
    /// ```
    ///
    /// # Notes
    ///
    /// As opposed to `m.0`, a call of this method can, depending on the context,
    /// better convey that the returned (owned) value is a matrix.
    ///
    /// [MRLS]: http://linear.ups.edu/html/definitions.html
    pub fn to_matrix(self) -> Matrix<T, R, C, S> {
        self.0
    }
}

impl<T, R, C, S> MatrixReprOfLinSys<T, R, C, S> {
    /// Performs the given [elementary row operation] on the matrix representation of the linear system.
    /// 
    /// For examples, refer to the documentation of [`RowXchg`][crate::elem_row_ops::RowXchg],
    /// [`RowAdd`][crate::elem_row_ops::RowAdd], and/or [`RowMul`][crate::elem_row_ops::RowMul].
    /// 
    /// [elementary row operation]: https://www.math.ucdavis.edu/~linear/old/notes3.pdf
    pub fn perform_elem_row_op<O>(&mut self, o: O) -> Result<(), O::Error>
    where
        O: ElemRowOp<Self>,
    {
        o.perform(self)
    }
}