API Reference

This chapter documents every public function exported by libHYPREDRV. The reference below is generated directly from the Doxygen comments in include/HYPREDRV.h.

Why use libHYPREDRV?

The hypredrive executable is well-suited for file-based workflows: provide a matrix, a YAML configuration, and get a solution. libHYPREDRV serves the complementary use case: your application already has an assembled HYPRE_IJMatrix/HYPRE_IJVector in memory and needs a low-overhead path to HYPRE’s solver stack, configurable at runtime from a YAML string or file.

Typical benefits:

  • Runtime configurability — swap solvers and preconditioners without recompiling; pass different YAML strings in different code paths.

  • Minimal boilerplate — three to five HYPREDRV_* calls replace dozens of direct HYPRE API calls for common solver setups.

  • Statistics and timing — built-in timing infrastructure produces structured output for benchmarking; reuse statistics across repetitions.

  • Preconditioner reuse — attach a long-lived preconditioner object across multiple right-hand sides or timesteps without rebuilding the setup phase.

Usage Notes

For a full library-mode walkthrough and complete code examples, see Library Examples (libHYPREDRV).

Two rules matter most when using the API directly:

  • HYPREDRV_SetLibraryMode must be called before HYPREDRV_InputArgsParse when your application owns the HYPRE matrices and vectors passed through LinearSystemSet*.

  • HYPREDRV_LinearSolverDestroy also destroys the associated preconditioner, so there is no need to call HYPREDRV_PreconDestroy afterward unless you are managing the preconditioner separately.

For embedded applications that keep multiple HYPREDRV_t objects alive at once, use the object-bound annotation and hierarchical-stats APIs directly on the relevant handle. In the current API, HYPREDRV_Annotate* and HYPREDRV_StatsLevel* all take a HYPREDRV_t argument and record/query state for that specific object.

Reference by Topic

The public API is organized below by workflow stage. The detailed per-function documentation remains in the generated Doxygen section that follows.

Core Type

  • HYPREDRV_t - Opaque handle that owns the hypredrive configuration, objects, and runtime state.

Lifecycle and Setup

Input Parsing and Presets

Linear System Setup

Linear System Accessors

State Vectors

Solver and Preconditioner

Statistics and Timing

Annotation

See Library Examples (libHYPREDRV) for worked examples that use this API.

Detailed API Reference

typedef struct hypredrv_struct *HYPREDRV_t

Opaque handle for a hypredrive context.

The main object type for the HYPREDRV library encapsulates the parsed input parameters, linear-system objects, solver/preconditioner state, performance statistics, and MPI communication context. Create it with HYPREDRV_Create() and destroy it with HYPREDRV_Destroy().

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_Initialize(void)

Initializes the HYPREDRV library.

Initializes the HYPREDRV library for use in the application. This function sets up the necessary environment for the HYPREDRV library by initializing the HYPRE library and its device-specific components. It ensures that initialization occurs only once even if called multiple times.

Example Usage: 

HYPREDRV_SAFE_CALL(HYPREDRV_Initialize());

Note

This function must be called after MPI_Init and before any other HYPREDRV functions are used. It is safe to call this function multiple times; only the first call will perform the initialization.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_Finalize(void)

Finalizes the HYPREDRV library.

Cleans up and releases any resources allocated by the HYPREDRV library. This function automatically destroys any live HYPREDRV_t objects still owned by the library, then finalizes the HYPRE library and its device-specific components. It should be the last HYPREDRV-related function called before the application exits.

Example Usage: 

HYPREDRV_SAFE_CALL(HYPREDRV_Finalize());

Note

This function should be called before MPI_Finalize. It is safe to call this function even if HYPREDRV_Initialize was not successfully called or was not called at all; in such cases, the function will have no effect. Auto-destroyed live handles are reclaimed internally, but caller-owned variables are not rewritten to NULL because only the library sees the live-object registry.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL void HYPREDRV_ErrorCodeDescribe(uint32_t error_code)

Describes and handles an error code from HYPREDRV operations.

This function processes an error code from HYPREDRV operations. If the error code is non-zero, it will:

  1. Describe the error using the internal error code description system

  2. Print the error message to stderr

  3. Clear the error message buffer

If the error code is zero (indicating no error), the function returns immediately without taking any action.

Example Usage: 

// Direct usage:
uint32_t error = some_HYPREDRV_operation();
HYPREDRV_ErrorCodeDescribe(error);

// Preferred usage with macro:
HYPREDRV_SAFE_CALL(some_HYPREDRV_operation());

Note

This function prints the error description and returns normally - it does NOT call MPI_Abort. For an abort-on-error helper, use the HYPREDRV_SAFE_CALL macro (defined in HYPREDRV_utils.h), which calls this function and then calls MPI_Abort when the error code is non-zero.

Parameters:

error_code – The error code to be processed (uint32_t)

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_ErrorInvalidValue(const char *message)

Record and return an invalid-value error with optional context.

This helper is intended for thin language-interface shims that validate fixed-width ABI values before forwarding to the typed HYPREDRV C API.

Parameters:

message – Optional human-readable context for the error chain.

Returns:

Current HYPREDRV error code bitfield.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_Create(MPI_Comm comm, HYPREDRV_t *hypredrv_ptr)

Create a HYPREDRV object.

This function allocates memory for a HYPREDRV object and initializes it with the provided MPI communicator. The newly created object is returned through the hypredrv_ptr parameter.

Example Usage: 

HYPREDRV_t *hypredrv;
MPI_Comm comm = MPI_COMM_WORLD; // or any other valid MPI_Comm
HYPREDRV_SAFE_CALL(HYPREDRV_Create(comm, &hypredrv));

Note

It is the caller’s responsibility to ensure that the MPI environment is properly initialized before calling this function. The function does not initialize or finalize the MPI environment.

Parameters:

  • comm – The MPI communicator to be associated with the HYPREDRV object. This communicator is used for parallel communications in the underlying HYPRE library calls.

  • hypredrv_ptr – A pointer to the HYPREDRV_t object where the address of the newly allocated HYPREDRV object will be stored. After the function call, *hypredrv_ptr will point to the allocated object.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_Destroy(HYPREDRV_t *hypredrv_ptr)

Destroy a HYPREDRV object.

This function deallocates the memory for a HYPREDRV object and performs necessary cleanup for its associated resources. It destroys HYPRE matrices and vectors created and used by the object, deallocates any input arguments, and finally frees the HYPREDRV object itself. After this function is called, the pointer to the HYPREDRV object is set to NULL to prevent any dangling references.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created and used) ...
HYPREDRV_SAFE_CALL(HYPREDRV_Destroy(&hypredrv));
// hypredrv is now NULL.

