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.mg package

Submodules

firedrake.mg.embedded module

class firedrake.mg.embedded.TransferManager(*, native_transfers=None, use_averaging=True, mat_type='matfree')

Bases: object

Manage transfers between levels in a multigrid hierarchy.

Parameters:

• native_transfers (dict) – A mapping from UFL elements to natively supported transfer operators. Each value must be a three-tuple containing the prolong, restrict, and inject operators.

• use_averaging (bool) – Whether to use averaging to approximate the projection out of an embedded DG space. If false, perform a global L2 projection.

• mat_type (str) – The matrix assembly type for prolongation and restriction.

class Cache(ufl_element, value_shape)

Bases: object

A caching object for work vectors and matrices.

Parameters:

element – The element to use for the caching.

DG_inv_mass(DG)

Inverse DG mass matrix :arg DG: the DG space :returns: A PETSc Mat.

DG_work(V)

A DG work Function matching V :arg V: a function space. :returns: A Function in the embedding DG space.

V_DG_mass(V, DG)

Mass matrix from between V and DG spaces. :arg V: a function space :arg DG: the DG space :returns: A PETSc Mat mapping from V -> DG

V_approx_inv_mass(V, DG)

Approximate inverse mass. Computes (cellwise) (V, V)^{-1} (V, DG). :arg V: a function space :arg DG: the DG space :returns: A PETSc Mat mapping from V -> DG.

V_dof_weights(V)

Dof weights for averaging projection.

Parameters:

V – function space to compute weights for.

Returns:

A PETSc Vec.

V_inv_mass_ksp(V)

A KSP inverting a mass matrix :arg V: a function space. :returns: A PETSc KSP for inverting (V, V).

cache(V)

cache_dat_versions(V, transfer_op, source, target)

Record the returned dat_versions of the source and target.

cache_key(V)

inject(uf, uc)

Inject a function (primal restriction)

Parameters:

• uf – The source (fine grid) function.

• uc – The target (coarse grid) function.

is_native(element, gdim, op)

op(source, target, transfer_op)

Primal transfer (either prolongation or injection).

Parameters:

• source – The source Function.

• target – The target Function.

• transfer_op – The transfer operation for the DG space.

prolong(uc, uf)

Prolong a function.

Parameters:

• uc – The source (coarse grid) function.

• uf – The target (fine grid) function.

requires_transfer(V, transfer_op, source, target)

Determine whether either the source or target have been modified since the last time a grid transfer was executed with them.

restrict(source, target)

Restrict a cofunction.

Parameters:

• source – The source (fine grid) Cofunction.

• target – The target (coarse grid) Cofunction.

transfer(x, y)

Transfer a function/cofunction.

Parameters:

• x – The source (co)function.

• y – The target (co)function.

work_vec(V)

A work Vec for V :arg V: a function space. :returns: A PETSc Vec for V.

firedrake.mg.interface module

firedrake.mg.interface.assemble_prolongation_aij(Vc, Vf, bcs=None)

Assemble the explicit AIJ matrix prolonging Vc to Vf.

Parameters:

• Vc (WithGeometry) – The source (coarse grid) function space.

• Vf (WithGeometry) – The target (fine grid) function space.

• bcs (list of DirichletBC) – Boundary conditions to apply to the rows and columns of the matrix. Defaults to None, in which case no boundary conditions are applied.

Returns:

The prolongation matrix mapping Vc to Vf.

Return type:

AssembledMatrix

firedrake.mg.interface.inject(fine, coarse)

firedrake.mg.interface.prolong(coarse, fine)

firedrake.mg.interface.restrict(fine_dual, coarse_dual)

firedrake.mg.kernels module

class firedrake.mg.kernels.MacroKernelBuilder(scalar_type, num_entities)

Bases: KernelBuilderBase

Kernel builder for integration on a macro-cell.

Parameters:

num_entities – the number of micro-entities to integrate over.

oriented = False

set_coefficients(coefficients)

set_coordinates(domain)

Prepare the coordinate field.

Parameters:

domain – ufl.AbstractDomain

firedrake.mg.kernels.dg_injection_kernel(Vf, Vc, ncell)

firedrake.mg.kernels.dual_evaluation_kernel(operand, dual_arg, parameters=None, name='evaluate')

Generate kernel for dual evaluation.

Parameters:

• operand (ufl.Expr) – A primal expression

• dual_arg (ufl.Coargument | ufl.Cofunction) – A dual argument or coefficient

Returns:

