# Variables

More information can be found in the Variables section of the manual.

## Macros

JuMP.@variableMacro
@variable(model, expr, args..., kw_args...)

Add a variable to the model model described by the expression expr, the positional arguments args and the keyword arguments kw_args.

Anonymous and named variables

expr must be one of the forms:

• Omitted, like @variable(model), which creates an anonymous variable
• A single symbol like @variable(model, x)
• A container expression like @variable(model, x[i=1:3])
• An anoymous container expression like @variable(model, [i=1:3])

Bounds

In addition, the expression can have bounds, such as:

• @variable(model, x >= 0)
• @variable(model, x <= 0)
• @variable(model, x == 0)
• @variable(model, 0 <= x <= 1)

and bounds can depend on the indices of the container expressions:

• @variable(model, -i <= x[i=1:3] <= i)

Sets

You can explicitly specify the set to which the variable belongs:

• @variable(model, x in MOI.Interval(0.0, 1.0))

For more information on this syntax, read Variables constrained on creation.

Positional arguments

The recognized positional arguments in args are the following:

• Bin: restricts the variable to the MOI.ZeroOne set, that is, {0, 1}. For example, @variable(model, x, Bin). Note: you cannot use @variable(model, Bin), use the binary keyword instead.
• Int: restricts the variable to the set of integers, that is, ..., -2, -1, 0, 1, 2, ... For example, @variable(model, x, Int). Note: you cannot use @variable(model, Int), use the integer keyword instead.
• Symmetric: Only available when creating a square matrix of variables, i.e., when expr is of the form varname[1:n,1:n] or varname[i=1:n,j=1:n], it creates a symmetric matrix of variables.
• PSD: A restrictive extension to Symmetric which constraints a square matrix of variables to Symmetric and constrains to be positive semidefinite.

Keyword arguments

Four keyword arguments are useful in all cases:

• base_name: Sets the name prefix used to generate variable names. It corresponds to the variable name for scalar variable, otherwise, the variable names are set to base_name[...] for each index ... of the axes axes.
• start::Float64: specify the value passed to set_start_value for each variable
• container: specify the container type. See Forcing the container type for more information.
• set_string_name::Bool = true: control whether to set the MOI.VariableName attribute. Passing set_string_name = false can improve performance.

Other keyword arguments are needed to disambiguate sitations with anonymous variables:

• lower_bound::Float64: an alternative to x >= lb, sets the value of the variable lower bound.
• upper_bound::Float64: an alternative to x <= ub, sets the value of the variable upper bound.
• binary::Bool: an alternative to passing Bin, sets whether the variable is binary or not.
• integer::Bool: an alternative to passing Int, sets whether the variable is integer or not.
• set::MOI.AbstractSet: an alternative to using x in set
• variable_type: used by JuMP extensions. See Extend @variable for more information.

Examples

The following are equivalent ways of creating a variable x of name x with lower bound 0:

model = Model()
@variable(model, x >= 0)
@variable(model, x, lower_bound = 0)
x = @variable(model, base_name = "x", lower_bound = 0)

Other examples:

model = Model()
@variable(model, x[i=1:3] <= i, Int, start = sqrt(i), lower_bound = -i)
@variable(model, y[i=1:3], container = DenseAxisArray, set = MOI.ZeroOne())
@variable(model, z[i=1:3], set_string_name = false)
source
JuMP.@variablesMacro
@variables(model, args...)

Adds multiple variables to model at once, in the same fashion as the @variable macro.

The model must be the first argument, and multiple variables can be added on multiple lines wrapped in a begin ... end block.

The macro returns a tuple containing the variables that were defined.

Examples

@variables(model, begin
x
y[i = 1:2] >= 0, (start = i)
z, Bin, (start = 0, base_name = "Z")
end)
Note

Keyword arguments must be contained within parentheses (refer to the example above).

source

## Basic utilities

JuMP.all_variablesFunction
all_variables(model::Model)::Vector{VariableRef}

Returns a list of all variables currently in the model. The variables are ordered by creation time.

Example

model = Model()
@variable(model, x)
@variable(model, y)
all_variables(model)

# output

2-element Array{VariableRef,1}:
x
y
source
JuMP.indexMethod
index(v::VariableRef)::MOI.VariableIndex

Return the index of the variable that corresponds to v in the MOI backend.

source
JuMP.optimizer_indexMethod
optimizer_index(x::VariableRef)::MOI.VariableIndex
optimizer_index(x::ConstraintRef{Model})::MOI.ConstraintIndex

Return the index that corresponds to x in the optimizer model.

Throws NoOptimizer if no optimizer is set, and throws an ErrorException if the optimizer is set but is not attached.

source
JuMP.check_belongs_to_modelFunction
check_belongs_to_model(func::AbstractJuMPScalar, model::AbstractModel)

Throw VariableNotOwned if the owner_model of one of the variables of the function func is not model.

check_belongs_to_model(constraint::AbstractConstraint, model::AbstractModel)

Throw VariableNotOwned if the owner_model of one of the variables of the constraint constraint is not model.

source
JuMP.VariableNotOwnedType
struct VariableNotOwned{V <: AbstractVariableRef} <: Exception
variable::V
end

