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

XPRBctr();
XPRBctr(xbctr *c);
XPRBctr(xbctr *c, XPRBrelation& r);

Methods

int add(XPRBexpr& e);

Add an expression to a constraint.

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);

Add a term to a constraint.

int delTerm(XPRBvar& var);
int delTerm(XPRBvar& var, XPRBvar& var2);

Delete a term from a constraint.

double getAct();

Get activity value for a constraint.

double getCoefficient(XPRBvar& var);
double getCoefficient(XPRBvar& var, XPRBvar& var2);

Get the coefficient of a constraint term.

xbctr *getCRef();

Get the C modeling object.

double getDual();

Get dual value.

int getIndicator();

Get the indicator type of a constraint.

XPRBvar getIndVar();

Get the indicator variable of a constraint.

const char *getName();

Get the name of a constraint.

int getRange(double *lw, double *up);

Get the range values for a range constraint.

double getRangeL();

Get the lower range bound for a range constraint.

double getRangeU();

Get the upper range bound for a range constraint.

double getRHS();

Get the right hand side value of a constraint.

double getRNG(int rngtype);

Get ranging information for a constraint.

int getRowNum();

Get the row number for a constraint.

int getSize();

Get the size of a constraint.

double getSlack();

Get slack value for a constraint.

int getType();

Get the row type of a constraint.

bool isDelayed();

Check the type of a constraint.

bool isIncludeVars();

Check the type of a constraint.

bool isIndicator();

Check the type of a constraint.

bool isModCut();

Check the type of a constraint.

bool isValid();

Test the validity of the constraint object.

const void *nextTerm(const void *ref, XPRBvar& var, double *coeff);
const void *nextTerm(const void *ref, XPRBvar& var, XPRBvar& v2, double *coeff);

Enumerate the terms of a constraint.

int print();

Print out a constraint.

void reset();

Reset the constraint object.

int setDelayed(bool dstat);

Set the constraint type.

int setIncludeVars(bool ivstat);

Set the constraint type.

int setIndicator(ind dir, XPRBvar );

Set the indicator constraint type.

int setModCut(bool mstat);

Set the constraint type.

int setRange(double lw, double up);

Define a range constraint.

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);

Set a constraint term.

int setType(int type);

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

c	A constraint in BCL C.
r	Relation defining the constraint.

Description

Create a new constraint object.

Method detail

add

Synopsis

int add(XPRBexpr& e);

Argument

e	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

See XPRBctr.setTerm.

addTerm

Synopsis

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

See XPRBctr.setTerm.

Related topics

Calls XPRBaddterm or XPRBaddqterm

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

See XPRBctr.setTerm.

Related topics

Calls XPRBgetcoeff or XPRBgetqcoeff

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

See XPRBctr.getAct.

Related topics

Calls XPRBgetdual

getIndicator

Synopsis

int getIndicator();

Return value

0	an ordinary constraint;
1	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

See XPRBctr.setIndicator.

Related topics

Calls XPRBgetindicator

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

See XPRBctr.setIndicator.

Related topics

Calls XPRBgetindvar

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

See XPRBctr.getAct.

Related topics

Calls XPRBgetctrname

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

See XPRBctr.setRange.

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

See XPRBctr.setRange.

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

See XPRBctr.getAct.

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

Calls XPRBgetctrrng

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

See XPRBctr.getAct.

Related topics

Calls XPRBgetrownum

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

See XPRBctr.setRange.

Related topics

Calls XPRBgetctrsize

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

See XPRBctr.getAct.

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

See XPRBctr.setRange.

Related topics

Calls XPRBgetctrtype

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

Calls XPRBgetdelayed

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

Calls XPRBgetincvars

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

Calls XPRBgetindicator

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

Calls XPRBgetmodcut

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

See XPRBprob.getCtrByName.

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

Calls XPRBgetnextterm or XPRBgetnextqterm

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

See XPRBctr.setRange.

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

Calls XPRBsetdelayed

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.

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

Calls XPRBsetincvars

setIndicator

Synopsis

int setIndicator(ind dir, XPRBvar );

Arguments

dir

The indicator type, which must be one of:

0	ordinary constraint;
-1	indicator constraint with condition b=0;
1	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.

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

Calls XPRBsetindicator

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

Calls XPRBsetmodcut

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

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

Calls XPRBsetterm or XPRBsetqterm

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

See XPRBctr.setRange.

Related topics

Calls XPRBsetctrtype

Contents

Index

Glossary

Search Results

XPRBctr

XPRBctr