The kernel

Return type:

pyop2.op2.Kernel

firedrake.mg.kernels.inject_kernel(Vf, Vc)

firedrake.mg.kernels.prolong_kernel(expression, Vf)

firedrake.mg.kernels.prolong_matrix_kernel(Vc, Vf)

Return a PyOP2 kernel that assembles the local prolongation matrices mapping Vc to Vf.

Parameters:

• Vc (WithGeometry) – The source (coarse grid) function space.

• Vf (WithGeometry) – The target (fine grid) function space.

Returns:

A kernel that fills in the local dense matrix of the point evaluation prolongation operator, for each fine grid cell and its overlapping coarse grid cells.

Return type:

pyop2.op2.Kernel

firedrake.mg.kernels.restrict_kernel(Vf, Vc)

firedrake.mg.kernels.to_reference_coordinates(ufl_coordinate_element, parameters=None)

firedrake.mg.mesh module

firedrake.mg.mesh.ExtrudedMeshHierarchy(base_hierarchy: HierarchyBase, height: float, base_layer: int = -1, refinement_ratio: int = 2, layers: Sequence[int] | None = None, kernel=None, extrusion_type: str = 'uniform', periodic: bool = False, gdim: int | None = None, mesh_builder=<cyfunction ExtrudedMesh>) → HierarchyBase

Build a hierarchy of extruded meshes by extruding a hierarchy of meshes.

Parameters:

• base_hierarchy (HierarchyBase) – The unextruded base mesh hierarchy to extrude.

• height (float) – The height of the domain to extrude to. This is in contrast to the extrusion routines, which take layer_height, the height of an individual layer. The height of an individual layer varies when the hierarchy is refined in the extruded dimension.

• base_layer (int) – The number of layers to use for the coarsest grid.

• refinement_ratio (int) – The ratio by which to increase base_layer at every refinement. A value of 2 gives standard uniform refinement, and a value of 1 does not refine in the extruded dimension, which gives a semicoarsened hierarchy.

• layers (Sequence[int] or None) – An alternative to specifying base_layer and refinement_ratio. This sequence gives the number of layers at each level in the extruded hierarchy. Do not combine this option with base_layer and refinement_ratio. The ratio of successive entries must be an integer for the multigrid transfer operators to work.

• kernel (pyop2.op2.Kernel or None) – An optional kernel that computes the coordinates of the extruded mesh.

• extrusion_type (str) – The algorithm that computes the extruded coordinates. Supported values include "uniform", "radial", "radial_hedgehog", and "custom".

• periodic (bool) – Whether to identify the top and bottom boundaries of each extruded mesh. Periodic extrusion requires a constant number of layers.

• gdim (int or None) – The number of spatial dimensions in the resulting mesh. This value is used only when kernel is provided.

• mesh_builder (collections.abc.Callable) – The function that turns a Mesh into an extruded mesh. This is used by pyadjoint.

Returns:

The hierarchy of extruded meshes.

Return type:

HierarchyBase

class firedrake.mg.mesh.HierarchyBase(meshes, coarse_to_fine_cells=None, fine_to_coarse_cells=None, refinements_per_level=1, nested=False, fine_to_coarse_points=None)

Bases: object

Create an encapsulation of an hierarchy of meshes.

Parameters:

• meshes – List of meshes (coarse to fine).

• coarse_to_fine_cells – Optional dictionary of numpy arrays keyed by level pair, mapping each coarse cell to its fine children. Every row is as wide as the busiest coarse cell’s count. 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. Omit this and fine_to_coarse_cells together to derive both maps from fine_to_coarse_points.

• fine_to_coarse_cells – Optional dictionary of numpy arrays keyed by level, mapping each fine cell to its coarse parent cell. 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. Omit this and coarse_to_fine_cells together to derive both maps from fine_to_coarse_points.

• refinements_per_level – Number of mesh refinements each multigrid level should “see”.

• nested – Is this mesh hierarchy nested?

• fine_to_coarse_points – Dict of numpy arrays for each level that was refined from the level below it. Each array maps fine DMPlex points to their coarse DMPlex source points, or to -1 when no corresponding coarse point is present. Cell maps derived from this point map follow Firedrake cell numbering.

Notes

Most of the time, you do not need to create this object yourself, instead using \(MeshHierarchy\), \(ExtrudedMeshHierarchy\), or \(NonNestedHierarchy\).

adapt(eta, theta: float)

Add a new mesh to the hierarchy by locally refining the finest mesh with a simplified variant of Dorfler marking.

