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, typename OutputType , typename InputType1 , typename InputType2 , typename CIT , typename RIT , typename NIT , class Semiring , Backend backend>
RC	mxm (Matrix< OutputType, backend, CIT, RIT, NIT > &C, const Matrix< InputType1, backend, CIT, RIT, NIT > &A, const Matrix< InputType2, backend, CIT, RIT, NIT > &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

mxm()

RC grb::mxm	(	Matrix< OutputType, backend, CIT, RIT, NIT > &	C,
		const Matrix< InputType1, backend, CIT, RIT, NIT > &	A,
		const Matrix< InputType2, backend, CIT, RIT, NIT > &	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