Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

firedrake.preconditioners package

Submodules

firedrake.preconditioners.asm module

class firedrake.preconditioners.asm.ASMExtrudedStarPC[source]

Bases: ASMStarPC

Patch-based PC using Star of mesh entities implmented as an ASMPatchPC.

ASMExtrudedStarPC is an additive Schwarz preconditioner where each patch consists of all DoFs on the topological star of the mesh entity specified by \(pc_star_construct_dim\).

Non-overlapping patches may be optionally grouped together via a coloring of the mesh entities. This is specified via the option \(pc_star_use_coloring\).

The mesh entities in the patches may be reordered by applying a matrix reordering to the connectivity graph with the option \(pc_star_mat_ordering_type\).

get_patches(V)[source]

Get the patches used for PETSc PCASM

Parameters:

V – the FunctionSpace.

Returns:

a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called).

class firedrake.preconditioners.asm.ASMLinesmoothPC[source]

Bases: ASMPatchPC

Linesmoother PC for extruded meshes implemented as an ASMPatchPC.

ASMLinesmoothPC is an additive Schwarz preconditioner where each patch consists of all dofs associated with a vertical column (and hence extruded meshes are necessary). Three types of columns are possible: columns of horizontal faces (each column built over a face of the base mesh), columns of vertical faces (each column built over an edge of the base mesh), and columns of vertical edges (each column built over a vertex of the base mesh).

To select the column type or types for the patches, use ‘pc_linesmooth_codims’ to set integers giving the codimension of the base mesh entities for the columns. For example, ‘pc_linesmooth_codims 0,1’ creates patches for each cell and each facet of the base mesh.

get_patches(V)[source]

Get the patches used for PETSc PCASM

Parameters:

V – the FunctionSpace.

Returns:

a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called).

class firedrake.preconditioners.asm.ASMPatchPC[source]

Bases: PCBase

PC for PETSc PCASM

should implement: - get_patches()

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

destroy(pc)[source]
abstractmethod get_patches(V)[source]

Get the patches used for PETSc PCASM

Parameters:

V – the FunctionSpace.

Returns:

a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called).

initialize(pc)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]
class firedrake.preconditioners.asm.ASMStarPC[source]

Bases: ASMPatchPC

Patch-based PC using Star of mesh entities implemented as an ASMPatchPC.

ASMStarPC is an additive Schwarz preconditioner where each patch consists of all DoFs on the topological star of the mesh entity specified by \(pc_star_construct_dim\).

Non-overlapping patches may be optionally grouped together via a coloring of the mesh entities. This is specified via the option \(pc_star_use_coloring\).

The mesh entities in the patches may be reordered by applying a matrix reordering to the connectivity graph with the option \(pc_star_mat_ordering_type\).

get_patches(V)[source]

Get the patches used for PETSc PCASM

Parameters:

V – the FunctionSpace.

Returns:

a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called).

class firedrake.preconditioners.asm.ASMVankaPC[source]

Bases: ASMPatchPC

Patch-based PC using closure of star of mesh entities implmented as an ASMPatchPC.

ASMVankaPC is an additive Schwarz preconditioner where each patch consists of all DoFs on the closure of the star of the mesh entity specified by \(pc_vanka_construct_dim\) (or codim).

Non-overlapping patches may be optionally grouped together via a coloring of the mesh entities. This is specified via the option \(pc_vanka_use_coloring\).

The mesh entities in the patches may be reordered by applying a matrix reordering to the connectivity graph with the option \(pc_vanka_mat_ordering_type\).

get_patches(V)[source]

Get the patches used for PETSc PCASM

Parameters:

V – the FunctionSpace.

Returns:

a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called).

firedrake.preconditioners.assembled module

class firedrake.preconditioners.assembled.AssembledPC[source]

Bases: PCBase

A matrix-free PC that assembles the operator.

Internally this makes a PETSc PC object that can be controlled by options using the extra options prefix assembled_.

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

initialize(pc)[source]

Initialize any state in this preconditioner.

set_nullspaces(pc)[source]
update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]
class firedrake.preconditioners.assembled.AuxiliaryOperatorPC[source]