Parameters:

• eta – A DG0 Function with the local error estimator.

• theta – The threshold for marking as a fraction of the maximum error.

Returns:

The mesh that was added.

Return type:

MeshGeometry

Note

Dorfler marking involves sorting all of the elements by decreasing error estimator and taking the minimal set that exceeds some fixed fraction of the total error. What this code implements is the simpler variant that doesn’t have a proof of convergence (as far as I know) but works as well in practice.

add_mesh(mesh, coarse_to_fine_cells=None, fine_to_coarse_cells=None)

Add a mesh on top of the finest level of the hierarchy.

Only supported for hierarchies with refinements_per_level == 1.

Parameters:

• mesh – The mesh to add, usually obtained by calling refine_marked_elements() on the current finest mesh.

• coarse_to_fine_cells – Map from the cells of the current finest mesh to the cells of mesh. Defaults to the map mesh recorded when it was adaptively refined.

• fine_to_coarse_cells – Map from the cells of mesh to the cells of the current finest mesh. Defaults the same way as coarse_to_fine_cells.

Returns:

The mesh that was added.

Return type:

MeshGeometry

property comm

firedrake.mg.mesh.MeshHierarchy(mesh, refinement_levels=0, refinements_per_level=1, netgen_flags=None, reorder=None, distribution_parameters=None, callbacks=None, mesh_builder=<cyfunction Mesh>, nested=True)

Build a hierarchy of meshes by uniformly refining a coarse mesh.

Parameters:

• mesh (MeshGeometry) – the coarse mesh to refine

• refinement_levels (int) – the number of levels of uniform refinement. This may be dynamically increased by HierarchyBase.adapt() or HierarchyBase.add_mesh().

• refinements_per_level (int) – the number of refinements for each level in the hierarchy. Adaptive refinement only supports one refinement per level.

• netgen_flags (dict or None) – Options for a mesh generated by Netgen. If mesh was generated by Netgen and this value is None, the hierarchy reuses its Netgen flags. The vertices of each refined mesh are snapped onto the Netgen geometry. The "degree" option sets the degree of the curved coordinates, either as an integer or as a sequence with one entry per level in the hierarchy. The "cg" option sets their continuity.

• distribution_parameters (dict) – options controlling mesh distribution, see Mesh() for details. If None, use the same distribution parameters as were used to distribute the coarse mesh, otherwise, these options override the default.

• reorder (bool) – optional flag indicating whether to reorder the refined meshes.

• callbacks (tuple) – A 2-tuple of callbacks to call before and after refinement of the DM. The before callback receives the DM to be refined (and the current level), the after callback receives the refined DM (and the current level).

• mesh_builder – Function to turn a DM into a Mesh. Used by pyadjoint.

• nested (bool) – Are the meshes added to this hierarchy required to be nested? If \(False\), HierarchyBase.add_mesh() accepts a mesh that was not adaptively refined from the finest level.

Returns:

The mesh hierarchy.

Return type:

HierarchyBase

firedrake.mg.mesh.NonNestedHierarchy(*meshes)

firedrake.mg.mesh.SemiCoarsenedExtrudedHierarchy(base_mesh, height, nref=1, base_layer=-1, refinement_ratio=2, layers=None, kernel=None, extrusion_type='uniform', gdim=None, mesh_builder=<cyfunction ExtrudedMesh>)

Build a hierarchy of extruded meshes with refinement only in the extruded dimension.

Parameters:

• base_mesh – the unextruded base mesh to extrude.

• nref – Number of refinements.

• height – the height of the domain to extrude to. This is in contrast to the extrusion routines, which take in layer_height, the height of an individual layer. This is because when refining in the extruded dimension, the height of an individual layer will vary.

• base_layer – the number of layers to use the extrusion of the coarsest grid.

• refinement_ratio – the ratio by which base_layer should be increased on every refinement. refinement_ratio = 2 means standard uniform refinement. refinement_ratio = 1 means to not refine in the extruded dimension, i.e. the multigrid hierarchy will use semicoarsening.

• layers – as an alternative to specifying base_layer and refinement_ratio, one may specify directly the number of layers to be used by each level in the extruded hierarchy. This option cannot be combined with base_layer and refinement_ratio. Note that the ratio of successive entries in this iterable must be an integer for the multigrid transfer operators to work.

• mesh_builder – function used to turn a Mesh into an extruded mesh. Used by pyadjoint.

See ExtrudedMesh() for the meaning of the remaining parameters.

