Constraint API
More information can be found in the Constraints section of the manual.
JuMP.@constraint
— Macro@constraint(m::Model, expr)
Add a constraint described by the expression expr
.
@constraint(m::Model, ref[i=..., j=..., ...], expr)
Add a group of constraints described by the expression expr
parametrized by i
, j
, ...
The expression expr
can either be
- of the form
func in set
constraining the functionfunc
to belong to the setset
which is either aMOI.AbstractSet
or one of the JuMP shortcutsSecondOrderCone
,RotatedSecondOrderCone
andPSDCone
, e.g.@constraint(model, [1, x-1, y-2] in SecondOrderCone())
constrains the norm of[x-1, y-2]
be less than 1; - of the form
a sign b
, wheresign
is one of==
,≥
,>=
,≤
and<=
building the single constraint enforcing the comparison to hold for the expressiona
andb
, e.g.@constraint(m, x^2 + y^2 == 1)
constrainsx
andy
to lie on the unit circle; - of the form
a ≤ b ≤ c
ora ≥ b ≥ c
(where≤
and<=
(resp.≥
and>=
) can be used interchangeably) constraining the paired the expressionb
to lie betweena
andc
; - of the forms
@constraint(m, a .sign b)
or@constraint(m, a .sign b .sign c)
which broadcast the constraint creation to each element of the vectors.
Note for extending the constraint macro
Each constraint will be created using add_constraint(m, build_constraint(_error, func, set))
where
_error
is an error function showing the constraint call in addition to the error message given as argument,func
is the expression that is constrained- and
set
is the set in which it is constrained to belong.
For expr
of the first type (i.e. @constraint(m, func in set)
), func
and set
are passed unchanged to build_constraint
but for the other types, they are determined from the expressions and signs. For instance, @constraint(m, x^2 + y^2 == 1)
is transformed into add_constraint(m, build_constraint(_error, x^2 + y^2, MOI.EqualTo(1.0)))
.
To extend JuMP to accept new constraints of this form, it is necessary to add the corresponding methods to build_constraint
. Note that this will likely mean that either func
or set
will be some custom type, rather than e.g. a Symbol
, since we will likely want to dispatch on the type of the function or set appearing in the constraint.
JuMP.@constraints
— Macro@constraints(model, args...)
Adds groups of constraints at once, in the same fashion as the @constraint
macro.
The model must be the first argument, and multiple constraints can be added on multiple lines wrapped in a begin ... end
block.
Examples
@constraints(model, begin
x >= 1
y - w <= 2
sum_to_one[i=1:3], z[i] + y == 1
end)
JuMP.@SDconstraint
— Macro@SDconstraint(model::Model, expr)
Add a semidefinite constraint described by the expression expr
.
@SDconstraint(model::Model, ref[i=..., j=..., ...], expr)
Add a group of semidefinite constraints described by the expression expr
parametrized by i
, j
, ...
The expression expr
needs to be of the form a sign b
where sign
is ⪰
, ≥
, >=
, ⪯
, ≤
or <=
and a
and b
are square
matrices. It constrains the square matrix x
(or -x
if the sign is ⪯
, ≤
or <=
) to be symmetric and positive semidefinite where
x = a
, ifb
is the symbol0
,x = -b
, ifa
is the symbol0
,- otherwise,
x = a - b
.
By default, we check numerical symmetry of the matrix x
, and if symmetry is violated by some arbitrary amount, we add explicit equality constraints. You can use Symmetric(x) in PSDCone()
with the @constraint
macro to skip these checks if you know the matrix must be symmetric; see PSDCone
for more information.
Examples
The following constrains the matrix [x-1 2x-2; -3 x-4]
to be symmetric and positive semidefinite, that is, it constrains 2x-2
to be equal to -3
and constrains all eigenvalues of the matrix to be nonnegative.
julia> model = Model();
julia> @variable(model, x)
x
julia> a = [x 2x
0 x];
julia> b = [1 2
3 4];
julia> cref = @SDconstraint(model, a ⪰ b)
[x - 1 2 x - 2;
-3 x - 4 ] ∈ PSDCone()
julia> jump_function(constraint_object(cref))
4-element Array{GenericAffExpr{Float64,VariableRef},1}:
x - 1
-3
2 x - 2
x - 4
julia> moi_set(constraint_object(cref))
MathOptInterface.PositiveSemidefiniteConeSquare(2)
In the set PositiveSemidefiniteConeSquare(2)
in the last output, Square
means that the matrix is passed as a square matrix as the corresponding off-diagonal entries need to be constrained to be equal. A similar set PositiveSemidefiniteConeTriangle
exists which only uses the upper triangular part of the matrix assuming that it is symmetric, see PSDCone
to see how to use it.
JuMP.@SDconstraints
— Macro@SDconstraints(model, args...)
Adds multiple semi-definite constraints to model at once, in the same fashion as the @SDconstraint
macro.
The model must be the first argument, and multiple constraints can be added on multiple lines wrapped in a begin ... end
block.
Examples
@SDconstraints(model, begin
A * x >= b
b - C * y >= 0
end)
JuMP.name
— Methodname(con_ref::ConstraintRef)
Get a constraint's name attribute.
JuMP.set_name
— Methodset_name(con_ref::ConstraintRef, s::AbstractString)
Set a constraint's name attribute.
JuMP.constraint_by_name
— Functionconstraint_by_name(model::AbstractModel,
name::String)::Union{ConstraintRef, Nothing}
Returns the reference of the constraint with name attribute name
or Nothing
if no constraint has this name attribute. Throws an error if several constraints have name
as their name attribute.
constraint_by_name(model::AbstractModel,
name::String,
F::Type{<:Union{AbstractJuMPScalar,
Vector{<:AbstractJuMPScalar},
MOI.AbstactFunction}},
S::Type{<:MOI.AbstractSet})::Union{ConstraintRef, Nothing}
Similar to the method above, except that it throws an error if the constraint is not an F
-in-S
contraint where F
is either the JuMP or MOI type of the function, and S
is the MOI type of the set. This method is recommended if you know the type of the function and set since its returned type can be inferred while for the method above (i.e. without F
and S
), the exact return type of the constraint index cannot be inferred.
julia> using JuMP
julia> model = Model()
A JuMP Model
Feasibility problem with:
Variables: 0
Model mode: AUTOMATIC
CachingOptimizer state: NO_OPTIMIZER
Solver name: No optimizer attached.
julia> @variable(model, x)
x
julia> @constraint(model, con, x^2 == 1)
con : x² = 1.0
julia> constraint_by_name(model, "kon")
julia> constraint_by_name(model, "con")
con : x² = 1.0
julia> constraint_by_name(model, "con", AffExpr, MOI.EqualTo{Float64})
julia> constraint_by_name(model, "con", QuadExpr, MOI.EqualTo{Float64})
con : x² = 1.0
JuMP.normalized_coefficient
— Functionnormalized_coefficient(con_ref::ConstraintRef, variable::VariableRef)
Return the coefficient associated with variable
in constraint
after JuMP has normalized the constraint into its standard form. See also set_normalized_coefficient
.
JuMP.set_normalized_coefficient
— Functionset_normalized_coefficient(con_ref::ConstraintRef, variable::VariableRef, value)
Set the coefficient of variable
in the constraint constraint
to value
.
Note that prior to this step, JuMP will aggregate multiple terms containing the same variable. For example, given a constraint 2x + 3x <= 2
, set_normalized_coefficient(con, x, 4)
will create the constraint 4x <= 2
.
model = Model()
@variable(model, x)
@constraint(model, con, 2x + 3x <= 2)
set_normalized_coefficient(con, x, 4)
con
# output
con : 4 x <= 2.0
JuMP.normalized_rhs
— Functionnormalized_rhs(con_ref::ConstraintRef)
Return the right-hand side term of con_ref
after JuMP has converted the constraint into its normalized form. See also set_normalized_rhs
.
JuMP.set_normalized_rhs
— Functionset_normalized_rhs(con_ref::ConstraintRef, value)
Set the right-hand side term of constraint
to value
.
Note that prior to this step, JuMP will aggregate all constant terms onto the right-hand side of the constraint. For example, given a constraint 2x + 1 <= 2
, set_normalized_rhs(con, 4)
will create the constraint 2x <= 4
, not 2x + 1 <= 4
.
julia> @constraint(model, con, 2x + 1 <= 2)
con : 2 x <= 1.0
julia> set_normalized_rhs(con, 4)
julia> con
con : 2 x <= 4.0
JuMP.add_to_function_constant
— Functionadd_to_function_constant(constraint::ConstraintRef, value)
Add value
to the function constant term.
Note that for scalar constraints, JuMP will aggregate all constant terms onto the right-hand side of the constraint so instead of modifying the function, the set will be translated by -value
. For example, given a constraint 2x <= 3
, add_to_function_constant(c, 4)
will modify it to 2x <= -1
.
Examples
For scalar constraints, the set is translated by -value
:
julia> @constraint(model, con, 0 <= 2x - 1 <= 2)
con : 2 x ∈ [1.0, 3.0]
julia> add_to_function_constant(con, 4)
julia> con
con : 2 x ∈ [-3.0, -1.0]
For vector constraints, the constant is added to the function:
julia> @constraint(model, con, [x + y, x, y] in SecondOrderCone())
con : [x + y, x, y] ∈ MathOptInterface.SecondOrderCone(3)
julia> add_to_function_constant(con, [1, 2, 2])
julia> con
con : [x + y + 1, x + 2, y + 2] ∈ MathOptInterface.SecondOrderCone(3)
JuMP.is_valid
— Functionis_valid(model::Model, con_ref::ConstraintRef{Model})
Return true
if constraint_ref
refers to a valid constraint in model
.
is_valid(model::Model, variable_ref::VariableRef)
Return true
if variable
refers to a valid variable in model
.
JuMP.delete
— Functiondelete(model::Model, con_ref::ConstraintRef)
Delete the constraint associated with constraint_ref
from the model model
.
See also: unregister
delete(model::Model, con_refs::Vector{<:ConstraintRef})
Delete the constraints associated with con_refs
from the model model
. Solvers may implement specialized methods for deleting multiple constraints of the same concrete type, i.e., when isconcretetype(eltype(con_refs))
. These may be more efficient than repeatedly calling the single constraint delete method.
See also: unregister
delete(model::Model, variable_ref::VariableRef)
Delete the variable associated with variable_ref
from the model model
.
See also: unregister
delete(model::Model, variable_refs::Vector{VariableRef})
Delete the variables associated with variable_refs
from the model model
. Solvers may implement methods for deleting multiple variables that are more efficient than repeatedly calling the single variable delete method.
See also: unregister
JuMP.list_of_constraint_types
— Functionlist_of_constraint_types(model::Model)::Vector{Tuple{DataType, DataType}}
Return a list of tuples of the form (F, S)
where F
is a JuMP function type and S
is an MOI set type such that all_constraints(model, F, S)
returns a nonempty list.
Example
julia> model = Model();
julia> @variable(model, x >= 0, Bin);
julia> @constraint(model, 2x <= 1);
julia> list_of_constraint_types(model)
3-element Array{Tuple{DataType,DataType},1}:
(GenericAffExpr{Float64,VariableRef}, MathOptInterface.LessThan{Float64})
(VariableRef, MathOptInterface.GreaterThan{Float64})
(VariableRef, MathOptInterface.ZeroOne)
JuMP.all_constraints
— Functionall_constraints(model::Model, function_type, set_type)::Vector{<:ConstraintRef}
Return a list of all constraints currently in the model where the function has type function_type
and the set has type set_type
. The constraints are ordered by creation time.
See also list_of_constraint_types
and num_constraints
.
Example
julia> model = Model();
julia> @variable(model, x >= 0, Bin);
julia> @constraint(model, 2x <= 1);
julia> all_constraints(model, VariableRef, MOI.GreaterThan{Float64})
1-element Array{ConstraintRef{Model,MathOptInterface.ConstraintIndex{MathOptInterface.SingleVariable,MathOptInterface.GreaterThan{Float64}},ScalarShape},1}:
x ≥ 0.0
julia> all_constraints(model, VariableRef, MOI.ZeroOne)
1-element Array{ConstraintRef{Model,MathOptInterface.ConstraintIndex{MathOptInterface.SingleVariable,MathOptInterface.ZeroOne},ScalarShape},1}:
x binary
julia> all_constraints(model, AffExpr, MOI.LessThan{Float64})
1-element Array{ConstraintRef{Model,MathOptInterface.ConstraintIndex{MathOptInterface.ScalarAffineFunction{Float64},MathOptInterface.LessThan{Float64}},ScalarShape},1}:
2 x ≤ 1.0
JuMP.num_constraints
— Functionnum_constraints(model::Model, function_type, set_type)::Int64
Return the number of constraints currently in the model where the function has type function_type
and the set has type set_type
.
See also list_of_constraint_types
and all_constraints
.
Example
julia> model = Model();
julia> @variable(model, x >= 0, Bin);
julia> @variable(model, y);
julia> @constraint(model, y in MOI.GreaterThan(1.0));
julia> @constraint(model, y <= 1.0);
julia> @constraint(model, 2x <= 1);
julia> num_constraints(model, VariableRef, MOI.GreaterThan{Float64})
2
julia> num_constraints(model, VariableRef, MOI.ZeroOne)
1
julia> num_constraints(model, AffExpr, MOI.LessThan{Float64})
2
JuMP.set_dual_start_value
— Functionset_dual_start_value(con_ref::ConstraintRef, value)
Set the dual start value (MOI attribute ConstraintDualStart
) of the constraint con_ref
to value
. To remove a dual start value set it to nothing
.
See also dual_start_value
.
JuMP.dual_start_value
— Functiondual_start_value(con_ref::ConstraintRef)
Return the dual start value (MOI attribute ConstraintDualStart
) of the constraint con_ref
.
Note: If no dual start value has been set, dual_start_value
will return nothing
.
See also set_dual_start_value
.
JuMP.ConstraintRef
— TypeConstraintRef
Holds a reference to the model and the corresponding MOI.ConstraintIndex.
JuMP.SecondOrderCone
— TypeSecondOrderCone
Second order cone object that can be used to constrain the euclidean norm of a vector x
to be less than or equal to a nonnegative scalar t
. This is a shortcut for the MOI.SecondOrderCone
.
Examples
The following constrains $\|(x-1, x-2)\|_2 \le t$ and $t \ge 0$:
julia> model = Model();
julia> @variable(model, x)
x
julia> @variable(model, t)
t
julia> @constraint(model, [t, x-1, x-2] in SecondOrderCone())
[t, x - 1, x - 2] ∈ MathOptInterface.SecondOrderCone(3)
JuMP.RotatedSecondOrderCone
— TypeRotatedSecondOrderCone
Rotated second order cone object that can be used to constrain the square of the euclidean norm of a vector x
to be less than or equal to $2tu$ where t
and u
are nonnegative scalars. This is a shortcut for the MOI.RotatedSecondOrderCone
.
Examples
The following constrains $\|(x-1, x-2)\|_2 \le 2tx$ and $t, x \ge 0$:
julia> model = Model();
julia> @variable(model, x)
x
julia> @variable(model, t)
t
julia> @constraint(model, [t, x, x-1, x-2] in RotatedSecondOrderCone())
[t, x, x - 1, x - 2] ∈ MathOptInterface.RotatedSecondOrderCone(4)
JuMP.PSDCone
— TypePSDCone
Positive semidefinite cone object that can be used to constrain a square matrix to be positive semidefinite in the @constraint
macro. If the matrix has type Symmetric
then the columns vectorization (the vector obtained by concatenating the columns) of its upper triangular part is constrained to belong to the MOI.PositiveSemidefiniteConeTriangle
set, otherwise its column vectorization is constrained to belong to the MOI.PositiveSemidefiniteConeSquare
set.
Examples
Consider the following example:
julia> model = Model();
julia> @variable(model, x)
x
julia> a = [ x 2x
2x x];
julia> b = [1 2
2 4];
julia> cref = @SDconstraint(model, a ⪰ b)
[x - 1 2 x - 2;
2 x - 2 x - 4 ] ∈ PSDCone()
julia> jump_function(constraint_object(cref))
4-element Array{GenericAffExpr{Float64,VariableRef},1}:
x - 1
2 x - 2
2 x - 2
x - 4
julia> moi_set(constraint_object(cref))
MathOptInterface.PositiveSemidefiniteConeSquare(2)
We see in the output of the last command that the matrix the vectorization of the matrix is constrained to belong to the PositiveSemidefiniteConeSquare
.
julia> using LinearAlgebra # For Symmetric
julia> cref = @constraint(model, Symmetric(a - b) in PSDCone())
[x - 1 2 x - 2;
2 x - 2 x - 4 ] ∈ PSDCone()
julia> jump_function(constraint_object(cref))
3-element Array{GenericAffExpr{Float64,VariableRef},1}:
x - 1
2 x - 2
x - 4
julia> moi_set(constraint_object(cref))
MathOptInterface.PositiveSemidefiniteConeTriangle(2)
As we see in the output of the last command, the vectorization of only the upper triangular part of the matrix is constrained to belong to the PositiveSemidefiniteConeSquare
.
JuMP.SOS1
— TypeSOS1
SOS1 (Special Ordered Sets type 1) object than can be used to constrain a vector x
to a set where at most 1 variable can take a non-zero value, all others being at 0. The weights
, when specified, induce an ordering of the variables; as such, they should be unique values. The kth element in the set corresponds to the kth weight in weights
. See here for a description of SOS constraints and their potential uses. This is a shortcut for the MathOptInterface.SOS1
set.
JuMP.SOS2
— TypeSOS2
SOS1 (Special Ordered Sets type 2) object than can be used to constrain a vector x
to a set where at most 2 variables can take a non-zero value, all others being at 0. In addition, if two are non-zero these must be consecutive in their ordering. The weights
induce an ordering of the variables; as such, they should be unique values. The kth element in the set corresponds to the kth weight in weights
. See here for a description of SOS constraints and their potential uses. This is a shortcut for the MathOptInterface.SOS2
set.
JuMP.SkewSymmetricMatrixSpace
— TypeSkewSymmetricMatrixSpace()
Use in the @variable
macro to constrain a matrix of variables to be skew-symmetric.
Examples
@variable(model, Q[1:2, 1:2] in SkewSymmetricMatrixSpace())
JuMP.SkewSymmetricMatrixShape
— TypeSkewSymmetricMatrixShape
Shape object for a skew symmetric square matrix of side_dimension
rows and columns. The vectorized form contains the entries of the upper-right triangular part of the matrix (without the diagonal) given column by column (or equivalently, the entries of the lower-left triangular part given row by row). The diagonal is zero.
JuMP.AbstractConstraint
— Typeabstract type AbstractConstraint
An abstract base type for all constraint types. AbstractConstraint
s store the function and set directly, unlike ConstraintRef
s that are merely references to constraints stored in a model. AbstractConstraint
s do not need to be attached to a model.
JuMP.ScalarConstraint
— Typestruct ScalarConstraint
The data for a scalar constraint. The func
field containts a JuMP object representing the function and the set
field contains the MOI set. See also the documentation on JuMP's representation of constraints for more background.
JuMP.VectorConstraint
— Typestruct VectorConstraint
The data for a vector constraint. The func
field containts a JuMP object representing the function and the set
field contains the MOI set. The shape
field contains an AbstractShape
matching the form in which the constraint was constructed (e.g., by using matrices or flat vectors). See also the documentation on JuMP's representation of constraints.
JuMP.index
— Methodindex(cr::ConstraintRef)::MOI.ConstraintIndex
Return the index of the constraint that corresponds to cr
in the MOI backend.
JuMP.optimizer_index
— Methodoptimizer_index(cr::ConstraintRef{Model})::MOI.ConstraintIndex
Return the index of the constraint that corresponds to cr
in the optimizer model. It throws NoOptimizer
if no optimizer is set and throws an ErrorException
if the optimizer is set but is not attached or if the constraint is bridged.
JuMP.constraint_object
— Functionconstraint_object(con_ref::ConstraintRef)
Return the underlying constraint data for the constraint referenced by ref
.
JuMP.moi_set
— Functionmoi_set(constraint::AbstractConstraint)
Return the set of the constraint constraint
in the function-in-set form as a MathOptInterface.AbstractSet
.
moi_set(s::AbstractVectorSet, dim::Int)
Returns the MOI set of dimension dim
corresponding to the JuMP set s
.
JuMP.function_string
— Functionfunction_string(print_mode::Type{<:JuMP.PrintMode},
func::Union{JuMP.AbstractJuMPScalar,
Vector{<:JuMP.AbstractJuMPScalar}})
Return a String
representing the function func
using print mode print_mode
.
JuMP.constraints_string
— Functionconstraints_string(print_mode, model::AbstractModel)::Vector{String}
Return a list of String
s describing each constraint of the model.
JuMP.in_set_string
— Functionin_set_string(print_mode::Type{<:JuMP.PrintMode},
set::Union{PSDCone, MOI.AbstractSet})
Return a String
representing the membership to the set set
using print mode print_mode
.
in_set_string(print_mode::Type{<:JuMP.PrintMode},
constraint::JuMP.AbstractConstraint)
Return a String
representing the membership to the set of the constraint constraint
using print mode print_mode
.
JuMP.show_constraints_summary
— Functionshow_constraints_summary(io::IO, model::AbstractModel)
Write to io
a summary of the number of constraints.
JuMP.ConstraintNotOwned
— Typestruct ConstraintNotOwned{C <: ConstraintRef} <: Exception
constraint_ref::C
end
The constraint constraint_ref
was used in a model different to owner_model(constraint_ref)
.