ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Macros | Functions
Level-1 Primitives

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 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 , 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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<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 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<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 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 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 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 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 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 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 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 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 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:

  1. grb::set (three variants);
  2. grb::foldr (in-place reduction to the right, scalar-to-vector and vector-to-vector);
  3. grb::foldl (in-place reduction to the left, scalar-to-vector and vector-to-vector);
  4. grb::eWiseApply (out-of-place application of a binary function);
  5. grb::eWiseAdd (in-place addition of two vectors, a vector and a scalar, into a vector); and
  6. 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:

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

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

  1. grb::set (three variants).

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

  1. 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:

  1. grb::eWiseAdd (in-place addition).

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

  1. grb::dot (in-place reduction of two vectors into a scalar); and
  2. 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:

  1. 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 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.

  1. 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 ( 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
descrThe descriptor to be used. Optional; the default descriptors is grb::descriptors::no_operation.
AddMonoidThe monoid used for addition during the computation of \( (x,y) \). The same monoid is used for accumulating the result into a given scalar.
AnyOpA binary operator that acts as the multiplication during \( (x,y) \).
OutputTypeThe output type.
InputType1The input element type of the left-hand input vector.
InputType2The input element type of the right-hand input vector.
Parameters
[in,out]zWhere to fold \( (x,y) \) into.
[in]xThe left-hand input vector.
[in]yThe right-hand input vector.
[in]addMonoidThe additive monoid under which the reduction of the results of element-wise multiplications of x and y are performed.
[in]anyOpThe multiplicative operator using which element-wise multiplications of x and y are performed. This may be any binary operator.
[in]phaseThe 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
  1. grb::descriptors::no_operation
  2. grb::descriptors::no_casting
  3. grb::descriptors::dense
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 ( 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
descrThe descriptor to be used. Optional; default descriptor is grb::descriptors::no_operation.
RingThe semiring type to use.
OutputTypeThe output type.
InputType1The input element type of the left-hand input vector.
InputType2The input element type of the right-hand input vector.
Parameters
[in,out]zThe output element \( z += (x,y) \).
[in]xThe left-hand input vector x.
[in]yThe right-hand input vector y.
[in]ringThe semiring under which to compute the dot product \( (x,y) \). The additive monoid is used to accumulate the dot product result into z.
[in]phaseThe 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

◆ eWiseAdd() [1/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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]xThe left-hand input vector of type InputType1. This may be a sparse vector.
[in]yThe right-hand input vector of type InputType2. This may be a sparse vector.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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() [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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]alphaThe left-hand input scalar of type InputType1.
[in]yThe right-hand input vector of type InputType2. This may be a sparse vector.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]xThe left-hand input vector of type InputType1. This may be a sparse vector.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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 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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]alphaThe left-hand input scalar of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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() [5/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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
MaskTypeThe nonzero type of the output mask vector.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]maskThe output mask vector of type MaskType.
[in]xThe left-hand input vector of type InputType1. This may be a sparse vector.
[in]yThe right-hand input vector of type InputType2. This may be a sparse vector.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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

◆ 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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
MaskTypeThe nonzero type of the output mask vector.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]maskThe output mask.
[in]alphaThe left-hand input scalar of type InputType1.
[in]yThe right-hand input vector of type InputType2. This may be a sparse vector.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
MaskTypeThe nonzero type of the output mask vector.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]maskThe output mask.
[in]xThe left-hand input vector of type InputType1. This may be a sparse vector.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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 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
descrThe descriptor to be used. Optional; default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise addition on.
InputType1The left-hand side input type to the additive operator of the ring.
InputType2The right-hand side input type to the additive operator of the ring.
OutputTypeThe result type of the additive operator of the ring.
MaskTypeThe nonzero type of the output mask vector.
Parameters
[out]zThe output vector of type OutputType. This may be a sparse vector.
[in]maskThe output mask.
[in]alphaThe left-hand input scalar of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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

