Level-3 Primitives

A collection of functions that allow GraphBLAS semirings to work on one or more two-dimensional sparse containers (i.e, sparse matrices). More...

Functions
template<Descriptor descr = descriptors::no_operation, class Monoid , typename OutputType , typename InputType1 , typename InputType2 , typename RIT1 , typename CIT1 , typename NIT1 , typename RIT2 , typename CIT2 , typename NIT2 , typename RIT3 , typename CIT3 , typename NIT3 , Backend backend>
RC	eWiseApply (Matrix< OutputType, backend, RIT1, CIT1, NIT1 > &C, const Matrix< InputType1, backend, RIT2, CIT2, NIT2 > &A, const Matrix< InputType2, backend, RIT3, CIT3, NIT3 > &B, const Monoid &monoid, const Phase phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Computes \( C = A \odot B \), out of place, monoid variant. More...
template<Descriptor descr = grb::descriptors::no_operation, class Operator , typename OutputType , typename InputType1 , typename InputType2 , typename RIT1 , typename CIT1 , typename NIT1 , typename RIT2 , typename CIT2 , typename NIT2 , typename RIT3 , typename CIT3 , typename NIT3 , Backend backend>
RC	eWiseApply (Matrix< OutputType, backend, RIT1, CIT1, NIT1 > &C, const Matrix< InputType1, backend, RIT2, CIT2, NIT2 > &A, const Matrix< InputType2, backend, RIT3, CIT3, NIT3 > &B, const Operator &op, const Phase phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< Operator >::value, void >::type *const =nullptr)
	Computes \( C = A \odot B \), out of place, operator variant. More...
template<Descriptor descr = descriptors::no_operation, typename OutputType , typename InputType1 , typename InputType2 , typename CIT1 , typename RIT1 , typename NIT1 , typename CIT2 , typename RIT2 , typename NIT2 , typename CIT3 , typename RIT3 , typename NIT3 , class Semiring , Backend backend>
RC	mxm (Matrix< OutputType, backend, CIT1, RIT1, NIT1 > &C, const Matrix< InputType1, backend, CIT2, RIT2, NIT2 > &A, const Matrix< InputType2, backend, CIT3, RIT3, NIT3 > &B, const Semiring &ring=Semiring(), const Phase &phase=EXECUTE)
	Unmasked and in-place sparse matrix–sparse matrix multiplication (SpMSpM), \( C += A+B \). More...
template<Descriptor descr = descriptors::no_operation, typename OutputType , typename InputType1 , typename InputType2 , typename InputType3 , typename RIT , typename CIT , typename NIT , Backend backend, typename Coords >
RC	zip (Matrix< OutputType, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Vector< InputType3, backend, Coords > &z, const Phase &phase=EXECUTE)
	The grb::zip merges three vectors into a matrix. More...
template<Descriptor descr = descriptors::no_operation, typename InputType1 , typename InputType2 , typename InputType3 , typename RIT , typename CIT , typename NIT , Backend backend, typename Coords >
RC	zip (Matrix< void, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Phase &phase=EXECUTE)
	Merges two vectors into a void matrix. More...

Detailed Description

A collection of functions that allow GraphBLAS semirings to work on one or more two-dimensional sparse containers (i.e, sparse matrices).

Function Documentation

eWiseApply() [1/2]

RC grb::eWiseApply	(	Matrix< OutputType, backend, RIT1, CIT1, NIT1 > &	C,
		const Matrix< InputType1, backend, RIT2, CIT2, NIT2 > &	A,
		const Matrix< InputType2, backend, RIT3, CIT3, NIT3 > &	B,
		const Monoid &	monoid,
		const Phase	phase = EXECUTE,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= nullptr
	)

Computes \( C = A \odot B \), out of place, monoid variant.

Calculates the element-wise operation on one scalar to elements of one matrix, \( C = A \odot B \), using the given monoid's operator. The input and output matrices must be of same dimension.

Any old entries of C will be removed after a successful call to this primitive; that is, this is an out-of-place primitive.

After a successful call to this primitive, the nonzero structure of C will match that of the union of A and B. An implementing backend may skip processing rows i and columns j that are not in the union of the nonzero structure of A and B.

Note

When applying element-wise operators on sparse matrices using semirings, there is a difference between interpreting missing values as an annihilating identity or as a neutral identity– intuitively, such identities are known as ‘zero’ or ‘one’, respectively. As a consequence, this functionality is provided by grb::eWiseApply depending on whether a monoid or operator is provided:

• grb::eWiseApply using monoids (neutral),
• grb::eWiseApply using operators (annihilating).

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Monoid	The monoid to use.
InputType1	The value type of the left-hand matrix.
InputType2	The value type of the right-hand matrix.
OutputType	The value type of the ouput matrix.

Parameters

[out]	C	The output matrix.
[in]	A	The left-hand input matrix.
[in]	B	The right-hand input matrix.
[in]	monoid	The monoid structure containing \( \odot \).
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Returns

grb::SUCCESS On successful completion of this call.

grb::MISMATCH Whenever the dimensions of x, y and z do not match. All input data containers are left untouched if this exit code is returned; it will be as though this call was never made.

grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output matrix z is cleared, and the call to this function has no further effects.

grb::OUTOFMEM If phase is grb::RESIZE, indicates an out-of-memory exception. The call to this function shall have no other effects beyond returning this error code; the previous state of z is retained.

grb::PANIC A general unmitigable error has been encountered. If returned, ALP enters an undefined state and the user program is encouraged to exit as quickly as possible.

Performance semantics

Each backend must define performance semantics for this primitive.

See also

Performance Semantics

eWiseApply() [2/2]

RC grb::eWiseApply	(	Matrix< OutputType, backend, RIT1, CIT1, NIT1 > &	C,
		const Matrix< InputType1, backend, RIT2, CIT2, NIT2 > &	A,
		const Matrix< InputType2, backend, RIT3, CIT3, NIT3 > &	B,
		const Operator &	op,
		const Phase	phase = EXECUTE,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< Operator >::value, void >::type * const	= nullptr
	)

Computes \( C = A \odot B \), out of place, operator variant.

Calculates the element-wise operation on one scalar to elements of one matrix, \( C = A \odot B \), using the given operator. The input and output matrices must be of same dimension.

Any old entries of C will be removed after a successful call to this primitive; that is, this primitive is out-of-place.

After a successful call to this primitive, the nonzero structure of C will match that of the intersection of A and B. An implementing backend may skip processing rows i and columns j that are not in the intersection of the nonzero structure of A and B.

Note

When applying element-wise operators on sparse matrices using semirings, there is a difference between interpreting missing values as an annihilating identity or as a neutral identity– intuitively, such identities are known as ‘zero’ or ‘one’, respectively. As a consequence, this functionality is provided by grb::eWiseApply depending on whether a monoid or operator is provided:

• grb::eWiseApply using monoids (neutral),
• grb::eWiseApply using operators (annihilating).

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Operator	The operator to use.
InputType1	The value type of the left-hand matrix.
InputType2	The value type of the right-hand matrix.
OutputType	The value type of the ouput matrix.

Parameters

[out]	C	The output matrix.
[in]	A	The left-hand input matrix.
[in]	B	The right-hand input matrix.
[in]	op	The operator.
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Returns

grb::SUCCESS On successful completion of this call.

grb::MISMATCH Whenever the dimensions of x, y and z do not match. All input data containers are left untouched if this exit code is returned; it will be be as though this call was never made.

grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output matrix z is cleared, and the call to this function has no further effects.

grb::OUTOFMEM If phase is grb::RESIZE, indicates an out-of-memory exception. The call to this function shall have no other effects beyond returning this error code; the previous state of z is retained.

grb::PANIC A general unmitigable error has been encountered. If returned, ALP enters an undefined state and the user program is encouraged to exit as quickly as possible.

Performance semantics

Each backend must define performance semantics for this primitive.

See also

Performance Semantics

mxm()

RC grb::mxm	(	Matrix< OutputType, backend, CIT1, RIT1, NIT1 > &	C,
		const Matrix< InputType1, backend, CIT2, RIT2, NIT2 > &	A,
		const Matrix< InputType2, backend, CIT3, RIT3, NIT3 > &	B,
		const Semiring &	ring = Semiring(),
		const Phase &	phase = EXECUTE
	)

Unmasked and in-place sparse matrix–sparse matrix multiplication (SpMSpM), \( C += A+B \).

Template Parameters

descr	The descriptors under which to perform the computation. Optional; default is grb::descriptors::no_operation.
OutputType	The type of elements in the output matrix.
InputType1	The type of elements in the left-hand side input matrix.
InputType2	The type of elements in the right-hand side input matrix.
Semiring	The semiring under which to perform the multiplication.

Parameters

[in,out]	C	The matrix into which the multiplication \( AB \) is accumulated.
[in]	A	The left-hand side input matrix \( A \).
[in]	B	The left-hand side input matrix \( B \).
[in]	ring	The semiring under which the computation should proceed.
[in]	phase	The grb::Phase the primitive should be executed with. This argument is optional; its default is grb::EXECUTE.

Returns

grb::SUCCESS If the computation completed as intended.

grb::FAILED If the capacity of C was insufficient to store the output of multiplying A and B. If this code is returned, C on output appears cleared.

grb::OUTOFMEM If phase is grb::RESIZE and an out-of-error condition arose while resizing C.

Note

This specification does not account for grb::TRY as that phase is still experimental. See its documentation for details.

Performance semantics

Each backend must define performance semantics for this primitive.

See also

Performance Semantics

zip() [1/2]

RC grb::zip	(	Matrix< OutputType, backend, RIT, CIT, NIT > &	A,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Vector< InputType3, backend, Coords > &	z,
		const Phase &	phase = EXECUTE
	)

The grb::zip merges three vectors into a matrix.

Interprets three input vectors x, y, and z as a series of row coordinates, column coordinates, and nonzeroes, respectively. The thus-defined nonzeroes of a matrix are then stored in a given output matrix A.

The vectors x, y, and z must have equal length, as well as the same number of nonzeroes. If the vectors are sparse, all vectors must have the same sparsity structure.

Note

A variant of this function only takes x and y, and has that the output matrix A has void element types.

If this function does not return grb::SUCCESS, the output \ a A will have no contents on function exit.

The matrix A must have been pre-allocated to store the nonzero pattern that the three given vectors x, y, and z encode, or otherwise this function returns grb::ILLEGAL.

Note

To ensure that the capacity of A is sufficient, a succesful call to grb::resize with grb::nnz of x suffices. Alternatively, and with the same effect, a succesful call to this function with phase equal to grb::RESIZE instead of grb::SUCCESS suffices also.

Parameters

[out]	A	The output matrix.
[in]	x	A vector of row indices.
[in]	y	A vector of column indices.
[in]	z	A vector of nonzero values.
[in]	phase	The grb::Phase in which the primitive is to proceed. Optional; the default is grb::EXECUTE.

Returns

grb::SUCCESS If A was constructed successfully.

grb::MISMATCH If y or z does not match the size of x.

grb::ILLEGAL If y or z do not have the same number of nonzeroes as x.

grb::ILLEGAL If y or z has a different sparsity pattern from x.

grb::FAILED If the capacity of A was insufficient to store the given sparsity pattern and phase is grb::EXECUTE.

grb::OUTOFMEM If the phase is grb::RESIZE and A could not be resized to have sufficient capacity to complete this function due to out-of-memory conditions.

Descriptors

None allowed.

Performance semantics

Each backend must define performance semantics for this primitive.

See also

Performance Semantics

zip() [2/2]

RC grb::zip	(	Matrix< void, backend, RIT, CIT, NIT > &	A,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Phase &	phase = EXECUTE
	)

Merges two vectors into a void matrix.

This is a specialisation of grb::zip for pattern matrices. The two input vectors x and y represent coordinates of nonzeroes to be stored in A.

Performance semantics

Each backend must define performance semantics for this primitive.

See also

Performance Semantics