Variable Declaration and Attributes

Declaration and attributes

Variables have some additional attributes above those of parameters. These extra attributes are used to steer a solver, or to hold additional information about solution values provided by the solver. The possible attributes of variables are given in this table.

Attribute	Value-type	See also page
IndexDomain	index-domain	The IndexDomain attribute
Range	range	The Range attribute
Default	constant-expression	The Default attribute
Unit	unit-expression	The Parameter Unit attribute, Units of Measurement
Priority	expression
NonvarStatus	expression
RelaxStatus	expression
Property	NoSave, numeric-storage-property, Inline	The Set Property attribute, The Parameter Property attribute
	SemiContinuous, Basic, Stochastic, Adjustable
	ReducedCost, ValueRange, CoefficientRange,
	constraint-related-sensitivity-property
Text	string	The Text and Comment attributes
Comment	comment string	The Text and Comment attributes
Definition	expression	The Set Definition attribute, The Parameter Definition attribute
Stage	expression	Uncertainty Related Properties and Attributes, Stochastic Parameters and Variables
Dependency	expression	Uncertainty Related Properties and Attributes, The Robust Dependency attribute

Index domain for variables

By specifying the IndexDomain attribute you can restrict the domain of a variable in the same way as that of a parameter. For variables, however, the domain restriction has an additional effect. During the generation of individual constraints AIMMS will reduce the size of the generated mathematical program by including only those variables that satisfy all domain restrictions.

The Range attribute

The values of the Range attribute of variables determine the bounds that are passed on to the solver. In addition, during an assignment, the Range attribute restricts the range of allowed values that can be assigned to a particular interval (as for parameters). The possible values for the Range attribute are:

• one of the predefined ranges Real, Nonnegative, Nonpositive, Integer or Binary,

• any one of the interval expressions [\(a,b\)], [\(a,b\)), (\(a,b\)] or (\(a,b\)), where \(a\) and \(b\) can be a constant number, inf, -inf, or a parameter reference involving some or all of the indices on the index list of the declared variable,

• any enumerated integer set expression, e.g. {\(a\) .. \(b\)} with \(a\) and \(b\) as above, or

• an integer set identifier.

If you specify Real, Nonnegative, Nonpositive, or an interval expression, AIMMS will interpret the variable as a continuous variable. If you specify Integer, Binary or an integer set expression, AIMMS will interpret the variable as a binary or integer variable.

Example

The following example illustrates a simple variable declaration.

Variable Transport {
    IndexDomain  : (i,j) in Connections;
    Range        : [ MinTransport(i), Capacity(i,j) ];
}

The declaration of the variable Transport(i,j) sets its lower bound equal to MinTransport(i) and its upper bound to Capacity(i,j). When generating the mathematical program, the variable Transport will only be generated for those tuples (i,j) that lie in the set Connections. Note that the specification of the lower bound only uses a subdomain (i) of the full index domain of the variable (i,j).

The .Lower and .Upper suffices

Besides using the Range attribute to specify the lower and upper bounds, you can also use the .Lower and .Upper suffices in assignment statements to accomplish this task. The .Lower and .Upper suffices are attached to the name of the variable, and, as a result, the corresponding bounds are defined for the entire index domain. This may lead to increased memory usage when variables share their bounds for slices of the domain. For this reason, you are advised to use the Range attribute as much as possible when specifying the lower and upper bounds.

When allowed

You can only make a bound assignment with either the .Lower or .Upper suffix when you have not used a parameter reference (or a non-constant expression) at the corresponding position in the Range attribute. Bound assignments via the .Lower and .Upper suffices must always lie within the range specified in the Range attribute.

Example

Consider the variable Transport declared in the previous example. The following assignment to Transport.Lower(i,j) is not allowed, because you have already specified a parameter reference at the corresponding position in the Range attribute.

Transport.Lower(i,j) := MinTransport(i) ;

On the other hand, given the following declaration,

Variable Shipment {
    IndexDomain  : (i,j) in Connections;
    Range        : Nonnegative;
}

the following assignment is allowed:

Shipment.Lower(i,j) := MinTransport(i);