◆ eWiseApply() [1/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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]alphaThe left-hand input scalar.
[in]betaThe right-hand input scalar.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [2/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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the output mask vector.
Parameters
[out]zThe output vector.
[in]maskThe ouptut mask.
[in]alphaThe left-hand input scalar.
[in]betaThe right-hand input scalar.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [3/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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]alphaThe left-hand input scalar.
[in]betaThe right-hand input scalar.
[in]monoidThe monoid with underlying operator \( \odot \).
[in]phaseThe 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() [4/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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the output mask vector.
Parameters
[out]zThe output vector.
[in]maskThe output mask.
[in]alphaThe left-hand input scalar.
[in]betaThe right-hand input scalar.
[in]monoidThe monoid with underlying operator \( \odot \).
[in]phaseThe 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() [5/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]alphaThe left-hand input scalar.
[in]yThe right-hand input vector.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [6/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the mask vector.
Parameters
[out]zThe output vector.
[in]maskThe output mask.
[in]alphaThe left-hand input scalar.
[in]yThe right-hand input vector.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [7/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]alphaThe left-hand input scalar.
[in]yThe right-hand input vector.
[in]monoidThe monoid that provides the operator \( \odot \).
[in]phaseThe 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() [8/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the output mask vector.
Parameters
[out]zThe output vector.
[out]maskThe output mask.
[in]alphaThe left-hand input scalar.
[in]yThe right-hand input vector.
[in]monoidThe monoid that provides the operator \( \odot \).
[in]phaseThe 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() [9/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]xThe left-hand input vector.
[in]betaThe right-hand input scalar.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [10/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the output vector.
MaskTypeThe value type of the output mask vector.
Parameters
[out]zThe output vector.
[in]maskThe output mask.
[in]xThe left-hand input vector.
[in]betaThe right-hand input scalar.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [11/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]xThe left-hand input vector.
[in]betaThe right-hand input scalar.
[in]monoidThe monoid that provides the operator \( \odot \).
[in]phaseThe 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() [12/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:
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
descrThe descriptor to be used. Equal to descriptors::no_operation if left unspecified.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the mask vector.
Parameters
[out]zThe output vector.
[out]maskThe output mask.
[in]xThe left-hand input vector.
[in]betaThe right-hand input scalar.
[in]monoidThe monoid that provides the operator \( \odot \).
[in]phaseThe 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() [13/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:
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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]xThe left-hand input vector.
[in]yThe right-hand input vector.
[in]opThe operator \( \odot \).
[in]phaseThe 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() [14/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:
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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
OPThe operator to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the output mask vector.
Parameters
[out]zThe output vector.
[in]maskThe output mask.
[in]xThe left-hand input vector.
[in]yThe right-hand input vector.
[in]opThe operator \( \odot \).
[in]phaseThe 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

◆ eWiseApply() [15/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:
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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
Parameters
[out]zThe output vector.
[in]xThe left-hand input vector.
[in]yThe right-hand input vector.
[in]monoidThe monoid structure that \( \odot \) corresponds to.
[in]phaseThe 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 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:
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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
MonoidThe monoid to use.
InputType1The value type of the left-hand vector.
InputType2The value type of the right-hand scalar.
OutputTypeThe value type of the ouput vector.
MaskTypeThe value type of the mask vector.
Parameters
[out]zThe output vector.
[in]maskThe output mask.
[in]xThe left-hand input vector.
[in]yThe right-hand input vector.
[in]monoidThe monoid structure that \( \odot \) corresponds to.
[in]phaseThe 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

◆ 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
Functhe user-defined lambda function type.
DataTypethe type of the user-supplied vector example.
backendthe backend type of the user-supplied vector example.
Parameters
[in]fThe 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]xThe 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,
const double beta,
) {
assert( grb::size(x) == grb::size(y) );
assert( grb::nnz(x) == grb::size(x) );
assert( grb::nnz(y) == grb::size(y) );
alpha = ring.getZero();
[&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 );

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(
const Operator op
) {
[&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 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output type.
Parameters
[out]zThe output vector of type OutputType.
[in]xThe left-hand input vector of type InputType1.
[in]yThe right-hand input vector of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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() [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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output type.
Parameters
[out]zThe output vector of type OutputType.
[in]alphaThe left-hand input scalar of type InputType1.
[in]yThe right-hand input vector of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output type.
Parameters
[out]zThe output vector of type OutputType.
[in]xThe left-hand input vector of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output type.
Parameters
[out]zThe output vector of type OutputType.
[in]alphaThe left-hand input scalar of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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() [5/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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output vector type.
MaskTypeThe output mask type.
Parameters
[in,out]zThe output vector of type OutputType.
[in]maskThe ouput mask of type MaskType.
[in]xThe left-hand input vector of type InputType1.
[in]yThe right-hand input vector of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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

◆ 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output vector type.
MaskTypeThe output mask type.
Parameters
[in,out]zThe output vector of type OutputType.
[in]maskThe ouput mask of type MaskType.
[in]alphaThe left-hand input scalar of type InputType1.
[in]yThe right-hand input vector of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output vector type.
MaskTypeThe output mask type.
Parameters
[in,out]zThe output vector of type OutputType.
[in]maskThe output mask of type MaskType.
[in]xThe left-hand input vector of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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 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
descrThe descriptor to be used. Optional; the default is grb::descriptors::no_operation.
RingThe semiring type to perform the element-wise multiply with.
InputType1The left-hand side input type.
InputType2The right-hand side input type.
OutputTypeThe output vector type.
MaskTypeThe output mask type.
Parameters
[in,out]zThe output vector of type OutputType.
[in]maskThe ouput mask of type MaskType.
[in]alphaThe left-hand input scalar of type InputType1.
[in]betaThe right-hand input scalar of type InputType2.
[in]ringThe generalized semiring under which to perform this element-wise multiplication.
[in]phaseThe 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

◆ foldl() [1/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
descrThe descriptor to be used (descriptors::no_operation if left unspecified).
MonoidThe monoid to use for reduction.
InputTypeThe type of the elements in the supplied ALP/GraphBLAS vector y.
IOTypeThe type of the output scalar x.
MaskTypeThe type of the elements in the supplied ALP/GraphBLAS vector mask.
Parameters
[out]xThe result of the reduction.
[in]yAny ALP/GraphBLAS vector. This vector may be sparse.
[in]maskAny ALP/GraphBLAS vector. This vector may be sparse.
[in]monoidThe 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() [2/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() [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.