Bases: AssembledPC

A preconditioner that builds a PC on a specified form. Mainly used for describing approximations to Schur complements.

firedrake.preconditioners.auxiliary_snes module

class firedrake.preconditioners.auxiliary_snes.AuxiliaryOperatorSNES[source]

Bases: SNESBase

Solve a residual form \(F(u) = 0\) using a nonlinear Richardson iteration preconditioned with an auxiliary form \(G\). This may be used to create nonlinear preconditioners for iterative methods such as Anderson acceleration or NGMRES.

The \(k\)-th nonlinearly preconditioned Richardson iteration is:

\[G(u_{k+1}; u_{k}) = G(u_{k}; u_{k}) - F(u_{k})\]

where \(u_{k}\) is the current guess and \(u_{k+1}\) is the next guess to be computed. A solution \(u_{*}\) of \(F(u_{*}) = 0\) is a fixed point of the Richardson iteration.

Options for the inner solve for \(G(u_{k+1}; u_{k})\) are specified using the "aux_" prefix.

The following solver parameters will specify the above Richardson iteration, assuming that the user has defined a class UserAuxiliarySNES which inherits from AuxiliaryOperatorSNES and implements the form() method. In this example, the inner solve uses a Newton method with a relative tolerance of 1e-4.

solver_parameters = {
    "snes_rtol": 1e-8,
    "snes_type": "python",
    "snes_python_type": f"{__name__}.UserAuxiliarySNES",
    "aux": {
        "snes_rtol": 1e-4,
        "snes_type": "newtonls",
        ...
    }
}

More details, including how to use this class as a nonlinear preconditioner with methods like Anderson acceleration, can be found in the manual page on Preconditioning infrastructure.

Notes

If the auxiliary form is linear, i.e. \(G(u)=Au\), with \(A\approx\nabla F\) approximating the Jacobian of the outer residual, then the iteration is an inexact Newton method:

\[u_{k+1} = u_{k} - A^{-1}F(u_{k}).\]
form(snes, u_k: Function, u: Function, test: Argument)[source]

Return the auxiliary residual form \(G(u_{k+1}; u_k)\) in the Richardson iteration and boundary conditions. Subclasses should override this method.

Defaults to returning a copy of \(F(u)\), i.e. \(G(u_{k+1}; u_k)=F(u_{k+1})\). This means that AuxiliaryOperatorSNES can be used similarly to AssembledPC, in that it can be used to specify an alternative snes_type for solving the same residual form as the outer SNES.

Parameters:

  • snes (petsc4py.PETSc.SNES) – The PETSc nonlinear solver object.

  • u_k – The current iterate \(u_{k}\).

  • u – The next iterate \(u_{k+1}\) that will be solved for.

  • test – The test function.

Returns:

  • G (ufl.BaseForm) – The preconditioning residual form.

  • bcs (Iterable[DirichletBC] | None) – The boundary conditions.

Notes

\(G(u_{k+1}; u_{k})\) is parameterised by the current iterate \(u_{k}\). For example, to use Picard iterations for the advection term:

\[F(u) = \ldots + u\cdot\nabla u\]

in the Navier-Stokes equations, we would use

\[G(u_{k+1}; u_{k}) = \ldots + u_{k}\cdot\nabla u_{k+1}.\]
initialize(snes)[source]

Initialize any state in this preconditioner.

step(snes, x, f, y)[source]
update(snes)[source]

Update any state in this preconditioner.

view(snes, viewer=None)[source]

firedrake.preconditioners.base module

class firedrake.preconditioners.base.PCBase[source]

Bases: PCSNESBase

Create a PC python context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

