ALP User Documentation  0.8.preview
Algebraic Programming User Documentation
Typedefs | Enumerations | Functions

This exposes a transition path API to the linear system solvers implemented in ALP. More...

Typedefs

typedef void * sparse_cg_handle_t
 A solver handle for the Conjugate Gradient algorithm.
 
typedef int(* sparse_cg_preconditioner_dxx_t) (double *const, const double *const, void *const)
 A user-defined preconditioner function type for CG solver that employ double-precision floating-point nonzero values. More...
 
typedef int(* sparse_cg_preconditioner_sxx_t) (float *const, const float *const, void *const)
 A user-defined preconditioner function type for CG solver that employ single-precision floating-point nonzero values. More...
 

Enumerations

enum  sparse_err_t {
  NO_ERROR, NULL_ARGUMENT, ILLEGAL_ARGUMENT, OUT_OF_MEMORY,
  FAILED, UNKNOWN
}
 The various error codes sparse solver library functions may return. More...
 

Functions

sparse_err_t sparse_cg_destroy_dii (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_destroy_diz (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_destroy_dzz (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_destroy_sii (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_destroy_siz (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_destroy_szz (sparse_cg_handle_t handle)
 Destroys a valid CG solver handle. More...
 
sparse_err_t sparse_cg_get_iter_count_dii (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_iter_count_diz (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_iter_count_dzz (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_iter_count_sii (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_iter_count_siz (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_iter_count_szz (const sparse_cg_handle_t handle, size_t *const iters)
 Retrieves the number of iterations the given CG solver has employed. More...
 
sparse_err_t sparse_cg_get_preconditioner_dii (const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_preconditioner_diz (const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_preconditioner_dzz (const sparse_cg_handle_t handle, sparse_cg_preconditioner_dxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_preconditioner_sii (const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_preconditioner_siz (const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_preconditioner_szz (const sparse_cg_handle_t handle, sparse_cg_preconditioner_sxx_t *const preconditioner, void **const data)
 Retrieves the currently active preconditioner. More...
 
sparse_err_t sparse_cg_get_residual_dii (const sparse_cg_handle_t handle, double *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_residual_diz (const sparse_cg_handle_t handle, double *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_residual_dzz (const sparse_cg_handle_t handle, double *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_residual_sii (const sparse_cg_handle_t handle, float *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_residual_siz (const sparse_cg_handle_t handle, float *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_residual_szz (const sparse_cg_handle_t handle, float *const tol)
 Retrieves the residual the given CG solve has achieved. More...
 
sparse_err_t sparse_cg_get_size_dii (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_size_diz (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_size_dzz (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_size_sii (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_size_siz (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_size_szz (sparse_cg_handle_t const handle, size_t *const size)
 Retrieves the system size for a given CG solver handle. More...
 
sparse_err_t sparse_cg_get_tolerance_dii (const sparse_cg_handle_t handle, double *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_get_tolerance_diz (const sparse_cg_handle_t handle, double *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_get_tolerance_dzz (const sparse_cg_handle_t handle, double *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_get_tolerance_sii (const sparse_cg_handle_t handle, float *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_get_tolerance_siz (const sparse_cg_handle_t handle, float *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_get_tolerance_szz (const sparse_cg_handle_t handle, float *const tol)
 Gets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_init_dii (sparse_cg_handle_t *const handle, const size_t n, const double *const a, const int *const ja, const int *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_init_diz (sparse_cg_handle_t *const handle, const size_t n, const double *const a, const int *const ja, const size_t *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_init_dzz (sparse_cg_handle_t *const handle, const size_t n, const double *const a, const size_t *const ja, const size_t *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_init_sii (sparse_cg_handle_t *const handle, const size_t n, const float *const a, const int *const ja, const int *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_init_siz (sparse_cg_handle_t *const handle, const size_t n, const float *const a, const int *const ja, const size_t *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_init_szz (sparse_cg_handle_t *const handle, const size_t n, const float *const a, const size_t *const ja, const size_t *const ia)
 Initialises a sparse_cg_handle_t object. More...
 
sparse_err_t sparse_cg_set_max_iter_count_dii (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_max_iter_count_diz (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_max_iter_count_dzz (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_max_iter_count_sii (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_max_iter_count_siz (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_max_iter_count_szz (sparse_cg_handle_t handle, const size_t max_iters)
 Sets the current maximum number of iterations for the given CG solver. More...
 
sparse_err_t sparse_cg_set_preconditioner_dii (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_preconditioner_diz (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_preconditioner_dzz (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_dxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_preconditioner_sii (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_preconditioner_siz (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_preconditioner_szz (const sparse_cg_handle_t handle, const sparse_cg_preconditioner_sxx_t preconditioner, void *const data)
 Sets a new preconditioner to apply during a next solve call. More...
 
sparse_err_t sparse_cg_set_tolerance_dii (sparse_cg_handle_t handle, const double tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_set_tolerance_diz (sparse_cg_handle_t handle, const double tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_set_tolerance_dzz (sparse_cg_handle_t handle, const double tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_set_tolerance_sii (sparse_cg_handle_t handle, const float tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_set_tolerance_siz (sparse_cg_handle_t handle, const float tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_set_tolerance_szz (sparse_cg_handle_t handle, const float tol)
 Sets the current accepted relative tolerance for the given CG solver. More...
 
sparse_err_t sparse_cg_solve_dii (sparse_cg_handle_t handle, double *const x, const double *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 
sparse_err_t sparse_cg_solve_diz (sparse_cg_handle_t handle, double *const x, const double *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 
sparse_err_t sparse_cg_solve_dzz (sparse_cg_handle_t handle, double *const x, const double *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 
sparse_err_t sparse_cg_solve_sii (sparse_cg_handle_t handle, float *const x, const float *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 
sparse_err_t sparse_cg_solve_siz (sparse_cg_handle_t handle, float *const x, const float *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 
sparse_err_t sparse_cg_solve_szz (sparse_cg_handle_t handle, float *const x, const float *const b)
 Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x. More...
 

Detailed Description

This exposes a transition path API to the linear system solvers implemented in ALP.

The primary benefit compared to simply using a SpBLAS or SparseBLAS interface, is that solvers herein defined can be compiled using the nonblocking backend, thus automatically optimising across (Sparse)BLAS primitives. This is an experimental feature designed to evaluate exactly this advantage.

The C-style interface here defined expects the industry-standard Compressed Row Storage (CRS) for matrices, also known as CSR. It employs a systematic postfix to the functions it defines. For example, the basic functions of the Conjugate Gradient solver are:

The postfix system and the sparse matrix storage format

First explaining the postfix system, each of the above x characters may be d or s, indicating the precision used during the solve: double- or single-precision, respectively.

Each of the y characters may be z or i, indicating the integer type used during the solve: a size_t or a regular int, respectively.

The first y character indicates the integer type of the CRS column index array, which maintains for each nonzero entry on which column it resides. For really large dimension matrices, a size_t integer type, which usually defaults to 64-bit unsigned integers, may be required.

The second y character indicates the integer type of the row offset array of the CRS. The \( i \)-th contiguous pair \( (a, b] \) of this array indicates where in the value and column arrays the \( i \)-th row of the matrix is encoded– the start position \( a \) is inclusive whereas the end position \( b \) is exclusive. The row offset array is of size \( m + 1 \), where \( m \) is the number of rows in the matrix. Hence the last entry of the offset array is the total number of nonzeroes the matrix contains. The data type of the offset array must be size_t when matrices contain many nonzeroes.

Note
Usually, if the offset array must be of type size_t, then the column index array must also be of type size_t. Certainly for matrices used with (linear) solvers, after all, the number of nonzeroes is a multiple of the number of matrix rows.
Implemented solvers

Currently, the following ALP solvers are exposed:

  1. the sparse Conjugate Gradient (CG) solver, implemented at grb::algorithms::conjugate_gradient.
  2. its preconditioned variant (PCG), implemented at grb::algorithms::preconditioned_conjugate_gradient. The preconditioner may be supplied as an arbitrary user-defined function; while this is maximally flexible, it also requires the user to employ parallelisation and other optimisations for the preconditioner, manually.

If you require any other solver, please feel free to submit a feature request or to contact the maintainer(s).

Warning
The solvers here defined, and the transition path functionalities as a whole, are currently in a prototype stage. While the underlying ALP algorithms are automatically smoke tested and robust, the transition path libraries are presently tested externally and often manually.

Typedef Documentation

◆ sparse_cg_preconditioner_dxx_t

typedef int(* sparse_cg_preconditioner_dxx_t) (double *const, const double *const, void *const)

A user-defined preconditioner function type for CG solver that employ double-precision floating-point nonzero values.

I.e. and more precisely, a preconditioner function type for CG solver handles of types dii, diz, and dzz.

A preconditioner is assumed to be a plain C function pointer, where

  1. the function returns an int error code (where zero will be interpreted as success);
  2. the first argument is where the result of applying the preconditioner will be stored. It is a raw vector pointer, i.e., double *;
  3. the second argument contains the data on which the preconditioner action should be computed. It is a raw const vector pointer, i.e., const double *;
  4. the third argument contains a pointer to any preconditioner data it may require. It is a raw void pointer, meaning, although usually not necessary nor recommended, the preconditioner data may be stateful.

The function signature must match exactly this specification.

◆ sparse_cg_preconditioner_sxx_t

typedef int(* sparse_cg_preconditioner_sxx_t) (float *const, const float *const, void *const)

A user-defined preconditioner function type for CG solver that employ single-precision floating-point nonzero values.

I.e. and more precisely, a preconditioner function type for CG solver handles of types sii, siz, and szz.

A preconditioner is assumed to be a plain C function pointer, where

  1. the function returns an int error code (where zero will be interpreted as success);
  2. the first argument is where the result of applying the preconditioner will be stored. It is a raw vector pointer, i.e., float *;
  3. the second argument contains the data on which the preconditioner action should be computed. It is a raw const vector pointer, i.e., const float*;
  4. the third argument contains a pointer to any preconditioner data it may require. It is a raw void pointer, meaning, although usually not necessary nor recommended, the preconditioner data may be stateful.

The function signature must match exactly this specification.

Enumeration Type Documentation

◆ sparse_err_t

The various error codes sparse solver library functions may return.

Enumerator
NO_ERROR 

The call has completed successfully.

NULL_ARGUMENT 

Illegal NULL pointer provided as argument.

ILLEGAL_ARGUMENT 

Illegal argument provided.

OUT_OF_MEMORY 

Out of memory error detected during call.

FAILED 

The algorithm has failed achieving its intended result.

For example, an iterative solver did not converge.

UNKNOWN 

An unknown error has been encountered.

The state of the underlying solver library has become undefined. When encoutering this error code, the caller is encouraged to exit gracefully or (at least) to make no further calls into this library.

Function Documentation

◆ sparse_cg_destroy_dii()

sparse_err_t sparse_cg_destroy_dii ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

This variant is for CG solver instances of type dii.

See also
sparse_cg_destroy_sii for full documentation.
Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-dii solvers.

◆ sparse_cg_destroy_diz()

sparse_err_t sparse_cg_destroy_diz ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

This variant is for CG solver instances of type diz.

See also
sparse_cg_destroy_sii for full documentation.
Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-diz solvers.

◆ sparse_cg_destroy_dzz()

sparse_err_t sparse_cg_destroy_dzz ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_destroy_sii for full documentation.
Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-dzz solvers.

◆ sparse_cg_destroy_sii()

sparse_err_t sparse_cg_destroy_sii ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

Parameters
[in,out]handleA handle to a valid CG solver object.
Returns
NULL_ARGUMENT If handle is NULL. When returning this error code, the call to this function shall have no other effects.
NO_ERROR If the given handle was successfully destroyed. The handle shall henceforth be invalid.

This variant is for CG solver instances of type sii.

Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-sii solvers.

◆ sparse_cg_destroy_siz()

sparse_err_t sparse_cg_destroy_siz ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

This variant is for CG solver instances of type siz.

See also
sparse_cg_destroy_sii for full documentation.
Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-siz solvers.

◆ sparse_cg_destroy_szz()

sparse_err_t sparse_cg_destroy_szz ( sparse_cg_handle_t  handle)

Destroys a valid CG solver handle.

This variant is for CG solver instances of type szz.

See also
sparse_cg_destroy_sii for full documentation.
Note
After a call to this function, the newly-invalid handle may be re-initialised, even for initialising non-szz solvers.

◆ sparse_cg_get_iter_count_dii()

sparse_err_t sparse_cg_get_iter_count_dii ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

This variant is for CG solver instances of type dii.

See also
sparse_cg_get_iter_count_sii for full documentation.
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dii On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_iter_count_diz()

sparse_err_t sparse_cg_get_iter_count_diz ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

This variant is for CG solver instances of type diz.

See also
sparse_cg_get_iter_count_sii for full documentation.
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_diz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_iter_count_dzz()

sparse_err_t sparse_cg_get_iter_count_dzz ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_get_iter_count_sii for full documentation.
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dzz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_iter_count_sii()

sparse_err_t sparse_cg_get_iter_count_sii ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

Parameters
[in]handleA handle to a valid CG solver object.
[out]itersWhere to store the requested number of iterations.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If iters is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_sii On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_iter_count_siz()

sparse_err_t sparse_cg_get_iter_count_siz ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

This variant is for CG solver instances of type siz.

See also
sparse_cg_get_iter_count_sii for full documentation.
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_siz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_iter_count_szz()

sparse_err_t sparse_cg_get_iter_count_szz ( const sparse_cg_handle_t  handle,
size_t *const  iters 
)

Retrieves the number of iterations the given CG solver has employed.

This variant is for CG solver instances of type szz.

See also
sparse_cg_get_iter_count_sii for full documentation.
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_szz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write zero into iters.

◆ sparse_cg_get_preconditioner_dii()

sparse_err_t sparse_cg_get_preconditioner_dii ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_dxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type dii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_preconditioner_diz()

sparse_err_t sparse_cg_get_preconditioner_diz ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_dxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type diz.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_preconditioner_dzz()

sparse_err_t sparse_cg_get_preconditioner_dzz ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_dxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type dzz.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_preconditioner_sii()

sparse_err_t sparse_cg_get_preconditioner_sii ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_sxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type sii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_preconditioner_siz()

sparse_err_t sparse_cg_get_preconditioner_siz ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_sxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type siz.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_preconditioner_szz()

sparse_err_t sparse_cg_get_preconditioner_szz ( const sparse_cg_handle_t  handle,
sparse_cg_preconditioner_sxx_t *const  preconditioner,
void **const  data 
)

Retrieves the currently active preconditioner.

Parameters
[in,out]handleA handle to a valid CG solver object.
[out]preconditionerWhere to store the function pointer that is the current preconditioner.
[out]dataWhere to store the pointer to any data that the currently active preconditioner requires.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If preconditioner is NULL. If this error code is returned, the call to this function shall have no other effects.
NULL_ARGUMENT If data is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type szz.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_residual_dii()

sparse_err_t sparse_cg_get_residual_dii ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Retrieves the residual the given CG solve has achieved.

This variant is for CG solver instances of type dii.

See also
sparse_cg_get_residual_sii for full documentation.
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dii On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_residual_diz()

sparse_err_t sparse_cg_get_residual_diz ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Retrieves the residual the given CG solve has achieved.

This variant is for CG solver instances of type diz.

See also
sparse_cg_get_residual_sii for full documentation.
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_diz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_residual_dzz()

sparse_err_t sparse_cg_get_residual_dzz ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Retrieves the residual the given CG solve has achieved.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_get_residual_sii for full documentation.
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dzz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_residual_sii()

sparse_err_t sparse_cg_get_residual_sii ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Retrieves the residual the given CG solve has achieved.

Parameters
[in]handleA handle to a valid CG solver object.
[out]tolWhere to store the requested residual.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If tol is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_sii On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_residual_siz()

sparse_err_t sparse_cg_get_residual_siz ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Retrieves the residual the given CG solve has achieved.

This variant is for CG solver instances of type siz.

See also
sparse_cg_get_residual_sii for full documentation.
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_siz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_residual_szz()

sparse_err_t sparse_cg_get_residual_szz ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Retrieves the residual the given CG solve has achieved.

This variant is for CG solver instances of type szz.

See also
sparse_cg_get_residual_sii for full documentation.
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_szz On how to execute a CG solve on a valid handle.
Note
Only after successful execution of a solver instance will a call to this function be useful; a valid instance that was freshly constructed will otherwise always write infinity into tol.

◆ sparse_cg_get_size_dii()

sparse_err_t sparse_cg_get_size_dii ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type dii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_size_diz()

sparse_err_t sparse_cg_get_size_diz ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type diz.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_size_dzz()

sparse_err_t sparse_cg_get_size_dzz ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type dzz.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_size_sii()

sparse_err_t sparse_cg_get_size_sii ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_size_siz()

sparse_err_t sparse_cg_get_size_siz ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type siz.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_size_szz()

sparse_err_t sparse_cg_get_size_szz ( sparse_cg_handle_t const  handle,
size_t *const  size 
)

Retrieves the system size for a given CG solver handle.

Parameters
[in]handleA handle to a valid CG solver object.
[out]sizeWhere to store the system size.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If size is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solve instances of type szz.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_dii()

sparse_err_t sparse_cg_get_tolerance_dii ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type dii.

See also
sparse_cg_get_tolerance_sii for full documentation.
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_diz()

sparse_err_t sparse_cg_get_tolerance_diz ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type diz.

See also
sparse_cg_get_tolerance_sii for full documentation.
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_dzz()

sparse_err_t sparse_cg_get_tolerance_dzz ( const sparse_cg_handle_t  handle,
double *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_get_tolerance_sii for full documentation.
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_sii()

sparse_err_t sparse_cg_get_tolerance_sii ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

Parameters
[in]handleA handle to a valid CG solver object.
[out]tolWhere to store the currently effective tolerance.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NULL_ARGUMENT If tol is NULL. If this error code is returned, the call to this function shall have no other effects.
NO_ERROR Otherwise.

This variant is for CG solver instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_siz()

sparse_err_t sparse_cg_get_tolerance_siz ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type siz.

See also
sparse_cg_get_tolerance_sii for full documentation.
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_get_tolerance_szz()

sparse_err_t sparse_cg_get_tolerance_szz ( const sparse_cg_handle_t  handle,
float *const  tol 
)

Gets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type szz.

See also
sparse_cg_get_tolerance_sii for full documentation.
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_init_dii()

sparse_err_t sparse_cg_init_dii ( sparse_cg_handle_t *const  handle,
const size_t  n,
const double *const  a,
const int *const  ja,
const int *const  ia 
)

Initialises a sparse_cg_handle_t object.

This variant is for double-precision floating point nonzeroes and integer ja and ia arrays, as also indicated by the dii postfix.

See also
sparse_cg_init_sii for full documentation.

◆ sparse_cg_init_diz()

sparse_err_t sparse_cg_init_diz ( sparse_cg_handle_t *const  handle,
const size_t  n,
const double *const  a,
const int *const  ja,
const size_t *const  ia 
)

Initialises a sparse_cg_handle_t object.

This variant is for double-precision floating point nonzeroes, size_t-valued ja, and integer-valued ia, as also indicated by the diz postfix.

See also
sparse_cg_init_sii for full documentation.

◆ sparse_cg_init_dzz()

sparse_err_t sparse_cg_init_dzz ( sparse_cg_handle_t *const  handle,
const size_t  n,
const double *const  a,
const size_t *const  ja,
const size_t *const  ia 
)

Initialises a sparse_cg_handle_t object.

This variant is for double-precision floating point nonzeroes and size_t-valued ja and ia, as also indicated by the dzz postfix.

See also
sparse_cg_init_sii for full documentation.

◆ sparse_cg_init_sii()

sparse_err_t sparse_cg_init_sii ( sparse_cg_handle_t *const  handle,
const size_t  n,
const float *const  a,
const int *const  ja,
const int *const  ia 
)

Initialises a sparse_cg_handle_t object.

Parameters
[out]handleAn uninitialised handler to a CG solver.

Initialisation proceeds according to a given system matrix given in Compressed Row Storage (CRS), also commonly known as the Compressed Sparse Rows (CSR) format.

Parameters
[in]nThe size of the system matrix.
[in]aThe nonzero values of the system matrix.
[in]jaThe column indices of the nonzeroes of the system matrix.
[in]iaThe row offset array of the system matrix.

This variant is for single-precision floating point nonzeroes and integer ja and ia arrays, as also indicated by the sii postfix.

Returns
ILLEGAL_ARGUMENT If n equals zero.
NULL_ARGUMENT If handle is NULL.
NULL_ARGUMENT If any of a, ja, or ia are NULL.
OUT_OF_MEMORY In case of encountering out-of-memory conditions.

On returning any of the above errors, the call to this function shall not have any other effects (than having returned the error code).

Note
This implies in particular that any initially given invalid and non-NULL handle may be reused for future, potentially successful, calls to this (or any other) initialisation function.
Returns
NO_ERROR If initialisation of the handle proceeded successfully. Only in this case shall handle henceforth be a valid handle.

◆ sparse_cg_init_siz()

sparse_err_t sparse_cg_init_siz ( sparse_cg_handle_t *const  handle,
const size_t  n,
const float *const  a,
const int *const  ja,
const size_t *const  ia 
)

Initialises a sparse_cg_handle_t object.

This variant is for single-precision floating point nonzeroes, size_t-valued ja, and integer-valued ia, as also indicated by the siz postfix.

See also
sparse_cg_init_sii for full documentation.

◆ sparse_cg_init_szz()

sparse_err_t sparse_cg_init_szz ( sparse_cg_handle_t *const  handle,
const size_t  n,
const float *const  a,
const size_t *const  ja,
const size_t *const  ia 
)

Initialises a sparse_cg_handle_t object.

This variant is for single-precision floating point nonzeroes and size_t-valued ja and ia, as also indicated by the szz postfix.

See also
sparse_cg_init_sii for full documentation.

◆ sparse_cg_set_max_iter_count_dii()

sparse_err_t sparse_cg_set_max_iter_count_dii ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

This variant is for CG solver instances of type dii.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_max_iter_count_diz()

sparse_err_t sparse_cg_set_max_iter_count_diz ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

This variant is for CG solver instances of type diz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_max_iter_count_dzz()

sparse_err_t sparse_cg_set_max_iter_count_dzz ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_max_iter_count_sii()

sparse_err_t sparse_cg_set_max_iter_count_sii ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]max_itersThe given maximum number of iterations.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_max_iter_count_siz()

sparse_err_t sparse_cg_set_max_iter_count_siz ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

This variant is for CG solver instances of type siz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_max_iter_count_szz()

sparse_err_t sparse_cg_set_max_iter_count_szz ( sparse_cg_handle_t  handle,
const size_t  max_iters 
)

Sets the current maximum number of iterations for the given CG solver.

This variant is for CG solver instances of type szz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_preconditioner_dii()

sparse_err_t sparse_cg_set_preconditioner_dii ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_dxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type dii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dii On how to call the resulting preconditioned solver.

◆ sparse_cg_set_preconditioner_diz()

sparse_err_t sparse_cg_set_preconditioner_diz ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_dxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type dii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_diz On how to call the resulting preconditioned solver.

◆ sparse_cg_set_preconditioner_dzz()

sparse_err_t sparse_cg_set_preconditioner_dzz ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_dxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type dii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_dzz On how to call the resulting preconditioned solver.

◆ sparse_cg_set_preconditioner_sii()

sparse_err_t sparse_cg_set_preconditioner_sii ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_sxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type sii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_sii On how to call the resulting preconditioned solver.

◆ sparse_cg_set_preconditioner_siz()

sparse_err_t sparse_cg_set_preconditioner_siz ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_sxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type sii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_siz On how to call the resulting preconditioned solver.

◆ sparse_cg_set_preconditioner_szz()

sparse_err_t sparse_cg_set_preconditioner_szz ( const sparse_cg_handle_t  handle,
const sparse_cg_preconditioner_sxx_t  preconditioner,
void *const  data 
)

Sets a new preconditioner to apply during a next solve call.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]preconditionerThe preconditioner as a C function pointer.
See also
sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.
Parameters
[in]dataPointer to any data the preconditioner may require.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver handles of type sii.

Warning
If handle did not refer to a valid CG solver instance of a matching type, the effect of calling this function is undefined(!)
See also
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.
sparse_cg_solve_szz On how to call the resulting preconditioned solver.

◆ sparse_cg_set_tolerance_dii()

sparse_err_t sparse_cg_set_tolerance_dii ( sparse_cg_handle_t  handle,
const double  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type dii.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_tolerance_diz()

sparse_err_t sparse_cg_set_tolerance_diz ( sparse_cg_handle_t  handle,
const double  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type diz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_tolerance_dzz()

sparse_err_t sparse_cg_set_tolerance_dzz ( sparse_cg_handle_t  handle,
const double  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_tolerance_sii()

sparse_err_t sparse_cg_set_tolerance_sii ( sparse_cg_handle_t  handle,
const float  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

Parameters
[in,out]handleA handle to a valid CG solver object.
[in]tolThe given tolerance.
Returns
NULL_ARGUMENT If handle is NULL. If this error is returned, the call to this function shall not have any other effects.
NO_ERROR Otherwise.

This variant is for CG solver instances of type sii.

Warning
If handle did not refer to a valid CG solver instance, the effect of calling this function is undefined(!).
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_tolerance_siz()

sparse_err_t sparse_cg_set_tolerance_siz ( sparse_cg_handle_t  handle,
const float  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type siz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_set_tolerance_szz()

sparse_err_t sparse_cg_set_tolerance_szz ( sparse_cg_handle_t  handle,
const float  tol 
)

Sets the current accepted relative tolerance for the given CG solver.

This variant is for CG solver instances of type szz.

See also
sparse_cg_set_tolerance_sii for full documentation.
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_dii()

sparse_err_t sparse_cg_solve_dii ( sparse_cg_handle_t  handle,
double *const  x,
const double *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

This variant is for CG solver instances of type dii.

See also
sparse_cg_solve_sii for full documentation.
sparse_cg_get_residual_dii to retrieve the last-known residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
The contents of x are only modified by this solve call if it returns NO_ERROR or FAILED. The contents of x will be guaranteed unmodified from the initial guess if the function returns NULL_ARGUMENT. The contents of x will be undefined if the function returns UNKNOWN.
See also
sparse_cg_init_dii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_diz()

sparse_err_t sparse_cg_solve_diz ( sparse_cg_handle_t  handle,
double *const  x,
const double *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

This variant is for CG solver instances of type diz.

See also
sparse_cg_solve_sii for full documentation.
sparse_cg_get_residual_diz to retrieve the last-known residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
The contents of x are only modified by this solve call if it returns NO_ERROR or FAILED. The contents of x will be guaranteed unmodified from the initial guess if the function returns NULL_ARGUMENT. The contents of x will be undefined if the function returns UNKNOWN.
See also
sparse_cg_init_diz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_dzz()

sparse_err_t sparse_cg_solve_dzz ( sparse_cg_handle_t  handle,
double *const  x,
const double *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

This variant is for CG solver instances of type dzz.

See also
sparse_cg_solve_sii for full documentation.
sparse_cg_get_residual_dzz to retrieve the last-known residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
The contents of x are only modified by this solve call if it returns NO_ERROR or FAILED. The contents of x will be guaranteed unmodified from the initial guess if the function returns NULL_ARGUMENT. The contents of x will be undefined if the function returns UNKNOWN.
See also
sparse_cg_init_dzz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_sii()

sparse_err_t sparse_cg_solve_sii ( sparse_cg_handle_t  handle,
float *const  x,
const float *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

Parameters
[in]handleA handle to a valid CG solver object, which embeds the linear system matrix on which the solve is executed.
[in,out]xOn input: an initial guess to the solution. On output: the last-obtained iterative refinement of the initial guess.
[in]bThe right-hand side of the linear system to solve.

The solve continues until convergence, until the maximum number of iterations has been achieved, or until an error is encountered.

Calling this function with an invalid handle will incur undefined behaviour.

Returns
NULL_ARGUMENT If one or more of handle, x, or b is NULL. In this case, the call to this function shall not have any other effects.
FAILED If the solver did not converge to the given relative tolerance within the given number of maximum iterations. In this case, x contains the last iteratively refined guess to the solution.
NO_ERROR If an acceptable solution has been found.
See also
sparse_cg_get_residual_sii to retrieve the residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
Returns
UNKNOWN If the solver failed due to any other error. In this case, the state of the solver library and the contents of x shall be undefined and the user is urged to gracefully exit the application at the next available opportunity, and in any case to not make any further calls into the solver library.
See also
sparse_cg_init_sii On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_siz()

sparse_err_t sparse_cg_solve_siz ( sparse_cg_handle_t  handle,
float *const  x,
const float *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

This variant is for CG solver instances of type siz.

See also
sparse_cg_solve_sii for full documentation.
sparse_cg_get_residual_siz to retrieve the last-known residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
The contents of x are only modified by this solve call if it returns NO_ERROR or FAILED. The contents of x will be guaranteed unmodified from the initial guess if the function returns NULL_ARGUMENT. The contents of x will be undefined if the function returns UNKNOWN.
See also
sparse_cg_init_siz On how to obtain a valid CG solver instance for use with this function.

◆ sparse_cg_solve_szz()

sparse_err_t sparse_cg_solve_szz ( sparse_cg_handle_t  handle,
float *const  x,
const float *const  b 
)

Executes a solve using a given CG solver handle, a given right-hand side b, and an initial guess x.

This variant is for CG solver instances of type szz.

See also
sparse_cg_solve_sii for full documentation.
sparse_cg_get_residual_szz to retrieve the last-known residual of x.
Note
Retrieving the residual may be of interest both on convergence (NO_ERROR) and when convergence was not obtained (FAILED).
The contents of x are only modified by this solve call if it returns NO_ERROR or FAILED. The contents of x will be guaranteed unmodified from the initial guess if the function returns NULL_ARGUMENT. The contents of x will be undefined if the function returns UNKNOWN.
See also
sparse_cg_init_szz On how to obtain a valid CG solver instance for use with this function.