firedrake.cython package¶
Submodules¶
firedrake.cython.dmplex module¶

firedrake.cython.dmplex.
boundary_nodes
()¶ Extract boundary nodes from a function space..
 Parameters
V – the function space
sub_domain – a mesh marker selecting the part of the boundary (may be “on_boundary” indicating the entire boundary).
method – how to identify boundary dofs on the reference cell.
 Returns
a numpy array of unique nodes on the boundary of the requested subdomain.

firedrake.cython.dmplex.
cell_facet_labeling
()¶ Computes a labeling for the facet numbers on a particular cell (interior and exterior facet labels with subdomain markers). The ith local facet is represented as:
cell_facets[c, i]
If cell_facets[c, i, 0] is
0
, then the local faceti
is an exterior facet, otherwise if the result is1
it is interior. cell_facets[c, i, 1] returns the subdomain marker for the local facet. Parameters
plex – The DMPlex object representing the mesh topology.
cell_numbering – PETSc.Section describing the global cell numbering
cell_closures – 2D array of ordered cell closures.

firedrake.cython.dmplex.
clear_adjacency_callback
()¶ Clear the callback for DMPlexGetAdjacency.
 Parameters
dm – The DMPlex object

firedrake.cython.dmplex.
closure_ordering
()¶ Apply Fenics local numbering to a cell closure.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
vertex_numbering – Section describing the universal vertex numbering
cell_numbering – Section describing the global cell numbering
entity_per_cell – List of the number of entity points in each dimension
 Vertices := Ordered according to global/universal
vertex numbering
 Edges/faces := Ordered according to lexicographical
ordering of nonincident vertices

firedrake.cython.dmplex.
create_section
()¶ Create the section describing a global numbering.
 Parameters
mesh – The mesh.
nodes_per_entity – Number of nodes on each type of topological entity of the mesh. Or, if the mesh is extruded, the number of nodes on, and on top of, each topological entity in the base mesh.
on_base – If True, assume extruded space is actually Foo x Real.
 Returns
A PETSc Section providing the number of dofs, and offset of each dof, on each mesh point.

firedrake.cython.dmplex.
exchange_cell_orientations
()¶ Halo exchange of cell orientations.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
section – Section describing the cell numbering
orientations – Cell orientations to exchange, values in the halo will be overwritten.

firedrake.cython.dmplex.
facet_numbering
()¶ Compute the parent cell(s) and the local facet number within each parent cell for each given facet.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
kind – String indicating the facet kind (interior or exterior)
facets – Array of input facets
cell_numbering – Section describing the global cell numbering
cell_closures – 2D array of ordered cell closures

firedrake.cython.dmplex.
get_cell_markers
()¶ Get the cells marked by a given subdomain_id.
 Parameters
plex – The DM for the mesh topology
cell_numbering – Section mapping plex cell points to firedrake cell indices.
subdomain_id – The subdomain_id to look for.
 Raises
ValueError – if the subdomain_id is not valid.
 Returns
A numpy array (possibly empty) of the cell ids.

firedrake.cython.dmplex.
get_cell_nodes
()¶ Builds the DoF mapping.
 Parameters
mesh – The mesh
global_numbering – Section describing the global DoF numbering
entity_dofs – FInAT element entity dofs for the cell
offset – offsets for each entity dof walking up a column.
Preconditions: This function assumes that cell_closures contains mesh entities ordered by dimension, i.e. vertices first, then edges, faces, and finally the cell. For quadrilateral meshes, edges corresponding to dimension (0, 1) in the FInAT element must precede edges corresponding to dimension (1, 0) in the FInAT element.

firedrake.cython.dmplex.
get_cell_remote_ranks
()¶ Returns an array assigning the rank of the owner to each locally visible cell. Locally owned cells have 1 assigned to them.
 Parameters
plex – The DMPlex object encapsulating the mesh topology

firedrake.cython.dmplex.
get_entity_classes
()¶ Builds PyOP2 entity class offsets for all entity levels.
 Parameters
plex – The DMPlex object encapsulating the mesh topology

firedrake.cython.dmplex.
get_facet_markers
()¶ Get an array of facet labels in the mesh.
 Parameters
dm – The DM that contains labels.
facets – The array of facet points.
 Returns
a numpy array of facet ids (or None if all facets had the default marker).

firedrake.cython.dmplex.
get_facet_nodes
()¶ Build to DoF mapping from facets.
 Parameters
mesh – The mesh.
cell_nodes – numpy array mapping from cells to function space nodes.
label – which set of facets to ask for (interior_facets or exterior_facets).
offset – optional offset (extruded only).
 Returns