The variable variable was used in a model different to owner_model(variable).

source
JuMP.VariableConstrainedOnCreationType
VariablesConstrainedOnCreation <: AbstractVariable

Variable scalar_variables constrained to belong to set. Adding this variable can be understood as doing:

function JuMP.add_variable(
model::Model,
variable::VariableConstrainedOnCreation,
names,
)
var_ref = add_variable(model, variable.scalar_variable, name)
add_constraint(model, VectorConstraint(var_ref, variable.set))
return var_ref
end

but adds the variables with MOI.add_constrained_variable(model, variable.set) instead. See the MOI documentation for the difference between adding the variables with MOI.add_constrained_variable and adding them with MOI.add_variable and adding the constraint separately.

source
JuMP.VariablesConstrainedOnCreationType
VariablesConstrainedOnCreation <: AbstractVariable

Vector of variables scalar_variables constrained to belong to set. Adding this variable can be thought as doing:

function JuMP.add_variable(
model::Model,
variable::VariablesConstrainedOnCreation,
names,
)
v_names = vectorize(names, variable.shape)
var_refs = add_variable.(model, variable.scalar_variables, v_names)
add_constraint(model, VectorConstraint(var_refs, variable.set))
return reshape_vector(var_refs, variable.shape)
end

but adds the variables with MOI.add_constrained_variables(model, variable.set) instead. See the MOI documentation for the difference between adding the variables with MOI.add_constrained_variables and adding them with MOI.add_variables and adding the constraint separately.

source
JuMP.ComplexPlaneType
ComplexPlane

Complex plane object that can be used to create a complex variable in the @variable macro.

Examples

Consider the following example:

julia> model = Model();

julia> @variable(model, x in ComplexPlane())
real(x) + (0.0 + 1.0im) imag(x)

julia> all_variables(model)
2-element Vector{VariableRef}:
real(x)
imag(x)

We see in the output of the last command that two real variables were created. The Julia variable x binds to an affine expression in terms of these two variables that parametrize the complex plane.

source

## Names

JuMP.variable_by_nameFunction
variable_by_name(model::AbstractModel,
name::String)::Union{AbstractVariableRef, Nothing}

Returns the reference of the variable with name attribute name or Nothing if no variable has this name attribute. Throws an error if several variables have name as their name attribute.

julia> model = Model();

julia> @variable(model, x)
x

julia> variable_by_name(model, "x")
x

julia> @variable(model, base_name="x")
x

julia> variable_by_name(model, "x")
ERROR: Multiple variables have the name x.
Stacktrace:
[1] error(::String) at ./error.jl:33
[2] get(::MOIU.Model{Float64}, ::Type{MathOptInterface.VariableIndex}, ::String) at /home/blegat/.julia/dev/MathOptInterface/src/Utilities/model.jl:222
[3] get at /home/blegat/.julia/dev/MathOptInterface/src/Utilities/universalfallback.jl:201 [inlined]
[4] get(::MathOptInterface.Utilities.CachingOptimizer{MathOptInterface.AbstractOptimizer,MathOptInterface.Utilities.UniversalFallback{MOIU.Model{Float64}}}, ::Type{MathOptInterface.VariableIndex}, ::String) at /home/blegat/.julia/dev/MathOptInterface/src/Utilities/cachingoptimizer.jl:490
[5] variable_by_name(::Model, ::String) at /home/blegat/.julia/dev/JuMP/src/variables.jl:268
[6] top-level scope at none:0

julia> var = @variable(model, base_name="y")
y

julia> variable_by_name(model, "y")
y

julia> set_name(var, "z")

julia> variable_by_name(model, "y")

julia> variable_by_name(model, "z")
z

julia> @variable(model, u[1:2])
2-element Array{VariableRef,1}:
u[1]
u[2]

julia> variable_by_name(model, "u[2]")
u[2]
source

## Start values

JuMP.set_start_valueFunction
set_start_value(con_ref::ConstraintRef, value)

Set the primal start value (MOI.ConstraintPrimalStart) of the constraint con_ref to value. To remove a primal start value set it to nothing.

See also start_value.

source
set_start_value(variable::VariableRef, value::Union{Real,Nothing})

Set the start value (MOI attribute VariablePrimalStart) of the variable to value.

Pass nothing to unset the start value.

Note: VariablePrimalStarts are sometimes called "MIP-starts" or "warmstarts".

See also start_value.

source
JuMP.start_valueFunction
start_value(con_ref::ConstraintRef)

Return the primal start value (MOI.ConstraintPrimalStart) of the constraint con_ref.

Note: If no primal start value has been set, start_value will return nothing.

See also set_start_value.

source
start_value(v::VariableRef)

Return the start value (MOI attribute VariablePrimalStart) of the variable v.

Note: VariablePrimalStarts are sometimes called "MIP-starts" or "warmstarts".

See also set_start_value.

source

## Lower bounds

JuMP.set_lower_boundFunction
set_lower_bound(v::VariableRef, lower::Number)

Set the lower bound of a variable. If one does not exist, create a new lower bound constraint.

