dolfinx.fem.petsc

Assembly functions into PETSc objects for variational forms.

Functions in this module generally apply functions in dolfinx.fem to PETSc linear algebra objects and handle any PETSc-specific preparation.

Functions

`apply_lifting`(b, a, bcs[, x0, scale, ...])	Apply the function `dolfinx.fem.apply_lifting()` to a PETSc Vector.
`apply_lifting_nest`(b, a, bcs[, x0, scale, ...])	Apply the function `dolfinx.fem.apply_lifting()` to each sub-vector in a nested PETSc Vector.
`assemble_matrix`(-> ~petsc4py.PETSc.Mat)
`assemble_matrix_block`(-> ~petsc4py.PETSc.Mat)
`assemble_matrix_nest`(-> ~petsc4py.PETSc.Mat)
`assemble_vector`(-> ~petsc4py.PETSc.Vec)
`assemble_vector_block`(-> ~petsc4py.PETSc.Vec)
`assemble_vector_nest`(-> ~petsc4py.PETSc.Vec)
`create_matrix`(a[, mat_type])	Create a PETSc matrix that is compaible with a bilinear form.
`create_matrix_block`(a)	Create a PETSc matrix that is compaible with a rectangular array of bilinear forms.
`create_matrix_nest`(a)	Create a PETSc matrix (`MatNest`) that is compaible with a rectangular array of bilinear forms.
`create_vector`(L)	Create a PETSc vector that is compaible with a linear form.
`create_vector_block`(L)	Create a PETSc vector (blocked) that is compaible with a list of linear forms.
`create_vector_nest`(L)	Create a PETSc netsted vector (`VecNest`) that is compaible with a list of linear forms.
`load_petsc_lib`(loader)	Load PETSc shared library using loader callable, e.g.
`set_bc`(b, bcs[, x0, scale])	Apply the function `dolfinx.fem.set_bc()` to a PETSc Vector.
`set_bc_nest`(b, bcs[, x0, scale])	Apply the function `dolfinx.fem.set_bc()` to each sub-vector of a nested PETSc Vector.

Classes

`LinearProblem`(a, L[, bcs, u, petsc_options, ...])	Class for solving a linear variational problem of the form \(a(u, v) = L(v) \, \forall v \in V\) using PETSc as a linear algebra backend.
`NonlinearProblem`(F, u[, bcs, J, ...])	Nonlinear problem class for solving the non-linear problem \(F(u, v) = 0 \ \forall v \in V\) using PETSc as the linear algebra backend.

class dolfinx.fem.petsc.DirichletBCMetaClass(value: Union[Function, Constant, numpy.ndarray], dofs: numpy.typing.ArrayLike, V: Optional[dolfinx.fem.FunctionSpace] = None)[source]

Bases: object

Representation of Dirichlet boundary condition which is imposed on a linear system.

Notes

Dirichlet boundary conditions should normally be constructed using fem.dirichletbc() and not using this class initialiser. This class is combined with different base classes that depend on the scalar type of the boundary condition.

Parameters

value – Lifted boundary values function.
dofs – Local indices of degrees of freedom in function space to which boundary condition applies. Expects array of size (number of dofs, 2) if function space of the problem, V is passed. Otherwise assumes function space of the problem is the same of function space of boundary values function.
V – Function space of a problem to which boundary conditions are applied.

property function_space: FunctionSpace: The function space on which the boundary condition is defined

property g: The boundary condition value(s)

class dolfinx.fem.petsc.FormMetaClass(form, V: list[dolfinx.cpp.fem.FunctionSpace], coeffs, constants, subdomains: dict[dolfinx.cpp.mesh.MeshTags_int32, Optional[Any]], mesh: Mesh, ffi, code)[source]

Bases: object

A finite element form

Notes

Forms should normally be constructed using forms.form() and not using this class initialiser. This class is combined with different base classes that depend on the scalar type used in the Form.

Parameters

form – Compiled UFC form
V – The argument function spaces
coeffs – Finite element coefficients that appear in the form
constants – Constants appearing in the form
subdomains – Subdomains for integrals
mesh – The mesh that the form is defined on

property code: str: C code strings

property dtype: dtype: dtype of this form

property function_spaces: List[FunctionSpace]: Function spaces on which this form is defined

property integral_types: Integral types in the form

property mesh: Mesh: Mesh on which this form is defined

property ufcx_form: The compiled ufcx_form object