AIMMS will produce a run-time error message if any value of MinTransport(i) is less than zero, because this violates the bound in the Range attribute of the variable Shipment.

The Default attribute

Variables that have not been initialized, evaluate to a default value automatically. These default values are also passed as initial values to the solver. You can specify the default value using the Default attribute. The value of this attribute must be a constant expression. If you do not provide a default value, AIMMS will use a default of 0.

The Unit attribute

Providing a unit for every variable and constraint in your model will help you in a number of ways.

• AIMMS will help you to check the consistency of all your constraints and assignments in your model, and

• AIMMS will use the units to scale the model that is sent to the solver.

Proper scaling of a model will generally result in a more accurate and robust solution process. You can find more information on the definition and use of units to scale mathematical programs in Units of Measurement.

The Definition attribute

It is not unusual that symbolic constraints in a model are equalities defining just one variable in terms of others. Under these conditions, it is preferable to provide the definition of the variable through its Definition attribute. As a result, you no longer need to specify extra constraints for just variable definitions. In the constraint listing, the constraints associated with a defined variable will be listed with a generated name consisting of the name of the variable with an additional suffix _definition.

Example

The following example defines the total cost of transport, based on unit transport cost and actual transport taking place.

Variable TransportCost {
    Definition : sum( (i,j), UnitTransportCost(i,j)*Transport(i,j) );
}

The Priority, Nonvar and RelaxStatus Attributes

The Priority attribute

With the Priority attribute you can assign priorities to integer variables (or continuous variables when using the solver BARON). The value of this attribute must be an expression using some or all of the indices in the index domain of the variable, and must be nonnegative and integer. All variables with priority zero will be considered last by the branch-and-bound process of the solver. For variables with a positive priority value, those with the highest priority value will be considered first.

The .Priority suffix

Alternatively, you can specify priorities through assignments to the .Priority suffix. This is only allowed if you have not specified the Priority attribute. In both cases, you can use the .Priority suffix to refer to the priority of a variable in expressions.

Use of priorities

The solution algorithm (i.e. solver) for integer and mixed-integer programs initially solves without the integer restriction, and then adds this restriction one variable at a time according to their priority. By default, all integer variables have equal priority. Some decisions, however, have a natural order in time or space. For example, the decision to build a factory at some site comes before the decision to purchase production capacity for that factory. Obeying this order naturally limits the number of subsequent choices, and could speed up the overall search by the solution algorithm.

The NonvarStatus attribute

You can use the NonvarStatus attribute to tell AIMMS which variables should be considered as parameters during the execution of a SOLVE statement. The value of the NonvarStatus attribute must be an expression in some or all of the indices in the index list of the variable, allowing you to change the nonvariable status of individual elements or groups of elements at once.

Positive versus negative values

The sign of the NonvarStatus value determines whether and how the variable is passed on to the solver. The following rules apply.

• If the value is 0 (the default value), the corresponding individual variable is generated, along with its specified lower and upper bounds.

• If the value is negative, the corresponding individual variable is still generated, but its lower and upper bounds are set equal to the current value of the variable.

• If the value is positive, the corresponding individual variable is no longer generated but passed as a constant to the solver.

When you specify a negative value, you will still be able to inspect the corresponding reduced cost values. In addition, you can modify the nonvariable status to zero without causing AIMMS to regenerate the model. When you specify a positive value, the size of the mathematical program is kept to a minimum, but any subsequent changes to the nonvariable status will require regeneration of the model constraints.

The .NonVar suffix

Alternatively, you can change the nonvariable status through assignments to the .NonVar suffix. This is only allowed if you have not specified the NonvarStatus attribute. In both cases, you can use the .NonVar suffix to refer to the variable status of a variable in expressions.

When to change the nonvariable status

By altering the nonvariable status of variables you are essentially reconfiguring your mathematical program. You could, for instance, reverse the role of an input parameter (declared as a variable with negative nonvariable status) and an output variable in your model to observe what input level is required to obtain a desired output level. Another example of temporary reconfiguration is to solve a smaller version of a mathematical program by first discarding selected variables, and then changing their status back to solve the larger mathematical program using the previous solution as a starting point.

