Skip to content

Commit 63e1283

Browse files
j-fuj-fu
committed
documentation update
1 parent d70cc66 commit 63e1283

7 files changed

Lines changed: 70 additions & 29 deletions

‎src/abstractextendablesparsematrixcsc.jl‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,15 @@ Abstract super type for extendable CSC matrices. It implements what is being dis
55
as the "AbstractSparseMatrixCSC interfacee"
66
77
Subtypes must implement:
8-
- SparseArrays.sparse flush+return SparseMatrixCSC
8+
- `SparseArrays.sparse`: flush+return SparseMatrixCSC
99
- Constructor from SparseMatrixCSC
10-
- rawupdateindex!
11-
- reset!: empty all internals, just keep size
12-
- flush!: (re)build SparseMatrixCSC, incorporating new entries
10+
- [`rawupdateindex!`](@ref)
11+
- [`reset!`](@ref): empty all internals, just keep size
12+
- [`flush!`](@ref): (re)build SparseMatrixCSC, incorporate new entries
13+
14+
Subtypes of this type would contain a SparseMatrixCSC which is used in linear algebra
15+
operations. In addition they would contain data structures for efficiently adding new entries,
16+
like instances or vectors of instances of subtypes of [`AbstractSparseMatrixExtension`](@ref).
1317
"""
1418
abstract type AbstractExtendableSparseMatrixCSC{Tv, Ti} <: AbstractSparseMatrixCSC{Tv, Ti} end
1519

‎src/genericextendablesparsematrixcsc.jl‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,13 @@
22
$(TYPEDEF)
33
44
Single threaded extendable sparse matrix parametrized by sparse matrix extension.
5+
6+
Fields:
7+
- `cscmatrix`: a SparseMatrixCSC containg existing matrix entries
8+
- `xmatrix`: instance of an [`AbstractSparseMatrixExtension`](@ref) which is used to collect new entries
59
"""
610
mutable struct GenericExtendableSparseMatrixCSC{Tm <: AbstractSparseMatrixExtension, Tv, Ti <: Integer} <: AbstractExtendableSparseMatrixCSC{Tv, Ti}
7-
"""
8-
Final matrix data
9-
"""
1011
cscmatrix::SparseMatrixCSC{Tv, Ti}
11-
12-
"""
13-
Matrix for new entries
14-
"""
1512
xmatrix::Tm
1613
end
1714