Note

It is the caller’s responsibility to ensure that hypredrv_ptr is a valid pointer to a HYPREDRV_t object. Passing an invalid pointer or a pointer to an already destroyed object can lead to undefined behavior.

Parameters:

hypredrv_ptr – A pointer to the HYPREDRV_t object that is to be destroyed. This pointer should have been initialized by HYPREDRV_Create function.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PrintLibInfo(MPI_Comm comm, int print_datetime)

Print library information at entrance.

This function optionally prints the current date and time, followed by version information about hypredrive and hypre.

Example Usage: 

MPI_Comm comm = MPI_COMM_WORLD; // or any other valid MPI_Comm
HYPREDRV_SAFE_CALL(HYPREDRV_PrintLibInfo(comm, 1));

Parameters:

  • comm – The MPI communicator associated with the HYPREDRV object.

  • print_datetime – Whether to print the date/time header (nonzero => on).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PrintSystemInfo(MPI_Comm comm)

Print system information.

Example Usage: 

MPI_Comm comm = MPI_COMM_WORLD; // or any other valid MPI_Comm
HYPREDRV_SAFE_CALL(HYPREDRV_PrintSystemInfo(comm));

Note

This function uses conditional compilation to determine what information about the system (machine) to print.

Parameters:

comm – The MPI communicator associated with the HYPREDRV object.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PrintExitInfo(MPI_Comm comm, const char *argv0)

Print library information at exit.

This function prints the driver name followed by the current date and time.

Example Usage: 

MPI_Comm comm = MPI_COMM_WORLD; // or any other valid MPI_Comm
HYPREDRV_SAFE_CALL(HYPREDRV_PrintExitInfo(comm, argv[0]));

Note

This function is intended to be used just before finishing the driver application

Parameters:

  • comm – The MPI communicator associated with the HYPREDRV object.

  • argv0 – The application driver name.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsParse(int argc, char **argv, HYPREDRV_t hypredrv)

Parse input arguments for a HYPREDRV object.

This function parses the command-line arguments and immediately applies the resulting configuration: HYPRE execution policy and Umpire pool sizes are set (skipped in library mode, where the caller owns HYPRE initialization), stats counters are initialized, and any preconditioner-reuse timestep schedule is loaded. No separate “configure” call is needed after this function.

Example Usage: 

HYPREDRV_t hypredrv = NULL;
int argc = ...; // Number of arguments
char **argv = ...; // Argument strings
// ... (hypredrv is created) ...
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsParse(argc, argv, hypredrv));

Note

It is expected that argv[1] is the name of the input file in YAML format

Parameters:

  • argc – The count of command-line arguments.

  • argv – The array of command-line argument strings.

  • hypredrv – The HYPREDRV_t object whose input arguments are to be parsed and set.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_SetLibraryMode(HYPREDRV_t hypredrv)

Enable library (borrowed-ownership) mode for a HYPREDRV object.

When library mode is active, matrices and vectors passed via HYPREDRV_LinearSystemSetMatrix(), HYPREDRV_LinearSystemSetRHS(), HYPREDRV_LinearSystemSetInitialGuess(), etc. are treated as borrowed references: HYPREDRV will not destroy them when the object is destroyed or when new objects are set. The caller retains full ownership and must free these objects independently.

When library mode is inactive (the default), ownership of non-NULL objects passed to those setters is transferred to HYPREDRV, which will destroy them at the appropriate time.

Example Usage: 

HYPREDRV_t hypredrv;
// ... (hypredrv is created) ...
HYPREDRV_SAFE_CALL(HYPREDRV_SetLibraryMode(hypredrv));

Note

This flag is a one-way latch: once set it cannot be unset for the lifetime of the HYPREDRV_t object. Create a new object if you need to switch back to owned mode.

Parameters:

hypredrv – The HYPREDRV_t object (passed by value - it is an opaque pointer, not a pointer-to-pointer).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_ObjectSetName(HYPREDRV_t hypredrv, const char *name)

Set or clear an optional display name for a HYPREDRV object.

The name is used in human-readable statistics banners such as STATISTICS SUMMARY for <name>:. Passing NULL or an empty string clears the current label.

Embedded applications can use this to identify multiple concurrent HYPREDRV_t objects without modifying an authoritative YAML file. When general.name is present in the parsed YAML input, it populates the same label automatically.

Parameters:

  • hypredrv – The HYPREDRV_t object to label.

  • name – The optional display name, or NULL to clear it.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsGetWarmup(HYPREDRV_t hypredrv, int *warmup)

Retrieve the warmup setting from a HYPREDRV object.

Example Usage: 

int warmup = 0;
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsGetWarmup(hypredrv, &warmup));

Parameters:

  • hypredrv – The HYPREDRV_t object to query.

  • warmup – [out] Set to the warmup flag value (0 or 1) on success.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsGetNumRepetitions(HYPREDRV_t hypredrv, int *num_reps)

Retrieve the number of repetitions from a HYPREDRV object.

Example Usage: 

int num_reps = 0;
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsGetNumRepetitions(hypredrv, &num_reps));

Parameters:

  • hypredrv – The HYPREDRV_t object to query.

  • num_reps – [out] Set to the number of repetitions on success.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsGetNumLinearSystems(HYPREDRV_t hypredrv, int *num_ls)

Retrieve the number of linear systems from a HYPREDRV object.

Example Usage: 

int num_ls = 0;
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsGetNumLinearSystems(hypredrv, &num_ls));

Parameters:

  • hypredrv – The HYPREDRV_t object to query.

  • num_ls – [out] Set to the number of linear systems on success.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsGetNumPreconVariants(HYPREDRV_t hypredrv, int *num_variants)

Retrieve the number of preconditioner variants from a HYPREDRV object.

Example Usage: 

   int num_variants = 0;
   HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsGetNumPreconVariants(hypredrv,
&num_variants));

Parameters:

  • hypredrv – The HYPREDRV_t object to query.

  • num_variants – [out] Set to the number of preconditioner variants on success.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsSetPreconVariant(HYPREDRV_t hypredrv, int variant_idx)

Set the active preconditioner variant index.

This function sets which preconditioner variant should be used for subsequent solve operations. It updates the active variant and destroys any existing solver/preconditioner objects to avoid stale configuration.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are set) ...
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsSetPreconVariant(hypredrv, 1));

Parameters:

  • hypredrv – The HYPREDRV_t object for which to set the variant.

  • variant_idx – The zero-based index of the variant to activate (must be in range [0, num_variants-1]).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure (e.g., invalid index, object not initialized).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsSetPreconPreset(HYPREDRV_t hypredrv, const char *preset)

