From 3130d06ad095971be9e76d574c5af8e2595a8f4c Mon Sep 17 00:00:00 2001 From: lijas Date: Wed, 15 May 2024 13:23:47 +0200 Subject: [PATCH] Suggested changes for sparse_matrix.md --- docs/src/topics/sparse_matrix.md | 44 +++++++++++++++++++------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/docs/src/topics/sparse_matrix.md b/docs/src/topics/sparse_matrix.md index 453abbc03e..0d826e50f8 100644 --- a/docs/src/topics/sparse_matrix.md +++ b/docs/src/topics/sparse_matrix.md @@ -11,15 +11,13 @@ Depth = 2:2 ## Sparsity pattern -The sparse structure, the *sparsity pattern*, depends on many factors such as e.g. the weak +The sparse structure of the linear system depends on many factors such as e.g. the weak form, the discretization, and the choice of interpolation(s). In the end it boils down to how the degrees of freedom (DoFs) *couple* with each other. The most common reason that two -DoFs couple is because they simply belong to the same element. - -Note, however, that this is not guaranteed to result in a coupling since it depends on the -specific weak form that is being discretized, see [XXX](@ref). - -Boundary conditions and constraints can also result in additional DoF couplings. +DoFs couple is because they simply belong to the same element. Note, however, that this is +not guaranteed to result in a coupling since it depends on the specific weak form that is +being discretized, see [XXX](@ref). Boundary conditions and constraints can also result in +additional DoF couplings. If DoFs `i` and `j` couple, then the computed value in the eventual matrix will be *nonzero*. In this case the entry `(i, j)` should be included in the sparsity pattern. @@ -59,7 +57,17 @@ following connections according to the weak form: - Trial function 4 couples with test functions 3 and 4 (entries `(4, 3)` and `(4, 4)` included in the sparsity pattern) -If the problem is solved with periodic boundary conditions, for example by constraining the +The resulting sparsity pattern would look like this: + +``` +4×4 SparseArrays.SparseMatrixCSC{Float64, Int64} with 10 stored entries: + 0.0 0.0 ⋅ ⋅ + 0.0 0.0 0.0 ⋅ + ⋅ 0.0 0.0 0.0 + ⋅ ⋅ 0.0 0.0 +``` + +Moreover, if the problem is solved with periodic boundary conditions, for example by constraining the value on the right side to the value on the left side, there will be additional couplings. In the example above, this means that DoF 4 should be equal to DoF 1. Since DoF 4 is constrained it has to be eliminated from the system. Existing entries that include DoF 4 are @@ -91,10 +99,18 @@ In summary, a dynamic structure is more efficient when incrementally building th inserting new entries, and a static or compressed structure is more efficient for linear algebra operations. +### Basic sparsity patterns construction in Ferrite -### Sparsity patterns construction in Ferrite +Working with the sparsity pattern explicitly is in many cases not necessary. For basic +usage (e.g. when only one matrix needed, when no customization of the pattern is +required, etc) there exist convenience methods of [`create_matrix`](@ref) that return +the matrix directly. For example, most examples in this documentation don't deal with +the sparsity pattern explicitly. + +### Costum sparsity patterns construction in Ferrite -The following steps are typically taken when constructing a sparsity pattern in Ferrite: +In more advanced cases, we need more fine grained control of the sparsity pattern. The +following steps are typically taken when constructing a sparsity pattern in Ferrite: 1. *Initialize an empty pattern.* This can be done by either using the [`init_sparsity_pattern(dh)`](@ref) function or by using a constructor directly. @@ -129,14 +145,6 @@ The following steps are typically taken when constructing a sparsity pattern in `cross_element_coupling!` and `condense_sparsity_pattern!`. Refer to the API reference for details. -!!! note "Advanced usage" - Working with the sparsity pattern explicitly is in many cases not necessary. For basic - usage (e.g. when only one matrix needed, when no customization of the pattern is - required, etc) there exist convenience methods of [`create_matrix`](@ref) that return - the matrix directly. For example, most examples in this documentation don't deal with - the sparsity pattern explicitly. - - ### Increasing the sparsity By default when creating a sparsity pattern it is assumed that a DoF couple with all other