A collection of functions that allow ALP/GraphBLAS operators, monoids, and semirings work on a mix of zero-dimensional and one-dimensional containers; i.e., allows various linear algebra operations on scalars and objects of type grb::Vector. More...

Macros
#define	NO_MASK Vector< bool >( 0 )
	A standard vector to use for mask parameters. More...

Functions
template<Descriptor descr = descriptors::no_operation, class Ring , typename IOType , typename InputType1 , typename InputType2 , Backend backend, typename Coords >
RC	dot (IOType &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< IOType >::value &&grb::is_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the dot product, \( z += (x,y) \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class AddMonoid , class AnyOp , typename OutputType , typename InputType1 , typename InputType2 , enum Backend backend, typename Coords >
RC	dot (OutputType &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const AddMonoid &addMonoid=AddMonoid(), const AnyOp &anyOp=AnyOp(), 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< AddMonoid >::value &&grb::is_operator< AnyOp >::value, void >::type *const =nullptr)
	Calculates the dot product, \( z += (x,y) \), under a given additive monoid and multiplicative operator. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += \alpha .+ \beta \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += \alpha .+ y \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += x .+ \beta \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition of two vectors, \( z += x .+ y \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += \alpha .+ \beta \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += \alpha .+ y \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition, \( z += x .+ \beta \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseAdd (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	Calculates the element-wise addition of two vectors, \( z += x .+ y \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const InputType2 beta, const Monoid &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 \( z = \alpha \odot \beta \), out of place, monoid version. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const InputType2 beta, const OP &op=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< OP >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot \beta \), out of place, operator version. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Monoid &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 \( z = \alpha \odot y \), out of place, monoid version. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const OP &op=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< OP >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot y \), out of place, operator version. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Monoid &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 \( z = x \odot \beta \), out of place, monoid variant. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const OP &op=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< OP >::value, void >::type *const =nullptr)
	Computes \( z = x \odot \beta \), out of place, operator variant. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Monoid &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 \( z = x \odot y \), out of place, monoid variant. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const OP &op=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< OP >::value, void >::type *const =nullptr)
	Computes \( z = x \odot y \), out of place, operator variant. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const InputType2 beta, const Monoid &monoid=Monoid(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot \beta \), out of place, masked monoid version. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const InputType2 beta, const OP &op=OP(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot \beta \), out of place, operator and masked version. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Monoid &monoid=Monoid(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot y \), out of place, masked monoid variant. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const OP &op=OP(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type *const =nullptr)
	Computes \( z = \alpha \odot y \), out of place, masked operator version. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Monoid &monoid=Monoid(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Computes \( z = x \odot \beta \), out of place, masked monoid variant. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const OP &op=OP(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type *const =nullptr)
	Computes \( z = x \odot \beta \), out of place, masked operator variant. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Monoid &monoid=Monoid(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Computes \( z = x \odot y \), out of place, masked monoid variant. More...

template<Descriptor descr = descriptors::no_operation, class OP , enum Backend backend, typename OutputType , typename MaskType , typename InputType1 , typename InputType2 , typename Coords >
RC	eWiseApply (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const OP &op=OP(), const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type *const =nullptr)
	Computes \( z = x \odot y \), out of place, masked operator variant. More...

template<typename Func , typename DataType , Backend backend, typename Coords , typename... Args>
RC	eWiseLambda (const Func f, const Vector< DataType, backend, Coords > &x, Args...)
	Executes an arbitrary element-wise user-defined function f on any number of vectors of equal length. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of two scalars, \( z += \alpha .* \beta \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of a scalar and vector, \( z += \alpha .* y \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of a vector and scalar, \( z += x .* \beta \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of two vectors, \( z += x .* y \), under a given semiring. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of two scalars, \( z += \alpha .* \beta \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const InputType1 alpha, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of a scalar and vector, \( z += \alpha .* y \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const InputType2 beta, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of a vector and scalar, \( z += x .* \beta \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Ring , enum Backend backend, typename InputType1 , typename InputType2 , typename OutputType , typename MaskType , typename Coords >
RC	eWiseMul (Vector< OutputType, backend, Coords > &z, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)
	In-place element-wise multiplication of two vectors, \( z += x .* y \), under a given semiring, masked variant. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , typename IOType , typename InputType , Backend backend, typename Coords >
RC	foldl (IOType &x, const Vector< InputType, backend, Coords > &y, const Monoid &monoid=Monoid(), const typename std::enable_if< !grb::is_object< IOType >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Folds a vector into a scalar, left-to-right. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , typename InputType , typename IOType , typename MaskType , Backend backend, typename Coords >
RC	foldl (IOType &x, const Vector< InputType, backend, Coords > &y, const Vector< MaskType, backend, Coords > &mask, const Monoid &monoid=Monoid(), const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< InputType >::value &&!grb::is_object< MaskType >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Reduces, or folds, a vector into a scalar. More...

template<Descriptor descr = descriptors::no_operation, class OP , typename IOType , typename InputType , typename MaskType , Backend backend, typename Coords >
RC	foldl (IOType &x, const Vector< InputType, backend, Coords > &y, const Vector< MaskType, backend, Coords > &mask, const OP &op=OP(), const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< MaskType >::value &&grb::is_operator< OP >::value, void >::type *const =nullptr)
	Folds a vector into a scalar, left-to-right. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , typename InputType , typename IOType , typename MaskType , Backend backend, typename Coords >
RC	foldr (const Vector< InputType, backend, Coords > &x, const Vector< MaskType, backend, Coords > &mask, IOType &y, const Monoid &monoid=Monoid(), const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< InputType >::value &&!grb::is_object< MaskType >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Folds a vector into a scalar, right-to-left. More...

template<Descriptor descr = descriptors::no_operation, class Monoid , typename IOType , typename InputType , Backend backend, typename Coords >
RC	foldr (const Vector< InputType, backend, Coords > &y, IOType &x, const Monoid &monoid=Monoid(), const typename std::enable_if< !grb::is_object< IOType >::value &&grb::is_monoid< Monoid >::value, void >::type *const =nullptr)
	Folds a vector into a scalar, right-to-left. More...

Detailed Description

A collection of functions that allow ALP/GraphBLAS operators, monoids, and semirings work on a mix of zero-dimensional and one-dimensional containers; i.e., allows various linear algebra operations on scalars and objects of type grb::Vector.

All functions return an error code of the enum-type grb::RC.

Primitives which produce vector output:

grb::set (three variants);
grb::foldr (in-place reduction to the right, scalar-to-vector and vector-to-vector);
grb::foldl (in-place reduction to the left, scalar-to-vector and vector-to-vector);
grb::eWiseApply (out-of-place application of a binary function);
grb::eWiseAdd (in-place addition of two vectors, a vector and a scalar, into a vector); and
grb::eWiseMul (in-place multiplication of two vectors, a vector and a scalar, into a vector).

Note: When grb::eWiseAdd or grb::eWiseMul using two input scalars is required, consider forming first the resulting scalar using level-0 primitives, and then using grb::set, grb::foldl, or grb::foldr, as appropriate.

Primitives that produce scalar output:

grb::foldr (reduction to the right, vector-to-scalar);
grb::foldl (reduction to the left, vector-to-scalar).

Primitives that do not require an operator, monoid, or semiring:

grb::set (three variants).

Primitives that could take an operator (see grb::operators):

grb::foldr, grb::foldl, and grb::eWiseApply. Such operators typically can only be applied on dense vectors, i.e., vectors with grb::nnz equal to its grb::size. Operations on sparse vectors require an intepretation of missing vector elements, which monoids or semirings provide.

Therefore, all aforementioned functions are also defined for monoids instead of operators.

The following functions are defined for monoids and semirings, but not for operators alone:

grb::eWiseAdd (in-place addition).

The following functions require a semiring, and are not defined for operators or monoids alone:

grb::dot (in-place reduction of two vectors into a scalar); and
grb::eWiseMul (in-place multiplication).

Sometimes, operations that are defined for semirings we would sometimes also like enabled on improper semirings. ALP/GraphBLAS statically checks most properties required for composing proper semirings, and as such, attempts to compose improper ones will result in a compilation error. In such cases, we allow to pass an additive monoid and a multiplicative operator instead of a semiring. The following functions allow this:

grb::dot, grb::eWiseAdd, grb::eWiseMul. The given multiplicative operator can be any binary operator, and in particular does not need to be associative.

The algebraic structures lost with improper semirings typically correspond to distributivity, zero being an annihilator to multiplication, as well as the concept of one. Due to the latter lost structure, the above functions on impure semirings are not defined for pattern inputs.

Warning: I.e., any attempt to use containers of the form
grb::Vector<void>

grb::Matrix<void>

grb::Matrix
An ALP/GraphBLAS matrix.
Definition: matrix.hpp:71

grb::Vector
A GraphBLAS vector.
Definition: vector.hpp:64

with an improper semiring will result in a compile-time error.

Note: Pattern containers are perfectly fine to use with proper semirings.

Warning: If an improper semiring does not have the property that the zero identity acts as an annihilator over the multiplicative operator, then the result of grb::eWiseMul may be unintuitive. Please take great care in the use of improper semrings.

For fusing multiple BLAS-1 style operations on any number of inputs and outputs, users can pass their own operator function to be executed for every index i.

grb::eWiseLambda. This requires manual application of operators, monoids, and/or semirings via level-0 interface – see grb::apply, grb::foldl, and grb::foldr.

For all of these functions, the element types of input and output types do not have to match the domains of the given operator, monoid, or semiring unless the grb::descriptors::no_casting descriptor was passed.

An implementation, whether blocking or non-blocking, should have clear performance semantics for every sequence of graphBLAS calls, no matter whether those are made from sequential or parallel contexts. Backends may define different performance semantics depending on which grb::Phase primitives execute in.

Macro Definition Documentation

◆ NO_MASK

#define NO_MASK Vector< bool >( 0 )

A standard vector to use for mask parameters.

Indicates that no mask shall be used.

Function Documentation

◆ dot() [1/2]

RC grb::dot	(	IOType &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< IOType >::value &&grb::is_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the dot product, \( z += (x,y) \), under a given semiring.

Template Parameters

descr	The descriptor to be used. Optional; default descriptor is grb::descriptors::no_operation.
Ring	The semiring type to use.
OutputType	The output type.
InputType1	The input element type of the left-hand input vector.
InputType2	The input element type of the right-hand input vector.

Parameters

[in,out]	z	The output element \( z += (x,y) \).
[in]	x	The left-hand input vector x.
[in]	y	The right-hand input vector y.
[in]	ring	The semiring under which to compute the dot product \( (x,y) \). The additive monoid is used to accumulate the dot product result into z.
[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 If the dimensions of x and y 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.

Valid descriptors

If the dense descriptor is set, this implementation returns grb::ILLEGAL if it was detected that either x or y was sparse. In this case, it shall otherwise be as though the call to this function had not occurred (no side effects).

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

See also: Performance Semantics

◆ dot() [2/2]

RC grb::dot	(	OutputType &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const AddMonoid &	addMonoid = `AddMonoid()`,
		const AnyOp &	anyOp = `AnyOp()`,
		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< AddMonoid >::value &&grb::is_operator< AnyOp >::value, void >::type * const	= `nullptr`
	)

Calculates the dot product, \( z += (x,y) \), under a given additive monoid and multiplicative operator.

Template Parameters

descr	The descriptor to be used. Optional; the default descriptors is grb::descriptors::no_operation.
AddMonoid	The monoid used for addition during the computation of \( (x,y) \). The same monoid is used for accumulating the result into a given scalar.
AnyOp	A binary operator that acts as the multiplication during \( (x,y) \).
OutputType	The output type.
InputType1	The input element type of the left-hand input vector.
InputType2	The input element type of the right-hand input vector.

Parameters

[in,out]	z	Where to fold \( (x,y) \) into.
[in]	x	The left-hand input vector.
[in]	y	The right-hand input vector.
[in]	addMonoid	The additive monoid under which the reduction of the results of element-wise multiplications of x and y are performed.
[in]	anyOp	The multiplicative operator using which element-wise multiplications of x and y are performed. This may be any binary operator.
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Note: By this primitive by which a dot-product operates under any additive monoid and any binary operator, it follows that a dot product under any semiring can be reduced to a call to this primitive instead.

Returns: grb::MISMATCH When the dimensions of x and y 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::SUCCESS On successful completion of this call.

Valid descriptors

If the dense descriptor is set, this implementation returns grb::ILLEGAL if it was detected that either x or y was sparse. In this case, it shall otherwise be as though the call to this function had not occurred (no side effects).

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

See also: Performance Semantics

◆ eWiseAdd() [1/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += \alpha .+ \beta \), under a given semiring.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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.

Valid descriptors: grb::descriptors::no_operation, grb::descriptors::no_casting, grb::descriptors::dense.

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [2/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += \alpha .+ y \), under a given semiring.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	y	The right-hand input vector of type InputType2. This may be a sparse vector.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 y and z do not match. All input data containers are left untouched; 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 vector 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.

Valid descriptors: grb::descriptors::no_operation, grb::descriptors::no_casting, grb::descriptors::dense.

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [3/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += x .+ \beta \), under a given semiring.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	x	The left-hand input vector of type InputType1. This may be a sparse vector.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 and z do not match. All input data containers are left untouched; 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 vector 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.

Valid descriptors: grb::descriptors::no_operation, grb::descriptors::no_casting, grb::descriptors::dense.

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [4/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition of two vectors, \( z += x .+ y \), under a given semiring.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	x	The left-hand input vector of type InputType1. This may be a sparse vector.
[in]	y	The right-hand input vector of type InputType2. This may be a sparse vector.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Note: There is also a masked variant of grb::eWiseAdd, as well as variants where x and/or y are scalars.

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; 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 vector 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.

Valid descriptors: grb::descriptors::no_operation, grb::descriptors::no_casting, grb::descriptors::dense.

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [5/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += \alpha .+ \beta \), under a given semiring, masked variant.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.
MaskType	The nonzero type of the output mask vector.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	mask	The output mask.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 If mask and z do not have the same size.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [6/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += \alpha .+ y \), under a given semiring, masked variant.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.
MaskType	The nonzero type of the output mask vector.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	mask	The output mask.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	y	The right-hand input vector of type InputType2. This may be a sparse vector.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 mask, y, and z do not match. All input data containers are left untouched; 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 vector 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.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [7/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition, \( z += x .+ \beta \), under a given semiring, masked variant.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.
MaskType	The nonzero type of the output mask vector.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	mask	The output mask.
[in]	x	The left-hand input vector of type InputType1. This may be a sparse vector.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 mask, x, and z do not match. All input data containers are left untouched; 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 vector 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.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseAdd() [8/8]

RC grb::eWiseAdd	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

Calculates the element-wise addition of two vectors, \( z += x .+ y \), under a given semiring, masked variant.

Note: This is an in-place operation.

Deprecated:: This function has been deprecated since v0.5. It may be removed at latest at v1.0 of ALP/GraphBLAS– or any time earlier.

Note: A call to this function is equivalent to two in-place fold operations using the additive monoid of the given semiring. Please update any code that calls grb::eWiseAdd with such a sequence as soon as possible.; We may consider providing this function as an algorithm in the grb::algorithms namespace, similar to grb::algorithms::mpv. Please let the maintainers know if you would prefer such a solution over outright removal and replacement with two folds.

Template Parameters

descr	The descriptor to be used. Optional; default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise addition on.
InputType1	The left-hand side input type to the additive operator of the ring.
InputType2	The right-hand side input type to the additive operator of the ring.
OutputType	The result type of the additive operator of the ring.
MaskType	The nonzero type of the output mask vector.

Parameters

[out]	z	The output vector of type OutputType. This may be a sparse vector.
[in]	mask	The output mask vector of type MaskType.
[in]	x	The left-hand input vector of type InputType1. This may be a sparse vector.
[in]	y	The right-hand input vector of type InputType2. This may be a sparse vector.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Note: There are also variants where x and/or y are scalars, as well as unmasked variants.

Returns: grb::SUCCESS On successful completion of this call.; grb::MISMATCH Whenever the dimensions of mask, x, y, and z do not match. All input data containers are left untouched; 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 vector 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.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the third domain of ring must match InputType1, 2) the fourth domain of ring must match InputType2, 3) the fourth domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseApply() [1/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const InputType2	beta,
		const Monoid &	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 \( z = \alpha \odot \beta \), out of place, monoid version.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	alpha	The left-hand input scalar.
[in]	beta	The right-hand input scalar.
[in]	monoid	The monoid with underlying operator \( \odot \).
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Specialisation scalar inputs, unmasked monoid version.

A call to this function is equivalent to the following code:

typename OP::D3 tmp;
grb::apply( tmp, x, y, monoid.getOperator() );
grb::set( z, tmp, phase );

Returns: grb::SUCCESS On successful completion of this call.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const InputType2	beta,
		const OP &	op = `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< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot \beta \), out of place, operator version.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	alpha	The left-hand input scalar.
[in]	beta	The right-hand input scalar.
[in]	op	The operator \( \odot \).
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Specialisation scalar inputs, unmasked operator version.

A call to this function is equivalent to the following code:

typename OP::D3 tmp;
grb::apply( tmp, x, y, op );
grb::set( z, tmp, phase );

Returns: grb::SUCCESS On successful completion of this call.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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() [3/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Monoid &	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 \( z = \alpha \odot y \), out of place, monoid version.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = \alpha \odot y \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( \alpha \odot y_i \). Any old entries of z are removed.

After a successful call to this primitive, z shall be dense.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	alpha	The left-hand input scalar.
[in]	y	The right-hand input vector.
[in]	monoid	The monoid that provides the operator \( \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 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 vector 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() [4/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const OP &	op = `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< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot y \), out of place, operator version.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = \alpha \odot y \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( \alpha \odot y_i \). Any old entries of z are removed. Entries i for which y has no nonzero will be skipped.

After a successful call to this primitive, the sparsity structure of z shall match that of y.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	alpha	The left-hand input scalar.
[in]	y	The right-hand input vector.
[in]	op	The operator \( \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 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 vector 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() [5/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Monoid &	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 \( z = x \odot \beta \), out of place, monoid variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot \beta \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot \beta \). Any old entries of z are removed.

After a successful call to this primitive, z shall be dense.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	x	The left-hand input vector.
[in]	beta	The right-hand input scalar.
[in]	monoid	The monoid that provides the operator \( \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 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 vector 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() [6/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const OP &	op = `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< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot \beta \), out of place, operator variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x .* \beta \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot \beta \). Any old entries of z are removed.

Entries i for which no nonzero exists in x are skipped. Therefore, after a successful call to this primitive, the nonzero structure of z will match that of x.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	x	The left-hand input vector.
[in]	beta	The right-hand input scalar.
[in]	op	The operator \( \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 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 vector 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() [7/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Monoid &	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 \( z = x \odot y \), out of place, monoid variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot y \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot y_i \). Any old entries of z are removed.

After a successful call to this primitive, the nonzero structure of z will match that of the union of x and y. An implementing backend may skip processing indices i that are not in the union of the nonzero structure of x and y.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

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 vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.

Parameters

[out]	z	The output vector.
[in]	x	The left-hand input vector.
[in]	y	The right-hand input vector.
[in]	monoid	The monoid structure that \( \odot \) corresponds to.
[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 vector 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() [8/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const OP &	op = `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< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot y \), out of place, operator variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot y \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot y_i \). Any old entries of z are removed. Entries i which have no nonzero in either x or y are skipped.

After a successful call to this primitive, the nonzero structure of z will match that of the intersection of x and y.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

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

Parameters

[out]	z	The output vector.
[in]	x	The left-hand input vector.
[in]	y	The right-hand input vector.
[in]	op	The operator \( \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 vector 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() [9/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const InputType2	beta,
		const Monoid &	monoid = `Monoid()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot \beta \), out of place, masked monoid version.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the output mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The output mask.
[in]	alpha	The left-hand input scalar.
[in]	beta	The right-hand input scalar.
[in]	monoid	The monoid with underlying operator \( \odot \).
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Specialisation for scalar inputs, masked monoid version.

A call to this function is equivalent to the following code:

typename OP::D3 tmp;
grb::apply( tmp, alpha, beta, monoid.getOperator() );
grb::set( z, mask, tmp, phase );

Returns: grb::SUCCESS On successful completion of this call.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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() [10/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const InputType2	beta,
		const OP &	op = `OP()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot \beta \), out of place, operator and masked version.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the output mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The ouptut mask.
[in]	alpha	The left-hand input scalar.
[in]	beta	The right-hand input scalar.
[in]	op	The operator \( \odot \).
[in]	phase	The grb::Phase the call should execute. Optional; the default parameter is grb::EXECUTE.

Specialisation scalar inputs, masked operator version.

A call to this function is equivalent to the following code:

typename OP::D3 tmp;
grb::apply( tmp, x, y, op );
grb::set( z, mask, tmp, phase );

Returns: grb::SUCCESS On successful completion of this call.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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() [11/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Monoid &	monoid = `Monoid()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot y \), out of place, masked monoid variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = \alpha \odot y \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( \alpha \odot y_i \). Any old entries of z are removed. Entries i for which mask evaluates false will be skipped.

After a successful call to this primitive, the sparsity structure of z shall match that of mask (after interpretation).

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the output mask vector.

Parameters

[out]	z	The output vector.
[out]	mask	The output mask.
[in]	alpha	The left-hand input scalar.
[in]	y	The right-hand input vector.
[in]	monoid	The monoid that provides the operator \( \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 mask, a 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 vector 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() [12/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const OP &	op = `OP()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = \alpha \odot y \), out of place, masked operator version.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = \alpha \odot y \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( \alpha \odot y_i \). Any old entries of z are removed. Entries i for which y has no nonzero will be skipped, as will entries i for which mask evaluates false.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The output mask.
[in]	alpha	The left-hand input scalar.
[in]	y	The right-hand input vector.
[in]	op	The operator \( \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 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 vector 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() [13/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Monoid &	monoid = `Monoid()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot \beta \), out of place, masked monoid variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot \beta \), using the given operator. The input and output vectors must be of equal length.

For all indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot \beta \). Any old entries of z are removed. Entries i for which mask evaluates false will be skipped.

After a successful call to this primitive, the sparsity structure of z matches that of mask (after interpretation).

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
Monoid	The monoid to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the mask vector.

Parameters

[out]	z	The output vector.
[out]	mask	The output mask.
[in]	x	The left-hand input vector.
[in]	beta	The right-hand input scalar.
[in]	monoid	The monoid that provides the operator \( \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 mask, x 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 vector 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() [14/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const OP &	op = `OP()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot \beta \), out of place, masked operator variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x .* \beta \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot \beta \). Any old entries of z are removed.

Entries i for which no nonzero exists in x are skipped. Entries i for which the mask evaluates false are skipped as well.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the output vector.
MaskType	The value type of the output mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The output mask.
[in]	x	The left-hand input vector.
[in]	beta	The right-hand input scalar.
[in]	op	The operator \( \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 mask, x, 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 vector 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() [15/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Monoid &	monoid = `Monoid()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot y \), out of place, masked monoid variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot y \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot y_i \). Any old entries of z are removed. Entries i for which mask evaluates false will be skipped.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

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 vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The output mask.
[in]	x	The left-hand input vector.
[in]	y	The right-hand input vector.
[in]	monoid	The monoid structure that \( \odot \) corresponds to.
[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 vector 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() [16/16]

RC grb::eWiseApply	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const OP &	op = `OP()`,
		const Phase &	phase = `EXECUTE`,
		const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&grb::is_operator< OP >::value, void >::type * const	= `nullptr`
	)

Computes \( z = x \odot y \), out of place, masked operator variant.

Calculates the element-wise operation on one scalar to elements of one vector, \( z = x \odot y \), using the given operator. The input and output vectors must be of equal length.

For all valid indices i of z, its element \( z_i \) after the call to this function completes equals \( x_i \odot y_i \). Any old entries of z are removed. Entries i which have no nonzero in either x or y are skipped, as will entries i for which mask evaluates false.

After a successful call to this primitive, the nonzero structure of z will match that of the intersection of x and y.

Note

When applying element-wise operators on sparse vectors 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, there are two different variants for element-wise operations whose names correspond to their intuitive meanings:

grb::eWiseAdd (neutral), and
grb::eWiseMul (annihilating). The above two primitives require a semiring. The same 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).

However, grb::eWiseAdd and grb::eWiseMul provide in-place semantics, while grb::eWiseApply does not.

An grb::eWiseAdd with some semiring and a grb::eWiseApply using its additive monoid thus are equivalent if operating when operating on empty outputs.

An grb::eWiseMul with some semiring and a grb::eWiseApply using its multiplicative operator thus are equivalent when operating on empty outputs.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
OP	The operator to use.
InputType1	The value type of the left-hand vector.
InputType2	The value type of the right-hand scalar.
OutputType	The value type of the ouput vector.
MaskType	The value type of the output mask vector.

Parameters

[out]	z	The output vector.
[in]	mask	The output mask.
[in]	x	The left-hand input vector.
[in]	y	The right-hand input vector.
[in]	op	The operator \( \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 mask, 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 vector 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

◆ eWiseLambda()

RC grb::eWiseLambda	(	const Func	f,
		const Vector< DataType, backend, Coords > &	x,
		Args...
	)

Executes an arbitrary element-wise user-defined function f on any number of vectors of equal length.

Warning: This is a relatively advanced function. It is recommended to read this specifications and its warnings before using it, or to instead exclusively only use the other primitives in Level-1 Primitives.

The vectors touched by f can be accessed in a read-only or a read/write fashion. The function f must be parametrised in a global index i, and f is only allowed to access elements of the captured vectors on that specific index.

Warning: Any attempt to access a vector element at a position differing from i will result in undefined behaviour.

All vectors captured by f must furthermore all be given as additional (variadic) arguments to this primitive. Captured vectors can only be used for dereferencing elements at a given position i; any other use invokes undefined behaviour.

Warning: In particular, captured vectors may not be passed to other ALP/GraphBLAS primitives within f.

This primitive will execute f on all indices where the first given such vector argument has nonzeroes. All other indices i will be ignored.

Warning: Therefore, for containers of which f references the i-th element, must indeed have a nonzero at position i or otherwise undefined behaviour is invoked.

This primitive hence allows a user to implement any level-1 like BLAS functionality over any number of input/output vectors, and also allows to compute multiple level-1 (like) BLAS functionalities as a single pass over the involved containers.

Note: Since the introduction of the nonblocking backend, rewriting f in terms of native ALP/GraphBLAS primitives no longer implies performance penalties (when compiling for the nonblocking backend)– rather, the nonblocking backend is likely to do better than manually fusing multiple level-1 like operations using this primitive, especially when the captured vectors are small relative to the private caches on the target architecture.

The function f may also capture scalars for read-only access.

Note: As a convention, consider always passing scalars by value, since otherwise the compilation of your code with a non-blocking backend may (likely) result in data races.

If grb::Properties::writableCaptured evaluates true then captured scalars may also safely be written to, instead of requiring to be read-only.

Note: This is useful for fusing reductions within other level-1 like operations.

Warning: If updating scalars using this primitive, be aware that the updates are local to the current user process only.

Note: If, after execution of this primitive, an updated scalar is expected to be synchronised across all user processes, see grb::collectives.; As a rule of thumb, parallel GraphBLAS implementations, due to being data-centric, cannot support writeable scalar captures and will have grb::Properties::writableCaptured evaluate to false.; A portable ALP/GraphBLAS algorithm should therefore either not rely on read/write captured scalars passed to this primitive, or provide different code paths to handle the two cases of the grb::Properties::writableCaptured backend property.; If the above sounds too tedious, consider rewriting f in terms of native ALP/GraphBLAS functions, with the scalar reductions performed by the scalar variants of grb::foldl and grb::foldr, e.g.

Warning: When compiling with a blocking backend, rewriting f in terms of native GraphBLAS primitives typically results in a slowdown due to this primitive naturally fusing potentially multiple operations together (which was the original motivation of Yzelman et al., 2020 for introducing this primitive. Rewriting f into a (sequence of) native GraphBLAS primtives does not carry a performance when compiling with a nonblocking backend, however.

Note: This is an addition to the GraphBLAS C specification. It is alike user-defined operators, monoids, and semirings, except that this primitive 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 vector example.
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 x. The lambda function should prescribe the operations required to execute at a given index i. Captured ALP/GraphBLAS vectors can access that element via the operator[]. It is illegal to access any element not at position i. The lambda takes only the single parameter i of type `const size_t`. Captured scalars will not be globally updated– the user must program this explicitly. Scalars and other non-GraphBLAS containers are always local to their user process.
[in]	x	The vector the lambda will be executed on. This argument determines which indices i will be accessed during the elementwise operation– elements with indices i that do not appear in x will be skipped during evaluation of f.

The remaining arguments must collect all vectors the lambda is to access elements of. Such vectors must be of the same length as x. If this constraint is violated, grb::MISMATCH shall be returned.

Note: These are passed using variadic arguments and so can contain any number of containers of type grb::Vector.; Distributed-memory ALP/GraphBLAS backends, apart from performing dimension checking, may also require data redistribution in case that different vectors are distributed differently.

Warning: Using a grb::Vector inside a lambda passed to this function while not passing that same vector into its 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.

Returns: grb::SUCCESS When the lambda is successfully executed.; grb::MISMATCH When two or more vectors passed to args are not of equal length.; grb::PANIC When ALP/GraphBLAS has encountered an unrecoverable error. The state of ALP becomes undefined after having returned this error code, and users can only attempt to exit the application gracefully.

Example.

An example valid use:

void f(
     double &alpha,
     grb::Vector< double > &y,
     const double beta,
     const grb::Vector< double > &x,
     const grb::Semiring< double > ring
) {
     assert( grb::size(x) == grb::size(y) );
     assert( grb::nnz(x) == grb::size(x) );
     assert( grb::nnz(y) == grb::size(y) );
     alpha = ring.getZero();
     grb::eWiseLambda(
         [&alpha,beta,&x,&y,ring]( const size_t i ) {
             double mul;
             const auto mul_op = ring.getMultiplicativeOperator();
             const auto add_op = ring.getAdditiveOperator();
             grb::apply( y[i], beta, x[i], mul_op );
             grb::apply( mul, x[i], y[i], mul_op );
             grb::foldl( alpha, mul, add_op );
     }, x, y );
     grb::collectives::allreduce( alpha, add_op );
}

This code takes a value beta, a vector x, and a semiring ring and computes: 1) y as the element-wise multiplication (under ring) of beta and x; and 2) alpha as the dot product (under ring) of x and y. This function can easily be made agnostic to whatever exact semiring is used by templating the type of ring. As it is, this code is functionally equivalent to:

grb::eWiseMul( y, beta, x, ring );

grb::dot( alpha, x, y, ring );

grb::eWiseMul

RC eWiseMul(Vector< OutputType, backend, Coords > &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Ring &ring=Ring(), 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_semiring< Ring >::value, void >::type *const =nullptr)

In-place element-wise multiplication of two vectors, , under a given semiring.

Definition: blas1.hpp:2794

grb::dot

RC dot(OutputType &z, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const AddMonoid &addMonoid=AddMonoid(), const AnyOp &anyOp=AnyOp(), 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< AddMonoid >::value &&grb::is_operator< AnyOp >::value, void >::type *const =nullptr)

Calculates the dot product, , under a given additive monoid and multiplicative operator.

Definition: blas1.hpp:4056

If the latter code block is compiled using a blocking ALP/GraphBLAS backend, the version using the lambdas is expected to execute faster as both x and y are streamed only once, while the latter code may stream both vectors twice. This performance difference disappears when compiling the latter code block using a nonblocking backend instead.

Warning: The following code is invalid:
template< class Operator >

void f(

grb::Vector< double > &x,

const Operator op

) {

grb::eWiseLambda(

[&x,&op]( const size_t i ) {

grb::apply( x[i], x[i], x[i+1], op );

}, x );

}

Only a Vector::lambda_reference to position exactly equal to i may be used within this function.

See also: Vector::operator[](); Vector::lambda_reference

Performance semantics: Each backend must define performance semantics for this primitive. It is expected that the defined performance semantics depend on the given lambda function f, the size of the containers passed into this primitive, as well as how many containers are passed into this primitive.

See also: Performance Semantics

◆ eWiseMul() [1/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of two scalars, \( z += \alpha .* \beta \), under a given semiring.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output type.

Parameters

[out]	z	The output vector of type OutputType.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [2/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of a scalar and vector, \( z += \alpha .* y \), under a given semiring.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output type.

Parameters

[out]	z	The output vector of type OutputType.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	y	The right-hand input vector of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [3/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of a vector and scalar, \( z += x .* \beta \), under a given semiring.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output type.

Parameters

[out]	z	The output vector of type OutputType.
[in]	x	The left-hand input vector of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [4/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of two vectors, \( z += x .* y \), under a given semiring.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output type.

Parameters

[out]	z	The output vector of type OutputType.
[in]	x	The left-hand input vector of type InputType1.
[in]	y	The right-hand input vector of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [5/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of two scalars, \( z += \alpha .* \beta \), under a given semiring, masked variant.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output vector type.
MaskType	The output mask type.

Parameters

[in,out]	z	The output vector of type OutputType.
[in]	mask	The ouput mask of type MaskType.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 If mask and z have different size.; grb::FAILED If phase is grb::EXECUTE, indicates that the capacity of z was insufficient. The output vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [6/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const InputType1	alpha,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of a scalar and vector, \( z += \alpha .* y \), under a given semiring, masked variant.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output vector type.
MaskType	The output mask type.

Parameters

[in,out]	z	The output vector of type OutputType.
[in]	mask	The ouput mask of type MaskType.
[in]	alpha	The left-hand input scalar of type InputType1.
[in]	y	The right-hand input vector of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 mask, 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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [7/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const InputType2	beta,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of a vector and scalar, \( z += x .* \beta \), under a given semiring, masked variant.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output vector type.
MaskType	The output mask type.

Parameters

[in,out]	z	The output vector of type OutputType.
[in]	mask	The output mask of type MaskType.
[in]	x	The left-hand input vector of type InputType1.
[in]	beta	The right-hand input scalar of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 mask, x 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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ eWiseMul() [8/8]

RC grb::eWiseMul	(	Vector< OutputType, backend, Coords > &	z,
		const Vector< MaskType, backend, Coords > &	mask,
		const Vector< InputType1, backend, Coords > &	x,
		const Vector< InputType2, backend, Coords > &	y,
		const Ring &	ring = `Ring()`,
		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_semiring< Ring >::value, void >::type * const	= `nullptr`
	)

In-place element-wise multiplication of two vectors, \( z += x .* y \), under a given semiring, masked variant.

Template Parameters

descr	The descriptor to be used. Optional; the default is grb::descriptors::no_operation.
Ring	The semiring type to perform the element-wise multiply with.
InputType1	The left-hand side input type.
InputType2	The right-hand side input type.
OutputType	The output vector type.
MaskType	The output mask type.

Parameters

[in,out]	z	The output vector of type OutputType.
[in]	mask	The ouput mask of type MaskType.
[in]	x	The left-hand input vector of type InputType1.
[in]	y	The right-hand input vector of type InputType2.
[in]	ring	The generalized semiring under which to perform this element-wise multiplication.
[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 mask, 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 vector 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.

Warning: Unlike grb::eWiseApply using monoids, given sparse vectors, missing elements in sparse input vectors are now interpreted as a the zero identity, therefore annihilating instead of acting as a monoid identity. Therefore even when z is empty on input, the grb::eWiseApply with monoids does not incur the same behaviour as this function. The grb::eWiseApply with operators is similar, except that this function is in-place and grb::eWiseApply is not.

Valid descriptors

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is specified, then 1) the first domain of ring must match InputType1, 2) the second domain of ring must match InputType2, 3) the third domain of ring must match OutputType. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ foldl() [1/3]

RC grb::foldl	(	IOType &	x,
		const Vector< InputType, backend, Coords > &	y,
		const Monoid &	monoid = `Monoid()`,
		const typename std::enable_if< !grb::is_object< IOType >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Folds a vector into a scalar, left-to-right.

Unmasked monoid variant. See masked variant for the full documentation.

◆ foldl() [2/3]

RC grb::foldl	(	IOType &	x,
		const Vector< InputType, backend, Coords > &	y,
		const Vector< MaskType, backend, Coords > &	mask,
		const Monoid &	monoid = `Monoid()`,
		const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< InputType >::value &&!grb::is_object< MaskType >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Reduces, or folds, a vector into a scalar.

Reduction takes place according a monoid \( (\oplus,1) \), where \( \oplus:\ D_1 \times D_2 \to D_3 \) with associated identities \( 1_k in D_k \). Usually, \( D_k \subseteq D_3, 1 \leq k < 3 \), though other more exotic structures may be envisioned (and used).

Let \( x_0 = 1 \) and let \( x_{i+1} = \begin{cases} x_i \oplus y_i\text{ if }y_i\text{ is nonzero and }m_i\text{ evaluates true} x_i\text{ otherwise} \end{cases},\) for all \( i \in \{ 0, 1, \ldots, n-1 \} \).

Note: Per this definition, the folding happens in a left-to-right direction. If another direction is wanted, which may have use in cases where \( D_1 \) differs from \( D_2 \), then either a monoid with those operator domains switched may be supplied, or grb::foldr may be used instead.

After a successfull call, x will be equal to \( x_n \).

Note that the operator \( \oplus \) must be associative since it is part of a monoid. This algebraic property is exploited when parallelising the requested operation. The identity is required when parallelising over multiple user processes.

Warning: In so doing, the order of the evaluation of the reduction operation should not be expected to be a serial, left-to-right, evaluation of the computation chain.

Template Parameters

descr	The descriptor to be used (descriptors::no_operation if left unspecified).
Monoid	The monoid to use for reduction.
InputType	The type of the elements in the supplied ALP/GraphBLAS vector y.
IOType	The type of the output scalar x.
MaskType	The type of the elements in the supplied ALP/GraphBLAS vector mask.

Parameters

[out]	x	The result of the reduction.
[in]	y	Any ALP/GraphBLAS vector. This vector may be sparse.
[in]	mask	Any ALP/GraphBLAS vector. This vector may be sparse.
[in]	monoid	The monoid under which to perform this reduction.

Returns: grb::SUCCESS When the call completed successfully.; grb::MISMATCH If a mask was not empty and does not have size equal to y.; grb::ILLEGAL If the provided input vector y was not dense, while grb::descriptors::dense was given.

See also: grb::foldr provides similar in-place functionality.; grb::eWiseApply provides out-of-place semantics.

Valid descriptors: grb::descriptors::no_operation, grb::descriptors::no_casting, grb::descriptors::dense, grb::descriptors::invert_mask, grb::descriptors::structural, grb::descriptors::structural_complement

Note: Invalid descriptors will be ignored.

If grb::descriptors::no_casting is given, then 1) the first domain of monoid must match InputType, 2) the second domain of op must match IOType, 3) the third domain must match IOType, and 4) the element type of mask must be bool. If one of these is not true, the code shall not compile.

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

See also: Performance Semantics

◆ foldl() [3/3]

RC grb::foldl	(	IOType &	x,
		const Vector< InputType, backend, Coords > &	y,
		const Vector< MaskType, backend, Coords > &	mask,
		const OP &	op = `OP()`,
		const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< MaskType >::value &&grb::is_operator< OP >::value, void >::type * const	= `nullptr`
	)

Folds a vector into a scalar, left-to-right.

Unmasked operator variant. See masked variant for the full documentation.

Deprecated:: This signature is deprecated. It was implemented for reference (and reference_omp), but could not be implemented for BSP1D and other distributed-memory backends. This signature may be removed with any release beyond 0.6.

◆ foldr() [1/2]

RC grb::foldr	(	const Vector< InputType, backend, Coords > &	x,
		const Vector< MaskType, backend, Coords > &	mask,
		IOType &	y,
		const Monoid &	monoid = `Monoid()`,
		const typename std::enable_if< !grb::is_object< IOType >::value &&!grb::is_object< InputType >::value &&!grb::is_object< MaskType >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Folds a vector into a scalar, right-to-left.

Masked variant. See the masked, left-to-right variant for the full documentation.

◆ foldr() [2/2]

RC grb::foldr	(	const Vector< InputType, backend, Coords > &	y,
		IOType &	x,
		const Monoid &	monoid = `Monoid()`,
		const typename std::enable_if< !grb::is_object< IOType >::value &&grb::is_monoid< Monoid >::value, void >::type * const	= `nullptr`
	)

Folds a vector into a scalar, right-to-left.

Unmasked variant. See the masked, left-to-right variant for the full documentation.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ NO_MASK

Function Documentation

◆ dot() [1/2]

◆ dot() [2/2]

◆ eWiseAdd() [1/8]

◆ eWiseAdd() [2/8]

◆ eWiseAdd() [3/8]

◆ eWiseAdd() [4/8]

◆ eWiseAdd() [5/8]

◆ eWiseAdd() [6/8]

◆ eWiseAdd() [7/8]

◆ eWiseAdd() [8/8]

◆ eWiseApply() [1/16]

◆ eWiseApply() [2/16]

◆ eWiseApply() [3/16]

◆ eWiseApply() [4/16]

◆ eWiseApply() [5/16]

◆ eWiseApply() [6/16]

◆ eWiseApply() [7/16]

◆ eWiseApply() [8/16]

◆ eWiseApply() [9/16]

◆ eWiseApply() [10/16]

◆ eWiseApply() [11/16]

◆ eWiseApply() [12/16]

◆ eWiseApply() [13/16]

◆ eWiseApply() [14/16]

◆ eWiseApply() [15/16]

◆ eWiseApply() [16/16]

◆ eWiseLambda()

◆ eWiseMul() [1/8]

◆ eWiseMul() [2/8]

◆ eWiseMul() [3/8]

◆ eWiseMul() [4/8]

◆ eWiseMul() [5/8]

◆ eWiseMul() [6/8]

◆ eWiseMul() [7/8]

◆ eWiseMul() [8/8]

◆ foldl() [1/3]

◆ foldl() [2/3]

◆ foldl() [3/3]

◆ foldr() [1/2]

◆ foldr() [2/2]