abstractmethod apply(pc, X, Y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

abstractmethod applyTranspose(pc, X, Y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

needs_python_amat = False

Set this to True if the A matrix needs to be Python (matfree).

needs_python_pmat = False

Set this to False if the P matrix needs to be Python (matfree).

If the preconditioner also works with assembled matrices, then use False here.

setUp(pc)[source]

Setup method called by PETSc.

Subclasses should probably not override this and instead implement update() and initialize().

class firedrake.preconditioners.base.PCSNESBase[source]

Bases: object

Create a PC or SNES python context suitable for PETSc.

Both Python PC and SNES classes should inherit from this class and implement:

Python PC classes should additionally implement:

Python SNES classes should additionally implement one of the following:

  • SNESBase.step

  • SNESBase.solve

destroy(pc)[source]
form(obj, *args)[source]

Return the preconditioning bilinear form and boundary conditions.

Parameters:

  • obj (PETSc.PC or PETSc.SNES) – The PETSc solver object.

  • test (ufl.TestFunction) – The test function.

  • trial (ufl.TrialFunction) – The trial function.

Returns:

  • a (ufl.Form) – The preconditioning bilinear form.

  • bcs (DirichletBC[] or None) – The boundary conditions.

Notes

Subclasses may override this function to provide an auxiliary bilinear form. Use \(self.get_appctx(obj)\) to get the user-supplied application-context, if desired.

static get_appctx(obj)[source]
abstractmethod initialize(pc)[source]

Initialize any state in this preconditioner.

static new_snes_ctx(pc: ~petsc4py.PETSc.PC, Jp: ~ufl.form.BaseForm, bcs: [<class 'firedrake.bcs.BCBase'>], mat_type: str, fcp: dict | None = None, **kwargs)[source]

Create a new \(_SNESContext\) for nested (linear) preconditioning

Parameters:

  • pc – The PC object.

  • Jp – A bilinear form for preconditioning.

  • bcs – The boundary conditions.

  • mat_type – The matrix type for the assembly of Jp.

  • fcp – The form compiler parameters.

  • kwargs – Any extra kwargs are passed on to the new _SNESContext. For details see \(firedrake.solving_utils._SNESContext\).

Return type:

A new \(_SNESContext\)

setUp(pc)[source]

Setup method called by PETSc.

Subclasses should probably not override this and instead implement update() and initialize().

abstractmethod update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]
class firedrake.preconditioners.base.SNESBase[source]

Bases: PCSNESBase

Create SNES python context suitable for PETSc.

Python SNES classes should inherit from this class and implement:

Inheriting classes should additionally implement either:

  • SNESBase.step

  • SNESBase.solve

The required function signatures for each method are shown below:

def solve(self, snes, b, x):
    '''Solve the nonlinear problem using the Vec x as the initial guess and
    putting the solution back into x. The Vec b is constant forcing term which
    may be None.
    '''
    pass

def step(self, snes, X, F, Y):
    '''Apply one iteration of the SNES to the current iterate X,
    using the function residual F, and putting the update in Y.

    X, F and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.
    '''
    pass

Notes

The function signatures for the solve and step methods are shown in the docstring rather than being implemented as abstract methods because petsc4py will test whether the SNES python context has either a step or solve method to decide what to do when snes.solve() is called.

firedrake.preconditioners.bddc module

class firedrake.preconditioners.bddc.BDDCPC[source]

Bases: PCBase

PC for PETSc PCBDDC (Balancing Domain Decomposition by Constraints). This is a domain decomposition method using subdomains defined by the blocks in a Mat of type IS.

Internally, this PC creates a PETSc PCBDDC object that can be controlled by the options: - 'bddc_cellwise' to set up a MatIS on cellwise subdomains if P.type == python, - 'bddc_matfree' to set up a matrix-free MatIS if A.type == python, - 'bddc_pc_bddc_neumann' to set sub-KSPs on subdomains excluding corners, - 'bddc_pc_bddc_dirichlet' to set sub-KSPs on subdomain interiors, - 'bddc_pc_bddc_coarse' to set the coarse solver KSP.

This PC also inspects optional callbacks supplied in the application context: - 'get_discrete_gradient' for 3D problems in H(curl), this is a callable that provide the arguments (a Mat tabulating the gradient of the auxiliary H1 space) and keyword arguments supplied to PETSc.PC.setBDDCDiscreteGradient. - 'get_divergence_mat' for problems in H(div) (resp. 2D H(curl)), this is provide the arguments (a Mat with the assembled bilinear form testing the divergence (curl) against an L2 space) and keyword arguments supplied to PETSc.PC.setDivergenceMat. - 'primal_markers' a Function marking degrees of freedom of the solution space to be included in the coarse space. Any nonzero value is counted as a marked degree of freedom. If a DG(0) Function is provided, then all degrees of freedom on the cell are marked. Alternatively, 'primal_markers' can be a list of the global degrees of freedom to be supplied directly to PETSc.PC.setBDDCPrimalVerticesIS.

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

initialize(pc)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.covariance module

class firedrake.preconditioners.covariance.CovariancePC[source]

Bases: PCBase

A python PC context for a covariance operator. Will apply either the action or inverse of the covariance, whichever is the opposite of the Mat operator.

\[ \begin{align}\begin{aligned}B: V^{*} \to V\\B^{-1}: V \to V^{*}\end{aligned}\end{align} \]

Available options:

  • -pc_use_amat - use Amat to apply the covariance operator.

See also

CovarianceOperatorBase, AutoregressiveCovariance, CovarianceMatCtx, CovarianceMat

apply(pc, x, y)[source]

Apply the action or inverse of the covariance operator to x, putting the result in y.

y is not guaranteed to be zero on entry.

Parameters:

  • pc (PETSc.PC) – The PETSc preconditioner that self is the python context of.

  • x (PETSc.Vec) – The vector acted on by the pc.

  • y (PETSc.Vec) – The result of the pc application.

initialize(pc)[source]

Initialize any state in this preconditioner.

This method is only called on the first time that the setUp method is called.

needs_python_pmat = True

Set this to False if the P matrix needs to be Python (matfree).

prefix = 'covariance'

The options prefix of this PC.

update(pc)[source]

Update any state in this preconditioner.

This method is called the on second and later times that the setUp method is called.

This method is not needed for all preconditioners and can often be a no-op.

view(pc, viewer=None)[source]

View object. Method usually called by PETSc with e.g. -ksp_view.

firedrake.preconditioners.facet_split module

class firedrake.preconditioners.facet_split.FacetSplitPC[source]

Bases: PCBase

A preconditioner that splits a function into interior and facet DOFs.

Internally this creates a PETSc PC object that can be controlled by options using the extra options prefix facet_.

This allows for statically-condensed preconditioners to be applied to linear systems involving the matrix applied to the full set of DOFs. Code generated for the matrix-free operator evaluation in the space with full DOFs will run faster than the one with interior-facet decomposition, since the full element has a simpler structure.

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

destroy(pc)[source]
get_indices(V, W)[source]
initialize(pc)[source]

Initialize any state in this preconditioner.

needs_python_pmat = False

Set this to False if the P matrix needs to be Python (matfree).

If the preconditioner also works with assembled matrices, then use False here.

prolong(x, y)[source]
restrict(x, y)[source]
set_nullspaces(pc)[source]
update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.fdm module

class firedrake.preconditioners.fdm.FDMPC[source]

Bases: PCBase

A preconditioner for tensor-product elements that changes the shape functions so that the H(d) (d in {grad, curl, div}) Riesz map is sparse on Cartesian cells, and assembles a global sparse matrix on which other preconditioners, such as \(ASMStarPC\), can be applied.

Here we assume that the volume integrals in the Jacobian can be expressed as:

inner(d(v), alpha * d(u))*dx + inner(v, beta * u)*dx

where alpha and beta are possibly tensor-valued. The sparse matrix is obtained by approximating (v, alpha * u) and (v, beta * u) as diagonal mass matrices.

The PETSc options inspected by this class are: - ‘fdm_mat_type’: can be either ‘aij’, ‘sbaij’, or ‘is’ - ‘fdm_static_condensation’: are we assembling the Schur complement on facets?

allocate_matrix(Amat, V, J, bcs, fcp, pmat_type, use_static_condensation, use_amat)[source]

Allocate the FDM sparse preconditioner.

Parameters:

  • Amat – the original Jacobian PETSc.Mat

  • V – the FunctionSpace of the form arguments

  • J – the Jacobian bilinear form

  • bcs – an iterable of boundary conditions on V

  • fcp – form compiler parameters to assemble coefficients

  • pmat_type – the \(PETSc.Mat.Type\) for the blocks in the diagonal

  • use_static_condensation – are we assembling the statically-condensed Schur complement on facets?

  • use_amat – are we computing the Schur complement exactly?

Returns:

3-tuple with the Jacobian PETSc.Mat, the preconditioner PETSc.Mat, and a list of assembly callables

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

assemble_coefficients(J, fcp, block_diagonal=False)[source]

Obtain coefficients for the auxiliary operator as the diagonal of a weighted mass matrix in broken(V^k) * broken(V^{k+1}). See Section 3.2 of Brubeck2024.

Parameters:

  • J – the Jacobian bilinear ufl.Form,

  • fcp – form compiler parameters to assemble the diagonal of the mass matrices.

  • block_diagonal – are we assembling the block diagonal of the mass matrices?

Returns:

a 2-tuple of a dict of coefficients and a list of assembly callables.

assemble_reference_tensor(V, transpose=False, sort_interior=False)[source]

Return the reference tensor used in the diagonal factorisation of the sparse cell matrices. See Section 3.2 of Brubeck2024.

Parameters:

V – a FunctionSpace

Returns:

a PETSc.Mat interpolating V^k * d(V^k) onto broken(V^k) * broken(V^{k+1}) on the reference element.

property assembly_lgmaps
condense(A, J, bcs, fcp, pc_type='icc')[source]

Construct block matrices used for matrix-free static condensation. The inversion of the interior-interior block is replaced with a local KSP object that is reused on each cell within an MPI rank.

Parameters:

  • A (PETSc.Mat) – The matrix to statically condense.

  • J (ufl.Form) – The bilinear form to statically condense.

  • bcs (.BCBase[]) – An iterable of boundary conditions to apply on A.

  • fcp (dict) – The form compiler parameters.

  • pc_type (PETSc.PC.Type) – The preconditioner type for the interior solver.

Returns:

  • Smat (PETSc.Mat) – A matrix with the original blocks of A, except that the matrix-free Schur complement replaces the interface-interface block.

  • Pmat (dict) – A dict mapping pairs of function spaces to the preconditioner blocks [[inv(A00), A01], [A10, inv(S)]].

destroy(pc)[source]
initialize(pc)[source]

Initialize any state in this preconditioner.

property insert_mode
set_values(A, Vrow, Vcol, mat_type=None)[source]

Assemble the auxiliary operator in the FDM basis using sparse reference tensors and diagonal mass matrices.

Parameters:

  • A (PETSc.Mat) – The (initialized) matrix to assemble.

  • Vrow (FunctionSpace) – The test space.

  • Vcol (FunctionSpace) – The trial space.

setup_block(Vrow, Vcol)[source]

Preallocate the auxiliary sparse operator.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]
class firedrake.preconditioners.fdm.PoissonFDMPC[source]

