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
+14-17Lines changed: 14 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,16 +21,15 @@ The `GBMatrix` is an opaque sparse matrix structure, which adapts to the sparsit
21
21
22
22
1.**Dense** - Equivalent to a Julia `Matrix`
23
23
2.**Bitmap** - 2 dense arrays, one storing booleans in the pattern of the matrix, the other storing the values.
24
-
3.**Compressed** - [Compressed Sparse Column (CSC)](http://netlib.org/linalg/html_templates/node92.html#SECTION00931200000000000000) or [Compressed Sparse Row(CSR)](http://netlib.org/linalg/html_templates/node91.html)
25
-
4.**Doubly Compressed** - 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
-
27
-
Users should never need to directly interact with the underlying storage type, SuiteSparse:GraphBLAS will automatically convert between them as necessary.
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).
28
26
27
+
Additionally a 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
28
29
+
Users should never need to directly interact with the underlying storage format, SuiteSparse:GraphBLAS will automatically convert between them as necessary.
30
30
31
31
### Construction
32
32
33
-
34
33
There are several methods to construct GBArrays. Shown here are empty construction, conversion from a dense matrix and a sparse matrix, and coordinate form with uniform or *iso* coefficients.
A `GBVector` is the one-dimensional equivalent of the `GBMatrix`, and internally a `GBVector` is represented in exactly the same fashion. However, they are always column-oriented.
56
+
57
+
### Construction
58
+
55
59
```@repl mat
56
60
v = GBVector{ComplexF32}(100)
57
61
v = GBMatrix(rand(ComplexF64, 3); fill = nothing)
@@ -72,22 +76,21 @@ The usual AbstractArray and SparseArray indexing capabilities are available. Inc
72
76
73
77
When indexing a GBArray structural zeros default to `nothing`.
74
78
While this is a significant departure from the `SparseMatrixCSC` it more closely matches the GraphBLAS spec,
75
-
and enables the consuming method to determine the value of implicit zeros.
79
+
and enables the consuming method to determine the value of implicit zeros in the presence of explicit zeros.
76
80
77
-
For instance with an element type of `Float64` you may want the zero to be `0.0`, `-∞` or `+∞` depending on your algorithm. In addition, for graph algorithms there may be a distinction between an implicit zero, indicating the lack of an edge between two vertices in an adjacency matrix, and an explicit zero where the edge exists but has a `0` weight.
81
+
For instance with an element type of `Float64` you may want the implicit zero to be `0.0`, `-∞` or `+∞` depending on your algorithm. In addition, for graph algorithms there may be a distinction between an implicit zero, indicating the lack of an edge between two vertices in an adjacency matrix, and an explicit zero where the edge exists but has a `0` weight.
78
82
79
-
However, many functions outside of GraphBLAS will not work when they index into an `AbstractArray` and get `nothing`.
83
+
However, many functions outside of GraphBLAS will throw an error if they receive `nothing` from an indexing operation. To accomodate these functions the user may set the fill value for an `AbstractGBArray` on construction and with [`setfill`](@ref) and [`setfill!`](@ref).
80
84
81
85
```@repl mat
82
86
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...])
83
87
SparseMatrixCSC(A)
84
88
A[4]
85
-
A[1,2]
89
+
A[1,2]
86
90
A[[1,3,5,7], :]
87
91
A[1:2:7, :]
88
92
A[:,:]
89
93
A[:, 5]
90
-
SparseMatrixCSC(A'[:,:]) #Transpose the first argument
91
94
```
92
95
93
96
The functionality illustrated above extends to `GBVector` as well.
@@ -98,11 +101,5 @@ overloaded to be equivalent.
98
101
99
102
!!! danger "Adjoint vs Transpose"
100
103
The adjoint operator `'` currently transposes matrices rather than performing the
101
-
conjugate transposition. In the future this will change to the complex conjugate
104
+
conjugate transposition. In the future this will change to the eager adjoint
102
105
for complex types, but currently you must do `map(conj, A')` to achieve this.
|`mxm`, `mxv`, `vxm`|``\bf C \langle M \rangle = C \odot AB``|`mul[!]`|
10
-
|`eWiseMult`|``\bf C \langle M \rangle = C \odot (A \otimes B)``|`emul[!]`|
11
-
|`eWiseAdd`|``\bf C \langle M \rangle = C \odot (A \oplus B)``|`eadd[!]`|
12
-
|`extract`|``\bf C \langle M \rangle = C \odot A(I,J)``|`extract[!]`, `getindex`|
13
-
|`subassign`|``\bf C (I,J) \langle M \rangle = C(I,J) \odot A``|`subassign[!]`, `setindex!`|
14
-
|`assign`|``\bf C \langle M \rangle (I,J) = C(I,J) \odot A``|`assign[!]`|
15
-
|`apply`|``{\bf C \langle M \rangle = C \odot} f{\bf (A)}``|`map[!]`|
16
-
||``{\bf C \langle M \rangle = C \odot} f({\bf A},y)``||
17
-
||``{\bf C \langle M \rangle = C \odot} f(x,{\bf A})``||
18
-
|`select`|``{\bf C \langle M \rangle = C \odot} f({\bf A},k)``|`select[!]`|
19
-
|`reduce`|``{\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]``|`reduce[!]`|
20
-
||``s = s \odot [{\oplus}_{ij} {\bf A}(i,j)]``||
21
-
|`transpose`|``\bf C \langle M \rangle = C \odot A^{\sf T}``|`gbtranspose[!]`, lazy: `transpose`, `'`|
22
-
|`kronecker`|``\bf C \langle M \rangle = C \odot \text{kron}(A, B)``|`kron[!]`|
23
-
24
-
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.
|`mxm`, `mxv`, `vxm`|``\bf C \langle M \rangle = C \odot AB``|`mul[!]` or `*`|
9
+
|`eWiseMult`|``\bf C \langle M \rangle = C \odot (A \otimes B)``|`emul[!]`or `.` broadcasting|
10
+
|`eWiseAdd`|``\bf C \langle M \rangle = C \odot (A \oplus B)``|`eadd[!]`|
11
+
|`extract`|``\bf C \langle M \rangle = C \odot A(I,J)``|`extract[!]`, `getindex`|
12
+
|`subassign`|``\bf C (I,J) \langle M \rangle = C(I,J) \odot A``|`subassign[!]` or `setindex!`|
13
+
|`assign`|``\bf C \langle M \rangle (I,J) = C(I,J) \odot A``|`assign[!]`|
14
+
|`apply`|``{\bf C \langle M \rangle = C \odot} f{\bf (A)}``|`apply[!]`, `map[!]` or `.` broadcasting|
15
+
||``{\bf C \langle M \rangle = C \odot} f({\bf A},y)``||
16
+
||``{\bf C \langle M \rangle = C \odot} f(x,{\bf A})``||
17
+
|`select`|``{\bf C \langle M \rangle = C \odot} f({\bf A},k)``|`select[!]`|
18
+
|`reduce`|``{\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]``|`reduce[!]`|
19
+
||``s = s \odot [{\oplus}_{ij} {\bf A}(i,j)]``||
20
+
|`transpose`|``\bf C \langle M \rangle = C \odot A^{\sf T}``|`gbtranspose[!]`, lazy: `transpose`, `'`|
21
+
|`kronecker`|``\bf C \langle M \rangle = C \odot \text{kron}(A, B)``|`kron[!]`|
22
+
23
+
24
+
where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumulating into ``\bf C``, and ``\otimes`` and ``\oplus`` are binary operators or monoids.
25
25
26
26
!!! note "assign vs subassign"
27
-
`subassign` is equivalent to `assign` except that the mask in `subassign` has the dimensions of ``\bf C(I,J)`` vs the dimensions of ``C`` for `assign`, and elements outside of the mask will never be modified by `subassign`. See the [GraphBLAS User Guide](https://github.com/DrTimothyAldenDavis/GraphBLAS/blob/stable/Doc/GraphBLAS_UserGuide.pdf) for more details.
28
-
29
-
## Operation Documentation
30
-
31
-
All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix.
32
-
33
-
### `mul`
34
-
```@docs
35
-
mul
36
-
emul
37
-
emul!
38
-
eadd
39
-
eadd!
40
-
extract
41
-
subassign!
42
-
assign!
43
-
Base.map
44
-
select
45
-
Base.reduce
46
-
gbtranspose
47
-
LinearAlgebra.kron
48
-
```
27
+
`subassign` is equivalent to `assign` except that the mask in `subassign` has the dimensions of ``\bf C(I,J)`` vs the dimensions of ``C`` for `assign`. Elements outside of the mask will also never be modified by `subassign`. See the [GraphBLAS User Guide](https://github.com/DrTimothyAldenDavis/GraphBLAS/blob/stable/Doc/GraphBLAS_UserGuide.pdf) for more details.
49
28
50
29
## Common arguments
51
30
52
31
The operations typically accept one of the following types in the `op` argument.
53
32
54
-
### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
55
-
56
-
This argument determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`. They typically have synonymous functions in Julia, so `conj` can be used in place of `UnaryOps.CONJ` for instance.
33
+
### `op` - `Function`:
57
34
58
-
!!! tip "Built-Ins"
59
-
The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
60
-
61
-
See the [Operators](@ref) section for more information.
35
+
This argument determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`. See [Operators](@ref) for more information.
62
36
63
37
### `desc` - `Descriptor`:
64
38
65
-
The descriptor argument allows the user to modify the operation in some fashion. The most common options are:
39
+
The descriptor argument allows the user to modify the operation in some fashion. A new `Descriptor` can be created with default settings as: `d = Descriptor()`. The most common options are:
Typically you should use Julia's built-in transpose functionality.
43
+
Typically you should use Julia's built-in transpose functionality.
70
44
71
-
-`desc.complement_mask == [true | false]`
45
+
-`desc.complement_mask == [true | false]`:
72
46
73
-
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.
74
48
75
-
-`desc.structural_mask == [true | false]`
49
+
-`desc.structural_mask == [true | false]`:
76
50
77
-
If `structural_mask` is set the presence of a value in the mask determines the presence of values
78
-
in the output, rather than the actual value of the mask.
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.
79
52
80
-
-`desc.replace_output == [true | false]`
53
+
-`desc.replace_output == [true | false]`:
81
54
82
-
If this option is set the operation will replace all values in the output matrix **after** the accumulation step.
83
-
If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`.
55
+
If this option is set the operation will replace all values in the output matrix **after** the accumulation step.
56
+
If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`.
84
57
85
58
86
-
### `accum` - `BinaryOp | Function`:
59
+
### `accum` - `Function`:
87
60
88
61
The `accum` keyword argument provides a binary operation to accumulate results into the result array.
89
62
The accumulation step is performed **before** masking.
@@ -94,6 +67,28 @@ The `mask` keyword argument determines whether each index from the result of an
94
67
The mask may be structural, where the presence of a value indicates the mask is `true`, or valued where the value of the mask indicates its truth value.
95
68
The mask may also be complemented. These options are controlled by the `desc` argument.
96
69
70
+
71
+
## Operation Documentation
72
+
73
+
All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix.
74
+
75
+
```@docs
76
+
mul
77
+
emul
78
+
emul!
79
+
eadd
80
+
eadd!
81
+
extract
82
+
subassign!
83
+
assign!
84
+
apply
85
+
select
86
+
Base.reduce
87
+
gbtranspose
88
+
LinearAlgebra.kron
89
+
mask
90
+
```
91
+
97
92
## Order of Operations
98
93
99
94
A GraphBLAS operation semantically occurs in the following order:
0 commit comments