OptimizerParameters.h

#pragma once
 
#include <limits>
#include <string>
#include <wmtk/utils/Logger.hpp>
 
namespace wmtk {
 
struct OptimizerParameters
{
    bool output_enabled = true; // private execution policy, never a JSON algorithm option
    double epsr = 1e-3; // relative error bound (wrt diagonal)
    double eps = -1.; // absolute error bound
    double lr = 5e-2; // target edge length (relative)
    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;
 
    // ---- Stuck-element sizing refinement --------------------------------
    // Trigger threshold: fire when the last iteration's improvement is small compared
    // with the distance the max energy still has to cover, i.e. refine when
    //     (prev_max - max) <= stall_eps * (max - target).
    // Equivalently: refine unless the mesh is on course to reach the target within
    // about 1/stall_eps more iterations. 0 => only when it does not improve at all.
    //
    // The denominator is the remaining distance, not prev_max, and that is the whole
    // point. Measured against prev_max, a mesh grinding down at a steady 1.3% per
    // iteration toward a target far below clears a 1% bar every single iteration and so
    // never looks stalled -- even though at that rate it needs on the order of a hundred
    // more iterations and the operations have in fact deadlocked. The escape hatch then
    // never fires, which is exactly the regime it exists for.
    double stuck_refine_stall_eps = 0.1;
    // Cooldown: after a refinement, skip this many improvement iterations before
    // refining again, so the operations get full passes to act on the new sizing
    // field before more refinement is added. 0 => may refine every iteration.
    //
    // 1, because refining every iteration can outrun the operations entirely. On
    // triwild20k 189017 at eps_rel 1e-4 the field ratchets down faster than split and
    // collapse can act on it: the mesh sits at ~31k faces for a dozen iterations, then
    // runs away 54k -> 96k -> 159k -> 5.8M and never converges, its max energy pinned at
    // the inverted sentinel. At cooldown 1 the same run climbs deliberately to 181k and
    // converges at 9.9994 in 35 iterations. Cooldown is the narrow instrument for this:
    // it slows the refinement rather than licensing collapse to undo refinement.
    //
    // Cost, measured over the 31 challenging models at stop_energy 10, cooldown 0 -> 1:
    //
    //     tetwild   iterations 185 -> 196 (+5.9%)  elements -1.8%  wall -5.3%
    //     triwild   iterations 166 -> 173 (+4.2%)  elements -0.1%  wall -6.2%
    //
    // A few percent more iterations, slightly fewer elements, and no wall-time cost -- the
    // extra iterations are cheaper ones. 1 is the knee: 2 and 3 buy a further 2-4% element
    // reduction in tetwild for +34% and +76% iterations.
    //
    // This supersedes an earlier reading of a 468-model triwild20k sweep, where cooldown 1
    // cost ~13% wall for identical mesh sizes and was taken as evidence that a cooldown
    // only delays the next escape. That holds where the escape hatch is not load-bearing;
    // it does not hold on the models where it is.
    int stuck_refine_cooldown = 1;
    // Number of worst cells (by energy) whose neighborhoods are refined.
    int stuck_refine_num_worst = 0;
    // Graph rings around each worst cell's vertices included in the refinement.
    int stuck_refine_rings = 0;
    // Multiplicative reduction of m_sizing_scalar per refinement (0.5 => /2).
    double stuck_refine_factor = 0.5;
    // Lower bound on m_sizing_scalar. Much smaller than the old l_min/l floor;
    // still far above the position-rounding scale so it stays numerically safe.
    double stuck_refine_min_scalar = 1e-3;
    // Gradation cap for the monotone sizing smoothing: neighboring sizings may
    // differ by at most this factor. The smoothing only ever *lowers* sizings
    // (spreads refinement outward), never raises the refined values, avoiding
    // sharp resolution jumps that make operations ill-conditioned.
    double stuck_refine_gradation = 2.0;
    // Force-split: when the max energy stalls, split each worst cell's longest edge
    // once, bypassing the split length gate. This unsticks a sliver whose edges are
    // too short to be split-eligible, WITHOUT touching the sizing field (which the
    // *factor ratchet above still drives). Adds at most one split per worst cell per
    // stall, so it does not bloat the element count.
    //
    // This deliberately applies to EVERY worst cell, including one already at its target
    // size. There used to be a stuck_refine_force_split_oversized_only gate that skipped
    // those, on the argument that AMIPS is scale invariant so subdividing a badly shaped
    // cell yields two badly shaped cells. The argument is sound about the cell itself and
    // wrong about the outcome: force-splitting it also refines its NEIGHBOURHOOD, and that
    // is what breaks a deadlocked configuration open. On Thingi10K 46024 -- the one model of
    // 10,000 in the sweep that finished above stop_energy -- the gate refused ~2000 tets on
    // every stall, the max energy froze at iteration 3 and stayed identical to 15 significant
    // figures for the remaining 77 iterations (4.6 h). Without the gate the same model
    // converges to 9.98 in 14 iterations and 11 minutes.
    bool stuck_refine_force_split = true;
 
 
    // ---- Skip good regions ----------------------------------------------
    // Only smooth vertices incident to a cell whose energy is >=
    // skip_good_regions_margin * stop_energy. Smoothing a vertex surrounded by
    // good cells does nothing, so skipping it is free (14-16x faster smooth
    // passes). Only smoothing is gated: gating the topology/sizing ops
    // (split/collapse/swap) starves the optimizer and blows up the element
    // count, so those always run over the whole mesh.
    bool skip_good_regions = false;
    // Safety margin on the "active" threshold: a cell is active when its energy is >= this
    // fraction of stop_energy, so vertices near cells sitting just below the target are
    // still smoothed.
    double skip_good_regions_margin = 0.9;
 
    double splitting_l2 = -1.; // the lower bound length (squared) for edge split
    double collapsing_l2 =
        std::numeric_limits<double>::max(); // the upper bound length (squared) for edge collapse
 
    double stop_energy = 100;
 
    double w_amips = 1e-4;
    std::string smoothing_mode = "projected";
    int project_line_search_steps = 12;
    int project_line_search_nested_steps = 0;
 
    bool smooth_quality_veto = true;
    double w_envelope = 1. - 1e-4; // derived; not read from json
 
    int num_smoothing_passes = 2;
    bool colored_smoothing = true;
    bool check_surface_folds = false;
    bool interleaved_smoothing = true;
    int interleaved_smoothing_passes = 1;
 
    // ---- Coarsening pass -------------------------------------------------
    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;
 
    void init_lengths_from_diagonal(const double diag)
    {
        diag_l = diag;
        if (l > 0) {
            lr = l / diag_l;
        } else {
            l = lr * diag_l;
        }
        splitting_l2 = l * l * (16 / 9.);
        collapsing_l2 = l * l * (16 / 25.);
 
        if (eps > 0) {
            epsr = eps / diag_l;
        } else {
            eps = epsr * diag_l;
        }
 
        logger().info("PARAMS: eps = {}, l = {}", eps, l);
    }
};
 
} // namespace wmtk