Convex.TreePrint.print_treeFunction

Usage

Prints an ASCII formatted representation of the tree to the given io object. By default all children will be printed up to a maximum level of 5, though this valud can be overriden by the maxdepth parameter. The charset to use in printing can be customized using the charset keyword argument.

Examples

julia> print_tree(STDOUT,Dict("a"=>"b","b"=>['c','d']))
Dict{String,Any}("b"=>['c','d'],"a"=>"b")
├─ b
│  ├─ c
│  └─ d
└─ a
   └─ b

julia> print_tree(STDOUT,Dict("a"=>"b","b"=>['c','d']);
        charset = TreeCharSet('+','\\','|',"--"))
Dict{String,Any}("b"=>['c','d'],"a"=>"b")
+-- b
|   +-- c
|   \-- d
\-- a
   \-- b
Convex.MAXDEPTHConstant
MAXDEPTH

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

Convex.MAXDEPTH[] = 5
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
Convex.MAXWIDTHConstant
MAXWIDTH

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

Convex.MAXWIDTH[] = 15
Convex.AbstractVariableType
abstract type AbstractVariable <: AbstractExpr end

An AbstractVariable should have head field, an id_hash 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 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.

Base.signMethod
sign(x::AbstractVariable)

Returns the current sign of x.

Base.summaryMethod
Base.summary(io::IO, x::AbstractVariable)

Prints a one-line summary of a variable x to io.

Examples

julia> x = ComplexVariable(3,2);

julia> summary(stdout, x)
3×2 complex variable (id: 732…737)
Convex._valueMethod
_value(x::AbstractVariable)

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

Convex.add_constraint!Method
add_constraint!(x::AbstractVariable, C::Constraint)

Adds an constraint to those carried by x.

Convex.constraintsMethod
constraints(x::AbstractVariable)

Returns the current constraints carried by x.

Convex.emit_dcp_warningsMethod
emit_dcp_warnings

Controls whether or not warnings are emitted for when an expression fails to be of disciplined convex form. To turn warnings off, override the method via

Convex.emit_dcp_warnings() = false

This will cause Julia's method invalidation to recompile any functions emitting DCP warnings and remove them. This should be run from top-level (not within a function).

Convex.evaluateFunction
evaluate(x::AbstractExpr)

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

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.is_psdMethod
is_psd(A; tol)

Check whether A is positive semi-definite by computing a LDLᵀ factorization of A + tol*I

Convex.partialtraceMethod
partialtrace(x, sys::Int, dims::Vector)

Returns the partial trace of x over the systh system, where dims is a vector of integers encoding the dimensions of each subsystem.

Convex.partialtransposeMethod
partialtranspose(x, sys::Int, dims::Vector)

Returns the partial transpose of x over the systh system, where dims is a vector of integers encoding the dimensions of each subsystem.

Convex.permutedims_matrixMethod
permutedims_matrix(dims, p)

Returns a matrix M so that for any vector v of length prod(dims),

M*v == vec(permutedims(reshape(v, dims), p))
Convex.print_tree_rstripMethod
print_tree_rstrip(io::IO, x)

Prints the results of TreePrint.print_tree(io, x) without the final newline. Used for show methods which invoke print_tree.

Convex.quadformMethod
quadform(x::AbstractExpr, A::AbstractExpr; assume_psd=false)

Represents x' * A * x where either:

  • x is a vector-valued variable and A is a positive semidefinite or negative semidefinite matrix (and in particular Hermitian or real symmetric). If assume_psd=true, then

A will be assumed to be positive semidefinite. Otherwise, Convex.is_psd will be used to check if A is positive semidefinite or negative semidefinite.

  • or A is a matrix-valued variable and x is a vector.
Convex.set_value!Function
set_value!(x::AbstractVariable, v)

Sets the current value of x to v.

Convex.show_idMethod
show_id(io::IO, x::Union{AbstractExpr, Constraint}; digits = 3)

Print a truncated version of the objects id_hash field.

Example

julia> x = Variable();

julia> Convex.show_id(stdout, x)
id: 163…906
Convex.sign!Method
sign!(x::AbstractVariable, s::Sign)

Sets the current sign of x to s.

Convex.solve!Method
solve!(problem::Problem{T}, optimizer::MOI.ModelLike;
    check_vexity::Bool = true,
    verbose::Bool = true,
    warmstart::Bool = false,
    silent_solver::Bool = false) where {T}

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.

Optional keyword arguments:

  • check_vexity (default: true): emits a warning if the problem is not DCP
  • verbose (default: true): emits a warning if the problem was not solved optimally or warmstart=true but is not supported by the solver.
  • warmstart (default: false): whether the solver should start the optimization from a previous optimal value (according to the current value of the variables in the problem, which can be set by set_value! and accessed by evaluate).
  • silent_solver: whether the solver should be silent (and not emit output or logs) during the solution process.
Convex.vexity!Method
vexity!(x::AbstractVariable, v::Vexity)

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

Convex.vexityMethod
vexity(x::AbstractVariable)

Returns the current vexity of x.

LinearAlgebra.normFunction
norm(x::AbstractExpr, p::Real=2)

Computes the p-norm ‖x‖ₚ = (∑ᵢ |xᵢ|^p)^(1/p) of a vector expression x.

This function uses specialized methods for p=1, 2, Inf. For p > 1 otherwise, this function uses the procedure documented at rational_to_socp.pdf, based on the paper "Second-order cone programming" by F. Alizadeh and D. Goldfarb, Mathematical Programming, Series B, 95:3-51, 2001.

Warning

For versions of Convex.jl prior to v0.14.0, norm on a matrix expression returned the operator norm (opnorm), which matches Julia v0.6 behavior. This functionality was deprecated since Convex.jl v0.8.0, and has been removed. In the future, norm(x, p) will return ‖vec(x)‖ₚ, matching the behavior of norm for numeric matrices.

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)
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_solver=true)
end
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.

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_solver=true)
end