Skip to content

Commit 8e130fb

Browse files
abhinavmehndirattaabhinavmehndiratta
committed
add documetation for element wise addition operations
1 parent 5dc4c22 commit 8e130fb

File tree

1 file changed

+317
-6
lines changed

1 file changed

+317
-6
lines changed

‎src/Operations/Element_wise_addition.jl

Lines changed: 317 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
1+
"""
2+
GrB_eWiseAdd(C, mask, accum, op, A, B, desc)
3+
4+
Generic method for element-wise matrix and vector operations: using set union.
5+
6+
GrB_eWiseAdd computes C<Mask> = accum (C, A+B), where pairs of elements in two matrices (or two vectors)
7+
are pairwise "added". The "add" operator can be any binary operator. With the plus operator,
8+
this is the same matrix addition in conventional linear algebra. The pattern of the result T=A+B is
9+
the set union of A and B. Entries outside of the union are not computed. That is, if both A(i,j) and B(i,j)
10+
are present in the pattern of A and B, then T(i,j) = A(i,j) "+" B(i,j). If only A(i,j) is present
11+
then T(i,j) = A (i,j) and the "+" operator is not used. Likewise, if only B(i,j) is in the pattern of B
12+
but A(i,j) is not in the pattern of A, then T(i,j) = B(i,j). For a semiring, the mult operator is the
13+
semiring's add operator.
14+
"""
115
function GrB_eWiseAdd(C::T, mask::V, accum::W, op::U, A::T, B::T,
2-
desc::X) where {T <: Union{GrB_Vector, GrB_Matrix}, U <: Union{GrB_BinaryOp, GrB_Monoid, GrB_Semiring},
16+
desc::X) where {T <: Union{GrB_Vector, GrB_Matrix}, U <: Union{GrB_BinaryOp, GrB_Monoid, GrB_Semiring},
317
V <: Union{GrB_Vector, GrB_Matrix, GrB_NULL_Type}, W <: valid_accum_types, X <: valid_desc_types}
418

519
T_name = get_struct_name(A)
@@ -17,6 +31,54 @@ function GrB_eWiseAdd(C::T, mask::V, accum::W, op::U, A::T, B::T,
1731
)
1832
end
1933

