Reference

CompactBFGSModel(nlp; mem = 6, scaling = true, max_skip = 2)

Wrap nlp so that its Hessian of the Lagrangian is replaced by a limited-memory BFGS approximation stored in compact form. The approximation is updated by the solver during the iterations. All other evaluations are forwarded to nlp.

This is what L2Penalty uses with qn_hessian_approximation = "bfgs". Construct it yourself only when using a preallocated L2PenaltySolver, see Preallocation.

Keyword arguments

• mem::Int = 6: number of pairs $(s, y)$ stored.
• scaling::Bool = true: whether the initial approximation is $B_0 = \gamma I$ with $\gamma = y^T y / s^T y$.
• max_skip::Int = 2: an update is skipped when dot(s, y) ≤ eps(T); the approximation is reset once more than max_skip consecutive updates have been skipped.

These correspond to the qn_mem, qn_scaling and qn_max_skip options, see Options Reference.

FixedVariableEliminationModel(nlp, free, fixed, ...) <: AbstractNLPModel{T,S}

A thin wrapper around nlp that hides the variables in fixed (those with lvar[i] == uvar[i]) from the optimizer. Fixed variables are kept at their bound value and are transparently substituted back in whenever the underlying model nlp is evaluated.

Do not construct this directly; use remove_fixed_variables.

solver = L2PenaltySolver(nlp; r2n_m_monotone = 12, linear_solver = "mumps")

Preallocate all the memory needed to solve nlp with the exact ℓ₂-penalty method. The solver can then be passed to solve! any number of times without further allocation, as long as the problem dimensions do not change. See Preallocation.

Unlike L2Penalty, no preprocessing is applied: if nlp has fixed variables or shifted constraints, see remove_fixed_variables and remove_constraint_shift.

Keyword arguments

These options determine the size of the workspace and can only be passed here, not to solve!:

• r2n_m_monotone::Int = 12: non-monotone memory of the inner (R2N) solver;
• linear_solver::String = "mumps": linear solver used for step computations.

See Options Reference for details.

NullHessianModel(nlp)

Wrap nlp so that its Hessian of the Lagrangian is replaced by the zero matrix. All other evaluations (objective, constraints, gradients, Jacobians) are forwarded to nlp.

This is what L2Penalty uses with qn_hessian_approximation = "null". Construct it yourself only when using a preallocated L2PenaltySolver, see Preallocation.

ScaledModel(nlp, d_f, d_c, ...) <: AbstractNLPModel{T,S}

Wraps nlp and exposes the scaled objective d_f * f(x) and scaled constraints d_c .* c(x). Do not construct directly; use scale_model.

ShiftedConstraintModel(nlp, shift) <: AbstractNLPModel{T,S}

Wraps nlp and exposes c(x) - shift in place of c(x), with lcon/ucon adjusted accordingly. Do not construct directly; use remove_constraint_shift.

stats = L2Penalty(nlp; kwargs...)

Solve the equality-constrained problem

min f(x)  s.t.  c(x) = 0

described by the AbstractNLPModel nlp (see NLPModels.jl) with an exact ℓ₂-penalty method. At each outer iteration, the nonsmooth subproblem

min f(x) + τₖ‖c(x)‖₂

is solved approximately by a regularized Newton method (R2N), and the penalty parameter τₖ is updated. Variables may not have bounds, except fixed variables (lvar[i] == uvar[i]).

Fixed variables and constraint right-hand sides are handled internally, and the problem is scaled according to the scaling options; the returned solution is expressed in terms of the original nlp.

Example

using ADNLPModels, Penelopt
nlp = ADNLPModel(x -> (x[1] - 1)^2 + x[2]^2, [2.0, 2.0], x -> [x[1] + x[2] - 1], [0.0], [0.0])
stats = L2Penalty(nlp; print_level = 1)

Keyword arguments

See Options Reference for the full list of options, Callbacks for the callback keyword, and Outputs for a description of stats. To reuse memory across several solves, see L2PenaltySolver and solve!.

stats = PeneloptExecutionStats(nlp)

Allocate a GenericExecutionStats object (see SolverCore.jl) for nlp with the solver_specific entries used by Penelopt.jl.