Configure the active preconditioner variant using a predefined preset.

This function allows library users to select a named preset (e.g., “poisson”, “elasticity-2D”) without calling HYPREDRV_InputArgsParse. It ensures that the input argument structure exists and that solver/preconditioner defaults are initialized, then applies the preset to the active variant only.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created) ...
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsSetPreconPreset(hypredrv, "poisson"));

Parameters:

  • hypredrv – The HYPREDRV_t object for which to set the preset.

  • preset – The preset name string.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure (e.g., invalid preset, object not initialized).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_InputArgsSetSolverPreset(HYPREDRV_t hypredrv, const char *preset)

Configure the solver using a predefined or registered preset name.

This function allows library users to select either a built-in named solver (e.g., “pcg”, “gmres”, “fgmres”, “bicgstab”) or a custom registered solver preset without calling HYPREDRV_InputArgsParse. It ensures that the input argument structure exists, then updates the solver method and arguments.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created) ...
HYPREDRV_SAFE_CALL(HYPREDRV_InputArgsSetSolverPreset(hypredrv, "pcg"));

Parameters:

  • hypredrv – The HYPREDRV_t object for which to set the solver.

  • preset – The solver name string (e.g., “pcg”, “gmres”) or a custom registered solver preset.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure (e.g., invalid solver name, object not initialized).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_SolverPresetRegister(const char *name, const char *yaml_text, const char *help)

Register a custom solver preset.

Registers a named preset from a YAML text string, making it available to HYPREDRV_InputArgsSetSolverPreset(). The preset text must be a valid YAML snippet that expands under solver:.

Parameters:

  • name – Unique preset name (case-insensitive; ‘-’ and ‘_’ are equivalent).

  • yaml_text – YAML snippet string (e.g. “fgmres:\n max_iter: 20”).

  • help – Short description shown in preset listings (may be NULL).

Returns:

0 on success, non-zero on failure (duplicate name, NULL args, alloc failure, or conflict with built-in solver names).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PreconPresetRegister(const char *name, const char *yaml_text, const char *help)

Register a custom preconditioner preset.

Registers a named preset from a YAML text string, making it available to HYPREDRV_InputArgsSetPreconPreset() and the YAML preset: key. The preset text must be a valid YAML snippet that expands under preconditioner:.

Example Usage: 

HYPREDRV_SAFE_CALL(HYPREDRV_PreconPresetRegister(
   "my_amg", "amg:\n  max_iter: 1\n  tolerance: 1e-8", "Custom AMG preset"));

Parameters:

  • name – Unique preset name (case-insensitive; ‘-’ and ‘_’ are equivalent).

  • yaml_text – YAML snippet string (e.g. “amg:\n max_iter: 1”).

  • help – Short description shown in preset listings (may be NULL).

Returns:

0 on success, non-zero on failure (duplicate name, NULL args, alloc failure).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemBuild(HYPREDRV_t hypredrv)

Build the linear system (matrix, RHS, and LHS) according to the YAML input passed to the HYPREDRV object.

The matrix is read from file. Vectors might be read from file or built according to predetermined options passed via YAML.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemBuild(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

hypredrv – The HYPREDRV_t object for which the linear system matrix is to be built.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemReadMatrix(HYPREDRV_t hypredrv)

Read the linear system matrix from file for a HYPREDRV object.

This function is responsible for reading the matrix data of a linear system associated with a HYPREDRV object. It performs the reading process given input arguments related to the linear system, and uses a pointer to store the read matrix. After reading the matrix, it retrieves and returns the error code generated during the process.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemReadMatrix(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

hypredrv – The HYPREDRV_t object for which the linear system matrix is to be read.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetMatrix(HYPREDRV_t hypredrv, HYPRE_Matrix mat_A)

Set the linear system matrix for a HYPREDRV object.

This function is responsible for setting the matrix data of a linear system associated with a HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetMatrix(hypredrv, mat_A));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the linear system matrix is to be associated.

  • mat_A – The HYPRE_Matrix object for the linear system matrix.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetRHS(HYPREDRV_t hypredrv, HYPRE_Vector vec)

Set the linear system right-hand side (RHS) vector for a HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetRHS(hypredrv, vec));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the RHS vector of the linear system is to be set.

  • vec – The HYPRE_Vector vector object representing the RHS of the linear system (NULL if set from input file).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetMatrixFromCSR(HYPREDRV_t hypredrv, HYPRE_BigInt row_start, HYPRE_BigInt row_end, const HYPRE_BigInt *indptr, const HYPRE_BigInt *col_indices, const HYPRE_Real *data)

Build the linear-system matrix from per-rank CSR arrays.

Constructs a HYPRE_PARCSR matrix from the caller’s rank-local rows in CSR layout and installs it as the system matrix on the HYPREDRV object.

The function performs a single internal copy through HYPRE’s IJ assembly, so the caller’s indptr, col_indices, and data buffers are not aliased and may be released as soon as this call returns. HYPREDRV always takes ownership of the resulting matrix and destroys it on HYPREDRV_Destroy(), regardless of library mode.

The row range is hypre-style inclusive: rank-local rows are [row_start, row_end]. Column indices in col_indices are global. The union of [row_start, row_end] across all ranks must form a contiguous global row partition starting at 0.

Example Usage: 

HYPRE_BigInt row_start = ..., row_end = ...;     // local row range
HYPRE_BigInt *indptr   = ..., *col_idx  = ...;
HYPRE_Real   *data     = ...;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetMatrixFromCSR(
   hypredrv, row_start, row_end, indptr, col_idx, data));

Note

When called multiple times, any previously owned system matrix (and the preconditioner matrix derived from it) is destroyed first. Callers may release indptr, col_indices, and data as soon as this call returns; HYPRE copies the values during IJ assembly.

Note

Empty local row ranges are not currently supported by this API: every participating rank must provide at least one local row.

Note

Offset CSR slabs are supported: callers may pass indptr arrays with indptr[0] > 0 when col_indices and data include leading padding or are views into a larger CSR storage block.

Note

This C API does not receive buffer lengths. When indptr[nrows] > indptr[0], callers must provide col_indices and data buffers valid through index indptr[nrows] - 1.

