udo docs

Author: Wimmerer

docs/make.jl

@@ -15,7 +15,8 @@ makedocs(
             "binaryops.md",
             "monoids.md",
             "semirings.md",
-            "selectops.md"
+            "selectops.md",
+            "udfs.md"
         ]
     ]
 )

docs/src/arrays.md

@@ -67,6 +67,16 @@ SparseMatrixCSC(A[:,:, desc=Descriptors.T0]) #Transpose the first argument
 
 All of this same functionality exists for vectors in 1-dimension.
 
+# Transpose
+The typical lazy Julia `transpose` is available as usual, and the adjoint operator `'` is also
+overloaded to be equivalent.
+
+`x = A'` will create a `Transpose` wrapper.
+When an operation uses this argument it will cause the `desc` to set `INP<0|1> = T_<0|1>`. 
+
+!!! warning
+    Vectors do not support transposition at this time. A matrix with the column or row size set to `1` may be a solution.
+
 # Utilities
 
 ```@docs

docs/src/index.md

@@ -6,7 +6,7 @@ It aims to provide a Julian wrapper over Tim Davis' SuiteSparse reference implem
 # Roadmap
 
 !!! note
-    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!
+    This library is still a WIP, if you are missing any functionality, find any incorrectly implemented functions, or need further/better documentation please open an issue, PR, or ask in the [#GraphBLAS channel on the Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/289264-GraphBLAS) (preferred) or the [#graphblas channel on the Julia Slack](https://julialang.slack.com/archives/C023B0WGMHR)!
 
 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:
 

docs/src/operations.md

@@ -32,7 +32,7 @@ The operations above have often accept most or all of the following arguments.
 
 ### `op` - `UnaryOp`, `BinaryOp`, `Monoid`, `Semiring`, or `SelectOp`:
 
-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`.
+This is the most important argument for most of the GraphBLAS operations. It determines ``\oplus``, ``\otimes``, or ``f`` in the table above as well as the semiring used in `mul`.
 Most operations are restricted to one type of operator.
 
 !!! tip "Built-Ins"

docs/src/udfs.md

@@ -0,0 +1,26 @@
+# User Defined Operators
+
+!!! warning "Experimental"
+    This is still a work in progress, and subject to change. Please open an issue if you find any problems!
+
+GraphBLAS supports users to supply functions as operators. Constructors exported are:
+
+- `UnaryOp(name::String, fn::Function, [type | types | ztype, xtype | ztypes, xtypes])`
+- `BinaryOp(name::String, fn::Function, [type | types | ztype, xtype | ztypes, xtypes])`
+- `Monoid(name::String, binop::Union{AbstractBinaryOp, GrB_BinaryOp}, id::T, terminal::T = nothing)`: all types must be the same.
+- `Semiring(name::String, add::[GrB_Monoid | AbstractMonoid], mul::[GrB_BinaryOp | AbstractBinaryOp])`
+
+`GrB_` prefixed arguments are typed operators, such as the result of `UnaryOps.COS[Float64]`.
+Type arguments may be single types or vectors of types.
+If no type is supplied to `UnaryOp` or `BinaryOp` they will default to constructing typed operators for all the built-in primitive types.
+
+The `fn` arguments to `UnaryOp` and `BinaryOp` must have one or two arguments respectively.
+
+!!! danger "Performance"
+    Due to the nature of the underlying C library user-defined operators may be significantly slower than their built-in counterparts.
+    When possible use the built-in operators, or combinations of them.
+
+!!! note "Where to Find User-Defined Operators"
+    The constructors for an operator add that operator to the submodule for that operator type.
+    For instance `UnaryOp(minus, -, Int64, Int64)` will add `UnaryOps.minus`.
+

src/operators/unaryops.jl

@@ -123,6 +123,7 @@ end
 
 #UnaryOp constructors
 #####################
+function UnaryOp end
 function UnaryOp(name::String, fn::Function, ztype, xtype)
     op = UnaryOp(name)
     _addunaryop(op, fn, toGBType(ztype), toGBType(xtype))

test/operations.jl

@@ -4,13 +4,13 @@
         n = GBMatrix([1,2,3,2], [1,2,2,1], [1,2,3,4])
         #eadd correctness
         @test eadd(m, n) == GBMatrix([1,1,2,2,3,3], [1,2,1,2,1,2], [2,4,6,7,3,9])
-        @test eadd(m, n; op = BinaryOps.GT)[1, 1] == 0
+        @test eadd(m, n, BinaryOps.GT)[1, 1] == 0
         #check that the (+) op is being picked up from the semiring.
-        @test eadd(m, n; op = Semirings.PLUS_MAX) == eadd(m, n; op = BinaryOps.PLUS)
+        @test eadd(m, n, Semirings.PLUS_MAX) == eadd(m, n, BinaryOps.PLUS)
         #emul correctness
-        @test emul(m, n; op = BinaryOps.POW)[3, 2] == m[3,2] ^ n[3,2]
+        @test emul(m, n, BinaryOps.POW)[3, 2] == m[3,2] ^ n[3,2]
         #check that the (*) op is being picked up from the semiring
-        @test emul(m, n; op = Semirings.MAX_PLUS) == emul(m, n; op = BinaryOps.PLUS)
+        @test emul(m, n, Semirings.MAX_PLUS) == emul(m, n, BinaryOps.PLUS)
     end
     @testset "kron" begin
         m1 = GBMatrix(UInt64[1, 2, 3, 5], UInt64[1, 3, 1, 2], Int8[1, 2, 3, 5])
@@ -68,7 +68,7 @@
         m = GBMatrix([[1,2,3] [4,5,6] [7,8,9]])
         s = select(SelectOps.TRIL, m)
         @test s[1,2] === nothing && s[3,1] == 3
-        s = select(SelectOps.LT_THUNK, m, 6)
+        s = select(SelectOps.LT, m, 6)
         @test s[2,2] == 5 && s[3,3] === nothing
     end
     @testset "transpose" begin