Docstrings

GCMMA

The globally convergent method of moving asymptotes (GCMMA) from the 2002 paper. This is an alias of MMA02: the 2002 paper's conservative variant of MMA with inner iterations on the lift parameter ρ.

MMA02

The globally convergent method of moving asymptotes (MMA) algorithm from the 2002 paper. This is the method commonly called GCMMA in the literature. Unlike MMA87, it runs inner iterations that increase the lift parameter ρ until the convex separable approximation upper-bounds the original functions, which yields the global convergence guarantee of the 2002 paper.

MMA87

The original method of moving asymptotes (MMA) algorithm from the 1987 paper.

struct MMAApprox{T} <: AbstractMMAApprox parent::AbstractFunction # exact function xk::AbstractVector # current approximation point fk::T # f(xk) ∇fk::AbstractVecOrMat # ∇f(xk) σ::AbstractVector # move limit l::AbstractVector # xk .- σ u::AbstractVector # xk .+ σ ρ::T # lift - only used in MMA 2002 p::AbstractVecOrMat # p[i, j] = σ[j]^2 max(0, ∇fk[j]) + ρ[i] σ[j] / 4 q::AbstractVecOrMat # q[i, j] = σ[i]^2 max(0, -∇fk[j]) + ρ[i] σ[j] / 4 r::T # r[i] = fk[i] + sum_j (p[i, j] + q[i, j]) / σ[j] out::T # cached output of the approximation end

An instance of MMAApprox stores information about the method of moving asymptotes (MMA) approximation of the function parent. The notation used here is from the original 1987 MMA paper and the 2002 paper. xk is the point around which the approximation is built. fk is the value of approximated function at xk. And ∇fk is the gradient of the approximated function at xk if it is a scalar-valued function and the Jacobian if it is a vector-valued function. l and u are the lower and upper asymptotes. σ is the move limit such that l = xk .- σ and u = xk .+ σ. r, p, q and ρ are explained in the paper. When an instance of MMAApprox is called, its output will be cached in the field out.

(f::MMAApprox)(x::AbstractVector)

Returns an approximation of the function f.parent at point x. See MMAApprox for an explanation.

MMAApprox(f::AbstractFunction, x::AbstractVector; σ = fill(10.0, length(x)), ρ = 0.0)

Constructs an MMA approximation of the function f around the point x using a move limit σ and ρ. See this paper for an explanation of the notation.

struct MMAApproxModel{TApprox <: AbstractMMAApprox} <: AbstractModel
    parent::VecModel
    objective_ineq_constraints::AbstractFunction
    approx_objective_ineq_constraints::TApprox
    box_min::AbstractVector
    box_max::AbstractVector
end

An approximate restricted model that uses the MMAApprox or XMMAApprox approximation of the objective and constraint functions. The lower and upper bounds of the approximate model are more restricted than the original model. See updatebounds! for more details on the bounds.

• parent: the original model.
• objective_ineq_constraints: a function that returns the exact objective value and constraint violations as a single vector.
• approx_objective_ineq_constraints: a function that returns the approximate objective value and constraint violations as a single vector.
• box_min: the restricted lower bounds on the decision variables.
• box_max: the restricted upper bounds on the decision variables.

MMAApproxModel(parent::VecModel, x::AbstractVector; extended = false, kwargs...)

Constructs an MMA approximation of the model parent around the point x. If extended is true, an XMMAApprox approximation is used. Otherwise, the default MMAApprox approximation is used. kwargs can be used to pass additional options to XMMAApprox, e.g. setting the coefficients.

struct MMADualModel <: AbstractModel
    parent::MMAApproxModel
    obj::MMADualObj
end

The dual model with a primal model parent and dual objective obj.

MMADualModel(model::MMAApproxModel)

Constructs an instance of MMADualModel for the approximate MMA model, model.

struct MMADualObj{TApprox <: AbstractMMAApprox} <: AbstractFunction
    model::MMAApproxModel{TApprox}
    x::AbstractVector # primal solution
    approxfg::AbstractVector # approximate [f(x); g(x)]
end

The dual objective function of the MMA model, model. The approximate objective and constraint values are cached in approxfg when the dual objective is called. For every input λ, the optimal primal solution is computed and cached in the field x.

(f::MMADualObj)(x, λ)

Evaluates the dual objective value at the primal solution x and the dual solution λ.

(f::MMADualObj)(λ)

Evaluates the dual objective value at the dual solution λ. The optimal primal solution is computed and used automatically.

MMADualObj(model::MMAApproxModel)

