Variables

What is a JuMP variable?

The term variable in mathematical optimization has many meanings. Here, we distinguish between the following three types of variables:

optimization variables, which are the mathematical $x$ in the problem $\max\{f_0(x) | f_i(x) \in S_i\}$.
Julia variables, which are bindings between a name and a value, for example x = 1. (See here for the Julia docs.)
JuMP variables, which are instances of the VariableRef struct defined by JuMP that contains a reference to an optimization variable in a model. (Extra for experts: the VariableRef struct is a thin wrapper around a MOI.VariableIndex, and also contains a reference to the JuMP model.)

To illustrate these three types of variables, consider the following JuMP code (the full syntax is explained below):

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[1:2])
2-element Array{VariableRef,1}:
 x[1]
 x[2]

This code does three things:

It adds two optimization variables to model.
It creates two JuMP variables that act as references to those optimization variables.
It binds those JuMP variables as a vector with two elements to the Julia variable x.

To reduce confusion, we will attempt, where possible, to always refer to variables with their corresponding prefix.

JuMP variables can have attributes, such as names or an initial primal start value. We illustrate the name attribute in the following example:

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

This code does four things:

It adds one optimization variable to model.
It creates one JuMP variable that acts as a reference to that optimization variable.
It binds the JuMP variable to the Julia variable y.
It tells JuMP that the name attribute of this JuMP variable is "decision variable". JuMP uses the value of base_name when it has to print the variable as a string.

For example, when we print y at the REPL we get:

julia> y
decision variable

Because y is a Julia variable, we can bind it to a different value. For example, if we write:

julia> y = 1
1

y is no longer a binding to a JuMP variable. This does not mean that the JuMP variable has been destroyed. It still exists and is still a reference to the same optimization variable. The binding can be reset by querying the model for the symbol as it was written in the @variable macro. For example:

julia> model[:y]
decision variable

This act of looking up the JuMP variable by using the symbol is most useful when composing JuMP models across multiple functions, as illustrated by the following example:

function add_component_to_model(model::JuMP.Model)
    x = model[:x]
    # ... code that uses x
end
function build_model()
    model = Model()
    @variable(model, x)
    add_component_to_model(model)
end

Now that we understand the difference between optimization, JuMP, and Julia variables, we can introduce more of the functionality of the @variable macro.

Variable bounds

We have already seen the basic usage of the @variable macro. The next extension is to add lower- and upper-bounds to each optimization variable. This can be done as follows:

julia> @variable(model, x_free)
x_free

julia> @variable(model, x_lower >= 0)
x_lower

julia> @variable(model, x_upper <= 1)
x_upper

julia> @variable(model, 2 <= x_interval <= 3)
x_interval

julia> @variable(model, x_fixed == 4)
x_fixed

In the above examples, x_free represents an unbounded optimization variable, x_lower represents an optimization variable with a lower bound and so forth.

Note

When creating a variable with only a lower-bound or an upper-bound, and the value of the bound is not a numeric literal, the name of the variable must appear on the left-hand side. Putting the name on the right-hand side will result in an error. For example:

@variable(model, 1 <= x)  # works
a = 1
@variable(model, a <= x)  # errors
@variable(model, x >= a)  # works

We can query whether an optimization variable has a lower- or upper-bound via the has_lower_bound and has_upper_bound functions. For example:

julia> has_lower_bound(x_free)
false

julia> has_upper_bound(x_upper)
true

If a variable has a lower or upper bound, we can query the value of it via the lower_bound and upper_bound functions. For example:

julia> lower_bound(x_interval)
2.0

julia> upper_bound(x_interval)
3.0

Querying the value of a bound that does not exist will result in an error.

Instead of using the <= and >= syntax, we can also use the lower_bound and upper_bound keyword arguments. For example:

julia> @variable(model, x, lower_bound=1, upper_bound=2)
x

julia> lower_bound(x)
1.0

Another option is to use the set_lower_bound and set_upper_bound functions. These can also be used to modify an existing variable bound. For example:

julia> @variable(model, x >= 1)
x

julia> lower_bound(x)
1.0

julia> set_lower_bound(x, 2)

julia> lower_bound(x)
2.0

We can delete variable bounds using delete_lower_bound and delete_upper_bound:

julia> @variable(model, 1 <= x <= 2)
x

julia> lower_bound(x)
1.0

julia> delete_lower_bound(x)

julia> has_lower_bound(x)
false

julia> upper_bound(x)
2.0

julia> delete_upper_bound(x)

julia> has_upper_bound(x)
false

In addition to upper and lower bounds, JuMP variables can also be fixed to a value using fix. See also is_fixed, fix_value, and unfix.

julia> @variable(model, x == 1)
x

julia> is_fixed(x)
true

julia> fix_value(x)
1.0

julia> unfix(x)

julia> is_fixed(x)
false

Fixing a variable with existing bounds will throw an error. To delete the bounds prior to fixing, use fix(variable, value; force = true).

julia> @variable(model, x >= 1)
x

julia> fix(x, 2)
ERROR: Unable to fix x to 2 because it has existing variable bounds. Consider calling `JuMP.fix(variable, value; force=true)` which will delete existing bounds before fixing the variable.

julia> fix(x, 2; force = true)


julia> fix_value(x)
2.0

Variable names

The name, i.e. the value of the MOI.VariableName attribute, of a variable can be obtained by JuMP.name(::JuMP.VariableRef) and set by JuMP.set_name(::JuMP.VariableRef, ::String).

JuMP.name — Method.

name(v::VariableRef)::String

Get a variable's name attribute.