Initializing help system before first use

XPRBctr

XPRBctr


Description
Methods for modifying and accessing constraints and operators for constructing them. Note that all terms in a constraint must belong to the same problem as the constraint itself.
Constructors
Methods
Add an expression to a constraint.
Add a term to a constraint.
Delete a term from a constraint.
Get activity value for a constraint.
Get the coefficient of a constraint term.
Get the C modeling object.
Get dual value.
Get the indicator type of a constraint.
Get the indicator variable of a constraint.
Get the name of a constraint.
Get the range values for a range constraint.
Get the lower range bound for a range constraint.
Get the upper range bound for a range constraint.
Get the right hand side value of a constraint.
Get ranging information for a constraint.
Get the row number for a constraint.
Get the size of a constraint.
Get slack value for a constraint.
Get the row type of a constraint.
Check the type of a constraint.
Check the type of a constraint.
Check the type of a constraint.
Check the type of a constraint.
Test the validity of the constraint object.
Enumerate the terms of a constraint.
Print out a constraint.
Reset the constraint object.
Set the constraint type.
Set the constraint type.
Set the indicator constraint type.
Set the constraint type.
Define a range constraint.
Set a constraint term.
Set the constraint type.
Operators
Assigning constraints and adding (linear or quadratic) expressions:
ctr = rel
ctr += expr
ctr -= expr

Constructor detail

XPRBctr
Synopsis
XPRBctr();
XPRBctr(xbctr *c);
XPRBctr(xbctr *c, XPRBrelation& r);
Arguments
A constraint in BCL C.
Relation defining the constraint.
Description
Create a new constraint object.

Method detail

add
Synopsis
int add(XPRBexpr& e);
Argument
A linear or quadratic expression (may be just a single variable or a constant).
Return value
0 if method executed successfully, 1 otherwise.
Description
This method adds a linear or quadratic expression to the left hand side of a constraint. That means, if the expression contains a constant, this value is subtracted from the constant representing the right hand side of the constraint.
Example

addTerm
Synopsis
int addTerm(XPRBvar& var, double val);
int addTerm(double val, XPRBvar& var);
int addTerm(XPRBvar& var);
int addTerm(double val);
int addTerm(XPRBvar& var, XPRBvar& var2, double val);
int addTerm(double val, XPRBvar& var, XPRBvar& var2);
int addTerm(XPRBvar& var, XPRBvar& var2);
Arguments
var 
A BCL variable.
var2 
A second BCL variable (may be the same as var).
val 
Value of the coefficient of the variable var.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method adds a new term to a constraint, comprising the variable var (or the product of variables var and var2) with coefficient val. If the constraint already has a term with variable var (respectively variables var and var2), val is added to its coefficient. If no variable is specified, the value val is added to the right hand side of the constraint. Constraint terms can also be added with method XPRBctr.add.
Example
Related topics

delTerm
Synopsis
int delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);
Arguments
var 
A BCL variable.
var2 
A second BCL variable (may be the same as var).
Return value
0 if method executed successfully, 1 otherwise.
Description
This function deletes a variable term from the given constraint. The constant term (right hand side value) is changed/reset with method XPRBctr.setTerm.
Related topics
Calls XPRBdelterm

getAct
Synopsis
double getAct();
Return value
Activity value for the constraint, 0 in case of an error.
Description
This method returns the activity value for a constraint. It may be used with constraints that are not part of the problem (in particular, constraints without relational operators, that is, constraints of type XPRB_N). In this case the function returns the evaluation of the constraint terms involving variables that are in the problem. Otherwise, the constraint activity is calculated as activity = RHS – slack.
If this method is called after completion of a global search and an integer solution has been found (that is, if method XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), it returns the value corresponding to the best integer solution. If no solution is available this function outputs a warning and returns 0. In all other cases it returns the activity value in the last LP that has been solved. If this function is used during the execution of an optimization process (for instance in Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync with the flag XPRB_XPRS_SOL.
Example
The following example shows how to retrieve solution values and some other information for a constraint.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");

x = prob.newVar("x", XPRB_PL, 0, 200);
y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);

...  // Solve an LP problem