source
JuMP.LowerBoundRefFunction
LowerBoundRef(v::VariableRef)

Return a constraint reference to the lower bound constraint of v. Errors if one does not exist.

source

## Upper bounds

JuMP.set_upper_boundFunction
set_upper_bound(v::VariableRef, upper::Number)

Set the upper bound of a variable. If one does not exist, create an upper bound constraint.

source
JuMP.UpperBoundRefFunction
UpperBoundRef(v::VariableRef)

Return a constraint reference to the upper bound constraint of v. Errors if one does not exist.

source

## Fixed bounds

JuMP.fix_valueFunction
fix_value(v::VariableRef)

Return the value to which a variable is fixed. Error if one does not exist.

source
JuMP.fixFunction
fix(v::VariableRef, value::Number; force::Bool = false)

Fix a variable to a value. Update the fixing constraint if one exists, otherwise create a new one.

If the variable already has variable bounds and force=false, calling fix will throw an error. If force=true, existing variable bounds will be deleted, and the fixing constraint will be added. Note a variable will have no bounds after a call to unfix.

source
JuMP.FixRefFunction
FixRef(v::VariableRef)

Return a constraint reference to the constraint fixing the value of v. Errors if one does not exist.

source

## Integer variables

JuMP.is_integerFunction
is_integer(v::VariableRef)

Return true if v is constrained to be integer.

source
JuMP.set_integerFunction
set_integer(variable_ref::VariableRef)

Add an integrality constraint on the variable variable_ref.

source
JuMP.unset_integerFunction
unset_integer(variable_ref::VariableRef)

Remove the integrality constraint on the variable variable_ref.

source
JuMP.IntegerRefFunction
IntegerRef(v::VariableRef)

Return a constraint reference to the constraint constraining v to be integer. Errors if one does not exist.

source

## Binary variables

JuMP.is_binaryFunction
is_binary(v::VariableRef)

Return true if v is constrained to be binary.

source
JuMP.set_binaryFunction
set_binary(v::VariableRef)

Add a constraint on the variable v that it must take values in the set $\{0,1\}$.

source
JuMP.unset_binaryFunction
unset_binary(variable_ref::VariableRef)

Remove the binary constraint on the variable variable_ref.

source
JuMP.BinaryRefFunction
BinaryRef(v::VariableRef)

Return a constraint reference to the constraint constraining v to be binary. Errors if one does not exist.

source

## Integrality utilities

JuMP.relax_integralityFunction
relax_integrality(model::Model)

Modifies model to "relax" all binary and integrality constraints on variables. Specifically,

• Binary constraints are deleted, and variable bounds are tightened if necessary to ensure the variable is constrained to the interval $[0, 1]$.
• Integrality constraints are deleted without modifying variable bounds.
• An error is thrown if semi-continuous or semi-integer constraints are present (support may be added for these in the future).
• All other constraints are ignored (left in place). This includes discrete constraints like SOS and indicator constraints.

Returns a function that can be called without any arguments to restore the original model. The behavior of this function is undefined if additional changes are made to the affected variables in the meantime.

Example

julia> model = Model();

julia> @variable(model, x, Bin);

julia> @variable(model, 1 <= y <= 10, Int);

julia> @objective(model, Min, x + y);

julia> undo_relax = relax_integrality(model);

julia> print(model)
Min x + y
Subject to
x ≥ 0.0
y ≥ 1.0
x ≤ 1.0
y ≤ 10.0

julia> undo_relax()

julia> print(model)
Min x + y
Subject to
y ≥ 1.0
y ≤ 10.0
y integer
x binary
source
JuMP.fix_discrete_variablesFunction
fix_discrete_variables([var_value::Function = value,] model::Model)

Modifies model to convert all binary and integer variables to continuous variables with fixed bounds of var_value(x).

Return

Returns a function that can be called without any arguments to restore the original model. The behavior of this function is undefined if additional changes are made to the affected variables in the meantime.

Notes

• An error is thrown if semi-continuous or semi-integer constraints are present (support may be added for these in the future).
• All other constraints are ignored (left in place). This includes discrete constraints like SOS and indicator constraints.

Example

julia> model = Model();

julia> @variable(model, x, Bin, start = 1);

julia> @variable(model, 1 <= y <= 10, Int, start = 2);

julia> @objective(model, Min, x + y);

julia> undo_relax = fix_discrete_variables(start_value, model);

julia> print(model)
Min x + y
Subject to
x = 1.0
y = 2.0

julia> undo_relax()

julia> print(model)
Min x + y
Subject to
y ≥ 1.0
y ≤ 10.0
y integer
x binary
source

## Extensions

JuMP.AbstractVariableRefType
AbstractVariableRef

Variable returned by add_variable. Affine (resp. quadratic) operations with variables of type V<:AbstractVariableRef and coefficients of type T create a GenericAffExpr{T,V} (resp. GenericQuadExpr{T,V}).

source
JuMP.parse_one_operator_variableFunction
parse_one_operator_variable(_error::Function, infoexpr::_VariableInfoExpr, sense::Val{S}, value) where S

Update infoexr for a variable expression in the @variable macro of the form variable name S value.

source