Struct AdaptiveMuUpdate 

pub struct AdaptiveMuUpdate {

    pub mu_oracle: MuOracleKind,
    pub adaptive_mu_globalization: AdaptiveMuGlobalization,
    pub adaptive_mu_kkt_norm: AdaptiveMuKktNorm,
    pub adaptive_mu_safeguard_factor: Number,
    pub adaptive_mu_kkterror_red_iters: usize,
    pub adaptive_mu_kkterror_red_fact: Number,
    pub filter_max_margin: Number,
    pub filter_margin_fact: Number,
    pub mu_min: Number,
    pub compl_inf_tol: Number,
    pub mu_max: Number,
    pub mu_max_fact: Number,
    pub tau_min: Number,
    pub mu_init: Number,
    pub barrier_tol_factor: Number,
    pub mu_linear_decrease_factor: Number,
    pub mu_superlinear_decrease_power: Number,
    pub adaptive_mu_monotone_init_factor: Number,
    pub restore_accepted_iterate: bool,
    pub sigma_max: Number,
    pub sigma_min: Number,
    pub qf_norm_type: NormType,
    pub qf_centrality_type: CentralityType,
    pub qf_balancing_term: BalancingTermType,
    pub qf_max_section_steps: i32,
    pub qf_section_sigma_tol: Number,
    pub qf_section_qf_tol: Number,
    pub probing_iterate_quality_factor: Number,
    /* private fields */
}

Fields

mu_oracle: MuOracleKind

adaptive_mu_globalization: AdaptiveMuGlobalization

adaptive_mu_kkt_norm: AdaptiveMuKktNorm

adaptive_mu_safeguard_factor: Number

adaptive_mu_kkterror_red_iters: usize

adaptive_mu_kkterror_red_fact: Number

filter_max_margin: Number

filter_margin_fact: Number

mu_min: Number

compl_inf_tol: Number