The RelaxStatus attribute

With the RelaxStatus attribute you can tell AIMMS to relax the integer restriction for those tuples in the domain of an integer variable for which the value of the relax status is nonzero. AIMMS will generate continuous variables for such tuples instead, i.e. variables which may assume any real value between their bounds.

The .Relax suffix

Alternatively, you can relax integer variables by making assignments to the .Relax suffix. This is only allowed if you have not specified the RelaxStatus attribute. In both cases, you can use the .Relax suffix to refer to the relax status of a variable in expressions.

When to relax variables

When solving large mixed integer programs, the solution times may become unacceptably high with an increase in the number of integer variables. You can try to resolve this by relaxing the integer condition of some of the integer variables. For instance, in a multi-period planning model, an accurate integer solution for the first few periods and an approximating continuous solution for the remaining periods may very well be acceptable, and at the same time reduce solution times drastically.

Effect on mathematical program type

As you will see in Solving Mathematical Programs, there are several types of mathematical programs. By changing the nonvariable and/or relax status of variables you may alter the type of your mathematical program. For instance, if your constraints contains a nonlinear term x*y, then changing the nonvariable status of either x or y will change it into a linear term. Eventually, this may result in a nonlinear mathematical program becoming a linear one. Similarly, changing the nonvariable or relax status of integer variables may at some point change a mixed integer program into a linear program.

Variable Properties

Properties of variables

Variables can have one or more of the following properties: NoSave, Inline, SemiContinuous, ReducedCost, CoefficientRange, ValueRange, Stochastic, and Adjustable. They are described in the paragraphs below.

Use of PROPERTY statement

You can also change the properties of a variable during the execution of your model by calling the PROPERTY statement. Identifier properties are changed by adding the property name as a suffix to the identifier name in a PROPERTY statement. When the value is set to off, the property no longer holds.

The NoSave property

With the property NoSave you indicate that you do not want to store data associated with this variable in a case. This property is especially suited for those identifiers that are intermediate quantities in the model, and that are not used anywhere in the graphical end-user interface.

Inline variables

With the property Inline you can indicate that AIMMS should substitute all references to the variable at hand by its defining expression when generating the constraints of a mathematical program. Setting this property only makes sense for defined variables, and will result in a mathematical program with less rows and columns but with a (possibly) larger number of nonzeros. After the mathematical program has been solved, AIMMS will compute the level values of all inline variables by evaluating their definition. However, no sensitivity information will be available.

If bounds have been specified for an inline variable then these bounds will be ignored when the mathematical program is solved. To enforce the bounds, they should be specified in a constraint (after which the variable can be changed into a free variable).

If the nonvariable status of an inline variable has been set to a nondefault value, either using the NonvarStatus attribute or the .NonVar suffix, then this status will be ignored when the mathematical program is solved. Fixing an inline variable to the current value of the variable should be done using a constraint.

Semi-continuous variables

To any continuous or integer variable you can assign the property SemiContinuous. This indicates to the solver that this variable is either zero, or lies within its specified range. Not all solvers support semi-continuous variables. In the latter case, AIMMS will automatically add the necessary constraints to the model.

Sensitivity Related Properties

Basic, superbasic, and nonbasic variables

With the Basic property you can instruct AIMMS to retrieve basic information of a specific variable from the solver. If retrieved, basic information can be accessed through the .Basic suffix. The basic information is presented as an element in the predefined AIMMS set AllBasicValues (i.e. {Basic, Nonbasic, Superbasic}). In linear programming a variable will either be basic or nonbasic, while in nonlinear programming the number of variables with zero reduced cost can be larger than the number of constraints. The solution algorithm then divides these variables into so-called basics and superbasics. The basic variables define a square system of nonlinear equations which is solved for fixed values of the remaining variables. The superbasics are assigned a fixed value between their bounds, while the nonbasics take their value at a bound.

The ReducedCost property

