IJ System Interface

group IJSystemInterface

A linear-algebraic conceptual interface.

This interface represents a linear-algebraic conceptual view of a linear system. The ‘I’ and ‘J’ in the name are meant to be mnemonic for the traditional matrix notation A(I,J).

IJ Matrices

typedef struct hypre_IJMatrix_struct *HYPRE_IJMatrix

The matrix object.

HYPRE_Int HYPRE_IJMatrixCreate(MPI_Comm comm, HYPRE_BigInt ilower, HYPRE_BigInt iupper, HYPRE_BigInt jlower, HYPRE_BigInt jupper, HYPRE_IJMatrix *matrix)

Create a matrix object.

Each process owns some unique consecutive range of rows, indicated by the global row indices ilower and iupper. The row data is required to be such that the value of ilower on any process \(p\) be exactly one more than the value of iupper on process \(p-1\). Note that the first row of the global matrix may start with any integer value. In particular, one may use zero- or one-based indexing.

For square matrices, jlower and jupper typically should match ilower and iupper, respectively. For rectangular matrices, jlower and jupper should define a partitioning of the columns. This partitioning must be used for any vector \(v\) that will be used in matrix-vector products with the rectangular matrix. The matrix data structure may use jlower and jupper to store the diagonal blocks (rectangular in general) of the matrix separately from the rest of the matrix.

Collective.

HYPRE_Int HYPRE_IJMatrixDestroy(HYPRE_IJMatrix matrix)

Destroy a matrix object.

An object should be explicitly destroyed using this destructor when the user’s code no longer needs direct access to it. Once destroyed, the object must not be referenced again. Note that the object may not be deallocated at the completion of this call, since there may be internal package references to the object. The object will then be destroyed when all internal reference counts go to zero.

HYPRE_Int HYPRE_IJMatrixInitialize(HYPRE_IJMatrix matrix)

Prepare a matrix object for setting coefficient values.

This routine will also re-initialize an already assembled matrix, allowing users to modify coefficient values.

HYPRE_Int HYPRE_IJMatrixInitialize_v2(HYPRE_IJMatrix matrix, HYPRE_MemoryLocation memory_location)

Prepare a matrix object for setting coefficient values.

This routine will also re-initialize an already assembled matrix, allowing users to modify coefficient values. This routine also specifies the memory location, i.e. host or device.

HYPRE_Int HYPRE_IJMatrixSetValues(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_Int *ncols, const HYPRE_BigInt *rows, const HYPRE_BigInt *cols, const HYPRE_Complex *values)

Sets values for nrows rows or partial rows of the matrix.

The arrays ncols and rows are of dimension nrows and contain the number of columns in each row and the row indices, respectively. The array cols contains the column indices for each of the rows, and is ordered by rows. The data in the values array corresponds directly to the column entries in cols. Erases any previous values at the specified locations and replaces them with new ones, or, if there was no value there before, inserts a new one if set locally. Note that it is not possible to set values on other processors. If one tries to set a value from proc i on proc j, proc i will erase all previous occurrences of this value in its stack (including values generated with AddToValues), and treat it like a zero value. The actual value needs to be set on proc j.

Note that a threaded version (threaded over the number of rows) will be called if HYPRE_IJMatrixSetOMPFlag is set to a value != 0. This requires that rows[i] != rows[j] for i!= j and is only efficient if a large number of rows is set in one call to HYPRE_IJMatrixSetValues.

Not collective.

HYPRE_Int HYPRE_IJMatrixSetConstantValues(HYPRE_IJMatrix matrix, HYPRE_Complex value)

Sets all matrix coefficients of an already assembled matrix to value.

HYPRE_Int HYPRE_IJMatrixAddToValues(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_Int *ncols, const HYPRE_BigInt *rows, const HYPRE_BigInt *cols, const HYPRE_Complex *values)

Adds to values for nrows rows or partial rows of the matrix.

Usage details are analogous to HYPRE_IJMatrixSetValues. Adds to any previous values at the specified locations, or, if there was no value there before, inserts a new one. AddToValues can be used to add to values on other processors.

