KmlMgSolverApply

Perform back substitution to obtain the solution.

Interface Definition

C interface:

KmlMgStatus KmlMgSolverApply(KmlMgSolverH solver, KmlMgMatrixH B, KmlMgMatrixH X, KmlMgApplyOptions* options);

Parameters

Parameter	Type	Description	Input/Output
solver	KmlMgSolverH	Solver handle created by KmlMgSolverCreate	Input/Output
B	KmlMgMatrixH	Matrix handle created by the KmlMgMatrixCreate function, indicating the RHS vector.	Input
X	KmlMgMatrixH	Matrix handle created by the KmlMgMatrixCreate function, indicating the solution space. The initial input value can be used as the initial value for the first iteration.	Input/Output
options	KmlMgApplyOptions&	Back substitution configuration information	Input

Return Value

Return Value	Type	Description
KML_MG_OK	int	The execution is successful.
KML_MG_ERR_INVALID_PARAM	int	The parameter is invalid.
KML_MG_ERR_UNSUPPORTED	int	Unsupported feature.
KML_MG_ERR_NO_MEMORY	int	Memory allocation failed.
KML_MG_ERR_EXCEEDS_LIMIT	int	The parameter is out of the valid range.
KML_MG_ERR_INCOMPATIBLE	int	Incompatible version.
KML_MG_ERR_NO_REQUIRED_FIELD	int	Required field not set.
KML_MG_ERR_UNKNOWN_TYPE	int	Unknown type.
KML_MG_ERR_THIRD_PART	int	Internal third-party call error.
KML_MG_ERR_INCONSISTENT	int	Inconsistent information transferred.
KML_MG_ERR_UNEXPECTED_CALL_ORDER	int	Unexpected call order.
KML_MG_ERR_MATRIX_VALUE_IS_NULL	int	The matrix value is null.
KML_MG_ERR_NO_RESOURCE	int	Resources not ready.

Structure Description

KmlMgApplyOptions

Field	Type	Description
fieldMask	uint64_t	Mask that determines to which fields the configuration is applied. If a bit is set to 1, its corresponding field uses a specified value. If a bit is set to 0, its corresponding field uses the default value. See the individual field description for configurable mask bits.
useZeroGuess	bool	Indicates whether to start iteration with X set to 0 as the initial value. If the value is true, the initial value of the iteration is 0. If the value is false, the initial value is the value of the parameter X. Mask bit: KML_MG_APPLY_OPTIONS_USE_ZERO_GUESS
toleranceType	KmlMgToleranceType	Threshold type for iterative convergence. The values are as follows: KML_MG_TOLERANCE_ABS KML_MG_TOLERANCE_REL Mask bit: KML_MG_APPLY_OPTIONS_TOLERANCE_TYPE
tolerance	double	Threshold for iterative convergence. Iteration stops once the error falls below this threshold. Mask bit: KML_MG_APPLY_OPTIONS_TOLERANCE
maxIteration	int64_t	Maximum number of iterations. If the number of iterations reaches the threshold, the iteration stops. Mask bit: KML_MG_APPLY_OPTIONS_MAX_ITERATION
restartStep	int64_t	Number of iterations before restart. This parameter is valid only when KmlMgSolverOptions.ksp is set to KML_MG_SOLVER_GCR or KML_MG_SOLVER_GMRES. Mask bit: KML_MG_APPLY_OPTIONS_RESTART_STEP
solveResi	bool	Indicates whether to reformulate an equation as a residual equation for accuracy optimization. If the initial value X0 is provided and this parameter is set to true, the equation A * X = B is reformulated as A * (X-X0) = B − A * X0. This parameter is valid only when X0 is very close to the true solution and KmlMgSolverOptions.ksp is set to KML_MG_SOLVER_G. Mask bit: KML_MG_APPLY_OPTIONS_SOLVE_RESI

Dependencies

#include "mg.h"

For details about the sample code, see Examples.

Parent topic: HMG