Skip to content

Commit c1374c6

Browse files
author
Wimmerer
committed
Removed early getoperators
1 parent 1d5f59f commit c1374c6

File tree

4 files changed

+119
-13
lines changed

4 files changed

+119
-13
lines changed

‎docs/src/index.md

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ Post 1.0 goals include:
2424
3. More efficient import and export between Julia and GraphBLAS
2525
4. Support for other GraphBLAS implementations in a follow-up GraphBLAS.jl
2626

27-
!!! warning Printing
27+
!!! danger "Printing"
28+
2829
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.
2930

3031
# Installation
@@ -106,8 +107,114 @@ v = GBVector([4], [10])
106107
A complete list of supported operations can be found in [Operations](@ref).
107108
GraphBLAS operations are, where possible, wrapped in existing Julia functions. The equivalent Julia functions are:
108109

109-
| GraphBLAS | Operation | Julia |
110-
|---------------|------------------------------------------|-----------|
111-
| mxm, mxv, vxm | ``\bf C \langle M \rangle = C \odot AB`` | mul!, mul |
112-
| | | |
113-
| | | |
110+
| GraphBLAS | Operation | Julia |
111+
|:--------------------|:----------------------------------------: |----------: |
112+
|`mxm`, `mxv`, `vxm` |``\bf C \langle M \rangle = C \odot AB`` |`mul[!]` |
113+
|`eWiseMult` |``\bf C \langle M \rangle = C \odot (A \otimes B)`` |`emul[!]` |
114+
|`eWiseAdd` |``\bf C \langle M \rangle = C \odot (A \oplus B)`` |`eadd[!]` |
115+
|`extract` |``\bf C \langle M \rangle = C \odot A(I,J)`` |`extract[!]`, `getindex` |
116+
|`subassign` |``\bf C (I,J) \langle M \rangle = C(I,J) \odot A`` |`subassign[!]`, `setindex!` |
117+
|`assign` |``\bf C \langle M \rangle (I,J) = C(I,J) \odot A`` |`assign[!]` |
118+
|`apply` |``{\bf C \langle M \rangle = C \odot} f{\bf (A)}`` |`map[!]` |
119+
| |``{\bf C \langle M \rangle = C \odot} f({\bf A},y)`` | |
120+
| |``{\bf C \langle M \rangle = C \odot} f(x,{\bf A})`` | |
121+
|`select` |``{\bf C \langle M \rangle = C \odot} f({\bf A},k)`` |`select[!]` |
122+
|`reduce` |``{\bf w \langle m \rangle = w \odot} [{\oplus}_j {\bf A}(:,j)]`` |`reduce[!]` |
123+
| |``s = s \odot [{\oplus}_{ij} {\bf A}(i,j)]`` | |
124+
|`transpose` |``\bf C \langle M \rangle = C \odot A^{\sf T}`` |`gbtranspose[!]`, lazy: `transpose`, `'` |
125+
|`kronecker` |``\bf C \langle M \rangle = C \odot \text{kron}(A, B)`` |`kron[!]` |
126+
127+
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.
128+
129+
!!! note "assign vs subassign"
130+
131+
`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`.
132+
133+
### Common arguments
134+
135+
The operations above have a typical set of common arguments. These are:
136+
137+
#### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, or `Semiring`:
138+
139+
This is the key argument to most of these operations, which determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
140+
Most operations are restricted to one type of operator.
141+
142+
!!! warning "Keyword vs Positional"
143+
For some operations like `mul` and `emul` this is a keyword argument which defaults to the typical arithmetic operators.
144+
For others like `map` this is the first argument, since there is no sensible default choice.
145+
146+
147+
148+
!!! tip "Built-Ins"
149+
The built-in operators can be found in the submodules: `UnaryOps`, `BinaryOps`, `Monoids`, and `Semirings`.
150+
151+
#### `desc` - `Descriptor`:
152+
153+
The descriptor argument allows the user to modify the operation in some fashion. The most common options are:
154+
155+
- `desc.[input1 | input2] == [DEFAULT | TRANSPOSE]`
156+
157+
Transposes the inputs and can be found in `Descriptors.[T0 | T1 | T0T1]`.
158+
Typically you should use Julia's built-in transpose functionality.
159+
160+
- `desc.mask == [DEFAULT | STRUCTURE | COMPLEMENT | STRUCTURE + COMPLEMENT]`
161+
162+
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.
163+
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).
164+
165+
- `desc.output` == [DEFAULT | REPLACE]
166+
167+
If `REPLACE` is set the operation will replace all values in the output matrix **after** the accumulation step.
168+
If an index is found in the output matrix, but not in the results of the operation it will be set to `nothing`.
169+
170+
171+
#### `accum` - `BinaryOp`:
172+
173+
The `accum` keyword argument provides a binary operation to accumulate results into the result array.
174+
The accumulation step is performed **before** masking.
175+
176+
#### `mask` - `GBArray`:
177+
178+
The `mask` keyword argument determines whether each index from the result of an operation appears in the output.
179+
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.
180+
The mask may also be complemented.
181+
182+
183+
### Order of Operations
184+
185+
A GraphBLAS operation occurs in the following order (steps are skipped when possible):
186+
187+
1. Calculate `T = <operation>(args...)`
188+
2. Elementwise accumulate `Z[i,j] = accum(C[i,j], T[i,j])`
189+
3. Optionally masked assignment `C[i,j] = mask[i,j] ? Z[i,j] : [nothing | C[i,j]]`
190+
191+
If `REPLACE` is set the option in step 3. is `nothing`, otherwise it is `C[i,j]`.
192+
193+
## GraphBLAS Operators
194+
195+
GraphBLAS operators are one of the following:
196+
197+
- `UnaryOps` such as `SIN`, `SQRT`, `ABS`, ...
198+
- `BinaryOps` such as `GE`, `MAX`, `POW`, `FIRSTJ`, ...
199+
- `Monoids` such as `PLUS_MONOID`, `LXOR_MONOID`, ...
200+
- `Semirings` such as `PLUS_TIMES` (the arithmetic semiring), `MAX_PLUS` (a tropical semiring), `PLUS_PLUS`, ...
201+
202+
Built-in operators can be found in exported submodules:
203+
204+
```julia
205+
julia> BinaryOps.
206+
207+
ANY BSET DIV FIRSTJ1 ISGE LDEXP MIN RDIV SECONDJ
208+
ATAN2 BSHIFT EQ FMOD ISGT LE MINUS REMAINDER SECONDJ1
209+
BAND BXNOR FIRST GE ISLE LOR NE RMINUS TIMES
210+
BCLR BXOR FIRSTI GT ISLT LT PAIR SECOND
211+
BGET CMPLX FIRSTI1 HYPOT ISNE LXOR PLUS SECONDI
212+
BOR COPYSIGN FIRSTJ ISEQ LAND MAX POW SECONDI1
213+
```
214+
215+
## Example
216+
217+
218+
219+
```julia
220+
```

