Initializing help system before first use

XPRBprob

Description
Problem definition, including methods for creating and deleting the modeling objects, problem solving, changing settings, and retrieving solution information.
Constructors
Methods
Add cuts to a problem.
Add a new feasible, infeasible or partial MIP solution to the Optimizer.
Start using the local optimizer problem with BCL in a callback.
Delete all directives.
Delete a constraint.
Delete a cut definition.
Delete a SOS.
Reset BCL to the original optimizer problem in a callback.
Print problem matrix to a file.
Fixes all the MIP entities to the values of the last found MIP solution.
Get the C modeling object.
Retrieve a constraint by its name.
Retrieve an index set by its name.
Get the LP status.
Get the MIP status.
Get the name of the problem.
Get the number of independent IIS in an infeasible LP problem.
Get the objective function value.
Get the problem status.
Get the sense of the optimization.
Retrieve a SOS by its name.
Retrieve a variable by its name.
Returns an XPRSprob problem reference for a problem defined in BCL.
Load a previously saved basis.
Load the problem into the optimizer.
Load an integer solution into BCL or the Optimizer.
Solve as a continuous problem.
Solve as a discrete problem.
Enumerate constraints.
Create a new constraint.
Create a new cut.
Create a new index set.
Create a solution.
Create a SOS.
Create a decision variable.
Print out the problem.
Print out the objective function of a problem.
Read a solution from a binary solution file (.sol), loading it into the Optimizer.
Read a solution from an ASCII solution file (.slx), loading it into the Optimizer.
Release system resources used for storing solution information.
Save the current basis.
Set a column ordering criterion for matrix generation.
Set the cut mode.
Set the size of a dictionary.
Set the message print level.
Select the objective function.
Set the name of the problem.
Set the format for printing real numbers.
Set the sense of the optimization.
Synchronize BCL with the Optimizer.
Write directives to a file.
Write the current Optimizer solution to a CSV format ASCII file, problem_name.asc (and .hdr).
Write the current Optimizer solution to a binary solution file for later input into the Optimizer.
Write the current Optimizer solution to a fixed format ASCII file, problem_name .prt.
Write the current Optimizer solution to an ASCII solution file (.slx) using a similar format to MPS files.

Constructor detail

XPRBprob
Synopsis
XPRBprob();
XPRBprob(const char *name);
Argument
name 
The problem name. If none specified, BCL creates a unique name.
Description
1. This method needs to be called to create and initialize a new problem. If BCL has not been initialized previously this method also initializes BCL and Xpress Optimizer. The initialization / problem creation fails if no valid license is found.
2. When solving several instances of a problem simultaneously the user must make sure to assign a different name to every instance.
Related topics
Calls XPRBnewprob

Method detail

addCuts
Synopsis
int addCuts(XPRBcut *cuts, int num);
Arguments
cuts 
Array of previously defined cuts.
num 
Number of cuts in cuts.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function adds previously defined cuts to the problem in Xpress Optimizer. It may only be called from within the Xpress Optimizer cut manager callback functions. BCL does not check for doubles, that is, if the user defines the same cut twice it will be added twice to the matrix. Cuts added at a node during the branch and bound search remain valid for all child nodes but are removed at all other nodes.
Example
This example shows how to define the cut manager callback and add a cut to the Optimizer problem. The function call adding the cut is surrounded by the pair XPRBprob.beginCB and XPRBprob.endCB to coordinate BCL with the local Optimizer subproblem in the case of a multi-threaded MIP search.
int XPRS_CC cbNode(XPRSprob oprob, void *bp)
{
 XPRBprob *bprob = (XPRBprob*)bp;
 XPRBcut aCut;
 bprob->beginCB(oprob);
   ...                // Define the cut 'aCut'
 bprob->addCuts(&aCut, 1);
 bprob->endCB();
 return 0;            // Call this function once per node
}

int main(int argc, char **argv)
{
 XPRBprob prob("myprob");
   ...                // Define the problem
 prob.setCutMode(1);
 XPRSsetcbcutmgr(prob.getXPRSprob(), cbNode, &prob);

 prob.setSense(XPRB_MAXIM);
 prob.mipOptimize();
   ...                // Solution output
} 
Related topics
Calls XPRBaddcuts

addMIPSol
Synopsis
int addMIPSol(XPRBsol& sol, const char *name);
int addMIPSol(XPRBsol& sol);
Arguments
sol 
A BCL solution.
name 
An optional name to associate with the solution. Can be NULL.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. If the matrix loaded in the Optimizer does not correspond to the current state of the specified problem definition, it is regenerated automatically before adding the solution.
2. The XPRBprob.mipOptimize method by default resets problem status including eventual loaded solutions; to avoid that, flag "c" should be specified for the alg argument of XPRBprob.mipOptimize when called after XPRBprob.addMIPSol.
3. The function returns immediately after passing the solution to the Optimizer. The solution is placed in a pool until the Optimizer is able to analyze the solution during a MIP solve.
4. If the provided solution is partial or found to be infeasible, a limited local search heuristic will be run in an attempt to find a close feasible integer solution. Values provided for continuous columns in partial solutions are currently ignored.
5. The usersolnotify callback can be used to discover the outcome of a loaded solution. The optional name provided as name will be returned in the callback.
Example
Add a MIP solution for problem prob to the Optimizer.
XPRBprob prob("myprob");
XPRBsol sol = prob.newSol();
  ...        // Define + load the problem
