Mondaic

salvus.mesh.algorithms.improve

salvus.mesh.algorithms.improve salvus mesh algorithms improve

Routines to perform mesh smoothing.

Functions

centroidal()

def centroidal(
    mesh: UnstructuredMesh,
    iterations: int = 50,
    fixed_side_sets: str | collections.abc.Sequence[str] | None = None,
    fixed_outer_boundaries: bool = True,
) -> UnstructuredMesh: ...

Area-weighted centroidal smoothing for uniform element sizes.

Every node that is not held fixed is repeatedly moved to the size-weighted average of the centroids of its incident elements (a Lloyd iteration), where the weight is each element’s area in 2-D or volume in 3-D. This pulls nodes towards larger elements and away from smaller ones, relaxing the mesh towards uniform element sizes. It holds all nodes on a side of a fixed side set in place, so the geometry and interfaces are preserved; only the coordinates change and the connectivity and all fields are untouched.

The smoothing is a Jacobi iteration: within a sweep every free node is updated from the previous sweep’s positions.

Parameters
  • mesh UnstructuredMesh — The mesh to smooth.
  • iterations int — Number of smoothing sweeps.
  • fixed_side_sets str | collections.abc.Sequence[str] | None — Name or names of the side sets whose nodes are held fixed. If None, every side set in mesh.side_sets is used.
  • fixed_outer_boundaries bool — If True, the mesh’s outer surface is detected with find_surface and its nodes are held fixed too, so the outer geometry is preserved. The temporary side set used to do this is removed from the returned mesh.
Returns UnstructuredMesh — A copy of mesh with the free nodes relocated.

laplacian()

def laplacian(
    mesh: UnstructuredMesh,
    iterations: int = 50,
    fixed_side_sets: str | collections.abc.Sequence[str] | None = None,
    fixed_outer_boundaries: bool = True,
) -> UnstructuredMesh: ...

Laplacian-smooth a mesh, holding the chosen side-set nodes fixed.

Every node that is not held fixed is repeatedly moved to the average of the nodes it shares an element edge with, which relaxes the mesh towards better-shaped elements. All nodes that lie on a side of a fixed side set are held in place, so the corresponding geometry and interfaces are preserved. Only the coordinates change; the connectivity and all fields are untouched.

The smoothing is a Jacobi iteration: within a sweep every free node is updated from the previous sweep’s positions.

Parameters
  • mesh UnstructuredMesh — The mesh to smooth.
  • iterations int — Number of smoothing sweeps.
  • fixed_side_sets str | collections.abc.Sequence[str] | None — Name or names of the side sets whose nodes are held fixed. If None, every side set in mesh.side_sets is used.
  • fixed_outer_boundaries bool — If True, the mesh’s outer surface is detected with find_surface and its nodes are held fixed too, so the outer geometry is preserved. The temporary side set used to do this is removed from the returned mesh.
Returns UnstructuredMesh — A copy of mesh with the free nodes relocated.

optimize_time_step_globally()

def optimize_time_step_globally(
    mesh: UnstructuredMesh,
    iterations: int = 10,
    max_resolution_loss: float = 0.0,
    fixed_side_sets: str | collections.abc.Sequence[str] | None = None,
    fixed_outer_boundaries: bool = True,
    skip_time_step_check: bool = False,
    verbosity: int = 1,
) -> UnstructuredMesh: ...

Relocate the nodes of a mesh to maximize its stable time step.

The time step a simulation on a mesh can run with is dictated by its worst element, that is by the smallest distance between two GLL points anywhere in the mesh over the wave speed there. All nodes that are not held fixed are moved simultaneously to maximize a smooth approximation of that worst case over the entire mesh, which lowers the cost of every simulation run on the mesh. It holds all nodes on a side of a fixed side set in place, so the geometry and interfaces are preserved; only the coordinates change and the connectivity and all fields are untouched. Elements that are valid to begin with are never left inverted, and the mesh that comes back is never a worse one than the mesh that went in: its time step is measured against the original’s, and the original is handed back untouched if the optimization did not lift it. That measurement computes the time step and the resolved frequency of both meshes, which is not free on a large one and can be given up with skip_time_step_check.

The wave speeds come from the mesh’s own material fields (compute_max_velocity_per_element), so a fast element is worth more room than a slow one and the optimization settles towards element sizes that follow the medium. On a mesh without material fields the objective is the smallest GLL point distance alone, which is the same thing for a homogeneous medium.

In contrast to laplacian and centroidal, which relax the mesh locally and cheaply, this is a global gradient-based minimization (L-BFGS-B) over all free node coordinates at once. It is markedly more expensive, but directly targets the quantity of interest.

A larger time step can always be had by coarsening the mesh, which is not an improvement at all: it trades away the resolution the mesh was built with and drives up dispersion error. max_resolution_loss is what keeps the optimization from taking that trade, and with it the result settles down instead of drifting as iterations is raised.

