GitHub

Models

Attribute interface

MathOptInterface.is_set_by_optimize — Function
is_set_by_optimize(::AnyAttribute)

Return a Bool indicating whether the value of the attribute is set during an optimize! call, that is, the attribute is used to query the result of the optimization.

If an attribute can be set by the user, define is_copyable instead.

An attribute cannot be both is_copyable and is_set_by_optimize.

Default fallback

This function returns false by default so it should be implemented for attributes that are set by optimize!.

Undefined behavior

Querying the value of the attribute that is_set_by_optimize before a call to optimize! is undefined and depends on solver-specific behavior.

Example

julia> import MathOptInterface as MOI

julia> MOI.is_set_by_optimize(MOI.ObjectiveValue())
true

julia> MOI.is_set_by_optimize(MOI.VariableName())
false
source
MathOptInterface.is_copyable — Function
is_copyable(::AnyAttribute)

Return a Bool indicating whether the value of the attribute may be copied during copy_to using set.

If an attribute is_copyable, then it cannot be modified by the optimizer, and get must always return the value that was set by the user.

If an attribute is the result of an optimization, define is_set_by_optimize instead.

An attribute cannot be both is_set_by_optimize and is_copyable.

Default fallback

By default is_copyable(attr) returns !is_set_by_optimize(attr), which is most probably true.

If an attribute should not be copied, define is_copyable(::MyAttribute) = false.

source
MathOptInterface.get — Function
get(optimizer::AbstractOptimizer, attr::AbstractOptimizerAttribute)

Return an attribute attr of the optimizer optimizer.

get(model::ModelLike, attr::AbstractModelAttribute)

Return an attribute attr of the model model.

get(model::ModelLike, attr::AbstractVariableAttribute, v::VariableIndex)

If the attribute attr is set for the variable v in the model model, return its value, return nothing otherwise. If the attribute attr is not supported by model then an error should be thrown instead of returning nothing.

get(model::ModelLike, attr::AbstractVariableAttribute, v::Vector{VariableIndex})

Return a vector of attributes corresponding to each variable in the collection v in the model model.

get(model::ModelLike, attr::AbstractConstraintAttribute, c::ConstraintIndex)

If the attribute attr is set for the constraint c in the model model, return its value, return nothing otherwise. If the attribute attr is not supported by model then an error should be thrown instead of returning nothing.

get(
    model::ModelLike,
    attr::AbstractConstraintAttribute,
    c::Vector{ConstraintIndex{F,S}},
) where {F,S}

Return a vector of attributes corresponding to each constraint in the collection c in the model model.

get(model::ModelLike, ::Type{VariableIndex}, name::String)

If a variable with name name exists in the model model, return the corresponding index, otherwise return nothing. Errors if two variables have the same name.

get(
    model::ModelLike,
    ::Type{ConstraintIndex{F,S}},
    name::String,
) where {F,S}

If an F-in-S constraint with name name exists in the model model, return the corresponding index, otherwise return nothing. Errors if two constraints have the same name.

get(model::ModelLike, ::Type{ConstraintIndex}, name::String)

If any constraint with name name exists in the model model, return the corresponding index, otherwise return nothing. This version is available for convenience but may incur a performance penalty because it is not type stable. Errors if two constraints have the same name.

source
MOI.get(b::AbstractBridge, ::MOI.NumberOfVariables)::Int64

Return the number of variables created by the bridge b in the model.

See also MOI.NumberOfConstraints.

Implementation notes

  • There is a default fallback, so you need only implement this if the bridge adds new variables.
source
MOI.get(b::AbstractBridge, ::MOI.ListOfVariableIndices)

Return the list of variables created by the bridge b.

See also MOI.ListOfVariableIndices.

Implementation notes

  • There is a default fallback, so you need only implement this if the bridge adds new variables.
source
MOI.get(b::AbstractBridge, ::MOI.NumberOfConstraints{F,S})::Int64 where {F,S}

Return the number of constraints of the type F-in-S created by the bridge b.

See also MOI.NumberOfConstraints.

Implementation notes

  • There is a default fallback, so you need only implement this for the constraint types returned by added_constraint_types.
source
MOI.get(b::AbstractBridge, ::MOI.ListOfConstraintIndices{F,S}) where {F,S}

Return a Vector{ConstraintIndex{F,S}} with indices of all constraints of type F-in-S created by the bride b.

See also MOI.ListOfConstraintIndices.

Implementation notes

  • There is a default fallback, so you need only implement this for the constraint types returned by added_constraint_types.
source
function MOI.get(
    model::MOI.ModelLike,
    attr::MOI.AbstractConstraintAttribute,
    bridge::AbstractBridge,
)

Return the value of the attribute attr of the model model for the constraint bridged by bridge.

source
MathOptInterface.get! — Function
get!(output, model::ModelLike, args...)

An in-place version of get.

The signature matches that of get except that the result is placed in the vector output.

source
MathOptInterface.set — Function
set(optimizer::AbstractOptimizer, attr::AbstractOptimizerAttribute, value)

Assign value to the attribute attr of the optimizer optimizer.

set(model::ModelLike, attr::AbstractModelAttribute, value)

Assign value to the attribute attr of the model model.

set(model::ModelLike, attr::AbstractVariableAttribute, v::VariableIndex, value)

Assign value to the attribute attr of variable v in model model.

set(
    model::ModelLike,
    attr::AbstractVariableAttribute,
    v::Vector{VariableIndex},
    vector_of_values,
)

Assign a value respectively to the attribute attr of each variable in the collection v in model model.

set(
    model::ModelLike,
    attr::AbstractConstraintAttribute,
    c::ConstraintIndex,
    value,
)

Assign a value to the attribute attr of constraint c in model model.

set(
    model::ModelLike,
    attr::AbstractConstraintAttribute,
    c::Vector{ConstraintIndex{F,S}},
    vector_of_values,
) where {F,S}

