The ALP/GraphBLAS namespace. More...

Namespaces
namespace	algorithms
	The namespace for ALP/GraphBLAS algorithms.

namespace	config
	Compile-time configuration constants as well as implementation details that are derived from such settings.

namespace	descriptors
	Collection of standard descriptors.

namespace	identities
	Standard identities common to many operators.

namespace	interfaces
	The namespace for programming APIs that automatically translate to ALP/GraphBLAS.

namespace	operators
	This namespace holds various standard operators such as grb::operators::add and grb::operators::mul.

Classes
class	Benchmarker
	A class that follows the API of the grb::Launcher, but instead of launching the given ALP program once, it launches it multiple times while benchmarking its execution times. More...

class	collectives
	A static class defining various collective operations on scalars. More...

struct	has_immutable_nonzeroes
	Used to inspect whether a given semiring has immutable nonzeroes under addition. More...

struct	is_associative
	Used to inspect whether a given operator or monoid is associative. More...

struct	is_commutative
	Used to inspect whether a given operator or monoid is commutative. More...

struct	is_container
	Used to inspect whether a given type is an ALP/GraphBLAS container. More...

struct	is_idempotent
	Used to inspect whether a given operator or monoid is idempotent. More...

struct	is_monoid
	Used to inspect whether a given type is an ALP monoid. More...

struct	is_object
	Used to inspect whether a given type is an ALP/GraphBLAS object. More...

struct	is_operator
	Used to inspect whether a given type is an ALP operator. More...

struct	is_semiring
	Used to inspect whether a given type is an ALP semiring. More...

class	Launcher
	A group of user processes that together execute ALP programs. More...

class	Matrix
	An ALP/GraphBLAS matrix. More...

class	Monoid
	A generalised monoid. More...

class	PinnedVector
	Provides a mechanism to access ALP containers from outside of an ALP context. More...

class	Semiring
	A generalised semiring. More...

class	spmd
	For backends that support multiple user processes this class defines some basic primitives to support SPMD programming. More...

class	Vector
	A GraphBLAS vector. More...

Typedefs
typedef unsigned int	Descriptor
	Descriptors indicate pre- or post-processing for some or all of the arguments to an ALP/GraphBLAS call.

Enumerations
enum	Backend { reference , reference_omp , hyperdags , shmem1D , NUMA1D , GENERIC_BSP , BSP1D , doublyBSP1D , BSP2D , autoBSP , optBSP , hybrid , hybridSmall , hybridMid , hybridLarge , minFootprint , banshee , banshee_ssr }
	A collection of all backends. More...

enum	EXEC_MODE { AUTOMATIC = 0 , MANUAL , FROM_MPI }
	The various ways in which the grb::Launcher can be used to execute an ALP program. More...

enum	IOMode { SEQUENTIAL = 0 , PARALLEL }
	The GraphBLAS input and output functionalities can either be used in a sequential or parallel fashion. More...

enum	Phase { RESIZE , TRY , EXECUTE }
	Primitives with sparse ALP/GraphBLAS output containers may run into the issue where an appropriate grb::capacity may not always be clear. More...

enum	RC { SUCCESS = 0 , PANIC , OUTOFMEM , MISMATCH , OVERLAP , OVERFLW , UNSUPPORTED , ILLEGAL , FAILED }
	Return codes of ALP primitives. More...

Functions
template<Descriptor descr = descriptors::no_operation, class OP , typename InputType1 , typename InputType2 , typename OutputType >
static enum RC	apply (OutputType &out, const InputType1 &x, const InputType2 &y, const OP &op=OP(), const typename std::enable_if< grb::is_operator< OP >::value &&!grb::is_object< InputType1 >::value &&!grb::is_object< InputType2 >::value &&!grb::is_object< OutputType >::value, void >::type *=nullptr)
	Out-of-place application of the operator OP on two data elements.

template<Descriptor descr = descriptors::no_operation, typename InputType , typename fwd_iterator1 = const size_t * __restrict__, typename fwd_iterator2 = const size_t * __restrict__, typename fwd_iterator3 = const InputType * __restrict__, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation > &A, fwd_iterator1 I, const fwd_iterator1 I_end, fwd_iterator2 J, const fwd_iterator2 J_end, fwd_iterator3 V, const fwd_iterator3 V_end, const IOMode mode)
	Assigns nonzeroes to the matrix from a coordinate format.