prob.addMIPsol(sol, "myHeurSol");
/* Request notification of solution status after processing */
XPRSaddcbusersolnotify(prob.getXPRSprob(), solnotify_handler, &prob, 0);
Related topics

beginCB
Synopsis
int beginCB(XPRSprob oprob);
Argument
oprob 
Reference to an Xpress Optimizer problem.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function switches from the original problem to the specified (local) optimizer problem for all BCL accesses to Xpress Optimizer (in particular, for solution updates and the definition of cuts). A call to this function must precede any call to such BCL functions in optimizer MIP callbacks when the default multi-threaded MIP search is used for solving a problem. A call to XPRBprob.beginCB must always be matched by a call to XPRBprob.endCB to reset the optimizer problem within BCL and to release the BCL problem (access to the BCL problem is locked to the particular thread in between the two function calls).
Example
The example shows how to set up the integer solution callback of Xpress Optimizer to use BCL to display the results.
void XPRS_CC printSol(XPRSprob oprob, void *my_object)
{
 int num;
 XPRBprob *bprob = (XPRBprob*)bp;
 XPRBvar x;

 XPRSgetintattrib(oprob, XPRS_MIPSOLS, &num);
                         // Get number of the solution
 bprob->beginCB(oprob);  // Work with local optimizer problem
 bprob->sync(XPRB_XPRS_SOL);   // Update BCL solution values

 cout << "Solution " << num << ": Objective value: ";
 cout << bprob->getObjVal() << endl;
 x = bcl_prob->getVarByName("x_1");
 cout << x.getName() << ": " << x.getSol() << endl;

 bprob->endCB();         // Reset BCL to orig. optimizer problem
}

int main(int argc, char **argv)
{
 XPRBprob prob("myprob");
   ...                // Define the problem
 XPRSsetcbintsol(prob.getXPRSprob(), printSol, &prob);
 prob.setSense(XPRB_MAXIM);
 prob.mipOptimize();
} 
Related topics
Calls XPRBbegincb

clearDir
Synopsis
void clearDir();
Description
This method deletes all directives on decision variables and SOS defined for a problem.
Example
This example defines directives for a binary variable and a SOS, writes out the directives to the file directout.dir and then deletes all directives.
XPRBvar b;
XPRBsos SO2;
XPRBprob prob("myprob");
b = prob.newVar("b", XPRB_BV);

b.setDir(XPRB_UP);         // Branch upwards first
SO2.setDir(XPRB_PR, 1);    // Highest branching priority
prob.writeDir("directout");
prob.clearDir();
Related topics
Calls XPRBcleardir

delCtr
Synopsis
void delCtr(XPRBctr& ctr);
Argument
ctr 
A BCL constraint.
Description
Delete a constraint from the given problem. If this constraint has previously been selected as the objective function (using function XPRBprob.setObj), the objective will be set to NULL. If the constraint occurs in a previously saved basis that is to be (re)loaded later on you should change its type to XPRB_N using XPRBctr.setType instead of entirely deleting the constraint.
Related topics
Calls XPRBdelctr

delCut
Synopsis
void delCut(XPRBcut& cut);
Argument
cut 
A BCL cut.
Description
This method deletes the definition of a cut in BCL, but not the cut itself if it has already been added to the problem held in Xpress Optimizer (using XPRBprob.addCuts).
Example
Related topics
Calls XPRBdelcut

delSos
Synopsis
void delSos(XPRBsos& sos);
Argument
sos 
A previously defined SOS of type 1 or 2.
Description
This method deletes a SOS without deleting the variables it consists of.
Example
Related topics
Calls XPRBdelsos

endCB
Synopsis
int endCB();
Return value
0 if method executed successfully, 1 otherwise.
Description
This function switches back to the original optimizer problem for all BCL accesses to Xpress Optimizer. A call to this function terminates a block of calls to BCL functions in an optimizer callback that is preceded by XPRBprob.beginCB. The call to XPRBprob.endCB releases the BCL problem (access to the BCL problem is locked to the particular thread between the two function calls).
Example
Related topics
Calls XPRBendcb

exportProb
Synopsis
int exportProb(int format, const char *filename);
int exportProb(int format);
Arguments
format 
The matrix output file format, which must be one of:
XPRB_LP 
LP file format (default);
XPRB_MPS 
MPS file format.
filename 
Name of the output file, without extension.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method prints the matrix to a file with an extended LP or extended MPS format. LP files receive the extension .lp and MPS files receive the extension .mps.
2. When exporting matrices semi-continuous and semi-continuous integer variables are preprocessed: if a lower bound value greater than 0 is given, then the variable is treated like a continuous (resp. integer) variable.
3. The precision used by BCL for printing real numbers can be changed with XPRB.setRealFmt to obtain more accurate output for very large or very small numbers. For full precision matrix output the user is advised to switch to the Optimizer function XPRSwriteprob, preceded by a call to XPRBprob.loadMat (see Appendix Using BCL with the Optimizer library for further detail).
Example
The following sets the sense of the optimization to maximization before exporting the problem matrix in LP format.
XPRBprob prob("myprob");
prob.setSense(XPRB_MAXIM);
prob.exportProb(XPRB_LP);
Related topics

