Utilities

group Utilities

Various utilities available in hypre.

Multiprecision

enum HYPRE_Precision

Available precisions.

Values:

enumerator HYPRE_REAL_SINGLE

enumerator HYPRE_REAL_DOUBLE

enumerator HYPRE_REAL_LONGDOUBLE

HYPRE_Int HYPRE_SetGlobalPrecision(HYPRE_Precision precision): Set the global default runtime precision.

HYPRE_Int HYPRE_GetGlobalPrecision(HYPRE_Precision *precision): Get the global default runtime precision.

Memory Management

enum _HYPRE_MemoryLocation

Memory location.

Values:

enumerator HYPRE_MEMORY_UNDEFINED

enumerator HYPRE_MEMORY_HOST

enumerator HYPRE_MEMORY_DEVICE

typedef enum _HYPRE_MemoryLocation HYPRE_MemoryLocation: Memory location.

HYPRE_Int HYPRE_SetMemoryLocation(HYPRE_MemoryLocation memory_location): (Optional) Sets the default (abstract) memory location.

HYPRE_Int HYPRE_GetMemoryLocation(HYPRE_MemoryLocation *memory_location): (Optional) Gets a pointer to the default (abstract) memory location.

Execution Policy

enum _HYPRE_ExecutionPolicy

Execution Policy.

Values:

enumerator HYPRE_EXEC_UNDEFINED

enumerator HYPRE_EXEC_HOST

enumerator HYPRE_EXEC_DEVICE

typedef enum _HYPRE_ExecutionPolicy HYPRE_ExecutionPolicy: Execution Policy.

HYPRE_Int HYPRE_SetExecutionPolicy(HYPRE_ExecutionPolicy exec_policy): (Optional) Sets the default execution policy.

HYPRE_Int HYPRE_GetExecutionPolicy(HYPRE_ExecutionPolicy *exec_policy): (Optional) Gets a pointer to the default execution policy.

const char *HYPRE_GetExecutionPolicyName(HYPRE_ExecutionPolicy exec_policy): (Optional) Returns a string denoting the execution policy passed as input.

Error Codes

HYPRE_Int HYPRE_GetGlobalError(MPI_Comm comm): Return an aggregate error code representing the collective status of all ranks.

HYPRE_Int HYPRE_GetError(void): Return the current hypre error flag.

HYPRE_Int HYPRE_CheckError(HYPRE_Int hypre_ierr, HYPRE_Int hypre_error_code): Check if the given error flag contains the given error code.

HYPRE_Int HYPRE_GetErrorArg(void): Return the index of the argument (counting from 1) where argument error (HYPRE_ERROR_ARG) has occured.

void HYPRE_DescribeError(HYPRE_Int hypre_ierr, char *descr): Describe the given error flag in the given string.

HYPRE_Int HYPRE_ClearAllErrors(void): Clear the hypre error flag.

HYPRE_Int HYPRE_ClearError(HYPRE_Int hypre_error_code): Clear the given error code from the hypre error flag.

HYPRE_Int HYPRE_SetPrintErrorMode(HYPRE_Int mode): Set behavior for printing errors: mode 0 = stderr, mode 1 = memory buffer.

HYPRE_Int HYPRE_SetPrintErrorVerbosity(HYPRE_Int code, HYPRE_Int verbosity): Set which error code messages to record for printing: code is an error code such as HYPRE_ERROR_CONV, code -1 = all codes, verbosity 0 = do not record.

HYPRE_Int HYPRE_GetErrorMessages(char **buffer, HYPRE_Int *bufsz): Return a buffer of error messages and clear them in hypre.

HYPRE_Int HYPRE_PrintErrorMessages(MPI_Comm comm): Print the error messages and clear them in hypre.

HYPRE_Int HYPRE_ClearErrorMessages(void): Clear the error messages in hypre and free any related memory allocated.

HYPRE_ERROR_GENERIC

HYPRE_ERROR_MEMORY

HYPRE_ERROR_ARG

