A collection of functions that allow GraphBLAS operators, monoids, and semirings work on a mix of zero-dimensional, one-dimensional, and two-dimensional containers. More...

Functions
template<typename Func , typename DataType , typename RIT , typename CIT , typename NIT , Backend implementation = config::default_backend, typename... Args>
RC	eWiseLambda (const Func f, const Matrix< DataType, implementation, RIT, CIT, NIT > &A, Args...)
	Executes an arbitrary element-wise user-defined function f on all nonzero elements of a given matrix A. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	mxv (Vector< IOType, backend, Coords > &u, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &v, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type *const =nullptr)
	Right-handed in-place sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename InputType4 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	mxv (Vector< IOType, backend, Coords > &u, const Vector< InputType3, backend, Coords > &mask, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &v, const Vector< InputType4, backend, Coords > &v_mask, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!std::is_same< InputType2, void >::value, void >::type *const =nullptr)
	Right-handed in-place doubly-masked sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	mxv (Vector< IOType, backend, Coords > &u, const Vector< InputType3, backend, Coords > &mask, const Matrix< InputType2, backend, RIT, NIT, CIT > &A, const Vector< InputType1, backend, Coords > &v, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!std::is_same< InputType2, void >::value, void >::type *const =nullptr)
	Right-handed in-place masked sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class Semiring , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename InputType4 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	mxv (Vector< IOType, backend, Coords > &u, const Vector< InputType3, backend, Coords > &u_mask, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &v, const Vector< InputType4, backend, Coords > &v_mask, const Semiring &semiring=Semiring(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_semiring< Semiring >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value, void >::type *const =nullptr)
	Right-handed in-place doubly-masked sparse matrix times vector multiplication, \( u = u + Av \). More...

template<Descriptor descr = descriptors::no_operation, class Ring , typename IOType , typename InputType1 , typename InputType2 , typename Coords , typename RIT , typename CIT , typename NIT , Backend implementation = config::default_backend>
RC	mxv (Vector< IOType, implementation, Coords > &u, const Matrix< InputType2, implementation, RIT, CIT, NIT > &A, const Vector< InputType1, implementation, Coords > &v, const Ring &ring, typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *=nullptr)
	Right-handed in-place sparse matrix–vector multiplication, \( u = u + Av \), over a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename RIT , typename CIT , typename NIT , typename Coords , enum Backend implementation = config::default_backend>
RC	mxv (Vector< IOType, implementation, Coords > &u, const Vector< InputType3, implementation, Coords > &mask, const Matrix< InputType2, implementation, RIT, CIT, NIT > &A, const Vector< InputType1, implementation, Coords > &v, const Ring &ring=Ring(), const Phase &phase=EXECUTE, typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *=nullptr)
	Right-handed in-place masked sparse matrix–vector multiplication, \( u = u + Av \), over a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	vxm (Vector< IOType, backend, Coords > &u, const Vector< InputType1, backend, Coords > &v, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type *const =nullptr)
	Left-handed in-place sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename InputType4 , typename Coords , typename RIT , typename CIT , typename NIT , Backend backend>
RC	vxm (Vector< IOType, backend, Coords > &u, const Vector< InputType3, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &v, const Vector< InputType4, backend, Coords > &v_mask, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!std::is_same< InputType2, void >::value, void >::type *const =nullptr)
	Left-handed in-place doubly-masked sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class Semiring , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename InputType4 , typename Coords , typename RIT , typename CIT , typename NIT , enum Backend backend>
RC	vxm (Vector< IOType, backend, Coords > &u, const Vector< InputType3, backend, Coords > &u_mask, const Vector< InputType1, backend, Coords > &v, const Vector< InputType4, backend, Coords > &v_mask, const Matrix< InputType2, backend, RIT, CIT, NIT > &A, const Semiring &semiring=Semiring(), const Phase &phase=EXECUTE, typename std::enable_if< grb::is_semiring< Semiring >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!grb::is_object< IOType >::value, void >::type *=nullptr)
	Left-handed in-place doubly-masked sparse matrix times vector multiplication, \( u = u + vA \). More...

template<Descriptor descr = descriptors::no_operation, class Ring , typename IOType , typename InputType1 , typename InputType2 , typename Coords , typename RIT , typename CIT , typename NIT , enum Backend implementation = config::default_backend>
RC	vxm (Vector< IOType, implementation, Coords > &u, const Vector< InputType1, implementation, Coords > &v, const Matrix< InputType2, implementation, RIT, CIT, NIT > &A, const Ring &ring=Ring(), const Phase &phase=EXECUTE, typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *=nullptr)
	Left-handed in-place sparse matrix–vector multiplication, \( u = u + vA \), over a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class AdditiveMonoid , class MultiplicativeOperator , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename Coords , typename RIT , typename CIT , typename NIT , Backend implementation>
RC	vxm (Vector< IOType, implementation, Coords > &u, const Vector< InputType3, implementation, Coords > &mask, const Vector< InputType1, implementation, Coords > &v, const Matrix< InputType2, implementation, RIT, CIT, NIT > &A, const AdditiveMonoid &add=AdditiveMonoid(), const MultiplicativeOperator &mul=MultiplicativeOperator(), const Phase &phase=EXECUTE, typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type *=nullptr)
	Left-handed in-place masked sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication. More...

template<Descriptor descr = descriptors::no_operation, class Ring , typename IOType , typename InputType1 , typename InputType2 , typename InputType3 , typename Coords , typename RIT , typename CIT , typename NIT , enum Backend implementation = config::default_backend>
RC	vxm (Vector< IOType, implementation, Coords > &u, const Vector< InputType3, implementation, Coords > &mask, const Vector< InputType1, implementation, Coords > &v, const Matrix< InputType2, implementation, RIT, CIT, NIT > &A, const Ring &ring=Ring(), const Phase &phase=EXECUTE, typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *=nullptr)
	Left-handed in-place masked sparse matrix–vector multiplication, \( u = u + vA \), over a given semiring. More...

Detailed Description

A collection of functions that allow GraphBLAS operators, monoids, and semirings work on a mix of zero-dimensional, one-dimensional, and two-dimensional containers.

That is, these functions allow various linear algebra operations on scalars, objects of type grb::Vector, and objects of type grb::Matrix.

Note: The backends of each opaque data type should match.

Function Documentation

◆ eWiseLambda()

RC grb::eWiseLambda	(	const Func	f,
		const Matrix< DataType, implementation, RIT, CIT, NIT > &	A,
		Args...
	)

Executes an arbitrary element-wise user-defined function f on all nonzero elements of a given matrix A.

The user-defined function is passed as a lambda which can capture whatever the user would like, including one or multiple grb::Vector instances, or multiple scalars. When capturing vectors, these should also be passed as a additional arguments to this functions so to make sure those vectors are synchronised for access on all row- and column- indices corresponding to locally stored nonzeroes of A.

Only the elements of a single matrix may be iterated upon.

Note: Rationale: while it is reasonable to expect an implementation be able to synchronise vector elements, it may be unreasonable to expect two different matrices can be jointly accessed via arbitrary lambda functions.

Warning: The lambda shall only be executed on the data local to the user process calling this function! This is different from the various fold functions, or grb::dot, in that the semantics of those functions always result in globally synchronised result. To achieve the same effect with user-defined lambdas, the users should manually prescribe how to combine the local results into global ones, for instance, by subsequent calls to grb::collectives.

Note: This is an addition to the GraphBLAS. It is alike user-defined operators, monoids, and semirings, except it allows execution on arbitrarily many inputs and arbitrarily many outputs.

Template Parameters

Func	the user-defined lambda function type.
DataType	the type of the user-supplied matrix.
backend	the backend type of the user-supplied vector example.

Parameters

[in]	f	The user-supplied lambda. This lambda should only capture and reference vectors of the same length as either the row or column dimension length of A. The lambda function should prescribe the operations required to execute on a given reference to a matrix nonzero of A (of type DataType) at a given index \( (i,j) \). Captured GraphBLAS vectors can access corresponding elements via Vector::operator[] or Vector::operator(). It is illegal to access any element not at position i if the vector length is equal to the row dimension. It is illegal to access any element not at position j if the vector length is equal to the column dimension. Vectors of length neither equal to the column or row dimension may not be referenced or undefined behaviour will occur. The reference to the matrix nonzero is non const and may thus be modified. New nonzeroes may not be added through this lambda functionality. The function f must have the following signature: `(DataType &nz, const size_t i, const size_t j)`. The GraphBLAS implementation decides which nonzeroes of A are dereferenced, and thus also decides the values i and j the user function is evaluated on.
[in]	A	The matrix the lambda is to access the elements of.

The remainder arguments should enumerate all vectors the lambda is to access elements of. Each such vector must be of the same length as nrows(A) or ncols(A). If this constraint is violated, grb::MISMATCH shall be returned. If a given vector length equals nrows(A), the vector shall be synchronized for access on i. If the vector length equals ncols(A), the vector shall be synchronized for access on j. If A is square, the vectors will be synchronised for access on both i and j.

Note: These vectors are passed using a variadic argument list and so may contain any number of containers of type grb::Vector, potentially with differing nonzero types, as separate arguments.

Warning: Using a grb::Vector inside a lambda passed to this function while not passing that same vector into the variadic argument list will result in undefined behaviour.; Due to the constraints on f described above, it is illegal to capture some vector y and have the following line in the body of f: x[i] += x[i+1]. Vectors can only be dereferenced at position i and i alone, and similarly for access using j. For square matrices, however, the following code in the body is accepted, however: x[i] += x[j].

Returns: grb::SUCCESS When the lambda is successfully executed.; grb::MISMATCH When two or more vectors passed into the variadic argument list are not of appropriate length.

Warning: Captured scalars will be local to the user process executing the lambda. To retrieve the global dot product, an allreduce must explicitly be called.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [1/6]

RC grb::mxv	(	Vector< IOType, backend, Coords > &	u,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const Vector< InputType1, backend, Coords > &	v,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type * const	= `nullptr`
	)

Right-handed in-place sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [2/6]

RC grb::mxv	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType3, backend, Coords > &	mask,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const Vector< InputType1, backend, Coords > &	v,
		const Vector< InputType4, backend, Coords > &	v_mask,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!std::is_same< InputType2, void >::value, void >::type * const	= `nullptr`
	)