You can use the ReducedCost property to specify whether you are interested in the reduced cost values of the variable after each SOLVE step. Storing the reduced costs of all variables may be very memory consuming, therefore, the default in AIMMS is not to store these values. If reduced costs are requested, the stored values can be accessed through the suffices .ReducedCost or .m.

Interpretation of reduced cost

The reduced cost indicates by how much the cost coefficient in the objective function should be reduced before the variable becomes active (off its bound). By definition, the reduced cost value of a variable between its bounds is zero. The precise mathematical interpretation of reduced cost is discussed in most text books on mathematical programming. Note: if a basic or superbasic variable has a reduced cost of zero then it will be displayed as 0.0, but if a nonbasic variable has a reduced cost of zero then it will be displayed as ZERO.

Unit of reduced cost

When the variables in your model have an associated unit (see Units of Measurement), special care is required in interpreting the values returned through the .ReducedCost suffix. To obtain the reduced cost in terms of the units specified in the model, the values of the .ReducedCost suffix must be scaled as explained in Unit-based Scaling of Mathematical Programs.

The property CoefficientRange

With the property CoefficientRange you request AIMMS to conduct a first type of sensitivity analysis on this variable during a SOLVE statement of a linear program. The result of this sensitivity analysis are three parameters, representing the smallest, nominal, and largest values for the objective coefficient of the variable so that the optimal basis remains constant. Their values are accessible through the suffices .SmallestCoefficient, .NominalCoefficient and .LargestCoefficient.

The property ValueRange

With the property ValueRange you request AIMMS to conduct a second type of sensitivity analysis during a SOLVE statement of a linear program. The result of the sensitivity analysis are two parameters, representing the smallest and largest values that the variable can take while holding the objective value constant. Their values are accessible through the .SmallestValue and .LargestValue suffices.

Linear programs only

AIMMS only supports the sensitivity analysis conducted through the properties CoefficientRange and ValueRange for linear mathematical programs. If you want to apply these types of analysis to the final solution of a mixed-integer program, you should fix all integer variables to their final solution (using the .NonVar suffix) and re-solve the resulting mathematical program as a linear program (e.g. by adding the clause WHERE type:='lp' to the SOLVE statement).

Storage and computational costs

Setting any of the properties ReducedCost, CoefficientRange or ValueRange may result in an increase of the memory usage. In addition, the computations required to compute the ValueRange may considerably increase the total solution time of your mathematical program.

Constraint related properties

Whenever a defined variable (which is not declared Inline) is part of a mathematical program, AIMMS implicitly adds a constraint to the generated model expressing this definition. In addition to the variable-related sensitivity properties discussed in this section, you can specify the constraint-related sensitivity properties ShadowPrice, RightHandSideRange and ShadowPriceRange (see also Constraint Declaration and Attributes) for such variables to obtain the sensitivity information that can be related to these constraint. You can access the requested sensitivity information by appending the associated suffices to the name of the defined variable.

Uncertainty Related Properties and Attributes

Stochastic programming and robust optimization

The AIMMS modeling language offers facilities for both stochastic programs and robust optimization models. For both types of models you can specify special Variable properties and attributes to define uncertainty-related relationships.

The Stochastic property

Through the Stochastic property you can indicate that, within a stochastic model, the variable can hold scenario-dependent solutions. AIMMS will add a Stage attribute for every variable for which the Stochastic property has been set.

The Stage attribute

The value of the Stage attribute must be a numerical expression evaluating to in integer number indicating the stage at the end of which the variable takes its value during the solution process of a stochastic model. Stochastic programming, and the Stochastic property and Stage attribute are discussed in full detail in Stochastic Parameters and Variables.

The Adjustable property

By setting the Adjustable property for a variable, you indicate that a variable in a robust optimization model has a functional dependency on some or all of the uncertain parameters in the model. If you declare a variable to be adjustable, the Dependency attribute also becomes available for that variable.

The Dependency attribute

Through the Dependency attribute you specify the precise collection of uncertain parameters on which the variable at hand depends. At this moment, AIMMS only supports affine relations between uncertain parameters and adjustable variables. The precise semantics of the Dependency attribute is discussed in Adjustable Variables.