topoptlab.linear_solvers module

topoptlab.linear_solvers.cg(A: sparray, b: ndarray, x0: None | ndarray = None, rtol: None | float = 1e-05, atol: None | float = 0.0, maxiter: int = 100000, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Conjugate gradient solver for Ax=b, for a symmetric, positive-definite matrix A without any preconditioning. Iterate until convergence criteria met or the maximum number of iterations is exceeded.

This is purely for teaching and benchmarking reasons and should never be used for any production runs.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• x0 (np.ndarray) – initial guess for solution.

• rtol (None or float) – relative convergence tolerance.

• atol (None or float) – absolute convergence tolerance.

• maxiter (int) – maximum number of iterations.

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.

topoptlab.linear_solvers.gauss_seidel(A: sparray, b: ndarray, x0: None | ndarray = None, atol: float = 1e-08, max_iter: int = 1000, L: None | sparray = None, U: None | sparray = None, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Gauss-Seidel solver for Ax = b. We re-write each iteration as with the lower and upper triangular matrices L,U

L x^i = omega b - U x^(i-1)

to avoid using for loops. Iterate until the residual r=b-Ax fulfills the convergence criteria or the maximum number of iterations is exceeded.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• x0 (np.ndarray) – initial guess for solution.

• atol (float) – abs. convergence tolerance.

• maxiter (int) – maximum number of iterations.

• L (scipy.sparse.sparray or None) – lower triangular matrix of A (with diagonal).

• U (scipy.sparse.sparray or None) – upper triangular matrix of A (without diagonal).

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.

topoptlab.linear_solvers.max_res(r: ndarray, atol: float, **kwargs: Any) → bool

Check if maximum residual smaller than tolerance. This is a very (!) strict convergence criterion so should only be used for testing or similar things.

Parameters:

• r (np.ndarray) – residual.

• atol (float) – absolute tolerance.

Returns:

converged – if True, max. residual smaller than tolerance.

Return type:

bool

topoptlab.linear_solvers.modified_richardson(A: sparray, b: ndarray, x0: None | ndarray = None, omega: float = 0.1, atol: float = 1e-08, max_iter: int = 1000, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Modified Richardson iterative solver for Ax=b. Iterate until the residual r=b-Ax fulfills r.max()<tol or the maximum number of iterations is exceeded.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• x0 (np.ndarray) – initial guess for solution.

• omega (float) – damping factor usually between 0/1.

• atol (float) – abs. convergence tolerance.

• maxiter (int) – maximum number of iterations.

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.

topoptlab.linear_solvers.pcg(A: sparray, b: ndarray, P: sparray | LinearOperator, x0: None | ndarray = None, rtol: None | float = 1e-05, atol: None | float = 0.0, maxiter: int = 100000, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Preconditioned conjugate gradient solver for Ax=b, for a symmetric, positive-definite matrix A. Iterate until convergence criteria met or the maximum number of iterations is exceeded.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• P (scipy.sparse.sparray or scipy.sparse.LinearOperator) – preconditioner that is called at each cg iteration.

• x0 (np.ndarray) – initial guess for solution.

• rtol (None or float) – relative convergence tolerance.

• atol (None or float) – absolute convergence tolerance.

• maxiter (int) – maximum number of iterations.

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.

topoptlab.linear_solvers.res_norm(r: ndarray, atol: float, **kwargs: Any) → bool

Check if maximum residual smaller than tolerance.

Parameters:

• r (np.ndarray) – residual.

• tol (float) – tolerance.

Returns:

converged – if True, max. residual smaller than tolerance.

Return type:

bool

topoptlab.linear_solvers.smoothed_jacobi(A: sparray, b: ndarray, x0: None | ndarray = None, omega: float = 0.67, atol: float = 1e-08, max_iter: int = 1000, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Smoothed Jacobi iterative solver for Ax = b. Iterate until the residual r=b-Ax fulfills r.max()<tol or the maximum number of iterations is exceeded.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• x0 (np.ndarray) – initial guess for solution.

• omega (float) – damping factor usually between 0/1.

• atol (float) – convergence tolerance.

• maxiter (int) – maximum number of iterations.

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.

topoptlab.linear_solvers.successive_overrelaxation(A: sparray, b: ndarray, x0: None | ndarray = None, omega: float = 0.5, atol: float = 1e-08, max_iter: int = 1000, D: None | sparray = None, A_u: None | sparray = None, A_l: None | sparray = None, conv_criterium: Callable = <function res_norm>, conv_args: Dict = {}, logger: EmptyLogger | SimpleLogger = <topoptlab.log_utils.EmptyLogger object>, **kwargs: Any) → Tuple[ndarray, int]

Successive over-relaxation (SRO) solver for Ax=b. We rewrite

(D+omega L) x^i = omega b - [ omega U + (omega - 1)D ]x^(i-1)

to

A_l x^i = omega b - A_u x^i-1

to avoid repeated addition etc. in the sparse matrices. Iterate until the residual r=b-Ax fulfills r.max()<tol or the maximum number of iterations is exceeded.

Parameters:

• A (scipy.sparse.sparray) – matrix of linear system.

• b (np.ndarray) – right hand side of linear system.

• x0 (np.ndarray) – initial guess for solution.

• omega (float) – damping factor usually between 0/1.

• atol (float) – abs. convergence tolerance.

• maxiter (int) – maximum number of iterations.

• D (scipy.sparse.sparray or None) – diagonal of A.

• M_u (scipy.sparse.sparray or None) – helper matrix (see equation above).

• M_l (scipy.sparse.sparray or None) – helper matrix (see equation above).

• conv_criterium (callable) – convergence criterium.

• conv_args (dict) – additional arguments for convergence criterium.

• logger (BaseLogger) – logger object to log performance.

Returns:

• x (np.ndarray) – final result for solution.

• info (int) – 0: converged, info>0: exited due to reaching maximum number of iterations.