cashocs.nonlinear_solvers#

Custom solvers for nonlinear equations.

This module has custom solvers for nonlinear PDEs, including a damped Newton method and a Picard iteration for coupled problems.

Functions

`linear_solve`(linear_form, u, bcs[, ...])	Solves a linear problem.
`newton_solve`(nonlinear_form, u, bcs[, ...])	Solves a nonlinear problem with Newton's method.
`picard_iteration`(form_list, u_list, bcs_list)	Solves a system of coupled PDEs via a Picard iteration.
`snes_solve`(nonlinear_form, u, bcs[, ...])	Solve a nonlinear PDE problem with PETSc SNES.

cashocs.nonlinear_solvers.linear_solve(linear_form, u, bcs, ksp_options=None, preconditioner_form=None, A_tensor=None, b_tensor=None, linear_solver=None)[source]#

Solves a linear problem.

Parameters:

linear_form (ufl.Form) – The linear variational form of the problem, i.e., linear_form == 0
u (fenics.Function) – The function to be solved for
bcs (Union[fenics.DirichletBC, List[fenics.DirichletBC]]) – The boundary conditions for the problem
ksp_options (Optional[_typing.KspOption]) – The options for the PETSc KSP solver, optional. Default is None, where the linear solver MUMPS is used
A_tensor (Optional[fenics.PETScMatrix]) – A fenics.PETScMatrix for storing the left-hand side of the linear sub-problem.
b_tensor (Optional[fenics.PETScVector]) – A fenics.PETScVector for storing the right-hand side of the linear sub-problem.
linear_solver (Optional[_utils.linalg.LinearSolver]) – The linear solver used to solve the (discretized) linear problem.
preconditioner_form (ufl.Form)

Returns:

The computed solution, this overwrites the input function u.

Return type:

fenics.Function

cashocs.nonlinear_solvers.newton_solve(nonlinear_form, u, bcs, derivative=None, shift=None, rtol=1e-10, atol=1e-10, max_iter=50, convergence_type='combined', norm_type='l2', damped=True, inexact=True, verbose=True, ksp_options=None, A_tensor=None, b_tensor=None, is_linear=False, preconditioner_form=None, linear_solver=None)[source]#

Solves a nonlinear problem with Newton's method.

Parameters:

nonlinear_form (ufl.Form) – The variational form of the nonlinear problem to be solved by Newton’s method.
u (fenics.Function) – The sought solution / initial guess. It is not assumed that the initial guess satisfies the Dirichlet boundary conditions, they are applied automatically. The method overwrites / updates this Function.
bcs (Union[fenics.DirichletBC, List[fenics.DirichletBC]]) – A list of DirichletBCs for the nonlinear variational problem.
derivative (Optional[ufl.Form]) – The Jacobian of nonlinear_form, used for the Newton method. Default is None, and in this case the Jacobian is computed automatically with AD.
shift (Optional[ufl.Form]) – A shift term, if the right-hand side of the nonlinear problem is not zero, but shift.
rtol (float) – Relative tolerance of the solver if convergence_type is either 'combined' or 'rel' (default is rtol = 1e-10).
atol (float) – Absolute tolerance of the solver if convergence_type is either 'combined' or 'abs' (default is atol = 1e-10).
max_iter (int) – Maximum number of iterations carried out by the method (default is max_iter = 50).
convergence_type (Literal['combined', 'rel', 'abs']) – Determines the type of stopping criterion that is used.
norm_type (Literal['l2', 'linf']) – Determines which norm is used in the stopping criterion.
damped (bool) – If True, then a damping strategy is used. If False, the classical Newton-Raphson iteration (without damping) is used (default is True).
inexact (bool) – If True, an inexact Newton's method is used. Default is True.
verbose (bool) – If True, prints status of the iteration to the console (default is True).
ksp_options (Optional[_typing.KspOption]) – The list of options for the linear solver.
A_tensor (Optional[fenics.PETScMatrix]) – A fenics.PETScMatrix for storing the left-hand side of the linear sub-problem.
b_tensor (Optional[fenics.PETScVector]) – A fenics.PETScVector for storing the right-hand side of the linear sub-problem.
is_linear (bool) – A boolean flag, which indicates whether the problem is actually linear.
preconditioner_form (Optional[ufl.Form]) – A UFL form which defines the preconditioner matrix.
linear_solver (Optional[_utils.linalg.LinearSolver]) – The linear solver (KSP) which is used to solve the linear systems arising from the discretized PDE.

Returns:

The solution of the nonlinear variational problem, if converged. This overwrites the input function u.

Return type:

fenics.Function

Examples

Consider the problem

\[\begin{split}\begin{alignedat}{2} - \Delta u + u^3 &= 1 \quad &&\text{ in } \Omega=(0,1)^2 \\ u &= 0 \quad &&\text{ on } \Gamma. \end{alignedat}\end{split}\]

