Fine-W+: experimental thorough param tuning Proposed

Adaptive multi-mode sampling for 1D parameter search. Coexists with the existing Fine-W / Size / WH binary-search modes.

Date: 2026-04-27 Scope: libmodal + modal_viewer/{app,ui} Item: #10 (1D first) Plan: 5 commits

¶Goal

Replace the current 1D bisection — which often fails because it assumes a monotonic param → freq map — with an adaptive sampler that (a) records every (param, freq, mode-amplitude) triple it has ever evaluated for the current note, (b) chooses each next sample by intermediate-value bracketing or unexplored-region density, and (c) matches against any mode whose strike amplitude clears an audibility threshold rather than only the fundamental.

The existing Fine-W / Fine-Size / Fine-WH modes are kept unchanged. The new tuner is exposed as Fine-W+ alongside them.

¶Theoretical framing

The 1D tuning problem:

Find x ∈ [lo, hi] such that some mode k has freq_k(x) ≈ target and |amp_k(x)| is large enough to be heard, where (freq_k, amp_k) come from the eigensolve at parameter x.

The current code reduces this to "find x such that freq[0](x) = target" via bisection. Bisection converges only when freq[0](x) is monotonic in x, which fails for our shapes because:

Mode reordering. As x grows, mode 1 may drop below mode 2; the identity of "the lowest mode" switches at a crossing. The lower-envelope freq[0] has a kink there.
Differential scaling. Bending modes scale ~1/L², longitudinal modes scale ~1/L. Different modes dominate at different sizes.
Localised modes. In shapes with sub-features (legs, strings, rings), some modes are governed by the sub-feature's geometry, not the overall scale parameter.

Each individual freq_k(x) IS continuous and locally monotonic within a "mode regime" — by the Intermediate Value Theorem, a root exists in any interval where freq_k brackets the target. The right approach is to sample the function densely enough to detect brackets across all relevant modes, then refine.

¶Design

Five components, in implementation order. Each commits independently.

1. `modal_compute_strike_amplitudes` (libmodal)

Expose the boundary-normal projection that modal_strike already does internally, so the viewer can query "what would the per-mode strike amplitudes be at this position?" without mutating audio state.

// Pure read; no mode_states_, vis_impulses_, or strike_buf side effects.
// Writes up to n_modes_max amplitudes (or fewer if fewer modes exist).
// Returns the actual count written.
int modal_compute_strike_amplitudes(
    ModalResult* res, float x, float y,
    float* out_amps, int n_modes_max);