Bases: FDMPC

A preconditioner for tensor-product elements that changes the shape functions so that the H^1 Riesz map is sparse in the interior of a Cartesian cell, and assembles a global sparse matrix on which other preconditioners, such as \(ASMStarPC\), can be applied.

Here we assume that the volume integrals in the Jacobian can be expressed as:

inner(grad(v), alpha(grad(u)))*dx + inner(v, beta(u))*dx

where alpha and beta are possibly tensor-valued. The sparse matrix is obtained by approximating alpha and beta by cell-wise constants and discarding the coefficients in alpha that couple together mixed derivatives and mixed components.

For spaces that are not H^1-conforming, this preconditioner will use the symmetric interior-penalty DG method. The penalty coefficient can be provided in the application context, keyed on "eta".

assemble_coefficients(J, fcp)[source]

Obtain coefficients for the auxiliary operator as the diagonal of a weighted mass matrix in broken(V^k) * broken(V^{k+1}). See Section 3.2 of Brubeck2024.

Parameters:

  • J – the Jacobian bilinear ufl.Form,

  • fcp – form compiler parameters to assemble the diagonal of the mass matrices.

  • block_diagonal – are we assembling the block diagonal of the mass matrices?

Returns:

a 2-tuple of a dict of coefficients and a list of assembly callables.

