ComplementaryVariable
Declaration and Attributes
Complementarity variables
To support you in formulating a complementarity model, AIMMS provides a
special type of variable, the ComplementaryVariable
. The attributes
of a complementarity variable allow you to declare an (indexed) class of
variables in a complementarity model along with their associated
constraints. The attributes of a ComplementaryVariable
are listed in
this table.
Automatic sanity checks
By construction, this new variable type automatically ensures that every
variable in a complementarity model is associated with a single
constraint. Also, when AIMMS detects that the total number of (finite)
bounds on both the complementarity variable and its associated
constraint is not equal to two (as required above), a compilation error
will result. Thus, ComplementaryVariable
will help to reduce the
most common declaration errors for this type of model.
Attribute 
Valuetype 
See also page 


indexdomain 


range 


unitvalued expression 


string 


comment string 


expression 


reference 



The IndexDomain
attribute
Through the IndexDomain
attribute of a complementarity variable you
can specify domain of tuples for which you want AIMMS to generate a
variable and its associated constraint. During generation, AIMMS will
only generate a variable for all tuples that satisfy all domain
restrictions that you have imposed on the domain.
The Range
attribute
In the Range
attribute you can specify the lower and upper bound of
a complementarity variable, in a similar manner for ordinary
Variables
(see also Variable Declaration and Attributes). During generation, AIMMS
will perform a runtime check, for every individual tuple in the index
domain, whether the number of finite bounds specified here, plus the
number of finite bounds in the constraint specified in the
Complement
attribute, exactly equals two.
The Complement
attribute
The Complement
attribute allows you to specify the constraint that
must be associated with the complementarity variable at hand. With
\(f(x,\dots)\) a general nonlinear function, the following types of
expressions are allowed
\(\phantom{a\leq{}}f(x,\dots)\geq a\) (variable must have a singlesided
Range
),\(\phantom{a\leq{}}f(x,\dots)\leq a\) (variable must have a singlesided
Range
),\(a \leq f(x,\dots) \leq b\) (variable must be free),
\(\phantom{a\leq{}}f(x,\dots)= a\) (variable must be free), or
\(\phantom{a\leq{}}f(x,\dots)\phantom{{}\leq b}\) (variable must be bounded).
In addition, the Complement
attribute can refer to an existing
Constraint
in your model, which then should hold a definition as one
of the cases above. The Complement
attribute can also hold a scalar
element parameter into the set AllConstraints
, which offers the
possibility to assign different constraints to the complementarity
variable in sequential solves.
Constraint listing
In the constraint listing, the constraints associated with a
complementarity variable will be listed with a generated name consisting
of the name of the ComplementarityVariable
with an additional suffix
_complement
.
The NonvarStatus
attribute
With the NonvarStatus
attribute you can indicate for which tuples
you want AIMMS to consider the complementarity variable as a parameter,
i.e. with the lower and upper bound set equal to the level value prior
to solving the model (see also The Priority, Nonvar and RelaxStatus Attributes). From the
mixed complementarity condition it follows that the function in the
corresponding constraint is then allowed to assume arbitrary values,
whence there is no strict need to generate the variable and constraint
for the solver.
Positive and negative values
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. When the NonvarStatus
assumes a positive value,
AIMMS will not generate the variable and its associated constraint. For
negative values, the variable and constraint will be generated, but
reduces to the second special case of the mixed complementarity
condition
i.e. the function in the constraint will be allowed to assume arbitrary values.
The Unit attribute
Providing a unit for a complementarity variable will help you in a number of ways.
AIMMS will help you to check the consistency of all the constraints and assignments in your model (including the expression in the
Complement
attribute), andAIMMS 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 Property
attribute
Complementarity variables support the properties NoSave
and
Complement
. With the property NoSave
you indicate that you do
not want to store data associated with this variable in a case. The
Complement
property indicates that you are interested in the level
values of the constraint defined in the Complement
attribute. When
this property is set, AIMMS will make the level value of this constraint
available through the .Complement suffix of the complementarity
variable at hand.
Example
The declaration of the complementarity variable MembraneHeight
expresses a complementarity condition for the height of a membrane in a
rectangular \((x,y)\)grid, with a uniform external force acting on
each cell in the grid.
ComplementaryVariable MembraneHeight {
IndexDomain : (x,y);
Range : [MembraneLowerBound(x,y), MembraneUpperBound(x,y)];
Complement : {
4*MembraneHeight(x,y)
 MembraneHeight(x+1,y)  MembraneHeight(x1,y)
 MembraneHeight(x,y+1)  MembraneHeight(x,y1)
 CellForce
}
}
The complementarity condition expresses that either the membrane reaches one its given bounds (for instance, an obstacle placed in the way of the membrane), or the external force on the cell must be equal to the internal forces acting on the cell caused by differences in height with neighboring cells.