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.cython package¶
Submodules¶
firedrake.cython.dmcommon module¶
- class firedrake.cython.dmcommon.DistributedMeshOverlapType(*values)¶
Bases:
EnumHow should the mesh overlap be grown for distributed meshes?
Possible options are:
Defaults to
FACET.- FACET = 1¶
- NONE = 4¶
- RIDGE = 2¶
- VERTEX = 3¶
- firedrake.cython.dmcommon.cell_facet_labeling(plex, cell_numbering, cell_closures)¶
Computes a labeling for the facet numbers on a particular cell (interior and exterior facet labels with subdomain markers). The i-th local facet is represented as:
cell_facets[c, i]
If \(cell_facets[c, i, 0]\) is
0, then the local facetiis an exterior facet, otherwise if the result is1it 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.dmcommon.clear_adjacency_callback(dm)¶
Clear the callback for DMPlexGetAdjacency.
- Parameters:
dm – The DMPlex object
- firedrake.cython.dmcommon.closure_ordering(mesh, closure_data_plex)¶
Apply FEniCS local numbering to a cell closure.
The reordering is achieved by ordering vertices according to their global number and by ordering edges and facets according to a lexicographical order of the non-incident vertices.
- Parameters:
mesh (MeshTopology) – The mesh providing the closures.
closure_data_plex (numpy.ndarray) – Array storing cell closure information.
- Returns:
Array storing the reordered cell closures.
- Return type:
Notes
The returned closure array stores entities in the preferred FIAT order (vertices, edges, faces, cells) which differs from the input DMPlex order (cells, faces, edges, vertices).
- firedrake.cython.dmcommon.complete_facet_labels(dm)¶
Transfer label values from the facet labels to everything in the closure of the facets.
- firedrake.cython.dmcommon.compute_dm_renumbering(mesh, new_to_old_cell_numbering_is=None)¶
Return a renumbering of DM points that maximises locality.
- Parameters:
dm – The DMPlex object encapsulating the mesh topology
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.boundary_set – A set of boundary subdomains, where a DirichletBC is to be applied. This is None if working with a FunctionSpace object, and non-empty if working with a RestrictedFunctionSpace object. If one is provided, this will move all core or owned boundary points to the end of the core+owned block.
The node permutation is derived from a depth-first traversal of the Plex graph over each entity class in turn. The returned IS is the Plex -> PyOP2 permutation. A tuple indicating the start and end of the core/owned constrained block is returned, for use in create_section.
- firedrake.cython.dmcommon.compute_point_cone_global_sizes(dm)¶
Compute the total number of DMPlex points and the global sum of cone sizes for dm.
- Parameters:
dm – The dm.
- Returns:
A list of global number of points and global sum of cone sizes.
- firedrake.cython.dmcommon.count_labelled_points(dm, name, start, end)¶
Return the number of points in the chart [start, end) that are marked by the given label.
Note
This destroys any index on the label.
- Parameters:
dm – The DM containing the label
name – The label name.
start – The smallest point to consider.
end – One past the largest point to consider.
- firedrake.cython.dmcommon.create_halo_exchange_sf(dm)¶
Create the halo exchange sf.
- Parameters:
dm (PETSc.DM) – The section dm.
- Returns:
The halo exchange sf.
- Return type:
PETSc.SF
Notes
The output sf is to update all ghost DoFs including constrained ones if any.
- firedrake.cython.dmcommon.entity_numbering(selected_points, new_to_old_numbering, comm)¶
Return a PETSc section representing the renumbering of a set of points.
The section maps from ‘plex’ indices (i.e. point numbers as seen by DMPlex) to entity-wise indices in the range [0, selected_points.size). This mapping is achieved by calling ‘section.getOffset(plex_point)’.
- Parameters:
selected_points – The ‘plex’ indices that we wish to include in the numbering.
new_to_old_renumbering – The mesh numbering.
- Returns:
A PETSc section encoding the numbering.
- Return type:
PETSc.Section
- firedrake.cython.dmcommon.entity_orientations(mesh, cell_closure)¶
Compute entity orientations.
- Parameters:
mesh – The
MeshTopologyobject encapsulating the mesh topologycell_closure – The two-dimensional array, each row of which contains the closure of the associated cell
- Returns:
A 2D array of the same shape as cell_closure, each row of which contains orientations of the entities in the closure of the associated cell
See
entity_orientations()for details on the returned array.
- firedrake.cython.dmcommon.exchange_cell_orientations(mesh, section, 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.dmcommon.extrude_mesh(base_dm, nlayers, thickness, periodic)¶
- firedrake.cython.dmcommon.extrude_point_numbering(dm, base_dm, base_renumbering, nlayers, periodic, extr2base, extr2off)¶
Consider
x-----x-----x 2 0 3 1 4 (1 0 2 3 4) going to
When we extrude it will have the following numbering:
5--2--8-11-14 | | | 4 1 7 10 13 | | | 3--0--6--9-12
whilst the DMPlex will think it is:
3--9--5-11--7 | | | 12 0 13 1 14 | | | 2--8--4-10--6
(To see this recall that points are numbered cells then vertices then edges.)
- firedrake.cython.dmcommon.extruded_plex_strata_order(dimension)¶
- firedrake.cython.dmcommon.facet_closure_nodes(V, sub_domain)¶
Extract nodes in the closure of facets with a given marker.
This works fine for interior as well as exterior facets.
- Parameters:
V – the function space
sub_domain – a tuple of mesh markers selecting the facets, or the magic string “on_boundary” indicating the entire boundary.
- Returns:
a numpy array of unique nodes in the closure of facets with the given marker.
- firedrake.cython.dmcommon.facets_with_label(mesh, label_name)¶
TODO, similar to get_facets_by_class.
Note that the facet indices returned by this function are not renumbered.
- firedrake.cython.dmcommon.filter_is(is_, start, end)¶
- firedrake.cython.dmcommon.get_boundary_set_points(dm, boundary_set, extruded)¶
Return the points in the DM that match the boundary set.
- firedrake.cython.dmcommon.get_cell_remote_ranks(plex)¶
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.dmcommon.get_dm_cell_types(dm)¶
Return all cell types in the mesh.
- Parameters:
dm (PETSc.DM) – The parent dm.
- Returns:
Tuple of all cell types in the mesh.
- Return type:
- firedrake.cython.dmcommon.get_extruded_base_point_map(base_dm, dm, nlayers, periodic)¶
# 2–0–3–1–4 # # to # # 6-15–9-18-12 # | | | # 20 1 22 3 24 # | | | # 5-14–8-17-11 # | | | # 19 0 21 2 23 # | | | # 4-13–7-16-10
- firedrake.cython.dmcommon.get_facet_ordering(plex, facet_numbering)¶
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.dmcommon.get_preallocation(preallocator, nrow)¶
- firedrake.cython.dmcommon.get_topological_dimension(dm)¶
Get the topological dimension of a DMPlex or DMSwarm. Assumes that a DMSwarm represents a mesh of vertices (tdim 0).
- Parameters:
dm – A DMPlex or DMSwarm.
- Returns:
For a DMPlex
dm.getDimension(), for a DMSwarm0.
- firedrake.cython.dmcommon.intersect_is(is1, is2)¶
Return the intersection of two PETSc ISs.
- firedrake.cython.dmcommon.is_on_comm(is_, comm, *, copy=True)¶
- firedrake.cython.dmcommon.label_facets(plex)¶
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”.
- firedrake.cython.dmcommon.local_facet_number(mesh, facet_type)¶
- firedrake.cython.dmcommon.make_node_to_node_map(pt_to_pt_map, from_sec, to_sec, block_size)¶
- firedrake.cython.dmcommon.mark_owned_points(dm)¶
Mark points in a DM as being either owned or ghost (owned by another process).
The points are marked using the label
firedrake_is_ghost, with1indicating ghost and0owned.Point ownership is determined by inspecting the point star forest of the DM.
- Parameters:
dm – The DM object encapsulating the mesh topology.
- firedrake.cython.dmcommon.mark_points_with_function_array(plex, section, height, array, dmlabel, label_value)¶
Marks points in a DMLabel using an indicator function array.
- Parameters:
plex – DMPlex representing the mesh topology
section – Section describing the function space DoF layout and order
height – Height of marked points (0 for cells, 1 for facets)
array – Array representing the indicator function whose layout is defined by plex, section, and height
dmlabel – DMLabel that records marked entities
label_value – Value used in dmlabel
- firedrake.cython.dmcommon.orientations_facet2cell(mesh, cell_ranks, facet_orientations)¶
Converts local quadrilateral facet orientations into global quadrilateral cell orientations.
- Parameters:
plex – The DMPlex object encapsulating the mesh topology
facet_orientations – Facet orientations (edge directions) relative to the local DMPlex ordering.
cell_numbering – Section describing the cell numbering
- firedrake.cython.dmcommon.partition_renumbering(dm, serial_new_to_old_renumbering)¶
Partition a serial point renumbering into owned and ghost points.
- firedrake.cython.dmcommon.quadrilateral_closure_ordering(mesh, cell_orientations)¶
Cellwise orders mesh entities according to the given cell orientations.
- Parameters:
plex – The DMPlex object encapsulating the mesh topology
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.dmcommon.quadrilateral_facet_orientations(plex, vertex_numbering, cell_ranks)¶
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) non-owned cell, or -1 for (locally) owned cell.
- firedrake.cython.dmcommon.reorder_closure_fiat_hex(plex_closures)¶
Reorder DMPlex closures to match FIAT entity numbering for hexes.
- Parameters:
plex_closures – 2D array of cell closures in DMPlex canonical ordering.
- Returns:
2D array of cell closures using the FIAT canonical ordering. Note that things are not renumbered: we are still using DMPlex entity numbering here. Only the order is changing.
- Return type:
- firedrake.cython.dmcommon.reordered_coords(dm, global_numbering, shape, reference_coord=False)¶
Return coordinates for the dm, reordered according to the global numbering permutation for the coordinate function space.
Shape is a tuple of (mesh.num_vertices(), geometric_dim).
- firedrake.cython.dmcommon.restrict_dm_renumbering(orig_renumbering, dm, nowned, boundary_set, extruded)¶
‘Restrict’ a renumbering of DM points by moving constrained points to the end.
- firedrake.cython.dmcommon.restrict_section(section, dm, nowned, boundary_set, extruded)¶
‘Restrict’ a section by moving constrained DoFs to the end.
- firedrake.cython.dmcommon.section_offsets(section, selected_points, *, sort=False)¶
Return the section offsets for a given set of points.
- firedrake.cython.dmcommon.section_permute(section, perm)¶
- firedrake.cython.dmcommon.set_adjacency_callback(dm, overlap_type)¶
Set the callback for DMPlexGetAdjacency.
- Parameters:
dm (PETSc.DM) – The DMPlex object.
overlap_type (DistributedMeshOverlapType) – \(DistributedMeshOverlapType.FACET\) or \(DistributedMeshOverlapType.RIDGE\).
Notes
This is used during DMPlexDistributeOverlap to determine where to grow the halos.
- firedrake.cython.dmcommon.submesh_correct_entity_classes(dm, subdm, ownership_transfer_sf)¶
Correct pyop2 entity classes.
- Parameters:
dm (PETSc.DM) – The original DM.
subdm (PETSc.DM) – The subdm.
ownership_transfer_sf (PETSc.SF) – The ownership transfer sf.
- firedrake.cython.dmcommon.submesh_create(dm, subdim, label_name, subdomain_id, ignore_label_halo, comm=None)¶
Create submesh.
- Parameters:
dm (PETSc.DM) – DMPlex representing the mesh topology
subdim (int | None) – Topological dimension of the submesh, or None to be inferred from other kwargs. See
Submesh().label_name (str | None) – Name of the label, or \(None\) to select every cell
subdomain_id (int | Sequence | None) – Values in the label, unused if
label_nameis \(None\)ignore_label_halo (bool) – If labeled points in the halo are ignored.
comm (PETSc.Comm | None) – An optional sub-communicator to define the submesh.
- firedrake.cython.dmcommon.submesh_create_cell_closure(subdm, dm, subcell_numbering, cell_numbering, cell_closure, entity_per_subcell)¶
Inherit cell_closure from parent.
- Parameters:
subdm (PETSc.DM) – The subdm.
dm (PETSc.DM) – The parent dm.
subcell_numbering (PETSc.Section) – The cell_numbering of the submesh.
cell_numbering (PETSc.Section) – The cell_numbering of the parent mesh.
cell_closure (numpy.ndarray) – The cell_closure of the parent mesh.
entity_per_subcell (numpy.ndarray) – List of the number of entity points in each dimension on subcell.
- firedrake.cython.dmcommon.submesh_update_facet_labels(dm, subdm)¶
Update facet labels of subdm taking the new exterior facet points into account.
- Parameters:
dm (PETSc.DM) – The parent dm.
subdm (PETSc.DM) – The subdm.
Notes
This function marks the new exterior facets with current max label value + 1 in “Face Sets”.
- firedrake.cython.dmcommon.transform_vec_from_firedrake_to_petsc(dm, finat_element, firedrake_sec, firedrake_vec, petsc_sec, petsc_vec, use_transitive_closure_dg=False)¶
Transform Firedrake vec to PETSc vec.
- Parameters:
dm (PETSc.DM) – \(PETSc.DM\).
finat_element (finat.finiteelementbase.FiniteElementBase) – FInAT element.
firedrake_sec (PETSc.Section) – \(PETSc.Section\) representing the Firedrake DoF layout.
firedrake_vec (PETSc.Vec) – \(PETSc.Vec\) representing the Firedrake DoF vector.
petsc_sec (PETSc.Section) – \(PETSc.Section\) representing the PETSc DoF layout.
petsc_vec (PETSc.Vec) – \(PETSc.Vec\) representing the PETSc DoF vector.
use_transitive_closure_dg (bool) – Whether to use PETSc DG element whose DoFs are ordered according to the transitive closure of the cell.
- firedrake.cython.dmcommon.validate_mesh(dm)¶
Perform some validation of the input mesh.
- Parameters:
dm – The DM object encapsulating the mesh topology.
firedrake.cython.hdf5interface module¶
- firedrake.cython.hdf5interface.get_h5py_file(vwr)¶
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(coarse_mesh, fine_mesh, fine_to_coarse_points)¶
Build the cell maps between two meshes from the refinement of their points.
- Parameters:
coarse_mesh (MeshGeometry) – The coarse and fine meshes.
fine_mesh (MeshGeometry) – The coarse and fine meshes.
fine_to_coarse_points (numpy.ndarray) – For each point of
fine_mesh.topology_dm, the point ofcoarse_mesh.topology_dmthat it was refined from, or -1 when no corresponding coarse point exists. This map uses DMPlex point numbering.
- Returns:
coarse_to_fine_cells (numpy.ndarray) – For each owned coarse cell, the owned fine cells obtained from it, in increasing order, using Firedrake cell numbering. Every row is as wide as the busiest coarse cell on any process. After adaptive refinement, a coarse cell that was not refined has fewer children, so its row is right-padded with -1. Here -1 is only padding.
fine_to_coarse_cells (numpy.ndarray) – For each owned fine cell, the owned coarse cell from which it was obtained, using Firedrake cell numbering. Here -1 marks a fine cell that has no parent in the coarse mesh. This happens in a \(SubmeshHierarchy\) that contains interior facets. A fine facet inside a coarse cell comes from that volume cell, which is not a cell of the coarse submesh.
- firedrake.cython.mgimpl.coarse_to_fine_nodes(Vc, Vf, coarse_to_fine_cells)¶
- firedrake.cython.mgimpl.compose_points(outer, inner)¶
Compose two point maps.
- Parameters:
outer (numpy.ndarray) – The map to apply second.
inner (numpy.ndarray) – The map to apply first. Negative or out-of-range entries mean that the corresponding point has no parent.
- Returns:
outer[inner], with -1 where the input or composed map has no corresponding point.- Return type:
- firedrake.cython.mgimpl.create_lgmap(dm)¶
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_labels(dm, keep, *label_names)¶
Remove labels from points that are not in keep. :arg dm: DM object with labels. :arg keep: subsection of the DMs chart on which to retain label values. :arg label_names: names of labels (strings) to clear. When refining, every point “underneath” the refined entity receives its label. But we typically have labels applied only to entities of a given stratum height (and rely on that elsewhere), so clear the labels from everything else.
- firedrake.cython.mgimpl.fine_to_coarse_nodes(Vf, Vc, fine_to_coarse_cells)¶
- firedrake.cython.mgimpl.get_entity_renumbering(plex, numbering, entity_type)¶
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
numbering – The renumbering
entity_type – The type of entity (either
"cell"or"vertex")
- firedrake.cython.mgimpl.overlapped_fine_to_coarse_points(coarse_mesh, fine_mesh, fine_to_coarse_points, coarse_lgmap, fine_lgmap)¶
Renumber a refinement of unoverlapped DMPlexes onto the DMPlexes of two meshes.
A hierarchy refines unoverlapped DMPlexes and adds overlap only when it builds each mesh. The saved transform relates the points of the unoverlapped DMPlexes, so this function carries both ends of the relation over to the meshes through the global point numbers.
- Parameters:
coarse_mesh (MeshGeometry) – The coarse mesh, and the mesh built from the refinement of its unoverlapped DMPlex.
fine_mesh (MeshGeometry) – The coarse mesh, and the mesh built from the refinement of its unoverlapped DMPlex.
fine_to_coarse_points (numpy.ndarray) – For each point of the unoverlapped fine DMPlex, the point of the unoverlapped coarse DMPlex that produced it, as given by \(transform_source_points\). This is a DMPlex point map; it does not use Firedrake cell numbering.
coarse_lgmap (PETSc.LGMap or None) – The point local-to-global maps of the unoverlapped coarse and fine DMPlexes, as given by \(create_lgmap\). These maps are
Nonewhen the hierarchy has no overlap or when it is serial.fine_lgmap (PETSc.LGMap or None) – The point local-to-global maps of the unoverlapped coarse and fine DMPlexes, as given by \(create_lgmap\). These maps are
Nonewhen the hierarchy has no overlap or when it is serial.
- Returns:
For each point of
fine_mesh.topology_dm, the point ofcoarse_mesh.topology_dmthat it was refined from, or -1 when the corresponding parent point is not present in the coarse local DMPlex. The result remains in DMPlex point numbering; \(coarse_to_fine_cells\) composes it with the Firedrake cell numberings when it builds cell maps.- Return type:
- firedrake.cython.mgimpl.transform_source_points(dm)¶
Find the point that produced each point of a transformed DMPlex.
- Parameters:
dm (PETSc.DM) – A DMPlex made by a transform, such as a refinement, of a DMPlex on which
setSaveTransformwas called first.- Returns:
For each point of
dm, the point of the original DMPlex that produced it.- Return type:
firedrake.cython.patchimpl module¶
- firedrake.cython.patchimpl.pcpatch_set_compute_operator(patch, function, ctx)¶
- firedrake.cython.patchimpl.pcpatch_set_compute_operator_exterior_facets(patch, function, ctx)¶
- firedrake.cython.patchimpl.pcpatch_set_compute_operator_interior_facets(patch, function, ctx)¶
- firedrake.cython.patchimpl.snespatch_set_compute_function(patch, function, ctx)¶
- firedrake.cython.patchimpl.snespatch_set_compute_operator(patch, function, ctx)¶
firedrake.cython.rtree module¶
- class firedrake.cython.rtree.RTree¶
Bases:
objectPython class for holding an Rtree.
- ctypes¶
Returns a ctypes pointer to the rtree.
- firedrake.cython.rtree.bounding_boxes_at_level(rtree, level, dim)¶
Return all bounding boxes at the specified level of the Rtree.
- firedrake.cython.rtree.build_from_aabb(coords_min, coords_max, ids=None)¶
Builds rtree from two arrays of shape (n, dim) containing the coordinates of the lower and upper corners of n axis-aligned bounding boxes, and an optional array of shape (n,) containing integer ids for each box.
- Parameters:
coords_min (numpy.ndarray) – Lower corner coordinates of the bounding boxes, with shape \((n, dim)\).
coords_max (numpy.ndarray) – Upper corner coordinates of the bounding boxes, with shape \((n, dim)\).
ids (numpy.ndarray) – Optional integer ids for each box, with shape \((n,)\). If not provided, defaults to \(0, 1, ..., n-1\).
- Returns:
An RTree object containing the Rtree.
- Return type:
- firedrake.cython.rtree.discover_remote_roots(rtree, points, comm)¶
Build the remote array for a candidate star forest. Collective.
This implements the non-blocking consensus algorithm from Hoefler et al. ‘Scalable communication protocols for dynamic sparse data exchange’.
This routine duplicates the given comm since we send tag-0 messages and listen with MPI_IProbe(MPI_ANY_SOURCE).
- Parameters:
rtree (RTree) – The distributed Rtree built by
build_from_aabb()with rank numbers as leaf ids.points (numpy.ndarray) – Local point coordinates in a
float64array of shape(n_points, gdim).comm (mpi4py.MPI.Comm) – The MPI communicator.
- Returns:
remote – For every local candidate leaf, the MPI rank and local index of its remote root point in an
IntTypearray of shape(nleaves, 2).- Return type:
- firedrake.cython.rtree.tree_depth(rtree)¶
Return the depth of the Rtree.
firedrake.cython.supermeshimpl module¶
- firedrake.cython.supermeshimpl.assemble_mixed_mass_matrix(V_A, V_B, candidates, node_locations_A, node_locations_B, M_SS, lib, mat)¶
- firedrake.cython.supermeshimpl.intersection_finder(mesh_A, mesh_B)¶