template<Descriptor descr = descriptors::no_operation, typename InputType , typename fwd_iterator1 = const size_t * __restrict__, typename fwd_iterator2 = const size_t * __restrict__, typename fwd_iterator3 = const InputType * __restrict__, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation > &A, fwd_iterator1 I, fwd_iterator2 J, fwd_iterator3 V, const size_t nz, const IOMode mode)
	Alias that transforms a set of pointers and an array length to the buildMatrixUnique variant based on iterators.

template<Descriptor descr = descriptors::no_operation, typename InputType , typename RIT , typename CIT , typename NIT , typename fwd_iterator , Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation, RIT, CIT, NIT > &A, fwd_iterator start, const fwd_iterator end, const IOMode mode)
	Version of buildMatrixUnique that works by supplying a single iterator (instead of three).

template<Descriptor descr = descriptors::no_operation, typename InputType , typename RIT , typename CIT , typename NIT , typename fwd_iterator1 = const size_t * __restrict__, typename fwd_iterator2 = const size_t * __restrict__, typename length_type = size_t, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation, RIT, CIT, NIT > &A, fwd_iterator1 I, fwd_iterator2 J, const length_type nz, const IOMode mode)
	Version of the above buildMatrixUnique that handles nullptr value pointers.

template<Descriptor descr = descriptors::no_operation, typename InputType , typename fwd_iterator , Backend backend, typename Coords >
RC	buildVector (Vector< InputType, backend, Coords > &x, fwd_iterator start, const fwd_iterator end, const IOMode mode)
	Constructs a dense vector from a container of exactly grb::size(x) elements.

template<Descriptor descr = descriptors::no_operation, typename InputType , class Merger = operators::right_assign< InputType >, typename fwd_iterator1 , typename fwd_iterator2 , Backend backend, typename Coords >
RC	buildVector (Vector< InputType, backend, Coords > &x, fwd_iterator1 ind_start, const fwd_iterator1 ind_end, fwd_iterator2 val_start, const fwd_iterator2 val_end, const IOMode mode, const Merger &merger=Merger())
	Ingests possibly sparse input from a container to which iterators are provided.