fixMIPEntities
Synopsis
int fixMIPEntities(int ifround = 1);
Argument
ifround 
If all MIP entities should be rounded to the nearest discrete value in the solution before being fixed.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This is useful e.g. for finding the reduced costs for the continuous variables after the discrete variables have been fixed to their optimal values. The discrete variables are fixed to the value of the MIP solution only in the Optimizer (not in BCL).
2. In order to eventually resync the bounds of discrete variables to their original values defined in BCL (i.e. unfix them), a call to XPRBsync with the flag XPRB_XPRS_PROB can be used.
Example
Performs a branch and bound tree search on problem expl2 and then uses XPRBfixmipentities before solving the remaining linear problem:
XPRBprob prob("myprob");
  ...        // Define + load the problem
prob.mipOptimize();
prob.fixMIPEntities();
prob.lpOptimize();
Related topics

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

getCtrByName
Synopsis
XPRBctr getCtrByName(const char *name);
Argument
name 
The name of the constraint to find.
Return value
A BCL constraint.
Description
This method always returns a BCL constraint the validity of which needs to be checked with XPRBctr.isValid. This method cannot be used if the names dictionary has been disabled (see XPRBprob.setDictionarySize).
Example
The following retrieves a constraint by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBctr C2;

C2 = prob.getCtrByName("C2");
if (C2.isValid())  C2.print(); 
Related topics

getIndexSetByName
Synopsis
XPRBindexSet getIndexSetByName(const char *name);
Argument
name 
The name of the index set to find.
Return value
A BCL index set.
Description
This method always returns a BCL index set the validity of which needs to be checked with XPRBindexSet.isValid. This method cannot be used if the names dictionary has been disabled (see XPRBprob.setDictionarySize).
Example
The following retrieves an index by its name and if a set has been found prints it out.
XPRBprob prob("myprob");
XPRBindexSet I2;

I2 = prob.getIndexSetByName("IS");
if (I2.isValid())  I2.print(); 
Related topics

getLPStat
Synopsis
int getLPStat();
Return value
the problem has not been loaded, or error;
XPRB_LP_OPTIMAL 
LP optimal;
XPRB_LP_INFEAS 
LP infeasible;
XPRB_LP_CUTOFF 
the objective value is worse than the cutoff;
XPRB_LP_UNFINISHED 
LP unfinished;
XPRB_LP_UNBOUNDED 
LP unbounded;
XPRB_LP_CUTOFF_IN_DUAL 
LP cutoff in dual.
XPRB_LP_UNSOLVED 
LP problem is not solved.
XPRB_LP_NONCONVEX 
QP problem is nonconvex.
Description
The return value of this method provides LP status information from the Xpress Optimizer.
Example
Related topics

getMIPStat
Synopsis
int getMIPStat();
Return value
XPRB_MIP_NOT_LOADED 
problem has not been loaded, or error;
XPRB_MIP_LP_NOT_OPTIMAL 
LP has not been optimized;
XPRB_MIP_LP_OPTIMAL 
LP has been optimized;
XPRB_MIP_NO_SOL_FOUND 
tree search incomplete — no integer solution found;
XPRB_MIP_SOLUTION 
tree search incomplete, although an integer solution has been found;
XPRB_MIP_INFEAS 
tree search complete, but no integer solution found;
XPRB_MIP_OPTIMAL 
tree search complete and an integer solution has been found.
XPRB_MIP_UNBOUNDED 
LP unbounded;
Description
This methods returns the MIP status information from the Xpress Optimizer.
Example
Related topics

getName
Synopsis
const char *getName();
Return value
Name of the problem if function executed successfully, NULL otherwise.
Description
This method returns the problem name. If none was specified at the creation of the problem, this is a unique name created by BCL.
Related topics

getNumIIS
Synopsis
int getNumIIS();
Return value
Number of independent IIS found by Xpress Optimizer, or a negative value in case of error.
Description
This function returns the number of independent IIS (irreducible infeasible sets) of an infeasible LP problem.
Related topics

getObjVal
Synopsis
double getObjVal();
Return value
The current objective function value; default and error return value: 0.
Description
This method returns the current objective function value from the Xpress Optimizer. If it is called after completion of a branch and bound tree search and an integer solution has been found (that is, if XPRBprob.getMIPStat returns values XPRB_MIP_SOLUTION or XPRB_MIP_OPTIMAL), it returns the value of the best integer solution. In all other cases, including during a branch and bound tree search, it returns the solution value of 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

getProbStat
Synopsis
int getProbStat();
Return value
Bit-encoded BCL status information:
XPRB_GEN 
the matrix has been generated;
XPRB_DIR 
directives have been added;
XPRB_MOD 
the problem has been modified;
XPRB_SOL 
the problem has been solved.
Description
This method returns the current BCL problem status. Note that the problem status uses bit-encoding contrary to the LP and MIP status information, because several states may apply at the same time.
Example
Related topics

getSense
Synopsis
int getSense();
Return value
XPRB_MAXIM 
the objective function is to be maximized;
XPRB_MINIM 
the objective function is to be minimized;
-1 
an error has occurred.
Description
This method returns the objective sense (maximization or minimization). The sense is set to minimization by default and may be changed with XPRBprob.setSense, XPRBprob.lpOptimize, and XPRBprob.mipOptimize.
Related topics
Calls XPRBgetsense

getSosByName
Synopsis
XPRBsos getSosByName(const char *name);
Argument
name 
The name of the SOS to find.
Return value
A BCL SOS.
Description
This method always returns a BCL SOS the validity of which needs to be checked with XPRBsos.isValid. This method cannot be used if the names dictionary has been disabled (see XPRBprob.setDictionarySize).
Example
The following retrieves a SOS by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBsos S2;

