You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/src/arrays.md
+24-20Lines changed: 24 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,28 +3,30 @@
3
3
There are two primary array types in SuiteSparseGraphBLAS.jl: [`GBVector`](@ref) and [`GBMatrix`](@ref), as well as a few specialized versions of those array types. The full type hierarchy is:
AbstractGBArray{T, F, O, N} <: AbstractSparseArray{Union{T, F}, N}
7
7
├ N = 2 ─ AbstractGBMatrix{T, F}
8
-
│ ├─ GBMatrix{T, F}
9
-
│ └─ OrientedGBMatrix{T, F, O}
10
-
└ N = 1 ─ AbstractGBVector{T, F}
11
-
└─ GBVector{T, F}
8
+
│ ├─ GBMatrix{T, F, RuntimeOrder()}
9
+
│ ├─ OrientedGBMatrix{T, F, O}
10
+
│ └─ GBShallowMatrix{T, F, ColMajor()}
11
+
└ N = 1, O = ColMajor() ─ AbstractGBVector{T, F}
12
+
├─ GBVector{T, F}
13
+
└─ GBShallowVector{T, F}
12
14
```
13
15
14
-
The `T` parameter is the element type of the array, `N` is the dimensionality, `F` is the type of the fill value (often `Nothing` or `T`). The `OrientedGBMatrix` restricts the orientation to the parameter `O`which is either `ByRow()` or `ByCol()`.
16
+
The `T` parameter is the element type of the array, `N` is the dimensionality, `F` is the type of the fill value (often `Nothing` or `T`), and `O` is the storage order. The `OrientedGBMatrix` restricts the orientation to the parameter `O`to either `ByRow()` or `ByCol()`.
15
17
16
18
All of these types attempt to implement most of the `AbstractArray` interface, and the relevant parts of the `SparseArrays` interface.
17
19
18
20
## GBMatrix
19
21
20
22
The `GBMatrix` is an opaque sparse matrix structure, which adapts to the sparsity of a matrix by changing the implementation internally. There are 4 different internal representations, all stored in either row or column orientation:
21
23
22
-
1.**Dense** - Equivalent to a Julia `Matrix`
23
-
2.**Bitmap** - 2 dense arrays, one storing booleans in the pattern of the matrix, the other storing the values.
4.**Doubly Compressed** or **Hypersparse** - Doubly Compressed Sparse Column (DCSC or Hypersparse CSC) and Doubly Compressed Sparse Row (DCSR or Hypersparse CSR). See this paper for more information: [pdf](https://people.eecs.berkeley.edu/~aydin/hypersparse-ipdps08.pdf).
24
+
1._**Dense**_ - Equivalent to a Julia `Matrix`, except it may be stored in `RowMajor()` order.
25
+
2._**Bitmap**_ - 2 dense arrays, one storing booleans in the pattern of the matrix, the other storing the values.
4._**Doubly Compressed**_ or **Hypersparse** - Doubly Compressed Sparse Column (DCSC or Hypersparse CSC) and Doubly Compressed Sparse Row (DCSR or Hypersparse CSR). See this paper for more information: [pdf](https://people.eecs.berkeley.edu/~aydin/hypersparse-ipdps08.pdf).
26
28
27
-
Additionally, when the stored values in a `GBMatrix` are uniform the value array may be stored in the **iso** version of one of the formats above. Rather than storing the full value array, an iso `GBMatrix` will only store the single scalar to improve performance. This is useful for matrices like the unweighted adjacency matrix, where all stored values may be `true`.
29
+
Additionally, when the stored values in a `GBMatrix` are uniform the value array may be stored in the _**iso**_ version of one of the formats above. Rather than storing the full value array, an iso `GBMatrix` will only store the single scalar to improve performance. This is useful for matrices like the unweighted adjacency matrix, where all stored values may be `true`.
28
30
29
31
Users should rarely need to directly interact with the underlying storage format, SuiteSparse:GraphBLAS will automatically convert between them as necessary.
30
32
@@ -40,14 +42,12 @@ x = GBMatrix{Bool}(20_000_000, 50_000)
Copy file name to clipboardExpand all lines: docs/src/index.md
+35-33Lines changed: 35 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,15 +53,17 @@ v = GBVector{Float64}(13)
53
53
# create a 1000 x 1000 empty sparse matrix with ComplexF64 elements.
54
54
A = GBMatrix{ComplexF64}(1000, 1000)
55
55
56
-
A[1,5] === nothing
56
+
# Non-stored values are equal to the fill value of A,
57
+
# which is by default zero(eltype(A))
58
+
A[1,5] == getfill(A)
57
59
```
58
60
59
61
Here we can already see several differences compared to `SparseArrays.SparseMatrixCSC`.
60
62
61
63
The first is that `A` is stored in `hypersparse` format, and by row.
62
64
63
65
`GBArrays` are (technically) opaque to the user in order to allow the library author to choose the best storage format.\
64
-
GraphBLAS takes advantage of this by storing matrices in one of four formats: `dense`, `bitmap`, `sparse-compressed`, or `hypersparse-compressed`; and in either `row` or `column` major orientation.\
66
+
SuiteSparse:GraphBLAS takes advantage of this by storing matrices in one of four formats: `dense`, `bitmap`, `sparse-compressed`, or `hypersparse-compressed`; and in either `row` or `column` major orientation.\
65
67
Different matrices may be better suited to storage in one of those formats, and certain operations may perform differently on `row` or `column` major matrices.
66
68
67
69
!!! warning "Default Orientation"
@@ -70,18 +72,16 @@ Different matrices may be better suited to storage in one of those formats, and
70
72
The orientation of a `GBMatrix` can be modified using
71
73
`setstorageorder!(A, RowMajor())` or `setstorageorder!(A, ColMajor())`, and queried by `StorageOrders.storageorder(A)`
72
74
73
-
Information about storage formats, orientation, conversion, construction and more can be found in [Arrays](@ref).
75
+
Information about storage formats, orientation, conversion, construction and more can be found in [Array-Types](@ref).
74
76
75
-
The second difference is that a `GBArray` doesn't assume the fill-in value of a sparse array.\
76
-
Since `A[1,5]` isn't stored in the matrix (it's been "compressed" out), we return `nothing`.\
77
-
78
-
This better matches the GraphBLAS spec, where `NO_VALUE` is returned, rather than `zero(eltype(A))`. This is better suited to graph algorithms where returning `zero(eltype(A))` might imply the presence of an edge with weight `zero`.\
79
-
However this behavior can be changed with the [`setfill!`](@ref) and [`setfill`](@ref) functions.
77
+
As noted in the example above, `A` has a fill-value, which defaults to `zero(eltype(A))`.
78
+
For normal linear algebra this is a good choice for fill-value, however GraphBLAS is intended for graphs.
79
+
To handle this `SuiteSparseGraphBLAS.jl` support `missing` for the fill value (this is an active area of development, and a new fill value that acts like the identity for most operations is better suited to this task).
80
80
81
81
```@repl intro
82
-
A[1, 1] === nothing
82
+
A[1, 1] == zero(eltype(A))
83
83
84
-
B = setfill(A, 0) # no-copy alias
84
+
B = setfill(A, missing) # no-copy alias
85
85
B[1, 1]
86
86
```
87
87
@@ -90,30 +90,32 @@ An empty matrix and vector won't do us much good, so let's see how to construct
90
90
```@repl intro
91
91
A = GBMatrix([1,1,2,2,3,4,4,5,6,7,7,7], [2,4,5,7,6,1,3,6,3,3,4,5], [1:12...])
92
92
93
-
v = GBVector([4], [10])
93
+
v = GBVector([4], [10], 7)
94
94
```
95
95
96
96
## GraphBLAS Operations
97
97
98
98
The complete documentation of supported operations can be found in [Operations](@ref).
99
99
GraphBLAS operations are, where possible, methods of existing Julia functions listed in the third column.
|`mxm`, `mxv`, `vxm`|``\bf C \langle M \rangle = C \odot AB``|`mul!` or `*`|
104
+
|`eWiseMult`|``\bf C \langle M \rangle = C \odot (A \otimes B)``|`emul[!]` or `.` broadcasting |
105
+
|`eWiseAdd`|``\bf C \langle M \rangle = C \odot (A \oplus B)``|`eadd[!]`|
106
+
|`eWiseUnion`|``\bf C \langle M \rangle = C \odot ([ A \vert \alpha ] \oplus [ B \vert \beta ])``|`eunion[!]`|
107
+
|`extract`|``\bf C \langle M \rangle = C \odot A(I,J)``|`extract[!]`, `getindex`|
108
+
|`subassign`|``\bf C (I,J) \langle M \rangle = C(I,J) \odot A``|`subassign[!]` or `setindex!`|
109
+
|`assign`|``\bf C \langle M \rangle (I,J) = C(I,J) \odot A``|`assign[!]`|
110
+
|`apply`|``{\bf C \langle M \rangle = C \odot} f{\bf (A)}``|`apply[!]`, `map[!]` or `.` broadcasting |
111
+
||``{\bf C \langle M \rangle = C \odot} f({\bf A},y)``||
112
+
||``{\bf C \langle M \rangle = C \odot} f(x,{\bf A})``||
113
+
||``{\bf C \langle M \rangle = C \odot} f({\bf A}_{ij}, i, j, x)``||
114
+
|`select`|``{\bf C \langle M \rangle = C \odot} f({\bf A}_{ij},i, j, x)``|`select[!]`|
115
+
|`reduce`|``{\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]``|`reduce[!]`|
116
+
||``s = s \odot [{\oplus}_{ij} {\bf A}(i,j)]``||
117
+
|`transpose`|``\bf C \langle M \rangle = C \odot A^{\sf T}``|`gbtranspose[!]`, lazy: `transpose`, `'`|
118
+
|`kronecker`|``\bf C \langle M \rangle = C \odot \text{kron}(A, B)``|`kron[!]`|
117
119
118
120
where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumulating into ``\bf C``, and ``\otimes`` and ``\oplus`` are a binary operation and commutative monoid respectively. ``f`` is either a unary or binary operator.
119
121
@@ -127,18 +129,18 @@ SuiteSparse:GraphBLAS ships with many of the common unary and binary operators a
127
129
along with monoids and semirings built commonly used in graph algorithms.
128
130
These built-in operators are *fast*, and should be used where possible. However, users are also free to provide their own functions as operators when necessary.
129
131
130
-
SuiteSparseGraphBLAS.jl will *mostly*take care of operators behind the scenes, and in most cases users should pass in normal functions like `+` and `sin`. For example:
132
+
SuiteSparseGraphBLAS.jl will take care of operators behind the scenes, and in most cases users should pass in normal functions like `+` and `sin`. For example:
131
133
132
134
```@repl intro
133
135
emul(A, A, ^) # elementwise exponent
134
136
135
137
map(sin, A)
136
138
```
137
139
138
-
Broadcasting functionality is also supported, `A .^ A` will lower to `emul(A, A, ^)`, and `sin.(A)` will lower to `map(sin, A)`.
140
+
Broadcasting functionality is also supported, `A .^ A` will lower to `emul(A, A, ^)`, and `sin.(A)` will lower to `apply(sin, A)`.
139
141
140
-
Matrix multiplication, which accepts a semiring, can be called with either `*(max, +)(A, B)` or
141
-
`*(A, B, (max, +))`.
142
+
Matrix multiplication, which accepts a semiring, can be called with either `*(max, +)(A, B)`,
143
+
`*(A, B, (max, +))`, or `LinearAlgebra.mul!(C, A, B, (max, +))`.
142
144
143
145
We can also use functions that are not already built into SuiteSparseGraphBLAS.jl:
144
146
@@ -153,8 +155,8 @@ Compared to `A .+ 1` which lowers to `apply(+, A, 1)` the `map` call above is ~2
153
155
154
156
!!! warning "Performance of User Defined Functions"
155
157
Operators which are not already built-in are automatically constructed using function pointers when called.
156
-
Note, however, that their performance is significantly degraded compared to built-in operators,
157
-
and where possible user code should avoid this capability. See [Operators](@ref).
158
+
Their performance is significantly degraded compared to built-in operators,
159
+
and where possible user code should avoid this capability and instead compose built-in operators. See [Operators](@ref).
Copy file name to clipboardExpand all lines: docs/src/operations.md
+10-1Lines changed: 10 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,11 +44,12 @@ Typically you should use Julia's built-in transpose functionality.
44
44
45
45
-`desc.complement_mask == [true | false]`:
46
46
47
-
If `complement_mask` is set the presence/truth value of the mask is complemented.
47
+
If `complement_mask` is set the presence/truth value of the mask is complemented. See [`SuiteSparseGraphBLAS.Complement`](@ref) for a wrapper that sets this flag.
48
48
49
49
-`desc.structural_mask == [true | false]`:
50
50
51
51
If `structural_mask` is set the presence of a value in the mask determines the presence of values in the output, rather than the actual value of the mask.
52
+
See [`SuiteSparseGraphBLAS.Structural`](@ref) for a wrapper that sets this flag.
0 commit comments