This is solved with the code

from fenics import *
import cashocs

mesh, _, boundaries, dx, _, _ = cashocs.regular_mesh(25)
V = FunctionSpace(mesh, 'CG', 1)

u = Function(function_space)
v = TestFunction(function_space)
F = inner(grad(u), grad(v))*dx + pow(u,3)*v*dx - Constant(1)*v*dx
bcs = cashocs.create_dirichlet_bcs(V, Constant(0.0), boundaries, [1,2,3,4])
cashocs.newton_solve(F, u, bcs)

cashocs.nonlinear_solvers.picard_iteration(form_list, u_list, bcs_list, max_iter=50, rtol=1e-10, atol=1e-10, verbose=True, inner_max_iter=25, ksp_options=None, A_tensors=None, b_tensors=None, preconditioner_forms=None, newton_linearizations=None)[source]#

Solves a system of coupled PDEs via a Picard iteration.

Parameters:

form_list (Union[List[ufl.form], ufl.Form]) – List of the coupled PDEs.
u_list (Union[List[fenics.Function], fenics.Function]) – List of the state variables (to be solved for).
bcs_list (Union[List[fenics.DirichletBC], List[List[fenics.DirichletBC]]]) – List of boundary conditions for the PDEs.
max_iter (int) – The maximum number of iterations for the Picard iteration.
rtol (float) – The relative tolerance for the Picard iteration, default is 1e-10.
atol (float) – The absolute tolerance for the Picard iteration, default is 1e-10.
verbose (bool) – Boolean flag, if True, output is written to stdout, default is True.
inner_max_iter (int) – Maximum number of iterations for the inner Newton solver; default is 25.
ksp_options (Optional[List[_typing.KspOption]]) – List of options for the KSP objects.
A_tensors (Optional[List[fenics.PETScMatrix]]) – List of matrices for the right-hand sides of the inner (linearized) equations.
b_tensors (Optional[List[fenics.PETScVector]]) – List of vectors for the left-hand sides of the inner (linearized) equations.
preconditioner_forms (Optional[Union[List[ufl.Form], ufl.Form]]) – The list of forms for the preconditioner. The default is None, so that the preconditioner matrix is the same as the system matrix.
newton_linearizations (Optional[List[ufl.Form]]) – A list of UFL forms describing which (alternative) linearizations should be used for the (nonlinear) equations when solving them (with Newton’s method). The default is None, so that the Jacobian of the supplied state forms is used.

Return type:

None

cashocs.nonlinear_solvers.snes_solve(nonlinear_form, u, bcs, derivative=None, petsc_options=None, shift=None, rtol=None, atol=None, max_iter=None, A_tensor=None, b_tensor=None, preconditioner_form=None)[source]#

Solve a nonlinear PDE problem with PETSc SNES.

An overview over possible PETSc command line options for the SNES can be found at https://petsc.org/release/manualpages/SNES/.

Parameters:

nonlinear_form (ufl.Form) – The variational form of the nonlinear problem to be solved by Newton’s method.
u (fenics.Function) – The sought solution / initial guess. It is not assumed that the initial guess satisfies the Dirichlet boundary conditions, they are applied automatically. The method overwrites / updates this Function.
bcs (Union[fenics.DirichletBC, List[fenics.DirichletBC]]) – A list of DirichletBCs for the nonlinear variational problem.
derivative (Optional[ufl.Form]) – The Jacobian of nonlinear_form, used for the Newton method. Default is None, and in this case the Jacobian is computed automatically with AD.
petsc_options (Optional[_typing.KspOption]) – The options for PETSc SNES object.
shift (Optional[ufl.Form]) – A shift term, if the right-hand side of the nonlinear problem is not zero, but shift.
rtol (Optional[float]) – Relative tolerance of the solver (default is rtol = 1e-10).
atol (Optional[float]) – Absolute tolerance of the solver (default is atol = 1e-10).
max_iter (Optional[int]) – Maximum number of iterations carried out by the method (default is max_iter = 50).
A_tensor (Optional[fenics.PETScMatrix]) – A fenics.PETScMatrix for storing the left-hand side of the linear sub-problem.
b_tensor (Optional[fenics.PETScVector]) – A fenics.PETScVector for storing the right-hand side of the linear sub-problem.
preconditioner_form (Optional[ufl.Form]) – A UFL form which defines the preconditioner matrix.

Returns:

The solution in form of a FEniCS Function.

Return type:

fenics.Function

Modules

`linear_solver`	Linear solver for linear PDEs.
`newton_solver`	Newton solver for nonlinear PDEs.
`picard_solver`	A Picard iteration for coupled PDEs.
`snes`	Interface for the PETSc SNES solver for nonlinear equations.