Provides functions for putting user data into opaque ALP/GraphBLAS containers, provides functions for extracting data from such containers, and provides query as well resizing functionalities. More...

Classes
class	PinnedVector< IOType, implementation >
	Provides a mechanism to access ALP containers from outside of an ALP context. More...

Functions
template<Descriptor descr = descriptors::no_operation, typename InputType , typename RIT , typename CIT , typename NIT , typename fwd_iterator1 = const RIT * __restrict__, typename fwd_iterator2 = const CIT * __restrict__, typename fwd_iterator3 = const InputType * __restrict__, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation, RIT, CIT, NIT > &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. More...

template<Descriptor descr = descriptors::no_operation, typename InputType , typename RIT , typename CIT , typename NIT , typename fwd_iterator1 = const RIT * __restrict__, typename fwd_iterator2 = const CIT * __restrict__, typename fwd_iterator3 = const InputType * __restrict__, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation, RIT, CIT, NIT > &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_iterator1 = const RIT * __restrict__, typename fwd_iterator2 = const CIT * __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 RIT , typename CIT , typename NIT , typename fwd_iterator1 = const RIT * __restrict__, typename fwd_iterator2 = const CIT * __restrict__, Backend implementation = config::default_backend>
RC	buildMatrixUnique (Matrix< InputType, implementation, RIT, CIT, NIT > &A, fwd_iterator1 I, const fwd_iterator1 I_end, fwd_iterator2 J, const fwd_iterator2 J_end, const IOMode mode)
	Version of the above buildMatrixUnique that handles nullptr value pointers.

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). More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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`. More...

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

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

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

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

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

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

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

Detailed Description

Provides functions for putting user data into opaque ALP/GraphBLAS containers, provides functions for extracting data from such containers, and provides query as well resizing functionalities.

ALP/GraphBLAS operates on opaque data objects. Users can input data using grb::buildVector and/or grb::buildMatrix.

The standard output methods are provided by grb::Vector::cbegin and grb::Vector::cend, and similarly for grb::Matrix. Iterators provide parallel output (see IOMode for a discussion on parallel versus sequential IO).

Sometimes it is desired to have direct access to ALP/GraphBLAS memory area, and to have that memory available even after the ALP/GraphBLAS context has been destroyed. This functionality is provided by the concept of pinned containers such as provided by grb::PinnedVector.

Containers may be instantiated with default or given requested capacities. Implementations may reserve a higher capacity, but must allocate at least the requested amount or otherwise raise an out-of-memory error.

Capacities are always expressed in terms of number of nonzeroes that the container can hold. Current capacities of container instances can be queried using grb::capacity. At any point in time, the actual number of nonzeroes held within a container is given by grb::nnz and must be less than the reported capacity.

To remove all nonzeroes from a container, see grb::clear. The use of this function does not affect a container's capacity.

Capacities can be resized after a container has been instantiated by use of grb::resize. Smaller capacities may or may not yield a reduction of memory used – this depends on the implementation, and specifically on the memory usage semantics it defines.

After instantiation, the size of a container cannot be modified. The size is retrieved through grb::size for vectors, and through grb::nrows as well as grb::ncols for matrices.

In the above, implementation can also be freely substituted with backend, in that a single implementation can provide multiple backends that define different performance and memory semantics.

Function Documentation

◆ buildMatrixUnique() [1/2]

RC grb::buildMatrixUnique	(	Matrix< InputType, implementation, RIT, CIT, NIT > &	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.

Invalidates any prior existing content. Disallows different nonzeroes to have the same row and column coordinates; input must consist out of unique triples.

Warning: Calling this function with duplicate input coordinates will lead to undefined behaviour.

Template Parameters

descr	The descriptor used. The default is grb::descriptors::no_operation, which means that no pre- or post-processing of input or input is performed.
fwd_iterator1	The type of the row index iterator.
fwd_iterator2	The type of the column index iterator.
fwd_iterator3	The type of the nonzero value iterator.
length_type	The type of the number of elements in each iterator.

Parameters

[out]	A	Where to store the given nonzeroes.
[in]	I	A forward iterator to cap row indices.
[in]	J	A forward iterator to cap column indices.
[in]	V	A forward iterator to cap nonzero values.
[in]	I_end	A forward iterator in end position relative to I.
[in]	J_end	A forward iterator in end position relative to J.
[in]	V_end	A forward iterator in end position relative to V.

The iterators will only be used to read from, never to assign to.

Parameters

[in] mode Whether the input should happen in grb::SEQUENTIAL or in the grb::PARALLEL mode.

In the below, let nz denote the number of items pointed to by the iterator pair I, I_end. This number should match the number of elements in J, J_end and V, V_end.

Returns: grb::SUCCESS When the function completes successfully.; grb::MISMATCH When an element from I dereferences to a value larger than the row dimension of this matrix, or when an element from J dereferences to a value larger than the column dimension of this matrix. When this error code is returned the state of this container will be as though this function was never called; however, the given forward iterators may have been copied and the copied iterators may have incurred multiple increments and dereferences.; grb::OVERFLW When the internal data type used for storing the number of nonzeroes is not large enough to store the number of nonzeroes the user wants to assign. When this error code is returned the state of this container will be as though this function was never called; however, the given forward iterators may have been copied and the copied iterators may have incurred multiple increments and dereferences.

Warning: This is an expensive function. Use sparingly and only when absolutely necessary.

Note: Streaming input can be implemented by supplying buffered iterators to ALP.; The functionality herein described is exactly that of buildMatrix, though with stricter input requirements. These requirements allow much faster construction.; No masked version of this variant is provided. The use of masks in matrix construction is costly and the user is referred to the costly buildMatrix() function instead.

Performance semantics:

each backend must define performance semantics for this primitive.

See also: Performance Semantics

Allowed descriptors:: None.

◆ buildMatrixUnique() [2/2]

RC grb::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).

This is useful in cases where the input is given as a single struct per nonzero, whatever this struct may be exactly, as opposed to multiple containers for row indices, column indices, and nonzero values.

This GraphBLAS implementation provides both input modes since which one is more appropriate (and performant!) depends mostly on how the data happens to be stored in practice.

Template Parameters

descr	The currently active descriptor.
InputType	The value type the output matrix expects.
fwd_iterator	The iterator type.
implementation	For which backend a matrix is being read.

The iterator fwd_iterator, in addition to being STL-compatible, must support the following three public functions:

S fwd_iterator.i(); which returns the row index of the current nonzero;
S fwd_iterator.j(); which returns the columnindex of the current nonzero;
V fwd_iterator.v(); which returns the nonzero value of the current nonzero.

It also must provide the following public typedefs:

fwd_iterator::RowIndexType
fwd_iterator::ColumnIndexType
fwd_iterator::ValueType

This means a specialised iterator is required for use with this function. See, for example, grb::utils::internal::MatrixFileIterator.

Parameters

[out]	A	The matrix to be filled with nonzeroes from start to end.
[in]	start	Iterator pointing to the first nonzero to be added.
[in]	end	Iterator pointing past the last nonzero to be added.
[in]	mode	Whether the input should happen in grb::SEQUENTIAL or in the grb::PARALLEL mode.

◆ buildVector() [1/2]

RC grb::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.

This function aliases to the buildVector routine that takes an accumulator, using grb::operators::right_assign (thus overwriting any old contents).

◆ buildVector() [2/2]

RC grb::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.

This function dispatches to the buildVector routine that includes an accumulator, here set to grb::operators::right_assign. Any existing values in x that overlap with newer values will hence be overwritten.

◆ buildVectorUnique()

RC grb::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.

Old values will be overwritten. The given set of nonzeroes must not contain duplicate nonzeroes that should be stored at the same index.

Warning: Inputs with duplicate nonzeroes when passed into this function will invoke undefined behaviour.

Parameters

[in,out]	x	The vector where to ingest nonzeroes into.
[in]	ind_start	Start iterator to the nonzero indices.
[in]	ind_end	End iterator to the nonzero indices.
[in]	val_start	Start iterator to the nonzero values.
[in]	val_end	End iterator to the nonzero values.
[in]	mode	Whether sequential or parallel ingestion is requested.

The containers the two iterator pairs point to must contain an equal number of elements. Any pre-existing nonzeroes that do not overlap with any nonzero between ind_start and ind_end will remain unchanged.

Returns: grb::SUCCESS When ingestion has completed successfully.; grb::ILLEGAL When a nonzero has an index larger than grb::size.; grb::PANIC If an unmitigable error has occured during ingestion.

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

See also: Performance Semantics

◆ capacity() [1/2]

size_t grb::capacity ( const Vector< InputType, backend, Coords > & x )

noexcept

Queries the capacity of the given ALP/GraphBLAS container.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] x The vector whose capacity is requested.

A call to this function shall always succeed and shall never throw exceptions.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of x unchanged.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; Backends thus are forced to cache current cacacities and immediately return those. By RAII principles, given containers on account of being instantiated, must have a capacity that can be immediately returned.

◆ capacity() [2/2]

size_t grb::capacity ( const Matrix< InputType, backend, RIT, CIT, NIT > & A )

noexcept

Queries the capacity of the given ALP/GraphBLAS container.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] A The matrix whose capacity is requested.

A call to this function shall always succeed and shall never throw exceptions.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of A untouched.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; Backends thus are forced to cache current cacacities and immediately return those. By RAII principles, given containers on account of being instantiated, must have a capacity that can be immediately returned.

◆ clear() [1/2]

RC grb::clear ( Vector< DataType, backend, Coords > & x )

noexcept

Clears a given vector of all nonzeroes.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in,out] x The vector of which to remove all values.

A call to this function shall always succeed and shall never throw exceptions. That clearing a container should never fail is also an implied requirement of the specification of grb::resize.

On function exit, this vector contains zero nonzeroes. The vector size as well as its nonzero capacity remain unchanged.

Returns: grb::SUCCESS This function cannot fail.

Warning: Calling clear may not free any dynamically allocated memory associated with x. None of the present backends in fact do so.

Note: Even grb::resize may or may not free dynamically allocated memory associated with x– depending on the memory usage semantics defined on a per-backend basis, this is optional.; Only the destruction of x would ensure all corresponding memory is freed, for all backends.

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

See also: Performance Semantics

◆ clear() [2/2]

RC grb::clear ( Matrix< InputType, backend, RIT, CIT, NIT > & A )

noexcept

Clears a given matrix of all nonzeroes.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in,out] A The matrix of which to remove all nonzero values.

A call to this function shall always succeed and shall never throw exceptions. That clearing a container should never fail is also an implied requirement of the specification of grb::resize.

On function exit, this matrix contains zero nonzeroes. The matrix dimensions (i.e., row and column sizes) as well as the nonzero capacity remains unchanged.

Returns: grb::SUCCESS This function cannot fail.

Warning: Calling clear may not clear any dynamically allocated memory associated with A.

Note: Depending on the memory usage semantics defined on a per-backend basis, grb::resize may or may not free dynamically allocated memory associated with A.; Only the destruction of A would ensure all corresponding memory is freed, for all backends.

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

See also: Performance Semantics

◆ getID() [1/2]

uintptr_t grb::getID ( const Vector< ElementType, implementation, Coords > & x )

Function that returns a unique ID for a given non-empty container.

Note: An empty container is either a vector of size 0 or a matrix with one of its dimensions equal to 0.

The ID is unique across all currently valid container instances. If \( n \) is the number of such valid instances, the returned ID may not be strictly smaller than \( n \) – i.e., implementations are not required to maintain consecutive IDs (nor would this be possible if IDs are to be reused).

The use of uintptr_t to represent IDs guarantees that, at any time during execution, there can never be more initialised containers than can be assigned an ID. Therefore this specification demands that a call to this function never fails.

An ID, once given, may never change during the life-time of the given container. I.e., multiple calls to this function using the same argument must return the same ID.

If the program calling this function is deterministic, then it must assign the exact same IDs across different runs.

If the backend supports multiple user processes, the IDs obtained for the same containers but across different processes, may differ. However, across the same run of a deterministic program, the IDs returned within any single user process must, as per the preceding requirement, be the same across different runs that are executed using the same number of user processes.

Parameters

[in] x A valid non-empty ALP container to retrieve a unique ID for.

Note: If x is invalid or empty then a call to this function results in undefined behaviour.

Returns: The unique ID corresponding to x.

Warning: The returned ID is not the same as a pointer to x, since, for example, two containers may be swapped via std::swap. In such a case, the IDs of the two containers are swapped also.

Note: Another example is when move semantics are invoked, e.g., when a temporary container is copied into another just before it would be destroyed. Via move semantics the remaining container is in fact not a copy of the temporary one, which would have caused their IDs to be different. Instead, the remaining container has taken over the ownership of the to-be destroyed one, retaining its ID.; For the purposes of defining determinism of ALP programs, and perhaps superfluously, two program which only differ by one program constructing a matrix while the other program constructing a vector, are not considered to be the same program; i.e., implementations are allowed to assign vector IDs differently from matrix IDs. However, implementations are not allowed to run out of IDs to assign as a result of using such a mechanism.

◆ getID() [2/2]

uintptr_t grb::getID ( const Matrix< ElementType, implementation, RIT, CIT, NIT > & x )

Specialisation of getID for matrix containers.

The same specification applies.

See also: getID

◆ ncols()

size_t grb::ncols ( const Matrix< InputType, backend, RIT, CIT, NIT > & A )

noexcept

Requests the column size of a given matrix.

The column size is set at construction of the given matrix and cannot be changed after instantiation.

A call to this function shall always succeed.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] A The matrix of which to retrieve the column size.

Returns: The number of columns of A.

This function shall not raise exceptions.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of A unchanged.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; This specification forces implementations and backends to cache the column size of a matrix so that it can be immediately returned. By RAII principles, given containers, on account of being instantiated and passed by reference, indeed must have a size that can be immediately returned.

◆ nnz() [1/2]

size_t grb::nnz ( const Vector< DataType, backend, Coords > & x )

noexcept

Request the number of nonzeroes in a given vector.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] x The vector whose current number of nonzeroes is requested.

A call to this function shall always succeed and shall never throw exceptions.

Returns: The number of nonzeroes in x.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of A untouched.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; Backends thus are forced to cache the current number of nonzeroes and immediately return that cached value.

◆ nnz() [2/2]

size_t grb::nnz ( const Matrix< InputType, backend, RIT, CIT, NIT > & A )

noexcept

Retrieve the number of nonzeroes contained in this matrix.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] A The matrix whose current number of nonzeroes is requested.

A call to this function shall always succeed and shall never throw exceptions.

Returns: The number of nonzeroes that A contains.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of A untouched.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; Backends thus are forced to cache the current number of nonzeroes and immediately return that cached value.

◆ nrows()

size_t grb::nrows ( const Matrix< InputType, backend, RIT, CIT, NIT > & A )

noexcept

Requests the row size of a given matrix.

The row size is set at construction of the given matrix and cannot be changed after instantiation.

A call to this function shall always succeed.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[in] A The matrix of which to retrieve the row size.

Returns: The number of rows of A.

This function shall not raise exceptions.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of A unchanged.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; This specification forces implementations and backends to cache the row size of a matrix so that it can be immediately returned. By RAII principles, given containers, on account of being instantiated and passed by reference, indeed must have a size that can be immediately returned.

◆ resize() [1/2]

RC grb::resize	(	Vector< InputType, backend, Coords > &	x,
		const size_t	new_nz
	)

noexcept

Resizes the nonzero capacity of this vector.

Any current contents of the vector are not retained.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[out]	x	The vector whose capacity is to be resized.
[in]	new_nz	The number of nonzeroes this vector is to contain. After a successful call, the container has, at minimum, space for new_nz nonzeroes.

The requested new_nz must be smaller than or equal to the size of x.

Even for non-successful calls to this function, the vector after the call shall not contain any nonzeroes; only if grb::PANIC is returned shall the resulting state of x be undefined.

The size of this vector is fixed. By a call to this function, only the maximum number of nonzeroes that the vector may contain can be adapted.

If the vector has size zero, all calls to this function will be equivalent to a call to grb::clear. In particular, any value for new_nz shall be ignored, even ones that would normally be considered illegal (which would be any nonzero value in the case of an empty container).

A request for less capacity than currently already may be allocated, may or may not be ignored. A backend

must define memory usage semantics that may be proportional to the requested capacity, and therefore must free any memory that the user has deemed unnecessary. However, a backend
could define memory usage semantics that are not proportional to the requested capacity, and in that case a performant implementation may choose not to free memory that the user has deemed unnecessary.

Returns: ILLEGAL When new_nz is larger than admissable and x was non-empty. The vector x is cleared, but its capacity remains unchanged.; OUTOFMEM When the required memory memory could not be allocated. The vector x is cleared, but its capacity remains unchanged.; SUCCESS If x is empty (i.e., has grb::size zero).; PANIC When allocation fails for any other reason. The vector x, as well as ALP/GraphBLAS, enters an undefined state.; SUCCESS If x is non-empty and when sufficient capacity for the resize operation was available. The vector x has obtained a capacity of at least new_nz while all nonzeroes it previously contained, if any, are cleared.

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

See also: Performance Semantics

Warning: For most implementations, this function will imply system calls, as well as \( \Theta( \mathit{new\_nz} ) \) work and data movement costs. It is thus to be considered an expensive function, and should be used sparingly and only when absolutely necessary.

◆ resize() [2/2]

RC grb::resize	(	Matrix< InputType, backend, RIT, CIT, NIT > &	A,
		const size_t	new_nz
	)

noexcept

Resizes the nonzero capacity of this matrix.

Any current contents of the matrix are not retained.

Template Parameters

InputType	The type of elements contained in the matrix A.
backend	The backend of the matrix A.

Parameters

[out]	A	The matrix whose capacity is to be resized.
[in]	new_nz	The number of nonzeroes this matrix is to contain. After a successful call, the container will have space for at least new_nz nonzeroes.

The requested new_nz must be smaller or equal to product of the number of rows and columns.

After a call to this function, the matrix shall not contain any nonzeroes. This is the case even after an unsuccessful call, with the exception for cases where grb::PANIC is returned– see below.

The size of this matrix is fixed. By a call to this function, only the maximum number of nonzeroes that the matrix may contain can be adapted.

If the matrix has size zero, meaning either zero rows or zero columns (or, as the preceding implies, both), then all calls to this function will be equivalent to a call to grb::clear. In particular, any value of new_nz shall be ignored, even ones that would normally be considered illegal (which would be any nonzero value in the case of an empty container).

A request for less capacity than currently already may be allocated, may or may not be ignored. A backend

must define memory usage semantics that may be proportional to the requested capacity, and therefore must free any memory that the user has deemed unnecessary. However, a backend
could define memory usage semantics that are not proportional to the requested capacity, and in that case a performant implementation may choose not to free memory that the user has deemed unnecessary.

Note: However, useful implementations will almost surely define storage costs that are proportional to new_nz, and in such cases resizing to smaller capacity must indeed free up unused memory.

Returns: ILLEGAL When new_nz is larger than admissable and A was non-empty. The capacity of A remains unchanged while its contents have been cleared.; OUTOFMEM When the required memory memory could not be allocated. The capacity of A remains unchanged while its contents have been cleared.; PANIC When allocation fails for any other reason. The matrix A as well as ALP/GraphBLAS, enters an undefined state.; SUCCESS If A is non-empty and when sufficient capacity for resizing was available. The matrix A has obtained the requested (or a larger) capacity. Its previous contents, if any, have been cleared.

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

See also: Performance Semantics

Warning: For useful backends, this function will indeed imply system calls and incur \( \Theta( \mathit{new\_nz} ) \) work and data movement costs. It is thus to be considered an expensive function, and should be used sparingly and only when absolutely necessary.

◆ set() [1/4]

RC grb::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.

Unmasked variant.

Template Parameters

descr	The descriptor used for this operation.
DataType	The type of each element in the given vector.
T	The type of the given value.
backend	The backend that implements this function.

Accepted descriptors

Parameters

[in,out]	x	The vector of which every element is to be set to equal val. On output, the number of elements shall be equal to the size of x.
[in]	val	The value to set each element of x to.
[in]	phase	Which grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.

In grb::RESIZE mode:

Returns: grb::OUTOFMEM When x could not be resized to hold the requested output, and the current capacity was insufficient.; grb::SUCCESS When the capacity of x was resized to guarantee the output of this operation can be contained.

In grb::EXECUTE mode:

Returns: grb::FAILED When x did not have sufficient capacity. The vector x on exit shall be cleared.; grb::SUCCESS When the call completes successfully.

In grb::TRY mode (experimental and may not be supported):

Returns: grb::FAILED When x did not have sufficient capacity. The vector x on exit will have contents defined as described for grb::TRY.; grb::SUCCESS When the call completes successfully.

When descr includes grb::descriptors::no_casting and if T does not match DataType, the code shall not compile.

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

See also: Performance Semantics

◆ set() [2/4]

RC grb::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 Parameters

descr	The descriptor used for this operation.
DataType	The type of each element in the given vector.
T	The type of the given value.
backend	The backend that implements this function.

Accepted descriptors

Parameters

[in,out]	x	The vector of which elements are to be set to val. On output, the number of elements shall depend on mask.
[in]	mask	The given mask. How the sparsity structure and values are evaluated depends on the given desc.
[in]	val	The value to set elements of x to.
[in]	phase	Which grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.

Warning: An empty mask, meaning grb::size( mask ) is zero, shall be interpreted as though no mask argument was given. In particular, any descriptors pertaining to the interpretation of mask shall be ignored.

In grb::RESIZE mode:

Returns: grb::OUTOFMEM When x could not be resized to hold the requested output, and the current capacity was insufficient.; grb::SUCCESS When the capacity of x was resized to guarantee the output of this operation can be contained.

In grb::EXECUTE mode:

Returns: grb::FAILED When x did not have sufficient capacity. The vector x on exit shall be cleared.; grb::SUCCESS When the call completes successfully.

In grb::TRY mode (experimental and may not be supported):

Returns: grb::FAILED When x did not have sufficient capacity. The vector x on exit will have contents defined as described for grb::TRY.; grb::SUCCESS When the call completes successfully.

When descr includes grb::descriptors::no_casting and if T does not match DataType, the code shall not compile.

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

See also: Performance Semantics

◆ set() [3/4]

RC grb::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 Parameters

descr	The descriptor of the operation.
OutputType	The type of each element in the output vector.
InputType	The type of each element in the input vector.

Parameters

[in,out]	x	The vector to be set.
[in]	y	The source vector.

The vector x may not be the same as y.

Parameters

[in] phase Which grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.

Accepted descriptors

When descr includes grb::descriptors::no_casting and if InputType does not match OutputType, the code shall not compile.

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

See also: Performance Semantics

◆ set() [4/4]

RC grb::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.

If an entry with index i has that the corresponding mask entry evaluates false, then that entry shall not be copied into x.

The vector x may not equal y.

Template Parameters

descr	The descriptor of the operation. Optional; default value is grb::descriptors::no_operation.
OutputType	The type of each element in the output vector.
MaskType	The type of each element in the mask vector.
InputType	The type of each element in the input vector.

Parameters

[in,out]	x	The vector to be set.
[in]	mask	The output mask.
[in]	y	The source vector. May not equal y.
[in]	phase	Which grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.

Accepted descriptors

When descr includes grb::descriptors::no_casting and if InputType does not match OutputType, the code shall not compile.

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

See also: Performance Semantics

◆ setElement()

RC grb::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.

If the input vector x already has an element \( x_i \), that element is overwritten to the given value val. If no such element existed, it is added and set equal to val. The number of nonzeroes in x may thus be increased by one due to a call to this function.

The parameter i may not be greater or equal than the size of x.

Template Parameters

descr	The descriptor to be used during evaluation of this function. Optional; the default descriptor is grb::descriptors::no_operation.
DataType	The type of the elements of x.
T	The type of the value to be set.

Parameters

[in,out]	x	The vector to be modified.
[in]	val	The value \( x_i \) should read after function exit.
[in]	i	The index of the element of x to set.
[in]	phase	Which grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.

Returns: grb::SUCCESS Upon successful execution of this operation.; grb::MISMATCH If i is greater or equal than the dimension of x.

Accepted descriptors

When descr includes grb::descriptors::no_casting and if T does not match DataType, the code shall not compile.

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

See also: Performance Semantics

◆ size()

size_t grb::size ( const Vector< DataType, backend, Coords > & x )

noexcept

Request the size of a given vector.

The dimension is set at construction of the given vector and cannot be changed after instantiation.

A call to this function shall always succeed.

Template Parameters

DataType	The type of elements contained in the vector x.
backend	The backend of the vector x.

Parameters

[in] x The vector of which to retrieve the size.

Returns: The size of the vector x.

This function shall not raise exceptions.

Performance semantics.

A call to this function:

completes in \( \Theta(1) \) work.
moves \( \Theta(1) \) intra-process data.
moves \( 0 \) inter-process data.
does not require inter-process reduction.
leaves memory requirements of x unchanged.
does not make system calls, and in particular shall not allocate or free any dynamic memory.

Note: This is a getter function which has strict performance semantics that are not backend-specific.; This specification forces implementations and backends to cache the size of a vector so that it can be immediately returned. By RAII principles, given containers, on account of being instantiated and passed by reference, indeed must have a size that can be immediately returned.

◆ wait() [1/3]

RC grb::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.

More formally, while run-time checks that result in grb::MISMATCH must be performed immediately even when a primitive is non-blocking, the detection of other error codes (such as for example the illegal use of a sparse vector) may in fact be deferred, as is of course any attempt to actually perform the requested computation.

A sequence of nonblocking calls may be forced to execute by a call to this primitive, at which point any non-success error code that would have normally been returned by a nonblocking call, will instead be returned by this primitive. If all requested nonblocking calls have executed successfully, then a call to this function shall return grb::SUCCESS.

The are several other cases in which the computation of nonblocking primtives is forced:

whenever an output iterator of an output container of any of the non- blocking primitives is requested; and
whenever an output container of any of the non-blocking primitives is input to an ALP/GraphBLAS primitive that has scalar output (e.g., grb::dot or folds from a vector into a scalar). A backend may specify additional such trigger points.

If a trigger point has no grb::RC return type, then any deferred non-SUCCESS error codes shall materialise as thrown C++ exceptions.

The performance semantics of a trigger point correspond to a sum of the performance semantics of each of the nonblocking primitives it executes.

Note: A good nonblocking backend will in fact incur less data movement by, e.g., fusing low arithmetic intensity operations, whenever possible. Hence the summed performance semantics typically correspond to worst- case bounds.; If automated decisions by a nonblocking backend is unacceptable in certain (parts of a) code base, then manual fusion is preferable. ALP/GraphBLAS provides grb::eWiseLambda for this purpose.

Returns: grb::SUCCESS If all queued non-blocking primitives are executed successfully. If not, any error code prescribed by the non-blocking primitives requested may be returned instead.

◆ wait() [2/3]

RC grb::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.

Implementations may elect to execute more than strictly required. In particular, a valid implementation of this variant simply calls grb::wait.

Parameters

[in] x The output container which, after a call to this function returns, must be fully computed.

More formally, after a call to this function, retrieving an output iterator of x no longer requires triggering any corresponding nonblocking primitives.

Parameters

[in] args Any additional containers whose output must be fully computed after a call to this function.

Returns: grb::SUCCESS If the queued non-blocking primitives that are executed as part of a call to this function have executed successfully. If not, any error code prescribed by the non-blocking primitives whose execution was attempted may be returned instead.

◆ wait() [3/3]

RC grb::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.

Implementations may elect to execute more than strictly required. In particular, a valid implementation of this variant simply calls grb::wait.

Parameters

[in] A The output container which, after a call to this function returns, must be fully computed.

More formally, after a call to this function, retrieving an output iterator of A no longer requires triggering any corresponding nonblocking primitives.

Parameters

[in] args Any additional containers whose output must be fully computed after a call to this function.

Returns: grb::SUCCESS If the queued non-blocking primitives that are executed as part of a call to this function have executed successfully. If not, any error code prescribed by the non-blocking primitives whose execution was attempted may be returned instead.

Classes

Functions

Detailed Description

Function Documentation

◆ buildMatrixUnique() [1/2]

◆ buildMatrixUnique() [2/2]

◆ buildVector() [1/2]

◆ buildVector() [2/2]

◆ buildVectorUnique()

◆ capacity() [1/2]

◆ capacity() [2/2]

◆ clear() [1/2]

◆ clear() [2/2]

◆ getID() [1/2]

◆ getID() [2/2]

◆ ncols()

◆ nnz() [1/2]

◆ nnz() [2/2]

◆ nrows()

◆ resize() [1/2]

◆ resize() [2/2]

◆ set() [1/4]

◆ set() [2/4]

◆ set() [3/4]

◆ set() [4/4]

◆ setElement()

◆ size()

◆ wait() [1/3]

◆ wait() [2/3]

◆ wait() [3/3]