‎src/operations/kronecker.jl

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
function LinearAlgebra.kron!(C::GBMatOrTranspose,
1+
function LinearAlgebra.kron!(
2+
C::GBMatOrTranspose,
23
A::GBMatOrTranspose,
34
B::GBMatOrTranspose;
45
op::MonoidBinaryOrRig = BinaryOps.TIMES,
@@ -26,8 +27,7 @@ function LinearAlgebra.kron(
2627
accum = C_NULL,
2728
desc::Descriptor = Descriptors.NULL
2829
)
29-
op = getoperator(op, optype(A, B))
30-
t = tojuliatype(ztype(op))
30+
t = optype(A, B)
3131
C = GBMatrix{t}(size(A,1) * size(B, 1), size(A, 2) * size(B, 2))
3232
kron!(C, A, B; op, mask, accum, desc)
3333
return C

‎src/operations/mul.jl

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,7 @@ function mul(
8686
accum = C_NULL,
8787
desc::Descriptor = Descriptors.NULL
8888
)
89-
op = getoperator(op, optype(A, B))
90-
t = tojuliatype(ztype(op))
89+
t = optype(A, B)
9190
if A isa GBVector && B isa GBMatOrTranspose
9291
C = GBVector{t}(size(B, 2))
9392
elseif A isa GBMatOrTranspose && B isa GBVector

‎src/operations/reduce.jl

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ function Base.reduce(
7272
end
7373

7474
function Base.reduce(
75-
op::BinaryUnion,
76-
A::GBArray;
75+
::BinaryUnion,
76+
::GBArray;
7777
dims = 2,
7878
typeout = nothing,
7979
init = nothing,

0 commit comments

Comments
 (0)