numpy array mapping from facets to nodes in the closure of the support of that facet.

firedrake.cython.dmplex.
get_facet_ordering
()¶ Builds a list of all facets ordered according to the given numbering.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
facet_numbering – A Section describing the global facet numbering

firedrake.cython.dmplex.
get_facets_by_class
()¶ Builds a list of all facets ordered according to PyOP2 entity classes and computes the respective class offsets.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
ordering – An array giving the global traversal order of facets
label – Label string that marks the facets to order

firedrake.cython.dmplex.
halo_begin
()¶ Begin a halo exchange.
 Parameters
sf – the PETSc SF to use for exchanges
dat – the
pyop2.Dat
to perform the exchange ondtype – an MPI datatype describing the unit of data
reverse – should a reverse (localtoglobal) exchange be performed.
Forward exchanges are implemented using
PetscSFBcastBegin
, reverse exchanges withPetscSFReduceBegin
.

firedrake.cython.dmplex.
halo_end
()¶ End a halo exchange.
 Parameters
sf – the PETSc SF to use for exchanges
dat – the
pyop2.Dat
to perform the exchange ondtype – an MPI datatype describing the unit of data
reverse – should a reverse (localtoglobal) exchange be performed.
Forward exchanges are implemented using
PetscSFBcastEnd
, reverse exchanges withPetscSFReduceEnd
.

firedrake.cython.dmplex.
label_facets
()¶ Add labels to facets in the the plex
Facets on the boundary are marked with “exterior_facets” while all others are marked with “interior_facets”.
 Parameters
label_boundary – if False, don’t label the boundary faces (they must have already been labelled).

firedrake.cython.dmplex.
make_global_numbering
()¶ Build an array of global numbers for local dofs
 Parameters
lsec – Section describing local dof layout and numbers.
gsec – Section describing global dof layout and numbers.

firedrake.cython.dmplex.
mark_entity_classes
()¶ Mark all points in a given Plex according to the PyOP2 entity classes:
core : owned and not in send halo owned : owned and in send halo ghost : in halo
 Parameters
plex – The DMPlex object encapsulating the mesh topology

firedrake.cython.dmplex.
orientations_facet2cell
()¶ Converts local quadrilateral facet orientations into global quadrilateral cell orientations.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
vertex_numbering – Section describing the universal vertex numbering
facet_orientations – Facet orientations (edge directions) relative to the local DMPlex ordering.
cell_numbering – Section describing the cell numbering

firedrake.cython.dmplex.
plex_renumbering
()¶ Build a global node renumbering as a permutation of Plex points.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
entity_classes – Array of entity class offsets for each dimension.
reordering – A reordering from reordered to original plex points used to provide the traversal order of the cells (i.e. the inverse of the ordering obtained from DMPlexGetOrdering). Optional, if not provided (or
None
), no reordering is applied and the plex is traversed in original order.
The node permutation is derived from a depthfirst traversal of the Plex graph over each entity class in turn. The returned IS is the Plex > PyOP2 permutation.

firedrake.cython.dmplex.
prune_sf
()¶ Prune an SF of roots referencing the local rank
 Parameters
sf – The PETSc SF to prune.

firedrake.cython.dmplex.
quadrilateral_closure_ordering
()¶ Cellwise orders mesh entities according to the given cell orientations.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
vertex_numbering – Section describing the universal vertex numbering
cell_numbering – Section describing the cell numbering
cell_orientations – Specifies the starting vertex for each cell, and the order of traversal (CCW or CW).

firedrake.cython.dmplex.
quadrilateral_facet_orientations
()¶ Returns globally synchronised facet orientations (edge directions) incident to locally owned quadrilateral cells.
 Parameters
plex – The DMPlex object encapsulating the mesh topology
vertex_numbering – Section describing the universal vertex numbering
cell_ranks – MPI rank of the owner of each (visible) nonowned cell, or 1 for (locally) owned cell.

firedrake.cython.dmplex.
reordered_coords
()¶ Return coordinates for the plex, reordered according to the global numbering permutation for the coordinate function space.
Shape is a tuple of (plex.numVertices(), geometric_dim).

firedrake.cython.dmplex.
set_adjacency_callback
()¶ Set the callback for DMPlexGetAdjacency.
 Parameters
dm – The DMPlex object.
This is used during DMPlexDistributeOverlap to determine where to grow the halos.

firedrake.cython.dmplex.
validate_mesh
()¶ Perform some validation of the input mesh.
 Parameters