S2 = prob.getSosByName("SO2");
if (S2.isValid())  S2.print();
Related topics

getVarByName
Synopsis
XPRBvar getVarByName(const char *name);
Argument
name 
The name of the variable to find.
Return value
A BCL variable.
Description
This method always returns a BCL variable the validity of which needs to be checked with XPRBvar.isValid. This method cannot be used if the names dictionary has been disabled (see XPRBprob.setDictionarySize).
Example
The following retrieves a variable by its name and if it has been found prints it out.
XPRBprob prob("myprob");
XPRBvar b2;

b2 = prob.getVarByName("b");
if (b2.isValid())
{ b2.print(); cout << endl; } 
Related topics

getXPRSprob
Synopsis
XPRSprob getXPRSprob();
Return value
Reference to a problem in Xpress Optimizer if executed successfully, NULL otherwise
Description
This method returns an XPRSprob problem reference for a problem defined in BCL and subsequently loaded into the Xpress Optimizer. The optimizer problem may be different from the problem loaded in BCL if the solution algorithms have not been called (and the problem has not been loaded explicitly) after the last modifications to the problem in BCL, or if any modifications have been carried out directly on the problem in the optimizer. See Section Using the Optimizer with BCL C++ for further detail.
Example
The following example shows how to change the setting of a control parameter of Xpress Optimizer.
XPRBprob bclProb("myprob");
XPRSprob optProb;
...   // Define the BCL problem
if ((prob.getProbStat()&XPRB_MOD) == XPRB_MOD)  prob.loadMat();
optProb = bclProb.getXPRSprob();
XPRSsetintcontrol(optProb, XPRS_PRESOLVE, 0); 
Related topics

loadBasis
Synopsis
int loadBasis(const XPRBbasis& bas);
Argument
bas 
A previously saved basis.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method loads a basis for the current problem. The basis must have been saved using XPRBprob.saveBasis. It is not possible to load a basis saved for any other problem than the current one, even if the problems are similar. This function takes into account that the problem may have been modified since the basis has been stored (addition of variables and constraints is handled—deletion of constraints is not handled: instead of entirely deleting a constraint, change its type to XPRB_N using XPRBctr.setType if you wish to load the basis later on). For reading a basis from a file, the Optimizer library function XPRSreadbasis may be used. Note that the problem has to be loaded explicitly (method XPRBprob.loadMat) before the basis is re-input with XPRBprob.loadBasis. Furthermore, if the reference to a basis is not used any more it should be deleted using XPRBbasis.reset.
Example
Related topics

loadMat
Synopsis
int loadMat();
Return value
0 if method executed successfully, 1 otherwise.
Description
This method calls the Optimizer library functions XPRSloadlp, XPRSloadqp, XPRSloadmip, or XPRSloadmiqp to transform the current BCL problem definition into a matrix in the Xpress Optimizer. Empty rows and columns are deleted before generating the matrix. Semi-continuous (integer) variables are preprocessed: if a lower bound value greater than 0 is given, then the variable is treated like a continuous (resp. integer) variable. Variables that belong to the problem but do not appear in the matrix receive negative column numbers. Usually, it is not necessary to call this function explicitly because BCL automatically does this conversion whenever it is required. To force matrix reloading, a call to this function needs to be preceded by a call to XPRBprob.sync with the flag XPRB_XPRS_PROB.
Example
Related topics
Calls XPRBloadmat

loadMIPSol
Synopsis
int loadMIPSol(double *sol, int ncol, bool ifopt);
int loadMIPSol(double *sol, int ncol);
Arguments
sol 
Array of size ncol holding the solution values.
ncol 
Number of variables (continuous+discrete) in the problem.
ifopt 
Whether to load the solution into the Optimizer:
false 
load into BCL only (default);
true 
load solution into the Optimizer.
Return value
Solution accepted,
Solution rejected because it is infeasible,
Solution rejected because it is cut off,
Solution rejected because the LP reoptimization was interrupted,
-1 
Solution rejected because an error occurred,
-2 
The given solution array does not have the expected size,
-3 
Error loading solution into BCL.
Description
1. This method loads a MIP solution from an external source ( e.g., the Xpress MIP Solution Pool) into BCL or the Optimizer. The solution is given in the form of an array, indexed by the column numbers of the decision variables. The size ncol of the array must correspond to the number of columns in the matrix (generated by a call to XPRBprob.loadMat or by starting an optimization run from BCL). If the solution is loaded into BCL the values are accepted as is, if the solution is loaded into the Optimizer ( ifopt = true), the Optimizer will check whether the solution is acceptable and recalculates the values for the continuous variables in the solution. In the latter case the solution is loaded into BCL only once it has been successfully loaded and validated by the Optimizer.
2. If the matrix loaded in the Optimizer does not correspond to the current state of the specified problem definition, it is regenerated automatically before loading the solution.
Example
Load a MIP solution for problem prob into BCL, but not into the Optimizer. We know that the problem has 5 variables.
XPRBprob prob("myprob");
double vals[] = {1.5, 1, 0, 4, 2.2};
  ...        // Define + load the problem
if (prob.loadMIPSol(vals, 5)!=0)
 cout << "Loading the solution failed." << endl; 
Related topics

