What the offset needs on top of the parameters every wmtk optimizer shares. More...

#include <Parameters.h>

Inheritance diagram for wmtk::components::topological_offset::Parameters:

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 = -1.0

double	envelope_size_rel = 1e-3

double	offset_dhat_factor

std::string	offset_field
	"smooth" (Phi level set) or "euclidean" (exact distance)

double	front_conv

double	front_conv_rel

bool	offset_collapse_veto = true

bool	offset_swap_veto = true

bool	offset_front_smooth_veto = false

bool	offset_collapse_changed_cells = true

double	offset_amips_weight = 1.

bool	debug_crossings = false
	Log-only: per pass, the front vertices whose ring measure crosses the bar (see the spec).

bool	front_pocket_split = true

bool	front_spanned_split = true

bool	exit_no_folds = true

std::string	coarsen_guard = "bar"

std::string	label_cleanup = "one_sided_at_target"

bool	sizing_collapse_min = true

bool	use_rest_pose = false

int	max_rounds = 30

int	stencil_order = 1

std::string	stencil_type = "subdivision"

std::string	front_measure

bool	sorted_marching

bool	save_offset_correspondence = false

std::string	construction_mode = "max_marchable_fallback"

double	sphere_trace_target_rel_tol

bool	init_optimize = false

int	init_optimize_stencil_order = -1

int	repulsion_smoothing_passes = 0

int	repulsion_rounds = 0

bool	split_energy_gate = false

std::string	band_volume_rule = "exact"

double	settle_stall_eps = 0.1

std::string	settle_test = "stall"

bool	settle_refinement = true

bool	gap_refinement = false

bool	damping = false

double	damping_factor = 0.5

bool	optimize_construction = true

std::string	growth_mode = "none"

int	linear_growth_steps = 4