34+
"""
35+
GrB_eWiseAdd_Vector_Semiring(w, mask, accum, semiring, u, v, desc)
36+
37+
Compute element-wise vector addition using semiring. Semiring's add operator is used.
38+
w<mask> = accum (w, u+v)
39+
40+
# Examples
41+
```jldoctest
42+
julia> using SuiteSparseGraphBLAS
43+
44+
julia> GrB_init(GrB_NONBLOCKING)
45+
GrB_SUCCESS::GrB_Info = 0
46+
47+
julia> u = GrB_Vector{Int64}()
48+
GrB_Vector{Int64}
49+
50+
julia> GrB_Vector_new(u, GrB_INT64, 5)
51+
GrB_SUCCESS::GrB_Info = 0
52+
53+
julia> I1 = [0, 2, 4]; X1 = [10, 20, 3]; n1 = 3;
54+
55+
julia> GrB_Vector_build(u, I1, X1, n1, GrB_FIRST_INT64)
56+
GrB_SUCCESS::GrB_Info = 0
57+
58+
julia> v = GrB_Vector{Float64}()
59+
GrB_Vector{Float64}
60+
61+
julia> GrB_Vector_new(v, GrB_FP64, 5)
62+
GrB_SUCCESS::GrB_Info = 0
63+
64+
julia> I2 = [0, 1, 4]; X2 = [1.1, 2.2, 3.3]; n2 = 3;
65+
66+
julia> GrB_Vector_build(v, I2, X2, n2, GrB_FIRST_FP64)
67+
GrB_SUCCESS::GrB_Info = 0
68+
69+
julia> w = GrB_Vector{Float64}()
70+
GrB_Vector{Float64}
71+
72+
julia> GrB_Vector_new(w, GrB_FP64, 5)
73+
GrB_SUCCESS::GrB_Info = 0
74+
75+
julia> GrB_eWiseAdd_Vector_Semiring(w, GrB_NULL, GrB_NULL, GxB_PLUS_TIMES_FP64, u, v, GrB_NULL)
76+
GrB_SUCCESS::GrB_Info = 0
77+
78+
julia> GrB_Vector_extractTuples(w)
79+
([0, 1, 2, 4], [11.1, 2.2, 20.0, 6.3])
80+
```
81+
"""
2082
function GrB_eWiseAdd_Vector_Semiring( # w<Mask> = accum (w, u+v)
2183
w::GrB_Vector, # input/output vector for results
2284
mask::T, # optional mask for w, unused if NULL
@@ -37,6 +99,54 @@ function GrB_eWiseAdd_Vector_Semiring( # w<Mask> = accum (w, u+v)
3799
)
38100
end
39101

102+
"""
103+
GrB_eWiseAdd_Vector_Monoid(w, mask, accum, monoid, u, v, desc)
104+
105+
Compute element-wise vector addition using monoid.
106+
w<mask> = accum (w, u+v)
107+
108+
# Examples
109+
```jldoctest
110+
julia> using SuiteSparseGraphBLAS
111+
112+
julia> GrB_init(GrB_NONBLOCKING)
113+
GrB_SUCCESS::GrB_Info = 0
114+
115+
julia> u = GrB_Vector{Int64}()
116+
GrB_Vector{Int64}
117+
118+
julia> GrB_Vector_new(u, GrB_INT64, 5)
119+
GrB_SUCCESS::GrB_Info = 0
120+
121+
julia> I1 = [0, 2, 4]; X1 = [10, 20, 3]; n1 = 3;
122+
123+
julia> GrB_Vector_build(u, I1, X1, n1, GrB_FIRST_INT64)
124+
GrB_SUCCESS::GrB_Info = 0
125+
126+
julia> v = GrB_Vector{Float64}()
127+
GrB_Vector{Float64}
128+
129+
julia> GrB_Vector_new(v, GrB_FP64, 5)
130+
GrB_SUCCESS::GrB_Info = 0
131+
132+
julia> I2 = [0, 1, 4]; X2 = [1.1, 2.2, 3.3]; n2 = 3;
133+
134+
julia> GrB_Vector_build(v, I2, X2, n2, GrB_FIRST_FP64)
135+
GrB_SUCCESS::GrB_Info = 0
136+
137+
julia> w = GrB_Vector{Float64}()
138+
GrB_Vector{Float64}
139+
140+
julia> GrB_Vector_new(w, GrB_FP64, 5)
141+
GrB_SUCCESS::GrB_Info = 0
142+
143+
julia> GrB_eWiseAdd_Vector_Monoid(w, GrB_NULL, GrB_NULL, GxB_MAX_FP64_MONOID, u, v, GrB_NULL)
144+
GrB_SUCCESS::GrB_Info = 0
145+
146+
julia> GrB_Vector_extractTuples(w)
147+
([0, 1, 2, 4], [10.0, 2.2, 20.0, 3.3])
148+
```
149+
"""
40150
function GrB_eWiseAdd_Vector_Monoid( # w<Mask> = accum (w, u+v)
41151
w::GrB_Vector, # input/output vector for results
42152
mask::T, # optional mask for w, unused if NULL
@@ -52,16 +162,64 @@ function GrB_eWiseAdd_Vector_Monoid( # w<Mask> = accum (w, u+v)
52162
dlsym(graphblas_lib, "GrB_eWiseAdd_Vector_Monoid"),
53163
Cint,
54164
(Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}),
55-
w.p, mask.p, accum.p, monoic.p, u.p, v.p, desc.p
165+
w.p, mask.p, accum.p, monoid.p, u.p, v.p, desc.p
56166
)
57167
)
58168
end
59169