lpOptimize
Synopsis
int lpOptimize(const char *alg);
int lpOptimize();
Argument
alg 
Choice of the solution algorithm and options, as a string of flags. If no flag is specified, solve the problem using the default LP/QP algorithm; otherwise, if the argument includes:
"d" 
solve the problem using the dual simplex algorithm;
"p" 
solve the problem using the primal simplex algorithm;
"b" 
solve the problem using the Newton barrier algorithm;
"n" 
use the network solver (LP only);
"c" 
continue a previously interrupted optimization run.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method selects and starts the Xpress Optimizer LP/QP solution algorithm. The characters indicating the algorithm choice may be combined where it makes sense, e.g. " pn. If the matrix loaded in the Optimizer does not correspond to the current state of the specified problem definition it is regenerated automatically prior to the start of the algorithm. Matrix reloading can also be forced by calling XPRBprob.sync before the optimization. The sense of the optimization (default: minimization) can be changed with function XPRBprob.setSense. Before solving a problem, the objective function must be selected with XPRBprob.setObj.
Example
Related topics

mipOptimize
Synopsis
int mipOptimize(const char *alg);
int mipOptimize();
Argument
alg 
Choice of the solution algorithm and options, as a string of flags. If no flag is specified, solve the problem using the default MIP/MIQP algorithm; otherwise, if the argument includes:
"d" 
solve the problem using the dual simplex algorithm;
"p" 
solve the problem using the primal simplex algorithm;
"b" 
solve the problem using the Newton barrier algorithm;
"n" 
use the network solver (for the initial LP);
"l" 
stop after solving the initial continuous relaxation (using MIP information in presolve);
"c" 
continue a previously interrupted optimization run.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method selects and starts the Xpress Optimizer MIP/MIQP solution algorithm. The characters indicating the algorithm choice may be combined where it makes sense, e.g. " pn. If the matrix loaded in the Optimizer does not correspond to the current state of the specified problem definition it is regenerated automatically prior to the start of the algorithm. Matrix reloading can also be forced by calling XPRBprob.sync before the optimization. The sense of the optimization (default: minimization) can be changed with function XPRBprob.setSense. Before solving a problem, the objective function must be selected with XPRBprob.setObj.
Example
The following example first maximizes the LP relaxation of a problem and then solves the problem as a MIP. After each optimization run the objective function value is displayed.
XPRBprob prob("myprob");
  ...        // Define the problem
prob.setSense(XPRB_MAXIM);
prob.lpOptimize();
if (prob.getLPStat() == XPRB_LP_OPTIMAL)
 cout << "LP solution: " << prob.getObjVal() << endl;
prob.mipOptimize();
if (prob.getMIPStat() == XPRB_MIP_OPTIMAL ||
    prob.getMIPStat() == XPRB_MIP_SOLUTION)
 cout << "MIP solution: " << prob.getObjVal() << endl; 
Related topics

nextCtr
Synopsis
bool nextCtr(XPRBctr& ref);
Argument
ref 
Reference constraint or NULL.
Return value
true if more constraints can be retrieved, false if the end of the enumeration has been reached.
Description
This method is used to enumerate the constraints of a problem. The argument ref serves to keep track of the current location in the enumeration; if this parameter is NULL, the first constraint is returned, otherwise the constraint that follows the reference constraint is returned.
Example
This code extract prints all constraints of the problem prob.
XPRBprob prob("myprob");
  ...        // Define + load the problem
XPRBctr iter = NULL;
while (prob.nextCtr(iter)) {
  iter.print();
}
Related topics

newCtr
Synopsis
XPRBctr newCtr(const char *name, XPRBrelation& ac);
XPRBctr newCtr(const char *name);
XPRBctr newCtr(XPRBrelation& ac);
XPRBctr newCtr();
Arguments
name 
The constraint name (of unlimited length). May be NULL if not required.
ac 
A linear or quadratic relation.
Return value
A new BCL constraint.
Description
This method creates a new constraint and returns the reference to this constraint, i.e., the constraint's model name. If the indicated name is already in use, BCL adds an index to it. If no constraint name is given, BCL generates a default name starting with CTR. (The generation of unique names will only take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.)
Example
These are a few examples of constraint creation.
XPRBvar x,y;
XPRBctr Ctr1, Ctr2, Ctr4, Profit;
XPRBexpr le;
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 >= 40);
Ctr2 = prob.newCtr("C2", 3*x*y + sqr(y) <= 500);
Profit = prob.newCtr("Profit", x+2*y);
prob.setObj(Profit);

le = x-5*y;
Ctr4 = prob.newCtr(le == 10);
Related topics
Calls XPRBnewctr

newCut
Synopsis
XPRBcut newCut(int id);
XPRBcut newCut(XPRBrelation& ac);
XPRBcut newCut(XPRBrelation& ac, int id);
XPRBcut newCut();
Arguments
ac 
A linear relation defining the cut (default: equality constraint).
id 
Cut classification or identification number (default 0).
Return value
A new BCL cut.
Description
This method creates a new cut. Cuts are loaded into the Optimizer by calling XPRBprob.addCuts from the Optimizer cutmanager callback.
Example
The following example shows different possibilities of how to define cuts.
XPRBprob prob("myprob");
XPRBvar y,b;
XPRBcut Cut1, Cut2, Cut3;

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

Cut1 = prob.newCut(y == 100*b);
Cut1.setID(1);

Cut2 = prob.newCut(y <= 100*b, 2);

Cut3 = prob.newCut(3);
Cut3.setType(XPRB_L);
Cut3.add(y+2);
prob.delCut(Cut3); 
Related topics
Calls XPRBnewcut

