---

NlpSlack Class Reference

An implementation of Nlp that transforms the problem into a formulation that uses slack variables. More...

#include <NlpSlack.hh>

Inheritance diagram for NlpSlack:

List of all members.

Public Methods
ElementGather &	l_in_cc ()
	Access mLinCC.
ElementGather &	l_in_c ()
	Access mLinC.
ElementGather &	p_in_cc ()
	Access mPinCC.
ElementGather &	p_in_c ()
	Access mPinC.
ElementGather &	yy_in_cc ()
	Access mYYinCC.
ElementGather &	y_in_c ()
	Access mYinC.
ElementGather &	t_in_cc ()
	Access mTinCC.
ElementGather &	u_in_cc ()
	Access mUinCC.
ElementGather &	s_in_cc ()
	Access mSinCC.
void	initialize (IotrVector &rxlow, IotrVector &rxupp, IotrVector &rclow, IotrVector &rcupp, IotrVector &x, IotrVector &yz, double bignum, Functional *c)
	Called explicitly (in other words, not from a constructor) to initialize this instance of Nlp before it is used.
virtual NlpBounds *	getBoundsPtr ()
	Return the bounds of the problem as a pointer.
virtual NlpBounds &	bounds ()
	Access the bounds of the problem.
virtual NlpIterate *	newVariables ()
virtual NlpIterate *	initialVariables ()
virtual NlpResiduals *	newResiduals ()
virtual NlpLinsys *	newLinsys ()
virtual NlpValues *	newValues ()
virtual NlpGrads *	newGrads ()
virtual NlpHessian *	newHessian ()
virtual NlpLocalModel *	localModelAt (NlpIterate &)
	Return NlpLocalModel centered at NlpIterate.
virtual void	inspect ()
	Display an ascii respresentation of this object.
virtual void	writeConfiguration (std::ostream &out, char indent[])
	Write configuration information for this object.
Protected Methods
virtual void	distributeSlacks (ElementGatherHandle &hXXinX, ElementGatherHandle &hTinX, ElementGatherHandle &hUinX, ElementGatherHandle &hSinC, ElementGatherHandle &hTinC, ElementGatherHandle &hUinC)
	Determine the placement of the slack variables in the new primal variables (X) and in the new constraints (C).
Protected Attributes
IotrVectorCategorizeHandle	mClassificationRule
	A rule for classifying constraints into those violated at the initial point, and those that are feasible at the initial point.
FunctionalHandle	mFunc
	The instance of Functional that defines the objective and constraint functions.
IotrVectorHandle	mRawXX
	The primal variables, including any fixed variables, which will be passed to the Functional::evaluate().
IotrVectorHandle	mYYz
	The dual variables that will be passed ot Functional::evaluate().
ElementGatherHandle	mXXfixedI
	Those elements of mRawXX that are fixed.
IotrVectorHandle	mXXfixed
	The values of the fixed variables.
ElementGatherHandle	mXXlowI
	Lower bounds of the original primal variables, after fixed variables have been removed.
ElementGatherHandle	mXXuppI
	Upper bounds of the original primal variables, after fixed variables have been removed.
ElementGatherHandle	mLinCC
	feasible lower bounds in the original constraints
ElementGatherHandle	mPinCC
	feasible upper bounds in the original constraints
ElementGatherHandle	mTinCC
	violated lower bounds in the original constraints
ElementGatherHandle	mUinCC
	violated upper bounds in the original constraints
ElementGatherHandle	mYYinCC
	equality constraints in the original constraints
ElementGatherHandle	mSinCC
	Elements in the old constraints that are unchanged in the new.
ElementTransferHandle	mStoC
	Transfer the constraints in SinCC to their locations in C.
ElementTransferHandle	mTtoC
	Transfer the constraints in TinCC to their locations in C.
ElementTransferHandle	mUtoC
	Transfer the constraints in UinCC to their locations in C.
ElementTransferHandle	mTinXtoC
	A transfer the may be used to subtract the values of the lower-bound slacks (T) from the appropriate locations in C.