HYPRE_ERROR_CONV

HYPRE_MAX_FILE_NAME_LEN

HYPRE_MAX_MSG_LEN

Initialize and Finalize

HYPRE_Int HYPRE_Initialize(void): (Required) Initializes the hypre library.

HYPRE_Int HYPRE_DeviceInitialize(void): (Optional) Initializes GPU features in the hypre library.

HYPRE_Int HYPRE_Finalize(void): (Required) Finalizes the hypre library.

HYPRE_Int HYPRE_Initialized(void): (Optional) Returns true if the hypre library has been initialized but not finalized yet.

HYPRE_Int HYPRE_Finalized(void): (Optional) Returns true if the hypre library has been finalized but not re-initialized yet.

HYPRE_Init()

(Required) Initializes the hypre library.

This function is provided for backward compatibility. Please, use HYPRE_Initialize instead.

Miscellaneous Information

HYPRE_Int HYPRE_PrintDeviceInfo(void): Print GPU information.

HYPRE_Int HYPRE_MemoryPrintUsage(MPI_Comm comm, HYPRE_Int level, const char *function, HYPRE_Int line)

Prints the memory usage of the current process.

This function prints the memory usage details of the process to standard output. It provides information such as the virtual memory size, resident set size, and other related statistics including GPU memory usage for device builds.

Note

The function is designed to be platform-independent but may provide different levels of detail depending on the underlying operating system (e.g., Linux, macOS). However, this function does not lead to correct memory usage statistics on Windows platforms.

Parameters:

comm – [in] The MPI communicator. This parameter allows the function to print memory usage information for the process within the context of an MPI program.
level – [in] The level of detail in the memory statistics output.
- 1 : Display memory usage statistics for each MPI rank.
- 2 : Display aggregate memory usage statistics over MPI ranks.
function – [in] The name of the function from which HYPRE_MemoryPrintUsage is called. This is typically set to __func__, which automatically captures the name of the calling function. This variable can also be used to denote a region name.
line – [in] The line number in the source file where HYPRE_MemoryPrintUsage is called. This is typically set to __LINE__, which automatically captures the line number. The line number can be omitted by passing a negative value to this variable.

Returns:

Returns an integer status code. 0 indicates success, while a non-zero value indicates an error occurred.

Library Version Information

HYPRE_Int HYPRE_Version(char **version_ptr): Allocates and returns a string with version number information in it.

HYPRE_Int HYPRE_VersionNumber(HYPRE_Int *major_ptr, HYPRE_Int *minor_ptr, HYPRE_Int *patch_ptr, HYPRE_Int *single_ptr)

Returns version number information in integer form.

Use ‘NULL’ for values not needed. The argument {\tt single} is a single sortable integer representation of the release number.

HYPRE_VERSION

Umpire and GPU Memory Pooling

HYPRE_Int HYPRE_SetUmpireDevicePoolSize(size_t nbytes)

Sets the size of the Umpire device memory pool.

Parameters:: nbytes – [in] The size of the device memory pool in bytes.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpireUMPoolSize(size_t nbytes)

Sets the size of the Umpire unified memory pool.

Parameters:: nbytes – [in] The size of the unified memory pool in bytes.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpireHostPoolSize(size_t nbytes)

Sets the size of the Umpire host memory pool.

Parameters:: nbytes – [in] The size of the host memory pool in bytes.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpirePinnedPoolSize(size_t nbytes)

Sets the size of the Umpire pinned memory pool.

Parameters:: nbytes – [in] The size of the pinned memory pool in bytes.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpireDevicePoolName(const char *pool_name)

Sets the name of the Umpire device memory pool.

Parameters:: pool_name – [in] The name to assign to the device memory pool.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpireUMPoolName(const char *pool_name)

Sets the name of the Umpire unified memory pool.

Parameters:: pool_name – [in] The name to assign to the unified memory pool.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpireHostPoolName(const char *pool_name)

Sets the name of the Umpire host memory pool.

