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
Conversion back to matrices, sparse or dense, is also supported.
31
+
## Vector Construction
32
+
```@repl mat
33
+
v = GBVector{ComplexF32}(100)
34
+
v = GBMatrix(rand(ComplexF64, 3))
35
+
v = GBVector(sprand(Bool, 100_000_000, 0.001))
36
+
```
37
+
38
+
```@docs
39
+
GBVector
40
+
SuiteSparseGraphBLAS.GBVector{T}()
41
+
SuiteSparseGraphBLAS.GBVector(::Vector, ::Vector)
42
+
SuiteSparseGraphBLAS.GBVector(::SparseVector)
43
+
```
44
+
45
+
# Indexing
46
+
47
+
The usual AbstractArray and SparseArray indexing should work here. Including indexing by scalars, vectors, and ranges.
48
+
49
+
!!! danger "Indexing Structural Zeros"
50
+
When you index a `SparseMatrixCSC` from `SparseArrays` and hit a structural zero (a value within the dimensions of the matrix but not stored) you can expect a `zero(T)`.
51
+
52
+
When you index a GBArray you will get `nothing` when you hit a structural zero. This is because the zero in GraphBLAS depends not just on the domain of the elements but also on what you are __doing__ with them. For instance with an element type of `Float64` you could want the zero to be `0.0`, `-∞` or `+∞`.
53
+
54
+
We'll use the small matrix from the Introduction to illustrate the indexing capabilities. We will also use `SparseArrays.SparseMatrixCSC` for the pretty printing functionality, which should be available in this package in `v1.0`.
55
+
56
+
```@repl mat
57
+
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...])
58
+
SparseMatrixCSC(A)
59
+
A[4]
60
+
A[1,2]
61
+
A[[1,3,5,7], :]
62
+
A[1:2:7, :]
63
+
A[:,:]
64
+
A[:, 5]
65
+
SparseMatrixCSC(A[:,:, desc=Descriptors.T0]) #Transpose the first argument
66
+
```
67
+
68
+
All of this same functionality exists for vectors in 1-dimension.
Copy file name to clipboardExpand all lines: docs/src/binaryops.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,14 @@
1
1
# Binary Operators
2
2
3
+
Binary operators are defined on three domains $D_1 \times D_2 \rightarrow D_3$.
4
+
However, the vast majority of binary operators are defined on a single domain.
5
+
3
6
## Built-Ins
4
7
8
+
All built-in binary oeprators can be found in the `BinaryOps` submodule.
9
+
10
+
The documentation below uses `T` to refer to any of the valid primitive types listed in [Supported Types](@ref), `ℤ` to refer to integers (signed and unsigned), `F` to refer to floating point types, `ℝ` to refer to real numbers (non-complex numbers).
SuiteSparseGraphBLAS.jl is a WIP package for sparse linear algebra on arbitrary semirings, with a particular focus on graph computations.
3
+
SuiteSparseGraphBLAS.jl is a package for sparse linear algebra on arbitrary semirings, with a particular focus on graph computations.
4
4
It aims to provide a Julian wrapper over Tim Davis' SuiteSparse reference implementation of the GraphBLAS C specification.
5
5
6
6
# Roadmap
7
7
8
+
!!! note
9
+
This library is still very WIP, if you are missing any functionality, or find any incorrectly implemented functions from those interfaces please open an issue or PR!
10
+
8
11
While the core library is mostly complete, and all GraphBLAS functionality is present, there are still quite a few features being worked on for v1.0:
9
12
10
13
1. ChainRules.jl integration for AD.
11
14
2. Complete SparseArrays and ArrayInterface interfaces.
12
-
3.Printing v2.
13
-
4. User-defined types and functions.
15
+
3.Fancy printing
16
+
4. User-defined types.
14
17
5. Alternative syntax for GraphBLAS ops (currently must use `BinaryOps.PLUS` instead of `+`).
15
-
6. Complex builtins.
16
18
17
19
Once these are completed there will be a v1.0 release, with the goal being JuliaCon 2021.
18
20
@@ -23,16 +25,12 @@ Post 1.0 goals include:
23
25
3. More efficient import and export between Julia and GraphBLAS
24
26
4. Support for other GraphBLAS implementations in a follow-up GraphBLAS.jl
25
27
26
-
!!! danger "Printing"
27
-
28
-
Printing is done directly by GraphBLAS in this release. This means printed indices are 0-based, and the displayed type is the equivalent C type. The v1.0 release will alleviate this issue.
29
-
30
28
# Installation
31
29
32
30
Install using the Julia package manager in the REPL:
33
31
34
32
```
35
-
] add SuiteSparseGraphBLAS#master
33
+
] add SuiteSparseGraphBLAS
36
34
```
37
35
38
36
or with `Pkg`
@@ -62,13 +60,15 @@ The three primary components of GraphBLAS are: matrices, operators, and operatio
62
60
63
61
SuiteSparseGraphBLAS.jl provides `GBVector` and `GBMatrix` array types which are subtypes of `SparseArrays.AbstractSparseVector` and `SparseArrays.AbstractSparseMatrix` respectively. Both can be constructed with no arguments to use the maximum size.
64
62
65
-
```julia
66
-
julia>GBVector{Float64}()
67
-
1152921504606846976x1 GraphBLAS double vector, sparse by col
68
-
no entries
63
+
```@setup intro
64
+
using SuiteSparseGraphBLAS
65
+
using SparseArrays
66
+
```
67
+
68
+
```@repl intro
69
+
GBVector{Float64}()
69
70
70
-
1152921504606846976x1152921504606846976 GraphBLAS int8_t matrix, hypersparse by col
71
-
no entries
71
+
GBMatrix{ComplexF64}()
72
72
```
73
73
74
74
GraphBLAS array types are opaque to the user in order to allow the library author to choose the best storage format.
@@ -77,29 +77,10 @@ SuiteSparseGraphBLAS.jl sets the default to column major to ensure fast imports
77
77
78
78
A complete list of construction methods can be found in [Construction](@ref), but the matrix and vector above can be constructed as follows:
79
79
80
-
```julia
81
-
julia> 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...])
82
-
7x7 GraphBLAS int64_t matrix, bitmap by col
83
-
12 entries
84
-
85
-
(3,0) 6
86
-
(0,1) 1
87
-
(3,2) 7
88
-
(5,2) 9
89
-
(6,2) 10
90
-
(0,3) 2
91
-
(6,3) 11
92
-
(1,4) 3
93
-
(6,4) 12
94
-
(2,5) 5
95
-
(4,5) 8
96
-
(1,6) 4
80
+
```@repl intro
81
+
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...])
97
82
98
83
v = GBVector([4], [10])
99
-
4x1 GraphBLAS int64_t vector, bitmap by col
100
-
1 entry
101
-
102
-
(3,0) 10
103
84
```
104
85
## GraphBLAS Operations
105
86
@@ -125,49 +106,6 @@ GraphBLAS operations are, where possible, methods of existing Julia functions l
125
106
126
107
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.
127
108
128
-
### Common arguments
129
-
130
-
The operations above have often accept most or all of the following arguments.
131
-
132
-
#### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
133
-
134
-
This is the most important argument for most of these operations. It determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
135
-
Most operations are restricted to one type of operator.
136
-
137
-
!!! tip "Built-Ins"
138
-
The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
139
-
140
-
#### `desc` - `Descriptor`:
141
-
142
-
The descriptor argument allows the user to modify the operation in some fashion. The most common options are:
If `STRUCTURE` is set the operation will use the presence of a value rather than the value itself to determine whether the index is masked.
152
-
If `COMPLEMENT` is set the presence/truth value is complemented (ie. if **no** value is present or the value is **false** that index is masked).
153
-
154
-
-`desc.output == [DEFAULT | REPLACE]`
155
-
156
-
If `REPLACE` is set the operation will replace all values in the output matrix **after** the accumulation step.
157
-
If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`.
158
-
159
-
160
-
#### `accum` - `BinaryOp`:
161
-
162
-
The `accum` keyword argument provides a binary operation to accumulate results into the result array.
163
-
The accumulation step is performed **before** masking.
164
-
165
-
#### `mask` - `GBArray`:
166
-
167
-
The `mask` keyword argument determines whether each index from the result of an operation appears in the output.
168
-
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.
169
-
The mask may also be complemented. These options are controlled by the `desc` argument.
170
-
171
109
## GraphBLAS Operators
172
110
173
111
GraphBLAS operators are one of the following:
@@ -180,7 +118,7 @@ GraphBLAS operators are one of the following:
180
118
Built-in operators can be found in exported submodules:
181
119
182
120
```julia
183
-
julia> BinaryOps.
121
+
julia> BinaryOps.\TAB
184
122
185
123
ANY BSET DIV FIRSTJ1 ISGE LDEXP MIN RDIV SECONDJ
186
124
ATAN2 BSHIFT EQ FMOD ISGT LE MINUS REMAINDER SECONDJ1
@@ -198,7 +136,7 @@ The methods are drawn from the LAGraph [repo](https://github.com/GraphBLAS/LAGra
198
136
Input `A` must be a square, symmetric matrix with any element type.
199
137
We'll test it using the matrix from the GBArray section above, which has two triangles in its undirected form.
200
138
201
-
```julia
139
+
```@repl intro
202
140
function cohen(A)
203
141
U = select(SelectOps.TRIU, A)
204
142
L = select(SelectOps.TRIL, A)
@@ -211,6 +149,6 @@ function sandia(A)
211
149
end
212
150
213
151
M = eadd(A, A', BinaryOps.PLUS) #Make undirected/symmetric
Copy file name to clipboardExpand all lines: docs/src/monoids.md
+8-2Lines changed: 8 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,18 @@
1
1
# Monoids
2
-
## About
3
2
4
3
A monoid is made up of a set or domain $T$ and a binary operator $z = f(x, y)$ operating on the same domain, $T \times T \rightarrow T$.
5
4
This binary operator must be associative, that is $f(a, f(b, c)) = f(f(a, b), c)$ is always true. Associativity is important for operations like `reduce` and the multiplication step of `mul`.
6
5
7
-
The operator must also be equipped with an identity such that $f(x, 0) = f(0, x) = x$. Some monoids are equipped with a terminal or annihilator such that $z = f(z, x) \forall x$.
6
+
The operator is also be equipped with an identity such that $f(x, 0) = f(0, x) = x$. Some monoids are equipped with a terminal or annihilator such that $z = f(z, x) \forall x$.
7
+
8
+
Monoids are used primarily in the `reduce`(@ref) operation. Their other use is as a component of semirings in the [`mul`](@ref) operation.
8
9
9
10
## Built-Ins
11
+
12
+
All built-in monoids can be found in the `Monoids` submodule.
13
+
14
+
The documentation below uses `T` to refer to any of the valid primitive types listed in [Supported Types](@ref), `ℤ` to refer to integers (signed and unsigned), `F` to refer to floating point types, `ℝ` to refer to real numbers (non-complex numbers).
15
+
10
16
!!! note "Note"
11
17
In the case of floating point numbers +∞ and -∞ have their typical meanings. However, for integer types they indicate `typemax` and `typemin` respectively.
Copy file name to clipboardExpand all lines: docs/src/operations.md
+50-2Lines changed: 50 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,6 +26,49 @@ where ``\bf M`` is a `GBArray` mask, ``\odot`` is a binary operator for accumula
26
26
!!! note "assign vs subassign"
27
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
28
29
+
## Common arguments
30
+
31
+
The operations above have often accept most or all of the following arguments.
32
+
33
+
### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
34
+
35
+
This is the most important argument for most of these operations. It determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
36
+
Most operations are restricted to one type of operator.
37
+
38
+
!!! tip "Built-Ins"
39
+
The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
40
+
41
+
### `desc` - `Descriptor`:
42
+
43
+
The descriptor argument allows the user to modify the operation in some fashion. The most common options are:
If `STRUCTURE` is set the operation will use the presence of a value rather than the value itself to determine whether the index is masked.
53
+
If `COMPLEMENT` is set the presence/truth value is complemented (ie. if **no** value is present or the value is **false** that index is masked).
54
+
55
+
-`desc.output == [DEFAULT | REPLACE]`
56
+
57
+
If `REPLACE` is set the operation will replace all values in the output matrix **after** the accumulation step.
58
+
If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`.
59
+
60
+
61
+
### `accum` - `BinaryOp`:
62
+
63
+
The `accum` keyword argument provides a binary operation to accumulate results into the result array.
64
+
The accumulation step is performed **before** masking.
65
+
66
+
### `mask` - `GBArray`:
67
+
68
+
The `mask` keyword argument determines whether each index from the result of an operation appears in the output.
69
+
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.
70
+
The mask may also be complemented. These options are controlled by the `desc` argument.
71
+
29
72
## Order of Operations
30
73
31
74
A GraphBLAS operation occurs in the following order (steps are skipped when possible):
@@ -38,15 +81,20 @@ If `REPLACE` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`
38
81
39
82
## Operation Documentation
40
83
84
+
All non-mutating operations below support a mutating form by adding an output array as the first argument as well as the `!` function suffix.
0 commit comments