template<Descriptor descr = descriptors::no_operation, typename InputType , class Merger = operators::right_assign< InputType >, typename fwd_iterator1 , typename fwd_iterator2 , Backend backend, typename Coords >
RC	buildVectorUnique (Vector< InputType, backend, Coords > &x, fwd_iterator1 ind_start, const fwd_iterator1 ind_end, fwd_iterator2 val_start, const fwd_iterator2 val_end, const IOMode mode)
	Ingests a set of nonzeroes into a given vector x.

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
size_t	capacity (const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
	Queries the capacity of the given ALP/GraphBLAS container.

template<typename InputType , Backend backend, typename Coords >
size_t	capacity (const Vector< InputType, backend, Coords > &x) noexcept
	Queries the capacity of the given ALP/GraphBLAS container.

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
RC	clear (Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
	Clears a given matrix of all nonzeroes.

template<typename DataType , Backend backend, typename Coords >
RC	clear (Vector< DataType, backend, Coords > &x) noexcept
	Clears a given vector of all nonzeroes.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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 using any number of vectors of equal length, following the nonzero pattern of the given vector x.

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.

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.

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.

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.

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.

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.

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.

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.

template<enum Backend backend = config::default_backend>
RC	finalize ()
	Finalises an ALP/GraphBLAS context opened by the last call to grb::init.

template<Descriptor descr = descriptors::no_operation, class OP , typename InputType , typename IOType >
static RC	foldl (IOType &x, const InputType &y, const OP &op=OP(), const typename std::enable_if< grb::is_operator< OP >::value &&!grb::is_object< InputType >::value &&!grb::is_object< IOType >::value, void >::type *=nullptr)
	Application of the operator OP on two data elements.

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.

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.

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.

template<Descriptor descr = descriptors::no_operation, class OP , typename InputType , typename IOType >
static RC	foldr (const InputType &x, IOType &y, const OP &op=OP(), const typename std::enable_if< grb::is_operator< OP >::value &&!grb::is_object< InputType >::value &&!grb::is_object< IOType >::value, void >::type *=nullptr)
	Application of the operator OP on two data elements.

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.

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.

template<typename ElementType , typename RIT , typename CIT , typename NIT , Backend implementation = config::default_backend>
uintptr_t	getID (const Matrix< ElementType, implementation, RIT, CIT, NIT > &x)
	Specialisation of getID for matrix containers.

template<typename ElementType , typename Coords , Backend implementation = config::default_backend>
uintptr_t	getID (const Vector< ElementType, implementation, Coords > &x)
	Function that returns a unique ID for a given non-empty container.

template<enum Backend backend = config::default_backend>
RC	init ()
	Initialises the calling user process.

template<enum Backend backend = config::default_backend>
RC	init (const size_t s, const size_t P, void *const implementation_data)
	Initialises the calling user process.

template<Descriptor descr = descriptors::no_operation, typename OutputType , typename InputType1 , typename InputType2 , typename CIT , typename RIT , typename NIT , class Semiring , Backend backend>
RC	mxm (Matrix< OutputType, backend, CIT, RIT, NIT > &C, const Matrix< InputType1, backend, CIT, RIT, NIT > &A, const Matrix< InputType2, backend, CIT, RIT, NIT > &B, const Semiring &ring=Semiring(), const Phase &phase=EXECUTE)
	Unmasked and in-place sparse matrix–sparse matrix multiplication (SpMSpM), \( C += A+B \).

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

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

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

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

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

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

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
size_t	ncols (const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
	Requests the column size of a given matrix.

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
size_t	nnz (const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
	Retrieve the number of nonzeroes contained in this matrix.

template<typename DataType , Backend backend, typename Coords >
size_t	nnz (const Vector< DataType, backend, Coords > &x) noexcept
	Request the number of nonzeroes in a given vector.

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
size_t	nrows (const Matrix< InputType, backend, RIT, CIT, NIT > &A) noexcept
	Requests the row size of a given matrix.

template<typename InputType , Backend backend, typename RIT , typename CIT , typename NIT >
RC	resize (Matrix< InputType, backend, RIT, CIT, NIT > &A, const size_t new_nz) noexcept
	Resizes the nonzero capacity of this matrix.

template<typename InputType , Backend backend, typename Coords >
RC	resize (Vector< InputType, backend, Coords > &x, const size_t new_nz) noexcept
	Resizes the nonzero capacity of this vector.

template<Descriptor descr = descriptors::no_operation, typename DataType , typename T , typename Coords , Backend backend>
RC	set (Vector< DataType, backend, Coords > &x, const T val, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< DataType >::value &&!grb::is_object< T >::value, void >::type *const =nullptr) noexcept
	Sets all elements of a vector to the given value.

template<Descriptor descr = descriptors::no_operation, typename DataType , typename MaskType , typename T , Backend backend, typename Coords >
RC	set (Vector< DataType, reference, Coords > &x, const Vector< MaskType, backend, Coords > &mask, const T val, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< DataType >::value &&!grb::is_object< T >::value, void >::type *const =nullptr)
	Sets all elements of a vector to the given value whenever the given mask evaluates `true`.

template<Descriptor descr = descriptors::no_operation, typename OutputType , typename InputType , Backend backend, typename Coords >
RC	set (Vector< OutputType, backend, Coords > &x, const Vector< InputType, backend, Coords > &y, const Phase &phase=EXECUTE)
	Sets the content of a given vector x to be equal to that of another given vector y.

template<Descriptor descr = descriptors::no_operation, typename OutputType , typename MaskType , typename InputType , Backend backend, typename Coords >
RC	set (Vector< OutputType, backend, Coords > &x, const Vector< MaskType, backend, Coords > &mask, const Vector< InputType, backend, Coords > &y, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< OutputType >::value &&!grb::is_object< MaskType >::value &&!grb::is_object< InputType >::value, void >::type *const =nullptr)
	Sets the content of a given vector x to be equal to that of another given vector y.

template<Descriptor descr = descriptors::no_operation, typename DataType , typename T , Backend backend, typename Coords >
RC	setElement (Vector< DataType, backend, Coords > &x, const T val, const size_t i, const Phase &phase=EXECUTE, const typename std::enable_if< !grb::is_object< DataType >::value &&!grb::is_object< T >::value, void >::type *const =nullptr)
	Sets the element of a given vector at a given position to a given value.

template<typename DataType , Backend backend, typename Coords >
size_t	size (const Vector< DataType, backend, Coords > &x) noexcept
	Request the size of a given vector.

std::string	toString (const RC code)

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

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

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

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

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

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

template<Backend backend = config::default_backend>
RC	wait ()
	Depending on the backend, ALP/GraphBLAS primitives may be non-blocking, meaning that the operation immediately returns even though the requested computation has not been performed.

template<Backend backend, typename InputType , typename RIT , typename CIT , typename NIT , typename... Args>
RC	wait (const Matrix< InputType, backend, RIT, CIT, NIT > &A, const Args &... args)
	A variant of grb::wait that executes, at minimum, all nonblocking primitives required for computing a given output matrix as well as, optionally, for any additional output containers given in the variadic argument list.

template<Backend backend, typename InputType , typename Coords , typename... Args>
RC	wait (const Vector< InputType, backend, Coords > &x, const Args &... args)
	A variant of grb::wait that executes, at minimum, all nonblocking primitives required for computing a given output vector as well as, optionally, for any additional output containers given in the variadic argument list.

template<Descriptor descr = descriptors::no_operation, typename OutputType , typename InputType1 , typename InputType2 , typename InputType3 , typename RIT , typename CIT , typename NIT , Backend backend, typename Coords >
RC	zip (Matrix< OutputType, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Vector< InputType3, backend, Coords > &z, const Phase &phase=EXECUTE)
	The grb::zip merges three vectors into a matrix.

template<Descriptor descr = descriptors::no_operation, typename InputType1 , typename InputType2 , typename InputType3 , typename RIT , typename CIT , typename NIT , Backend backend, typename Coords >
RC	zip (Matrix< void, backend, RIT, CIT, NIT > &A, const Vector< InputType1, backend, Coords > &x, const Vector< InputType2, backend, Coords > &y, const Phase &phase=EXECUTE)
	Merges two vectors into a `void` matrix.

Detailed Description

The ALP/GraphBLAS namespace.

All ALP/GraphBLAS primitives, container types, algebraic structures, and type traits are defined within.

Typedef Documentation

◆ Descriptor

typedef unsigned int Descriptor

Descriptors indicate pre- or post-processing for some or all of the arguments to an ALP/GraphBLAS call.

An example is to transpose the input matrix during a sparse matrix–vector multiplication: grb::mxv< grb::descriptors::transpose_matrix >( y, A, x, ring ); the above thus computes \( y \to y + A^Tx \) and not \( y \to y + Ax \).

Such pre-processing often happens on-the-fly, without significant overhead to the primitive costings in any of its cost dimensions – work, intra- and inter-process data movement, synchronisations, and memory usage.

Note: If the application of a descriptor is not without significant overhead, a backend must clearly indicate so.

Descriptors may be combined using bit-wise operators. For instance, to both indicate the matrix needs be transposed and the mask needs be inverted, the following descriptor can be passed: transpose_matrix | invert_mask

Enumeration Type Documentation

◆ EXEC_MODE

enum EXEC_MODE

The various ways in which the grb::Launcher can be used to execute an ALP program.

Warning: An implementation may require different linker commands when using different modes.; Depending on the mode given to grb::Launcher, the parameters required for the exec function may differ.

Note: However, the ALP program is unaware of which mode is the launcher employs and will not have to change.

Enumerator

AUTOMATIC

Automatic mode.

The grb::Launcher can spawn user processes which will execute a given program.

MANUAL

Manual mode.

The user controls nprocs user processes which together should execute a given program, by, for example, using the grb::Launcher.

FROM_MPI

When running from an MPI program.

The user controls nprocs MPI programs, which, together, should execute a given ALP program.

◆ IOMode

enum IOMode

The GraphBLAS input and output functionalities can either be used in a sequential or parallel fashion.

Input functions such as buildVector or buildMatrixUnique default to sequential behaviour, which means that the collective calls to either function must have the exact same arguments– that is, each user process is passed the exact same input data.

Note: This does not necessarily mean that all data is stored in a replicated fashion across all user processes.

This default behaviour comes with obvious performance penalties; each user process must scan the full input data set, which takes \( \Theta( n ) \) time. Scalable behaviour would instead incur \( \Theta( n / P ) \) time, with P the number of user processes. Using a parallel IOMode provides exactly this scalable performance. On input, this means that each user process can pass different data to the same collective call to, e.g., buildVector or buildMatrixUnique.

For output, which GraphBLAS provides via const iterators, sequential mode means that each user process retrieves an iterator over all output elements– this requires costly all-to-all communication. Parallel mode output instead only returns those elements that do not require inter user- process communication.

Note: It is guaranteed the union of all output over all user processes corresponds to all elements in the GraphBLAS container.

See the respective functions and classes for full details:

Enumerator

SEQUENTIAL

Sequential mode IO.

Use of this mode results in non-scalable input and output. Its use is recommended only in case of small data sets or in one-off situations.

PARALLEL

Parallel mode IO.

Use of this mode results in fully scalable input and output. Its use is recommended as a default. Note that this does require the user to have his or her data distributed over the various user processes on input, and requires the user to handle distributed data on output.

This is the default mode on all GraphBLAS IO functions.

Note: The parallel mode in situations where the number of user processes is one, for instance when choosing a sequential or data-centric GraphBLAS implementation, IOMode::parallel is equivalent to IOMode::sequential.

◆ Phase

enum Phase

Primitives with sparse ALP/GraphBLAS output containers may run into the issue where an appropriate grb::capacity may not always be clear.

This is classically the case for level-3 sparse BLAS primitives, which commonly is solved by splitting up the computation into a symbolic and numeric phase. During the symbolic phase, the computation is simulated in order to derive the required capacity of the output container, which is then immediately resized. Then during the numeric phase, the actual computation is carried out, knowing that the output container is large enough to hold the requested output.

A separation in a symbolic and numeric phase is not the only possible split; for example, required output capacities may be estimated during a first stage, while a second stage will then dynamically allocate additional memory if the estimation proved too optimistic.

We recognise that:

not only level-3 primitives may require a two-stage approach– for example, a backend could be designed to support extremely large-sized vectors that contains relatively few nonzeroes, in which case also level-1 and level-2 primitives may benefit of symbolic and numeric phases.
especially for level-1 and level-2 primitives, it may also be that single-phase approaches are feasible. Hence ALP/GraphBLAS defines that the execute phase, grb::EXECUTE, is the default when calling an ALP/GraphBLAS primitive without an explicit phase argument.
sometimes speculative execution is warranted; these apply to situations where
1. capacities are almost surely sufficient, and
2. partial results, if the full output could not be computed due to capacity issues, are in fact acceptable.

To cater to a wide range of approaches and use cases, we support the following three phases:

grb::RESIZE, which resizes capacities based on the requested operation;
grb::EXECUTE, which attempts to execute the computation assuming the capacity is sufficient;
grb::TRY, which attempts to execute the computation, and does not mind if the capacity turns out to be insufficient.

Backends must give precise performance semantics to primitives executing in each of the three possible phases. Backends can only fail with grb::OUTOFMEM or grb::PANIC when an operation is called using the resize phase and is immediately followed by an equivalent call using the execute phase– otherwise, it must succeed and complete the requested computation.

Summarising the above, a call to any ALP/GraphBLAS primitive f with (potentially sparse) output container A can be made in three ways:

f( A, ..., EXECUTE ), which shall always be successful if it somehow is guaranteed that A has enough capacity prior to the call. If A did not have enough capacity, the call to f shall fail and the contents of A, after function exit, shall be cleared.
a successful call to f( A, ..., RESIZE ) shall guarantee that a following call to f( A, ..., EXECUTE ) is successful;
a call to f( A, ..., TRY ), which may or may not succeed. If the call does not succeed, then A, after function exit:
1. contains exactly grb::capacity (of A) nonzeroes;
2. has nonzeroes at the coordinates where A on entry had nonzeroes;
3. has nonzeroes with values equal to those that would have been computed at its coordinates were the call successul; and
4. does not have computed all nonzeroes that would have been present if the call were successful (or otherwise it should have returned grb::SUCCESS).

Note: Calls can typically also return grb::PANIC, which, if returned, makes undefined the contents of all ALP/GraphBLAS containers as well as makes undefined the state of ALP/GraphBLAS as a whole.

The following code snippets, assuming all unchecked return codes are grb::SUCCESS, thus are semantically equivalent:

// default capacity of A is sufficient for \a f to succeed

f( A, ..., EXECUTE );

grb::EXECUTE

@ EXECUTE

Speculatively assumes that the output container of the requested operation has enough capacity to com...

Definition: phase.hpp:257

if( resize( A, sufficient_capacity_for_output_of_f ) == SUCCESS ) {
   f( A, ..., EXECUTE );
}

if( f( A, ..., RESIZE ) == SUCCESS ) {
    f( A, ..., EXECUTE );
}

resize( B, nnz( A ) );
set( B, A );
if( f( A, ..., EXECUTE ) == FAILED ) {
    f( B, ..., RESIZE );
    std::swap( A, B );
}

resize( B, nnz( A ) );
set( B, A );
while( f( A, ..., EXECUTE ) == FAILED ) {
    resize( A, capacity( A ) + 1 );
    set( A, B );
}

Note: If the matrix A is empty on entry, then the latter two code snippets do not require the use B as a temporary buffer.; Since grb::EXECUTE is the default phase, any occurrance of f( A, ..., EXECUTE ) may be replaced with f( A, ... ).

The above code snippets do not include try phases since whenever output containers do not have enough capacity, primitives executed using grb::TRY will not generate equivalent results.

Enumerator

RESIZE

Speculatively assumes that the output container(s) of the requested operation lack the necessary capacity to hold all outputs of the computation.

Instead of executing the requested operation, this phase attempts to both estimate and resize the output container(s).

A successful call using this phase guarantees that a subsequent and equivalent call using the grb::EXECUTE phase shall be successful.

Here, an equivalent call means that the operation must be called with exactly the same arguments, except for the grb::Phase argument.

Here, subsequent means that all involved containers are not arguments to any other ALP/GraphBLAS primitives prior to the final call that requests the execute phase.

Different from grb::resize, calling operations using the resize phase does not modify the contents of output containers, and may only enlargen capacities– not shrink them.

Note: This specification does not disallow implementations or backends that perform part of the computation during the resize phase. Any such behaviour is totally optional for implementations and backends. However, any progress made in such manner must remain hidden from the user since output container contents must not be modified by primitives executing a resize phase.

A backend must define clear performance semantics for each primitive and for each phase that primitive can be called with. In particular, backends must specify whether system calls such as dynamic memory allocations or frees may occur, and whether primtives operating in a resize phase may return grb::OUTOFMEM.

TRY

Speculatively assumes that the output container of the requested operation has enough capacity to complete the computation, and attempts to do so.

If the capacity was indeed found to be sufficient, then the computation must complete as specified– unless grb::PANIC is returned.

If, nevertheless, capacity was not sufficient then the result of the computation is incomplete and the primitive shall return grb::FAILED. Regarding each output container A, the following are guaranteed:

the capacity of A remains unchanged;
contains grb::capacity (of A) nonzeroes;
has nonzeroes at the coordinates where A on entry had nonzeroes;
has nonzeroes with values equal to those that would have been computed at its coordinates were the call successul; and
does not contain all nonzeroes that would have been present in A were the call successful (or otherwise grb::SUCCESS would have been returned instead).

Warning: If execution failed, then even though the semantics guarantee valid partial output, there generally is no way to recover the full output without re-initiating the full computation. In other words, this mechanism does not allow for the partial computation to complete the remainder computation using less effort than the full computation would have required. This is the main difference with the grb::EXECUTE phase.

Note: This phase is particularly useful if partial output is still usable and recomputation to generate the full output is not required.

A backend must define clear performance semantics for each primitive and for each phase that primitive can be called with.

Warning: The try phase is current experimental and not broadly supported in the reference implementation.

EXECUTE

Speculatively assumes that the output container of the requested operation has enough capacity to complete the computation, and attempts to do so.

If the capacity was indeed found to be sufficient, then the computation must complete as specified. In this case, capacities are additionally not allowed to be modified by the call to the primitive using the execute phase.

If, instead, the output container capacity was found to be insufficient, then the requested operation may return grb::FAILED, in which case the contents of output containers shall be cleared.

Note: That on failure a primitive called using the execute phase may destroy any pre-existing contents of output containers is a critical difference with the grb::TRY phase.

Warning: When calling ALP/GraphBLAS primitives without specifying a phase explicitly, this execute phase will be assumed by default.

A backend must define clear performance semantics for each primitive and for each phase that primitive can be called with. In particular, backends must specify whether system calls such as dynamic memory allocations or frees may occur, and whether primtives operating in a resize phase may return grb::OUTOFMEM.

Note: Typically, implementations and backends are advised to specify no system calls and in particular dynamic memory management calls are allowed as part of an execute phase.

◆ RC

enum RC

Return codes of ALP primitives.

All primitives that are not getters return one of the codes defined here. All primitives may return SUCCESS, and all primitives may return PANIC. All other error codes are optional– please see the description of each primitive which other error codes may be valid.

For core ALP primitives, any non-SUCCESS and non-PANIC error code shall have no side effects; if a call fails, it shall be as though the call was never made.

Enumerator
SUCCESS	Indicates the primitive has executed successfully. All primitives may return this error code.
PANIC	Generic fatal error code. Signals that ALP has entered an undefined state. Users can only do their best to exit their application gracefully once PANIC has been encountered. An implementation (backend) is encouraged to write clear error messages to stderr prior to returning this error code. All primitives may return this error code even if not explicitly documented.
OUTOFMEM	Signals an out-of-memory error while executing the requested primitive. User can mitigate by freeing memory and retrying the call or by reducing the amount of memory required by this call. This error code may only be returned when explicitly documented as such.
MISMATCH	One or more of the ALP/GraphBLAS objects passed to the primitive that returned this error have mismatching dimensions. User can mitigate by reissuing with correct parameters. It is usually not possible to mitigate at run-time; more often than not, this error signals a logical programming error. This error code may only be returned when explicitly documented as such.
OVERLAP	One or more of the GraphBLAS objects corresponding to the call returning this error refer to the same object while this explicitly is forbidden. Deprecated: This error code will be replaced with ILLEGAL. User can mitigate by reissuing with correct parameters. It is usually not possible to mitigate at run-time; more often than not, this error signals a logical programming error. This error code may only be returned when explicitly documented as such, but note the deprecation message– any uses of OVERLAP will be replaced with ILLEGAL before v1.0 is released.
OVERFLW	Indicates that execution of the requested primitive with the given arguments would result in overflow. Users can mitigate by modifying the offending call. It is usually not possible to mitigate at run-time; more often than not, this error signals the underlying problem is too large to handle with whatever current resources have been assigned to ALP. This error code may only be returned when explicitly documented as such.
UNSUPPORTED	Indicates that the execution of the requested primitive with the given arguments is not supported by the selected backend. This error code should never be returned by a fully compliant backend. If encountered, the end-user may mitigate by selecting a different backend.
ILLEGAL	A call to a primitive has determined that one of its arguments was illegal as per the specification of the primitive. User can mitigate by reissuing with correct parameters. It is usually not possible to mitigate at run-time; more often than not, this error signals a logical programming error. This error code may only be returned when explicitly documented as such; in other words, the specification precisely determines which (combinations of) inputs are illegal.
FAILED	Indicates when one of the grb::algorithms has failed to achieve its intended result, for instance, when an iterative method failed to converged within its alloted resources. This error code may only be returned when explicitly documented as such, and may never be returned by core ALP primitives– it is reserved for use by algorithms only.

Function Documentation

◆ finalize()

RC finalize ( )

Finalises an ALP/GraphBLAS context opened by the last call to grb::init.

Deprecated:: Please use grb::Launcher instead. This primitive will be removed from verson 1.0 onwards.

This function must be called collectively and must follow a call to grb::init. After successful execution of this function, a new call to grb::init may be made. (This function is re-entrant.)

After a call to this function, any ALP/GraphBLAS objects that remain in scope become invalid.

Warning: Invalid ALP/GraphBLAS containers will remain invalid no matter if a next call to grb::init is made.

Template Parameters

backend Which ALP/GraphBLAS backend to finalise.

Returns: SUCCESS If finalisation was successful.; PANIC If this function fails, the state of the ALP/GraphBLAS implementation becomes undefined. This means none of its functions should be called during the remainder program execution; in particular this means a new call to grb::init will not remedy the situation.

Performance semantics: None. Implementations are encouraged to specify the complexity of their implementation of this function in terms of the parameter P the matching call to grb::init was called with.

Warning: This primitive has been deprecated since version 0.5. Please update your code to use the grb::Launcher instead.

◆ init() [1/2]

RC init ( )

Initialises the calling user process.

Deprecated:: Please use grb::Launcher instead. This primitive will be removed from verson 1.0 onwards.

This variant takes no input arguments. It will assume a single user process exists; i.e., the call is equivalent to one to grb::init with s zero and P one (and implementation_data NULL).

Template Parameters

backend The backend implementation to initialise.

Returns: SUCCESS If the initialisation was successful.; PANIC If returned, the state of the ALP library becomes undefined.

Warning: This primitive has been deprecated since version 0.5. Please update your code to use the grb::Launcher instead.

◆ init() [2/2]

RC init	(	const size_t	s,
		const size_t	P,
		void *const	implementation_data
	)

Initialises the calling user process.

Deprecated:: Please use grb::Launcher instead. This primitive will be removed from verson 1.0 onwards.

Template Parameters

backend Which GraphBLAS backend this call to init initialises.

By default, the backend that is selected by the user at compile-time is used. If no backend was selected, grb::reference is assumed.

Parameters

[in]	s	The ID of this user process.
[in]	P	The total number of user processes.

If the backend supports multiple user processes, the user can invoke this function with P equal to one or higher; if the backend supports only a single user process, then P must equal one.

The value for the user process ID s must be larger or equal to zero and must be strictly smaller than P. If P > 1, each user process must call this function collectively, each user process should pass the same value for P, and each user process should pass a unique value for s amongst all P collective calls made.

Parameters

[in] implementation_data Any implementation-defined data structure required for successful completion of this call.

An implementation may define that additional data is required for a call to this function to complete successfully. Such data may be passed via the final argument to this function, implementation_data.

If the implementation does not support multiple user processes, then a value for implementation_data shall not be required. In particular, a call to this function with an empty parameter list shall then be legal and infer the following default arguments: zero for s, one for P, and NULL for implementation_data. When such an implementation is requested to initialise multiple user processes, then grb::UNSUPPORTED shall be returned.

A call to this function must be matched with a call to grb::finalize. After a successful call to this function, a new call to grb::init without first calling grb::finalize shall incur undefined behaviour. The construction of ALP/GraphBLAS containers without a preceding successful call to grb::init will result in undefined behaviour. Any valid GraphBLAS containers will become invalid after a call to grb::finalize.

Returns: SUCCESS If the initialisation was successful.; UNSUPPORTED When the implementation does not support multiple user processes while the given P was larger than 1.; PANIC If returned, the state of the ALP library becomes undefined.

After a call to this function that exits with a non-SUCCESS and non-PANIC error code, the program shall behave as though the call were never made.

Note: There is no argument checking. If s is larger or equal to P, undefined behaviour occurs. If implementation_data was invalid or corrupted, undefined behaviour occurs.

Performance semantics: Implementations and backends must specify the complexity of this function in terms of P.

Note: Compared to the GraphBLAS C specification, this function lacks a choice whether to execute in ‘blocking’ or ‘non-blocking’ mode. With ALP, the selected backend controls whether execution proceeds in a non-blocking manner or not. Thus selecting a blocking backend for compilation results in the application of blocking semantics, while selecting a non-blocking backend results in the application of non- blocking semantics.; Note that in the GraphBLAS C specification, a blocking mode is a valid implementation of a non-blocking mode. Therefore, this specification will still yield a valid C API implementation when properly wrapping around a blocking ALP/GraphBLAS backend.; This specification allows for grb::init to be called multiple times from the same process and the same thread. The parameters s and P (and implementation_data) may differ each time. Each (repeated) call must of course continue to meet all the above requirements.; The GraphBLAS C API does not have the notion of user processes. We believe this notion is necessary to properly integrate into parallel frameworks, and also to affect proper and efficient parallel I/O.

Warning: This primitive has been deprecated since version 0.5. Please update your code to use the grb::Launcher instead.

◆ toString()

std::string toString ( const RC code )

Returns: A string describing the given error code.

Namespaces

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ Descriptor

Enumeration Type Documentation

◆ EXEC_MODE

◆ IOMode

◆ Phase

◆ RC

Function Documentation

◆ finalize()

◆ init() [1/2]

◆ init() [2/2]

◆ toString()