newIndexSet
Synopsis
XPRBindexSet newIndexSet();
XPRBindexSet newIndexSet(const char *name);
XPRBindexSet newIndexSet(const char *name, int maxsize);
Arguments
name 
Name of the index set to be created. May be NULL if not required.
maxsize 
Maximum size of the index set.
Return value
A new BCL index set.
Description
This method creates a new index set. Note that the indicated size maxsize corresponds to the space allocated initially to the set, but it is increased dynamically if need be. If the indicated set name is already in use, BCL adds an index to it. If no name is given, BCL generates a default name starting with IDX. (The generation of unique names will only take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.)
Example
The following example defines an index set of size 10 and then adds two elemnts to the set.
XPRBindexSet ISet;
XPRBprob prob("myprob");
int ind;

ISet = prob.newIndexSet("IS", 10);
ind = ISet.addElement("a"); ISet += "b";
Related topics

newSol
Synopsis
XPRBsol newSol();
Return value
A new BCL solution.
Description
This method creates a new solution.
Example
Related topics
Calls XPRBnewsol

newSos
Synopsis
XPRBsos newSos(int type);
XPRBsos newSos(const char *name, int type);
XPRBsos newSos(int type, XPRBexpr& le);
XPRBsos newSos(const char *name, int type, XPRBexpr& le);
Arguments
name 
The name of the set.
type 
The set type, which must be one of:
XPRB_S1 
Special Ordered Set of type 1 (default);
XPRB_S2 
Special Ordered Set of type 2.
le 
A linear expression.
Return value
A new BCL SOS.
Description
This method creates a Special Ordered Set (SOS) of type 1 or 2 (abbreviated SOS1 and SOS2). If the indicated name is already in use, BCL adds an index to it. If no name is given for the set, BCL generates a default name starting with SOS. (The generation of unique names will only take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.)
Example
The following example defines the SOS-1 SO1, prints is out (output displayed as comment) and then deletes it. After this it defines an SOS-2 named SO2.
XPRBvar x,y,z;
XPRBsos SO1, SO2;
XPRBprob prob("myprob");

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

SO1 = prob.newSos("SO1");
SO1.add(x+2*y+3*z);
SO1.print();             //  SO1(1): x(+1) y(+2) z(+3)
prob.delSos(SO1);

SO2 = prob.newSos("SO2", XPRB_S2, 10*x+20*y);
Related topics
Calls XPRBnewsos

newVar
Synopsis
XPRBvar newVar(const char *name, int type, double lob, double upb);
XPRBvar newVar(const char *name, int type);
XPRBvar newVar(const char *name);
XPRBvar newVar();
Arguments
name 
The variable name (of unlimited length). May be NULL if not required.
type 
The variable type, which may be one of:
XPRB_PL 
continuous (default);
XPRB_BV 
binary;
XPRB_UI 
general integer;
XPRB_PI 
partial integer;
XPRB_SC 
semi-continuous;
XPRB_SI 
semi-continuous integer.
lob 
The variable's lower bound (default value: 0)
upb 
The variable's upper bound (default value: XPRB_INFINITY)
Return value
A new BCL decision variable.
Description
1. The creation of a variable in BCL involves not only its name but also its type and bounds. The method returns the BCL reference to the variable ( i.e., a model variable). If the indicated name is already in use, BCL adds an index to it. If no variable name is given, BCL generates a default name starting with VAR. (The generation of unique names will only take place if the names dictionary is enabled, see XPRBprob.setDictionarySize.) If a partial integer, semi-continuous, or semi-continuous integer variable is being created, the integer or semi-continuous limit ( i.e. the lower bound of the continuous part for partial integer and semi-continuous, and of the semi-continuous integer part for semi-continuous integer) is set to the maximum of 1 and bdl. This value can be subsequently modified with the method XPRBvar.setLim.
2. The lower and upper bounds may take values of -XPRB_INFINITY and XPRB_INFINITY for minus and plus infinity respectively.
Example
This example shows how to define different types of variables.
XPRBvar x,b,s;
XPRBprob prob("myprob");

x = prob.newVar("x");        // Continuous with default bounds
b = prob.newVar("b", XPRB_BV);         // Binary variable
s = prob.newVar("s", XPRB_SC, 0, 50);  // Semi-cont. in [0,50]
s.setLim(10);                          // with limit value 10 
Related topics
Calls XPRBnewvar

print
Synopsis
int print();
Return value
0 if function executed successfully, 1 otherwise.
Description
Related topics

printObj
Synopsis
int printObj();
Return value
0 if function executed successfully, 1 otherwise.
Description
Related topics
Calls XPRBprintobj

readBinSol
Synopsis
int readBinSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If omitted, the extension .bin will be appended.
flags 
Flags to control solution import. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSreadbinsol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function reads a solution from a binary solution file (.sol), loading it into the Optimizer.
Example
This example the reads a solution from file example2.sol
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.readBinSol();
prob.mipOptimize(); 
Related topics

readSlxSol
Synopsis
int readSlxSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If omitted, the extension .slx will be appended.
flags 
Flags to control solution import. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSreadslxsol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function reads a solution from an ASCII solution file (.slx), loading it into the Optimizer.
Example
This example the reads a solution from file example2.slx
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.readSlxSol();
prob.mipOptimize(); 
Related topics

reset
Synopsis
int reset();
Return value
0 if method executed successfully, 1 otherwise.
Description
This method deletes any solution information stored in BCL; it also deletes the corresponding Xpress Optimizer problem and removes any auxiliary files that may have been created by optimization runs. It also resets the Optimizer control parameters for spare matrix elements ( EXTRACOLS, EXTRAROWS, and EXTRAELEMS) to their default values. The BCL problem definition itself remains. This method may be used to free up memory if the solution information is not required any longer but the problem definition is to be kept for later (re)use.
Related topics

