ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Functions | Variables
grb::descriptors Namespace Reference

Collection of standard descriptors. More...

Functions

std::string toString (const Descriptor descr)
 Translates a descriptor into a string. More...
 

Variables

static constexpr Descriptor add_identity = 32
 For any call to a matrix computation, the input matrix A is instead interpreted as \( A+I \), with I the identity matrix of dimension matching A. More...
 
static constexpr Descriptor dense = 16
 Indicates that all input and output vectors to an ALP/GraphBLAS primitive are structurally dense. More...
 
static constexpr Descriptor explicit_zero = 512
 Computation shall proceed with zeros (according to the current semiring) propagating throughout the requested computation. More...
 
static constexpr Descriptor invert_mask = 1
 Inverts the mask prior to applying it. More...
 
static constexpr Descriptor no_casting = 256
 Disallows the standard casting of input parameters to a compatible domain in case they did not match exactly. More...
 
static constexpr Descriptor no_duplicates = 4
 For data ingestion methods, such as grb::buildVector or grb::buildMatrix, this descriptor indicates that the input shall not contain any duplicate entries. More...
 
static constexpr Descriptor no_operation = 0
 Indicates no additional pre- or post-processing on any of the GraphBLAS function arguments.
 
static constexpr Descriptor safe_overlap = 1024
 Indicates overlapping input and output vectors is intentional and safe, due to, for example, the use of masks.
 
static constexpr Descriptor structural = 8
 Uses the structure of a mask vector only. More...
 
static constexpr Descriptor structural_complement = structural | invert_mask
 Uses the structural complement of a mask vector. More...
 
static constexpr Descriptor transpose_left = 2048
 For operations involving two matrices, transposes the left-hand side input matrix prior to applying it.
 
static constexpr Descriptor transpose_matrix = 2
 Transposes the input matrix prior to applying it.
 
static constexpr Descriptor transpose_right = 4096
 For operations involving two matrices, transposes the right-hand side input matrix prior to applying it.
 
static constexpr Descriptor use_index = 64
 Instead of using input vector elements, use the index of those elements. More...
 

Detailed Description

Collection of standard descriptors.

Function Documentation

◆ toString()

std::string grb::descriptors::toString ( const Descriptor  descr)

Translates a descriptor into a string.

Parameters
[in]descrThe input descriptor.
Returns
A detailed English description.

Variable Documentation

◆ add_identity

constexpr Descriptor add_identity = 32
static

For any call to a matrix computation, the input matrix A is instead interpreted as \( A+I \), with I the identity matrix of dimension matching A.

If A is not square, padding zero columns or rows will be added to I in the largest dimension.

◆ dense

constexpr Descriptor dense = 16
static

Indicates that all input and output vectors to an ALP/GraphBLAS primitive are structurally dense.

If a user passes this descriptor but one or more vectors to the call are not structurally dense, then ILLEGAL shall be returned.

Warning
All vectors includes any vectors that operate as masks. Thus if the primitive is to operate with structurally sparse masks but with otherwise dense vectors, then the dense descriptor may not be defined.
For in-place operations with vector outputs –which are all ALP/GraphBLAS primitives with vector outputs except grb::set and grb::eWiseApply– the output vector is also an input vector. Thus passing this descriptor to such primitive indicates that also the output vector is structurally dense.
For out-of-place operations with vector output(s), passing this descriptor also demands that the output vectors are already dense.
Vectors with explicit zeroes (under the semiring passed to the related primitive) will be computed with explicitly.

The benefits of using this descriptor whenever possible are two-fold: 1) less run-time overhead as code handling sparsity is disabled; 2) smaller binary sizes as code handling structurally sparse vectors is not emitted (unless required elsewhere).

The consistent use of this descriptor is hence strongly encouraged.

◆ explicit_zero

constexpr Descriptor explicit_zero = 512
static

Computation shall proceed with zeros (according to the current semiring) propagating throughout the requested computation.

Warning
This may lead to unexpected results if the same output container is interpreted under a different semiring– what is zero for the current semiring may not be zero for another. In other words: the concept of sparsity will no longer generalise to other semirings.

◆ invert_mask

constexpr Descriptor invert_mask = 1
static

Inverts the mask prior to applying it.

◆ no_casting

constexpr Descriptor no_casting = 256
static

Disallows the standard casting of input parameters to a compatible domain in case they did not match exactly.

Setting this descriptor will yield compile-time errors whenever casting would have been necessary to successfully compile the requested graphBLAS operation.

Warning
It is illegal to perform conditional toggling on this descriptor.
Note
With conditional toggling, if descr is a descriptor, we mean if( descr & descriptors::no_casting ) { new_descr = desc - descriptors::no_casting //followed by any use of this new descriptor } The reason we cannot allow for this type of toggling is because this descriptor makes use of the static_assert C++11 function, which is checked regardless of the result of the if-statement. Thus the above code actually always throws compile errors on mismatching domains, no matter the original value in descr.

◆ no_duplicates

constexpr Descriptor no_duplicates = 4
static

For data ingestion methods, such as grb::buildVector or grb::buildMatrix, this descriptor indicates that the input shall not contain any duplicate entries.

Use of this descriptor will speed up the corresponding function call significantly.

A call to buildMatrix with this descriptor set will pass its arguments to buildMatrixUnique.

Warning
Use of this descriptor while the data to be ingested actually does contain duplicates will lead to undefined behaviour.

Currently, the reference implementation only supports ingesting data using this descriptor. Support for duplicate input is not yet implemented everywhere.

◆ structural

constexpr Descriptor structural = 8
static

Uses the structure of a mask vector only.

This ignores the actual values of the mask argument. The i-th element of the mask now evaluates true if the mask has any value assigned to its i-th index, regardless of how that value evaluates. It evaluates false if there was no value assigned.

See also
structural_complement

◆ structural_complement

constexpr Descriptor structural_complement = structural | invert_mask
static

Uses the structural complement of a mask vector.

This is a convenience short-hand for:

This ignores the actual values of the mask argument. The i-th element of the mask now evaluates true if the mask has no value assigned to its i-th index, and evaluates false otherwise.

◆ use_index

constexpr Descriptor use_index = 64
static

Instead of using input vector elements, use the index of those elements.

Indices are cast from their internal data type (size_t, e.g.) to the relevant domain of the operator used.