dolfinx::fem::petsc Namespace Reference

Helper functions for assembly into PETSc data structures. More...

Functions
template<std::floating_point T>
Mat	create_matrix (const Form< PetscScalar, T > &a, std::optional< std::string > type=std::nullopt)
	Create a matrix.
template<std::floating_point T>
Mat	create_matrix_block (const std::vector< std::vector< const Form< PetscScalar, T > * > > &a, std::optional< std::string > type=std::nullopt)
	Initialise a monolithic matrix for an array of bilinear forms.
template<std::floating_point T>
Mat	create_matrix_nest (const std::vector< std::vector< const Form< PetscScalar, T > * > > &a, std::optional< std::vector< std::vector< std::optional< std::string > > > > types)
	Create nested (MatNest) matrix.
Vec	create_vector_block (const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Initialise monolithic vector. Vector is not zeroed.
Vec	create_vector_nest (const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &maps)
	Create nested (VecNest) vector. Vector is not zeroed.
template<std::floating_point T>
void	assemble_vector (Vec b, const Form< PetscScalar, T > &L, std::span< const PetscScalar > constants, const std::map< std::pair< IntegralType, int >, std::pair< std::span< const PetscScalar >, int > > &coeffs)
	Assemble linear form into an already allocated PETSc vector.
template<std::floating_point T>
void	assemble_vector (Vec b, const Form< PetscScalar, T > &L)
	Assemble linear form into an already allocated PETSc vector.
template<std::floating_point T>
void	apply_lifting (Vec b, std::vector< std::optional< std::reference_wrapper< const Form< PetscScalar, T > > > > a, const std::vector< std::span< const PetscScalar > > &constants, const std::vector< std::map< std::pair< IntegralType, int >, std::pair< std::span< const PetscScalar >, int > > > &coeffs, const std::vector< std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > > &bcs1, const std::vector< Vec > &x0, PetscScalar alpha)
	Modify RHS vector to account for Dirichlet boundary conditions.
template<std::floating_point T>
void	apply_lifting (Vec b, const std::vector< std::optional< std::reference_wrapper< const Form< PetscScalar, T > > > > &a, const std::vector< std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > > &bcs1, const std::vector< Vec > &x0, PetscScalar alpha)
	Modify RHS vector to account for Dirichlet boundary conditions.
template<std::floating_point T>
void	set_bc (Vec b, const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &bcs, std::optional< const Vec > x0, PetscScalar alpha=1)
	Entries in b that are constrained by a Dirichlet boundary conditions are set to alpha * (x_bc - x0), where x_bc is the (interpolated) boundary condition value.
template<std::floating_point T>
void	assemble_residual (const Vec x, Vec b, const Form< PetscScalar, T > &F, const Form< PetscScalar, T > &J, const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &bcs, Function< PetscScalar, T > &u)
	Assemble the residual \(F(x)\) of a nonlinear problem into b, with Dirichlet conditions applied.
template<std::floating_point T>
void	assemble_jacobian (const Vec x, Mat Jmat, Mat Pmat, const Form< PetscScalar, T > &J, const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &bcs, Function< PetscScalar, T > &u, const Form< PetscScalar, T > *P=nullptr)
	Assemble the Jacobian \(dF/dx\) of a nonlinear problem into Jmat, and a preconditioner into Pmat.

Detailed Description

Helper functions for assembly into PETSc data structures.

Function Documentation

apply_lifting() [1/2]

template<std::floating_point T>

void apply_lifting	(	Vec	b,
		const std::vector< std::optional< std::reference_wrapper< const Form< PetscScalar, T > > > > &	a,
		const std::vector< std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > > &	bcs1,
		const std::vector< Vec > &	x0,
		PetscScalar	alpha )

Modify RHS vector to account for Dirichlet boundary conditions.

Modify b such that:

b <- b - alpha * A_j (g_j - x0_j)

where j is a block (nest) index. For a non-blocked problem j = 0. The boundary conditions bcs1 are on the trial spaces V_j. The forms in [a] must have the same test space as L (from which b was built), but the trial space may differ. If x0 is not supplied, then it is treated as zero.

Ghost contributions are not accumulated (not sent to owner). Caller is responsible for calling VecGhostUpdateBegin/End.

Parameters

[in,out]	b	Vector to modify by lifting.
[in]	a	Bilinear forms, one per block j. A std::nullopt entry skips that block.
[in]	bcs1	Boundary conditions on the trial space V_j for each block j.
[in]	x0	Vectors used in the lifting, one per block j. If empty, x0_j is treated as zero for every block. Otherwise must have the same length as a.
[in]	alpha	Scaling to apply.

apply_lifting() [2/2]

template<std::floating_point T>

void apply_lifting	(	Vec	b,
		std::vector< std::optional< std::reference_wrapper< const Form< PetscScalar, T > > > >	a,
		const std::vector< std::span< const PetscScalar > > &	constants,
		const std::vector< std::map< std::pair< IntegralType, int >, std::pair< std::span< const PetscScalar >, int > > > &	coeffs,
		const std::vector< std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > > &	bcs1,
		const std::vector< Vec > &	x0,
		PetscScalar	alpha )

Modify RHS vector to account for Dirichlet boundary conditions.

Modify b such that:

b <- b - alpha * A_j (g_j - x0_j)

where j is a block (nest) index. For a non-blocked problem j = 0. The boundary conditions bcs1 are on the trial spaces V_j. The forms in [a] must have the same test space as L (from which b was built), but the trial space may differ. If x0 is not supplied, then it is treated as zero.

Ghost contributions are not accumulated (not sent to owner). Caller is responsible for calling VecGhostUpdateBegin/End.

Parameters

[in,out]	b	Vector to modify by lifting.
[in]	a	Bilinear forms, one per block j. A std::nullopt entry skips that block.
[in]	constants	Constants that appear in each form in a, one entry per block j.
[in]	coeffs	Coefficients that appear in each form in a, one entry per block j.
[in]	bcs1	Boundary conditions on the trial space V_j for each block j.
[in]	x0	Vectors used in the lifting, one per block j. If empty, x0_j is treated as zero for every block. Otherwise must have the same length as a.
[in]	alpha	Scaling to apply.

assemble_jacobian()

template<std::floating_point T>

void assemble_jacobian	(	const Vec	x,
		Mat	Jmat,
		Mat	Pmat,
		const Form< PetscScalar, T > &	J,
		const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &	bcs,
		Function< PetscScalar, T > &	u,
		const Form< PetscScalar, T > *	P = nullptr )

Assemble the Jacobian \(dF/dx\) of a nonlinear problem into Jmat, and a preconditioner into Pmat.

Intended as the body of the Jacobian callback of nls::petsc::SNESSolver, which passes the point to evaluate at x and the matrices to assemble into Jmat and Pmat:

solver.set_J([&](const Vec x, Mat Jmat, Mat Pmat)
             { assemble_jacobian(x, Jmat, Pmat, J, bcs, u); },
             A_layout);

Rows and columns constrained by bcs are zeroed, and for a form whose test and trial spaces are the same a unit diagonal is set on the constrained rows, matching the residual assembled by assemble_residual.

Parameters

[in]	x	Point at which to evaluate the Jacobian, e.g. a line search trial point. Must be ghosted. Its ghost values are updated before use.
[out]	Jmat	Matrix to assemble the Jacobian into, which is the one the solver passed to the callback and not necessarily the one registered with set_J. Zeroed first.
[out]	Pmat	Matrix to assemble the preconditioner into. Zeroed first. Unused, and may be nullptr, if P is not given.
[in]	J	Jacobian form.
[in]	bcs	Dirichlet boundary conditions.
[out]	u	Function that J and P hold as a coefficient. Its degrees-of-freedom are set to x before assembly.
[in]	P	Preconditioner form. If not given, Pmat is left alone and PETSc preconditions with the Jacobian.

assemble_residual()

template<std::floating_point T>

void assemble_residual	(	const Vec	x,
		Vec	b,
		const Form< PetscScalar, T > &	F,
		const Form< PetscScalar, T > &	J,
		const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &	bcs,
		Function< PetscScalar, T > &	u )

Assemble the residual \(F(x)\) of a nonlinear problem into b, with Dirichlet conditions applied.

Intended as the body of the residual callback of nls::petsc::SNESSolver, which passes the point to evaluate at x and the vector to assemble into b:

solver.set_F([&](const Vec x, Vec b)
             { assemble_residual(x, b, F, J, bcs, u); }, b_layout);

Entries of b constrained by bcs are set to x - g, so that a Newton update drives x to the boundary condition value g.

Parameters

[in]	x	Point at which to evaluate the residual, e.g. a line search trial point. Must be ghosted. Its ghost values are updated before use.
[out]	b	Vector to assemble into, which is the one the solver passed to the callback and not necessarily the one registered with set_F. Zeroed first, and its ghost values are updated on return.
[in]	F	Residual form.
[in]	J	Jacobian form, used to lift bcs.
[in]	bcs	Dirichlet boundary conditions.
[out]	u	Function that F and J hold as a coefficient. Its degrees-of-freedom are set to x before assembly.

assemble_vector() [1/2]

template<std::floating_point T>

void assemble_vector	(	Vec	b,
		const Form< PetscScalar, T > &	L )

Assemble linear form into an already allocated PETSc vector.

Ghost contributions are not accumulated (not sent to owner). Caller is responsible for calling VecGhostUpdateBegin/End.

Parameters

[in,out]	b	Vector to assemble the form into. The vector must already be initialised with the correct size. The process-local contribution of the form is assembled into this vector. It is not zeroed before assembly.
[in]	L	Linear form to assemble.

assemble_vector() [2/2]

template<std::floating_point T>

void assemble_vector	(	Vec	b,
		const Form< PetscScalar, T > &	L,
		std::span< const PetscScalar >	constants,
		const std::map< std::pair< IntegralType, int >, std::pair< std::span< const PetscScalar >, int > > &	coeffs )

Assemble linear form into an already allocated PETSc vector.

Ghost contributions are not accumulated (not sent to owner). Caller is responsible for calling VecGhostUpdateBegin/End.

Parameters

[in,out]	b	The PETsc vector to assemble the form into. The vector must already be initialised with the correct size. The process-local contribution of the form is assembled into this vector. It is not zeroed before assembly.
[in]	L	The linear form to assemble
[in]	constants	The constants that appear in L
[in]	coeffs	The coefficients that appear in L

create_matrix()

template<std::floating_point T>

Mat create_matrix	(	const Form< PetscScalar, T > &	a,
		std::optional< std::string >	type = std::nullopt )

Create a matrix.

Parameters

[in]	a	A bilinear form
[in]	type	The PETSc matrix type to create

Returns

A sparse matrix with a layout and sparsity that matches the bilinear form. The caller is responsible for destroying the Mat object.

create_matrix_block()

template<std::floating_point T>

Mat create_matrix_block	(	const std::vector< std::vector< const Form< PetscScalar, T > * > > &	a,
		std::optional< std::string >	type = std::nullopt )

Initialise a monolithic matrix for an array of bilinear forms.

Parameters

[in]	a	Rectangular array of bilinear forms. The a(i, j) form will correspond to the (i, j) block in the returned matrix
[in]	type	The type of PETSc Mat. If empty the PETSc default is used.

Returns

A sparse matrix with a layout and sparsity that matches the bilinear forms. The caller is responsible for destroying the Mat object.

create_matrix_nest()

template<std::floating_point T>

Mat create_matrix_nest	(	const std::vector< std::vector< const Form< PetscScalar, T > * > > &	a,
		std::optional< std::vector< std::vector< std::optional< std::string > > > >	types )

Create nested (MatNest) matrix.

Note

The caller is responsible for destroying the Mat object.

create_vector_block()

Vec create_vector_block

(

const std::vector< std::pair< std::reference_wrapper< const common::IndexMap >, int > > &

maps

)

Initialise monolithic vector. Vector is not zeroed.

The caller is responsible for destroying the Vec object

set_bc()

template<std::floating_point T>

void set_bc	(	Vec	b,
		const std::vector< std::reference_wrapper< const DirichletBC< PetscScalar, T > > > &	bcs,
		std::optional< const Vec >	x0,
		PetscScalar	alpha = 1 )

Entries in b that are constrained by a Dirichlet boundary conditions are set to alpha * (x_bc - x0), where x_bc is the (interpolated) boundary condition value.

Parameters

[in]	b	The vector to apply the boundary condition to. The local (owned) part of this vector is modified. The user is responsible for scattering the changes to the ghost part of the vector if necessary.
[in]	bcs	The boundary conditions to apply.
[in]	x0	Optional vector used in computing the value to set. If not provided it is treated as zero. The local (owned) part of this vector is used.
[in]	alpha	Scaling to apply.