Note that a threaded version (threaded over the number of rows) will be called if HYPRE_IJMatrixSetOMPFlag is set to a value != 0. This requires that rows[i] != rows[j] for i!= j and is only efficient if a large number of rows is added in one call to HYPRE_IJMatrixAddToValues.

Not collective.

HYPRE_Int HYPRE_IJMatrixSetValues2(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_Int *ncols, const HYPRE_BigInt *rows, const HYPRE_Int *row_indexes, const HYPRE_BigInt *cols, const HYPRE_Complex *values)

Sets values for nrows rows or partial rows of the matrix.

Same as IJMatrixSetValues, but with an additional row_indexes array that provides indexes into the cols and values arrays. Because of this, there can be gaps between the row data in these latter two arrays.

HYPRE_Int HYPRE_IJMatrixAddToValues2(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_Int *ncols, const HYPRE_BigInt *rows, const HYPRE_Int *row_indexes, const HYPRE_BigInt *cols, const HYPRE_Complex *values)

Adds to values for nrows rows or partial rows of the matrix.

Same as IJMatrixAddToValues, but with an additional row_indexes array that provides indexes into the cols and values arrays. Because of this, there can be gaps between the row data in these latter two arrays.

HYPRE_Int HYPRE_IJMatrixAssemble(HYPRE_IJMatrix matrix)

Finalize the construction of the matrix before using.

HYPRE_Int HYPRE_IJMatrixGetRowCounts(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_BigInt *rows, HYPRE_Int *ncols)

Gets number of nonzeros elements for nrows rows specified in rows and returns them in ncols, which needs to be allocated by the user.

HYPRE_Int HYPRE_IJMatrixGetValues(HYPRE_IJMatrix matrix, HYPRE_Int nrows, HYPRE_Int *ncols, HYPRE_BigInt *rows, HYPRE_BigInt *cols, HYPRE_Complex *values)

Gets values for nrows rows or partial rows of the matrix.

Usage details are mostly analogous to HYPRE_IJMatrixSetValues. Note that if nrows is negative, the routine will return the column_indices and matrix coefficients of the (-nrows) rows contained in rows.

HYPRE_Int HYPRE_IJMatrixSetObjectType(HYPRE_IJMatrix matrix, HYPRE_Int type)

Set the storage type of the matrix object to be constructed.

Currently, type can only be HYPRE_PARCSR.

Not collective, but must be the same on all processes.

See also

HYPRE_IJMatrixGetObject

HYPRE_Int HYPRE_IJMatrixGetObjectType(HYPRE_IJMatrix matrix, HYPRE_Int *type)

Get the storage type of the constructed matrix object.

HYPRE_Int HYPRE_IJMatrixGetLocalRange(HYPRE_IJMatrix matrix, HYPRE_BigInt *ilower, HYPRE_BigInt *iupper, HYPRE_BigInt *jlower, HYPRE_BigInt *jupper)

Gets range of rows owned by this processor and range of column partitioning for this processor.

HYPRE_Int HYPRE_IJMatrixGetObject(HYPRE_IJMatrix matrix, void **object)

Get a reference to the constructed matrix object.

See also

HYPRE_IJMatrixSetObjectType

HYPRE_Int HYPRE_IJMatrixSetRowSizes(HYPRE_IJMatrix matrix, const HYPRE_Int *sizes)

(Optional) Set the max number of nonzeros to expect in each row.

The array sizes contains estimated sizes for each row on this process. This call can significantly improve the efficiency of matrix construction, and should always be utilized if possible.

Not collective.

HYPRE_Int HYPRE_IJMatrixSetDiagOffdSizes(HYPRE_IJMatrix matrix, const HYPRE_Int *diag_sizes, const HYPRE_Int *offdiag_sizes)

(Optional) Sets the exact number of nonzeros in each row of the diagonal and off-diagonal blocks.

The diagonal block is the submatrix whose column numbers correspond to rows owned by this process, and the off-diagonal block is everything else. The arrays diag_sizes and offdiag_sizes contain estimated sizes for each row of the diagonal and off-diagonal blocks, respectively. This routine can significantly improve the efficiency of matrix construction, and should always be utilized if possible.

Not collective.

