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:

sparse_cg_init_xyy,
sparse_cg_solve_xyy, and
sparse_cg_destroy_xyy.

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:

the sparse Conjugate Gradient (CG) solver, implemented at grb::algorithms::conjugate_gradient.
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

the function returns an int error code (where zero will be interpreted as success);
the first argument is where the result of applying the preconditioner will be stored. It is a raw vector pointer, i.e., double *;
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 *;
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

the function returns an int error code (where zero will be interpreted as success);
the first argument is where the result of applying the preconditioner will be stored. It is a raw vector pointer, i.e., float *;
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*;
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

enum 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] handle A 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]	handle	A handle to a valid CG solver object.
[out]	iters	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	preconditioner	Where to store the function pointer that is the current preconditioner.
[out]	data	Where 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]	handle	A handle to a valid CG solver object.
[out]	tol	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	size	Where 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]	handle	A handle to a valid CG solver object.
[out]	tol	Where 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] handle An 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]	n	The size of the system matrix.
[in]	a	The nonzero values of the system matrix.
[in]	ja	The column indices of the nonzeroes of the system matrix.
[in]	ia	The 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]	handle	A handle to a valid CG solver object.
[in]	max_iters	The 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_dxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	preconditioner	The preconditioner as a C function pointer.

See also: sparse_cg_preconditioner_sxx_t On the required signature for preconditioner.

Parameters

[in] data Pointer 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]	handle	A handle to a valid CG solver object.
[in]	tol	The 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]	handle	A handle to a valid CG solver object, which embeds the linear system matrix on which the solve is executed.
[in,out]	x	On input: an initial guess to the solution. On output: the last-obtained iterative refinement of the initial guess.
[in]	b	The 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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ sparse_cg_preconditioner_dxx_t

◆ sparse_cg_preconditioner_sxx_t

Enumeration Type Documentation

◆ sparse_err_t

Function Documentation

◆ sparse_cg_destroy_dii()

◆ sparse_cg_destroy_diz()

◆ sparse_cg_destroy_dzz()

◆ sparse_cg_destroy_sii()

◆ sparse_cg_destroy_siz()

◆ sparse_cg_destroy_szz()

◆ sparse_cg_get_iter_count_dii()

◆ sparse_cg_get_iter_count_diz()

◆ sparse_cg_get_iter_count_dzz()

◆ sparse_cg_get_iter_count_sii()

◆ sparse_cg_get_iter_count_siz()

◆ sparse_cg_get_iter_count_szz()

◆ sparse_cg_get_preconditioner_dii()

◆ sparse_cg_get_preconditioner_diz()

◆ sparse_cg_get_preconditioner_dzz()

◆ sparse_cg_get_preconditioner_sii()

◆ sparse_cg_get_preconditioner_siz()

◆ sparse_cg_get_preconditioner_szz()

◆ sparse_cg_get_residual_dii()

◆ sparse_cg_get_residual_diz()

◆ sparse_cg_get_residual_dzz()

◆ sparse_cg_get_residual_sii()

◆ sparse_cg_get_residual_siz()

◆ sparse_cg_get_residual_szz()

◆ sparse_cg_get_size_dii()

◆ sparse_cg_get_size_diz()

◆ sparse_cg_get_size_dzz()

◆ sparse_cg_get_size_sii()

◆ sparse_cg_get_size_siz()

◆ sparse_cg_get_size_szz()

◆ sparse_cg_get_tolerance_dii()

◆ sparse_cg_get_tolerance_diz()

◆ sparse_cg_get_tolerance_dzz()

◆ sparse_cg_get_tolerance_sii()

◆ sparse_cg_get_tolerance_siz()

◆ sparse_cg_get_tolerance_szz()

◆ sparse_cg_init_dii()

◆ sparse_cg_init_diz()

◆ sparse_cg_init_dzz()

◆ sparse_cg_init_sii()

◆ sparse_cg_init_siz()

◆ sparse_cg_init_szz()

◆ sparse_cg_set_max_iter_count_dii()

◆ sparse_cg_set_max_iter_count_diz()

◆ sparse_cg_set_max_iter_count_dzz()

◆ sparse_cg_set_max_iter_count_sii()

◆ sparse_cg_set_max_iter_count_siz()

◆ sparse_cg_set_max_iter_count_szz()

◆ sparse_cg_set_preconditioner_dii()

◆ sparse_cg_set_preconditioner_diz()

◆ sparse_cg_set_preconditioner_dzz()

◆ sparse_cg_set_preconditioner_sii()

◆ sparse_cg_set_preconditioner_siz()

◆ sparse_cg_set_preconditioner_szz()

◆ sparse_cg_set_tolerance_dii()

◆ sparse_cg_set_tolerance_diz()

◆ sparse_cg_set_tolerance_dzz()

◆ sparse_cg_set_tolerance_sii()

◆ sparse_cg_set_tolerance_siz()

◆ sparse_cg_set_tolerance_szz()

◆ sparse_cg_solve_dii()

◆ sparse_cg_solve_diz()

◆ sparse_cg_solve_dzz()

◆ sparse_cg_solve_sii()

◆ sparse_cg_solve_siz()

◆ sparse_cg_solve_szz()