170+
"""
171+
GrB_eWiseAdd_Vector_BinaryOp(w, mask, accum, add, u, v, desc)
172+
173+
Compute element-wise vector addition using binary operator.
174+
w<mask> = accum (w, u+v)
175+
176+
# Examples
177+
```jldoctest
178+
julia> using SuiteSparseGraphBLAS
179+
180+
julia> GrB_init(GrB_NONBLOCKING)
181+
GrB_SUCCESS::GrB_Info = 0
182+
183+
julia> u = GrB_Vector{Int64}()
184+
GrB_Vector{Int64}
185+
186+
julia> GrB_Vector_new(u, GrB_INT64, 5)
187+
GrB_SUCCESS::GrB_Info = 0
188+
189+
julia> I1 = [0, 2, 4]; X1 = [10, 20, 3]; n1 = 3;
190+
191+
julia> GrB_Vector_build(u, I1, X1, n1, GrB_FIRST_INT64)
192+
GrB_SUCCESS::GrB_Info = 0
193+
194+
julia> v = GrB_Vector{Float64}()
195+
GrB_Vector{Float64}
196+
197+
julia> GrB_Vector_new(v, GrB_FP64, 5)
198+
GrB_SUCCESS::GrB_Info = 0
199+
200+
julia> I2 = [0, 1, 4]; X2 = [1.1, 2.2, 3.3]; n2 = 3;
201+
202+
julia> GrB_Vector_build(v, I2, X2, n2, GrB_FIRST_FP64)
203+
GrB_SUCCESS::GrB_Info = 0
204+
205+
julia> w = GrB_Vector{Float64}()
206+
GrB_Vector{Float64}
207+
208+
julia> GrB_Vector_new(w, GrB_FP64, 5)
209+
GrB_SUCCESS::GrB_Info = 0
210+
211+
julia> GrB_eWiseAdd_Vector_BinaryOp(w, GrB_NULL, GrB_NULL, GrB_PLUS_FP64, u, v, GrB_NULL)
212+
GrB_SUCCESS::GrB_Info = 0
213+
214+
julia> GrB_Vector_extractTuples(w)
215+
([0, 1, 2, 4], [11.1, 2.2, 20.0, 6.3])
216+
```
217+
"""
60218
function GrB_eWiseAdd_Vector_BinaryOp( # w<Mask> = accum (w, u+v)
61219
w::GrB_Vector, # input/output vector for results
62220
mask::T, # optional mask for w, unused if NULL
63221
accum::U, # optional accum for z=accum(w,t)
64-
mult::GrB_BinaryOp, # defines '+' for t=u+v
222+
add::GrB_BinaryOp, # defines '+' for t=u+v
65223
u::GrB_Vector, # first input: vector u
66224
v::GrB_Vector, # second input: vector v
67225
desc::V # descriptor for w and mask
@@ -72,11 +230,68 @@ function GrB_eWiseAdd_Vector_BinaryOp( # w<Mask> = accum (w, u+v)
72230
dlsym(graphblas_lib, "GrB_eWiseAdd_Vector_BinaryOp"),
73231
Cint,
74232
(Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}),
75-
w.p, mask.p, accum.p, mult.p, u.p, v.p, desc.p
233+
w.p, mask.p, accum.p, add.p, u.p, v.p, desc.p
76234
)
77235
)
78236
end
79237