Complementarity tolerance — option compl_inf_tol, default 1e-4 per IpAlgorithmRegOp.cpp. Not used directly by the adaptive update; enters only through Self::certificate_safe_mu_min, which caps mu_min so a strongly scaled-down objective can still reach the termination certificate (pounce#266) — the μ floor lives in scaled space while compl_inf_tol is enforced on the unscaled complementarity.

mu_max: Number

Upper bound on μ. Sentinel -1.0 means “not yet computed; init lazily on the first update_barrier_parameter call to mu_max_fact * curr_avrg_compl()”. Mirrors IpAdaptiveMuUpdate.cpp:160-165 (load step) and IpAdaptiveMuUpdate.cpp:267-274 (lazy init).

mu_max_fact: Number

mu_max_fact (default 1e3) — factor for lazy init of mu_max. Upstream IpAdaptiveMuUpdate.cpp:RegisterOptions line 42. Ignored if the user explicitly sets mu_max to a non-sentinel value.

tau_min: Number

tau_min from IpAdaptiveMuUpdate.cpp:RegisterOptions. Used to derive curr_tau = max(tau_min, 1 - mu) after each update, mirroring upstream’s IpAdaptiveMuUpdate.cpp:UpdateBarrierParameter at the post-oracle update.

mu_init: Number

Initial mu seed — mu_init from IpoptAlgorithm registered options. Used to seed curr_mu in initialize.

barrier_tol_factor: Number

barrier_tol_factor (default 10) from upstream IpMonotoneMuUpdate::RegisterOptions. Threshold for fixed-mode barrier subproblem completion: reduce μ when curr_barrier_error ≤ barrier_tol_factor · μ.

mu_linear_decrease_factor: Number

mu_linear_decrease_factor (default 0.2) — fixed-mode update uses min(linear · μ, μ^superlinear_power).

mu_superlinear_decrease_power: Number

mu_superlinear_decrease_power (default 1.5).

adaptive_mu_monotone_init_factor: Number

adaptive_mu_monotone_init_factor (default 0.8). Used by new_fixed_mu when no fix_mu_oracle_ is configured.

restore_accepted_iterate: bool

adaptive_mu_restore_previous_iterate (default false).

sigma_max: Number

sigma_max / sigma_min forwarded to QualityFunctionMuOracle on every free-mode call. sigma_max is additionally forwarded to ProbingMuOracle (upstream IpProbingMuOracle.cpp reads the same sigma_max option to cap its centering parameter — L3). Defaults from IpQualityFunctionMuOracle.cpp:RegisterOptions.

sigma_min: Number

qf_norm_type: NormType

quality_function_norm_type (default 2-norm-squared) — norm used to aggregate the three KKT components inside the quality function. Forwarded to QualityFunctionMuOracle on every free-mode call. Mirrors IpQualityFunctionMuOracle.cpp:RegisterOptions.

qf_centrality_type: CentralityType

quality_function_centrality (default none) — penalty term added to the quality function for centrality deviation.

qf_balancing_term: BalancingTermType

quality_function_balancing_term (default none) — penalty term added to the quality function when the complementarity is far smaller than the infeasibilities.

qf_max_section_steps: i32

quality_function_max_section_steps (default 8) — cap on golden-section iterations when picking σ.

qf_section_sigma_tol: Number

quality_function_section_sigma_tol (default 1e-2) — width tolerance in σ-space for the golden-section search.

qf_section_qf_tol: Number

quality_function_section_qf_tol (default 0.0) — relative flatness tolerance for the golden-section search.

probing_iterate_quality_factor: Number

probing_iterate_quality_factor (default 1e4, pounce-specific; see pounce#58). When the probing (Mehrotra) μ-oracle is about to read curr_avrg_compl() for its mu_curr input, a single imbalanced (s_i, z_i) pair can inflate the average 5+ orders above the stored data.curr_mu. Probing then mathematically correctly returns σ·mu_curr ≫ previous μ, which throws the iterate out of the convergence neighborhood. This guard short-circuits that case: when curr_avrg_compl / curr_mu > probing_iterate_quality_factor, we signal restoration via [IpoptData::request_resto] and keep μ unchanged. Set to 0 or any non-positive value to disable.

Implementations

impl AdaptiveMuUpdate

pub fn new() -> Self

pub fn probing_iterate_guard_fires( factor: Number, curr_mu: Number, avrg_compl: Number, ) -> bool

Pure-arithmetic predicate behind the probing-oracle iterate- quality guard (pounce#58). Returns true when the ratio avrg_compl / curr_mu exceeds factor. The two non-strict gates (factor > 0, curr_mu > 0) keep the predicate well-defined when the guard is disabled or when an unusual μ-strategy zeroes curr_mu.

pub fn lazy_mu_max( mu_max_fact: Number, avrg: Number, mu_init: Number, mu_min: Number, ) -> Number

Scalar core of the lazy mu_max initialization (IpAdaptiveMuUpdate.cpp:267-274): on the first call, when the user did not set mu_max explicitly, upstream sets it to mu_max_fact * curr_avrg_compl().

A warm start (warm_start_init_point=yes) can hand us an iterate whose bound multipliers are all zero — pounce does not yet wire warm_start_mult_bound_push, so seed_from_nlp leaves z_l/z_u/v_l/v_u at 0. Then curr_avrg_compl() is 0 even though bounds exist, the no_bounds short-circuit does NOT fire, mu_max collapses to 0, and the later new_mu.clamp(mu_min, mu_max) panics with min > max (min = mu_min = 1e-11, max = 0). When avrg carries no positive complementarity signal (zero, or a NaN handed in by a pathological iterate) fall back to mu_init as the proxy — what a cold start’s avrg_compl is ~scaled to — so the [mu_min, mu_max] band stays valid. The final .max(mu_min) is a belt-and-suspenders floor against pathological options.

pub fn lower_mu_safeguard( &mut self, dual_inf: Number, primal_inf: Number, min_ref_val: Number, ) -> Number

Scalar core of AdaptiveMuUpdate::lower_mu_safeguard (IpAdaptiveMuUpdate.cpp:753-786):

  init_dual_inf   ← max(1, dual_inf)   if not yet set
  init_primal_inf ← max(1, primal_inf) if not yet set
  lower = max(safeguard_factor * dual_inf / init_dual_inf,
              safeguard_factor * primal_inf / init_primal_inf)
  if globalization == KKT_ERROR: lower = min(lower, min_ref_val)

pub fn reset_init_inf(&mut self)

pub fn certificate_safe_mu_min(&self, obj_scaling_factor: Number) -> Number

mu_min capped so it can never block the termination certificate (pounce#266) — the adaptive twin of crate::mu::monotone::MonotoneMuUpdate::certificate_safe_mu_min, which carries the full story. The raw absolute mu_min (default 1e-11) lives in μ’s scaled space while compl_inf_tol is enforced on the unscaled complementarity; below |df| ≈ mu_min·(barrier_tol_factor+1)/compl_inf_tol an uncapped floor pins the unscaled complementarity above compl_inf_tol and the strict certificate is unreachable — in adaptive mode the solve then degrades to Solved_To_Acceptable_Level (code 100, outside AMPL’s 0..99 solved band) on an iterate sitting at the optimum.

The restoration sub-builder’s mu_min = 100 · outer_mu_min safeguard is unaffected for the same reason as in monotone mode: RestoIpoptNlp does not override obj_scaling_factor, so the resto inner IPM sees df = 1 and the cap sits far above the safeguard.

pub fn fixed_mode_mu_floor( &self, tol: Number, obj_scaling_factor: Number, ) -> Number

Floor for the fixed-mode (monotone-mode) μ decrease — port of IpAdaptiveMuUpdate.cpp:328-329:

new_mu = Max(new_mu,
    Min(compl_inf_tol_scaled, IpData().tol()) / (barrier_tol_factor_ + 1.));

pounce#511: this branch used to floor at mu_min instead — 1e-11 against upstream’s 9.09e-10 at default tol = 1e-8, ~91× lower, and further with a looser tol (at tol = 1e-6 upstream’s floor is 9.09e-8, four orders up). mu_min is the free-mode clamp; once the strategy has switched to fixed mode upstream deliberately uses the looser, tolerance-derived floor — that is the point of the switch. Driving the Newton system down to 1e-11 past the accuracy the termination test asks for buys nothing and invites degenerate search directions on an ill-conditioned Jacobian.

Two details mirror the monotone floor (MonotoneMuUpdate::update_barrier_parameter):

• compl_inf_tol is converted into μ’s scaled space first (pounce#257 — upstream’s apply_obj_scaling), since it is enforced on the unscaled complementarity while μ and tol are scaled;
• the result is additionally maxed with the certificate-safe mu_min (pounce#266) so the restoration sub-builder’s 100 · outer_mu_min safeguard still applies. Capped that way, mu_min can only raise the floor, never push it under the certificate.

Trait Implementations

impl Default for AdaptiveMuUpdate

fn default() -> Self

Returns the “default value” for a type.

impl MuUpdate for AdaptiveMuUpdate

fn initialize(&mut self, data: &IpoptDataHandle)

Port of IpAdaptiveMuUpdate.cpp:InitializeImpl. Seeds curr_mu = mu_init, curr_tau = max(tau_min, 1 - mu_init), resets the globalization state, and starts in free-μ mode (SetFreeMuMode(true) at line 239).

fn update_barrier_parameter( &mut self, data: &IpoptDataHandle, cq: &IpoptCqHandle, nlp: Option<&Rc<RefCell<dyn IpoptNlp>>>, pd_search_dir: Option<&mut PdSearchDirCalc>, ) -> Number

Adaptive μ update — port of UpdateBarrierParameter (IpAdaptiveMuUpdate.cpp:252-444). Runs the FreeMuMode / FixedMuMode state machine:

• FreeMuMode: ask the configured oracle for a candidate (LOQO closed-form, Probing predictor solve, or QualityFunction golden-section). If progress is sufficient, stay in free mode and remember the iterate; otherwise switch to fixed mode at new_fixed_mu.
• FixedMuMode: monotone Fiacco-McCormick reduction (min(linear · μ, μ^superlinear_power)). Switch back to free mode once the globalization criterion is satisfied again.

Probing / QualityFunction silently fall back to LOQO when nlp / pd_search_dir are unavailable (mirrors upstream lines 402-408).

Line-search reset: upstream calls linesearch_->Reset() at three points — line 339 (fixed-mode decrease), line 386 (free→fixed switch) and line 431 (every free-mode iteration, whether or not μ moved). The MuUpdate trait surface carries no line-search handle, so we raise IpoptData::request_ls_reset at exactly those three points and IpoptAlgorithm::iterate performs the reset right after this call returns — the same plumbing the pounce#58 probing guard uses for IpoptData::request_resto. See pounce#510: the previous “reset when μ changed” proxy in the caller is correct for the monotone update but not for this one, and left the filter holding pre-restoration entries whenever μ happened to stay put.

fn terminates_on_tiny_step(&self) -> bool

Whether the main loop may infer STOP_AT_TINY_STEP from “tiny-step flag set and μ came back unchanged”.