Parameters
  • mesh UnstructuredMesh — The mesh to optimize.
  • iterations int — Maximum number of minimization iterations. The minimization stops earlier if it converges.
  • max_resolution_loss float — The fraction of the mesh’s own resolved frequency (estimate_resolved_frequency) that the optimization may give up, as a trade for a larger time step. The default of 0.0 asks for the mesh to keep resolving exactly what it already does, which is the conservative choice and leaves the optimization the least room to work with, as most meshes have some elements already at the size that sets their resolved frequency. Raise it to trade a little resolution for a larger time step. Elements are never asked to shrink: an element that already exceeds its share of the budget is left at the size it has. On a mesh without any material fields attached, “resolved frequency” falls back to every element’s longest edge relative to the mesh’s own largest edge, since there is no velocity to scale it by.
  • fixed_side_sets str | collections.abc.Sequence[str] | None — Name or names of the side sets whose nodes are held fixed. If None, every side set in mesh.side_sets is used.
  • fixed_outer_boundaries bool — If True, the mesh’s outer surface is detected with find_surface and its nodes are held fixed too, so the outer geometry is preserved. The temporary side set used to do this is removed from the returned mesh.
  • skip_time_step_check bool — If True, the optimized mesh is handed back without measuring it against the original. This saves computing the time step and the resolved frequency of both meshes, which is worth having on a large mesh, but it also gives up the guarantee that the result is not a worse mesh than the input: all that is then left is the approximate objective the minimization works with. The resolution budget is unaffected, as it is enforced by the minimization itself rather than by this check. Nothing is reported before and after either, whatever verbosity asks for.
  • verbosity int — Verbosity level. At 0 nothing is printed at all. At 1 a progress bar is shown while minimizing and the time step and resolved frequency are reported before and after. Anything higher adds the diagnostics of the minimization itself.
Returns UnstructuredMesh — A copy of mesh with the free nodes relocated.

optimize_time_step_locally()

def optimize_time_step_locally(
    mesh: UnstructuredMesh,
    iterations: int = 50,
    worst_element_count: int = 100,
    halo_width: int = 3,
    max_resolution_loss: float = 0.0,
    fixed_side_sets: str | collections.abc.Sequence[str] | None = None,
    fixed_outer_boundaries: bool = True,
    skip_time_step_check: bool = False,
    verbosity: int = 1,
) -> UnstructuredMesh: ...

Relocate the nodes of the worst elements to maximize the stable time step.

Only a small part of a mesh usually limits its time step. This routine therefore ranks all elements by how much they restrict it, takes the worst_element_count worst ones, grows a halo of halo_width element layers around them, and optimizes the nodes of that region only, as optimize_time_step_globally does for the whole mesh. That is far cheaper than optimizing every node of a large mesh, and usually just as effective, as the untouched elements were not limiting the time step to begin with.

Both the ranking and the optimization weight every element with its own wave speed, taken from the mesh’s material fields, so the elements that are worked on are the ones that limit the time step of the medium rather than the worst shaped ones. See optimize_time_step_globally.

It holds all nodes on a side of a fixed side set in place, so the geometry and interfaces are preserved, exactly as laplacian, centroidal and optimize_time_step_globally do. Additionally, the sides of the optimized region that cut through the mesh are always held fixed, as the region has to stay conforming with the rest of the mesh. Only the coordinates change; the connectivity and all fields are untouched. Elements that are valid to begin with are never left inverted, and the mesh that comes back is never a worse one than the mesh that went in: its time step is measured against the original’s, and the original is handed back untouched if the optimization did not lift it. That measurement is over the whole mesh rather than the optimized region, so it costs the same here as it does globally and can be given up with skip_time_step_check.

A larger time step can always be had by coarsening the mesh, which is not an improvement at all: it trades away the resolution the mesh was built with and drives up dispersion error. max_resolution_loss is what keeps the optimization from taking that trade, and with it the result settles down instead of drifting as iterations is raised.

Parameters
  • mesh UnstructuredMesh — The mesh to optimize.
  • iterations int — Maximum number of minimization iterations. The minimization stops earlier if it converges.
  • worst_element_count int — Number of worst elements to optimize. The region that is actually optimized is larger, as it also contains the halo around those elements.
  • halo_width int — Number of element layers to grow around the worst elements before optimizing. A wider halo gives the worst elements more room to improve, at a higher cost.
  • max_resolution_loss float — The fraction of the mesh’s own resolved frequency (estimate_resolved_frequency), measured over the whole mesh, that the optimization may give up, as a trade for a larger time step. The default of 0.0 asks for the mesh to keep resolving exactly what it already does, which is the conservative choice and leaves the optimization the least room to work with, as most meshes have some elements already at the size that sets their resolved frequency. Raise it to trade a little resolution for a larger time step. Elements are never asked to shrink: an element that already exceeds its share of the budget is left at the size it has. On a mesh without any material fields attached, “resolved frequency” falls back to every element’s longest edge relative to the mesh’s own largest edge, since there is no velocity to scale it by.
  • fixed_side_sets str | collections.abc.Sequence[str] | None — Name or names of the side sets whose nodes are held fixed. If None, every side set in mesh.side_sets is used.
  • fixed_outer_boundaries bool — If True, the mesh’s outer surface is detected with find_surface and its nodes are held fixed too, so the outer geometry is preserved. The temporary side set used to do this is removed from the returned mesh.
  • skip_time_step_check bool — If True, the optimized mesh is handed back without measuring it against the original. This saves computing the time step and the resolved frequency of both meshes, which is worth having on a large mesh - all the more so here, where the optimization itself only works on a small region and the check is over the whole mesh - but it also gives up the guarantee that the result is not a worse mesh than the input: all that is then left is the approximate objective the minimization works with. The resolution budget is unaffected, as it is enforced by the minimization itself rather than by this check. Nothing is reported before and after either, whatever verbosity asks for.
  • verbosity int — Verbosity level. At 0 nothing is printed at all. At 1 a progress bar is shown while minimizing and the time step and resolved frequency are reported before and after. Anything higher adds the diagnostics of the minimization itself, such as the size of the optimized region.
Returns UnstructuredMesh — A copy of mesh with the nodes of the optimized region relocated.