assemble_reference_tensor(V)[source]

Return the reference tensor used in the diagonal factorisation of the sparse cell matrices. See Section 3.2 of Brubeck2024.

Parameters:

V – a FunctionSpace

Returns:

a PETSc.Mat interpolating V^k * d(V^k) onto broken(V^k) * broken(V^{k+1}) on the reference element.

condense(A, J, bcs, fcp)[source]

Construct block matrices used for matrix-free static condensation. The inversion of the interior-interior block is replaced with a local KSP object that is reused on each cell within an MPI rank.

Parameters:

  • A (PETSc.Mat) – The matrix to statically condense.

  • J (ufl.Form) – The bilinear form to statically condense.

  • bcs (.BCBase[]) – An iterable of boundary conditions to apply on A.

  • fcp (dict) – The form compiler parameters.

  • pc_type (PETSc.PC.Type) – The preconditioner type for the interior solver.

Returns:

  • Smat (PETSc.Mat) – A matrix with the original blocks of A, except that the matrix-free Schur complement replaces the interface-interface block.

  • Pmat (dict) – A dict mapping pairs of function spaces to the preconditioner blocks [[inv(A00), A01], [A10, inv(S)]].

set_values(A, Vrow, Vcol, mat_type=None)[source]

Assemble the stiffness matrix in the FDM basis using Kronecker products of interval matrices.