Refactor the existing compute_strike_impulse (added in #9, commit a05bdbc) to share the projection code with this new function. ~30 LOC net.

2. `Sample` and the sample database

struct Sample {
    float param;                  // x value (width for Fine-W+)
    std::vector<float> freqs;     // top-K mode frequencies
    std::vector<float> amps;      // strike amplitude per mode
    int   best_mode;              // index of best-matching audible mode (or -1)
    float best_cents;             // signed cents from target for best_mode
    float best_amp_norm;          // |amps[best_mode]| / max_i|amps[i]|
    bool  quiet;                  // best_amp_norm < min_audible_ratio
};

Database lives on App as std::vector<Sample> param_db_, kept sorted by param. Cleared on session start (Fine-W+ click) and on Reset.

K defaults to 24 modes per sample. Eigensolve already computes them; storing freq/amp arrays adds ~200 bytes per sample.

Selecting best_mode: the closest-to-target mode whose |amps[i]| / max|amps| ≥ min_audible_ratio. If none qualifies, fall back to closest-overall and set quiet = true. This keeps the algorithm prefering audible matches but doesn't crash when no audible mode exists.

3. The adaptive sampler

Per-session state on App:

Field	Meaning	Default
`fine_budget_`	Max samples per session	64
`fine_min_audible_`	Mode amplitude threshold (fraction of loudest)	0.1
`param_db_`	Sorted (param, ..) samples	{}
`init_seeded_`	True after the initial 8-sample sweep	false

Algorithm (per Phase-4 invocation):

1. Insert just-completed Sample into param_db_ (sorted).
2. If !init_seeded_:
       Pick next of 8 evenly-spaced params in [fine_lo_, fine_hi_].
       If all 8 done: init_seeded_ = true. Else hand to Phase 2 and stop.
3. best_sample = sample with min |best_cents| where !quiet.
4. Termination checks:
     a. CONVERGED:           best_cents < threshold AND !quiet → apply.
     b. BUDGET_EXHAUSTED:    param_db_.size() ≥ fine_budget_ → apply suboptimal.
     c. DENSITY_EXHAUSTED:   min adjacent gap < (hi-lo)/10000
                             AND best_cents > 2 × threshold → apply suboptimal,
                             status: "1D search exhausted — try Fine-WH+ later."
5. Score every region (consecutive sample pair):
     BRACKET (priority 0): sign change in best_cents → must contain a root.
                           score = 1 / (|ci| + |cj| + 1e-3),  pick = midpoint.
     NEAR_BEST (1):        adjacent to current best.
                           score = 1 / (|best_cents| · gap),  pick = best ± 0.3·gap.
     GAP (2):               otherwise.  score = gap / total_range,  pick = midpoint.
6. Choose highest-scoring region (tie-break by priority).
7. Hand pick.param to Phase 2 (build_with_param). Loop.

"Running in circles" detection is structural: every iteration produces a new sample at a previously-unsampled param. The minimum-gap density check catches the case where the algorithm has refined as much as 1D can ever express — that's the signal to suggest Fine-WH+ later.

4. State-machine integration

fine_mode_ gains a new value 4 (Fine-W+). Existing values 1/2/3 keep their behaviour.

Phase 1 / 3 (wait_strike, wait_sound) — identical for all modes.
Phase 2 (build_with_param) — for mode 4, the param to build with comes from pick_next_sample_for_adaptive(). For modes 1/2/3, unchanged.
Phase 4 (read result) — branches:
- Modes 1/2/3: existing binary-search step.
- Mode 4: build a Sample (read freqs + compute strike amps), insert into param_db_, run the adaptive sampler step.

The Auto-mode glue from #6C already takes a mode number in start_fine_tune_for_target(int mode); passing 4 re-arms Fine-W+ for the next note transparently.

5. UI changes

Toolbar Row 3 gains one button + two sliders:

The new [Fine-W+] button starts mode 4. The two new sliders share Row 3's adaptive-wrap behaviour from #1.

Chart augmentation: when fine_mode == 4, the existing "binary search segment" view at the top of the Tuning Chart is replaced by a true histogram:

X axis: parameter value (the searched dimension).
Y axis: frequency in Hz (log-scale), with a horizontal target band.
Each sample: dot at (param, freqs[best_mode]), coloured by |best_cents|: green ≤ threshold, yellow ≤ 4 × threshold, red beyond.
Glyph: filled circle for audible (!quiet), hollow circle for quiet.
Best-so-far: extra ring (same as today).

The "Frequency vs attempt" plot stays unchanged below the histogram — gives time-ordered context. So the chart shows both views in Fine-W+ mode (per your request).

¶New configuration

Variable	Type	Default	Range	UI
`fine_budget_`	`int`	64	16..4096	Drag slider in Row 3
`fine_min_audible_`	`float`	0.1	0.01..0.5	Drag slider in Row 3
`tune_threshold_cents_`	`float`	5.0	unchanged	(existing)

Budget = 64 means up to 64 evaluations per note × ~10 ms per eval ≈ 0.6 s wall time on the current machine. Budget = 4096 ≈ 40 s — useful for difficult shapes when run unattended (Auto mode).

¶Failure modes & edge cases

Strike position not yet recorded. Phase 1 still waits for the user's first strike. Once recorded, the rest is automatic.
All modes quiet at every sample. Algorithm exhausts budget without an audible hit; reports quiet suboptimal. User re-strikes off-centre.
Target outside the achievable frequency range. Density-exhaustion fires. User widens [lo, hi] (currently hardcoded at 0.3 × initial → 3 × initial; could be exposed later).
Budget set very low. Pre-warn at < 24: "Budget very low; increase for better results."
Memory growth. Worst case 4096 × ~200 bytes ≈ 800 KB per session. Cleared on session start. Negligible.
Eigensolve order matters across samples. Eigensolver returns ascending order — mode reordering shows up as freqs[0] discontinuity. The multi-mode match handles this: we don't track mode identity, only "any matching mode."

¶Out of scope

Fine-Size+ and Fine-WH+. Genuine 2D adaptive sampling needs different priority scoring (Latin-hypercube seeding, 2D bracket detection). Deferred until 1D is validated.
Bayesian Optimisation with Gaussian Process surrogate. Theoretically optimal for expensive black-box optimisation but ~500 LOC of new code (or a library dependency). Deferred unless 1D Fine-W+ proves insufficient.
Brent's method as a refinement step inside a bracketing region. Could add later if further evaluation budget reduction matters; for now bisection-of-bracket is fine.
Mode-tracking via continuation (computing per-mode trajectories across param values to follow specific modes through crossings). Useful for Fine-WH+; not needed for 1D multi-mode matching.
Auto-widening [lo, hi]. User controls it via re-running with manual width adjustment.

¶Acceptance criteria

With Fine-W+ selected and an arbitrary 1D-tunable shape struck off-centre, the algorithm reaches |cents| < threshold for the audible best mode in ≤ 64 evaluations on shapes where any of Fine-W/Fine-WH would also converge.
On shapes where bisection fails (e.g. a shape with a known mode crossing in [lo, hi]), Fine-W+ finds an audible match where bisection cannot. Verified manually on at least one such shape.
Density-exhaustion path produces the "try Fine-WH+ for this note" status message and accepts suboptimal=true.
Budget-exhaustion accepts suboptimal=true. Note shows orange.
Auto mode (#6C) drives Fine-W+ end-to-end across all 8 notes when Fine-W+ is the chosen mode.
The histogram chart renders correctly with at least 1 sample, with proper colour coding for in-threshold / close / far / quiet.
Existing modes (Fine-W, Fine-Size, Fine-WH) remain byte-identical in behaviour.

¶Implementation plan

libmodal — modal_compute_strike_amplitudes (refactor + new function). ~30 LOC.
Sample DB — Sample struct, param_db_, sample-insertion helper, best-mode selection. ~80 LOC.
Adaptive sampler — pick_next_param_adaptive(), region scoring, termination checks. ~150 LOC.
State machine integration — fine_mode_ = 4 dispatch in Phase 2 and Phase 4; Auto-mode integration. ~50 LOC.
UI — [Fine-W+] button, Budget + MinAudible sliders, histogram chart view (replaces "binary search segment" when fine_mode == 4). ~80 LOC.

Total ~390 LOC across libmodal/src/modal_api.cpp, modal_viewer/src/app/app.{cpp,h}, modal_viewer/src/ui/ui_manager.{cpp,h}. No new files.