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/binaryops.md
+85-17Lines changed: 85 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,23 +3,91 @@
3
3
Binary operators are defined on three domains $D_1 \times D_2 \rightarrow D_3$.
4
4
However, the vast majority of binary operators are defined on a single domain.
5
5
6
-
## Built-Ins
6
+
`BinaryOp`s are in almost every GraphBLAS operation. They are the primary `op` argument for [`emul`](@ref), [`eadd`](@ref), and [`apply`](@ref). `BinaryOp`s which are also monoids may be used in [`reduce`](@ref). And every GraphBLAS operation which takes an `accum` keyword argument accepts a `BinaryOp`.
7
+
8
+
In 99% of cases you should pass Julia functions, which will be mapped to built-in operators, or used to create a new user-defined operator.
9
+
10
+
```@repl
11
+
using SuiteSparseGraphBLAS
12
+
13
+
x = GBMatrix([[1,2] [3,4]])
14
+
15
+
x .+ x
16
+
eadd(x, x, +)
17
+
18
+
x .^ x
19
+
emul(x, x, ^)
20
+
21
+
x2 = Float64.(x)
22
+
eadd!(x2, x, x, +; accum=/)
23
+
```
7
24
8
-
All built-in binary operators can be found in the `BinaryOps` submodule.
25
+
Internally functions are lowered like this:
9
26
10
-
```@eval
11
-
using Pkg
12
-
Pkg.activate("..")
13
-
cd("..")
27
+
```@repl
14
28
using SuiteSparseGraphBLAS
15
-
using Latexify
16
-
head = ["UnaryOp", "Function Form", "Types"]
17
-
v1 = filter((x) -> getproperty(BinaryOps, x) isa SuiteSparseGraphBLAS.AbstractBinaryOp, names(BinaryOps))
Copy file name to clipboardExpand all lines: docs/src/monoids.md
+17-23Lines changed: 17 additions & 23 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,26 +9,20 @@ Monoids are used primarily in the `reduce`(@ref) operation. Their other use is a
9
9
10
10
## Built-Ins
11
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
-
16
-
!!! note "Note"
17
-
In the case of floating point numbers +∞ and -∞ have their typical meanings. However, for integer types they indicate `typemax` and `typemin` respectively.
Operators are one of the basic objects of GraphBLAS. In Julia, however, users must only interact directly with operators on rare occasions, and should instead pass functions to GraphBLAS operations.
4
+
3
5
There are five operator types in SuiteSparseGraphBLAS. Four are defined for all GraphBLAS implementations: `UnaryOp`, `BinaryOp`, `Monoid`, and `Semiring`.
4
6
One is an extension to the `v1.3` specification: `SelectOp`.
5
7
6
8
!!! danger "Note"
7
-
Operators are **not** callable objects like functions. They **do** behave like functions as arguments to higher-order functions (operations in the language of GraphBLAS). However `BinaryOp` and `UnaryOp` operators
8
-
typically have a synonymous julia function, which can be found using `juliaop(op)`.
9
+
Operators are **not** callable objects like functions. They **do** behave like functions when used as arguments to higher-order functions (operations in the language of GraphBLAS).
9
10
10
11
Typically operators are positional arguments in one of two places.
11
12
For operations with a clear default operator they appear as the last positional argument:
@@ -17,18 +18,21 @@ For operations with a clear default operator they appear as the last positional
17
18
18
19
For other operations without a clear default operator they appear as the first argument:
GraphBLAS supports both built-in and user-defined operators. Built-in operators are precompiled C functions, while user-defined operators are function pointers to Julia functions.
28
+
29
+
Built-in operators are typically much faster than user-defined ones. See the page for the particular operator type (unary, binary, select, etc.) for more information.
30
+
31
+
24
32
## UnaryOps, BinaryOps, Monoids, and Semirings
25
33
26
34
Each operator is defined on a specific domain. For some this is the usual primitive datatypes like booleans, floats, and signed and unsigned integers of the typical sizes.
27
35
28
-
Each operator is represented as its own concrete type for dispatch purposes.
29
-
For instance `BinaryOps.PLUS <: AbstractBinaryOp <: AbstractOp`.
30
-
Operators are effectively dictionaries containing the type-specific operators indexed by the `DataType` of their arguments.
31
-
32
36
### Supported Types
33
37
34
38
SuiteSparseGraphBLAS.jl natively supports the following types:
@@ -39,42 +43,44 @@ SuiteSparseGraphBLAS.jl natively supports the following types:
39
43
- Float32 and Float64
40
44
- ComplexF32 and ComplexF64
41
45
42
-
The supported types can be found as in the example below:
46
+
### Lowering
47
+
48
+
Operators are lowered from a Julia function to a container like `BinaryOp` or `Semiring`. After this they are lowered once again using the type to a `TypedBinaryOp`, `TypedSemiring`, etc. The `TypedBinaryOp` contains the reference to the C-side GraphBLAS operator. Typed operators, like `TypedSemiring` are constants, found in a submodule (`SuiteSparseGraphBLAS.Semirings` in the case of `TypedSemiring`s).
49
+
43
50
```@setup operators
44
51
using SuiteSparseGraphBLAS
45
52
```
46
53
```@repl operators
47
-
Semiring(max, +)
48
-
Semirings.MAX_PLUS
49
-
Semirings.MAX_PLUS[Float64]
54
+
b = BinaryOp(+)
55
+
b(Int32)
56
+
57
+
s = Semiring(max, +)
58
+
s(Float64)
50
59
```
51
60
52
-
All operations will accept the function/tuple form, the `DataType` form, or the `TypedSemiring` form.
53
-
Unless you need to specifically cast the arguments to a specific type there is no need to specify the operator type.
61
+
All operations should accept the function/tuple form, the `Semiring{typeof(max), typeof(+)}` form, or the `TypedSemiring` form.
62
+
Unless you need to specifically cast the arguments to a specific type there is generally no need to use the latter two forms.
54
63
55
-
You can determine the available types for an operator and the input and output types of a type-specific operator with the functions below:
64
+
You can determine the the input and output types of a type-specific operator with the functions below:
56
65
57
66
```@docs
58
67
xtype
59
68
ytype
60
69
ztype
61
70
```
62
-
```@docs
63
-
validtypes
64
-
```
65
71
66
72
Some examples of these functions are below.
67
73
Note the difference between `ISGT` which returns a result with the same type as the input, and `GT` which returns a `Boolean`.
68
74
69
75
```@repl operators
70
-
xtype(Semirings.LOR_GT[Float64])
71
-
ztype(Semirings.LOR_GT[Float64])
72
-
xtype(BinaryOps.ISGT[Int8])
73
-
ztype(BinaryOps.ISGT[Int8])
74
-
ztype(BinaryOps.GT[Int8])
76
+
xtype(Semirings.LOR_GT_UINT16)
77
+
ztype(Semirings.LOR_GT_FP64)
78
+
xtype(BinaryOps.ISGT_INT8)
79
+
ztype(BinaryOps.ISGT_INT8)
80
+
ztype(BinaryOps.GT_INT8)
75
81
```
76
82
77
83
## SelectOps
78
84
79
85
The [`SelectOp`](@ref) is a SuiteSparse extension to the specification, although a similar construct is likely to be found in a future specification.
80
-
Unlike the other operators there are no type-specific operators, and as such you cannot index into them with types to obtain a type-specific version.
86
+
Unlike the other operators there are no type-specific operators, and as such you cannot index into them with types to obtain a type-specific version.
Copy file name to clipboardExpand all lines: docs/src/semirings.md
+5-42Lines changed: 5 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,45 +10,8 @@ A semiring is denoted by a tuple $(D_1, D_2, D_3, \oplus, \otimes, \mathbb{0})$.
10
10
11
11
Semirings are used in a single GraphBLAS operation, [`mul[!]`](@ref mul).
12
12
13
-
## Built-Ins
14
-
There are over 200 built-in semirings available as constants in the `Semirings` submodule. These are named `<ADD>_<MULTIPLY>` and include many of the most commonly used semirings such as:
15
-
16
-
- Arithmetic semiring $(+, \times)$, available as `Semirings.PLUS_TIMES` and as the default operator for `mul[!]`.
17
-
- Tropical semirings $(\max, +)$, available as `Semirings.MAX_PLUS`, and $(\min, +)$, available as `Semirings.MIN_PLUS`).
18
-
- Boolean semiring $(\vee, \wedge)$ available as `Semirings.LOR_LAND`.
19
-
- GF2, the two-element Galois Field $(\text{xor}, \wedge)$, available as `Semirings.LXOR_LAND`.
20
-
21
-
Below are the built-in semirings available, along with their associated monoids, binary operators, and types.
22
-
For common semirings where the binary operator and monoid have equivalent julia functions, those functions are listed.
23
-
24
-
25
-
!!! note
26
-
In all cases the input and output types of the semirings are the same, **except** for cases where the "add" types and "multiply" output output types are boolean, such as in `LAND_GE`.
27
-
28
-
```@eval
29
-
using Pkg
30
-
Pkg.activate("..")
31
-
cd("..")
32
-
using SuiteSparseGraphBLAS
33
-
using Latexify
34
-
head = ["Semiring", "⊕", "⊗", "Types"]
35
-
v1 = filter((x) -> getproperty(Semirings, x) isa SuiteSparseGraphBLAS.AbstractSemiring, names(Semirings))
`mul[!]` is the only function which accepts semirings, and the best method to do so is a tuple of binary functions like `mul(A, B, (max, +))`. An operator form is also available as `*(min, +)(A, B)`.
16
+
17
+
Semiring objects may be constructed in a similar fashion: `Semiring(max, +)`.
0 commit comments