# API

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

`Convex.AbstractVariable`

— Type`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.

`Convex._value`

— Function`_value(x::AbstractVariable)`

Raw access to the current value of `x`

; used internally by Convex.jl.

`Convex.set_value!`

— Function`set_value!(x::AbstractVariable, v)`

Sets the current value of `x`

to `v`

.

`Convex.get_constraints`

— Function`get_constraints(x::AbstractVariable)`

Returns the current constraints carried by `x`

.

`Convex.add_constraint!`

— Function`add_constraint!(x::AbstractVariable, C::Constraint)`

Adds an constraint to those carried by `x`

.

`Convex.vexity`

— Function`vexity(x::AbstractVariable)`

Returns the current vexity of `x`

.

`Convex.vexity!`

— Function`vexity!(x::AbstractVariable, v::Vexity)`

Sets the current vexity of `x`

to `v`

. Should only be called by `fix!`

and `free!`

.

`Base.sign`

— Method`Base.sign(x::AbstractVariable)`

Returns the current sign of `x`

.

`Convex.sign!`

— Function`sign!(x::AbstractVariable, s::Sign)`

Sets the current sign of `x`

to `s`

.

`Convex.VarType`

— Type`VarType`

Describe the type of a `AbstractVariable`

: either continuous (`ContVar`

), integer-valued (`IntVar`

), or binary (`BinVar`

).

`Convex.vartype`

— Function`vartype(x::AbstractVariable)`

Returns the current `VarType`

of `x`

.

`Convex.vartype!`

— Function`vartype!(x::AbstractVariable, vt::VarType)`

Sets the current `VarType`

of `x`

to `vt`

.

`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!`

.

`Convex.free!`

— Function`free!(x::AbstractVariable)`

Frees a previously `fix!`

'd variable `x`

, to treat it once again as a variable to optimize over.

`Convex.evaluate`

— Function`evaluate(x::AbstractVariable)`

Returns the current value of `x`

if assigned; errors otherwise.

`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!`

.

`Convex.MAXDEPTH`

— Constant`MAXDEPTH`

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

`Convex.MAXDEPTH[] = 5`

`Convex.MAXWIDTH`

— Constant`MAXWIDTH`

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

`Convex.MAXWIDTH[] = 10`

`Convex.MAXDIGITS`

— Constant`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`

`Convex.ProblemDepot.run_tests`

— Function```
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
```

`Convex.ProblemDepot.benchmark_suite`

— Function```
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 benchmark*suite of benchmarks. `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). Pass a second argument`

problems` 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
```

`Convex.ProblemDepot.foreach_problem`

— Function```
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.

`Convex.ProblemDepot.PROBLEMS`

— Constant`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)
```

`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.

`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.

`Convex.write_to_file`

— 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.