‎src/genericmtextendablesparsematrixcsc.jl‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,25 @@
22
$(TYPEDEF)
33
44
5-
Extendable sparse matrix parametrized by sparse matrix extension allowing multithreaded assembly.
5+
Extendable sparse matrix parametrized by sparse matrix extension allowing multithreaded assembly and
6+
parallel matrix-vector multiplication.
7+
8+
Fields:
9+
- `cscmatrix`: a SparseMatrixCSC containg existing matrix entries
10+
- `xmatrices`: vector of instances of [`AbstractSparseMatrixExtension`](@ref) used to collect new entries
11+
- `colparts`: vector describing colors of the partitions of the unknowns
12+
- `partnodes`: vector describing partition of the unknowns
13+
14+
It is assumed that the set of unknowns is partitioned, and the partitioning is colored in such a way that
15+
several partitions of the same color can be handeled by different threads, both during matrix assembly (which
16+
in general would use a partition of e.g. finite elements compatible to the partioning of the nodes) and during
17+
matrix-vector multiplication. This approach is compatible with the current choice of the standard Julia
18+
sparse ecosystem which prefers compressed colume storage (CSC) over compressed row storage (CSR).
619
720
"""
821
mutable struct GenericMTExtendableSparseMatrixCSC{Tm <: AbstractSparseMatrixExtension, Tv, Ti <: Integer} <: AbstractExtendableSparseMatrixCSC{Tv, Ti}
9-
"""
10-
Final matrix data
11-
"""
1222
cscmatrix::SparseMatrixCSC{Tv, Ti}
13-
14-
"""
15-
Vector of dictionaries for new entries
16-
"""
1723
xmatrices::Vector{Tm}
18-
1924
colparts::Vector{Ti}
2025
partnodes::Vector{Ti}
2126
end

‎src/sparsematrixdict.jl‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,32 @@
11
"""
22
$(TYPEDEF)
33
4-
Sparse matrix where entries are organized as dictionary.
4+
[`AbstractSparseMatrixExtension`](@ref) extension where entries are organized as dictionary.
5+
This is meant as an example implementation to show how a sparse matrix
6+
extension could be implemented. As dictionary access tends to be slow, it
7+
is not meant for general use.
8+
9+
An advantage of this format is the fact that it avoids to store a vector of the length of unknowns
10+
indicating the first column indices, avoiding storage overhead during parallel assembly.
11+
12+
$(TYPEDFIELDS)
513
"""
614
mutable struct SparseMatrixDict{Tv, Ti} <: AbstractSparseMatrixExtension{Tv, Ti}
15+
"""
16+
Number of rows
17+
"""
718
m::Ti
19+
20+
"""
21+
Number of columns
22+
"""
823
n::Ti
24+
25+
"""
26+
Dictionary with pairs of integers as keys containing values
27+
"""
928
values::Dict{Pair{Ti, Ti}, Tv}
29+
1030
SparseMatrixDict{Tv, Ti}(m, n) where {Tv, Ti} = new(m, n, Dict{Pair{Ti, Ti}, Tv}())
1131
end
1232

‎src/sparsematrixdilnkc.jl‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,18 @@
11
"""
22
$(TYPEDEF)
33
4-
Modification of SparseMatrixLNK where the pointer to first index of
5-
column j is stored in a dictionary.
6-
"""
4+
[`AbstractSparseMatrixExtension`](@ref) where entries are stored as linked list, but
5+
where -- in difference to [`SparseMatrixLNK`](@ref) -- the pointer to first index
6+
of column j is stored in a dictionary.
7+
8+
Thus this format -- similar to [`SparseMatrixDict`](@ref) -- avoids to store a vector of the length of unknowns
9+
indicating the first column indices, avoiding storage overhead during parallel assembly.
10+
11+
Via the type alias [`MTExtendableSparseMatrixCSC`](@ref), this extension is used as default for handling
12+
parallel assembly.
13+
14+
$(TYPEDFIELDS)
15+
"""
716
mutable struct SparseMatrixDILNKC{Tv, Ti <: Integer} <: AbstractSparseMatrixExtension{Tv, Ti}
817
"""
918
Number of rows

‎src/sparsematrixlnk.jl‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
"""
22
$(TYPEDEF)
33
4-
Struct to hold sparse matrix in the linked list format.
4+
[`AbstractSparseMatrixExtension`](@ref) where entries are organized in the linked list
5+
sparse matrix format. This was the standard structure in ExtendableSparse v1.x.
56
67
Modeled after the linked list sparse matrix format described in
78
the [whitepaper](https://www-users.cs.umn.edu/~saad/software/SPARSKIT/paper.ps)
@@ -15,6 +16,11 @@ The advantage of the linked list structure is the fact that upon insertion
1516
of a new entry, the arrays describing the structure can grow at their respective ends and
1617
can be conveniently updated via `push!`. No copying of existing data is necessary.
1718
19+
Via the type aliases [`STExtendableSparseMatrixCSC`](@ref), [`ExtendableSparseMatrixCSC`](@ref),
20+
and [`ExtendableSparseMatrix`](@ref) this extension is used as default for handling
21+
scalar assembly.
22+
23+
1824
$(TYPEDFIELDS)
1925
"""
2026
mutable struct SparseMatrixLNK{Tv, Ti <: Integer} <: AbstractSparseMatrixExtension{Tv, Ti}

‎src/typealiases.jl‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
44
Multithreaded extendable sparse matrix (Experimental).
55
6-
Aliased to [`GenericMTExtendableSparseMatricCSC`](@ref) with [`SparseMatrixDILNKC`](@ref) scalar matrix parameter.
6+
Aliased to [`GenericMTExtendableSparseMatrixCSC`](@ref) with [`SparseMatrixDILNKC`](@ref) scalar matrix parameter.
77
"""
88
const MTExtendableSparseMatrixCSC{Tv, Ti} = GenericMTExtendableSparseMatrixCSC{SparseMatrixDILNKC{Tv, Ti}, Tv, Ti}
99
MTExtendableSparseMatrixCSC(m, n, args...) = MTExtendableSparseMatrixCSC{Float64, Int64}(m, n, args...)
@@ -13,7 +13,7 @@ MTExtendableSparseMatrixCSC(m, n, args...) = MTExtendableSparseMatrixCSC{Float64
1313
1414
Single threaded extendable sparse matrix (Experimental).
1515
16-
Aliased to [`GenericExtendableSparseMatricCSC`](@ref) with [`SparseMatrixLNK`](@ref) scalar matrix parameter.
16+
Aliased to [`GenericExtendableSparseMatrixCSC`](@ref) with [`SparseMatrixLNK`](@ref) scalar matrix parameter.
1717
"""
1818
const STExtendableSparseMatrixCSC{Tv, Ti} = GenericExtendableSparseMatrixCSC{SparseMatrixLNK{Tv, Ti}, Tv, Ti}
1919
STExtendableSparseMatrixCSC(::Type{Tv}, m::Number, n::Number) where {Tv} = STExtendableSparseMatrixCSC{Tv, Int64}(m, n)
@@ -34,7 +34,7 @@ STExtendableSparseMatrixCSC(I, J, V::AbstractVector, m, n, combine::Function) =
3434
"""
3535
ExtendableSparseMatrixCSC
3636
37-
Aliased to [`@STExtendableSparseMatrixCSC`](@ref) to ensure backward compatibility
37+
Aliased to [`STExtendableSparseMatrixCSC`](@ref) to ensure backward compatibility
3838
to ExtendableSparse v1.x.
3939
"""
4040
const ExtendableSparseMatrixCSC = STExtendableSparseMatrixCSC
@@ -43,7 +43,7 @@ const ExtendableSparseMatrixCSC = STExtendableSparseMatrixCSC
4343
"""
4444
ExtendableSparseMatrix
4545
46-
Aliased to [`@STExtendableSparseMatrixCSC`](@ref) to ensure backward compatibility
46+
Aliased to [`STExtendableSparseMatrixCSC`](@ref) to ensure backward compatibility
4747
to ExtendableSparse v1.x.
4848
"""
4949
const ExtendableSparseMatrix = STExtendableSparseMatrixCSC

0 commit comments

Comments
 (0)