Right-handed in-place doubly-masked sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::mxv for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [3/6]

RC grb::mxv	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType3, backend, Coords > &	mask,
		const Matrix< InputType2, backend, RIT, NIT, CIT > &	A,
		const Vector< InputType1, backend, Coords > &	v,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!std::is_same< InputType2, void >::value, void >::type * const	= `nullptr`
	)

Right-handed in-place masked sparse matrix–vector multiplication, \( u = u + Av \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::mxv for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [4/6]

RC grb::mxv	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType3, backend, Coords > &	u_mask,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const Vector< InputType1, backend, Coords > &	v,
		const Vector< InputType4, backend, Coords > &	v_mask,
		const Semiring &	semiring = `Semiring()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_semiring< Semiring >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value, void >::type * const	= `nullptr`
	)

Right-handed in-place doubly-masked sparse matrix times vector multiplication, \( u = u + Av \).

Aliases to this function exist that do not include masks:

grb::mxv( u, u_mask, A, v, semiring );
grb::mxv( u, A, v, semiring ); When masks are omitted, the semantics shall be the same as though a dense Boolean vector of the appropriate size with all elements set to true was given as a mask. We thus describe the semantics of the fully masked variant only.

Note: If only an input mask v_mask is intended to be given (and no output mask u_mask), then u_mask must nonetheless be explicitly given. Passing an empty Boolean vector for u_mask is sufficient.

Let \( u, \mathit{u\_mask} \) be vectors of size \( m \), let \( v, \mathit{v\_mask} \) be vectors of size \( n \), and let \( A \) be an \( m \times n \) matrix. Then, a call to this function computes \( u = u + Av \) but:

only for the elements \( u_i \) for which \( \mathit{u\_mask}_i \) evaluates true; and
only considering the elements \( v_j \) for which \( \mathit{v\_mask}_v \) evaluates true, and otherwise substituting the zero element under the given semiring.

When multiplying a matrix nonzero element \( a_{ij} \in A \), it shall be multiplied with an element \( x_j \) using the multiplicative operator of the given semiring.

When accumulating multiple contributions of multiplications of nonzeroes on some row \( i \), the additive operator of the given semiring shall be used.

Nonzero resulting from computing \( Av \) are accumulated into any pre- existing values in \( u \) by the additive operator of the given semiring.

If elements from \( v \), \( A \), or \( u \) were missing, the zero identity of the given semiring is substituted.

If nonzero values from \( A \) were missing, the one identity of the given semiring is substituted.

Note: A nonzero in \( A \) may not have a nonzero value in case it is declared as grb::Matrix< void >.

The following template arguments may be explicitly given:

Template Parameters

descr	Any combination of one or more grb::descriptors. When ommitted, the default grb::descriptors:no_operation will be assumed.
Semiring	The generalised semiring the matrix–vector multiplication is to be executed under.

The following template arguments will be inferred from the input arguments:

Template Parameters

IOType	The type of the elements of the output vector u.
InputType1	The type of the elements of the input vector v.
InputType2	The type of the elements of the input matrix A.
InputType3	The type of the output mask (u_mask) elements.
InputType4	The type of the input mask (v_mask) elements.

The following arguments are mandatory:

Parameters

[in,out]	u	The output vector.
[in]	A	The input matrix. Its grb::nrows must equal the grb::size of u.
[in]	v	The input vector. Its grb::size must equal the grb::ncols of A.
[in]	semiring	The semiring to perform the matrix–vector multiplication under. Unless grb::descriptors::no_casting is defined, elements from u, A, and v will be cast to the domains of the additive and multiplicative operators of semiring.

The vector v may not be the same as u.

Instead of passing a semiring, users may opt to provide an additive commutative monoid and a binary multiplicative operator instead. In this case, A may not be a pattern matrix (that is, it must not be of type grb::Matrix< void >).

The semiring (or the commutative monoid - binary operator pair) is optional if they are passed as a template argument instead.

Note: When providing a commutative monoid - binary operator pair, ALP backends are precluded from employing distributative laws in generating optimised codes.

Non-mandatory arguments are:

Parameters

[in]	u_mask	The output mask. The vector must be of equal size as u, or it must be empty (have size zero).
[in]	v_mask	The input mask. The vector must be of equal size as v, or it must be empty (have size zero).
[in]	phase	The requested phase for this primitive– see grb::Phase for details.

The vectors u_mask and v_mask may never be the same as u.

An empty u_mask will behave semantically the same as providing no mask; i.e., as a mask that evaluates true at every position.

If phase is not given, it will be set to the default grb::EXECUTE.

If phase is grb::EXECUTE, then the capacity of u must be greater than or equal to the capacity required to hold all output elements of the requested computation.

The above semantics may be changed by the following descriptors:

descriptors::transpose_matrix: \( A \) is interpreted as \( A^T \) instead.
descriptors::add_identity: the matrix \( A \) is instead interpreted as \( A + \mathbf{1} \), where \( \mathbf{1} \) is the one identity (i.e., multiplicative identity) of the given semiring.
descriptors::invert_mask: \( u_i \) will be written to if and only if \( \mathit{u\_mask}_i \) evaluates false, and \( v_j \) will be read from if and only if \( \mathit{v\_mask}_j \) evaluates false.
descriptors::structural: when evaluating \( \mathit{mask}_i \), only the structure of \( \mathit{u\_mask}, \mathit{v\_mask} \) is considered, as opposed to considering their values.
descriptors::structural_complement: a combination of two descriptors: descriptors::structural and descriptors::invert_mask.
descriptors::use_index: when reading \( v_i \), then, if there is indeed a nonzero \( v_i \), use the value \( i \) instead. This casts the index from size_t to the InputType1 of v.
descriptors::explicit_zero: if \( u_i \) was unassigned on entry and if \( (Av)_i \) is \( \mathbf{0} \), then instead of leaving \( u_i \) unassigned, it is set to \( \mathbf{0} \) explicitly. Here, \( \mathbf{0} \) is the additive identity of the provided semiring.
descriptors::safe_overlap: the vectors u and v may now be the same container. The user guarantees that no race conditions exist during the requested computation, however. The user may guarantee this due to a a very specific structure of A and v, or via an intelligently constructed u_mask, for example.

Returns: grb::SUCCESS If the computation completed successfully.; grb::MISMATCH If there is at least one mismatch between vector dimensions or between vectors and the given matrix.; grb::OVERLAP If two or more provided vectors refer to the same container while this was not allowed.

When any of the above non-SUCCESS error code is returned, it shall be as though the call was never made– the state of all container arguments and of the application remain unchanged, save for the returned error code.

Returns: grb::PANIC Indicates that the application has entered an undefined state.

Note: Should this error code be returned, the only sensible thing to do is exit the application as soon as possible, while refraining from using any other ALP pritimives.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [5/6]

RC grb::mxv	(	Vector< IOType, implementation, Coords > &	u,
		const Matrix< InputType2, implementation, RIT, CIT, NIT > &	A,
		const Vector< InputType1, implementation, Coords > &	v,
		const Ring &	ring,
		typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *	= `nullptr`
	)

Right-handed in-place sparse matrix–vector multiplication, \( u = u + Av \), over a given semiring.

See the documentation of grb::mxv for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ mxv() [6/6]

RC grb::mxv	(	Vector< IOType, implementation, Coords > &	u,
		const Vector< InputType3, implementation, Coords > &	mask,
		const Matrix< InputType2, implementation, RIT, CIT, NIT > &	A,
		const Vector< InputType1, implementation, Coords > &	v,
		const Ring &	ring = `Ring()`,
		const Phase &	phase = `EXECUTE`,
		typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *	= `nullptr`
	)

Right-handed in-place masked sparse matrix–vector multiplication, \( u = u + Av \), over a given semiring.

See the documentation of grb::mxv for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [1/6]

RC grb::vxm	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType1, backend, Coords > &	v,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type * const	= `nullptr`
	)

Left-handed in-place sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [2/6]

RC grb::vxm	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType3, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	v,
		const Vector< InputType4, backend, Coords > &	v_mask,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!std::is_same< InputType2, void >::value, void >::type * const	= `nullptr`
	)

Left-handed in-place doubly-masked sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [3/6]

RC grb::vxm	(	Vector< IOType, backend, Coords > &	u,
		const Vector< InputType3, backend, Coords > &	u_mask,
		const Vector< InputType1, backend, Coords > &	v,
		const Vector< InputType4, backend, Coords > &	v_mask,
		const Matrix< InputType2, backend, RIT, CIT, NIT > &	A,
		const Semiring &	semiring = `Semiring()`,
		const Phase &	phase = `EXECUTE`,
		typename std::enable_if< grb::is_semiring< Semiring >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< InputType3 >::value &&!grb::is_object< InputType4 >::value &&!grb::is_object< IOType >::value, void >::type *	= `nullptr`
	)

Left-handed in-place doubly-masked sparse matrix times vector multiplication, \( u = u + vA \).

A call to this function is exactly equivalent to calling

grb::vxm( u, u_mask, A, v, v_mask, semiring, phase ) with the descriptors::transpose_matrix flipped.

See the documentation of grb::mxv for the full semantics of this function. Like with grb::mxv, aliases to this function exist that do not include masks:

grb::vxm( u, u_mask, v, A, semiring, phase );
grb::vxm( u, v, A, semiring, phase );

Similarly, aliases to this function exist that take an additive commutative monoid and a multiplicative binary operator instead of a semiring.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [4/6]

RC grb::vxm	(	Vector< IOType, implementation, Coords > &	u,
		const Vector< InputType1, implementation, Coords > &	v,
		const Matrix< InputType2, implementation, RIT, CIT, NIT > &	A,
		const Ring &	ring = `Ring()`,
		const Phase &	phase = `EXECUTE`,
		typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *	= `nullptr`
	)

Left-handed in-place sparse matrix–vector multiplication, \( u = u + vA \), over a given semiring.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [5/6]

RC grb::vxm	(	Vector< IOType, implementation, Coords > &	u,
		const Vector< InputType3, implementation, Coords > &	mask,
		const Vector< InputType1, implementation, Coords > &	v,
		const Matrix< InputType2, implementation, RIT, CIT, NIT > &	A,
		const AdditiveMonoid &	add = `AdditiveMonoid()`,
		const MultiplicativeOperator &	mul = `MultiplicativeOperator()`,
		const Phase &	phase = `EXECUTE`,
		typename std::enable_if< grb::is_monoid< AdditiveMonoid >::value &&grb::is_operator< MultiplicativeOperator >::value &&!grb::is_object< IOType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!std::is_same< InputType2, void >::value, void >::type *	= `nullptr`
	)

Left-handed in-place masked sparse matrix–vector multiplication, \( u = u + vA \), over a given commutative additive monoid and any binary operator acting as multiplication.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

◆ vxm() [6/6]

RC grb::vxm	(	Vector< IOType, implementation, Coords > &	u,
		const Vector< InputType3, implementation, Coords > &	mask,
		const Vector< InputType1, implementation, Coords > &	v,
		const Matrix< InputType2, implementation, RIT, CIT, NIT > &	A,
		const Ring &	ring = `Ring()`,
		const Phase &	phase = `EXECUTE`,
		typename std::enable_if< grb::is_semiring< Ring >::value, void >::type *	= `nullptr`
	)

Left-handed in-place masked sparse matrix–vector multiplication, \( u = u + vA \), over a given semiring.

See the documentation of grb::vxm for the full specification of this function.

Performance semantics: Each backend must define performance semantics for this primitive.

See also: Performance Semantics

Functions

Detailed Description

Function Documentation

◆ eWiseLambda()

◆ mxv() [1/6]

◆ mxv() [2/6]

◆ mxv() [3/6]

◆ mxv() [4/6]

◆ mxv() [5/6]

◆ mxv() [6/6]

◆ vxm() [1/6]

◆ vxm() [2/6]

◆ vxm() [3/6]

◆ vxm() [4/6]

◆ vxm() [5/6]

◆ vxm() [6/6]