saveBasis
Synopsis
XPRBbasis saveBasis();
Return value
A BCL basis.
Description
This method saves the current basis of a problem. The basis may be reinput using XPRBprob.loadBasis. These two methods serve for storing bases in memory; for writing a basis to a file, the Optimizer library function XPRSwritebasis may be used. Note that there is no need to allocate space for the basis, but after its use, the basis should be deleted using XPRBbasis.reset. You may have to switch linear presolve and integer preprocessing off (Optimizer library controls PRESOLVE and MIPPRESOLVE) in order for the saving and reloading of bases to work correctly.
Example
The following saves a basis and after some modifications to the problem reloads the problem and the saved basis into the Optimizer before re-solving the problem.
XPRBbasis bas;
XPRBprob prob("myprob");

bas = prob.saveBasis();
 ...              // Modify the problem
prob.loadMat();
prob.loadBasis(bas);
bas.reset();
prob.lpOptimize();
Related topics

setColOrder
Synopsis
int setColOrder(int num);
Argument
num 
The ordering flag, which must be one of:
default ordering;
alphabetical order.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. BCL runs reproduce always the same matrix for a problem. This method allows the user to choose a different ordering criterion than the default one. Note that this method only changes the order of columns in what is sent to Xpress Optimizer, you do not see any effect when exporting the matrix with BCL. However you can control the effect by exporting the matrix from the Optimizer.
2. To change this setting for all problems that are created subsequently use the corresponding method of class XPRB.
Related topics

setCutMode
Synopsis
int setCutMode(int mode);
Argument
mode 
Cut mode indicator:
switch cut mode off
switch cut mode on
Return value
0 if method executed successfully, 1 otherwise.
Description
This function switches the cut mode on or off. It changes the settings of certain Optimizer controls. Switching the cut mode off resets these controls to their default values.
Example
Related topics

setDictionarySize
Synopsis
int setDictionarySize(int dict, int size);
Arguments
dict 
Choice of the dictionary. Possible values:
XPRB_DICT_NAMES 
names dictionary
XPRB_DICT_IDX 
indices dictionary
size 
Non-negative value, preferrably a prime number; 0 disables the dictionary (for names dictionary only).
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This function sets the size of the hash table of the names or indices dictionaries (defaults: names 2999, indices 1009) of the given problem. It can only be called immediately after the creation of the corresponding problem.
2. The names dictionary serves for storing and accessing the names of all modeling objects (variables, arrays of variables, constraints, SOS, index sets). Once it has been disabled it cannot be enabled any more. All methods relative to the names cannot be used if this dictionary has been disabled and BCL will not generate any unique names at the creation of model objects. If this dictionary is enabled (default setting) BCL automatically resizes this dictionary to a suitable size for your problem. If nevertheless you wish to set the size by yourself we recommend to choose a value close to the number of variables+constraints in your problem.
3. The indices dictionary serves for storing all index set elements. The indices dictionary cannot be disabled, it is created automatically once an index set element is defined.
Related topics