if (Ctr1.getRowNum() >= 0 && prob.getLPStat()==XPRB_LP_OPTIMAL)
{
  cout << Ctr1.getName() << ": activity: " << Ctr1.getAct();
  cout << " = " << Ctr1.getRHS() << " - " << Ctr1.getSlack();
  cout << ", dual: " << Ctr1.getDual() << endl;
}
else
  cout << "No solution information available." << endl; 
Related topics
Calls XPRBgetact

getCoefficient
Synopsis
double getCoefficient(XPRBvar& var);
double getCoefficient(XPRBvar& var, XPRBvar& var2);
Arguments
var 
A BCL variable.
var2 
A second BCL variable (may be the same as var).
Return value
The coefficient of the given variable or pair of variables, 0 if the constraint does not contain the term.
Description
This function returns the coefficient of a given variable var or of the quadratic term var*var2 in the constraint ctr. Return value 0 indicates that the term is not contained in the constraint. If var is set to NULL, this method returns the right hand side (constant term) of the constraint.
Example
Related topics

getCRef
Synopsis
xbctr *getCRef();
Return value
The underlying modeling object in BCL C.
Description
This method returns the constraint object in BCL C that belongs to the C++ constraint object.

getDual
Synopsis
double getDual();
Return value
Dual value for the constraint, 0 in case of an error.
Description
This function returns the dual value for a constraint. The user may wish to test first whether this constraint is part of the problem, for instance by checking that the row number is non-negative.
Dual information is available only after LP solving. To obtain dual values for a MIP solution (that is, if function XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), you need to fix the discrete variables to their solution values with a call to XPRSfixglobals, followed by a call to XPRBlpoptimize before calling XPRBgetdual. Otherwise, if this function is called when a MIP solution is available it returns 0.
If no solution information is available this function outputs a warning and returns 0.
If this function is used during the execution of an optimization process (for instance in Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync with the flag XPRB_XPRS_SOL. In this case it returns the dual value in the last LP that has been solved.
Example
Related topics
Calls XPRBgetdual

getIndicator
Synopsis
int getIndicator();
Return value
an ordinary constraint;
an indicator constraint with condition b=1;
-1 
an indicator constraint with condition b=0;
-2 
an error has occurred.
Description
This method returns the indicator status of the given constraint.
Example
Related topics

getIndVar
Synopsis
XPRBvar getIndVar();
Return value
A BCL variable.
Description
This method returns the indicator variable associated with the given constraint. This method always returns a BCL variable the validity of which needs to be checked with XPRBvar.isValid.
Example
Related topics

getName
Synopsis
const char *getName();
Return value
Name of the constraint if function executed successfully, NULL otherwise
Description
This method returns the name of a constraint. If the user has not defined a name the default name generated by BCL is returned.
Example
Related topics

getRange
Synopsis
int getRange(double *lw, double *up);
Arguments
lw 
Lower bound on the range constraint.
up 
Upper bound on the range constraint.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method returns the range values of the given constraint.
Related topics
Calls XPRBgetrange

getRangeL
Synopsis
double getRangeL();
Return value
Lower bound on the range constraint.
Description
This method returns the lower bound on the range defined for the given constraint.
Example
Related topics
Calls XPRBgetrange

getRangeU
Synopsis
double getRangeU();
Return value
Upper bound on the range constraint.
Description
This method returns the upper bound on the range defined for the given constraint.
Example
Related topics
Calls XPRBgetrange

getRHS
Synopsis
double getRHS();
Return value
Right hand side value of the constraint, 0 in case of an error.
Description
This method returns the right hand side value ( i.e. the constant term) of a previously defined constraint. The default right hand side value is 0. If the given constraint is a ranged constraint this function returns its upper bound.
Example
Related topics
Calls XPRBgetrhs

getRNG
Synopsis
double getRNG(int rngtype);
Argument
rngtype 
The type of ranging information sought. This is one of:
XPRB_UPACT 
upper activity (= the level to which the constraint activity may be increased at a cost per unit of increase given by the XPRB_UUP value, ignoring the upper bound on the constraint as specified by its RHS);
XPRB_LOACT 
lower activity (= the level to which the constraint activity may be decreased at a cost per unit of decrease given by the XPRB_UDN value, ignoring the lower bound on the constraint as specified by its RHS);
XPRB_UUP 
upper unit cost;
XPRB_UDN 
lower unit cost.
Return value
Ranging information of the required type.
Description
This method can only be used after solving an LP problem. Ranging information for MIP problems can be obtained by fixing all discrete variables to their solution values and re-solving the resulting LP problem.
Example
The following example displays the constraint activity and the activity range.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");

x = prob.newVar("x", XPRB_PL, 0, 200);
y = prob.newVar("y", XPRB_PL, 0, 200);
Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);

