Struct ContinuationPath 

pub struct ContinuationPath { /* private fields */ }

Object 1 — the coupled continuation path. Owns the three schedules and the scalar path parameter s, and drives the K≥2 SAE joint fit down the coupled homotopy. Entry is always s = 1 (heavy-smoothing contraction regime); the tail is a homotopy floor with no rejection exit.

The wiring agent drives the path one waypoint at a time: let step = path.step(obj, &mut ledger); and, per [ContinuationStep], installs the next waypoint’s ScalarLegTargets (τ on the SAE term, isometry weight on the gauge penalty) and applies the LogitTrustRegion / ActiveMassFloor hooks inside the inner solve.

Implementations

impl ContinuationPath

pub fn enter(schedules: CoupledSchedules) -> Self

Build the coupled path. s is initialized to 1.0 — the heavy-smoothing entry regime where the joint inner solve is a contraction. The path can only be entered here; there is no constructor that starts cold at the real objective. This is what makes warm-invariance (#969) structural: any entry, warm or cold, funnels through the s = 1 contraction fixed point.

pub fn heavy_entry() -> Self

No-argument heavy-smoothing entry for a continuation-entry objective (the seed cascade ctor). Builds the default coupled schedules — a single-component oversmoothed ρ leg, the standard diffuse→sharp τ leg and the loose→tight isometry gauge leg — and enters at s = 1, the heavy-smoothing contraction regime. The seed cascade only reads the coarse PathRegime and the logit step radius from the path; the concrete ρ vector is replaced by the spine’s own per-component target at each waypoint via ContinuationPath::current_rho_target, so the single-component default here is the entry placeholder, not a constraint on the real fit’s dimensionality.

pub fn heavy_entry_for_rho( rho_target: Array1<f64>, bounds_upper: Array1<f64>, ) -> Self

Heavy-smoothing entry coupled to a CONCRETE ρ target and legal box. The seed cascade rebuilds the path per-seed with this once it knows the objective’s real ρ dimension (the no-argument ContinuationPath::heavy_entry is a dimension-1 placeholder used only before the seed is in hand). The ρ leg rides the spine from the spine’s own oversmoothed ρ₀ down to rho_target (the real objective ρ*); bounds_upper is the legal ρ box. The τ / isometry legs use the standard diffuse→sharp / loose→tight default endpoints. Enters at s = 1, the heavy-smoothing contraction regime. rho_target and bounds_upper must share length.

pub fn enter_regime(&self) -> PathRegime

The coarse heavy-smoothing regime the path is currently entering at. The seed cascade reports this in its demotion ledger and final diagnosis. A fresh ContinuationPath::heavy_entry is in PathRegime::Heavy.

pub fn demote_with_reason(&mut self, reason: PathDemotionReason) -> PathRegime

Demote the seed cascade to a heavier path regime with a recorded reason and return the regime re-entered at. This is the regime-escalation view of re-entry: it routes onto the same ContinuationPath::reenter_heavier mechanism a spine struggle or a mass-floor breach uses (raise s toward the entry regime, refine the step), so a structural diagnosis becomes a heavier-regime RE-ENTRY of the same seed — never a rejection. The reason is a diagnostic tag the caller records alongside the returned regime; the demotion mechanism is identical for every reason.

pub fn logit_step_radius(&self) -> f64

The base radius the per-iteration assignment-logit trust region is built from (rho_optimizer.rs / atom_selection.rs hardening hook). This is the ∞-norm logit step radius at the current waypoint; heavier regimes (after a demotion / re-entry) cool τ and so hand back a tighter radius, shrinking every atom’s logit cap with no separate knob.

pub fn note_active_mass_breach(&mut self) -> PathRegime

Bare active-mass-floor breach hook for the inner-loop call site that does not thread its own ReseedLedger. Records the breach in the path-owned ledger at the current s and re-enters a heavier regime — the same non-fatal response as ContinuationPath::note_mass_breach, without requiring the caller to carry a ledger. Returns the heavier PathRegime re-entered at so the call site can report it. Never fatal — a breach is a re-entry, never a rejection.

pub fn reseed_count(&self) -> usize

Number of scaffold re-seeds recorded through the bare ContinuationPath::note_active_mass_breach hook (diagnostics).

pub fn s(&self) -> f64

Current path parameter s ∈ [0, 1].

pub fn current_scalar_targets(&self) -> ScalarLegTargets

The scalar leg targets (τ, isometry weight) at the current s. The wiring agent installs these before the inner solve at this waypoint.

pub fn current_rho_target(&self) -> Array1<f64>

The ρ target the spine should anneal toward at the current s.

pub fn logit_trust_region(&self) -> LogitTrustRegion

The per-waypoint logit trust region (from the current τ). The wiring agent caps each assignment-logit Newton step with this.

pub fn active_mass_floor(&self) -> ActiveMassFloor

The active-mass floor for this path. The wiring agent calls ActiveMassFloor::check with the observed mean active mass each inner iteration and, on breach, records a scaffold re-seed in the ledger and reports it back via ContinuationPath::note_mass_breach.

pub fn arrived(&self) -> bool

Whether the path has arrived at (or below) the real objective s = 0. The outer driver stops driving ContinuationPath::step once this is true and hands the warm iterate to the normal optimizer at ρ*.

Trait Implementations

impl Clone for ContinuationPath

fn clone(&self) -> ContinuationPath

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ContinuationPath

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.