int	smart_growth_attempts = 2
	growth_mode "smart": the turns an attempt gets to converge. At least 1 (the spec's min).

int	smart_growth_max_fails = 10

double	foldover_angle = 30.

bool	debug_remote_output = false

bool	debug_stencil = false

bool	allow_mult_comp = false

std::string	settle_mark = "vertex_edge"

std::string	output_path

bool	save_vtu

int	phi_grid_resolution

int	num_threads

int	max_iterations

double	offset_envelope = -1.

double	offset_envelope_rel = -1.

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	pre_smooth

VectorXd	box_min

VectorXd	box_max

Public Attributes inherited from wmtk::OptimizerParameters
bool	output_enabled = true

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	colored_smoothing = true

bool	check_surface_folds = false

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()

double wmtk::components::topological_offset::Parameters::front_conv_frac ( ) const

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.

Member Data Documentation

◆ allow_mult_comp

bool wmtk::components::topological_offset::Parameters::allow_mult_comp = false

TESTING (2026-10-16), 3D: an input complex of more than one connected piece is accepted; the energy's band term then reads the distance to all pieces at once. See the spec doc.

◆ band_volume_rule

std::string wmtk::components::topological_offset::Parameters::band_volume_rule = "exact"

EXPERIMENTAL (2026-10-12), 3D. The band term b(t) of a band cell in the energy (TopoOffsetTetMesh::band_cell_term()). "corner_bound": vol times the min over all input triangles P of the corner mean of (d_P - delta) / delta, an upper bound on the cell's part of int_B (d - delta) / delta dV that no split raises. "exact" (the default): J_t / delta, J_t = int_t (d - delta) dV in closed form (ExactBandIntegral); an upper bound only on its rule-(a) pieces. "front_flux": the operations as "exact", the front smoother's band term in the front form (flux of a field G with div G = d - delta through the band's boundary faces at the vertex, plus the bisector jumps D_t of its flagged cells). "exact_swept" (2026-10-22): "exact"'s energy, but each operation's rule reads the band integral's exact change where the band changes – value() on the tets a moving vertex's boundary faces of the band sweep, or on the cone over a flip's changed faces – instead of integrating whole cells before and after; the smoother searches on that same exact change (its derivatives by Reynolds' transport theorem over the band's boundary faces, or the ring cells' where a curved bisector crosses one), and its move is accepted on it, halved up to 4 times. See the spec doc and TopoOffsetTetMesh, EXACT SWEPT CHANGE. "surface" (2026-10-27): no band term; the offset term is a surface integral over the front, L / front_conv^2 (L the bounding box diagonal) sum over the offset faces of (A_f / |S|) sum over the stencil of (d - target_distance)^2 (TopoOffsetTetMesh::surface_face_term()). See the spec doc.

◆ coarsen_guard

std::string wmtk::components::topological_offset::Parameters::coarsen_guard = "bar"

EXPERIMENTAL_coarsen_guard (see the spec), 3D, read only with coarsen_pass: what judges a coarsening collapse. "bar" (the default): the survivor's offset faces must stay within the bar, face_criterion_rel() <= 1, and the front is collapsed only by length-limited passes. "no_rise" (2026-10-28): the max AMIPS of the cells a collapse changes may not rise, nor the offset error of the faces it changes (collapse_after_connectivity()); front vertices are collapsed too, only the final pass coarsens, and the coarsening runs after a loop that converges without a final pass.

◆ construction_mode

std::string wmtk::components::topological_offset::Parameters::construction_mode = "max_marchable_fallback"

How the marching places the offset (see the spec). A target_distance below the maximum marchable distance is traced to; otherwise "max_marchable_fallback" traces to half the maximum marchable distance and "midpoint_fallback" splits every marched edge at its midpoint. See marching_tris() / marching_tets().

◆ damping

bool wmtk::components::topological_offset::Parameters::damping = false

EXPERIMENTAL (2026-10-15), 3D: every smoothing solve of the loop may move its vertex at most damping_factor times the shortest edge at the vertex (to any vertex of its one-ring), measured from where the solve started (TopoOffsetTetMesh::damping_step(), SmoothVertexOptions::max_step). Never in a TetWild pass or the repulsion passes (TopoOffsetTetMesh::damping_active()). See the spec doc.

◆ damping_factor

double wmtk::components::topological_offset::Parameters::damping_factor = 0.5

EXPERIMENTAL (2026-10-15), 3D, with damping: the bound as a factor of the shortest edge at the vertex. 0.5 (the default) = half, the bound damping had before the key existed.

◆ debug_remote_output

bool wmtk::components::topological_offset::Parameters::debug_remote_output = false

DEBUG (2026-10-20), 3D: debug frames for a remote machine short on space – overrides DEBUG_output (sets it, so every debug computation runs) and writes only the constructed mesh, each TetWild pass's start and every iteration of it, the end of the construction TetWild pass, the end of every turn of the loop, and the final mesh. See the spec doc.

◆ debug_stencil

bool wmtk::components::topological_offset::Parameters::debug_stencil = false

DEBUG (2026-10-29), 3D, with DEBUG_output: every debug frame also writes <frame>_stencil.vtu, one point per stencil point of every offset face with its offset error. See the spec doc.

◆ exit_no_folds

bool wmtk::components::topological_offset::Parameters::exit_no_folds = true

EXPERIMENTAL_exit_no_folds (see the spec): the loop does not exit while a real fold with a foldover face (front_face_field_angle() over foldover_angle) remains.

◆ foldover_angle

double wmtk::components::topological_offset::Parameters::foldover_angle = 30.

3D: a front face is a foldover when the angle between its normal, out of the band, and the field's normal (grad d at its centroid) exceeds this many degrees (TopoOffsetTetMesh::front_face_field_angle()): the debug frames' per-face field_angle_foldover and the end-of-run [foldover] count, and which real folds hold the exit under EXPERIMENTAL_exit_no_folds. See the spec doc.

◆ front_measure

std::string wmtk::components::topological_offset::Parameters::front_measure

Which measure the 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_offset_term()) of its incident offset faces – in 2D of the chord measures (edge_offset_term()) of its front chords – every simplex weighted equally. 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. "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.

◆ front_pocket_split

bool wmtk::components::topological_offset::Parameters::front_pocket_split = true

EXPERIMENTAL_front_pocket_split (see the spec): before every smoothing pass of the loop, split every pinned cell until none is left (TopoOffsetTetMesh::front_pocket_split()).

◆ front_spanned_split

bool wmtk::components::topological_offset::Parameters::front_spanned_split = true

EXPERIMENTAL_front_spanned_split (see the spec): front_pocket_split() splits spanned edges and faces too, not only pinned cells.

◆ gap_refinement

bool wmtk::components::topological_offset::Parameters::gap_refinement = false

EXPERIMENTAL (2026-10-10), with EXPERIMENTAL_settle_refinement: on a settled turn a band cell with a front corner is also refined (its corners halved) when md - d(centroid) > front_conv, md the corner mean of the bounding triangle's distance (the corner bound's own min). Where d is convex on the cell, Vol (md - d(c)) / delta bounds the corner bound's gap (bound - true integral) from above (Jensen). Exit also needs no such cell. See the spec doc.

◆ growth_mode

std::string wmtk::components::topological_offset::Parameters::growth_mode = "none"

3D (2026-10-21; "linear" was EXPERIMENTAL_incremental_growth): how the loop grows the offset when the march traces the front below target_distance (construction_mode "max_marchable_fallback", the target not below the maximum marchable distance), from the traced distance d_0. "none": the ordinary loop at target_distance. "linear": loops at d_0 and at d_0 + k (target_distance - d_0) / linear_growth_steps, each to convergence, the last the ordinary loop (TopoOffsetTetMesh::linear_growth()). "smart": a loop at d_0, then attempts toward target_distance, reverted and halved when they fail (TopoOffsetTetMesh::smart_growth()). "individual_op_reject": loops at d_0 and at target_distance (linear with one step), every collapse, offset-surface flip and smoothing move that raises the folded offset faces refused (TopoOffsetTetMesh::fold_reject_active()). See the spec doc.

◆ init_optimize

bool wmtk::components::topological_offset::Parameters::init_optimize = false

Default false. Only when the target is not below the maximum marchable distance (marched as construction_mode says): the loop first converges under stencil_order without refinement, then under stencil_order with refinement. See the spec doc.

◆ label_cleanup

std::string wmtk::components::topological_offset::Parameters::label_cleanup = "one_sided_at_target"

EXPERIMENTAL_label_cleanup (see the spec), 3D: after each operation group's operation passes, cells on the wrong side of the level set flip between band and non-band where the flip keeps both labels' topology (TopoOffsetTetMesh::label_cleanup()). "off", "one_sided", "one_sided_tips", "one_sided_at_target" (the default) or "energy_decrease" (it needs band_volume_rule "surface").

◆ linear_growth_steps

int wmtk::components::topological_offset::Parameters::linear_growth_steps = 4

growth_mode "linear": N, the steps from d_0 to target_distance, so N + 1 loops. At least 1 (the spec's min).

◆ max_iterations

int wmtk::components::topological_offset::Parameters::max_iterations

Cap of the shared TriWild/TetWild loop, which runs only in the TetWild passes: the final pass, and in 3D the construction pass (optimize_construction).

◆ max_rounds

int wmtk::components::topological_offset::Parameters::max_rounds = 30

The outer loop's budget in turns. The loop leaves on the front test; this is only the guard.

◆ offset_amips_weight

double wmtk::components::topological_offset::Parameters::offset_amips_weight = 1.

The weight w of AMIPS in the per-cell energy: in 3D the energy's AMIPS term, (w / stop_energy^3) vol AMIPS^3 (TopoOffsetTetMesh::cell_energy()); in 2D tri_energy = w AMIPS + the offset terms. See the spec.

◆ optimize_construction

bool wmtk::components::topological_offset::Parameters::optimize_construction = true

3D, with optimize_offset (2026-10-21): before the loop, TetWild's own pass on the mesh as constructed, from the sizing field at 1 everywhere, the offset surface held in an envelope of half the distance the march traced it to (TopoOffsetTetMesh::optimize_construction_pass()). Ignored when optimize_offset is false. See the spec doc.

◆ 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) before the first turn of the loop.

◆ repulsion_rounds

int wmtk::components::topological_offset::Parameters::repulsion_rounds = 0

2D and 3D. After those passes, at most this many rounds of the loop's operations (split, collapse, swap, each with its smoothing) before the march, with no refinement and no split of a marched edge; same stop test. 0 (the default) = off. See the spec doc.

◆ repulsion_smoothing_passes

int wmtk::components::topological_offset::Parameters::repulsion_smoothing_passes = 0

Smoothing passes before the march that push the outer ends of the marched edges out to 2 x target_distance; they stop early once every outer end is beyond target_distance + front_conv. 0 (the default) = off. See the spec doc and TopoOffsetTetMesh::repulsion_smoothing() / TopoOffsetTriMesh::repulsion_smoothing().

◆ save_offset_correspondence

bool wmtk::components::topological_offset::Parameters::save_offset_correspondence = false

Construction only (optimize_offset false), 2D and 3D: the output .msh carries the node field corr_input_vid, each offset vertex's input-complex vertex (see the spec).

◆ settle_mark

std::string wmtk::components::topological_offset::Parameters::settle_mark = "vertex_edge"

EXPERIMENTAL (2026-10-09), read only under settle_refinement: the test that marks the front on a settled turn. "vertex": a front vertex's own |d - target_distance| exceeds front_conv; its sizing is halved. "vertex_edge" (the default): "vertex", and also both ends of a front edge whose ends are within front_conv and whose midpoint is not have their sizing halved (they do not hold the exit). "vertex_split": "vertex", and also a front face whose corners are within front_conv but an edge midpoint or its centroid is not has its worst edge split before the next turn's first smoothing pass (needs EXPERIMENTAL_front_pocket_split). "max": a face's max of |d - target_distance| exceeds front_conv (exact up to rounding; an upper bound on rule-(a) pieces, see ExactBandIntegral::max_distance()). "rms": a face's share of the offset excess exceeds its bar energy, X_f = (1/2 delta) int_f (d - delta)^2 cos(theta) dA > front_conv^2 area(f) / (2 delta), i.e. the mean over f of (d - delta)^2 cos(theta) exceeds front_conv^2 (theta between the face's normal, out of the band, and grad d; signed), by the 3-edge-midpoint rule. "stencil" (2026-10-28): a face with a point of its offset stencil (stencil_order, EXPERIMENTAL_stencil_type) at or beyond front_conv, (d - target_distance)^2 >= front_conv^2, or unmeasurable, has its corners' sizing halved; the exit needs none, i.e. every stencil point within front_conv. See the spec doc.

◆ settle_refinement

bool wmtk::components::topological_offset::Parameters::settle_refinement = true

EXPERIMENTAL (2026-10-09), 3D. Refinement and exit wait for the front to settle: a turn is settled when the offset energy (E without its AMIPS term) fell by less than the bar energy b = front_conv^2 A / (2 target_distance), A the front's area – the offset term's excess for a front lying front_conv off the level set. On a settled turn every front face whose distance from the level set (the face's min of d, and its max of d, ExactBandIntegral::max_distance()) exceeds front_conv has its corners halved; exit = settled and no face over. The energy criterion's own refinement and exit are off. See the spec doc.

◆ settle_stall_eps

double wmtk::components::topological_offset::Parameters::settle_stall_eps = 0.1

EXPERIMENTAL_band_volume_rule "surface" only: the settle test's stall threshold. O* = the max over the front's stencil points of (d - target_distance)^2; a turn is settled when O* < front_conv^2 or O*_prev - O* <= settle_stall_eps (O* - front_conv^2) – TetWild's stall test on the max offset error. See the spec doc.

◆ settle_test

std::string wmtk::components::topological_offset::Parameters::settle_test = "stall"

EXPERIMENTAL_band_volume_rule "surface" only: which settle test. "stall" (the default): O* stall test above (settle_stall_eps). "bar": the volume rules' bar test on the surface integral – settled when O_g = int over the front of (d - target_distance)^2 fell by less than front_conv^2 times the front's area, O_g of a front one front_conv off everywhere.

◆ 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.

◆ smart_growth_max_fails

int wmtk::components::topological_offset::Parameters::smart_growth_max_fails = 10

growth_mode "smart": the failed attempts allowed from one converged distance before the run gives up (throws). At least 1 (the spec's min).

◆ sphere_trace_target_rel_tol

double wmtk::components::topological_offset::Parameters::sphere_trace_target_rel_tol

|d - D| <= tol x D ends the trace (D: see above)

◆ split_energy_gate

bool wmtk::components::topological_offset::Parameters::split_energy_gate = false

EXPERIMENTAL (2026-10-09). Every loop split is committed only if E, summed over the cells it changes, strictly falls – judged right after the split, before any smoothing.

◆ stencil_type

std::string wmtk::components::topological_offset::Parameters::stencil_type = "subdivision"

EXPERIMENTAL_stencil_type (3D, 2026-10-28): which points stencil_order's face stencil holds. "subdivision" (the default): the lattice above, subdivision_face_stencil(). "interior": interior_face_stencil(), (i, j, l) / (k + 2), i, j, l >= 1. "fem": fem_face_stencil(), the degree-k Lagrange nodes (i, j, l) / k, i, j, l >= 0 (order 1 the corners, 2 + the edge midpoints, 3 + two per edge and the centroid), weighted by their lumped area weights (fem_face_stencil_weights()). "interior" and "fem" need stencil_order >= 1. See the spec doc. 2D does not read it.

◆ use_rest_pose

bool wmtk::components::topological_offset::Parameters::use_rest_pose = false

3D: the medium outside the band and the input complex is plastic during the loop – its AMIPS term against a rest shape stamped before every operation group and smoothing block. false: equilateral AMIPS for every cell. See the spec doc.

The documentation for this struct was generated from the following file:

components/topological_offset/wmtk/components/topological_offset/Parameters.h

Public Member Functions

Public Attributes