Parameters:

  • hypredrv – The HYPREDRV_t object to associate the matrix with.

  • row_start – First locally-owned global row index (inclusive).

  • row_end – Last locally-owned global row index (inclusive).

  • indptr – CSR row pointers, length nrows+1, where nrows = row_end - row_start + 1. indptr[0] may be zero (standard CSR) or a nonnegative offset into col_indices / data.

  • col_indices – Global column indices. The consumed entries are col_indices[indptr[0] … indptr[nrows]-1].

  • data – Nonzero values. The consumed entries are data[indptr[0] … indptr[nrows]-1].

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetRHSFromArray(HYPREDRV_t hypredrv, HYPRE_BigInt row_start, HYPRE_BigInt row_end, const HYPRE_Real *values)

Build the linear-system right-hand side from a per-rank values array.

Constructs a HYPRE_PARCSR vector from the caller’s rank-local values and installs it as the RHS on the HYPREDRV object.

The function copies values into HYPRE-owned storage; the caller’s buffer may be released as soon as this call returns. HYPREDRV always takes ownership of the resulting vector and destroys it on HYPREDRV_Destroy(), regardless of library mode.

Example Usage: 

HYPRE_Real *b = ...;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetRHSFromArray(
   hypredrv, row_start, row_end, b));

Note

Must be called after a system matrix has been installed. The row_start / row_end range must match the matrix row range owned by this rank.

Parameters:

  • hypredrv – The HYPREDRV_t object to associate the RHS with.

  • row_start – First locally-owned global row index (inclusive).

  • row_end – Last locally-owned global row index (inclusive).

  • values – Local RHS values, length row_end - row_start + 1.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetInitialGuess(HYPREDRV_t hypredrv, HYPRE_Vector vec)

Set the initial guess for the solution vector of the linear system for a HYPREDRV object.

This function is responsible for setting the initial guess for the solution vector of a linear system associated with a HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetInitialGuess(hypredrv, NULL));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Note

Ownership for non-NULL vec:

  • library mode ON (HYPREDRV_SetLibraryMode): borrowed (not destroyed by HYPREDRV).

  • library mode OFF: ownership is transferred to HYPREDRV.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the initial guess of the solution vector of the linear system is to be set.

  • vec – Optional initial-guess vector. If NULL, the initial guess is built from input/default behavior (x0_filename/init_guess_mode). If non-NULL, this vector is used as x0.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetSolution(HYPREDRV_t hypredrv, HYPRE_Vector vec)

Set the solution vector of the linear system for a HYPREDRV object.

Allows the caller to supply a pre-built HYPRE_Vector to use as the working solution buffer (the vector the linear solver writes its result into).

Example Usage: 

HYPRE_IJVector my_x; // previously created, same size as b
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetSolution(hypredrv,
                                                    (HYPRE_Vector)my_x));
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverApply(hypredrv));
// my_x now contains the solution.

Note

Typical use: provide your own HYPRE_ParVector allocation before calling HYPREDRV_LinearSolverApply() so the result is written directly into your buffer. You can then retrieve the same pointer via HYPREDRV_LinearSystemGetSolution().

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • vec – The HYPRE_Vector to use as the solution buffer. If NULL, HYPREDRV allocates an internal buffer (vec_b must already be set). If non-NULL, the vector is borrowed - HYPREDRV will never destroy it.

Returns:

0 on success; nonzero error code otherwise. Returns an error when vec is NULL and the RHS vector has not been set yet.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetReferenceSolution(HYPREDRV_t hypredrv, HYPRE_Vector vec)

Set or refresh the reference solution vector used by GMRES tagged residual/error reporting.

This function updates the internal reference solution vector associated with the current linear system. The reference solution is consumed by GMRES tagged output modes (for example, when printing tagged residual or tagged error histories).

This vector can be tagged and scaled/unscaled internally during solve setup/apply.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetReferenceSolution(hypredrv, NULL));

Note

On hypre versions older than v3.0.0, this function is a no-op for GMRES tagged residual/error internals.

Note

Ownership for non-NULL vec:

  • library mode ON (HYPREDRV_SetLibraryMode): borrowed (not destroyed by HYPREDRV).

  • library mode OFF: ownership is transferred to HYPREDRV.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the reference solution vector is to be set or refreshed.

  • vec – Optional reference-solution vector. If NULL, the reference solution is updated using the existing file/default rules (xref_filename/xref_basename). If non-NULL, this vector is used directly as the reference solution.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemResetInitialGuess(HYPREDRV_t hypredrv)

Reset the initial guess of the solution vector for a HYPREDRV object to its original state as computed with HYPREDRV_LinearSystemSetInitialGuess.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemResetInitialGuess(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

hypredrv – The HYPREDRV_t object for which the initial guess of the solution vector is to be reset.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetPrecMatrix(HYPREDRV_t hypredrv, HYPRE_Matrix mat)

Set the matrix that is used to compute the preconditioner of a HYPREDRV object.

By default, the preconditioning matrix is the same as the linear system matrix. However, it is also possible to use an arbitrary matrix set by the user, e.g., a filtered version of the linear system matrix.

This matrix may be scaled/unscaled internally during solve setup/apply.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetPrecMatrix(hypredrv, NULL));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Note

Ownership for non-NULL mat:

  • library mode ON (HYPREDRV_SetLibraryMode): borrowed (not destroyed by HYPREDRV).

  • library mode OFF: ownership is transferred to HYPREDRV.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the preconditioner matrix is to be set.

  • mat – Optional preconditioner matrix. If NULL, the preconditioner matrix is resolved by current file/default behavior (precmat_filename/precmat_basename with fallback to the system matrix). If non-NULL, this matrix is used directly.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetDofmap(HYPREDRV_t hypredrv, int size, const int *dofmap)

Set the degree of freedom (DOF) map for the linear system of a HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
int size = ... // Size of dofmap is set
int *dofmap = ... // dofmap array is set
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetDofmap(hypredrv, size, dofmap));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the DOF map of the linear system is to be set.

  • size – The local size (current rank) of the dofmap array.

  • dofmap – The array containing the mapping codes for the degrees of freedom

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetInterleavedDofmap(HYPREDRV_t hypredrv, int num_local_blocks, int num_dof_types)

Set an interleaved degree of freedom (DOF) map for the linear system of a HYPREDRV object.

Example Usage: 

   HYPREDRV_t *hypredrv;
   int num_dof_types = ... // Number of degree of freedom types
   int num_local_nodes = ... // Number of local (current MPI rank) nodes
   // ... (hypredrv is created, and its components are initialized) ...
   HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetInterleavedDofmap(hypredrv,
num_local_dofs, num_dof_types));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the DOF map of the linear system is to be set.

  • num_local_blocks – The local (owned by the current rank) number of blocks (cells/nodes) containing a set of num_dof_types degrees of freedom.

  • num_dof_types – The number of degree of freedom types.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetContiguousDofmap(HYPREDRV_t hypredrv, int num_local_blocks, int num_dof_types)

