API

abstract type AbstractVariable <: AbstractExpr end

An AbstractVariable should have head field, and a size field to conform to the AbstractExpr interface, and implement methods (or use the field-access fallbacks) for

• _value, set_value!: get or set the numeric value of the variable. _value should return nothing when no numeric value is set. Note: evaluate is the user-facing method to access the value of x.
• vexity, vexity!: get or set the vexity of the variable. The vexity should be AffineVexity() unless the variable has been fix!'d, in which case it is ConstVexity().
• sign, vartype, and get_constraints: get the Sign, VarType, numeric type, and a (possibly empty) vector of constraints which are to be applied to any problem in which the variable is used.

Optionally, also implement sign!, vartype!, and add_constraint! to allow users to modify those values or add a constraint.

_value(x::AbstractVariable)

Raw access to the current value of x; used internally by Convex.jl.

set_value!(x::AbstractVariable, v)

Sets the current value of x to v.

get_constraints(x::AbstractVariable)

Returns the current constraints carried by x.

add_constraint!(x::AbstractVariable, C::Constraint)

Adds an constraint to those carried by x.

vexity(x::AbstractVariable)

Returns the current vexity of x.

vexity!(x::AbstractVariable, v::Vexity)

Sets the current vexity of x to v. Should only be called by fix! and free!.

Base.sign(x::AbstractVariable)

Returns the current sign of x.

sign!(x::AbstractVariable, s::Sign)

Sets the current sign of x to s.

VarType

Describe the type of a AbstractVariable: either continuous (ContVar), integer-valued (IntVar), or binary (BinVar).

vartype(x::AbstractVariable)

Returns the current VarType of x.

vartype!(x::AbstractVariable, vt::VarType)

Sets the current VarType of x to vt.

fix!(x::AbstractVariable, v = value(x))

Fixes x to v. It is subsequently treated as a constant in future optimization problems. See also free!.

free!(x::AbstractVariable)

Frees a previously fix!'d variable x, to treat it once again as a variable to optimize over.

evaluate(x::AbstractVariable)

Returns the current value of x if assigned; errors otherwise.

solve!(
    problem::Problem,
    optimizer_factory;
    silent::Bool = false,
    warmstart::Bool = false,
)

Solves the problem, populating problem.optval with the optimal value, as well as the values of the variables (accessed by evaluate) and constraint duals (accessed by cons.dual), where applicable. Returns the input problem.

Optional keyword arguments:

• silent: whether or not Convex and the solver should be silent (and not emit output or logs) during the solution process. When silent=false, Convex will print the formulation time, and warn if the problem was not solved optimally.
• warmstart (default: false): whether the solver should start the optimization from a previous optimal value (according to the current primal value of the variables in the problem, which can be set by set_value!.

MAXDEPTH

Controls depth of tree printing globally for Convex.jl; defaults to 3. Set via

Convex.MAXDEPTH[] = 5

MAXWIDTH

Controls width of tree printing globally for Convex.jl; defaults to 3. Set via

Convex.MAXWIDTH[] = 10

MAXDIGITS

When priting IDs of variables, only show the initial and final digits if the full ID has more than double the number of digits specified here. So, with the default setting MAXDIGITS=3, any ID longer than 7 digits would be shortened; for example, ID 14656210999710729289 would be printed as 146…289.

This setting controls tree printing globally for Convex.jl; defaults to 3.

Set via:

Convex.MAXDIGITS[] = 3

run_tests(
    handle_problem!::Function;
    problems::Union{Nothing, Vector{String}, Vector{Regex}} = nothing;
    exclude::Vector{Regex} = Regex[],
    T=Float64, atol=1e-3, rtol=0.0,
)

Run a set of tests. handle_problem! should be a function that takes one argument, a Convex.jl Problem and processes it (e.g. solve! the problem with a specific solver).

Use exclude to exclude a subset of sets; automatically excludes r"benchmark". Optionally, pass a second argument problems to only allow certain problems (specified by exact names or regex). The test tolerances specified by atol and rtol. Set T to choose a numeric type for the problem. Currently this is only used for choosing the type parameter of the underlying MathOptInterface model, but not for the actual problem data.

Examples

run_tests(exclude=[r"mip"]) do p
    solve!(p, SCS.Optimizer; silent=true)
end

benchmark_suite(
    handle_problem!::Function,
    problems::Union{Nothing, Vector{String}, Vector{Regex}} = nothing;
    exclude::Vector{Regex} = Regex[],
    test = Val(false),
    T=Float64, atol=1e-3, rtol=0.0,
)

Create a benchmarksuite of benchmarks. `handleproblem!should be a function that takes one argument, a Convex.jlProblemand processes it (e.g.solve!the problem with a specific solver). Pass a second argumentproblems` to specify run benchmarks only with certain problems (specified by exact names or regex).

Use exclude to exclude a subset of benchmarks. Optionally, pass a second argument problems to only allow certain problems (specified by exact names or regex). Set test=true to also check the answers, with tolerances specified by atol and rtol. Set T to choose a numeric type for the problem. Currently this is only used for choosing the type parameter of the underlying MathOptInterface model, but not for the actual problem data.

Examples

benchmark_suite(exclude=[r"mip"]) do p
    solve!(p, SCS.Optimizer; silent=true)
end

foreach_problem(apply::Function, [class::String],
    problems::Union{Nothing, Vector{String}, Vector{Regex}} = nothing;
    exclude::Vector{Regex} = Regex[])

Provides a convience method for iterating over problems in PROBLEMS. For each problem in PROBLEMS, apply the function apply, which takes two arguments: the name of the function associated to the problem, and the function associated to the problem itself.

Optionally, pass a second argument class to only iterate over a class of problems (class should satsify class ∈ keys(PROBLEMS)), and pass third argument problems to only allow certain problems (specified by exact names or regex). Use the exclude keyword argument to exclude problems by regex.

const PROBLEMS = Dict{String, Dict{String, Function}}()

A "depot" of Convex.jl problems, subdivided into categories. Each problem is stored as a function with the signature

f(handle_problem!, ::Val{test}, atol, rtol, ::Type{T}) where {T, test}

where handle_problem! specifies what to do with the Problem instance (e.g., solve! it with a chosen solver), an option test to choose whether or not to test the values (assuming it has been solved), tolerances for the tests, and a numeric type in which the problem should be specified (currently, this is not respected and all problems are specified in Float64 precision).

See also run_tests and benchmark_suite for helpers to use these problems in testing or benchmarking.

Examples

julia> PROBLEMS["affine"]["affine_diag_atom"]
affine_diag_atom (generic function with 1 method)

conic_form!(context::Context, a::AbstractExpr)

Return the conic form for a. If it as already been created, it is directly accessed in context[a], otherwise, it is created by calling Convex.new_conic_form! and then cached in context so that the next call with the same expression does not create a duplicate one.

new_conic_form!(context::Context, a::AbstractExpr)

Create a new conic form for a and return it, assuming that no conic form for a has already been created, that is !haskey(context, a) as this is already checked in conic_form! which calls this function.

write_to_file(problem::Problem{Float64}, filename::String)

Write the current problem to the file at filename.

The file format is inferred from the filename extension. Supported file types depend on the model type.

Currently, Float64 is the only supported coefficient type. This may be relaxed in future if file formats support other types.