Assign a value respectively to the attribute attr of each constraint in the collection c in model model.

An UnsupportedAttribute error is thrown if model does not support the attribute attr (see supports) and a SetAttributeNotAllowed error is thrown if it supports the attribute attr but it cannot be set.

set(
    model::ModelLike,
    ::ConstraintSet,
    c::ConstraintIndex{F,S},
    set::S,
) where {F,S}

Change the set of constraint c to the new set set which should be of the same type as the original set.

set(
    model::ModelLike,
    ::ConstraintFunction,
    c::ConstraintIndex{F,S},
    func::F,
) where {F,S}

Replace the function in constraint c with func. F must match the original function type used to define the constraint.

Note

Setting the constraint function is not allowed if F is VariableIndex; a SettingVariableIndexNotAllowed error is thrown instead. This is because, it would require changing the index c since the index of VariableIndex constraints must be the same as the index of the variable.

source
function MOI.set(
    model::MOI.ModelLike,
    attr::MOI.AbstractConstraintAttribute,
    bridge::AbstractBridge,
    value,
)

Set the value of the attribute attr of the model model for the constraint bridged by bridge.

source
MathOptInterface.supports — Function
supports(model::ModelLike, sub::AbstractSubmittable)::Bool

Return a Bool indicating whether model supports the submittable sub.

supports(model::ModelLike, attr::AbstractOptimizerAttribute)::Bool

Return a Bool indicating whether model supports the optimizer attribute attr. That is, it returns false if copy_to(model, src) shows a warning in case attr is in the ListOfOptimizerAttributesSet of src; see copy_to for more details on how unsupported optimizer attributes are handled in copy.

supports(model::ModelLike, attr::AbstractModelAttribute)::Bool

Return a Bool indicating whether model supports the model attribute attr. That is, it returns false if copy_to(model, src) cannot be performed in case attr is in the ListOfModelAttributesSet of src.

supports(
    model::ModelLike,
    attr::AbstractVariableAttribute,
    ::Type{VariableIndex},
)::Bool

Return a Bool indicating whether model supports the variable attribute attr. That is, it returns false if copy_to(model, src) cannot be performed in case attr is in the ListOfVariableAttributesSet of src.

supports(
    model::ModelLike,
    attr::AbstractConstraintAttribute,
    ::Type{ConstraintIndex{F,S}},
)::Bool where {F,S}

Return a Bool indicating whether model supports the constraint attribute attr applied to an F-in-S constraint. That is, it returns false if copy_to(model, src) cannot be performed in case attr is in the ListOfConstraintAttributesSet of src.

For all five methods, if the attribute is only not supported in specific circumstances, it should still return true.

Note that supports is only defined for attributes for which is_copyable returns true as other attributes do not appear in the list of attributes set obtained by ListOfXXXAttributesSet.

source
MOI.supports(
    model::MOI.ModelLike,
    attr::MOI.AbstractConstraintAttribute,
    BT::Type{<:AbstractBridge},
)

Return a Bool indicating whether BT supports setting attr to model.

source
MathOptInterface.attribute_value_type — Function
attribute_value_type(attr::AnyAttribute)

Given an attribute attr, return the type of value expected by get, or returned by set.

Notes

  • Only implement this if it make sense to do so. If un-implemented, the default is Any.
source

Model interface

MathOptInterface.is_empty — Function
is_empty(model::ModelLike)

Returns false if the model has any model attribute set or has any variables or constraints.

Note that an empty model can have optimizer attributes set.

source
MathOptInterface.empty! — Function
empty!(model::ModelLike)

Empty the model, that is, remove all variables, constraints and model attributes but not optimizer attributes.

source
MathOptInterface.write_to_file — Function
write_to_file(model::ModelLike, filename::String)

Write the current model to the file at filename.

Supported file types depend on the model type.

source
MathOptInterface.read_from_file — Function
read_from_file(model::ModelLike, filename::String)

Read the file filename into the model model. If model is non-empty, this may throw an error.

Supported file types depend on the model type.

Note

Once the contents of the file are loaded into the model, users can query the variables via get(model, ListOfVariableIndices()). However, some filetypes, such as LP files, do not maintain an explicit ordering of the variables. Therefore, the returned list may be in an arbitrary order.

To avoid depending on the order of the indices, look up each variable index by name using get(model, VariableIndex, "name").

source
MathOptInterface.copy_to — Function
copy_to(dest::ModelLike, src::ModelLike)::IndexMap

Copy the model from src into dest.

The target dest is emptied, and all previous indices to variables and constraints in dest are invalidated.

Returns an IndexMap object that translates variable and constraint indices from the src model to the corresponding indices in the dest model.

Notes

AbstractOptimizerAttributes are not copied to the dest model.

IndexMap

Implementations of copy_to must return an IndexMap. For technical reasons, this type is defined in the Utilities submodule as MOI.Utilities.IndexMap. However, since it is an integral part of the MOI API, we provide MOI.IndexMap as an alias.

Example

# Given empty `ModelLike` objects `src` and `dest`.

x = add_variable(src)

is_valid(src, x)   # true
is_valid(dest, x)  # false (`dest` has no variables)

index_map = copy_to(dest, src)
is_valid(dest, x) # false (unless index_map[x] == x)
is_valid(dest, index_map[x]) # true
source
MathOptInterface.IndexMap — Type
IndexMap()

The dictionary-like object returned by copy_to.

IndexMap

Implementations of copy_to must return an IndexMap. For technical reasons, the IndexMap type is defined in the Utilities submodule as MOI.Utilities.IndexMap. However, since it is an integral part of the MOI API, we provide this MOI.IndexMap as an alias.

source

Model attributes

MathOptInterface.Name — Type
Name()

