SNESSolver Class Reference

Solver for nonlinear systems \(F(x) = 0\) using PETSc SNES. More...

#include <SNESSolver.h>

Public Member Functions
	SNESSolver (MPI_Comm comm)
	Create a nonlinear solver.
	SNESSolver (SNES snes, bool inc_ref_count)
	Create a solver wrapper of a PETSc SNES object.
	SNESSolver (const SNESSolver &solver)=delete
	SNESSolver (SNESSolver &&solver) noexcept
	~SNESSolver ()
	Destructor.
SNESSolver &	operator= (const SNESSolver &solver)=delete
SNESSolver &	operator= (SNESSolver &&solver) noexcept
	Move assignment.
void	set_F (std::function< void(const Vec x, Vec b)> F, Vec b_layout)
	Set the function for computing the residual \(F(x)\), and the vector that defines its layout.
void	set_J (std::function< void(const Vec x, Mat Jmat, Mat Pmat)> J, Mat J_layout, Mat P_layout=nullptr)
	Set the function for computing the Jacobian \(J := dF/dx\), and the matrices that define its layout.
void	set_update (std::function< void(PetscInt step)> update)
	Set a function called before each nonlinear iteration, e.g. to update a time- or step-dependent term.
SNESConvergedReason	solve (Vec x)
	Solve \(F(x) = 0\).
void	set_options_prefix (std::string_view options_prefix)
	Set the prefix used by PETSc when searching the PETSc options database.
std::string	get_options_prefix () const
	Get the prefix used by PETSc when searching the PETSc options database.
void	set_from_options () const
	Set options from the PETSc options database.
SNES	snes () const
	Get the wrapped PETSc SNES object, e.g. to configure the line search or the Krylov solver used for each iteration.

Detailed Description

Solver for nonlinear systems \(F(x) = 0\) using PETSc SNES.

Adapts C++ callables to the SNES callback interface and handles memory management. Configuration of the solve is left to the user, via the options database or the SNES object returned by snes().

An exception thrown by a callback aborts the solve and is re-thrown by solve().

Example:

nls::petsc::SNESSolver solver(mesh.comm());
solver.set_F([&](const Vec x, Vec b) { assemble_residual(x, b); }, b);
solver.set_J([&](const Vec x, Mat A, Mat) { assemble_jacobian(x, A); },
              A);
solver.set_options_prefix("my_problem_");
solver.set_from_options();
solver.solve(x);

Constructor & Destructor Documentation

SNESSolver() [1/3]

SNESSolver ( MPI_Comm comm )

explicit

Create a nonlinear solver.

Parameters

[in]

comm

MPI communicator for the solver.

SNESSolver() [2/3]

SNESSolver	(	SNES	snes,
		bool	inc_ref_count )

Create a solver wrapper of a PETSc SNES object.

Note

The callbacks registered on snes hold a pointer to the solver, which is not reference counted. Using snes once the solver has been destroyed is undefined.

The solver claims the SNES application context (via SNESSetApplicationContext) to recover itself in callbacks that take no context argument, e.g. the update hook. Any application context already set on snes is overwritten.

Parameters

[in]	snes	PETSc SNES object. It should already have been created.
[in]	inc_ref_count	Increment the reference count on snes if true, so that it outlives a caller that destroys their own reference.

SNESSolver() [3/3]

SNESSolver ( SNESSolver && solver )

noexcept

Move constructor

Note

The SNES callback context is a pointer to the owning solver, so moving re-registers the callbacks.

Member Function Documentation

get_options_prefix()

std::string get_options_prefix

(

)

const

Get the prefix used by PETSc when searching the PETSc options database.

Returns

The options prefix.

set_F()

void set_F	(	std::function< void(const Vec x, Vec b)>	F,
		Vec	b_layout )

Set the function for computing the residual \(F(x)\), and the vector that defines its layout.

A residual defined by a fem::Form can be assembled with fem::petsc::assemble_residual.

Note

F must assemble into the b it is passed, which is not always b_layout. A line search, for instance, evaluates the residual in a work vector duplicated from b_layout.

Parameters

[in]	F	Function to assemble the residual at x into the b it is passed. It is responsible for zeroing that vector, and for any required ghost update of x.
[in]	b_layout	Vector that the solver may duplicate to create the vectors passed to F. A reference is held, so the caller can destroy their own reference.

set_J()

void set_J	(	std::function< void(const Vec x, Mat Jmat, Mat Pmat)>	J,
		Mat	J_layout,
		Mat	P_layout = nullptr )

Set the function for computing the Jacobian \(J := dF/dx\), and the matrices that define its layout.

A Jacobian defined by a fem::Form can be assembled with fem::petsc::assemble_jacobian.

Note

J must assemble into the Jmat and Pmat it is passed, which are not always J_layout and P_layout.

Parameters

[in]	J	Function to assemble the Jacobian at x into the Jmat it is passed, and the preconditioner into the Pmat it is passed. It is responsible for zeroing the matrices it assembles into and for finalising assembly.
[in]	J_layout	Matrix defining the layout of the Jacobian.
[in]	P_layout	Matrix defining the layout of the preconditioner. If nullptr, J_layout is used, the two matrices passed to J are the same, and J should assemble the Jacobian only. A reference to each matrix is held, so the caller can destroy their own references.

set_options_prefix()

void set_options_prefix

(

std::string_view

options_prefix

)

Set the prefix used by PETSc when searching the PETSc options database.

Parameters

[in]

options_prefix

Prefix to set. Conventionally ends with _.

set_update()

void set_update

(

std::function< void(PetscInt step)>

update

)

Set a function called before each nonlinear iteration, e.g. to update a time- or step-dependent term.

Parameters

[in]

update

Function called with the index of the iteration that is about to be taken.

snes()

SNES snes

(

)

const

Get the wrapped PETSc SNES object, e.g. to configure the line search or the Krylov solver used for each iteration.

Returns

The PETSc SNES object. The solver retains ownership.

solve()

SNESConvergedReason solve ( Vec x )

nodiscard

Solve \(F(x) = 0\).

Non-convergence is not treated as an error (a warning is logged); check the returned convergence reason, or use the -snes_error_if_not_converged option.

Note

An exception thrown by a callback is re-thrown here. The callback must throw on all ranks. A solver that throws an exception must not be used again.

Parameters

[in,out]

x

Solution vector, holding the initial guess on entry.

Returns

The PETSc convergence reason (positive on convergence, negative on divergence).

---

The documentation for this class was generated from the following files:

• /__w/dolfinx/dolfinx/cpp/dolfinx/nls/SNESSolver.h
• /__w/dolfinx/dolfinx/cpp/dolfinx/nls/SNESSolver.cpp