Utility Functions

Input/Output Functions

int LAGraph_MMRead(GrB_Matrix *A, FILE *f, char *msg)

LAGraph_MMRead: reads a matrix in MatrixMarket format. The file format used here is compatible with all variations of the Matrix Market “coordinate” and “array” format (http://www.nist.gov/MatrixMarket), for sparse and dense matrices respectively. The format is fully described in LAGraph/Doc/MatrixMarket.pdf, and summarized here (with extensions for LAGraph).

First Line

The first line of the file starts with %%MatrixMarket, with the following format:

%%MatrixMarket matrix <fmt> <type> <storage>

<fmt>

One of:

coordinate : sparse matrix in triplet form
array : dense matrix in column-major form

Both formats are returned as a GrB_Matrix.

If not present, defaults to coordinate.

<type>

One of:

real : returns as GrB_FP64
integer : returns as GrB_INT64
pattern : returns as GrB_BOOL
complex : currently not supported

The return type can be modified by the %%GraphBLAS structured comment described below.

If not present, defaults to real.

<storage>

One of:

general
the matrix has no symmetry properties (or at least none that were exploited when the file was created).
Hermitian
square complex matrix with A(i,j) = conj (A(j,i)). All entries on the diagonal are real. Each off-diagonal entry in the file creates two entries in the GrB_Matrix that is returned.
symmetric
A(i,j) == A(j,i). Only entries on or below the diagonal appear in the file. Each off-diagonal entry in the file creates two entries in the GrB_Matrix that is returned.
skew-symmetric
A(i,j) == -A(i,j). There are no entries on the diagonal. Only entries below the diagonal appear in the file. Each off-diagonal entry in the file creates two entries in the GrB_Matrix that is returned.

The Matrix Market format is case-insensitive, so “hermitian” and “Hermitian” are treated the same.

If not present, defaults to general.

Not all combinations are permitted. Only the following are meaningful:

(coordinate or array) x (real, integer, or complex) x (general, symmetric, or skew-symmetric)
(coordinate or array) x (complex) x (Hermitian)
(coodinate) x (pattern) x (general or symmetric)

Second Line

The second line is an optional extension to the Matrix Market format:

%%GraphBLAS type <entrytype>

<entrytype>: One of the 11 built-in types (bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, or double.

If this second line is included, it overrides the default GraphBLAS types for the Matrix Market <type> on line one of the file: real, pattern, and integer. The Matrix Market complex <type> is not yet supported.

Other Lines

Any other lines starting with “%” are treated as comments, and are ignored. Comments may be interspersed throughout the file. Blank lines are ignored. The Matrix Market header is optional in this routine (it is not optional in the Matrix Market format). The remaining lines are space delimited, and free format (one or more spaces can appear, and each field has arbitrary width).

Coordinate Format

For coordinate format, the first non-comment line must appear, and it must contain three integers:

nrows ncols nvals

For example, a 5-by-12 matrix with 42 entries would have:

5 12 42

Each of the remaining lines defines one entry. The order is arbitrary. If the Matrix Market <type> is real or integer, each line contains three numbers: row index, column index, and value. For example, if A(3,4) is equal to 5.77, a line:

3 4 5.77

would appear in the file. The indices in the Matrix Market are 1-based, so this entry becomes A(2,3) in the GrB_Matrix returned to the caller. If the <type> is pattern, then only the row and column index appears. If <type> is complex, four values appear. If A(8,4) has a real part of 6.2 and an imaginary part of -9.3, then the line is:

8 4 6.2 -9.3

and since the file is 1-based but a GraphBLAS matrix is always 0-based, one is subtracted from the row and column indices in the file, so this entry becomes A(7,3). Note however that LAGraph does not yet support complex types.

Array Format

For array format, the first non-comment line must appear, and it must contain just two integers:

nrows ncols

A 5-by-12 matrix would have this as the first non-comment line after the header:

5 12

Each of the remaining lines defines one entry, in column major order. If the <type> is real or integer, this is the value of the entry. An entry if <type> of complex consists of two values, the real and imaginary part (not yet supported). The <type> cannot be pattern in this case.

Infinity & Not-A-Number

For both coordinate and array formats, real and complex values may use the terms INF, +INF, -INF, and NAN to represent floating-point infinity and NaN values, in either upper or lower case.

According to the Matrix Market format, entries are always listed in column-major order. This rule is follwed by LAGraph_MMWrite . However, LAGraph_MMRead can read the entries in any order.

Parameters

A – [out] handle of the matrix to create.
f – [inout] handle to an open file to read from.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if A or f are NULL.
LAGRAPH_IO_ERROR – if the file could not be read or contains a matrix with an invalid Matrix Market format.
GrB_NOT_IMPLEMENTED – if the type is not supported. Complex types (GxB_FC32 and GxB_FC64 in SuiteSparse:GraphBLAS) are not yet supported.

int LAGraph_MMWrite(GrB_Matrix A, FILE *f, FILE *fcomments, char *msg)

LAGraph_MMWrite: writes a matrix in MatrixMarket format. Refer to LAGraph_MMRead for a description of the output file format. The MatrixMarket header line always appears, followed by the second line containing the GraphBLAS type:

 %%GraphBLAS type <entrytype>

Parameters

A – [in] matrix to write.
f – [inout] handle to an open file to write to.
fcomments – [in] optional handle to an open file containing comments; may be NULL.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if A or f are NULL.
LAGRAPH_IO_ERROR – if the file could not be written to.
GrB_NOT_IMPLEMENTED – if the type is not supported. Complex types (GxB_FC32 and GxB_FC64 in SuiteSparse:GraphBLAS) are not yet supported.

double LAGraph_WallClockTime(void)

LAGraph_WallClockTime returns the current wall clock time. Normally, this is simply a wrapper for omp_get_wtime, if OpenMP is in use. Otherwise, an OS-specific timing function is called. Note that unlike all other LAGraph functions, this function does not return an error condition, nor does it have a msg string parameter. Instead, it returns the current wall clock time (in seconds) since some fixed point in the past.

Returns: the current wall clock time.

Matrix Structure Functions

int LAGraph_Matrix_Structure(GrB_Matrix *C, GrB_Matrix A, char *msg)

LAGraph_Matrix_Structure: returns the sparsity structure of a matrix A as a boolean (GrB_BOOL) matrix C. If A(i,j) appears in the sparsity structure of A, then C(i,j) is set to true. The sparsity structure of A and C are identical.

Parameters

C – [out] A boolean matrix with same structure of A, with C(i,j) true if A(i,j) appears in the sparsity structure of A.
A – [in] matrix to compute the structure for.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if A or C are NULL.

int LAGraph_Vector_Structure(GrB_Vector *w, GrB_Vector u, char *msg)

LAGraph_Vector_Structure: returns the sparsity structure of a vector u as a boolean (GrB_BOOL) vector w. If u(i) appears in the sparsity structure of u, then w(i) is set to true. The sparsity structure of u and w are identical.

Parameters

w – [out] A boolean vector with same structure of u, with w(i) true if u(i,j) appears in the sparsity structure of u.
u – [in] vector to compute the structure for.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if w or u are NULL.

Matrix Comparison Functions

int LAGraph_Matrix_IsEqual(bool *result, const GrB_Matrix A, const GrB_Matrix B, char *msg)

LAGraph_Matrix_IsEqual compares two matrices for exact equality. If the two matrices have different data types, the result is always false (no typecasting is performed). Only the 11 built-in GrB* types are supported. If both A and B are NULL, the return value is true. If A and/or B are floating-point types and contain NaN’s, result is false.

Parameters

result – [out] true if A and B are exactly equal, false otherwise.
A – [in] matrix to compare.
B – [in] matrix to compare.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if result is NULL.
GrB_NOT_IMPLEMENTED – if A or B has a user-defined type.

int LAGraph_Matrix_IsEqualOp(bool *result, const GrB_Matrix A, const GrB_Matrix B, const GrB_BinaryOp op, char *msg)

LAGraph_Matrix_IsEqualOp compares two matrices using the given binary operator. The op may be built-in or user-defined. The two matrices may have different types and still be determined to be equal. To be equal, two matrices must have the same sparsity structure, and op(aij,bij) must return true for all pairs of entries aij and bij that appear in the structure of both A and B. The matrices A and/or B can have any type, as long as they are valid inputs to the op. If both A and B are NULL, the return value is true.

Parameters

result – [out] true if A and B are equal (per the op), false otherwise.
A – [in] matrix to compare.
B – [in] matrix to compare.
op – [in] operator for the comparison.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if result or op are NULL.

int LAGraph_Vector_IsEqual(bool *result, const GrB_Vector u, const GrB_Vector v, char *msg)

LAGraph_Vector_IsEqual compares two vectors for exact equality. If the two vectors have different data types, the result is always false (no typecasting is performed). Only the 11 built-in GrB* types are supported. If both u and v are NULL, the return value is true. If u and/or v are floating-point types and contain NaN’s, result is false.

Parameters

result – [out] true if u and v are exactly equal, false otherwise.
u – [in] vector to compare.
v – [in] vector to compare.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if result is NULL.
GrB_NOT_IMPLEMENTED – if u or v has a user-defined type.

int LAGraph_Vector_IsEqualOp(bool *result, const GrB_Vector u, const GrB_Vector v, const GrB_BinaryOp op, char *msg)

LAGraph_Vector_IsEqualOp compares two vectors using the given binary operator. The op may be built-in or user-defined. The two vectors may have different types and still be determined to be equal. To be equal, two vectors must have the same sparsity structure, and op(ui,vi) must return true for all pairs of entries ui and vi that appear in the structure of both u and v. The vectors u and/or v can have any type, as long as they are valid inputs to the op. If both u and v are NULL, the return value is true.

Parameters

result – [out] true if u and v are equal (per the op), false otherwise.
u – [in] vector to compare.
v – [in] vector to compare.
op – [in] operator for the comparison.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if result or op are NULL.

Introspecting Types

int LAGraph_NameOfType(char *name, GrB_Type type, char *msg)

LAGraph_NameOfType returns the name of a GraphBLAS type as a string. The names for the 11 built-in types (GrB_BOOL, GrB_INT8, etc) correspond to the names of the corresponding C types (bool, int8_t, etc).

Parameters

name – [out] name of the type: user provided array of size at least LAGRAPH_MAX_NAME_LEN.
type – [in] GraphBLAS type to find the name of.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if name or type are NULL.

int LAGraph_TypeFromName(GrB_Type *type, char *name, char *msg)

LAGraph_TypeFromName: returns the GrB_Type corresponding to its name. That is, given the string “bool”, this method returns GrB_BOOL.

Parameters

type – [out] GraphBLAS type corresponding to the given name string.
name – [in] name of the type: a null-terminated string.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if name or type are NULL.

int LAGraph_SizeOfType(size_t *size, GrB_Type type, char *msg)

LAGraph_SizeOfType: returns sizeof(…) of a GraphBLAS GrB_Type. For example, if given the GrB_Type of GrB_FP64, the value sizeof(double) is returned.

Parameters

size – [out] size of the type
type – [in] GraphBLAS type to find the size of.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if size or type are NULL.

int LAGraph_Matrix_TypeName(char *name, GrB_Matrix A, char *msg)

LAGraph_Matrix_TypeName: returns the name of the GrB_Type of a GrB_Matrix.

Parameters

name – [out] name of the type of the matrix: user provided array of size at least LAGRAPH_MAX_NAME_LEN.
A – [in] GraphBLAS matrix to find the type name of.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if name or A are NULL.

int LAGraph_Vector_TypeName(char *name, GrB_Vector v, char *msg)

LAGraph_Vector_TypeName: returns the name of the GrB_Type of a GrB_Vector.

Parameters

name – [out] name of the type of the vector: user provided array of size at least LAGRAPH_MAX_NAME_LEN.
v – [in] GraphBLAS vector to find the type name of.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if name or v are NULL.

int LAGraph_Scalar_TypeName(char *name, GrB_Scalar s, char *msg)

LAGraph_Scalar_TypeName: returns the name of the GrB_Type of a GrB_Scalar.

Parameters

name – [out] name of the type of the scalar: user provided array of size at least LAGRAPH_MAX_NAME_LEN.
s – [in] GraphBLAS scalar to find the type name of.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if name or s are NULL.

Printing

int LAGraph_Graph_Print(const LAGraph_Graph G, LAGraph_PrintLevel pr, FILE *f, char *msg)

LAGraph_Graph_Print: prints the contents of a graph to a file in a human- readable form. This method is not meant for saving a graph to a file; see LAGraph_MMWrite for that method.

Parameters

G – [in] graph to display.
pr – [in] print level.
f – [inout] handle to an open file to write to.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if G or f are NULL.
LAGRAPH_INVALID_GRAPH – if G is invalid ( LAGraph_CheckGraph failed).
GrB_NOT_IMPLEMENTED – if G->A has a user-defined type.
LAGRAPH_IO_ERROR – if the file could not be written to.

int LAGraph_Matrix_Print(const GrB_Matrix A, LAGraph_PrintLevel pr, FILE *f, char *msg)

LAGraph_Matrix_Print displays a matrix in a human-readable form. This method is not meant for saving a GrB_Matrix to a file; see LAGraph_MMWrite for that method.

Parameters

A – [in] matrix to display.
pr – [in] print level.
f – [inout] handle to an open file to write to.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if A or f are NULL.
GrB_NOT_IMPLEMENTED – if A has a user-defined type.
LAGRAPH_IO_ERROR – if the file could not be written to.

int LAGraph_Vector_Print(const GrB_Vector v, LAGraph_PrintLevel pr, FILE *f, char *msg)

LAGraph_Vector_Print displays a vector in a human-readable form. This method is not meant for saving a GrB_Vector to a file. To perform that operation, copy the GrB_Vector into an n-by-1 GrB_Matrix and use LAGraph_MMWrite .

Parameters

v – [in] vector to display.
pr – [in] print level.
f – [inout] handle to an open file to write to.
msg – [inout] any error messages.

Returns

any GraphBLAS errors that may have been encountered.

Returns

GrB_SUCCESS – if successful.
GrB_NULL_POINTER – if v or f are NULL.
GrB_NOT_IMPLEMENTED – if v has a user-defined type.
LAGRAPH_IO_ERROR – if the file could not be written to.

enum LAGraph_PrintLevel

LAGraph_PrintLevel: an enum to control how much to print in LAGraph_*_Print methods.

Values:

enumerator LAGraph_SILENT: nothing is printed.

enumerator LAGraph_SUMMARY: print a terse summary.

enumerator LAGraph_SHORT: short description, about 30 entries.

enumerator LAGraph_COMPLETE: print the entire contents of the object.

enumerator LAGraph_SHORT_VERBOSE: short, but with “%.15g” for doubles.

enumerator LAGraph_COMPLETE_VERBOSE: complete, but “%.15g” for doubles.

Pre-defined semirings

LAGraph adds the following pre-defined semirings. They are created by LAGr_Init or LAGraph_Init, and freed by LAGraph_Finalize.

LAGraph_plus_first_T:

Uses the GrB_PLUS_MONOID_T monoid and the corresponding GrB_FIRST_T multiplicative operator:

LAGraph_plus_first_int8
LAGraph_plus_first_int16
LAGraph_plus_first_int32
LAGraph_plus_first_int64
LAGraph_plus_first_uint8
LAGraph_plus_first_uint16
LAGraph_plus_first_uint32
LAGraph_plus_first_uint64
LAGraph_plus_first_fp32
LAGraph_plus_first_fp64

LAGraph_plus_second_T

Uses the GrB_PLUS_MONOID_T monoid and the corresponding GrB_SECOND_T multiplicative operator:

LAGraph_plus_second_int8
LAGraph_plus_second_int16
LAGraph_plus_second_int32
LAGraph_plus_second_int64
LAGraph_plus_second_uint8
LAGraph_plus_second_uint16
LAGraph_plus_second_uint32
LAGraph_plus_second_uint64
LAGraph_plus_second_fp32
LAGraph_plus_second_fp64

LAGraph_plus_one_T:

Uses the GrB_PLUS_MONOID_T monoid and the corresponding GrB_ONEB_T multiplicative operator:

LAGraph_plus_one_int8
LAGraph_plus_one_int16
LAGraph_plus_one_int32
LAGraph_plus_one_int64
LAGraph_plus_one_uint8
LAGraph_plus_one_uint16
LAGraph_plus_one_uint32
LAGraph_plus_one_uint64
LAGraph_plus_one_fp32
LAGraph_plus_one_fp64

LAGraph_any_one_T:
Uses the GrB_MIN_MONOID_T for non-boolean types or GrB_LOR_MONOID_BOOL for boolean, and the GrB_ONEB_T multiplicative op.

These semirings are very useful for unweighted graphs, or for algorithms that operate only on the sparsity structure of unweighted graphs:
LAGraph_any_one_bool LAGraph_any_one_int8 LAGraph_any_one_int16 LAGraph_any_one_int32 LAGraph_any_one_int64 LAGraph_any_one_uint8 LAGraph_any_one_uint16 LAGraph_any_one_uint32 LAGraph_any_one_uint64 LAGraph_any_one_fp32 LAGraph_any_one_fp64