Parameters:

  • A (PETSc.Mat) – The (initialized) matrix to assemble.

  • Vrow (FunctionSpace) – The test space.

  • Vcol (FunctionSpace) – The trial space.

  • mat_type (PETSc.Mat.Type) – The matrix type of auxiliary operator. This only used when A is a preallocator to determine the nonzeros on the upper triangual part of an 'sbaij' matrix.

firedrake.preconditioners.gtmg module

Non-nested multigrid preconditioner

class firedrake.preconditioners.gtmg.GTMGPC[source]

Bases: PCBase

Non-nested multigrid preconditioner

Implements the method described in [1]. Note that while the authors of this paper consider a non-nested function space hierarchy, the algorithm can also be applied if the spaces are nested.

Uses PCMG to implement a two-level multigrid method involving two spaces:

  • \(V\): the fine space on which the problem is formulated

  • \(V_coarse\): a user-defined coarse space

The following options must be passed through the \(appctx\) dictionary:

  • \(get_coarse_space\): method which returns the user-defined coarse space

  • \(get_coarse_operator\): method which returns the operator on the coarse space

The following options (also passed through the \(appctx\)) are optional:

  • \(form_compiler_parameters\): parameters for assembling operators on both levels of the hierarchy.

  • \(coarse_space_bcs\): boundary conditions to be used on coarse space.

  • \(get_coarse_op_nullspace\): method which returns the nullspace of the coarse operator.

  • \(get_coarse_op_transpose_nullspace\): method which returns the nullspace of the transpose of the coarse operator.

  • \(interpolation_matrix\): PETSc Mat which describes the interpolation from the coarse to the fine space. If omitted, this will be constructed automatically with an Interpolate object.

  • \(restriction_matrix\): PETSc Mat which describes the restriction from the fine space dual to the coarse space dual. It defaults to the transpose of the interpolation matrix.

PETSc options for the underlying PCMG object can be set with the prefix gt_.

Reference:

[1] Gopalakrishnan, J. and Tan, S., 2009: “A convergent multigrid cycle for the hybridized mixed method”. Numerical Linear Algebra with Applications, 16(9), pp.689-714. https://doi.org/10.1002/nla.636

apply(pc, X, Y)[source]

Apply preconditioner

Parameters:

  • pc – PETSc preconditioner instance

  • X – right hand side PETSc vector

  • Y – PETSc vector with resulting solution

applyTranspose(pc, X, Y)[source]

Apply transpose preconditioner

Parameters:

  • pc – PETSc preconditioner instance

  • X – right hand side PETSc vector

  • Y – PETSc vector with resulting solution

initialize(pc)[source]

Initialize new instance

Parameters:

pc – PETSc preconditioner instance

needs_python_pmat = False

Set this to False if the P matrix needs to be Python (matfree).