...  // Solve the problem

cout << "C1: " << Ctr1.getAct() << " (activity range: ";
cout << Ctr1.getRNG(XPRB_LOACT) << ", " ;
cout << Ctr1.getRNG(XPRB_UPACT) << ")" << endl;
Related topics

getRowNum
Synopsis
int getRowNum();
Return value
Row number (non-negative value), or a negative value.
Description
This method returns the matrix row number of a constraint. If the matrix has not yet been generated or the constraint is not part of the matrix (constraint type XPRB_N or no non-zero terms) then the return value is negative. To check whether the matrix has been generated, use method XPRBprob.getProbStat. The counting of row numbers starts with 0.
Example
Related topics

getSize
Synopsis
int getSize();
Return value
Size (= number of linear or quadratic terms with a non-zero coefficient) of the constraint, or -1 in case of an error.
Description
This method returns the size of a constraint (or -1 in case of an error).
Example
Related topics

getSlack
Synopsis
double getSlack();
Return value
Slack value for the constraint, 0 in case of an error.
Description
This method returns the slack value for a constraint. The user may wish to test first whether this constraint is part of the problem, for instance by checking that the row number is non-negative.
If this function is called after completion of a global search and an integer solution has been found (that is, if method XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), it returns the value in the best integer solution. If no integer solution is available after a global search this function outputs a warning and returns 0. In all other cases it returns the slack value in the last LP that has been solved. If this function is used during the execution of an optimization process (for instance in Optimizer library callback functions) it needs to be preceded by a call to XPRBprob.sync with the flag XPRB_XPRS_SOL.
Example
Related topics
Calls XPRBgetslack

getType
Synopsis
int getType();
Return value
XPRB_L 
'less than or equal to' inequality;
XPRB_G 
'greater than or equal to' inequality;
XPRB_E 
equality;
XPRB_N 
a non-binding row (objective function);
XPRB_R 
a range constraint;
-1 
an error has occurred.
Description
This method returns the constraint type if successful, and -1 in case of an error.
Example
Related topics

isDelayed
Synopsis
bool isDelayed();
Return value
true if constraint is delayed constraint, false otherwise.
Description
This method indicates whether the given constraint is a delayed or an ordinary constraint.
Related topics

isIncludeVars
Synopsis
bool isIncludeVars();
Return value
true if constraint is an include vars special constraint, false otherwise.
Description
This method indicates whether the given constraint is an include varsspecial constraint or an ordinary constraint.
Related topics

isIndicator
Synopsis
bool isIndicator();
Return value
true if constraint is an indicator constraint, false otherwise.
Description
This method indicates whether the given constraint is an indicator or an ordinary constraint.
Related topics

isModCut
Synopsis
bool isModCut();
Return value
true if constraint is a model cut, false otherwise.
Description
This method indicates whether the given constraint is a model cut or an ordinary constraint.
Related topics

isValid
Synopsis
bool isValid();
Return value
true if object is valid, false otherwise.
Description
This method checks whether the constraint object is correctly defined. It should always be used to test the result returned by XPRBprob.getCtrByName.
Example

nextTerm
Synopsis
const void *nextTerm(const void *ref, XPRBvar& var, double *coeff);
const void *nextTerm(const void *ref, XPRBvar& var, XPRBvar& v2, double *coeff);
Arguments
ref 
Reference pointer or NULL.
var 
A BCL variable.
v2 
A second BCL variable (for enumeration of quadratic terms).
coeff 
Coefficient associated to current term.
Return value
Reference pointer for the next call to nextTerm or NULL if there are no more terms.
Description
These methods are used to enumerate the linear or quadratic terms of a constraint. The first parameter ref serves to keep track of the current location in the enumeration; if this parameter is NULL, the first term is returned. This function returns NULL if it is called with the reference to the last element. Otherwise, the returned value can be used as the input parameter ref to retrieve the following term of the same type.
Example
The following example shows how to enumerate and display the linear terms of a constraint.
XPRBprob prob("myprob");
XPRBctr Ctr1;
...
XPRBvar var;
double coeff;
const void *ref = NULL;
while ((ref = Ctr1.nextTerm(ref, var, &coeff)) != NULL) {
  cout << " var " << var.getName() << " has coeff " << coeff << endl;
}
Related topics