HYPRE_Int HYPRE_IJMatrixSetMaxOffProcElmts(HYPRE_IJMatrix matrix, HYPRE_Int max_off_proc_elmts)

(Optional) Sets the maximum number of elements that are expected to be set (or added) on other processors from this processor This routine can significantly improve the efficiency of matrix construction, and should always be utilized if possible.

Not collective.

HYPRE_Int HYPRE_IJMatrixSetPrintLevel(HYPRE_IJMatrix matrix, HYPRE_Int print_level)

(Optional) Sets the print level, if the user wants to print error messages.

The default is 0, i.e. no error messages are printed.

HYPRE_Int HYPRE_IJMatrixSetOMPFlag(HYPRE_IJMatrix matrix, HYPRE_Int omp_flag)

(Optional) if set, will use a threaded version of HYPRE_IJMatrixSetValues and HYPRE_IJMatrixAddToValues.

This is only useful if a large number of rows is set or added to at once.

NOTE that the values in the rows array of HYPRE_IJMatrixSetValues or HYPRE_IJMatrixAddToValues must be different from each other !!!

This option is VERY inefficient if only a small number of rows is set or added at once and/or if reallocation of storage is required and/or if values are added to off processor values.

HYPRE_Int HYPRE_IJMatrixRead(const char *filename, MPI_Comm comm, HYPRE_Int type, HYPRE_IJMatrix *matrix)

Read the matrix from file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJMatrixReadMM(const char *filename, MPI_Comm comm, HYPRE_Int type, HYPRE_IJMatrix *matrix)

Read the matrix from MM file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJMatrixPrint(HYPRE_IJMatrix matrix, const char *filename)

Print the matrix to file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJMatrixPrintBinary(HYPRE_IJMatrix matrix, const char *filename)

Print the matrix to file in binary format.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJMatrixReadBinary(const char *filename, MPI_Comm comm, HYPRE_Int type, HYPRE_IJMatrix *matrix_ptr)

Read the matrix from file stored in binary format.

This is mainly for debugging purposes.

IJ Vectors

typedef struct hypre_IJVector_struct *HYPRE_IJVector

The vector object.

HYPRE_Int HYPRE_IJVectorCreate(MPI_Comm comm, HYPRE_BigInt jlower, HYPRE_BigInt jupper, HYPRE_IJVector *vector)

Create a vector object.

Each process owns some unique consecutive range of vector unknowns, indicated by the global indices jlower and jupper. The data is required to be such that the value of jlower on any process \(p\) be exactly one more than the value of jupper on process \(p-1\). Note that the first index of the global vector may start with any integer value. In particular, one may use zero- or one-based indexing.

Collective.

HYPRE_Int HYPRE_IJVectorDestroy(HYPRE_IJVector vector)

Destroy a vector object.

An object should be explicitly destroyed using this destructor when the user’s code no longer needs direct access to it. Once destroyed, the object must not be referenced again. Note that the object may not be deallocated at the completion of this call, since there may be internal package references to the object. The object will then be destroyed when all internal reference counts go to zero.

HYPRE_Int HYPRE_IJVectorInitialize(HYPRE_IJVector vector)

Prepare a vector object for setting coefficient values.

This routine will also re-initialize an already assembled vector, allowing users to modify coefficient values.

HYPRE_Int HYPRE_IJVectorInitialize_v2(HYPRE_IJVector vector, HYPRE_MemoryLocation memory_location)

Prepare a vector object for setting coefficient values.

This routine will also re-initialize an already assembled vector, allowing users to modify coefficient values. This routine also specifies the memory location, i.e. host or device.

HYPRE_Int HYPRE_IJVectorSetMaxOffProcElmts(HYPRE_IJVector vector, HYPRE_Int max_off_proc_elmts)

(Optional) Sets the maximum number of elements that are expected to be set (or added) on other processors from this processor This routine can significantly improve the efficiency of matrix construction, and should always be utilized if possible.

Not collective.

HYPRE_Int HYPRE_IJVectorSetNumComponents(HYPRE_IJVector vector, HYPRE_Int num_components)

(Optional) Sets the number of components (vectors) of a multivector.

