# Linear solvers¶

Warning

Some algorithms may require the installation of GEMSEO with all its features and some others may depend on plugins.

Note

All the features of the wrapped algorithm libraries may not be exposed through GEMSEO.

## BICG¶

Linear solver implemented in the SciPy library.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.bicg.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.

## BICGSTAB¶

Linear solver implemented in the SciPy library.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.bicgstab.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.

## DEFAULT¶

This starts by LGMRES, but if it fails, switches to GMRES, then direct method super LU factorization.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.splu.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• inner_m : int, optional

By default it is set to 30.

• outer_k : int, optional

The number of vectors to carry between inner GMRES iterations.

By default it is set to 3.

• outer_v : list[tuple] | None, optional

The data used to augment the Krylov subspace.

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.

## GMRES¶

Linear solver implemented in the SciPy library.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.gmres.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.

## LGMRES¶

Linear solver implemented in the SciPy library.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.lgmres.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• inner_m : int, optional

By default it is set to 30.

• outer_k : int, optional

The number of vectors to carry between inner GMRES iterations.

By default it is set to 3.

• outer_v : list[tuple] | None, optional

The data used to augment the Krylov subspace.

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.

## PETSC_KSP¶

Note

The plugin gemseo_petsc is required.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float, optional

The absolute convergence tolerance of the (possibly preconditioned) residual norm.

By default it is set to 1e-50.

• dtol : float, optional

The divergence tolerance, e.g. the amount the (possibly preconditioned) residual norm can increase.

By default it is set to 100000.0.

• ksp_pre_processor : bool | None, optional

A callback function that is called with (KSP problem, options dict) as arguments before calling ksp.solve(). It allows the user to obtain an advanced configuration that is not supported by the current wrapper. If None, do not perform any call.

By default it is set to None.

• monitor_residuals : bool, optional

Whether to store the residuals during convergence. WARNING: as said in Petsc documentation, “the routine is slow and should be used only for testing or convergence studies, not for timing.”

By default it is set to False.

• options_cmd : dict[str, Any] | None, optional

The options to pass to the PETSc KSP solver. If None, use the default options.

By default it is set to None.

• preconditioner_type : str, optional

The type of the precondtioner, see https://www.mcs.anl.gov/petsc/petsc4py-current/docs/apiref/petsc4py.PETSc.PC.Type-class.html_ # noqa: B950

By default it is set to ilu.

• set_from_options : bool, optional

Whether the options are set from sys.argv, a classical Petsc configuration mode.

By default it is set to False.

• solver_type : str, optional

The KSP solver type. See https://petsc.org/release/docs/manualpages/KSP/KSPType.html#KSPType_

By default it is set to gmres.

• tol : float, optional

The relative convergence tolerance, relative decrease in the (possibly preconditioned) residual norm.

By default it is set to 1e-05.

• view_config : bool, optional

Whether to call ksp.view() to view the configuration of the solver before run.

By default it is set to False.

## QMR¶

Linear solver implemented in the SciPy library.

More details about the algorithm and its options on https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.qmr.html.

Required parameters
• max_iter : int

The maximum number of iterations.

Optional parameters
• atol : float | None, optional

The absolute tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to None.

• preconditioner : ndarray | LinearOperator | None, optional

The preconditionner, approximation of RHS^-1. If None, no preconditioner is used.

By default it is set to None.

• save_when_fail : bool, optional

Whether to save the linear system to the disk when the solver failed to converge.

By default it is set to False.

• store_residuals : bool, optional

Whether to store the residuals convergence history.

By default it is set to False.

• tol : float, optional

The relative tolerance for convergence, norm(RHS.dot(sol)) <= max(tol*norm(LHS), atol).

By default it is set to 1e-12.

• use_ilu_precond : bool, optional

Whether to use superLU to compute an incomplete LU factorization as preconditioner. inner_m int: The number of inner GMRES iterations per outer iteration.

By default it is set to True.

• x0 : ndarray | None, optional

The initial guess for the solution. M{sparse matrix, dense matrix, LinearOperator}. If None, solvers usually start from the null vector.

By default it is set to None.