Constructs the dual objective function from the approximate MMA model, model.

MMAOptions

A struct that stores all the options of the MMA algorithms. Th following are the fields of MMAOptions:

• maxiter: the maximum number of inner iterations. For MMA87, there is 1 inner iteration per outer iteration.
• outer_maxiter: the maximum number of outer iterations.
• maxinner: the maximum number of inner iterations per outer iteration of MMA02. Not applicable for MMA87.
• tol: a tolerance struct of type Tolerance.
• s_init: defined in the original MMA02 paper.
• s_incr: defined in the original MMA02 paper.
• s_decr: defined in the original MMA02 paper.
• store_trace: if true, a trace will be stored.
• dual_options: the options passed to the dual optimizer from Optim.jl.
• convcriteria: an instance of ConvergenceCriteria that specifies the convergence criteria of the MMA algorithm.
• verbose: true/false, when true prints convergence statistics.

MMAWorkspace

A struct that stores all the intermediate states and memory allocations needed for the optimization. The following are the fields of the struct:

• model: the original instance of MMAApproxModel being optimized.
• dualmodel: an instance of MMADualObj which resembles the dual of the MMA approximation of the original model.
• x0: the initial primal solution.
• solution: an instance of Solution that resembles the current solution in the optimization algorithm.
• σ: the workspace move limit, explained in MMAApprox.
• ρ: the ρ parameter as explained in MMAApprox.
• tempx: a temporary vector used to store the 2nd previous primal solution.
• options: an instance of MMAOptions that resembles the options of the MMA algorithm.
• callback: a function that is called on solution in every iteration of the algorithm. This can be used to store information about the optimization process.
• optimizer: an instance of AbstractOptimizer such as MMA87() or MMA02() that specifies the variant of MMA used to optimize the model.
• suboptimizer: the dual optimization algorithm used to optimize the barrier problem. This should be an Optim.jl optimizer.
• tracing: a Boolean that when true stores the trace of solutions evaluated during the optimization process.
• outer_iter: the current outer iteration index. MMA87 has 1 inner iteration per outer iteration. MMA02 does multiple inner iterations per outer iteration.
• iter: the current inner iteration index.
• fcalls: the current number of objective and constraint function calls.

Trace

A struct that stores the history of solutions.

struct XMMAApprox <: AbstractMMAApprox
    mma::MMAApprox
    approxfg::AbstractVector
    a::AbstractVector
    c::AbstractVector
    d::AbstractVector
    y::AbstractVector
    z::Base.RefValue{<:Real}
    out::AbstractVector
end

This is similar to MMAApprox but it uses the extended formulation given in the 2002 MMA paper. y and z are additional variables added and a, c and d are coefficients, all of which are explained in the paper. mma is the underlying MMA approximation of the objective and constraints. Calling mma returns a vector whose first element is the objective approximation and the rest are the constraint violation approximations.

If the original model is:

• Variables: x
• Objective: f(x)
• Constraint i: g(x) <= 0
• Bounds: x ∈ X

the transformed model is:

• Variables: x, y, z
• Objective: f(x) + a[1] * z + Σ_i c[i] * y[i] + 1/2 * d[i] * y[i]^2
• Constraint i: g_i(x) - a[i + 1] * z - y[i] <= 0
• Bounds: x ∈ X, y >= 0, z >= 0

(approx::XMMAApprox)(xyz::AbstractVector)

Returns the values of the approximate objective and constraints. xyz is x, y and z concatenated in a single vector.

XMMAApprox(
    mma::MMAApprox;
    a = fill(1.0, size(mma.p, 1)),
    c = fill(1.1, size(mma.p, 1) - 1),
    d = fill(1.0, size(mma.p, 1) - 1),
    kwargs...,
)

Constructs an instance of the extended MMA approximation XMMAApprox using the MMA approximation mma and coefficients a, b and c. See XMMAApprox for an explanation.

getapproxfg(approx::AbstractMMAApprox)

Returns the last cached value of the output of approx.

getapproxfg(model::MMAApproxModel)

Returns the last cached value of the approximate objective and constraint values.

getapproxfg(dualobj::MMADualObj)

Returns the cached approximate objective and constraint values.

getasymptotes(approx::AbstractMMAApprox)

Returns the asymptotes of the MMA approximation approx.

getfk(approx::AbstractMMAApprox)
setfk!(approx::AbstractMMAApprox, fk)

Get or set the function value fk of the approximated function at the approximation point xk of approx.

getfk(approx::AbstractMMAApprox)
setfk!(approx::AbstractMMAApprox, fk)

