# firedrake.preconditioners package¶

## firedrake.preconditioners.asm module¶

class firedrake.preconditioners.asm.ASMExtrudedStarPC[source]

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.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

get_patches(V)[source]

Get the patches used for PETSc PSASM

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]

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.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

get_patches(V)[source]

Get the patches used for PETSc PSASM

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]

PC for PETSc PCASM

should implement: - get_patches()

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.

abstract get_patches(V)[source]

Get the patches used for PETSc PSASM

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]

Patch-based PC using Star of mesh entities implmented 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.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

get_patches(V)[source]

Get the patches used for PETSc PSASM

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]

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).

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

get_patches(V)[source]

Get the patches used for PETSc PSASM

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]

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_.

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.

form(pc, test, trial)[source]
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.assembled.AuxiliaryOperatorPC[source]

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

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

abstract form(pc, test, trial)[source]
Parameters
• pc – a PETSc.PC object. Use self.get_appctx(pc) to get the user-supplied application-context, if desired.

• test – a TestFunction on this FunctionSpace.

• trial – a TrialFunction on this FunctionSpace.

:returns (a, bcs), where a is a bilinear Form and bcs is a list of DirichletBC boundary conditions (possibly None).

## firedrake.preconditioners.base module¶

class firedrake.preconditioners.base.PCBase[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

abstract 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.

abstract 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 context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

static get_appctx(pc)[source]
abstract initialize(pc)[source]

Initialize any state in this preconditioner.

static new_snes_ctx(pc, op, bcs, mat_type, fcp=None, options_prefix=None)[source]

Create a new SNES contex for nested preconditioning

setUp(pc)[source]

Setup method called by PETSc.

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

abstract update(pc)[source]

Update any state in this preconditioner.

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

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

## firedrake.preconditioners.fdm module¶

class firedrake.preconditioners.fdm.FDMPC[source]

A preconditioner for tensor-product elements that changes the shape functions so that the H^1 Riesz map is diagonalized 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:

where alpha and beta are linear functions (tensor contractions). 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".

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.

Return the coefficients of the Jacobian form arguments and their gradient with respect to the reference coordinates.

Parameters
• J – the Jacobian bilinear form

• discard_mixed – discard entries in second order coefficient with mixed derivatives and mixed components

• cell_average – to return the coefficients as DG_0 Functions

Returns

a 2-tuple of coefficients: a dictionary mapping strings to firedrake.Functions with the coefficients of the form, assembly_callables: a list of assembly callables for each coefficient of the form

assemble_kron(A, V, coefficients, Afdm, Dfdm, eta, bcflags, needs_hdiv)[source]

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

Parameters
• A – the PETSc.Mat to assemble

• V – the firedrake.FunctionSpace of the form arguments

• coefficients – a dict mapping strings to firedrake.Functions with the form coefficients

• Bq – a firedrake.Function with the zero-th order coefficients of the form

• Afdm – the list with interval matrices returned by FDMPC.assemble_matfree

• Dfdm – the list with normal derivatives matrices returned by FDMPC.assemble_matfree

• eta – the SIPG penalty parameter as a float

• bcflags – the numpy.ndarray with BC facet flags returned by FDMPC.get_bc_flags

• needs_hdiv – a bool indicating whether the function space V is H(div)-conforming

static assemble_matfree(V, N, Nq, eta, needs_interior_facet, needs_hdiv)[source]

Setup of coefficient-independent quantities in the FDM

Assemble the sparse interval stiffness matrices, tabulate normal derivatives, and get the transfer kernels between the space V and the FDM basis.

Parameters
• V – the FunctionSpace of the problem

• N – the degree of V

• Nq – the quadrature degree for the assembly of interval matrices

• eta – a float penalty parameter for the symmetric interior penalty method

• needs_interior_facet – is the space V non-H^1-conforming?

• needs_hdiv – is the space V H(div)-conforming?

Returns

a 4-tuple with Afdm: a list of lists of interval matrices for each direction, Dfdm: a list with tabulations of the normal derivative for each direction restrict_kernel: a pyop2.Kernel with the tensor product restriction from V onto the FDM space, prolong_kernel: a pyop2.Kernel with the tensor product prolongation from the FDM space onto V

static fdm_setup_cg(Ahat, Bhat)[source]

Setup for the fast diagonalization method for continuous Lagrange elements. Compute the FDM eigenvector basis and the sparsified interval stiffness and mass matrices.

Parameters
• Ahat – GLL stiffness matrix as a numpy.ndarray

• Bhat – GLL mass matrix as a numpy.ndarray

Returns

3-tuple of: Afdm: a list of PETSc.Mats with the sparse interval matrices Sfdm.T * Bhat * Sfdm, and bcs(Sfdm.T * Ahat * Sfdm) for every combination of either natural or strong Dirichlet BCs on each endpoint, Sfdm: the tabulation of Dirichlet eigenfunctions on the GLL nodes, Dfdm: None.

static fdm_setup_ipdg(Ahat, Bhat, eta, gll=False)[source]

Setup for the fast diagonalization method for the IP-DG formulation. Compute the FDM eigenvector basis, its normal derivative and the sparsified interval stiffness and mass matrices.

Parameters
• Ahat – GLL stiffness matrix as a numpy.ndarray

• Bhat – GLL mass matrix as a numpy.array

• eta – penalty coefficient as a float

• gllbool flag indicating whether to keep the eigenvectors in the GLL basis

Returns

3-tuple of: Afdm: a list of PETSc.Mats with the sparse interval matrices Sfdm.T * Bhat * Sfdm, and bcs(Sfdm.T * Ahat * Sfdm) for every combination of either natural or weak Dirichlet BCs on each endpoint, Sfdm: the tabulation of Dirichlet eigenfunctions on the GL or GLL nodes, Dfdm: the tabulation of the normal derivatives of the Dirichlet eigenfunctions.

static get_bc_flags(bcs, J)[source]
static get_interior_facet_maps(V)[source]

Extrude V.interior_facet_node_map and V.ufl_domain().interior_facets.local_facet_dat

Parameters

V – a FunctionSpace

Returns

the 3-tuple of facet_to_nodes_fun: maps interior facets to the nodes of the two cells sharing it, local_facet_data_fun: maps interior facets to the local facet numbering in the two cells sharing it, nfacets: the total number of interior facets owned by this process

static glonum(node_map)[source]

Return an array with the nodes of each topological entity of a certain kind.

Parameters

node_map – a pyop2.Map mapping entities to their nodes, including ghost entities.

Returns

a numpy.ndarray whose rows are the nodes for each cell

static glonum_fun(node_map)[source]

Return a function that maps each topological entity to its nodes and the total number of entities.

Parameters

node_map – a pyop2.Map mapping entities to their nodes, including ghost entities.

Returns

a 2-tuple with the map and the number of cells owned by this process

initialize(pc)[source]

Initialize any state in this preconditioner.

static multiplicity(V)[source]
static numpy_to_petsc(A_numpy, dense_indices, diag=True)[source]
static pull_axis(x, pshape, idir)[source]
static semhat(N, Nq)[source]

Setup for the GLL finite element method on the reference interval

Parameters
• N – polynomial degree of the GLL element

• Nq – quadrature degree (Nq >= 2*N+1 gives exact integrals)

Returns

5-tuple of numpy.ndarray Ahat: GLL(N) stiffness matrix Bhat: GLL(N) mass matrix Jhat: tabulation of the GLL(N) basis on the GL quadrature nodes Dhat: tabulation of the first derivative of the GLL(N) basis on the GL quadrature nodes what: GL quadrature weights

update(pc)[source]

Update any state in this preconditioner.

view(pc, viewer=None)[source]

## firedrake.preconditioners.gtmg module¶

class firedrake.preconditioners.gtmg.GTMGPC[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.

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 any state in this preconditioner.

view(pc, viewer=None)[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.P1PC[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

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 ufl.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 ufl.FiniteElement to coarsen.

class firedrake.preconditioners.low_order.P1SNES[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

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 ufl.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 ufl.FiniteElement to coarsen.

## firedrake.preconditioners.massinv module¶

class firedrake.preconditioners.massinv.MassInvPC[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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)

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.

needs_python_pmat = True

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

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

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".

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: firedrake.preconditioners.base.PCBase, firedrake.preconditioners.patch.PatchBase

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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: firedrake.preconditioners.base.SNESBase, firedrake.preconditioners.patch.PatchBase

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

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

Bases: object

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

## firedrake.preconditioners.pcd module¶

class firedrake.preconditioners.pcd.PCDPC[source]

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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.

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$$, $$M = \mathbb{I}$$ and $$F_p = 1/\mathrm{Re} \\nabla^2 + u\cdot\\nabla$$.

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: firedrake.preconditioners.base.PCBase, firedrake.preconditioners.pmg.PMGBase

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

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: firedrake.preconditioners.base.SNESBase, firedrake.preconditioners.pmg.PMGBase

Create a PC context suitable for PETSc.

Matrix free preconditioners should inherit from this class and implement:

• initialize()

• update()

• apply()

• applyTranspose()

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