ElementTransferHandle	mUinXtoC
	A transfer the may be used to subtract the values of the lower-bound slacks (U) from the appropriate locations in C.
ElementTransferHandle	mXtoRawXX
	Used to transfer elements from the transformed primal variables into mRawXX so that Functional::evaluate() may be called.
NlpBoundsHandle	mBounds
	The bounds of the transformed problem.
Indices of variables that are not fixed
The indices of elements of mRawXX that are not fixed, represented as an ElementGather and an equivalent IotrMask.
ElementGatherHandle	mXXfilter
IotrMaskHandle	mXXmask
The layout of S
S is the union of the feasible lower bounds, the feasible upper bounds and the original equality constrants.
ElementGatherHandle	mLinS
ElementGatherHandle	mPinS
ElementGatherHandle	mYYinS
The layout of X
X is the union of the original primal variables (XX), the slack variables corresponding to constraints with violated lower bounds and the slack variables corresponding to constraints with violated upper bounds.
ElementGatherHandle	mXXinX
ElementGatherHandle	mTinX
ElementGatherHandle	mUinX
The layout of G
G is the vector of dual variables for lower bounds on the primal variables of the transformed (new) problem; it is the union of the dual variables for the lower bounds on the original variables (GG) with the dual variables for the lower bounds of the slack variables T and U.
ElementGatherHandle	mGGinG
ElementGatherHandle	mTinG
ElementGatherHandle	UinG
ElementGatherHandle	mSinC
	The layout of C.
ElementGatherHandle	mTinC
	The layout of C.
ElementGatherHandle	mUinC
	The layout of C.
ElementGatherHandle	mYYinY
	The layout of Y.
ElementGatherHandle	mTinY
	The layout of Y.
ElementGatherHandle	mUinY
	The layout of Y.

---

Detailed Description

An implementation of Nlp that transforms the problem into a formulation that uses slack variables.

The iotr algorithm requires us to choose an initial point at which all the inequality constraints are strictly satisfied. It is easy to choose values of x that are strictly feasible with respect to their bounds. It is much more difficult to choose an x so that all the inequality constraints on c(x) are strictly satisfied. The NlpSlack formulation is used when a stricly feasible initial point is not known. This formulation uses slack variables to convert some general constraints to equality constraints. The class thus converts the problem into one for which an initial point that strictly satisfies the inequality constraints is known.

The NlpSlackLocalModel, NlpSlackValues, NlpSlackGrads, NlpSlackHessian and NlpSlackLinsys classes are aware of this decomposition of the constraints. Other classes should be unaware of this transformation, with the possible exception of classes that display information to the user. (The user might be interested in the slacks as slacks.)

When an instance of NlpSlack is created, the user may supply the rule for choosing which constraints will be treated as slack variables, or may elect to use the default rule by using the default constructor to create an instance of NlpSlack, as is done in the following code

 NlpSlackHandle formulation( new NlpSlack );

The default rule is recommended for most uses. It chooses to add slacks to inequality contraints that are either violated, or are too close to their bounds. See the documentation of the DefaultCategorizeGenConstraints for an exact description of the rules used.

Before any further processing is done, the problem is transformed to one without fixed variables. The values and locations of these fixed variables are noted, so that the the NlpSlack::localModelAt method may provide all variables to the fuction, and so the various methods of NlpSlackGrads, NlpSlackHessian and NlpSlackLinsys may filter out columns and or rows corresponding to fixed variables from the data returned from the Functional. Otherwise, the problem is treated as if it had no fixed variables.

The original primal variables (after fixed variables have been filtered out) are refered to as xx, and the original constraint values are referred to as cc. The members of cc may be devided into the following five categories:

• YYinCC - Equality constraints;
• LinCC - Lower bounds that are not violated at the starting point;
• PinCC - Upper bounds that are not violated at the starting point.
• TinCC - Lower bounds that are violated at the starting point.
• UinCC - Upper bounds that are violated at the starting point.

These categories are almost certainly not disjoint. In particular, elements in LinCC may also be in PinCC or UinCC and elements in PinCC may also be in LinCC or TinCC. YYinCC, on the other hand, is necessarily disjoint from the other categories.