plex – The DMPlex object encapsulating the mesh topology.
firedrake.cython.extrusion_numbering module¶
Computation dof numberings for extruded meshes¶
On meshes with a constant number of cell layers (i.e. each column contains the same number of cells), it is possible to compute all the correct numberings by just lying to DMPlex about how many degrees of freedom there are on the base topological entities.
This ceases to be true as soon as we permit variable numbers of cells in each column, since now, although the number of degrees of freedom on a cell does not change from column to column, the number that are stacked up on each topological entity does change.
This module implements the necessary chicanery to deal with it.
Computation of topological layer extents¶
First, a picture.
Consider a onedimensional mesh:
x0x1x2x
Extruded to form the following twodimensional mesh:
xx
 
 
2  
 
xxxx
  
  
1   
  
xxx
 
 
0  
 
xx
This is constructed by providing the number of cells in each column as well as the starting cell layer:
[[0, 2],
[1, 1],
[2, 1]]
We need to promote this cell layering to layering for all topological entities. Our solution to “interior” facets that only have one side is to require that they are geometrically zero sized, and then guarantee that we never iterate over them. We therefore need to keep track of two bits of information, the layer extent for allocation purposes and also the layer extent for iteration purposes.
We compute both by iterating over the cells and transferring cell layers to points in the closure of each cell. Allocation bounds use minmax on the cell bounds, iteration bounds use maxmin.
To simplify some things, we require that the resulting mesh is not topologically disconnected anywhere. Offset cells must, at least, share a vertex with some other cell.
Computation of function space allocation size¶
With the layer extents computed, we need to compute the dof allocation. For this, we need the number of degrees of freedom on the base topological entity, and above it in each cell:
xx
 o 
o o o
o o o
 o 
ooo
This element has one degree of freedom on each base vertex and cell, two degrees of freedom “above” each vertex, and four above each cell. To compute the number of degrees of freedom on the column of topological entities we sum the number on the entity, multiplied by the number of layers with the number above, multiplied by the number of layers minus one (due to the fencepost error difference). This number of layers naturally changes from entity to entity, and so we can’t compute this up front, but must do it point by point, constructing the PETSc Section as we go.
Computation of function space maps¶
Now we need the maps from topological entities (cells and facets) to the function space nodes they can see. The allocation offsets that the numbering section gives us are wrong, because when we have a step in the column height, the offset will be wrong if we’re looking from the higher cell. Consider a vertex discretisation on the previous mesh, with a numbering:
810
 
 
 
 
2579
  
  
  
  
146
 
 
 
 
03
The cell node map we get by just looking at allocation offsets is:
[[0, 1, 3, 4],
[3, 4, 6, 7],
[6, 7, 9, 10]]
note how the second and third cells have the wrong value for their “left” vertices. Instead, we need to shift the numbering we obtain from the allocation offset by the number of entities we’re skipping over, to result in:
[[0, 1, 3, 4],
[4, 5, 6, 7],
[7, 8, 9, 10]]
Now, when we iterate over cells, we ensure that we access the correct dofs. The same trick needs to be applied to facet maps too.
Computation of boundary nodes¶
For the top and bottom boundary nodes, we walk over the cells at, respectively, the top and bottom of the column and pull out those nodes whose entity height matches the appropriate cell height. As an example:
810
 
 
 
 
2579
  
  
  
  
146
 
 
 
 
03
The bottom boundary nodes are:
[0, 3, 4, 6, 7, 9]
whereas the top are:
[2, 5, 7, 8, 10]
For these strange “interior” facets, we first walk over the cells, picking up the dofs in the closure of the base (ceiling) of the cell, then we walk over facets, picking up all the dofs in the closure of facets that are exposed (there may be more than one of these in the cell column). We don’t have to worry about any lowerdimensional entities, because if a codim 2 or greater entity is exposed in a column, then the codim 1 entity in its star is also exposed.
For the side boundary nodes, we can make a simplification: we know that the facet heights are always the same as the cell column heights (because there is only one cell in the support of the facet). Hence we just walk over the boundary facets of the base mesh, extract out the nodes on that facet on the bottom cell and walk up the column. This is guaranteed to pick up all the nodes in the closure of the facet column.

firedrake.cython.extrusion_numbering.
entity_layers
()¶ Compute the layers for a given entity type.
 Parameters
mesh – the extruded mesh to compute layers for.
height – the height of the entity to consider (in the DMPlex sense). e.g. 0 > cells, 1 > facets, etc…
label – optional label to select some subset of the points of the given height (may be None meaning select all points).
 Returns
a numpy array of shape (num_entities, 2) providing the layer extents for iteration on the requested entities.

firedrake.cython.extrusion_numbering.
layer_extents
()¶ Compute the extents (start and stop layers) for an extruded mesh.
 Parameters
