salvus.mesh.algorithms.improve
salvus.mesh.algorithms.improve salvus mesh algorithms improve Routines to perform mesh smoothing.
Functions
centroidal()
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.
meshUnstructuredMesh — The mesh to smooth.iterationsint =50— Number of smoothing sweeps.fixed_side_setsstr | collections.abc.Sequence[str] | None =None— Name or names of the side sets whose nodes are held fixed. IfNone, every side set inmesh.side_setsis used.fixed_outer_boundariesbool =True— IfTrue, the mesh’s outer surface is detected withfind_surfaceand 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.
mesh with the free nodes relocated.laplacian()
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.
meshUnstructuredMesh — The mesh to smooth.iterationsint =50— Number of smoothing sweeps.fixed_side_setsstr | collections.abc.Sequence[str] | None =None— Name or names of the side sets whose nodes are held fixed. IfNone, every side set inmesh.side_setsis used.fixed_outer_boundariesbool =True— IfTrue, the mesh’s outer surface is detected withfind_surfaceand 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.
mesh with the free nodes relocated.optimize_time_step_globally()
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.
meshUnstructuredMesh — The mesh to optimize.iterationsint =10— Maximum number of minimization iterations. The minimization stops earlier if it converges.max_resolution_lossfloat =0.0— 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 of0.0asks 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_setsstr | collections.abc.Sequence[str] | None =None— Name or names of the side sets whose nodes are held fixed. IfNone, every side set inmesh.side_setsis used.fixed_outer_boundariesbool =True— IfTrue, the mesh’s outer surface is detected withfind_surfaceand 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_checkbool =False— IfTrue, 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, whateververbosityasks for.verbosityint =1— Verbosity level. At0nothing is printed at all. At1a 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.
mesh with the free nodes relocated.optimize_time_step_locally()
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.
meshUnstructuredMesh — The mesh to optimize.iterationsint =50— Maximum number of minimization iterations. The minimization stops earlier if it converges.worst_element_countint =100— Number of worst elements to optimize. The region that is actually optimized is larger, as it also contains the halo around those elements.halo_widthint =3— 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_lossfloat =0.0— 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 of0.0asks 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_setsstr | collections.abc.Sequence[str] | None =None— Name or names of the side sets whose nodes are held fixed. IfNone, every side set inmesh.side_setsis used.fixed_outer_boundariesbool =True— IfTrue, the mesh’s outer surface is detected withfind_surfaceand 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_checkbool =False— IfTrue, 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, whateververbosityasks for.verbosityint =1— Verbosity level. At0nothing is printed at all. At1a 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.
mesh with the nodes of the optimized region relocated.