Thresholds and factors

Two conventions govern every mechanism in the package. Both are enforced at construction, so a configuration that violates either fails immediately rather than producing a run that looks plausible and is outside the theory.

Acceptance is not scaling

TRParams carries three thresholds satisfying

\[0 \le \eta \le \eta_1 \le \eta_2 < 1 ,\]

and they answer different questions:

η defines the successful and unsuccessful index sets

\[\mathcal{S} = \{k : \rho_k \ge \eta\}, \qquad \mathcal{U} = \{k : \rho_k < \eta\} ,\]

and nothing else in the package compares ρ with it. η₁ and η₂ never decide whether a step is taken.

using TrustRegionRadius, ADNLPModels

a = TRParams(η = 0.0, η1 = 0.1, η2 = 0.9)     # decoupled
b = TRParams(η1 = 0.1, η2 = 0.9)              # η defaults to η1
(a.η, a.η1, b.η, b.η1)

(0.0, 0.1, 0.1, 0.1)

The keywords are ASCII, matching update_radius!. η₁, η₂ and Δ₀ are accepted as aliases and readable as properties either way, so TRParams(η₁ = 0.2).η1 == 0.2.

Because η defaults to η₁, existing code is unaffected until it asks for something else.

What decoupling buys

Setting η < η₁ opens a band in which ρ_k ∈ [η, η₁): the step is accepted and the radius still contracts. The model was good enough to make progress worth keeping and bad enough that the region should not be trusted at its current size. Nothing in the framework forbids this, and no rule needed changing to support it — the rules already branch on η₁.

Setting η = 0 accepts every step with a positive predicted reduction. This is admissible in Part I and excluded by the framework of Curtis & Scheinberg (2020), which requires a strictly positive acceptance threshold; it is worth a column of its own in any comparison.

ss  = stats.solver_specific
ρ, acc = ss[:ratio_trajectory], ss[:accepted_trajectory]
count(i -> acc[i] && ρ[i] < params.η1, eachindex(acc))

Why the rules are told the outcome

update_radius!(rule, Δ, ρ, accepted, η1, η2, s_norm, g_norm_old, g_norm_new)

accepted is passed rather than recomputed. A rule cannot derive it: acceptance is decided by η, which the rule never receives, and the retrospective rules are handed ρ̃ in the ρ slot, so they do not see ρ_k at all. For RRTR and RRTRGrad this argument is load-bearing — see Retrospective rules and rejected steps.

Rules that constrain the thresholds

Some rules cannot accept every admissible triple. The step-driven rules need η₁ > 0, because at η₁ = 0 their aggressive branch is unreachable and the lower-bound constant of Part I degenerates. validate_thresholds is called once when the solver is built, so the failure is a constructor error rather than a silent change of behaviour:

nlp = ADNLPModel(x -> sum(abs2, x), [1.0, 2.0])
try
    DeterministicTRSolver(nlp; rule = RStep(),
                          params = TRParams(η = 0.0, η1 = 0.0, η2 = 0.9))
catch e
    showerror(stdout, e)
end

ArgumentError: RStep: the step-driven update needs η1 > 0

Rules with no such requirement accept η₁ = 0 unchanged. To add a requirement for a new rule, define a method of validate_thresholds; the fallback accepts everything.

One convention for the scaling factors

Every rule carries γ₁, γ₂, γ₃ with

\[0 < \gamma_1 \le \gamma_2 < 1 < \gamma_3 ,\]

γ₁ the aggressive contraction, γ₂ the mild one, γ₃ the expansion. This is the convention of Parts I–II, checked in every constructor by check_factors, which throws an ArgumentError naming the rule and the offending inequality. A rule that does not use one of the three passes nothing for it; the remaining inequalities are still checked.

ArgumentError rather than @assert deliberately: @assert is documented as liable to be disabled, and these are argument checks rather than internal invariants.

The rule constructors take ASCII factor names, γ1, γ2, γ3. The Unicode aliases η₁, η₂, Δ₀ exist on TRParams but do not extend to the rules, so RGrad(γ₂ = 2.0) raises MethodError: no method matching RGrad(; γ₂::Float64) rather than the validation error you were reaching for.

for f in (() -> RGrad(γ2 = 2.0),
          () -> RDelta(γ1 = 0.8, γ2 = 0.3),
          () -> RDelta(γ3 = 0.9),
          () -> RGrad(γ1 = 0.25, γ2 = 0.5, γ3 = 2.0))
    try
        f()
        println("constructed")
    catch e
        println(sprint(showerror, e))
    end
end

ArgumentError: RGrad: need 0 < γ2 < 1, got γ2 = 2.0
ArgumentError: RDelta: need γ1 ≤ γ2, got γ1 = 0.8, γ2 = 0.3
ArgumentError: RDelta: need γ3 > 1, got γ3 = 0.9
constructed

The Hei family carries one extra requirement, γ₃ > 1 + γ₂, so that the smooth factor can exceed the value it takes at the threshold; see The Hei family.

Rules whose factors were renumbered

Four rules previously used γ₂ for expansion, which is now the mild contraction slot:

RDelta, RStep and RDFO keep their values; only their checks are tighter, since γ₂ < 1 and γ₁ ≤ γ₂ were previously unverified. Old keyword calls now throw, so none of these can pass silently. MIGRATION.md in the repository root lists the case that can: a positional call, to any of the four rules that take positional factors, whose numbers happen to satisfy 0 < γ1 ≤ γ2 < 1 < γ3 under the new reading. The renumbering moved what slot 3 means, and nothing can distinguish that from a deliberate call.

Radius bounds

Every rule carries Δmin and Δmax and applies them on every branch. Previously Δmax was honoured only on the expansion branch of some rules and absent from others, so the field meant different things in different rules and the solver's global cap hid the inconsistency. check_bounds enforces 0 ≤ Δmin ≤ Δmax at construction — the old clamp threw from inside the iteration instead.

API

TRParams{T}(; η, η1, η2, Δ0, Δmin, Δmax, max_iterations, tol, tol_H,
              max_time, true_stop, stop_z)

validate_thresholds(rule, η, η1, η2) -> nothing

check_factors(name; γ1, γ2, γ3) -> nothing

check_bounds(name; Δmin, Δmax) -> nothing

confirms_stop(p) -> Bool

confirmation_needs_truth(p) -> Bool