Pass it to solve! together with an L2PenaltySolver; it is filled in place. See Outputs for a description of its fields.

constraint_shift(nlp)

Return the shift vector v such that the original constraints satisfy c_orig(x) = c(x) + v, where c(x) is what nlp itself now reports. Returns a vector of zeros for a plain AbstractNLPModel (i.e. one that was left untouched by remove_constraint_shift).

find_model(::Type{M}, nlp)

Unwrap nlp through any number of get_model-defined wrappers until an instance of M is found. Returns nothing if none is found.

recover_full_solution(nlp, x)

Return x mapped back to the original variable space, restoring any fixed variables to their bound. Unwraps through any number of get_model-defined wrappers (e.g. ShiftedConstraintModel, QuasiNewtonModel) to find the underlying FixedVariableEliminationModel. Returns x unchanged if none is found.

remove_constraint_shift(nlp::AbstractNLPModel)

Detect equality constraints of the form c_i(x) = v_i with v_i != 0 (lcon[i] == ucon[i] != 0) and reformulate them as c_i(x) - v_i = 0, by wrapping nlp in a model whose cons! subtracts v_i and whose lcon[i]/ucon[i] become 0. Inequality constraints and equality constraints already at 0 are left untouched.

The Jacobian and Hessian are unaffected by this reformulation (subtracting a constant does not change derivatives), so they are delegated to nlp unchanged.

If no constraint needs shifting (including if nlp is unconstrained), nlp itself is returned unchanged.

See constraint_shift to recover the original constraint values, and https://github.com/JuliaSmoothOptimizers/Penelopt.jl/issues/186 for context.

remove_fixed_variables(nlp::AbstractNLPModel)

Return a new AbstractNLPModel in which every variable i with lvar[i] == uvar[i] has been removed from the optimization and is instead treated as a fixed parameter equal to its bound. The returned model has nvar reduced by the number of fixed variables, and behaves exactly like nlp in every other respect (same objective, same constraints, evaluated with the fixed variables substituted in).

If nlp has no fixed variables, nlp itself is returned unchanged (no wrapping, no overhead).

Use recover_full_solution to map a solution of the reduced problem back to the original variable space.

scale_model(nlp::AbstractNLPModel, d_f, d_c::AbstractVector)

Return a ScaledModel wrapping nlp whose objective is d_f * f(x) and whose constraints are d_c .* c(x). d_f must be a positive scalar and d_c a vector of positive scaling factors, one per constraint (length(d_c) == get_ncon(nlp)).

If get_ncon(nlp) == 0, d_c may be passed as an empty vector.

scale_multipliers(nlp::ScaledModel, y)

Map Lagrange multipliers of the original problem to the multipliers that the scaled problem's stationarity condition expects: y_scaled = y .* d_f ./ d_c.

unscale_constraints(nlp::ScaledModel, c_scaled)

Map a constraint value vector of the scaled problem back to the original units.

unscale_multipliers!(y_out, nlp::ScaledModel, y_scaled)

In-place, non-allocating version of unscale_multipliers: writes the result into the preallocated y_out instead of returning a new vector.

unscale_multipliers(nlp::ScaledModel, y_scaled)

Map Lagrange multipliers of the scaled problem back to the multipliers of the original problem: y = y_scaled .* d_c ./ d_f.

unscale_objective(nlp::ScaledModel, f_scaled)

Map an objective value of the scaled problem back to the original units.

update_scaling!(nlp::ScaledModel, gk::AbstractVector, Ak; gmax)

Recompute nlp's gradient-based scaling factors from the gradient gk and constraint Jacobian Ak of the underlying problem, and update nlp in place.

solve!(solver::L2PenaltySolver, nlp, stats; kwargs...)

Solve nlp with the preallocated solver, writing the results in stats (see PeneloptExecutionStats). solver must have been built from a problem with the same dimensions as nlp.

All keyword arguments of L2Penalty are accepted, except r2n_m_monotone, linear_solver and the qn_* options, which must be set when constructing the solver or the model. See Options Reference.

Call SolverCore.reset!(solver) between two solves to discard the state kept from the previous one.