A vector is assumed to have a single component when this function is not called. This function must be called prior to HYPRE_IJVectorInitialize.

HYPRE_Int HYPRE_IJVectorSetComponent(HYPRE_IJVector vector, HYPRE_Int component)

(Optional) Sets the component identifier of a vector with multiple components (multivector).

This can be used for Set/AddTo/Get purposes.

HYPRE_Int HYPRE_IJVectorSetValues(HYPRE_IJVector vector, HYPRE_Int nvalues, const HYPRE_BigInt *indices, const HYPRE_Complex *values)

Sets values in vector.

The arrays values and indices are of dimension nvalues and contain the vector values to be set and the corresponding global vector indices, respectively. Erases any previous values at the specified locations and replaces them with new ones. Note that it is not possible to set values on other processors. If one tries to set a value from proc i on proc j, proc i will erase all previous occurrences of this value in its stack (including values generated with AddToValues), and treat it like a zero value. The actual value needs to be set on proc j.

Not collective.

HYPRE_Int HYPRE_IJVectorAddToValues(HYPRE_IJVector vector, HYPRE_Int nvalues, const HYPRE_BigInt *indices, const HYPRE_Complex *values)

Adds to values in vector.

Usage details are analogous to HYPRE_IJVectorSetValues. Adds to any previous values at the specified locations, or, if there was no value there before, inserts a new one. AddToValues can be used to add to values on other processors.

Not collective.

HYPRE_Int HYPRE_IJVectorAssemble(HYPRE_IJVector vector)

Finalize the construction of the vector before using.

HYPRE_Int HYPRE_IJVectorUpdateValues(HYPRE_IJVector vector, HYPRE_Int nvalues, const HYPRE_BigInt *indices, const HYPRE_Complex *values, HYPRE_Int action)

Update vectors by setting (action 1) or adding to (action 0) values in ‘vector’.

Note that this function cannot update values owned by other processes and does not allow repeated index values in ‘indices’.

Not collective.

HYPRE_Int HYPRE_IJVectorGetValues(HYPRE_IJVector vector, HYPRE_Int nvalues, const HYPRE_BigInt *indices, HYPRE_Complex *values)

Gets values in vector.

Usage details are analogous to HYPRE_IJVectorSetValues.

Not collective.

HYPRE_Int HYPRE_IJVectorSetObjectType(HYPRE_IJVector vector, HYPRE_Int type)

Set the storage type of the vector object to be constructed.

Currently, type can only be HYPRE_PARCSR.

Not collective, but must be the same on all processes.

See also

HYPRE_IJVectorGetObject

HYPRE_Int HYPRE_IJVectorGetObjectType(HYPRE_IJVector vector, HYPRE_Int *type)

Get the storage type of the constructed vector object.

HYPRE_Int HYPRE_IJVectorGetLocalRange(HYPRE_IJVector vector, HYPRE_BigInt *jlower, HYPRE_BigInt *jupper)

Returns range of the part of the vector owned by this processor.

HYPRE_Int HYPRE_IJVectorGetObject(HYPRE_IJVector vector, void **object)

Get a reference to the constructed vector object.

See also

HYPRE_IJVectorSetObjectType

HYPRE_Int HYPRE_IJVectorSetPrintLevel(HYPRE_IJVector vector, HYPRE_Int print_level)

(Optional) Sets the print level, if the user wants to print error messages.

The default is 0, i.e. no error messages are printed.

HYPRE_Int HYPRE_IJVectorRead(const char *filename, MPI_Comm comm, HYPRE_Int type, HYPRE_IJVector *vector)

Read the vector from file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJVectorReadBinary(const char *filename, MPI_Comm comm, HYPRE_Int type, HYPRE_IJVector *vector)

Read the vector from binary file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJVectorPrint(HYPRE_IJVector vector, const char *filename)

Print the vector to file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJVectorPrintBinary(HYPRE_IJVector vector, const char *filename)

Print the vector to binary file.

This is mainly for debugging purposes.

HYPRE_Int HYPRE_IJVectorInnerProd(HYPRE_IJVector x, HYPRE_IJVector y, HYPRE_Real *prod)

Computes the inner product between two vectors.