class dolfinx.fem.petsc.LinearProblem(a: Form, L: Form, bcs: List[DirichletBCMetaClass] = [], u: Optional[Function] = None, petsc_options={}, form_compiler_options={}, jit_options={})[source]

Bases: object

Class for solving a linear variational problem of the form \(a(u, v) = L(v) \, \forall v \in V\) using PETSc as a linear algebra backend.

Initialize solver for a linear variational problem.

Parameters

a – A bilinear UFL form, the left hand side of the variational problem.
L – A linear UFL form, the right hand side of the variational problem.
bcs – A list of Dirichlet boundary conditions.
u – The solution function. It will be created if not provided.
petsc_options – Options that are passed to the linear algebra backend PETSc. For available choices for the ‘petsc_options’ kwarg, see the PETSc documentation.
form_compiler_options – Options used in FFCx compilation of this form. Run ffcx --help at the commandline to see all available options.
jit_options – Options used in CFFI JIT compilation of C code generated by FFCx. See python/dolfinx/jit.py for all available options. Takes priority over all other option values.

Example:

problem = LinearProblem(a, L, [bc0, bc1],
                        petsc_options={"ksp_type": "preonly",
                                       "pc_type": "lu",
                                       "pc_factor_mat_solver_type": "mumps"})

property A: Mat: Matrix operator

property L: FormMetaClass: The compiled linear form

property a: FormMetaClass: The compiled bilinear form

property b: Vec: Right-hand side vector

solve() → Function[source]: Solve the problem.

property solver: KSP: Linear solver object

class dolfinx.fem.petsc.NonlinearProblem(F: Form, u: Function, bcs: List[DirichletBCMetaClass] = [], J: Optional[Form] = None, form_compiler_options={}, jit_options={})[source]

Bases: object

Nonlinear problem class for solving the non-linear problem \(F(u, v) = 0 \ \forall v \in V\) using PETSc as the linear algebra backend.

Initialize solver for solving a non-linear problem using Newton’s method, \(dF/du(u) du = -F(u)\).

Parameters

F – The PDE residual F(u, v)
u – The unknown
bcs – List of Dirichlet boundary conditions
J – UFL representation of the Jacobian (Optional)
form_compiler_options – Options used in FFCx compilation of this form. Run ffcx --help at the commandline to see all available options.
jit_options – Options used in CFFI JIT compilation of C code generated by FFCx. See python/dolfinx/jit.py for all available options. Takes priority over all other option values.

Example:

problem = LinearProblem(F, u, [bc0, bc1])

F(x: Vec, b: Vec)[source]

Assemble the residual F into the vector b.

Parameters

x – The vector containing the latest solution
b – Vector to assemble the residual into

J(x: Vec, A: Mat)[source]

Assemble the Jacobian matrix.

Parameters: x – The vector containing the latest solution

property L: FormMetaClass: Compiled linear form (the residual form)

property a: FormMetaClass: Compiled bilinear form (the Jacobian form)

form(x: Vec)[source]

This function is called before the residual or Jacobian is computed. This is usually used to update ghost values.

Parameters: x – The vector containing the latest solution

dolfinx.fem.petsc.apply_lifting(b: Vec, a: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]], bcs: List[List[DirichletBCMetaClass]], x0: List[Vec] = [], scale: float = 1.0, constants=None, coeffs=None) → None[source]: Apply the function dolfinx.fem.apply_lifting() to a PETSc Vector.

dolfinx.fem.petsc.apply_lifting_nest(b: Vec, a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass], x0: Optional[Vec] = None, scale: float = 1.0, constants=None, coeffs=None) → Vec[source]: Apply the function dolfinx.fem.apply_lifting() to each sub-vector in a nested PETSc Vector.

dolfinx.fem.petsc.assemble_matrix(a: Any, bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat[source]
dolfinx.fem.petsc.assemble_matrix(a: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128], bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat
dolfinx.fem.petsc.assemble_matrix(A: Mat, a: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128], bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat

dolfinx.fem.petsc.assemble_matrix_block(a: Any, bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat[source]
dolfinx.fem.petsc.assemble_matrix_block(a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat
dolfinx.fem.petsc.assemble_matrix_block(A: Mat, a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat

dolfinx.fem.petsc.assemble_matrix_nest(a: Any, bcs: List[DirichletBCMetaClass] = [], mat_types=[], diagonal: float = 1.0, constants=None, coeffs=None) → Mat[source]
dolfinx.fem.petsc.assemble_matrix_nest(a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], mat_types=[], diagonal: float = 1.0, constants=None, coeffs=None) → Mat
dolfinx.fem.petsc.assemble_matrix_nest(A: Mat, a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], diagonal: float = 1.0, constants=None, coeffs=None) → Mat

dolfinx.fem.petsc.assemble_vector(L: Any, constants=None, coeffs=None) → Vec[source]
dolfinx.fem.petsc.assemble_vector(L: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128], constants=None, coeffs=None) → Vec
dolfinx.fem.petsc.assemble_vector(b: Vec, L: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128], constants=None, coeffs=None) → Vec

