ALP User Documentation 0.7.alpha
Algebraic Programming User Documentation
Loading...
Searching...
No Matches
Functions
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 \).
 
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.
 
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.
 

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 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
descrThe descriptors under which to perform the computation. Optional; default is grb::descriptors::no_operation.
OutputTypeThe type of elements in the output matrix.
InputType1The type of elements in the left-hand side input matrix.
InputType2The type of elements in the right-hand side input matrix.
SemiringThe semiring under which to perform the multiplication.
Parameters
[in,out]CThe matrix into which the multiplication \( AB \) is accumulated.
[in]AThe left-hand side input matrix \( A \).
[in]BThe left-hand side input matrix \( B \).
[in]ringThe semiring under which the computation should proceed.
[in]phaseThe 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 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]AThe output matrix.
[in]xA vector of row indices.
[in]yA vector of column indices.
[in]zA vector of nonzero values.
[in]phaseThe 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 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