grb::descriptors Namespace Reference

Collection of standard descriptors. More...

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

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.
static constexpr Descriptor	dense = 16
	Indicates that all input and output vectors to an ALP/GraphBLAS primitive are structurally dense.
static constexpr Descriptor	explicit_zero = 512
	Computation shall proceed with zeros (according to the current semiring) propagating throughout the requested computation.
static constexpr Descriptor	invert_mask = 1
	Inverts the mask prior to applying it.
static constexpr Descriptor	no_casting = 256
	Disallows the standard casting of input parameters to a compatible domain in case they did not match exactly.
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.
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.
static constexpr Descriptor	structural_complement = structural | invert_mask
	Uses the structural complement of a mask vector.
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.

Detailed Description

Collection of standard descriptors.

Function Documentation

toString()

std::string toString

(

const Descriptor

descr

)

Translates a descriptor into a string.

Parameters

[in]

descr

The input descriptor.

Returns

A detailed English description.

Variable Documentation

add_identity

constexpr Descriptor add_identity = 32

staticconstexpr

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

staticconstexpr

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

staticconstexpr

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.

no_casting

constexpr Descriptor no_casting = 256

staticconstexpr

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

staticconstexpr

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

staticconstexpr

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

staticconstexpr

Uses the structural complement of a mask vector.

This is a convenience short-hand for:

constexpr Descriptor structural_complement = structural | invert_mask;

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

staticconstexpr

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.