An AbstractModelAttribute for the string identifying the model.

It has a default value of "" if not set.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.Name)::String
MOI.set(::Optimizer, ::MOI.Name, ::String)::Nothing
MOI.supports(::Optimizer, ::MOI.Name)::Bool
source
MathOptInterface.ObjectiveFunction — Type
ObjectiveFunction{F<:AbstractScalarFunction}()

An AbstractModelAttribute for the objective function which has a type F<:AbstractScalarFunction.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ObjectiveFunction{F},
)::F where {F<:MOI.AbstractFunction}
MOI.set(
    ::Optimizer,
    ::MOI.ObjectiveFunction{F},
    ::F,
)::F where {F<:MOI.AbstractFunction}
MOI.supports(::Optimizer, ::MOI.ObjectiveFunction{<:MOI.AbstractFunction})::Bool

When implementing get, F may to be equivalent but not necessarily identical to the function type set by the user. If the objective function cannot be converted to F, an InexactError must be thrown.

source
MathOptInterface.ObjectiveFunctionType — Type
ObjectiveFunctionType()

An AbstractModelAttribute for the type F of the objective function set using the ObjectiveFunction{F} attribute.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ObjectiveFunctionType,
)::Type{<:MOI.AbstractFunction}

They should not implement set or supports.

Example

julia> import MathOptInterface as MOI

julia> model = MOI.Utilities.Model{Float64}();

julia> x = MOI.add_variable(model)
MOI.VariableIndex(1)

julia> MOI.set(model, MOI.ObjectiveFunction{MOI.VariableIndex}(), x)

julia> MOI.get(model, MOI.ObjectiveFunctionType())
MathOptInterface.VariableIndex
source
MathOptInterface.ObjectiveSense — Type
ObjectiveSense()

An AbstractModelAttribute for the objective sense of the objective function, which must be an OptimizationSense.

The default is FEASIBILITY_SENSE.

Interaction with ObjectiveFunction

Setting the sense to FEASIBILITY_SENSE unsets the ObjectiveFunction attribute. That is, if you first set ObjectiveFunction and then set ObjectiveSense to be FEASIBILITY_SENSE, no objective function will be passed to the solver.

In addition, some reformulations of ObjectiveFunction via bridges rely on the value of ObjectiveSense. Therefore, you should set ObjectiveSense before setting ObjectiveFunction.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.ObjectiveSense)::MOI.OptimizationSense
MOI.set(::Optimizer, ::MOI.ObjectiveSense, ::MOI.OptimizationSense)::Nothing
MOI.supports(::Optimizer, ::MOI.ObjectiveSense)::Bool
source
MathOptInterface.ListOfVariableIndices — Type
ListOfVariableIndices()

An AbstractModelAttribute for querying the Vector{MOI.VariableIndex} of all [MOI.VariableIndex] present in the model.

Order

The variables must be returned in the order in which they were added to the model.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.ListOfVariableIndices)::Vector{MOI.VariableIndex}

They should not implement set or supports.

source
MathOptInterface.NumberOfConstraints — Type
NumberOfConstraints{F,S}()

An AbstractModelAttribute for querying the number of constraints of the type F-in-S present in the model.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.NumberOfConstraints{F,S},
)::Int64 where {F<:MOI.AbstractFunction,MOI.AbstractSet}

They should not implement set or supports.

source
MathOptInterface.ListOfConstraintIndices — Type
ListOfConstraintIndices{F,S}()

An AbstractModelAttribute for the Vector{MOI.ConstraintIndex{F,S}} of all constraint indices of type F-in-S in the model.

Order

The constraints must be returned in the order in which they were added to the model.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ListOfConstraintIndices{F,S},
)::Vector{MOI.ConstraintIndex{F,S}} where {F<:MOI.AbstractFunction,MOI.AbstractSet}

They should not implement set or supports.

source
MathOptInterface.ListOfVariableAttributesSet — Type
ListOfVariableAttributesSet()

An AbstractModelAttribute for the Vector{AbstractVariableAttribute} of all variable attributes attr such that:

  1. is_copyable(attr) returns true
  2. the attribute was set for at least one variable in the model

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ListOfVariableAttributesSet,
)::Vector{MOI.AbstractVariableAttribute}

They should not implement set or supports.

source
MathOptInterface.ListOfVariablesWithAttributeSet — Type
ListOfVariablesWithAttributeSet(attr::AbstractVariableAttribute)

An AbstractModelAttribute for the Vector{MOI.VariableIndex} of all variables with the attribute attr set.

The returned list may not be minimal, so some elements may have their default value set.

Note

This is an optional attribute to implement. The default fallback is to get ListOfVariableIndices.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ListOfVariablesWithAttributeSet{<:MOI.AbstractVariableAttribute},
)::Vector{MOI.VarialbeIndex}

They should not implement set or supports.

source
MathOptInterface.UserDefinedFunction — Type
UserDefinedFunction(name::Symbol, arity::Int) <: AbstractModelAttribute

Set this attribute to register a user-defined function by the name of name with arity arguments.

Once registered, name will appear in ListOfSupportedNonlinearOperators.

You cannot register multiple UserDefinedFunctions with the same name but different arity.

Value type

The value to be set is a tuple containing one, two, or three functions to evaluate the function, the first-order derivative, and the second-order derivative respectively. Both derivatives are optional, but if you pass the second-order derivative you must also pass the first-order derivative.

For univariate functions with arity == 1, the functions in the tuple must have the form:

  • f(x::T)::T: returns the value of the function at x
  • ∇f(x::T)::T: returns the first-order derivative of f with respect to x
  • ∇²f(x::T)::T: returns the second-order derivative of f with respect to x.