Parameters:: pool_name – [in] The name to assign to the host memory pool.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUmpirePinnedPoolName(const char *pool_name)

Sets the name of the Umpire pinned memory pool.

Parameters:: pool_name – [in] The name to assign to the pinned memory pool.
Returns:: Returns hypre’s global error code, where 0 indicates success.

Miscellaneous

HYPRE_Int HYPRE_SetLogLevel(HYPRE_Int log_level)

Sets the logging level for the HYPRE library.

The following options are available for log_level:

0 : (default) No messaging.
1 : Display memory usage statistics for each MPI rank.
2 : Display aggregate memory usage statistics over MPI ranks.

Note

Log level codes can be combined using bitwise OR to enable multiple logging behaviors simultaneously.

Parameters:: log_level – The logging level to set.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetSpTransUseVendor(HYPRE_Int use_vendor)

Specifies the algorithm used for sparse matrix transposition in device builds.

The following options are available for use_vendor:

0 : Use hypre’s internal implementation.
1 : (default) Use the vendor library’s implementation. This includes:
- cuSPARSE for CUDA (HYPRE_USING_CUSPARSE)
- rocSPARSE for HIP (HYPRE_USING_ROCSPARSE)
- oneMKL for SYCL (HYPRE_USING_ONEMKLSPARSE)

Parameters:: use_vendor – Indicates whether to use the internal or vendor-provided implementation.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetSpMVUseVendor(HYPRE_Int use_vendor)

Specifies the algorithm used for sparse matrix/vector multiplication in device builds.

The following options are available for use_vendor:

0 : Use hypre’s internal implementation.
1 : (default) Use the vendor library’s implementation. This includes:
- cuSPARSE for CUDA (HYPRE_USING_CUSPARSE)
- rocSPARSE for HIP (HYPRE_USING_ROCSPARSE)
- oneMKL for SYCL (HYPRE_USING_ONEMKLSPARSE)

Parameters:: use_vendor – Indicates whether to use the internal or vendor-provided implementation.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetSpGemmUseVendor(HYPRE_Int use_vendor)

Specifies the algorithm used for sparse matrix/matrix multiplication in device builds.

The following options are available for use_vendor:

0 : Use hypre’s internal implementation.
1 : Use the vendor library’s implementation. This includes:
- cuSPARSE for CUDA (HYPRE_USING_CUSPARSE)
- rocSPARSE for HIP (HYPRE_USING_ROCSPARSE)
- oneMKL for SYCL (HYPRE_USING_ONEMKLSPARSE)

Note

The default value is 1, except for CUDA builds, which is zero.

Parameters:: use_vendor – Indicates whether to use the internal or vendor-provided implementation.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetUseGpuRand(HYPRE_Int use_curand)

Specifies the algorithm used for generating random numbers in device builds.

The following options are available for use_curand:

0 : random numbers are generated on the host and copied to device memory.
1 : (default) Use the vendor library’s implementation. This includes:
- cuSPARSE for CUDA (HYPRE_USING_CUSPARSE)
- rocSPARSE for HIP (HYPRE_USING_ROCSPARSE)
- oneMKL for SYCL (HYPRE_USING_ONEMKLSPARSE)

Parameters:: use_curand – Indicates whether to use the vendor-provided implementation or not.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_Int HYPRE_SetGpuAwareMPI(HYPRE_Int use_gpu_aware_mpi)

Configures the usage of GPU-aware MPI for communication in device builds.

The following options are available for use_gpu_aware_mpi:

0 : MPI buffers are transferred between device and host memory. Communication occurs on the host.
1 : MPI communication is performed directly from the device using device-resident buffers.

Note

This option requires hypre to be configured with GPU-aware MPI support for it to take effect.

Parameters:: use_gpu_aware_mpi – Specifies whether to enable GPU-aware MPI communication or not.
Returns:: Returns hypre’s global error code, where 0 indicates success.

HYPRE_SetSpGemmUseCusparse(use_vendor)