What the offset needs on top of the parameters every wmtk optimizer shares. More...
#include <Parameters.h>
Public Member Functions | |
| double | front_conv_frac () const |
| Parameters (const nlohmann::json &json_params) | |
| void | init (const VectorXd &min_, const VectorXd &max_) |
 Public Member Functions inherited from wmtk::OptimizerParameters | |
| void | init_lengths_from_diagonal (const double diag) |
| Derive the edge-length and envelope quantities from the bounding-box diagonal. | |
Public Attributes | |
| ExpressionPtr | offset_selection |
| std::set< std::string > | offset_output_tag |
| std::set< std::string > | protected_tags |
| bool | offset_in |
| bool | offset_out |
| double | target_distance |
| double | target_distance_rel |
| bool | throw_on_nonconvergence |
| bool | optimize_offset |
| double | envelope_size |
| double | envelope_size_rel |
| double | offset_dhat_factor |
| double | debug_manual_dhat |
| std::string | offset_field |
| "smooth" (Phi level set) or "euclidean" (exact distance) | |
| double | front_conv |
| double | front_conv_rel |
| std::string | front_conv_criterion |
| gradient_norm_rel | step_size_rel | decrement | residual_error [2D ONLY] | |
| bool | front_normal_projection = true |
| bool | front_alignment_energy = true |
| bool | sizing_collapse_min = true |
| bool | deform_others = true |
| int | max_rounds = 40 |
| int | stencil_order |
| std::string | front_measure |
| bool | sorted_marching |
| bool | sphere_trace_initialization |
| double | sphere_trace_target_rel_tol |
| bool | experimental_consistent_construction_split = true |
| bool | experimental_aggresive_refine = true |
| bool | experimental_nonoverlapping_gates = false |
| std::string | output_path |
| bool | save_vtu |
| int | phi_grid_resolution |
| int | num_threads |
| int | max_iterations |
| double | offset_envelope |
| absolute; < 0 means use offset_envelope_rel | |
| double | offset_envelope_rel |
| double | min_edge_length |
| double | min_edge_length_rel |
| double | min_sizing_scalar |
| double | max_sizing_scalar |
| double | sizing_gradation |
| std::string | sizing_gradation_mode |
| bool | adaptive_smoothing |
| int | adaptive_smoothing_max_passes |
| cap on the passes per group | |
| double | adaptive_smoothing_stall_rel |
| front stalled: max ratio dropped by less than this | |
| double | adaptive_smoothing_step_rel |
| bool | pre_smooth |
| VectorXd | box_min |
| VectorXd | box_max |
| Public Attributes inherited from wmtk::OptimizerParameters | |
| double | epsr = 1e-3 |
| double | eps = -1. |
| double | lr = 5e-2 |
| double | l = -1. |
| double | l_min = -1 |
| double | diag_l = -1. |
| bool | preserve_topology = false |
| bool | optimize_envelope_around_simplified = false |
| int | split_high_valence_threshold = 0 |
| double | stuck_refine_stall_eps = 0.1 |
| int | stuck_refine_cooldown = 1 |
| int | stuck_refine_num_worst = 0 |
| int | stuck_refine_rings = 0 |
| double | stuck_refine_factor = 0.5 |
| double | stuck_refine_min_scalar = 1e-3 |
| double | stuck_refine_gradation = 2.0 |
| bool | stuck_refine_force_split = true |
| bool | skip_good_regions = false |
| double | skip_good_regions_margin = 0.9 |
| double | splitting_l2 = -1. |
| double | collapsing_l2 |
| double | stop_energy = 100 |
| double | w_amips = 1e-4 |
| std::string | smoothing_mode = "projected" |
| "projected" or "exact"; see SmoothVertexOptions::SmoothingMode. | |
| int | project_line_search_steps = 12 |
| Bisections tried before the projected search gives up. See SmoothVertexOptions. | |
| int | project_line_search_nested_steps = 0 |
| Partial-projection bisections tried after it gives up; 0 disables that pass. | |
| bool | smooth_quality_veto = true |
| double | w_envelope = 1. - 1e-4 |
| int | num_smoothing_passes = 2 |
| Number and placement of smoothing passes in the shared Wild optimization driver. | |
| bool | interleaved_smoothing = true |
| int | interleaved_smoothing_passes = 1 |
| bool | coarsen_pass = false |
| bool | coarsen_unbounded = true |
| int | coarsen_local_smoothing_passes = 0 |
| int | coarsen_smooth_ring = 1 |
| int | coarsen_global_smoothing_passes = 1 |
| int | coarsen_max_rounds = 2 |
| int | coarsen_max_inner_passes = 1 |
| bool | debug_output = false |
| bool | perform_sanity_checks = false |
Detailed Description
What the offset needs on top of the parameters every wmtk optimizer shares.
The optimization phase reuses wmtk::TriOptimizerMesh / wmtk::TetOptimizerMesh, so everything that phase reads – target edge length, the split/collapse thresholds derived from it, smoothing weights and pass count, the sizing knobs, the debug switch – comes from wmtk::OptimizerParameters and is not restated here. The bounding box stays here because its type and meaning differ per application.
Every key below means the same thing in 2D and 3D; the two pipelines are the same algorithm one dimension apart, and a key that only one of them read would be a difference in the algorithm.
Member Function Documentation
◆ front_conv_frac()
|
inline |
The convergence epsilon as a FRACTION of target_distance, which is the form the dimensionless relative error OffsetPotential::relative_residual() is compared against. A mean of squared relative errors is below front_conv_frac()^2 exactly when the same mean taken in lengths is below front_conv^2 – the two differ by target_distance^2 on both sides – so which form the code uses is a matter of where the division sits, not of what is being asked. 2D's fraction-valued criteria ('decrement', 'gradient_norm_rel') take it for the same reason.
Member Data Documentation
◆ adaptive_smoothing
| bool wmtk::components::topological_offset::Parameters::adaptive_smoothing |
See the spec: the interleaved smoothing of each operation group runs until the front's Newton-step ratio converges or stalls AND the background's step settles, instead of a fixed interleaved_smoothing_passes.
◆ adaptive_smoothing_step_rel
| double wmtk::components::topological_offset::Parameters::adaptive_smoothing_step_rel |
background settled: max step / (s_v l) at or below
◆ debug_manual_dhat
| double wmtk::components::topological_offset::Parameters::debug_manual_dhat |
[2D ONLY] Debugging override for the potential's support radius: >= 0 uses this dhat as an ABSOLUTE length, in place of both offset_dhat_factor x target_distance and the constructed-offset floor. Negative (the default) leaves the automatic sizing alone. Only the 2D construction reads it; the 3D twin ignores it until the port.
◆ deform_others
| bool wmtk::components::topological_offset::Parameters::deform_others = true |
Other input regions (no input-complex simplex, no wall contact) deform under smoothing against their rest shape instead of being envelope-held. See the spec doc.
◆ experimental_aggresive_refine
| bool wmtk::components::topological_offset::Parameters::experimental_aggresive_refine = true |
EXPERIMENTAL, 3D only. DEFAULT TRUE since 2026-09-24. Drops the placement gate on refinement. With it FALSE a face over the bar is handed to the halving only when all THREE of its corners are already placed – the safeguard that stops refinement from chasing a moving front. True (the default) refines EVERY face over the bar, placed or not, so the sizing scalar is halved at every vertex of every unresolved face. The floor and the once-per-vertex-per-turn rule are unchanged, and so is the exit test: a face is refinable only while the halving can still lower a target, and n_faces_over_placed / max_face_placed still report the PLACED subset alone.
Why it exists: under one unified measure the two halves can deadlock. A face chording a feature of radius delta puts its centroid far inside the level set, and that sample's pull cancels the corners' own placement pull almost exactly, so the corners never place; refinement, which is the only thing that would shorten the chord and remove the sag, is gated on exactly those corners being placed. Measured on the deliverable cube at target_distance_rel 1e-2 / front_conv_rel 1e-4: 98% cancellation along the normal, the 1-D Newton step 1-2% of the move needed, and 600+ faces over the bar with ZERO refinable for 40 turns.
◆ experimental_consistent_construction_split
| bool wmtk::components::topological_offset::Parameters::experimental_consistent_construction_split = true |
EXPERIMENTAL. Makes the marching construction all-or-nothing: normally a sphere trace that leaves its edge falls back to the midpoint for THAT edge alone, so one construction can mix vertices sitting on the level set with vertices sitting at edge midpoints. With this on, the march is probed first, and a single untraceable edge sends EVERY edge to its midpoint. Only sphere_trace_initialization can mix, so this is a no-op when that is off. See the spec doc, and marching_tris() / marching_tets().
◆ experimental_nonoverlapping_gates
| bool wmtk::components::topological_offset::Parameters::experimental_nonoverlapping_gates = false |
EXPERIMENTAL, default false pending more runs. Separates the two length gates so a split can never hand the collapse pass its own halves. Both passes measure r = L / (l x mean of the endpoints' sizing scalars); the split fires at r > 4/3 and the collapse at r < 4/5, so an edge with 4/3 < r < 8/5 splits into halves with r/2 < 4/5, which the collapse pass merges straight back. With this on, splitting_l2 becomes (8/5 l)^2 – twice the collapse gate – and collapsing_l2 is untouched, so every half a split produces is at or above the collapse gate. A split is still never refused on quality; this is a length rule alone. Measured on the deliverable cube at target_distance_rel 1e-2 / front_conv_rel 1e-4, alignment off: 81% of the split candidates at the end of turn 7 (29068 of 35865) were inside that band, and turns 6-8 each ran ~36k splits and ~29k collapses while refinement touched 0 vertices. With it on: last-turn operations 66826 -> 19263, 8 -> 7 turns, 223 -> 126 s, final max AMIPS 8.69 -> 10.64, front faces 25816 -> 21042 under the same bar. Off by default until more runs confirm it; false keeps the TetWild gates.
◆ front_alignment_energy
| bool wmtk::components::topological_offset::Parameters::front_alignment_energy = true |
see the spec: needed at pressed seams, biased elsewhere
◆ front_measure
| std::string wmtk::components::topological_offset::Parameters::front_measure |
Which measure the single-phase loop exits on and refines by, in 3D and in 2D; see the spec. "vertex_ring" (the default): at each front vertex the RING MEASURE, the root mean square of the face measures (face_conv_ratio()) of its incident offset faces weighted by area – in 2D of the chord measures (edge_conv_ratio()) of its front chords weighted by length. The loop exits when every ring measure is within the bar and nothing is unmeasurable, and the halving takes each vertex over the bar alone. In 3D the front smoother's stencil energy weights its faces by area the same way (StencilEnergy3D::Face::weight). "face": every offset face (2D: chord) within the bar and the halving at the corners of every face over it – the rule of 2026-09-25, kept for comparison.
◆ max_iterations
| int wmtk::components::topological_offset::Parameters::max_iterations |
Cap of the shared TriWild/TetWild loop, which now runs in exactly one place: the frozen-front finishing pass.
◆ max_rounds
| int wmtk::components::topological_offset::Parameters::max_rounds = 40 |
The outer loop's budget in turns. The loop leaves on the front test; this is only the guard.
◆ optimize_offset
| bool wmtk::components::topological_offset::Parameters::optimize_offset |
See the spec: false stops the run at the constructed offset, optimize_offset() is not called and the constructed band is written as the result.
◆ pre_smooth
| bool wmtk::components::topological_offset::Parameters::pre_smooth |
See the spec: true runs one smoothing block (the fixed interleaved count, or the adaptive smoothing) before the first turn of the single-phase loop.
◆ sizing_collapse_min
| bool wmtk::components::topological_offset::Parameters::sizing_collapse_min = true |
What a collapse's surviving vertex keeps as its sizing scalar. true (the default): the smaller of the two, which is the shared engine's rule – refinement then never relaxes behind a travelling front. false: the survivor's own.
◆ sizing_gradation_mode
| std::string wmtk::components::topological_offset::Parameters::sizing_gradation_mode |
See the spec: how a lowered sizing scalar spreads to the vertices around it. "ring" = the base gradation_smooth_sizing, ring by ring at sizing_gradation x per ring; "distance" = TetWild's adjust_sizing_field ramp, a factor 0.5 at a seed rising linearly to 1 at distance 1.8 l, applied within that ball only.
◆ sphere_trace_initialization
| bool wmtk::components::topological_offset::Parameters::sphere_trace_initialization |
See the spec: the marching places each new vertex where d(x) reaches target_distance along the edge by sphere tracing, midpoint when the trace leaves the edge.
◆ sphere_trace_target_rel_tol
| double wmtk::components::topological_offset::Parameters::sphere_trace_target_rel_tol |
|d - target| <= tol x target ends the trace
The documentation for this struct was generated from the following file:
- /home/runner/work/wildmeshing-toolkit/wildmeshing-toolkit/components/topological_offset/wmtk/components/topological_offset/Parameters.h