For multivariate functions with arity > 1, the functions in the tuple must have the form:

  • f(x::T...)::T: returns the value of the function at x
  • ∇f(g::AbstractVector{T}, x::T...)::Nothing: fills the components of g, with g[i] being the first-order partial derivative of f with respect to x[i]
  • ∇²f(H::AbstractMatrix{T}, x::T...)::Nothing: fills the non-zero components of H, with H[i, j] being the second-order partial derivative of f with respect to x[i] and then x[j]. H is initialized to the zero matrix, so you do not need to set any zero elements.

Example

julia> import MathOptInterface as MOI

julia> f(x, y) = x^2 + y^2
f (generic function with 1 method)

julia> function ∇f(g, x, y)
           g .= 2 * x, 2 * y
           return
       end
∇f (generic function with 1 method)

julia> function ∇²f(H, x...)
           H[1, 1] = H[2, 2] = 2.0
           return
       end
∇²f (generic function with 1 method)

julia> model = MOI.Utilities.UniversalFallback(MOI.Utilities.Model{Float64}());

julia> MOI.set(model, MOI.UserDefinedFunction(:f, 2), (f,))

julia> MOI.set(model, MOI.UserDefinedFunction(:g, 2), (f, ∇f))

julia> MOI.set(model, MOI.UserDefinedFunction(:h, 2), (f, ∇f, ∇²f))

julia> x = MOI.add_variables(model, 2)
2-element Vector{MathOptInterface.VariableIndex}:
 MOI.VariableIndex(1)
 MOI.VariableIndex(2)

julia> MOI.set(model, MOI.ObjectiveSense(), MOI.MIN_SENSE)

julia> obj_f = MOI.ScalarNonlinearFunction(:f, Any[x[1], x[2]])
f(MOI.VariableIndex(1), MOI.VariableIndex(2))

julia> MOI.set(model, MOI.ObjectiveFunction{typeof(obj_f)}(), obj_f)

julia> print(model)
Minimize ScalarNonlinearFunction:
 f(v[1], v[2])

Subject to:
source
MathOptInterface.ListOfSupportedNonlinearOperators — Type
ListOfSupportedNonlinearOperators() <: AbstractModelAttribute

When queried with get, return a Vector{Symbol} listing the operators supported by the model. These operators may appear in the head field of ScalarNonlinearFunction.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ListOfSupportedNonlinearOperators,
)::Vector{Symbol}

They should not implement set or supports.

source

Optimizer interface

MathOptInterface.AbstractOptimizer — Type
AbstractOptimizer <: ModelLike

Abstract supertype for objects representing an instance of an optimization problem tied to a particular solver. This is typically a solver's in-memory representation. In addition to ModelLike, AbstractOptimizer objects let you solve the model and query the solution.

source
MathOptInterface.optimize! — Method
optimize!(dest::AbstractOptimizer, src::ModelLike)::Tuple{IndexMap,Bool}

A "one-shot" call that copies the problem from src into dest and then uses dest to optimize the problem.

Returns a tuple of an IndexMap and a Bool copied.

  • The IndexMap object translates variable and constraint indices from the src model to the corresponding indices in the dest optimizer. See copy_to for details.
  • If copied == true, src was copied to dest and then cached, allowing incremental modification if supported by the solver.
  • If copied == false, a cache of the model was not kept in dest. Therefore, only the solution information (attributes for which is_set_by_optimize is true) is available to query.
Note

The main purpose of optimize! method with two arguments is for use in Utilities.CachingOptimizer.

Relationship to the single-argument optimize!

The default fallback of optimize!(dest::AbstractOptimizer, src::ModelLike) is

function optimize!(dest::AbstractOptimizer, src::ModelLike)
    index_map = copy_to(dest, src)
    optimize!(dest)
    return index_map, true
end

Therefore, subtypes of AbstractOptimizer should either implement this two-argument method, or implement both copy_to(::Optimizer, ::ModelLike) and optimize!(::Optimizer).

source
MathOptInterface.instantiate — Function
instantiate(
    optimizer_constructor,
    with_cache_type::Union{Nothing,Type} = nothing,
    with_bridge_type::Union{Nothing,Type} = nothing,
)

Create an instance of an optimizer by either:

  • calling optimizer_constructor.optimizer_constructor() and setting the parameters in optimizer_constructor.params if optimizer_constructor is a OptimizerWithAttributes
  • calling optimizer_constructor() if optimizer_constructor is callable.

withcachetype

If with_cache_type is not nothing, then the optimizer is wrapped in a Utilities.CachingOptimizer to store a cache of the model. This is most useful if the optimizer you are constructing does not support the incremental interface (see supports_incremental_interface).

withbridgetype

If with_bridge_type is not nothing, the optimizer is wrapped in a Bridges.full_bridge_optimizer, enabling all the bridges defined in the MOI.Bridges submodule with coefficient type with_bridge_type.

In addition, if the optimizer created by optimizer_constructor does not support the incremental interface (see supports_incremental_interface), then, irrespective of with_cache_type, the optimizer is wrapped in a Utilities.CachingOptimizer to store a cache of the bridged model.

If with_cache_type and with_bridge_type are both not nothing, then they must be the same type.

source
MathOptInterface.default_cache — Function
default_cache(optimizer::ModelLike, ::Type{T}) where {T}

Return a new instance of the default model type to be used as cache for optimizer in a Utilities.CachingOptimizer for holding constraints of coefficient type T. By default, this returns Utilities.UniversalFallback(Utilities.Model{T}()). If copying from a instance of a given model type is faster for optimizer then a new method returning an instance of this model type should be defined.

source

Optimizer attributes

MathOptInterface.SolverVersion — Type
SolverVersion()

An AbstractOptimizerAttribute for the string identifying the version of the solver.

Versioning systems