print
Synopsis
int print();
Return value
0 if function executed successfully, 1 otherwise.
Description
This method prints out a constraint in LP format. It is not available in the student version.
Example
Related topics
Calls XPRBprintctr

reset
Synopsis
void reset();
Description
Clear the definition of the constraint object.

setDelayed
Synopsis
int setDelayed(bool dstat);
Argument
dstat 
The constraint type, which must be one of:
false 
ordinary constraint;
true 
delayed constraint.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method changes the type of a previously defined constraint from ordinary constraint to delayed constraint and vice versa. Delayed or 'lazy' constraints must be satisfied for any integer solution, but will not be loaded into the active set of constraints until required.
2. Constraint properties 'include vars', 'model cut', 'delayed constraint', and 'indicator constraint' are mutually exclusive. When changing from one of these types to another you must first reset the correponding type to 0.
Example
The following example turns the constraint Ctr3 into a delayed constraint.
XPRBvar y,b;
XPRBctr Ctr3;
XPRBprob prob("myprob");

y = prob.newVar("y", XPRB_PL, 0, 200);
b = prob.newVar("b", XPRB_BV);

Ctr3 = prob.newCtr("C3", y >= 50*b);
Ctr3.setDelayed(true); 
Related topics

setIncludeVars
Synopsis
int setIncludeVars(bool ivstat);
Argument
ivstat 
The constraint type, which must be one of:
false 
ordinary constraint;
true 
include vars special constraint.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method changes the type of a previously defined constraint from ordinary constraint to an include vars special constraint and vice versa. Include vars constraints are used to force the loading of all variables they contain into the Optimizer (even if they don't appear in any other constraint). Only constraints of type XPRB_N can be changed into include vars constraints; the constraints themselves are not loaded into the Optimizer (as all constraints of type XPRB_N), just the variables they contain are loaded. The coefficients of the variables are also ignored as long as they are non-zero.
2. Constraint properties 'include vars', 'model cut', 'delayed constraint', and 'indicator constraint' are mutually exclusive. When changing from one of these types to another you must first reset the correponding type to 0.
Example
The following example turns the constraint CtrIV into an include vars special constraint.
XPRBvar y,b;
XPRBctr CtrIV;
XPRBprob prob("myprob");

y = prob.newVar("y", XPRB_PL, 0, 200);
b = prob.newVar("b", XPRB_BV);

CtrIV = prob.newCtr("IncVars", b+y);
CtrIV.setIncludeVars(true); 
Related topics

setIndicator
Synopsis
int setIndicator(ind dir, XPRBvar );
Arguments
dir 
The indicator type, which must be one of:
ordinary constraint;
-1 
indicator constraint with condition b=0;
indicator constraint with condition b=1.
previously created binary variable.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method changes the type of a previously defined constraint from ordinary constraint to indicator constraint and vice versa. Indicator constraints are defined by associating a binary variable and an implication sense with a linear inequality or range constraint.
2. Constraint properties 'include vars', 'model cut', 'delayed constraint', and 'indicator constraint' are mutually exclusive. When changing from one of these types to another you must first reset the correponding type to 0.
Example
The following example turns the constraint Ctr3 into the indicator constraint b=1 ⇒ Ctr3.
XPRBvar y,b;
XPRBctr Ctr3;
XPRBprob prob("myprob");

y = prob.newVar("y", XPRB_PL, 0, 200);
b = prob.newVar("b", XPRB_BV);

Ctr3 = prob.newCtr("C3", y >= 50);
Ctr3.setIndicator(1, b);
if (Ctr3.isIndicator())
  cout << Ctr3.getIndVar().getName() << "->" << Ctr3.getName() << endl;
Related topics

setModCut
Synopsis
int setModCut(bool mstat);
Argument
mstat 
The constraint type, which must be one of:
false 
constraint;
true 
model cut.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method changes the type of a previously defined constraint from ordinary constraint to model cut and vice versa.
2. Model cuts must be 'true' cuts, in the sense that they are redundant at the optimal MIP solution. The Optimizer does not guarantee to add all violated model cuts, so they must not be required to define the optimal MIP solution.
3. Constraint properties 'include vars', 'model cut', 'delayed constraint', and 'indicator constraint' are mutually exclusive. When changing from one of these types to another you must first reset the correponding type to 0.
Example
The following example turns the constraint Ctr3 into a model cut.
XPRBvar y,b;
XPRBctr Ctr3;
XPRBprob prob("myprob");

y = prob.newVar("y", XPRB_PL, 0, 200);
b = prob.newVar("b", XPRB_BV);

Ctr3 = prob.newCtr("C3", y >= 50*b);
Ctr3.setModCut(true); 
Related topics

setRange
Synopsis
int setRange(double lw, double up);
Arguments
lw 
Lower bound on the range constraint.
up 
Upper bound on the range constraint.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method changes the type of a constraint to a range constraint within the bounds specified by lw and up. The constraint type and right hand side value of the constraint are replaced by the type XPRB_R (range) and the two bounds.
Example
The following example defines a constraint with the range bounds 100 and 500, adds 5 to the range bounds and prints them out. The constraint is then changed to an inequality constraint whereby the upper range bound is transformed into the right hand side. The output printed by this example is displayed in the commentaries.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");

x = prob.newVar("x", XPRB_PL, 0, 200);
y = prob.newVar("y", XPRB_PL, 0, 200);

Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);
Ctr1.setRange(100,500);
Ctr1.addTerm(5);
if (Ctr1.getType() == XPRB_R)
{
 cout << "C1 in [" << Ctr1.getRangeL() << ",";
 cout << Ctr1.getRangeU() << "]" << endl;   // C1 in [105,505]
 cout << "C1 size: " << Ctr1.getSize() << endl;   // C1 size: 2
 Ctr1.setType(XPRB_G);
 Ctr1.print();                         // C1: 3*x + 2*y >= 505
} 
Related topics
Calls XPRBsetrange