Set a contiguous degree of freedom (DOF) map for the linear system of a HYPREDRV object.

Example Usage: 

   HYPREDRV_t *hypredrv;
   int num_dof_types = ... // Number of degree of freedom types
   int num_local_nodes = ... // Number of local (current MPI rank) nodes
   // ... (hypredrv is created, and its components are initialized) ...
   HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemSetContiguousDofmap(hypredrv,
num_local_blocks, num_dof_types));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

  • hypredrv – The HYPREDRV_t object for which the DOF map of the linear system is to be set.

  • num_local_blocks – The local (owned by the current rank) number of blocks (cells/nodes) containing a set of num_dof_types degrees of freedom.

  • num_dof_types – The number of degree of freedom types.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemReadDofmap(HYPREDRV_t hypredrv)

Read the degree of freedom (DOF) map for the linear system of a HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemReadDofmap(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

hypredrv – The HYPREDRV_t object for which the DOF map of the linear system is to be read.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemPrintDofmap(HYPREDRV_t hypredrv, const char *filename)

Print the current degree of freedom (DOF) map of the linear system to file.

Writes the locally owned DOF map entries to a text file. In MPI runs with more than one process, the rank id is appended to the provided filename as a numeric suffix: filename.rank, zero-padded to 5 digits. In single-process runs, the file is written exactly to filename.

File format (ASCII): line 1: number of entries lines : dofmap entries (space-separated), arbitrary line breaks

Parameters:

  • hypredrv – A valid HYPREDRV_t object containing the DOF map.

  • filename – The output filename (prefix). If running with multiple MPI ranks, the function appends “.%05d” with the rank id.

Returns:

0 on success; nonzero error code otherwise.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemPrint(HYPREDRV_t hypredrv)

Print the linear system (matrix and RHS) and the DOF map (if present).

This convenience routine dumps:

  • Matrix A via HYPRE_IJMatrixPrint to an ASCII file (basename + “.out”).

  • RHS b via HYPRE_IJVectorPrint to an ASCII file (basename + “.out”).

  • DOF map via HYPREDRV_LinearSystemPrintDofmap if it exists (basename + “.out”).

Basenames are taken from the input arguments if set; otherwise, defaults are used:

  • Matrix: ls.matrix_basename or “IJ.out.A”

  • RHS: ls.rhs_basename or “IJ.out.b”

  • DOFMap: ls.dofmap_basename or “dofmap”

Parameters:

hypredrv – A valid HYPREDRV_t object with matrix/vector set.

Returns:

0 on success; nonzero error code otherwise.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemSetNearNullSpace(HYPREDRV_t hypredrv, int num_entries, int num_components, const HYPRE_Complex *values)

Set near-nullspace modes for the current linear system (e.g., elastic RBMs).

The input array must contain num_components contiguous blocks (component-major/SoA), each of length num_entries, stored back-to-back (not interleaved). The data is copied into internal storage owned and freed by HYPREDRV; the caller retains ownership of its input buffer and is responsible for freeing it after the call returns.

Typical use for linear elasticity: provide 6 rigid-body modes with num_entries = 3 * num_local_nodes.

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • num_entries – Number of local entries.

  • num_components – Number of components per entry (modes).

  • values – Pointer to contiguous data (length = num_entries * num_components).

Returns:

0 on success; nonzero error code otherwise.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetSolutionValues(HYPREDRV_t hypredrv, HYPRE_Complex **sol_data)

Retrieves the solution values from the linear system of a HYPREDRV object.

This function provides access to the internal pointer where the solution vector of the linear system associated with the given HYPREDRV_t object is stored. It does not copy the solution values; instead, it assigns the internal pointer to the user-provided pointer sol_data.

Example Usage: 

HYPREDRV_t *hypredrv;
HYPRE_Complex *sol_data = NULL;
// Ensure hypredrv is initialized and the system is solved
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetSolutionValues(hypredrv, &sol_data));
// Use sol_data but do not free or modify it.

Parameters:

  • hypredrv – A valid HYPREDRV_t object from which the internal solution pointer is to be retrieved.

  • sol_data – A pointer to a HYPRE_Complex pointer, which will be set to point to the internal solution data array. The user must not free or modify the internal array.

Returns:

Returns an error code, with 0 indicating success. If the hypredrv parameter is invalid (e.g., NULL or uninitialized), an error code is returned, and the error can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetSolutionLength(HYPREDRV_t hypredrv, HYPRE_BigInt *length)

Return the local solution-vector length.

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • length – Output local vector length on this rank.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetSolutionNorm(HYPREDRV_t hypredrv, const char *norm_type, double *norm)

Computes a norm of the solution vector from the linear system.

This function computes the specified norm of the solution vector. Valid norm types are:

  • ”L1” or “l1”: L1 norm (sum of absolute values)

  • ”L2” or “l2”: L2 norm (Euclidean norm, sqrt of sum of squares)

  • ”inf”, “Linf”, or “linf”: Infinity norm (maximum absolute value)

Example Usage: 

   double norm_inf;
   HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetSolutionNorm(hypredrv, "inf",
&norm_inf));

Parameters:

  • hypredrv – A valid HYPREDRV_t object with a solved linear system.

  • norm_type – String specifying the norm type (“L1”, “L2”, or “inf”/”Linf”).

  • norm – Pointer to a double where the computed norm will be stored.

Returns:

Returns an error code, with 0 indicating success. If the norm_type is invalid, the norm will be set to -1.0.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetSolution(HYPREDRV_t hypredrv, HYPRE_Vector *vec)

Retrieve the solution vector from a HYPREDRV object.

Returns the HYPRE_Vector that the linear solver wrote its result into. This is useful for passing the solution directly to another HYPRE routine without copying the underlying data.

Example Usage: 

HYPRE_Vector x = NULL;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetSolution(hypredrv, &x));
// Pass x to another HYPRE routine; do not free it.

Parameters:

  • hypredrv – A valid HYPREDRV_t object with a solved linear system.

  • vec – A pointer to a HYPRE_Vector, set to the internal solution vector on success. The returned pointer is owned by HYPREDRV (unless a user-supplied buffer was injected via HYPREDRV_LinearSystemSetSolution()); the caller must not free it.

Returns:

0 on success; nonzero if hypredrv is invalid or the solution vector has not been allocated yet (i.e., before the first solve or SetSolution call).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetRHSValues(HYPREDRV_t hypredrv, HYPRE_Complex **rhs_data)

Retrieves the right-hand side values from the linear system of a HYPREDRV object.