dm – The DMPlex.
cell_numbering – The cell numbering (plex points to Firedrake points).
cell_extents – The cell layers.
 Returns
a numpy array of shape (npoints, 4) where npoints is the number of mesh points in the base mesh.
npoints[p, 0:2]
gives the start and stop layers for allocation for mesh pointp
(in plex ordering), whilenpoints[p, 2:4]
gives the start and stop layers for iteration over mesh pointp
(in plex ordering).
Warning
The indexing of this array uses DMPlex point ordering, not Firedrake ordering. So you always need to iterate over plex points and translate to Firedrake numbers if necessary.

firedrake.cython.extrusion_numbering.
node_classes
()¶ Compute the node classes for a given extruded mesh.
 Parameters
mesh – the extruded mesh.
nodes_per_entity – Number of nodes on, and on top of, each type of topological entity on the base mesh for a single cell layer. Multiplying up by the number of layers happens in this function.
 Returns
A numpy array of shape (3, ) giving the set entity sizes for the given nodes per entity.

firedrake.cython.extrusion_numbering.
top_bottom_boundary_nodes
()¶ Extract top or bottom boundary nodes from an extruded function space.
 Parameters
mesh – The extruded mesh.
cell_node_list – The map from cells to nodes.
masks – masks for dofs in the closure of the facets of the cell. First the vertical facets, then the horizontal facets (bottom then top).
offsets – Offsets to apply walking up the column.
kind – Whether we should select the bottom, or the top, nodes.
 Returns
a numpy array of unique indices of nodes on the bottom or top of the mesh.
firedrake.cython.hdf5interface module¶

firedrake.cython.hdf5interface.
get_h5py_file
()¶ Attempt to convert PETSc viewer file handle to h5py File.
 Parameters
vwr – The PETSc Viewer (must have type HDF5).
Warning
For this to work, h5py and PETSc must both have been compiled against the same HDF5 library (otherwise the file handles are not interchangeable). This is the likeliest reason for failure when attempting the conversion.
firedrake.cython.mgimpl module¶

firedrake.cython.mgimpl.
coarse_to_fine_cells
()¶ Return a map from (renumbered) cells in a coarse mesh to those in a refined fine mesh.
 Parameters
mc – the coarse mesh to create the map from.
mf – the fine mesh to map to.
clgmaps – coarse lgmaps (nonoverlapped and overlapped)
flgmaps – fine lgmaps (nonoverlapped and overlapped)
 Returns
Two arrays, one mapping coarse to fine cells, the second fine to coarse cells.

firedrake.cython.mgimpl.
coarse_to_fine_nodes
()¶

firedrake.cython.mgimpl.
create_lgmap
()¶ Create a local to global map for all points in the given DM.
 Parameters
dm – The DM to create the map for.
Returns a petsc4py LGMap.

firedrake.cython.mgimpl.
filter_exterior_facet_labels
()¶ Remove exterior facet labels from things that aren’t facets.
When refining, every point “underneath” the refined entity receives its label. But we want the facet label to really only apply to facets, so clear the labels from everything else.

firedrake.cython.mgimpl.
fine_to_coarse_nodes
()¶

firedrake.cython.mgimpl.
get_entity_renumbering
()¶ Given a section numbering a type of topological entity, return the renumberings from original plex numbers to new firedrake numbers (and vice versa)
 Parameters
plex – The DMPlex object
section – The Section defining the renumbering
entity_type – The type of entity (either
"cell"
or"vertex"
)
firedrake.cython.patchimpl module¶

firedrake.cython.patchimpl.
set_patch_jacobian
()¶

firedrake.cython.patchimpl.
set_patch_residual
()¶
firedrake.cython.spatialindex module¶

class
firedrake.cython.spatialindex.
SpatialIndex
¶ Bases:
object
Python class for holding a native spatial index object.

ctypes
¶ Returns a ctypes pointer to the native spatial index.


firedrake.cython.spatialindex.
bounding_boxes
()¶ Given a spatial index and a point, return the bounding boxes the point is in.
 Parameters
sidx – the SpatialIndex
x – the point
 Returns
a numpy array of candidate bounding boxes.

firedrake.cython.spatialindex.
from_regions
()¶ Builds a spatial index from a set of maximum bounding regions (MBRs).
regions_lo and regions_hi must have the same size. regions_lo[i] and regions_hi[i] contain the coordinates of the diagonally opposite lower and higher corners of the ith MBR, respectively.
firedrake.cython.supermeshimpl module¶

firedrake.cython.supermeshimpl.
assemble_mixed_mass_matrix
()¶

firedrake.cython.supermeshimpl.
intersection_finder
()¶