Get or set the function value fk of the approximated function at the approximation point xk of approx.

getfk(approx::AbstractMMAApprox)
setfk!(approx::AbstractMMAApprox, fk)

Get or set the function value fk of the approximated function at the approximation point xk of approx.

getoptimalx(m::MMADualModel)

Returns the last cached optimal primal solution.

getoptimalx(f::MMADualObj)

Returns the cached optimal primal solution.

getxk(approx::AbstractMMAApprox)
setxk!(approx::AbstractMMAApprox, x::AbstractVector)

Get or set the approximation point xk of approx.

getxk(approx::AbstractMMAApprox)
setxk!(approx::AbstractMMAApprox, x::AbstractVector)

Get or set the approximation point xk of approx.

getxk(approx::AbstractMMAApprox)
setxk!(approx::AbstractMMAApprox, x::AbstractVector)

Get or set the approximation point xk of approx.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

get∇fk(approx)
set∇fk!(approx, ∇f::AbstractVecOrMat)

Get or set the value of the gradient/Jacobian, ∇fk, of the approximated function at the approximation point xk.

get∇fk(approx)
set∇fk!(approx, ∇f::AbstractVecOrMat)

Get or set the value of the gradient/Jacobian, ∇fk, of the approximated function at the approximation point xk.

get∇fk(approx)
set∇fk!(approx, ∇f::AbstractVecOrMat)

Get or set the value of the gradient/Jacobian, ∇fk, of the approximated function at the approximation point xk.

optimizeprimal!(f::MMADualObj, λ::AbstractVector)

Finds and returns the primal minimizer of the Lagrangian function for a given dual solution λ.

saveout!(approx::XMMAApprox, out)

Saves out in the cache approx.out.

scaleobjective!(model::VecModel, fg, ∇fg, approxfg, λ)

Scales the objective of model using the ratio of the ∞ norms of the constraint and objective values and gradients. After scaling, the ∞ norms will be the same.

getfk(approx::AbstractMMAApprox)
setfk!(approx::AbstractMMAApprox, fk)

Get or set the function value fk of the approximated function at the approximation point xk of approx.

getfk(approx::AbstractMMAApprox)
setfk!(approx::AbstractMMAApprox, fk)

Get or set the function value fk of the approximated function at the approximation point xk of approx.

getxk(approx::AbstractMMAApprox)
setxk!(approx::AbstractMMAApprox, x::AbstractVector)

Get or set the approximation point xk of approx.

getxk(approx::AbstractMMAApprox)
setxk!(approx::AbstractMMAApprox, x::AbstractVector)

Get or set the approximation point xk of approx.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getρ(approx::AbstractMMAApprox)
setρ!(approx::AbstractMMAApprox, ρ)

Get or set the value of ρ in approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

getσ(approx::AbstractMMAApprox)
setσ!(approx::AbstractMMAApprox, σ)

Get or set the move limit σ of the MMA approximation approx. See MMAApprox for an explanation.

get∇fk(approx)
set∇fk!(approx, ∇f::AbstractVecOrMat)

Get or set the value of the gradient/Jacobian, ∇fk, of the approximated function at the approximation point xk.

get∇fk(approx)
set∇fk!(approx, ∇f::AbstractVecOrMat)

Get or set the value of the gradient/Jacobian, ∇fk, of the approximated function at the approximation point xk.

updateapprox!(f, x)

Updates the MMA approximation in f making it around the point x.

updateapprox!(approx::AbstractMMAApprox, x, f, ∇f)

Updates the MMA approximation approx making it around the point x where f is the value of the approximated function at x and ∇f is its gradient if f is a number and the Jacobian if f is a vector.

updateapprox!(approx::AbstractMMAApprox)

Updates the MMA approximation approx. This is called when σ, ρ or xk change.

updateapprox!(model::MMAApproxModel, x, f, ∇f)

Updates the MMA approximation in model making it around the point x where f is the value of the approximated function at x and ∇f is its gradient if f is a number and the Jacobian if f is a vector.

updateapprox!(model::MMAApproxModel, x)

Updates the MMA approximation in model making it around the point x.

updateapprox!(approx::MMAApproxModel)

Updates the MMA approximation in model. This is called when σ, ρ or xk change.

updateapprox!(f, x)

Updates the MMA approximation in f making it around the point x.

updatebounds!(model::MMAApproxModel, x)

Updates the bounds on the decision variables in model using the asymptotes of the approximation and the bounds on the original variables. The update formula is described in the original 1987 MMA paper and the 2002 paper.