Observe that we refer to the category of violated lower bounds as TinCC, but the method for getting the ElementGather specifying TinCC is NlpSlack::t_in_cc(). Similarly, the data member bound to this ElementGather is mTinCC. We won't dwell on these minor difference in name. We believe that the naming system is consistent, and that the values will be clear in context.

The constraints in YYinCC, LinCC and PinCC will be unaltered in the transfromed problems. We name the union of these three sets SinCC (S for same.) The members of TinCC and UinCC, on the other hand, must be converted into equality constraints using slack, and thus become new constraints in the transformed problem. We refer to the constraints of the new problem as c. The new constraints, c, are a union of the constraints unchanged from the original problem, SinCC, new equality constraints corresponding to the constraints in TinCC and new equality constraints corresponding to the constraints in UinCC. Thus the new constraint functions are

where t and u are new vectors of slacks, and nt and nu are the lengths of these vectors.

There is no general rule for how these three sets of constraints will be ordered in c. In a sequential implementation, it might make sense to put those members of SinCC first, followed by the memebers of TinCC and UinCC. In a parallel implementation, on the other hand, one might want to be careful that the values for each constraint functions are located on the processor on which the function is evaluated. Because there is no general rule, the protected virtual function NlpSlack::distributeSlacks is used to specify the layout of c. This method computes three instances of ElementGather that completely specify the layout of c: SinC, TinC and UinC. The ElementTransfer StoC transfers the elements of SinCC from their location in cc to their location in c, which is given by SinC. The instances UtoC and TtoC of ElementTransfer behave analogously.

The addition of new slacks implies that the transformed system will have additional primal variables. We refer to the variables of the transformed problem as x. As with the constraint vector, c, there is no general rule for the layout of x. In particular on a parallel system, it would be best to have the slack variables on the same processor as their corresponding constraint values. Because there is no general layout, the NlpSlack::distributeSlacks method also returns XXinX, TinX and UinX. The ElementGather TinX contains the locations in x of the slacks corresponding to the constraints in TinC. The ElementTransfer TinXtoC transfers the slack values in x to the constraint locations is c. In particular,

 TinXtoC->transferForward( -1.0, x, 1.0, c )

subtracts the slack variables from the corresponding constriants. The objects UinX and UinXtoC behave analogously.

The addition of slacks also implies additional lower bounds on the variables corresponding to the slacks. We refer to these bounds as g. The components of g are broken down into the three categories:

• GGinG - lower bounds on x corresponding to lower bounds on xx.
• TinG - lower bounds on x corresponding to the TinX slacks.
• UinG - lower bounds on x corresponding to the UinX slacks.

These sets are completely determined by XXinX, TinX and UinX.

Similarly the addition of new equality constraints to the problem implies new multipilers for these constraints. The location of these multipliers are given by the following ElementGathers:

• YinC - the location of all equality multipliers in C
• YYinY - the location of the original equality constraints in the transformed equality constraints.
• TinY - the location of the "T" constraints in the transformed equality constraints.
• UinY - the location of the "U" constraints in the transformed equality constraints.

The index set YYinC, giving the locations of the old equality constraints among the new constraints, can be obtained by composition.

 YYinC = ElementGatherHandle( YYinY->composeWith( YinC ) );

---

Member Function Documentation

virtual void NlpSlack::distributeSlacks (  ElementGatherHandle &    hXXinX, ElementGatherHandle &    hTinX, ElementGatherHandle &    hUinX, ElementGatherHandle &    hSinC, ElementGatherHandle &    hTinC, ElementGatherHandle &    hUinC )  [protected, virtual]

Determine the placement of the slack variables in the new primal variables (X) and in the new constraints (C). In general, the layout of C and X cannot be determined a priori, but rathermust be chosen to suit the method of evaluating the problem functions. For instance, in a parallel context, each slack variable should be placed on the same processor as the constraint function that it corresponds to. The default implementation just appends the slacks to X and C. Override this function in a subclass if this is not a desirable layout.

---

The documentation for this class was generated from the following file:

• NlpSlack.hh

---