mod routing_probe

module routing_probe

Probe-based multimodality evidence for portfolio regime routing.

The static mean-width rule cannot separate a Styblinski-class multi-basin box from a least-squares valley of the same width: both present a moderate design box, but one rewards global heavy-tailed visiting while the other rewards deep local descent. This module spends a small, ledger-charged probe budget on short projected-gradient descents from spread starts and reports how many distinct basin depths the descents reach. Routing then commits to the global regime only when the probe shows at least two competitive basins.

Variables

const BASIN_DEPTH_REL_TOL: f64

Relative tolerance for grouping two descent endpoints into one basin depth class. The scale is the probe’s own observed descent range from the worst start value, so the classification is invariant to objective offset and scaling.

Functions

fn distinct_depth_classes(sorted_values: &[f64], depth_scale: f64) -> usize

Group sorted descent values into depth classes.

Two values belong to the same class when their gap is at most BASIN_DEPTH_REL_TOL of the probe’s depth scale max(worst_start - best_descent, |best_descent|, 1).

fn multimodality_probe<O, G>(obj: &O, grad: &G, bounds: &Bounds<f64>, starts: &[Array1<f64>], max_fevals_per_start: usize) -> Option<RoutingProbe>
where
    O: Objective<f64>,
    G: Gradient<f64>

Run n_starts short projected-gradient descents from spread starts and classify the endpoint depths.

Every evaluation and gradient call is charged to obj / grad by the caller’s budgeted wrappers; max_fevals_per_start bounds each descent. Returns None when fewer than two descents produced finite values.

Structs and Unions

struct RoutingProbe

Evidence gathered by multimodality_probe.

descent_values: Vec<f64>

Final objective values of each short descent, sorted ascending.

distinct_basins: usize

Number of distinct basin depth classes among the descents.

best_start_value: f64

Best raw (un-descended) start value observed.

worst_start_value: f64

Worst raw (un-descended) start value observed.

best_descent_value: f64

Best descended value.

Implementations

impl RoutingProbe

Functions

fn multimodal(&self) -> bool

Whether the probe found evidence of two or more competitive basins.