setMsgLevel
Synopsis
int setMsgLevel(int lev);
Argument
level 
The message level, i.e. the type of messages printed by BCL. This may be one of:
no messages printed;
error messages only printed;
warnings and errors printed;
warnings, errors, and Optimizer log printed (default);
all messages printed.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. BCL can produce different types of messages; status information, warnings and errors. This function controls which of these are output. For settings 1 or higher, the corresponding Optimizer output is also displayed. In addition to this setting, the amount of Optimizer output can be modified through several Optimizer printing control parameters (see the `Xpress Optimizer Reference Manual').
2. To change this setting for all problems that are created subsequently use the corresponding method of class XPRB.
Example
The following example changes the global BCL message printing level to 'errors' only and sets the printing level for problem prob back to the default. It also modifies the values of the Optimizer printing controls for simplex and MIP logging.
XPRBprob prob("myprob");
XPRB::setMsgLevel(1);
prob.setMsgLevel(3);
XPRSsetintcontrol(prob.getXPRSprob(), XPRS_LPLOG, 0);
XPRSsetintcontrol(prob.getXPRSprob(), XPRS_MIPLOG, -500); 
Related topics

setObj
Synopsis
int setObj(XPRBctr ctr);
int setObj(XPRBexpr e);
int setObj(XPRBvar v);
Arguments
ctr 
A BCL constraint.
A linear or quadratic expression.
A BCL decision variable.
Return value
0 if method executed successfully, 1 otherwise.
Description
This functions sets the objective function by selecting a constraint the variable terms of which become the objective function. This must be done before any optimization task is carried out. Typically, the objective constraint will have the type XPRB_N (non-binding), but any other type of constraint may be chosen too. In the latter case, the equation or inequality expressed by the constraint also remains part of the problem.
Example
Related topics
Calls XPRBsetobj

setName
Synopsis
int setName(const char *name);
Argument
name 
A string of up to 1024 characters containing the new problem name.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method sets the problem name.
Related topics

setRealFmt
Synopsis
int setRealFmt(const char *fmt);
Argument
fmt 
Format string (as used by the C function printf). Simple format strings are of the form %n where n may be, for instance, one of
default printing format (precision: 6 digits; exponential notation if the exponent resulting from the conversion is less than -4 or greater than or equal to the precision)
.numf 
print real numbers in the style [-]d.d where the number of digits after the decimal point is equal to the given precision num.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. In problems with very large or very small numbers it may become necessary to change the printing format to obtain a more exact output. In particular, by changing the precision it is possible to reduce the difference between matrices loaded in memory into Xpress Optimizer and the output produced by exporting them to a file.
2. To change this setting for all problems that are created subsequently use the corresponding method of class XPRB.
Example
Related topics

setSense
Synopsis
int setSense(int dir);
Argument
dir 
Sense of the objective function, which must be one of:
XPRB_MAXIM 
maximize the objective;
XPRB_MINIM 
minimize the objective.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method sets the optimization sense to maximization or minimization. It is set to minimization by default.
Example
Related topics
Calls XPRBsetsense

sync
Synopsis
int sync(int synctype);
Argument
synctype 
Type of the synchronization. Possible values:
XPRB_XPRS_SOL 
update the BCL solution information with the LP solution currently held in the Optimizer;
XPRB_XPRS_SOLMIP 
update the BCL solution information with the last MIP solution found by the Optimizer;
XPRB_XPRS_PROB 
force problem reloading.
Return value
0 if method executed successfully, 1 otherwise.
Description
1. This method resets the BCL problem status.
2. XPRB_XPRS_SOL: retrieves the current LP solution (through XPRSgetlpsol function and XPRS_LPOBJVAL attribute); correctly used also in intsol callbacks as, when an integer solution is found during a branch and bound tree search, it is always set up as an LP solution to the current node.
3. XPRB_XPRS_SOLMIP: retrieves the last MIP solution found (through XPRSgetmipsol function and XPRS_MIPOBJVAL attribute); if used from an intsol callback, it will not necessarily return the solution that caused the invocation of the callback (it is possible that another thread finds a new integer solution before that one is retrieved).
4. XPRB_XPRS_SOL and XPRB_XPRS_SOLMIP: the solution information in BCL is updated with the solution held in the Optimizer at the next solution access (only the objective value is updated immediately).
5. XPRB_XPRS_PROB: at the next call to optimization or XPRBloadmat the problem is completely reloaded into the Optimizer; bound changes are not passed on to the problem loaded in the Optimizer any longer.
Example
The following forces BCL to reload the matrix into the Optimizer even if there has been no change other than bound changes to the problem definition in BCL since the preceding optimization / matrix loading.
XPRBprob prob("myprob");
  ...        // Define + load the problem
prob.sync(XPRB_XPRS_PROB);
prob.mipOptimize(); 
Related topics
Calls XPRBsync

writeDir
Synopsis
int writeDir();
int writeDir(const char *filename);
Argument
filename 
Name of the directives files.
Return value
0 if method executed successfully, 1 otherwise.
Description
This method writes out to a file the directives defined for a problem. If the given file name does not include an extension the extension .dir is appended to it. When no file name is given, the name of the problem is used. If a file of the given name exists already it is replaced.
Example
Related topics
Calls XPRBwritedir

writeSol
Synopsis
int writeSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If no file extension is specified, then extensions .hdr and .asc will be appended.
flags 
Flags to control output format. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSwritesol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function writes out, to a CSV format ASCII file, the current Optimizer solution. If no file extension is specified, then two files will be written with extensions .asc and .hdr appended to the given file name. When no file name is given, the name of the problem is used. If a file of the given name exists already it is replaced.
Example
This example the writes current solution to the file example2.asc (and .hdr).
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.mipOptimize();
prob.writeSol(); 
Related topics
Calls XPRBwritesol

writeBinSol
Synopsis
int writeBinSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If omitted, the extension .sol will be appended.
flags 
Flags to control output format. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSwritebinsol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function writes out, to a binary file, the current Optimizer solution. If no file extension is specified, then the extension .sol is appended to the given file name. When no file name is given, the name of the problem is used. If a file of the given name exists already it is replaced.
Example
This example the writes current solution to the file example2.sol.
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.mipOptimize();
prob.writeBinSol(); 
Related topics

writePrtSol
Synopsis
int writePrtSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If omitted, the extension .prt will be appended.
flags 
Flags to control output format. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSwriteprtsol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function writes out, to a fixed format ASCII file, the current Optimizer solution. If no file extension is specified, then the extension .prt is appended to the given file name. When no file name is given, the name of the problem is used. If a file of the given name exists already it is replaced.
Example
This example the writes current solution to the file example2.prt.
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.mipOptimize();
prob.writePrtSol(); 
Related topics

writeSlxSol
Synopsis
int writeSlxSol(const char *filename = NULL, const char *flags = "");
Arguments
fname 
Name of the solution file. May be NULL or the empty string if the problem name is to be used. If omitted, the extension .slx will be appended.
flags 
Flags to control output format. If no flags need to be specified, use either NULL or the empty string. Refer to function XPRSwriteslxsol in the `Xpress Optimizer Reference Manual' for details.
Return value
0 if method executed successfully, 1 otherwise.
Description
This function writes out, to an ASCII solution file (using a similar format to MPS files) the current Optimizer solution. If no file extension is specified, then the extension .slx is appended to the given file name. When no file name is given, the name of the problem is used. If a file of the given name exists already it is replaced.
Example
This example the writes current solution to the file example2.slx.
XPRBprob prob("example2");
  ...        // Define + load the problem
prob.mipOptimize();
prob.writeSlxSol(); 
Related topics


© 2001-2025 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.