Refinement Model¶

Introduction¶

The RefinementModel coordinates adaptive mesh refinement (h-refinement) within a simulation. It registers geometric and topological coefficient functions useful for visualization, reporting, and refinement criteria. It also works with other models that do refinement logic. It queries these models before it changes the mesh.

Functions¶

RefinementModel()

The RefinementModel gives mesh refinement capabilities in the simulation.

refine_mesh(max_relative_increase=None)

Refines the mesh based on refinement suggestions from other models.

The software queries all initialized models that implement the refinement interface. These models mark the cells to refine. If a model marks a cell more than one time, the software refines it only one time. The software then refines the marked cells in parallel. The type of refinement depends on the mesh:

• Non-conforming mesh (loaded with a NonConformingOption): the refinement makes hanging nodes.
• Conforming mesh with tetrahedra: the refinement is conforming (bisection). To keep the mesh conforming, the software also divides neighbouring cells (closure).
• Conforming mesh with only hexahedra or prisms: the refinement makes hanging nodes.

max_relative_increase sets the maximum number of marked cells, as a fraction of the current number of cells on each MPI process. For example, 0.5 refines at most 50 % of the cells. The default None sets no limit. The models give their marks in order of priority. For example, the time-harmonic magnetic model sorts the marks by the material contrast. Thus, the software keeps the cells with the highest priority.

Use this limit to control the growth of the mesh. This is important for conforming refinement of tetrahedral meshes. The closure also divides neighbouring cells. Thus, the real increase is larger than this fraction. The software writes the real increase to the log. Use this value to adjust the limit:

RefinementModel: refined 120000 -> 171000 cells (+42%).

uniform_refinement()

Does uniform refinement of the entire mesh.

This subdivides all cells uniformly. It does not check any refinement criteria. You can use it for debugging, convergence studies, or testing.

refine_order()

Does p-refinement based on model-specific criteria.

The software queries the models that implement the p-refinement interface. These models mark the cells that need a higher polynomial order.

refine_along_interface(phi, sample_ir_order=2, max_refinement_contrast=1)

Refines the cells crossed by the zero level set of the scalar coefficient phi. The software samples each cell with an integration rule of order sample_ir_order. It marks a cell for refinement when phi changes sign between the sample points. You can use it to resolve material interfaces that are defined implicitly, for example with the Implicit Geometry Material:

for _ in range(5):
    refinement_model.refine_along_interface(phi=cff_phi, sample_ir_order=8)

refinement_model.equilibrate_refinement()

equilibrate_refinement(max_refinement_contrast=1)

Equilibrates refinement levels across the mesh so that neighboring cells differ by at most max_refinement_contrast levels.

Coefficients¶

The RefinementModel registers the following coefficient:

This model does not add general mesh coefficients such as Cell Volume, Element Type, Position, and Global Cell Index. They are always available as Built-in Coefficients.

Example¶

In this example you load a mesh and do uniform refinement. Then you show the coefficient functions with the Field Exporter and ParaView:

import mufem

sim = mufem.Simulation.New(
    name="My Case",
    mesh_path="data/geometry.mesh",
    verbosity_level=mufem.Verbosity.WARNING,
)

refinement_model = mufem.RefinementModel()

sim.get_model_manager().add_model(refinement_model)

refinement_model.uniform_refinement()

field_exporter = sim.get_field_exporter()

field_exporter.add_field_output("Cell Volume")
field_exporter.add_field_output("Element Type")
field_exporter.add_field_output("Position")
field_exporter.add_field_output("Refinement Level")
field_exporter.add_field_output("Global Cell Index")

field_exporter.save()