If the preconditioner also works with assembled matrices, then use False here.

update(pc)[source]

Update preconditioner

Re-assemble operators on both levels of the hierarchy

Parameters:

pc – PETSc preconditioner instance

view(pc, viewer=None)[source]

View preconditioner options

Parameters:

  • pc – preconditioner instance

  • viewer – PETSc viewer instance

firedrake.preconditioners.hiptmair module

class firedrake.preconditioners.hiptmair.HiptmairPC[source]

Bases: TwoLevelPC

A two-level method for H(curl) or H(div) problems with an auxiliary potential space in H^1 or H(curl), respectively.

Internally this creates a PETSc PCMG object that can be controlled by options using the extra options prefix hiptmair_mg_.

This allows for effective multigrid relaxation methods with patch solves centered around vertices for H^1, edges for H(curl), or faces for H(div). For the lowest-order spaces this corresponds to point-Jacobi.

The H(div) auxiliary vector potential problem in H(curl) is singular for high-order. This can be overcome by pertubing the problem by a multiple of the mass matrix. The scaling factor can be provided (defaulting to 0) by providing a scalar in the application context, keyed on "hiptmair_shift".

coarsen(pc)[source]

Return a tuple with coarse bilinear form, coarse boundary conditions, and coarse-to-fine interpolation matrix

class firedrake.preconditioners.hiptmair.TwoLevelPC[source]

Bases: PCBase

PC for two-level methods

should implement: - coarsen()

