1 //------------------------------------------------------------------------------
2 // GrB_Semiring_new: create a new semiring
3 //------------------------------------------------------------------------------
4
5 // SuiteSparse:GraphBLAS, Timothy A. Davis, (c) 2017-2021, All Rights Reserved.
6 // SPDX-License-Identifier: Apache-2.0
7
8 //------------------------------------------------------------------------------
9
10 // A GraphBLAS Semiring consists of two components: "add" and "multiply".
11 // These components imply three domains: ztype, xtype, and ytype.
12
13 // The "add" is an associative and commutative monoid, which is a binary
14 // operator that works on a single type, ztype = add(ztype,ztype). The add
15 // monoid also includes an identity value, called "zero", so that
16 // add(x,zero)=add(zero,x)=x. For most algebras, this "zero" is a plain zero
17 // in the usual sense, but this is not the case for all algebras. For example,
18 // for the max-plus algebra, the "add" operator is the function max(a,b), and
19 // the "zero" for this operator is -infinity since max(a,-inf)=max(-inf,a)=a.
20
21 // The "multiply" is a binary operator z = multiply(x,y). It has no
22 // restrictions, except that the type of z must exactly match the ztype
23 // of the add monoid. That is, the types for the multiply operator are
24 // ztype = multiply (xtype, ytype). When the semiring is applied to two
25 // matrices A and B, where (A,B) appear in that order in the method, the
26 // multiply operator is always applied as z = multiply (A(i,j),B(i,j)). The
27 // two input operands always appear in that order. That is, the multiply
28 // operator is not assumed to be commutative.
29
30 #include "GB.h"
31
32 #define GB_FREE_ALL \
33 { \
34 GB_FREE (semiring, header_size) ; \
35 }
36
GrB_Semiring_new(GrB_Semiring * semiring,GrB_Monoid add,GrB_BinaryOp multiply)37 GrB_Info GrB_Semiring_new // create a semiring
38 (
39 GrB_Semiring *semiring, // handle of semiring to create
40 GrB_Monoid add, // additive monoid of the semiring
41 GrB_BinaryOp multiply // multiply operator of the semiring
42 )
43 {
44
45 //--------------------------------------------------------------------------
46 // check inputs
47 //--------------------------------------------------------------------------
48
49 GrB_Info info ;
50 GB_WHERE1 ("GrB_Semiring_new (&semiring, add, multiply)") ;
51 GB_RETURN_IF_NULL (semiring) ;
52 (*semiring) = NULL ;
53 GB_RETURN_IF_NULL_OR_FAULTY (add) ;
54 GB_RETURN_IF_NULL_OR_FAULTY (multiply) ;
55 ASSERT_MONOID_OK (add, "semiring->add", GB0) ;
56 ASSERT_BINARYOP_OK (multiply, "semiring->multiply", GB0) ;
57
58 //--------------------------------------------------------------------------
59 // allocate the semiring
60 //--------------------------------------------------------------------------
61
62 size_t header_size ;
63 (*semiring) = GB_MALLOC (1, struct GB_Semiring_opaque, &header_size) ;
64 if (*semiring == NULL)
65 {
66 // out of memory
67 return (GrB_OUT_OF_MEMORY) ;
68 }
69 (*semiring)->header_size = header_size ;
70
71 //--------------------------------------------------------------------------
72 // create the semiring
73 //--------------------------------------------------------------------------
74
75 GB_OK (GB_Semiring_new (*semiring, add, multiply)) ;
76 return (GrB_SUCCESS) ;
77 }
78
79