For solvers supporting semantic versioning, the SolverVersion should be a string of the form "vMAJOR.MINOR.PATCH", so that it can be converted to a Julia VersionNumber (for example, `VersionNumber("v1.2.3")).

We do not require Semantic Versioning because some solvers use alternate versioning systems. For example, CPLEX uses Calendar Versioning, so SolverVersion will return a string like "202001".

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.SolverVersion)::String

They should not implement set or supports.

source
MathOptInterface.Silent — Type
Silent()

An AbstractOptimizerAttribute for silencing the output of an optimizer.

When set to true, this attribute takes precedence over any other attribute controlling verbosity and requires the optimizer to produce no output.

The default value is false which has no effect. In this case the verbosity is controlled by other optimizer-specific attributes.

Value and default

The provided value must be a Bool.

The default value is false.

Note

Every optimizer should have verbosity on by default. For instance, if a solver has a solver-specific log level attribute, the MOI implementation should set it to 1 by default. If the user sets Silent to true, then the log level should be set to 0, even if the user specifically sets a value of log level. If the value of Silent is false then the log level set to the solver is the value given by the user for this solver-specific parameter or 1 if none is given.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.Silent)::Bool
MOI.set(::Optimizer, ::MOI.Silent, ::Bool)::Nothing
MOI.supports(::Optimizer, ::MOI.Silent)::Bool
source
MathOptInterface.TimeLimitSec — Type
TimeLimitSec()

An AbstractOptimizerAttribute for setting a time limit (in seconds) for a call to optimize!.

Value and default

The provided limit must be a Union{Nothing,Real}.

When set to nothing, it deactivates the time limit.

The default value is nothing.

TerminationStatus

The optimizer may stop when the SolveTimeSec is larger than the TimeLimitSec. If stopped because of this limit, the TerminationStatus must be TIME_LIMIT.

Note that most optimizers do not strictly respect a time limit. Instead, they terminate at the first convenient time after the time limit has been exceeded. Thus, you may find that the SolveTimeSec exceeds the TimeLimitSec by a few seconds.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.TimeLimitSec)::Union{Nothing,Float64}
MOI.set(::Optimizer, ::MOI.TimeLimitSec, ::Union{Nothing,Real})::Nothing
MOI.supports(::Optimizer, ::MOI.TimeLimitSec)::Bool
source
MathOptInterface.ObjectiveLimit — Type
ObjectiveLimit()

An AbstractOptimizerAttribute for setting a limit on the objective value.

Value and default

The provided limit must be a Union{Nothing,Real}.

When set to nothing, the limit reverts to the solver's default.

The default value is nothing.

TerminationStatus

The solver may stop when the ObjectiveValue is better (lower for minimization, higher for maximization) than the ObjectiveLimit. If stopped, because of this limit, the TerminationStatus should be OBJECTIVE_LIMIT.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.ObjectiveLimit)::Union{Nothing,Float64}
MOI.set(::Optimizer, ::MOI.ObjectiveLimit, ::Union{Nothing,Real})::Nothing
MOI.supports(::Optimizer, ::MOI.ObjectiveLimit)::Bool
source
MathOptInterface.SolutionLimit — Type
SolutionLimit()

An AbstractOptimizerAttribute for setting a limit on the number of available feasible solutions.

Value and default

The provided limit must be a Union{Nothing,Int}.

When set to nothing, the limit reverts to the solver's default.

The default value is nothing.

Termination criteria

The solver may stop when the ResultCount is larger than or equal to the SolutionLimit. If stopped because of this attribute, the TerminationStatus must be SOLUTION_LIMIT.

Solution quality

The quality of the available solutions is solver-dependent. The set of resulting solutions is not guaranteed to contain an optimal solution.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.SolutionLimit)::Union{Nothing,Int}
MOI.set(::Optimizer, ::MOI.SolutionLimit, ::Union{Nothing,Int})::Nothing
MOI.supports(::Optimizer, ::MOI.SolutionLimit)::Bool
source
MathOptInterface.NodeLimit — Type
NodeLimit()

An AbstractOptimizerAttribute for setting a limit on the number of branch-and-bound nodes explored by a mixed-integer program (MIP) solver.

Value and default

The provided limit must be a Union{Nothing,Int}.

When set to nothing, the limit reverts to the solver's default.

The default value is nothing.

Termination criteria

The solver may stop when the NodeCount is larger than or equal to the NodeLimit. If stopped because of this attribute, the TerminationStatus must be NODE_LIMIT.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.NodeLimit)::Union{Nothing,Int}
MOI.set(::Optimizer, ::MOI.NodeLimit, ::Union{Nothing,Int})::Nothing
MOI.supports(::Optimizer, ::MOI.NodeLimit)::Bool
source
MathOptInterface.RawOptimizerAttribute — Type
RawOptimizerAttribute(name::String)

An AbstractOptimizerAttribute for the solver-specific parameter identified by name.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.RawOptimizerAttribute)::Any
MOI.set(::Optimizer, ::MOI.RawOptimizerAttribute, ::Any)::Nothing
MOI.supports(::Optimizer, ::MOI.RawOptimizerAttribute)::Bool
source
MathOptInterface.NumberOfThreads — Type
NumberOfThreads()

An AbstractOptimizerAttribute for setting the number of threads used for an optimization.

Value and default

The provided value must be nothing or a positive Int.

When set to nothing, the value reverts to the solver's default.

The default value is nothing.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.NumberOfThreads)::Union{Nothing,Int}
MOI.set(::Optimizer, ::MOI.NumberOfThreads, ::Union{Nothing,Int})::Nothing
MOI.supports(::Optimizer, ::MOI.NumberOfThreads)::Bool
source
MathOptInterface.AbsoluteGapTolerance — Type
AbsoluteGapTolerance()

An AbstractOptimizerAttribute for setting the absolute gap tolerance for an optimization.

Definition

The mathematical definition of "absolute gap" and its allowed range are solver-dependent. However, most solvers that implement this attribute will stop once $|f - b| ≤ g_{abs}$, where $b$ is the best bound, $f$ is the best feasible objective value, and $g_{abs}$ is the absolute gap.

Value and default

The provided value must be a Union{Nothing,Float64}.

When set to nothing, the limit reverts to the solver's default.

TerminationStatus

The optimizer may stop when the absolute difference between ObjectiveValue and ObjectiveBound is smaller than the AbsoluteGapTolerance. If stopped because of this limit, the TerminationStatus may be OPTIMAL.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.AbsoluteGapTolerance)::Union{Nothing,Float64}
MOI.set(
    ::Optimizer,
    ::MOI.AbsoluteGapTolerance,
    ::Union{Nothing,Float64},
)::Nothing
MOI.supports(::Optimizer, ::MOI.AbsoluteGapTolerance)::Bool
source
MathOptInterface.RelativeGapTolerance — Type
RelativeGapTolerance()

An AbstractOptimizerAttribute for setting the relative gap tolerance for an optimization.

Definition

The mathematical definition of "relative gap" and its allowed range are solver-dependent. Typically, solvers expect a value between 0.0 and 1.0.

Value and default

The provided value must be a Union{Nothing,Float64}.

When set to nothing, the limit reverts to the solver's default.

TerminationStatus

The optimizer may stop when the RelativeGap is smaller than the RelativeGapTolerance. If stopped because of this limit, the TerminationStatus may be OPTIMAL.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.RelativeGapTolerance)::Union{Nothing,Float64}
MOI.set(
    ::Optimizer,
    ::MOI.RelativeGapTolerance,
    ::Union{Nothing,Float64},
)::Nothing
MOI.supports(::Optimizer, ::MOI.RelativeGapTolerance)::Bool
source
MathOptInterface.AutomaticDifferentiationBackend — Type
AutomaticDifferentiationBackend() <: AbstractOptimizerAttribute

An AbstractOptimizerAttribute for setting the automatic differentiation backend used by the solver.

The value must be a subtype of Nonlinear.AbstractAutomaticDifferentiation.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.AutomaticDifferentiationBackend,
)::MOI.Nonlinear.AbstractAutomaticDifferentiation
MOI.set(
    ::Optimizer,
    ::MOI.AutomaticDifferentiationBackend,
    ::MOI.Nonlinear.AbstractAutomaticDifferentiation,
)::Nothing
MOI.supports(::Optimizer, ::MOI.AutomaticDifferentiationBackend)::Bool
source

List of attributes useful for optimizers

MathOptInterface.TerminationStatusCode — Type
TerminationStatusCode

An Enum of possible values for the TerminationStatus attribute.

This attribute explains why the optimizer stopped executing in the most recent call to optimize!.

Values

OPTIMIZE_NOT_CALLED

The algorithm has not started.

OPTIMAL

The algorithm found a globally optimal solution.

INFEASIBLE

The algorithm proved that no primal feasible solution exists.

DUAL_INFEASIBLE

The algorithm proved that no dual feasible solution exists.

To check if the primal problem is feasible, set the objective sense to FEASIBILITY_SENSE and re-solve the problem.

If a primal feasible point does not exist, the original problem is both primal and dual infeasible.

If a primal feasible solution exists, this status typically implies that the problem is unbounded, with some technical exceptions (for example, if the problem is a conic optimization problem in which strong duality does not hold).

The technical exceptions do not apply to linear programs. The combination of DUAL_INFEASIBLE and a primal feasible point means that the primal linear program is unbounded.

LOCALLY_SOLVED

The algorithm converged to a stationary point, local optimal solution, could not find directions for improvement, or otherwise completed its search without global guarantees.

LOCALLY_INFEASIBLE

The algorithm converged to an infeasible point or otherwise completed its search without finding a feasible solution, without guarantees that no feasible solution exists.

If you know a primal feasible solution exists, use VariablePrimalStart to provide a feasible starting point to the solver.

INFEASIBLE_OR_UNBOUNDED

The algorithm stopped because it proved that the problem is infeasible or unbounded, without distinguishing between the two cases.

To distinguish between the two cases, set the objective sense to FEASIBILITY_SENSE and re-solve the problem. If a primal feasible point exists, the original problem is unbounded. If a primal feasible point does not exist, the original problem is infeasible.

ALMOST_OPTIMAL

The algorithm found a globally optimal solution to relaxed tolerances.

ALMOST_INFEASIBLE

The algorithm concluded that no feasible solution exists within relaxed tolerances.

ALMOST_DUAL_INFEASIBLE

The algorithm concluded that no dual bound exists for the problem within relaxed tolerances.

ALMOST_LOCALLY_SOLVED

The algorithm converged to a stationary point, local optimal solution, or could not find directions for improvement within relaxed tolerances.

ITERATION_LIMIT

An iterative algorithm stopped after conducting the maximum number of iterations.

TIME_LIMIT

The algorithm stopped after a user-specified computation time.

This status may be returned in relation to the TimeLimitSec attribute, or some other solver-specific attribute.

NODE_LIMIT

A branch-and-bound algorithm stopped because it explored a maximum number of nodes in the branch-and-bound tree.

This status may be returned in relation to the NodeLimit attribute, or some other solver-specific attribute.

SOLUTION_LIMIT

The algorithm stopped because it found the required number of solutions. This is often used in MIPs to get the solver to return the first feasible solution it encounters.

This status may be returned in relation to the SolutionLimit attribute, or some other solver-specific attribute.

MEMORY_LIMIT

The algorithm stopped because it ran out of memory.

OBJECTIVE_LIMIT

The algorithm stopped because it found a solution better than a minimum limit set by the user.

This status may be returned in relation to the ObjectiveLimit attribute, or some other solver-specific attribute.

NORM_LIMIT

The algorithm stopped because the norm of an iterate became too large.

This typically means that the primal problem is unbounded, but that the solver could not prove so.

OTHER_LIMIT

The algorithm stopped due to a limit not covered by one of the _LIMIT_ statuses above.

SLOW_PROGRESS

The algorithm stopped because it was unable to continue making progress towards the solution.

NUMERICAL_ERROR

The algorithm stopped because it encountered unrecoverable numerical error.

INVALID_MODEL

The algorithm stopped because the model is invalid.

The reason for this return code is solver-specific, but common causes are that the problem has zero variables or constraints, or that the problem data contains an invalid number such as NaN.

INVALID_OPTION

The algorithm stopped because it was provided an invalid option.

INTERRUPTED

The algorithm stopped because of an interrupt signal.

This typically means that the solver was interrupted by the user with CTRL+C.

OTHER_ERROR

The algorithm stopped because of an error not covered by one of the statuses defined above. Check the solver log for further details.

source
MathOptInterface.DUAL_INFEASIBLE — Constant
DUAL_INFEASIBLE::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm proved that no dual feasible solution exists.

To check if the primal problem is feasible, set the objective sense to FEASIBILITY_SENSE and re-solve the problem.

If a primal feasible point does not exist, the original problem is both primal and dual infeasible.

If a primal feasible solution exists, this status typically implies that the problem is unbounded, with some technical exceptions (for example, if the problem is a conic optimization problem in which strong duality does not hold).

The technical exceptions do not apply to linear programs. The combination of DUAL_INFEASIBLE and a primal feasible point means that the primal linear program is unbounded.

source
MathOptInterface.LOCALLY_SOLVED — Constant
LOCALLY_SOLVED::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm converged to a stationary point, local optimal solution, could not find directions for improvement, or otherwise completed its search without global guarantees.

source
MathOptInterface.LOCALLY_INFEASIBLE — Constant
LOCALLY_INFEASIBLE::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm converged to an infeasible point or otherwise completed its search without finding a feasible solution, without guarantees that no feasible solution exists.

If you know a primal feasible solution exists, use VariablePrimalStart to provide a feasible starting point to the solver.

source
MathOptInterface.INFEASIBLE_OR_UNBOUNDED — Constant
INFEASIBLE_OR_UNBOUNDED::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm stopped because it proved that the problem is infeasible or unbounded, without distinguishing between the two cases.

To distinguish between the two cases, set the objective sense to FEASIBILITY_SENSE and re-solve the problem. If a primal feasible point exists, the original problem is unbounded. If a primal feasible point does not exist, the original problem is infeasible.

source
MathOptInterface.NODE_LIMIT — Constant
NODE_LIMIT::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

A branch-and-bound algorithm stopped because it explored a maximum number of nodes in the branch-and-bound tree.

This status may be returned in relation to the NodeLimit attribute, or some other solver-specific attribute.

source
MathOptInterface.SOLUTION_LIMIT — Constant
SOLUTION_LIMIT::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm stopped because it found the required number of solutions. This is often used in MIPs to get the solver to return the first feasible solution it encounters.

This status may be returned in relation to the SolutionLimit attribute, or some other solver-specific attribute.

source
MathOptInterface.NORM_LIMIT — Constant
NORM_LIMIT::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm stopped because the norm of an iterate became too large.

This typically means that the primal problem is unbounded, but that the solver could not prove so.

source
MathOptInterface.INVALID_MODEL — Constant
INVALID_MODEL::TerminationStatusCode

An instance of the TerminationStatusCode enum.

About

The algorithm stopped because the model is invalid.

The reason for this return code is solver-specific, but common causes are that the problem has zero variables or constraints, or that the problem data contains an invalid number such as NaN.

source
MathOptInterface.PrimalStatus — Type
PrimalStatus(result_index::Int = 1)

An AbstractModelAttribute for the ResultStatusCode of the primal result result_index.

result_index

If result_index is omitted, it defaults to 1.

See ResultCount for information on how the results are ordered.

If result_index is larger than the value of ResultCount then NO_SOLUTION is returned.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.PrimalStatus)::MOI.ResultStatusCode

They should not implement set or supports.

source
MathOptInterface.ResultCount — Type
ResultCount()

An AbstractModelAttribute for the number of results available.

Order of solutions

A number of attributes contain an index, result_index, which is used to refer to one of the available results. Thus, result_index must be an integer between 1 and the number of available results.

As a general rule, the first result (result_index = 1) is the most important result (for example, an optimal solution or an infeasibility certificate). Other results will typically be alternate solutions that the solver found during the search for the first result.

If a (local) optimal solution is available, that is, TerminationStatus is OPTIMAL or LOCALLY_SOLVED, the first result must correspond to the (locally) optimal solution. Other results may be alternative optimal solutions, or they may be other suboptimal solutions; use ObjectiveValue to distinguish between them.

If a primal or dual infeasibility certificate is available, that is, TerminationStatus is INFEASIBLE or DUAL_INFEASIBLE and the corresponding PrimalStatus or DualStatus is INFEASIBILITY_CERTIFICATE, then the first result must be a certificate. Other results may be alternate certificates, or infeasible points.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.ResultCount)::Int

They should not implement set or supports.

source
MathOptInterface.ObjectiveValue — Type
ObjectiveValue(result_index::Int = 1)

An AbstractModelAttribute for the objective value of the primal solution result_index.

PrimalStatus

Before quering this attribute you should first check PrimalStatus to confirm that a primal solution is avaiable.

If the PrimalStatus is NO_SOLUTION the result of querying this attribute is undefined.

result_index

The optimizer may return multiple primal solutions. See ResultCount for information on how the results are ordered.

If the solver does not have a primal value for the objective because the result_index is beyond the available solutions (whose number is indicated by the ResultCount attribute), getting this attribute must throw a ResultIndexBoundsError.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.ObjectiveValue,
)::Union{T,Vector{T}} where {T<:Real}

They should not implement set or supports.

source
MathOptInterface.DualObjectiveValue — Type
DualObjectiveValue(result_index::Int = 1)

An AbstractModelAttribute for the value of the objective function of the dual solution result_index.

DualStatus

Before quering this attribute you should first check DualStatus to confirm that a dual solution is avaiable.

If the DualStatus is NO_SOLUTION the result of querying this attribute is undefined.

result_index

The optimizer may return multiple dual solutions. See ResultCount for information on how the results are ordered.

If the solver does not have a dual value for the objective because the result_index is beyond the available solutions (whose number is indicated by the ResultCount attribute), getting this attribute must throw a ResultIndexBoundsError.

Implementation

Optimizers should implement the following methods:

MOI.get(
    ::Optimizer,
    ::MOI.DualObjectiveValue,
)::Union{T,Vector{T}} where {T<:Real}

They should not implement set or supports.

source
MathOptInterface.RelativeGap — Type
RelativeGap()

An AbstractModelAttribute for the final relative optimality gap.

Warning

The definition of this gap is solver-dependent. However, most solvers implementing this attribute define the relative gap as some variation of $\frac{|b-f|}{|f|}$, where $b$ is the best bound and $f$ is the best feasible objective value.

source
MathOptInterface.SimplexIterations — Type
SimplexIterations()

An AbstractModelAttribute for the cumulative number of simplex iterations while solving a problem.

For a mixed-integer program (MIP), the return value is the total simplex iterations for all nodes.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.SimplexIterations)::Int64

They should not implement set or supports.

source
MathOptInterface.BarrierIterations — Type
BarrierIterations()

An AbstractModelAttribute for the cumulative number of barrier iterations while solving a problem.

For a mixed-integer program (MIP), the return value is the total barrier iterations for all nodes.

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.BarrierIterations)::Int64

They should not implement set or supports.

source
MathOptInterface.NodeCount — Type
NodeCount()

An AbstractModelAttribute for the total number of branch-and-bound nodes explored while solving a mixed-integer program (MIP).

Implementation

Optimizers should implement the following methods:

MOI.get(::Optimizer, ::MOI.NodeCount)::Int64

They should not implement set or supports.

source

ResultStatusCode

MathOptInterface.ResultStatusCode — Type
ResultStatusCode

An Enum of possible values for the PrimalStatus and DualStatus attributes.

The values indicate how to interpret the result vector.

Values

NO_SOLUTION

The result vector is empty.

FEASIBLE_POINT

The result vector is a feasible point.

NEARLY_FEASIBLE_POINT

The result vector is feasible if some constraint tolerances are relaxed.

INFEASIBLE_POINT

The result vector is an infeasible point.

INFEASIBILITY_CERTIFICATE

The result vector is an infeasibility certificate.

If the PrimalStatus is INFEASIBILITY_CERTIFICATE, then the primal result vector is a certificate of dual infeasibility.

If the DualStatus is INFEASIBILITY_CERTIFICATE, then the dual result vector is a proof of primal infeasibility.

NEARLY_INFEASIBILITY_CERTIFICATE

The result satisfies a relaxed criterion for a certificate of infeasibility.

If the PrimalStatus is NEARLY_INFEASIBILITY_CERTIFICATE, then the primal result vector is a certificate of dual infeasibility.

If the DualStatus is NEARLY_INFEASIBILITY_CERTIFICATE, then the dual result vector is a proof of primal infeasibility.

REDUCTION_CERTIFICATE

The result vector is an ill-posed certificate; see this article for details.

If the PrimalStatus is REDUCTION_CERTIFICATE, then the primal result vector is a proof that the dual problem is ill-posed.

If the DualStatus is REDUCTION_CERTIFICATE, then the dual result vector is a proof that the primal is ill-posed.

NEARLY_REDUCTION_CERTIFICATE

The result satisfies a relaxed criterion for an ill-posed certificate.

UNKNOWN_RESULT_STATUS

The result vector contains a solution with an unknown interpretation. Check the solver log for more details.

OTHER_RESULT_STATUS

The result vector contains a solution with an interpretation not covered by one of the statuses defined above. Check the solver log for more details.

source

Conflict Status

MathOptInterface.compute_conflict! — Function
compute_conflict!(optimizer::AbstractOptimizer)

Computes a minimal subset of constraints such that the model with the other constraint removed is still infeasible.

Some solvers call a set of conflicting constraints an Irreducible Inconsistent Subsystem (IIS).

See also ConflictStatus and ConstraintConflictStatus.

Note

If the model is modified after a call to compute_conflict!, the implementor is not obliged to purge the conflict. Any calls to the above attributes may return values for the original conflict without a warning. Similarly, when modifying the model, the conflict can be discarded.

source
MathOptInterface.ConflictStatusCode — Type
ConflictStatusCode

An Enum of possible values for the ConflictStatus attribute.

This attribute is meant to explain the reason why the conflict finder stopped executing in the most recent call to compute_conflict!.

Values

COMPUTE_CONFLICT_NOT_CALLED

The function compute_conflict! has not yet been called.

NO_CONFLICT_EXISTS

There is no conflict because the problem is feasible.

NO_CONFLICT_FOUND

The solver could not find a conflict.

CONFLICT_FOUND

The solver found a conflict.

source
MathOptInterface.ConflictParticipationStatusCode — Type
ConflictParticipationStatusCode

An Enum for the value of the ConstraintConflictStatus attribute.

This attribute is meant to indicate whether a given constraint participates or not in the last computed conflict.

Values

NOT_IN_CONFLICT

The constraint does not participate in the conflict.

IN_CONFLICT

The constraint participates in the conflict.

MAYBE_IN_CONFLICT

The solver was not able to prove whether the constraint is required to participate in the conflict.

source