apply(pc, X, Y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, X, Y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

abstractmethod coarsen(pc)[source]

Return a tuple with coarse bilinear form, coarse boundary conditions, and coarse-to-fine interpolation matrix

initialize(pc)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.hypre_ads module

class firedrake.preconditioners.hypre_ads.HypreADS[source]

Bases: PCBase

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

initialize(obj)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.hypre_ams module

class firedrake.preconditioners.hypre_ams.HypreAMS[source]

Bases: PCBase

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

initialize(obj)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.low_order module

class firedrake.preconditioners.low_order.LORPC[source]

Bases: PMGPC

A low-order refined preconditioner with a P1-iso-Pk coarse space.

coarsen_element(ele)[source]

Coarsen a given element to form the next problem down in the p-hierarchy.

If the supplied element should form the coarsest level of the p-hierarchy, raise \(ValueError\). Otherwise, return a new finat.ufl.finiteelement.FiniteElement.

By default, this does power-of-2 coarsening in polynomial degree until we reach the coarse degree specified through PETSc options (1 by default).

Parameters:

ele – A finat.ufl.finiteelement.FiniteElement to coarsen.

class firedrake.preconditioners.low_order.P1PC[source]

Bases: PMGPC

A two-level preconditioner with agressive p-coarsening.

coarsen_element(ele)[source]

Coarsen a given element to form the next problem down in the p-hierarchy.

If the supplied element should form the coarsest level of the p-hierarchy, raise \(ValueError\). Otherwise, return a new finat.ufl.finiteelement.FiniteElement.

By default, this does power-of-2 coarsening in polynomial degree until we reach the coarse degree specified through PETSc options (1 by default).

Parameters:

ele – A finat.ufl.finiteelement.FiniteElement to coarsen.

class firedrake.preconditioners.low_order.P1SNES[source]

Bases: PMGSNES

A two-level nonlinear solver with agressive p-coarsening.

coarsen_element(ele)[source]

Coarsen a given element to form the next problem down in the p-hierarchy.

If the supplied element should form the coarsest level of the p-hierarchy, raise \(ValueError\). Otherwise, return a new finat.ufl.finiteelement.FiniteElement.

By default, this does power-of-2 coarsening in polynomial degree until we reach the coarse degree specified through PETSc options (1 by default).

Parameters:

ele – A finat.ufl.finiteelement.FiniteElement to coarsen.

firedrake.preconditioners.massinv module

class firedrake.preconditioners.massinv.MassInvPC[source]

Bases: AssembledPC

A matrix free operator that assembles the mass matrix in the provided space.

Internally this creates a PETSc PC object that can be controlled by options using the extra options prefix Mp_.

A preconditioner with the (approximate) action of the inverse mass matrix can be constructed by creating an internal PETSc KSP object by setting -Mp_pc_type ksp and suitable inner options, such as -Mp_ksp_ksp_type chebyshev and -Mp_ksp_pc_type jacobi, for example.

For Stokes problems, to be spectrally equivalent to the Schur complement, the mass matrix should be weighted by the viscosity. This can be provided (defaulting to constant viscosity) by providing a field defining the viscosity in the application context, keyed on "mu".

form(pc, test, trial)[source]

Return the preconditioning bilinear form and boundary conditions.

Parameters:

  • obj (PETSc.PC or PETSc.SNES) – The PETSc solver object.

  • test (ufl.TestFunction) – The test function.

  • trial (ufl.TrialFunction) – The trial function.

Returns:

  • a (ufl.Form) – The preconditioning bilinear form.

  • bcs (DirichletBC[] or None) – The boundary conditions.

Notes

Subclasses may override this function to provide an auxiliary bilinear form. Use \(self.get_appctx(obj)\) to get the user-supplied application-context, if desired.

set_nullspaces(pc)[source]

firedrake.preconditioners.offload module

class firedrake.preconditioners.offload.OffloadPC[source]

Bases: PCBase

Offload PC from CPU to GPU and back.

Internally this makes a PETSc PC object that can be controlled by options using the extra options prefix offload_.

apply(pc, x, y, transpose=False)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

call_device_vec_impl(x, func_name: str, *args, **kwargs)[source]
initialize(pc)[source]

Initialize any state in this preconditioner.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.patch module

class firedrake.preconditioners.patch.PatchPC[source]

Bases: PCBase, PatchBase

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

configure_patch(patch, pc)[source]
class firedrake.preconditioners.patch.PatchSNES[source]

Bases: SNESBase, PatchBase

configure_patch(patch, snes)[source]
step(snes, x, f, y)[source]
class firedrake.preconditioners.patch.PlaneSmoother[source]

Bases: object

__call__(pc)[source]

Call self as a function.

static coords(dm, p, coordinates)[source]
sort_entities(dm, axis, dir, ndiv=None, divisions=None)[source]

firedrake.preconditioners.pcd module

class firedrake.preconditioners.pcd.PCDPC[source]

Bases: PCBase

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

destroy(pc)[source]
initialize(pc)[source]

Initialize any state in this preconditioner.

needs_python_pmat = True

A Pressure-Convection-Diffusion preconditioner for Navier-Stokes.

This preconditioner approximates the inverse of the pressure schur complement for the Navier-Stokes equations by.

\[S^{-1} \sim K^{-1} F_p M^{-1}\]

Where \(K = \nabla^2\), \(F_p = (1/\mathrm{Re}) \nabla^2 + u\cdot\nabla\) and \(M = \mathbb{I}\).

The inverse of \(K\) is approximated by a KSP which can be controlled using the options prefix pcd_Kp_.

The inverse of \(M\) is similarly approximated by a KSP which can be controlled using the options prefix pcd_Mp_.

\(F_p\) requires both the Reynolds number and the current velocity. You must provide these with options using the glbaol option Re for the Reynolds number and the prefixed option pcd_velocity_space which should be the index into the full space that gives velocity field.

Note

Currently, the boundary conditions applied to the PCD operator are correct for characteristic velocity boundary conditions, but sub-optimal for in and outflow boundaries.

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

firedrake.preconditioners.pmg module

class firedrake.preconditioners.pmg.PMGPC[source]

Bases: PCBase, PMGBase

apply(pc, x, y)[source]

Apply the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

applyTranspose(pc, x, y)[source]

Apply the transpose of the preconditioner to X, putting the result in Y.

Both X and Y are PETSc Vecs, Y is not guaranteed to be zero on entry.

coarsen_bc_value(bc, cV)[source]
configure_pmg(pc, pdm)[source]
class firedrake.preconditioners.pmg.PMGSNES[source]

Bases: SNESBase, PMGBase

coarsen_bc_value(bc, cV)[source]
configure_pmg(snes, pdm)[source]
step(snes, x, f, y)[source]

Module contents