This function provides access to the internal pointer where the right-hand side vector of the linear system associated with the given HYPREDRV_t object is stored. It does not copy the solution values; instead, it assigns the internal pointer to the user-provided pointer rhs_data.

Example Usage: 

HYPREDRV_t *hypredrv;
HYPRE_Complex *rhs_data = NULL;
// Ensure hypredrv is initialized and the system is solved
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetRHSValues(hypredrv, &rhs_data));
// Use rhs_data but do not free or modify it.

Parameters:

  • hypredrv – A valid HYPREDRV_t object from which the internal solution pointer is to be retrieved.

  • rhs_data – A pointer to a HYPRE_Complex pointer, which will be set to point to the internal right-hand side data array. The user must not free or modify the internal array.

Returns:

Returns an error code, with 0 indicating success. If the obj parameter is invalid (e.g., NULL or uninitialized), an error code is returned, and the error can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetRHS(HYPREDRV_t hypredrv, HYPRE_Vector *vec)

Retrieve the right-hand side vector from a HYPREDRV object.

Returns the HYPRE_Vector for the RHS (vec_b). This is useful for passing the vector directly to another HYPRE routine without copying the underlying data.

Example Usage: 

HYPRE_Vector b = NULL;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetRHS(hypredrv, &b));
// Pass b to another HYPRE routine; do not free it.

Parameters:

  • hypredrv – A valid HYPREDRV_t object with the RHS set.

  • vec – A pointer to a HYPRE_Vector, set to the internal RHS vector on success. The returned pointer is owned by HYPREDRV; the caller must not free it.

Returns:

0 on success; nonzero if hypredrv is invalid or the RHS has not been set yet.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemGetMatrix(HYPREDRV_t hypredrv, HYPRE_Matrix *mat)

Retrieve the system matrix from a HYPREDRV object.

This function provides access to the internal system matrix (mat_A) associated with the given HYPREDRV_t object. The returned pointer is owned by HYPREDRV; the caller must not free it.

Example Usage: 

HYPRE_Matrix A = NULL;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemGetMatrix(hypredrv, &A));
// Use A for inspection but do not free it.

Parameters:

  • hypredrv – A valid HYPREDRV_t object with the matrix set.

  • mat – A pointer to a HYPRE_Matrix, which will be set to the internal system matrix. The user must not free or destroy this object.

Returns:

Returns an error code, with 0 indicating success. Returns a non-zero code if hypredrv is invalid or the matrix has not been set yet.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StateVectorSet(HYPREDRV_t hypredrv, int nstates, HYPRE_IJVector *vecs)

Set state vectors for time-stepping or multi-state applications.

This function initializes the state vector management system, which is useful for time-stepping applications where multiple solution states need to be maintained (e.g., previous time step, current time step). The state vectors are managed internally using a circular indexing scheme.

Example Usage: 

HYPREDRV_t hypredrv;
HYPRE_IJVector vec_s[2];
// ... (create and initialize vec_s[0] and vec_s[1]) ...
HYPREDRV_SAFE_CALL(HYPREDRV_StateVectorSet(hypredrv, 2, vec_s));

Note

The state vectors must be created and initialized by the caller before calling this function. Typically, these are HYPRE_IJVector objects created with the same row range as the linear system.

Note

This function must be called before using other state vector functions such as HYPREDRV_StateVectorGetValues, HYPREDRV_StateVectorCopy, etc.

Parameters:

  • hypredrv – The HYPREDRV_t object for which state vectors are to be set.

  • nstates – The number of state vectors to manage.

  • vecs – An array of HYPRE_Vector objects (HYPRE_IJVector) representing the state vectors. The array must contain at least nstates valid vectors.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StateVectorGetValues(HYPREDRV_t hypredrv, int index, HYPRE_Complex **data_ptr)

Retrieve a pointer to the data array of a state vector.

This function provides direct access to the underlying data array of a state vector, allowing efficient read/write access without copying. The returned pointer points to the local portion of the distributed vector on the current MPI rank.

Example Usage: 

HYPREDRV_t hypredrv;
HYPRE_Complex *u_old = NULL;
// Get pointer to state vector at index 1 (e.g., previous time step)
HYPREDRV_SAFE_CALL(HYPREDRV_StateVectorGetValues(hypredrv, 1, &u_old));
// Now u_old points to the local data array

Note

The returned pointer is valid only as long as the state vector exists and has not been modified by operations that may reallocate the underlying storage.

Note

The data layout is contiguous and follows the DOF ordering of the linear system (e.g., interleaved u, v, p for Navier-Stokes).

Parameters:

  • hypredrv – The HYPREDRV_t object containing the state vectors.

  • index – The logical index of the state vector (0-based, relative to the current state mapping).

  • data_ptr – A pointer to a HYPRE_Complex pointer, which will be set to point to the local data array. The user must not free this pointer, but may read and write to the array.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StateVectorCopy(HYPREDRV_t hypredrv, int index_in, int index_out)

Copy one state vector to another.

This function copies the contents of one state vector to another. It is commonly used in time-stepping applications to initialize the new time step with the solution from the previous time step.

Example Usage: 

HYPREDRV_t hypredrv;
// Copy state 1 (previous time step) to state 0 (current time step)
HYPREDRV_SAFE_CALL(HYPREDRV_StateVectorCopy(hypredrv, 1, 0));

Note

Both state vectors must have been set via HYPREDRV_StateVectorSet and must have compatible sizes (same row ranges).

Parameters:

  • hypredrv – The HYPREDRV_t object containing the state vectors.

  • index_in – The logical index of the source state vector (0-based).

  • index_out – The logical index of the destination state vector (0-based).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StateVectorUpdateAll(HYPREDRV_t hypredrv)

Cycle through state vector indices (advance state mapping).

This function advances the internal state mapping by one position in a circular manner. After calling this function, the logical indices (0, 1, …) now refer to different physical state vectors. This is useful for time-stepping applications where state vectors are reused in a circular buffer pattern.

Example Usage: 

HYPREDRV_t hypredrv;
// At end of time step, cycle states so next iteration uses updated mapping
HYPREDRV_SAFE_CALL(HYPREDRV_StateVectorUpdateAll(hypredrv));

Note

This function modifies the internal state mapping but does not copy any data. It is typically called at the end of a time step to prepare for the next iteration.

Note

After calling this function, the logical index 0 will refer to what was previously index 1, index 1 will refer to what was previously index 2, etc., wrapping around for the last index.

Parameters:

hypredrv – The HYPREDRV_t object containing the state vectors.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StateVectorApplyCorrection(HYPREDRV_t hypredrv, int state_idx)

Apply the linear solver correction to a state vector.

