ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Classes | Functions
Data Ingestion and Extraction

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
descrThe descriptor used. The default is grb::descriptors::no_operation, which means that no pre- or post-processing of input or input is performed.
fwd_iterator1The type of the row index iterator.
fwd_iterator2The type of the column index iterator.
fwd_iterator3The type of the nonzero value iterator.
length_typeThe type of the number of elements in each iterator.
Parameters
[out]AWhere to store the given nonzeroes.
[in]IA forward iterator to cap row indices.
[in]JA forward iterator to cap column indices.
[in]VA forward iterator to cap nonzero values.
[in]I_endA forward iterator in end position relative to I.
[in]J_endA forward iterator in end position relative to J.
[in]V_endA forward iterator in end position relative to V.

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

Parameters
[in]modeWhether 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
descrThe currently active descriptor.
InputTypeThe value type the output matrix expects.
fwd_iteratorThe iterator type.
implementationFor which backend a matrix is being read.

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

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

It also must provide the following public typedefs:

  1. fwd_iterator::RowIndexType
  2. fwd_iterator::ColumnIndexType
  3. fwd_iterator::ValueType

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

Parameters
[out]AThe matrix to be filled with nonzeroes from start to end.
[in]startIterator pointing to the first nonzero to be added.
[in]endIterator pointing past the last nonzero to be added.
[in]modeWhether 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]xThe vector where to ingest nonzeroes into.
[in]ind_startStart iterator to the nonzero indices.
[in]ind_endEnd iterator to the nonzero indices.
[in]val_startStart iterator to the nonzero values.
[in]val_endEnd iterator to the nonzero values.
[in]modeWhether 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]xThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of x unchanged.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]AThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of A untouched.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in,out]xThe 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in,out]AThe 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]xA 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]AThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of A unchanged.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]xThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of A untouched.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]AThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of A untouched.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[in]AThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of A unchanged.
  6. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[out]xThe vector whose capacity is to be resized.
[in]new_nzThe 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

  1. 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
  2. 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
InputTypeThe type of elements contained in the matrix A.
backendThe backend of the matrix A.
Parameters
[out]AThe matrix whose capacity is to be resized.
[in]new_nzThe 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

  1. 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
  2. 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
descrThe descriptor used for this operation.
DataTypeThe type of each element in the given vector.
TThe type of the given value.
backendThe backend that implements this function.
Accepted descriptors
  1. grb::descriptors::no_operation
  2. grb::descriptors::no_casting
Parameters
[in,out]xThe 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]valThe value to set each element of x to.
[in]phaseWhich 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
descrThe descriptor used for this operation.
DataTypeThe type of each element in the given vector.
TThe type of the given value.
backendThe backend that implements this function.
Accepted descriptors
  1. grb::descriptors::no_operation
  2. grb::descriptors::no_casting
  3. grb::descriptors::invert_mask
  4. grb::descriptors::structural_mask
Parameters
[in,out]xThe vector of which elements are to be set to val. On output, the number of elements shall depend on mask.
[in]maskThe given mask. How the sparsity structure and values are evaluated depends on the given desc.
[in]valThe value to set elements of x to.
[in]phaseWhich 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
descrThe descriptor of the operation.
OutputTypeThe type of each element in the output vector.
InputTypeThe type of each element in the input vector.
Parameters
[in,out]xThe vector to be set.
[in]yThe source vector.

The vector x may not be the same as y.

Parameters
[in]phaseWhich grb::Phase the operation is requested. Optional; the default is grb::EXECUTE.
Accepted descriptors
  1. grb::descriptors::no_operation
  2. grb::descriptors::no_casting
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
descrThe descriptor of the operation. Optional; default value is grb::descriptors::no_operation.
OutputTypeThe type of each element in the output vector.
MaskTypeThe type of each element in the mask vector.
InputTypeThe type of each element in the input vector.
Parameters
[in,out]xThe vector to be set.
[in]maskThe output mask.
[in]yThe source vector. May not equal y.
[in]phaseWhich 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
descrThe descriptor to be used during evaluation of this function. Optional; the default descriptor is grb::descriptors::no_operation.
DataTypeThe type of the elements of x.
TThe type of the value to be set.
Parameters
[in,out]xThe vector to be modified.
[in]valThe value \( x_i \) should read after function exit.
[in]iThe index of the element of x to set.
[in]phaseWhich 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
DataTypeThe type of elements contained in the vector x.
backendThe backend of the vector x.
Parameters
[in]xThe 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:
  1. completes in \( \Theta(1) \) work.
  2. moves \( \Theta(1) \) intra-process data.
  3. moves \( 0 \) inter-process data.
  4. does not require inter-process reduction.
  5. leaves memory requirements of x unchanged.
  6. 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:

  1. whenever an output iterator of an output container of any of the non- blocking primitives is requested; and
  2. 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]xThe 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]argsAny 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]AThe 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]argsAny 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.