Skip to content

Commit 339f03f

Browse files
ikorotkinikorotkin
committed
Write sparse-matrix page
1 parent 307cebf commit 339f03f

File tree

2 files changed

+182
-7
lines changed

2 files changed

+182
-7
lines changed

‎docs/quick-start.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ Below is a simplified procedure of defining and solving the given DAE system usi
5353

5454
### Step 1. Define the mass matrix of the system
5555

56-
Tha mass matrix contains only one non-zero element:
56+
The mass matrix contains only one non-zero element:
5757

5858
$$
5959
\mathbf{M} =

‎docs/sparse-matrix.md‎

Lines changed: 181 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,188 @@ layout: default
44
nav_order: 2
55
---
66

7-
Work in progress
8-
{: .label .label-red }
9-
107
# Sparse Matrix class
118

12-
Text
9+
Sparse Matrix class `daecpp::sparse_matrix` defines sparse matrix holder in [three-array format](#three-array-format).
10+
It is used to define the mass matrix and, optionally, the Jacobian matrix of the DAE system.
11+
The class provides a set of helper tools for the user to allocate memory, define and convert sparse matrices in a very straightforward way, e.g.:
12+
13+
```cpp
14+
sparse_matrix M; // Creates empty sparse matrix M
15+
M.reserve(2); // Reserves memory for 2 elements (optional)
16+
M.add_element(0, 1, 12.0); // Fills row 0, column 1 with value 12.0
17+
M.add_element(1, 1, 42.0); // Fills row 1, column 1 with value 42.0
18+
std::cout << M.dense(3) << '\n'; // Prints matrix on screen assuming it's a 3x3 matrix
19+
```
20+
21+
## Three-array format
22+
23+
The three-array format defines a sparse matrix using two (unsigned) integer vectors of indices `i` and `j` and one floating point vector `A` of the corresponding non-zero elements of the matrix. Only non-zero elements of the sparse matrix should be defined. Theoretically, all three arrays can be empty. This will define a zero matrix where all elements are zeros.
24+
25+
{: .note }
26+
All three arrays `i`, `j`, and `A` should be the same size. This can be (and will be) checked by calling the `void check()` method of the class `daecpp::sparse_matrix`.
27+
28+
Here is an example of a sparse matrix:
29+
30+
$$
31+
\mathbf{M} =
32+
\begin{vmatrix}
33+
1 & 0 & 3 \\
34+
0 & 2 & 0 \\
35+
0 & 0 & 0
36+
\end{vmatrix}.
37+
$$
38+
39+
This matrix contains only 3 non-zero elements: `1`, `2`, and `3`.
40+
Here is the matrix definition in three-array format:
41+
42+
| `i` (row index) | `j` (column index) | `A` (non-zero element) |
43+
| --------------- | ------------------ | ---------------------- |
44+
| 0 | 0 | 1.0 |
45+
| 1 | 1 | 2.0 |
46+
| 0 | 2 | 3.0 |
47+
48+
The indices `i` and `j` define the position of the corresponding non-zero element `A` in the matrix. Index `i` is the row index and index `j` is the column index.
49+
50+
It doesn't matter in which order you define each element of the matrix.
51+
52+
{: .note }
53+
The row and column numeration starts from `0`.
54+
55+
## Sparse Matrix class public data
56+
57+
| Variable | Type | Description |
58+
| -------- | ---- | ----------- |
59+
| `A` | `std` vector of `double` (default) or `float` | Vector of non-zero elements `A` |
60+
| `i` | `std` vector of `uint32_t` (default) or `uint64_t` | Vector of row indices `i` |
61+
| `j` | `std` vector of `uint32_t` (default) or `uint64_t` | Vector of column indices `j` |
62+
63+
{: .note }
64+
All three vectors are initially empty an NOT preallocated
65+
66+
## Sparse Matrix class methods
67+
68+
----
69+
70+
## `void operator()(ind_i, ind_j, A_ij)`
71+
72+
<br>
73+
Adds next non-zero element to the sparse matrix.
74+
Duplicated elements will be summed up.
75+
76+
### Parameters:
77+
78+
- `ind_i` - row index of the element (`int_type`)
79+
- `ind_j` - column index of the element (`int_type`)
80+
- `A_ij`- non-zero element (`float_type`)
81+
82+
### Example:
83+
84+
```cpp
85+
sparse_matrix M; // Creates empty sparse matrix M
86+
M(0, 1, 42.0); // Fills row 0, column 1 with value 42.0
87+
M(1, 2, 10.0); // Defines next non-zero element: row 1, column 2, value 10.0
88+
M(0, 1, 2.0); // Duplicated element is OK, it will be summed up, i.e., the value will be 44.0
89+
```
90+
91+
----
92+
93+
## `void add_element(ind_i, ind_j, A_ij)`
94+
95+
<br>
96+
An alias to the operator `()` defined above.
97+
Adds next non-zero element to the sparse matrix.
98+
Duplicated elements will be summed up.
99+
100+
### Parameters:
101+
102+
- `ind_i` - row index of the element (`int_type`)
103+
- `ind_j` - column index of the element (`int_type`)
104+
- `A_ij`- non-zero element (`float_type`)
105+
106+
### Example:
107+
108+
```cpp
109+
sparse_matrix M; // Creates empty sparse matrix M
110+
M.add_element(0, 1, 42.0); // Fills row 0, column 1 with value 42.0
111+
M.add_element(1, 2, 10.0); // Defines next non-zero element: row 1, column 2, value 10.0
112+
M.add_element(0, 1, 2.0); // Duplicated element will be summed up, i.e., the value will be 44.0
113+
```
114+
115+
----
116+
117+
## `void reserve(N_elements)`
118+
119+
<br>
120+
Reserves memory for `N_elements` non-zero elements. It is strongly advised to allocate memory before filling in the sparse matrix arrays to avoid multiple copying and reallocation.
121+
122+
### Parameter:
123+
124+
- `N_elements` - estimated number of non-zero elements (`int_type`)
125+
126+
### Example:
127+
128+
```cpp
129+
sparse_matrix M; // Creates empty sparse matrix M
130+
M.reserve(16); // Pre-allocates memory for 16 non-zero elements
131+
```
132+
133+
----
134+
135+
## `void clear()`
136+
137+
<br>
138+
Clears the sparse matrix arrays and frees the memory. Invalidates iterators and pointers. The matrix becomes a *zero* matrix.
139+
140+
----
141+
142+
## `void check() const`
143+
144+
<br>
145+
Performs a few basic checks of the matrix structure. Particularly, checks that the size of vectors `i`, `j`, and `A` is the same.
146+
If it fails, the solver exits with error message (it is not possible to recover).
147+
148+
----
149+
150+
## `auto dense(N) const`
151+
152+
<br>
153+
Represents matrix in dense format. Suitable for printing using `std::cout`.
154+
155+
### Parameter:
156+
157+
- `N` - matrix size (square matrix `N` x `N`) (`int_type`)
158+
159+
### Returns:
160+
161+
- Dense matrix representation in `Eigen` format.
162+
163+
### Example:
164+
165+
```cpp
166+
sparse_matrix M; // Creates empty sparse matrix M
167+
M(0, 1, 42.0); // Fills row 0, column 1 with value 42.0
168+
std::cout << M.dense(3) << '\n'; // Prints matrix on screen assuming it's a 3x3 matrix
169+
```
170+
171+
----
172+
173+
## `Eigen::SparseMatrix<float_type> convert(N) const`
174+
175+
<br>
176+
Converts matrix from `dae-cpp` three-array format to `Eigen::SparseMatrix` format.
177+
178+
### Parameter:
179+
180+
- `N` - matrix size (square matrix `N` x `N`) (`int_type`)
181+
182+
### Returns:
183+
184+
- `Eigen::SparseMatrix<float_type>` (`core::eimat`) sparse matrix.
185+
186+
----
13187
14-
## Subtitle
188+
## `std::size_t N_elements() const`
15189
16-
Text
190+
<br>
191+
Returns the number of non-zero elements in the matrix.

0 commit comments

Comments
 (0)