This function adds the solution increment from the linear solver (stored in vec_x) to the state vector at logical index state_idx. This implements the Newton update: U^{k+1} = U^k + ΔU, where ΔU is the solution from the linear system J ΔU = -R.

Pass state_idx = 0 to apply the correction to the current (most recent) state, which is the typical usage after HYPREDRV_StateVectorUpdateAll() has cycled the indices so that index 0 refers to the new current state.

Example Usage: 

HYPREDRV_t hypredrv;
// ... (assemble linear system, solve) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverApply(hypredrv));
HYPREDRV_SAFE_CALL(HYPREDRV_StateVectorApplyCorrection(hypredrv, 0));

Note

This function should be called after HYPREDRV_LinearSolverApply has completed successfully.

Note

The operation performed is: state[state_idx] += vec_x (in-place update).

Parameters:

  • hypredrv – The HYPREDRV_t object containing the state vectors and the linear solver solution (vec_x).

  • state_idx – Zero-based logical index of the state vector to update. Must be in [0, nstates).

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PreconCreate(HYPREDRV_t hypredrv)

Create a preconditioner for the HYPREDRV object based on the specified method.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_PreconCreate(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the preconditioning method and other related settings are properly set in the input arguments.

Parameters:

hypredrv – The HYPREDRV_t object for which the preconditioner is to be created.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverCreate(HYPREDRV_t hypredrv)

Create a linear solver for the HYPREDRV object based on the specified method.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverCreate(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the solver method and other related settings are properly set in the input arguments.

Parameters:

hypredrv – The HYPREDRV_t object for which the linear solver is to be created.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PreconSetup(HYPREDRV_t hypredrv)

Set up the preconditioner for the HYPREDRV object.

Sets up only the preconditioner, without setting up the enclosing linear solver. Use this when applying the preconditioner standalone via HYPREDRV_PreconApply().

Example Usage: 

HYPREDRV_t hypredrv;
// ... (hypredrv is created, matrix is set) ...
HYPREDRV_SAFE_CALL(HYPREDRV_PreconCreate(hypredrv));
HYPREDRV_SAFE_CALL(HYPREDRV_PreconSetup(hypredrv));
HYPREDRV_SAFE_CALL(HYPREDRV_PreconApply(hypredrv, vec_b, vec_x));

Note

HYPREDRV_LinearSolverSetup() sets up the preconditioner internally as part of the combined solver setup. A prior call to this function is not required before calling HYPREDRV_LinearSolverSetup().

Parameters:

hypredrv – The HYPREDRV_t object for which the preconditioner is to be set up.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverSetup(HYPREDRV_t hypredrv)

Set up the linear solver for the HYPREDRV object.

Configures the linear solver using the current solver and preconditioner methods, matrix, RHS vector, and solution vector. This function sets up the preconditioner internally - a prior call to HYPREDRV_PreconSetup() is not required for the normal solver workflow.

Example Usage: 

HYPREDRV_t hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverSetup(hypredrv));

Note

To use the preconditioner standalone (e.g., via HYPREDRV_PreconApply()), call HYPREDRV_PreconSetup() explicitly instead.

Parameters:

hypredrv – The HYPREDRV_t object for which the linear solver is to be set up.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverApply(HYPREDRV_t hypredrv)

Apply the linear solver to solve the linear system for the HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverApply(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the solver method, solver, matrix, RHS vector, and solution vector are properly set in the input arguments.

Parameters:

hypredrv – The HYPREDRV_t object for which the linear solver is to be applied.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PreconApply(HYPREDRV_t hypredrv, HYPRE_Vector vec_b, HYPRE_Vector vec_x)

Apply the preconditioner associated with a HYPREDRV_t object to an input vector.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_PreconApply(hypredrv, vec_b, vec_x));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the preconditioner method, solver, matrix, RHS vector, and solution vector are properly set in the input arguments.

Parameters:

  • hypredrv – The HYPREDRV_t object defining the preconditioner to be applied.

  • vec_b – The HYPRE_Vector object defining the input vector.

  • vec_x – The HYPRE_Vector object defining the output vector.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_PreconDestroy(HYPREDRV_t hypredrv)

Destroy the preconditioner associated with the HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_PreconDestroy(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the preconditioner method and the preconditioner itself are properly set in the HYPREDRV_t object.

Parameters:

hypredrv – The HYPREDRV_t object whose preconditioner is to be destroyed.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverDestroy(HYPREDRV_t hypredrv)

Destroy the linear solver associated with the HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverDestroy(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error. The function assumes that the linear solver method and the linear solver object itself are properly set in the HYPREDRV_t object.

Note

This function also destroys the associated preconditioner. There is no need to call HYPREDRV_PreconDestroy separately before or after this call.

Parameters:

hypredrv – The HYPREDRV_t object whose linear solver is to be destroyed.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StatsPrint(HYPREDRV_t hypredrv)

Print the statistics associated with the HYPREDRV object.

This function is responsible for printing the statistics collected during the operations performed by the HYPREDRV object.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_StatsPrint(hypredrv));

Note

It’s the caller’s responsibility to ensure that the hypredrv parameter is a valid pointer to an initialized HYPREDRV_t object. Passing a NULL or uninitialized object will result in an error.

Parameters:

hypredrv – The HYPREDRV_t object whose statistics are to be printed.

Returns:

Returns an error code with 0 indicating success. Any non-zero value indicates a failure, and the error code can be further described using HYPREDRV_ErrorCodeDescribe(error_code).

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_AnnotateBegin(HYPREDRV_t hypredrv, const char *name, int id)

Begin annotation of a code region for timing and Caliper instrumentation.

This function marks the beginning of a code region for performance measurement. It should be paired with HYPREDRV_AnnotateEnd to mark the end of the region.

Example Usage: 

HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateBegin(hypredrv, "system", -1));
// ... code to measure ...
HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateEnd(hypredrv, "system", -1));

Note

This function is Caliper-only: it does not record entries in the stats context and thus does not feed HYPREDRV_StatsLevelGetEntry(). Use HYPREDRV_AnnotateLevelBegin/End if you need both Caliper and stats recording.

Note

When Caliper is enabled (via HYPREDRV_ENABLE_CALIPER), this function also creates Caliper regions that can be captured by Caliper profiling tools.

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should receive the annotation.

  • name – The name of the region to annotate. Available names include: “system”, “matrix”, “rhs”, “dofmap”, “prec”, “solve”, “reset_x0”, “initialize”, “finalize”, or custom names.

  • id – An integer identifier for the region. If id >= 0, the region name will be formatted as “name-id” (e.g., “system-1”). If id < 0, the name is used as-is (e.g., “system”).

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_AnnotateEnd(HYPREDRV_t hypredrv, const char *name, int id)