setTerm
Synopsis
int setTerm(XPRBvar& var, double val);
int setTerm(double val, XPRBvar& var);
int setTerm(double val);
int setTerm(XPRBvar& var, XPRBvar& var2, double val);
int setTerm(double val, XPRBvar& var, XPRBvar& var2);
Arguments
var 
A BCL variable.
var2 
A second BCL variable (may be the same as var).
val 
Value of the coefficient of the variable var.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method sets the coefficient of a variable (or of the product of the two given variables) to the value val. If no variable is specified, the right hand side of the constraint is set to val.
Example
This example sets the coefficient of variable y in constraint Ctr1 to 5 and then adds a linear expression and a constant term. The commentaries show the constraint definitions resulting from the modifications. Please notice in particular the different behavior of add and addTerm for the addition of constants.
XPRBvar x,y;
XPRBctr Ctr1;
XPRBprob prob("myprob");

x = prob.newVar("x", XPRB_PL, 0, 200);
y = prob.newVar("y", XPRB_PL, 0, 200);

Ctr1 = prob.newCtr("C1", 3*x + 2*y <= 400);
Ctr1.setTerm(5, y);       // C1:  3*x + 5*y <= 400
Ctr1.add(x+10);           // C1:  4*x + 5*y <= 390
Ctr1.setTerm(400);        // C1:  4*x + 5*y <= 400
Ctr1.addTerm(5);          // C1:  4*x + 5*y <= 405

cout << "Coefficient of x in " << Ctr1.getName() << ": ";
cout << Ctr1.getCoefficient(x) << endl;
cout << "Coefficient of x*y in " << Ctr1.getName() << ": ";
cout << Ctr1.getCoefficient(x,y) << endl;
Related topics

setType
Synopsis
int setType(int type);
Argument
type 
The constraint type, which must be one of:
XPRB_L 
'less than or equal to' constraint;
XPRB_G 
'greater than or equal to' constraint;
XPRB_E 
an equality;
XPRB_N 
a non-binding row (objective function).
Return value
0 if method executed successfully, 1 otherwise.
Description
This method changes the type of a previously defined constraint to inequality, equation or non-binding. Method XPRBctr.setRange has to be used for changing the constraint to a ranged constraint. If a ranged constraint is changed back to some other type with this method, its upper bound becomes the right hand side value.
Example
Related topics


© 2001-2019 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.