\section{Variable}

A variable is a numerical value that is determined during optimization.
Pyomo variables are managed with the \code{Var} class, which can denote
a single, independent value, or an array of values.  Variables define
the search space for optimization.  Variables can have initial values,
and the value of variable can be retrieved and set.


\subsection{Var Declarations}

A simple instance of \code{Var} declares a single variable:
\begin{lstlisting}
model.x = Var()
\end{lstlisting}
A variable array can also be specified by providing sets as options
to the \code{Var} object.  Multi-dimensional variable arrays can be declared by simply including a list of sets as options to the \code{Var} object:
\begin{lstlisting}
model.A = Set()
model.Y = Var(model.A)
model.B = Set()
model.X = Var(model.A, model.B)
\end{lstlisting}


\subsection{Variable Initialization}

By default, a \code{Var} object refers to one or more variables in a model.  Variable
values are typically determined during optimization.  However, variables can 
be initialized using the \code{initialize} option.
This option can specify a numerical value used to 
initialize a variable or variable array:
\begin{lstlisting}
model.x = Var(initialize=9)
model.x = Var(model.A,initialize={1:1, 2:4, 3:9})
model.x = Var(model.A,initialize=2)
\end{lstlisting}
Additionally, this option can use a function 
that accepts the variable indices and model and returns the value of that variable element:
\begin{lstlisting}
def f(i,model):
    return 3*i
model.x = Var(model.A,initialize=f)
\end{lstlisting}


\subsection{Variable Domain}

The domain of a variable is specified with the \code{within} option:
\begin{lstlisting}
model.x = Var(within=model.A)
\end{lstlisting}
This domain is used in various aspects of model construction.  For example, binary variables define zero-one constraints in integer programs, as well as upper and lower bounds for linear programming relaxations.  


\subsection{Variable Options}

Variable bounds can be explicitly specified
with the \code{bounds} option:
\begin{lstlisting}
model.x = Var(bounds=(0.0,1.0))
def f(i,model):
  return (model.A[i], model.B[i])
model.y = Var(model.I, bounds=f)
\end{lstlisting}
The \code{bounds} option can specify a 2-tuple with lower and upper values.  Alternatively,
it can specify a function that returns a 2-tuple for each variable index.  Note that \code{None} can be used to specify that a bound is not enforced.

% Provide an example where the bounds tuple include an expression.

\subsection{Working With Variables}

Variable objects have a variety of helper functions and utility methods that facilitate 
the use of these objects.  The \code{float} function can be used to coerce a \code{Var} object into a floating point value:
\begin{lstlisting}
tmp = float(model.x)
tmp = float(model.x[i])
\end{lstlisting}
Similarly, the \code{value} function can be used to coerce a \code{Var} object
into its natural numerical value:
\begin{lstlisting}
tmp = value(model.x)
tmp = value(model.x[i])
\end{lstlisting}
Variable values can be set using the equality operator:
\begin{lstlisting}
model.x = tmp
model.x[i] = tmp
\end{lstlisting}
Finally, the \code{len} function returns the number of variables in a variable array.
\begin{lstlisting}
len(model.x)
\end{lstlisting}


\subsection{Class Attributes}

Methods
\begin{itemize}

\item \code{dim}\\
    Returns the number of dimensions of the variable index

\item \code{keys}\\
    Returns the indices of the variable array

\item \code{reset}\\
    Set the variable with the initial value.  When a variable is constructed, its value is \code{None}

\end{itemize}

Options
\begin{itemize}

\item \code{value}\\
    The value of the variable.

\item \code{initial}\\
    The initial value of the variable.

\item \code{lb}\\
    The value of the variable lower bound.

\item \code{ub}\\
    The value of the variable upper bound.

\item \code{fixed}\\
    A boolean value that indicates whether this variable is fixed during optimization.

\end{itemize}