End annotation of a code region for timing and Caliper instrumentation.

This function marks the end of a code region for performance measurement. It should be paired with HYPREDRV_AnnotateBegin to mark the beginning of the region.

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should receive the annotation end event.

  • name – The name of the region to annotate. Must match the name used in the corresponding HYPREDRV_AnnotateBegin call.

  • id – An integer identifier for the region. Must match the id used in the corresponding HYPREDRV_AnnotateBegin call.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_AnnotateLevelBegin(HYPREDRV_t hypredrv, int level, const char *name, int id)

Begin hierarchical annotation of a code region with a specified level.

This function marks the beginning of a hierarchical code region for performance measurement. Hierarchical annotations allow tracking nested regions such as time steps (level 0), non-linear iterations (level 1), etc.

Example Usage: 

// Time step loop (level 0)
for (int t = 0; t < num_steps; t++)
{
   HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateLevelBegin(hypredrv, 0, "timestep", t));

   // Non-linear iteration loop (level 1)
   for (int n = 0; n < max_nl_iters; n++)
   {
      HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateLevelBegin(hypredrv, 1, "newton", n));
      // ... solve linear system ...
      HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateLevelEnd(hypredrv, 1, "newton", n));
   }

   HYPREDRV_SAFE_CALL(HYPREDRV_AnnotateLevelEnd(hypredrv, 0, "timestep", t));
}

Note

Each level can only have one active annotation at a time. The annotation must be ended with HYPREDRV_AnnotateLevelEnd using the same level, name, and id.

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should receive the annotation.

  • level – The hierarchical level (0-9). Lower levels represent outer loops, higher levels represent inner loops. For example:

    • Level 0: Time steps

    • Level 1: Non-linear iterations

  • name – The name of the region to annotate (e.g., “timestep”, “newton”).

  • id – An integer identifier for the region. If id >= 0, the region name will be formatted as “name-id” (e.g., “timestep-0”, “newton-1”). If id < 0, the name is used as-is.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_AnnotateLevelEnd(HYPREDRV_t hypredrv, int level, const char *name, int id)

End hierarchical annotation of a code region with a specified level.

This function marks the end of a hierarchical code region. The level, name, and id must match the corresponding HYPREDRV_AnnotateLevelBegin call.

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • level – The hierarchical level (0-9), must match the Begin call.

  • name – The name of the region, must match the Begin call.

  • id – An integer identifier for the region, must match the Begin call.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSystemComputeEigenspectrum(HYPREDRV_t hypredrv)

Compute the full eigenspectrum of the current linear system matrix or the preconditioned linear system.

Example Usage: 

HYPREDRV_t *hypredrv;
// ... (hypredrv is created, and its components are initialized) ...
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSystemComputeEigenspectrum(hypredrv));

Note

When hypredrive is built without -DHYPREDRV_ENABLE_EIGSPEC=ON, this function is a silent no-op: it prints a one-time warning to stderr on rank 0 and returns success. It is therefore safe to leave the call unconditionally in application code.

Note

When built with -DHYPREDRV_ENABLE_EIGSPEC=ON, this function operates on a single MPI rank and writes eigenvalues (and optionally eigenvectors) to files in the current directory as configured via the YAML input under linear_system.eigspec.

Parameters:

hypredrv – The HYPREDRV_t object for which the eigenspectrum is to be computed.

Returns:

Returns an error code with 0 indicating success

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverGetNumIter(HYPREDRV_t hypredrv, int *iters)

Get the iteration count from the last linear solve.

Example Usage: 

int iters;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverGetNumIter(hypredrv, &iters));

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • iters – Pointer to store the iteration count.

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverGetSetupTime(HYPREDRV_t hypredrv, double *seconds)

Get the preconditioner setup time from the last linear solve.

Example Usage: 

double setup_time;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverGetSetupTime(hypredrv, &setup_time));

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • seconds – Pointer to store the setup time in the currently configured stats units (seconds by default, milliseconds when general.use_millisec: on).

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_LinearSolverGetSolveTime(HYPREDRV_t hypredrv, double *seconds)

Get the solver apply time from the last linear solve.

Example Usage: 

double solve_time;
HYPREDRV_SAFE_CALL(HYPREDRV_LinearSolverGetSolveTime(hypredrv, &solve_time));

Parameters:

  • hypredrv – The HYPREDRV_t object.

  • seconds – Pointer to store the solve time in the currently configured stats units (seconds by default, milliseconds when general.use_millisec: on).

Returns:

Returns an error code with 0 indicating success.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StatsLevelGetCount(HYPREDRV_t hypredrv, int level, int *count)

Get the number of entries recorded at a specific level.

Returns the count of entries recorded via level annotations (HYPREDRV_AnnotateLevelBegin/End with the specified level).

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should be queried.

  • level – The annotation level (0 to STATS_MAX_LEVELS-1).

  • count – Pointer to store the number of entries recorded.

Returns:

Returns an error code with 0 indicating success. Returns a non-zero error code if level is out of range or no stats context is active.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StatsLevelGetEntry(HYPREDRV_t hypredrv, int level, int index, int *entry_id, int *num_solves, int *linear_iters, double *setup_time, double *solve_time)

Get statistics entry by level and index.

Retrieves statistics for a specific entry at the given level. Statistics are computed on-demand from the solve index range.

Note

Any pointer parameter can be NULL to skip retrieving that value.

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should be queried.

  • level – The annotation level (0 to STATS_MAX_LEVELS-1).

  • index – Zero-based index of the entry (0 to count-1).

  • entry_id – Pointer to store the entry ID (1-based).

  • num_solves – Pointer to store the number of solves in this entry.

  • linear_iters – Pointer to store the total linear iterations.

  • setup_time – Pointer to store the total setup time (seconds).

  • solve_time – Pointer to store the total solve time (seconds).

Returns:

Returns an error code with 0 indicating success. Returns a non-zero error code if the level or index is invalid, or if no stats context is active.

HYPREDRV_EXPORT_SYMBOL uint32_t HYPREDRV_StatsLevelPrint(HYPREDRV_t hypredrv, int level)

Print statistics summary for a specific level.

Prints a table of all recorded entries at the specified level including number of solves, linear iterations, setup time, and solve time per entry, followed by totals and averages.

Parameters:

  • hypredrv – The HYPREDRV_t object whose stats context should be printed.

  • level – The annotation level to print (0 to STATS_MAX_LEVELS-1).

Returns:

Returns an error code with 0 indicating success.