238+
"""
239+
GrB_eWiseAdd_Matrix_Semiring(C, Mask, accum, semiring, A, B, desc)
240+
241+
Compute element-wise matrix addition using semiring. Semiring's add operator is used.
242+
C<Mask> = accum (C, A+B)
243+
244+
# Examples
245+
```jldoctest
246+
julia> using SuiteSparseGraphBLAS
247+
248+
julia> GrB_init(GrB_NONBLOCKING)
249+
GrB_SUCCESS::GrB_Info = 0
250+
251+
julia> A = GrB_Matrix{Int64}()
252+
GrB_Matrix{Int64}
253+
254+
julia> GrB_Matrix_new(A, GrB_INT64, 4, 4)
255+
GrB_SUCCESS::GrB_Info = 0
256+
257+
julia> I1 = [0, 0, 2, 2]; J1 = [1, 2, 0, 2]; X1 = [10, 20, 30, 40]; n1 = 4;
258+
259+
julia> GrB_Matrix_build(A, I1, J1, X1, n1, GrB_FIRST_INT64)
260+
GrB_SUCCESS::GrB_Info = 0
261+
262+
julia> B = GrB_Matrix{Int64}()
263+
GrB_Matrix{Int64}
264+
265+
julia> GrB_Matrix_new(B, GrB_INT64, 4, 4)
266+
GrB_SUCCESS::GrB_Info = 0
267+
268+
julia> I2 = [0, 0, 2]; J2 = [3, 2, 0]; X2 = [15, 16, 17]; n2 = 3;
269+
270+
julia> GrB_Matrix_build(B, I2, J2, X2, n2, GrB_FIRST_INT64)
271+
GrB_SUCCESS::GrB_Info = 0
272+
273+
julia> C = GrB_Matrix{Int64}()
274+
GrB_Matrix{Int64}
275+
276+
julia> GrB_Matrix_new(C, GrB_INT64, 4, 4)
277+
GrB_SUCCESS::GrB_Info = 0
278+
279+
julia> mask = GrB_Matrix{Bool}()
280+
GrB_Matrix{Bool}
281+
282+
julia> GrB_Matrix_new(mask, GrB_BOOL, 4, 4)
283+
GrB_SUCCESS::GrB_Info = 0
284+
285+
julia> GrB_Matrix_build(mask, [0, 0], [1, 2], [true, true], 2, GrB_FIRST_BOOL)
286+
GrB_SUCCESS::GrB_Info = 0
287+
288+
julia> GrB_eWiseAdd_Matrix_Monoid(C, mask, GrB_NULL, GxB_PLUS_INT64_MONOID, A, B, GrB_NULL)
289+
GrB_SUCCESS::GrB_Info = 0
290+
291+
julia> GrB_Matrix_extractTuples(C)
292+
([0, 0], [1, 2], [10, 36])
293+
```
294+
"""
80295
function GrB_eWiseAdd_Matrix_Semiring( # C<Mask> = accum (C, A+B)
81296
C::GrB_Matrix, # input/output matrix for results
82297
Mask::T, # optional mask for C, unused if NULL
@@ -97,6 +312,54 @@ function GrB_eWiseAdd_Matrix_Semiring( # C<Mask> = accum (C, A+B)
97312
)
98313
end
99314

315+
"""
316+
GrB_eWiseAdd_Matrix_Monoid(C, Mask, accum, monoid, A, B, desc)
317+
318+
Compute element-wise matrix addition using monoid.
319+
C<Mask> = accum (C, A+B)
320+
321+
# Examples
322+
```jldoctest
323+
julia> using SuiteSparseGraphBLAS
324+
325+
julia> GrB_init(GrB_NONBLOCKING)
326+
GrB_SUCCESS::GrB_Info = 0
327+
328+
julia> A = GrB_Matrix{Int64}()
329+
GrB_Matrix{Int64}
330+
331+
julia> GrB_Matrix_new(A, GrB_INT64, 4, 4)
332+
GrB_SUCCESS::GrB_Info = 0
333+
334+
julia> I1 = [0, 0, 2, 2]; J1 = [1, 2, 0, 2]; X1 = [10, 20, 30, 40]; n1 = 4;
335+
336+
julia> GrB_Matrix_build(A, I1, J1, X1, n1, GrB_FIRST_INT64)
337+
GrB_SUCCESS::GrB_Info = 0
338+
339+
julia> B = GrB_Matrix{Int64}()
340+
GrB_Matrix{Int64}
341+
342+
julia> GrB_Matrix_new(B, GrB_INT64, 4, 4)
343+
GrB_SUCCESS::GrB_Info = 0
344+
345+
julia> I2 = [0, 0, 2]; J2 = [3, 2, 0]; X2 = [15, 16, 17]; n2 = 3;
346+
347+
julia> GrB_Matrix_build(B, I2, J2, X2, n2, GrB_FIRST_INT64)
348+
GrB_SUCCESS::GrB_Info = 0
349+
350+
julia> C = GrB_Matrix{Int64}()
351+
GrB_Matrix{Int64}
352+
353+
julia> GrB_Matrix_new(C, GrB_INT64, 4, 4)
354+
GrB_SUCCESS::GrB_Info = 0
355+
356+
julia> GrB_eWiseAdd_Matrix_Monoid(C, GrB_NULL, GrB_NULL, GxB_PLUS_INT64_MONOID, A, B, GrB_NULL)
357+
GrB_SUCCESS::GrB_Info = 0
358+
359+
julia> GrB_Matrix_extractTuples(C)
360+
([0, 0, 0, 2, 2], [1, 2, 3, 0, 2], [10, 36, 15, 47, 40])
361+
```
362+
"""
100363
function GrB_eWiseAdd_Matrix_Monoid( # C<Mask> = accum (C, A+B)
101364
C::GrB_Matrix, # input/output matrix for results
102365
Mask::T, # optional mask for C, unused if NULL
@@ -117,11 +380,59 @@ function GrB_eWiseAdd_Matrix_Monoid( # C<Mask> = accum (C, A+B)
117380
)
118381
end
119382

383+
"""
384+
GrB_eWiseAdd_Matrix_BinaryOp(C, Mask, accum, add, A, B, desc)
385+
386+
Compute element-wise matrix addition using binary operator.
387+
C<Mask> = accum (C, A+B)
388+
389+
# Examples
390+
```jldoctest
391+
julia> using SuiteSparseGraphBLAS
392+
393+
julia> GrB_init(GrB_NONBLOCKING)
394+
GrB_SUCCESS::GrB_Info = 0
395+
396+
julia> A = GrB_Matrix{Int64}()
397+
GrB_Matrix{Int64}
398+
399+
julia> GrB_Matrix_new(A, GrB_INT64, 4, 4)
400+
GrB_SUCCESS::GrB_Info = 0
401+
402+
julia> I1 = [0, 0, 2, 2]; J1 = [1, 2, 0, 2]; X1 = [10, 20, 30, 40]; n1 = 4;
403+
404+
julia> GrB_Matrix_build(A, I1, J1, X1, n1, GrB_FIRST_INT64)
405+
GrB_SUCCESS::GrB_Info = 0
406+
407+
julia> B = GrB_Matrix{Int64}()
408+
GrB_Matrix{Int64}
409+
410+
julia> GrB_Matrix_new(B, GrB_INT64, 4, 4)
411+
GrB_SUCCESS::GrB_Info = 0
412+
413+
julia> I2 = [0, 0, 2]; J2 = [3, 2, 0]; X2 = [15, 16, 17]; n2 = 3;
414+
415+
julia> GrB_Matrix_build(B, I2, J2, X2, n2, GrB_FIRST_INT64)
416+
GrB_SUCCESS::GrB_Info = 0
417+
418+
julia> C = GrB_Matrix{Int64}()
419+
GrB_Matrix{Int64}
420+
421+
julia> GrB_Matrix_new(C, GrB_INT64, 4, 4)
422+
GrB_SUCCESS::GrB_Info = 0
423+
424+
julia> GrB_eWiseAdd_Matrix_BinaryOp(C, GrB_NULL, GrB_NULL, GrB_PLUS_INT64, A, B, GrB_NULL)
425+
GrB_SUCCESS::GrB_Info = 0
426+
427+
julia> GrB_Matrix_extractTuples(C)
428+
([0, 0, 0, 2, 2], [1, 2, 3, 0, 2], [10, 36, 15, 47, 40])
429+
```
430+
"""
120431
function GrB_eWiseAdd_Matrix_BinaryOp( # C<Mask> = accum (C, A+B)
121432
C::GrB_Matrix, # input/output matrix for results
122433
Mask::T, # optional mask for C, unused if NULL
123434
accum::U, # optional accum for Z=accum(C,T)
124-
mult::GrB_BinaryOp, # defines '+' for T=A+B
435+
add::GrB_BinaryOp, # defines '+' for T=A+B
125436
A::GrB_Matrix, # first input: matrix A
126437
B::GrB_Matrix, # second input: matrix B
127438
desc::V # descriptor for C, Mask, A, and B
@@ -132,7 +443,7 @@ function GrB_eWiseAdd_Matrix_BinaryOp( # C<Mask> = accum (C, A+B)
132443
dlsym(graphblas_lib, "GrB_eWiseAdd_Matrix_BinaryOp"),
133444
Cint,
134445
(Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}, Ptr{Cvoid}),
135-
C.p, Mask.p, accum.p, mult.p, A.p, B.p, desc.p
446+
C.p, Mask.p, accum.p, add.p, A.p, B.p, desc.p
136447
)
137448
)
138449
end

0 commit comments

Comments
 (0)