API

Info

See Supported operations for a list of the operations supported by Convex.

Convex.AbstractVariableType
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.

source
Convex._valueFunction
_value(x::AbstractVariable)

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

source
Convex.vexity!Function
vexity!(x::AbstractVariable, v::Vexity)

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

source
Base.signMethod
Base.sign(x::AbstractVariable)

Returns the current sign of x.

source
Convex.sign!Function
sign!(x::AbstractVariable, s::Sign)

Sets the current sign of x to s.

source
Convex.fix!Function
fix!(x::AbstractVariable, v = value(x))

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

source
Convex.free!Function
free!(x::AbstractVariable)

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

source
Convex.evaluateFunction
evaluate(x::AbstractVariable)

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

source
Convex.solve!Function
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!.
source
Convex.MAXDEPTHConstant
MAXDEPTH

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

Convex.MAXDEPTH[] = 5
source
Convex.MAXWIDTHConstant
MAXWIDTH

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

Convex.MAXWIDTH[] = 10
source
Convex.MAXDIGITSConstant
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
source
Convex.ProblemDepot.run_testsFunction
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
source
Convex.ProblemDepot.benchmark_suiteFunction
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
source
Convex.ProblemDepot.foreach_problemFunction
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.

source
Convex.ProblemDepot.PROBLEMSConstant
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)
source
Convex.conic_form!Function
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.

source
Convex.new_conic_form!Function
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.

source
Convex.write_to_fileFunction
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.

source