See also ExtrudedMeshHierarchy() if you want to extruded a hierarchy of unstructured meshes.

firedrake.mg.mesh.SubmeshHierarchy(parent_hierarchy: HierarchyBase, subdim: int | None = None, subdomain_id: int | Sequence | None = None, label_name: str | None = None, name: str | None = None, ignore_halo: bool = False, reorder: bool | None = None, comm=None)

Build a hierarchy of submeshes from an existing mesh hierarchy.

Parameters:

• parent_hierarchy – Parent mesh hierarchy.

• subdim – Topological dimension of the submesh. Defaults to mesh.topological_dimension.

• subdomain_id – Subdomain ID representing the submesh. If \(None\) the submesh will cover the entire domain. This is useful to obtain a codim-1 submesh over all facets or a submesh over a different communicator.

• label_name – Name of the label to search subdomain_id in. Defaults to 'Cell Sets' or 'Face Sets' depending on subdim.

• name (str | None) – Name of the submesh. Defaults to mesh.name + "_submesh"·

• ignore_halo – Whether to exclude the halo from the submesh.

• reorder – Whether to reorder the mesh entities. By default, the submesh will be reordered if the parent mesh was reordered.

• comm (PETSc.Comm | None) – An optional sub-communicator to define the submesh. By default, the submesh is defined on \(mesh.comm\).

Returns:

The submesh hierarchy.

Return type:

HierarchyBase

Notes

A facet submesh that contains interior facets, such as the skeleton obtained with subdim=tdim-1 and subdomain_id=None, is only partially nested. A fine facet inside a coarse cell has no parent in the coarse submesh. Injection is still possible, because the fine children of each coarse facet cover it. \(prolong\) and \(restrict\) raise \(NotImplementedError\) when a fine node lies only on facets without a parent.

firedrake.mg.opencascade_mh module

firedrake.mg.opencascade_mh.OpenCascadeMeshHierarchy(stepfile, element_size, levels, comm=<mpi4py.MPI.Intracomm object>, distribution_parameters=None, callbacks=None, order=1, mh_constructor=<function MeshHierarchy>, cache=True, verbose=True, gmsh='gmsh', project_refinements_to_cad=True, reorder=None)

firedrake.mg.ufl_utils module

firedrake.mg.ufl_utils.coarsen(expr, self, coefficient_mapping=None)

firedrake.mg.ufl_utils.coarsen(mesh: MeshSequence, self, coefficient_mapping=None)

firedrake.mg.ufl_utils.coarsen(mesh: Mesh, self, coefficient_mapping=None)

firedrake.mg.ufl_utils.refine(expr, self, coefficient_mapping=None)

firedrake.mg.ufl_utils.refine(mesh: MeshSequence, self, coefficient_mapping=None)

firedrake.mg.ufl_utils.refine(mesh: Mesh, self, coefficient_mapping=None)

firedrake.mg.utils module

firedrake.mg.utils.coarse_cell_child_count(Vc: WithGeometry, Vf: WithGeometry) → Dat

Count the fine cells that each coarse cell was refined into.

A row of \(HierarchyBase.coarse_to_fine_cells\) is as wide as the busiest coarse cell’s count, so its width overstates how many children most cells have. The DG injection kernel reads this count to stop at a coarse cell’s own children, and so leaves the padding alone.

Parameters:

• Vc (firedrake.functionspaceimpl.WithGeometry) – The coarse function space.

• Vf (firedrake.functionspaceimpl.WithGeometry) – The fine function space, on the next level of the same hierarchy.

Returns:

One count per cell of Vc’s mesh, over that mesh’s cell set. Halo cells are left at zero: a par_loop visits the core and owned parts only, so the kernel never reads them.

Return type:

pyop2.types.dat.Dat

firedrake.mg.utils.coarse_cell_to_fine_node_map(Vc, Vf)

firedrake.mg.utils.coarse_node_to_fine_node_map(Vc, Vf)

firedrake.mg.utils.fine_node_to_coarse_node_map(Vf, Vc)

firedrake.mg.utils.get_level(obj)

Try and obtain hierarchy and level info from an object.

If no level info is available, return None, None.

firedrake.mg.utils.has_level(obj)

Does the provided object have level info?

firedrake.mg.utils.identity_node_map(V)

firedrake.mg.utils.physical_node_locations(V)

firedrake.mg.utils.set_level(obj, hierarchy, level)

Attach hierarchy and level info to an object.

Module contents