dolfinx.fem.petsc.assemble_vector_block(L: Any, a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], x0: Optional[Vec] = None, scale: float = 1.0, constants_L=None, coeffs_L=None, constants_a=None, coeffs_a=None) → Vec[source]
dolfinx.fem.petsc.assemble_vector_block(L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]], a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], x0: Optional[Vec] = None, scale: float = 1.0, constants_L=None, coeffs_L=None, constants_a=None, coeffs_a=None) → Vec
dolfinx.fem.petsc.assemble_vector_block(b: Vec, L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]], a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]], bcs: List[DirichletBCMetaClass] = [], x0: Optional[Vec] = None, scale: float = 1.0, constants_L=None, coeffs_L=None, constants_a=None, coeffs_a=None) → Vec

dolfinx.fem.petsc.assemble_vector_nest(L: Any, constants=None, coeffs=None) → Vec[source]
dolfinx.fem.petsc.assemble_vector_nest(L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]], constants=None, coeffs=None) → Vec
dolfinx.fem.petsc.assemble_vector_nest(b: Vec, L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]], constants=None, coeffs=None) → Vec

dolfinx.fem.petsc.create_matrix(a: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128], mat_type=None) → Mat[source]

Create a PETSc matrix that is compaible with a bilinear form.

Parameters

a – A bilinear form.
mat_type – The PETSc matrix type (MatType).

Returns

A PETSc matrix with a layout that is compatible with a.

dolfinx.fem.petsc.create_matrix_block(a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]]) → Mat[source]

Create a PETSc matrix that is compaible with a rectangular array of bilinear forms.

Parameters: a – A rectangular array of bilinear forms.
Returns: A PETSc matrix with a blocked layout that is compatible with a.

dolfinx.fem.petsc.create_matrix_nest(a: List[List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]]) → Mat[source]

Create a PETSc matrix (MatNest) that is compaible with a rectangular array of bilinear forms.

Parameters: a – A rectangular array of bilinear forms.
Returns: A PETSc matrix (‘MatNest``) that is compatible with a.

dolfinx.fem.petsc.create_vector(L: Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]) → Vec[source]

Create a PETSc vector that is compaible with a linear form.

Parameters: L – A linear form.
Returns: A PETSc vector with a layout that is compatible with L.

dolfinx.fem.petsc.create_vector_block(L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]) → Vec[source]

Create a PETSc vector (blocked) that is compaible with a list of linear forms.

Parameters: L – List of linear forms.
Returns: A PETSc vector with a layout that is compatible with L.

dolfinx.fem.petsc.create_vector_nest(L: List[Union[FormMetaClass, Form_float32, Form_float64, Form_complex64, Form_complex128]]) → Vec[source]

Create a PETSc netsted vector (VecNest) that is compaible with a list of linear forms.

Parameters: L – List of linear forms.
Returns: A PETSc nested vector (VecNest) with a layout that is compatible with L.

dolfinx.fem.petsc.load_petsc_lib(loader: Callable[[str], Any]) → Any[source]

Load PETSc shared library using loader callable, e.g. ctypes.CDLL.

Parameters: loader – A callable that accepts a library path and returns a wrapped library.
Returns: A wrapped library of the type returned by the callable.

dolfinx.fem.petsc.set_bc(b: Vec, bcs: List[DirichletBCMetaClass], x0: Optional[Vec] = None, scale: float = 1.0) → None[source]: Apply the function dolfinx.fem.set_bc() to a PETSc Vector.

dolfinx.fem.petsc.set_bc_nest(b: Vec, bcs: List[List[DirichletBCMetaClass]], x0: Optional[Vec] = None, scale: float = 1.0) → None[source]: Apply the function dolfinx.fem.set_bc() to each sub-vector of a nested PETSc Vector.