Introduction

Topics covered in this chapter:

New object-oriented solver API

In Xpress 9.4 the Java and .NET APIs to the Xpress Solver were extended to allow the creation of an optimization problem in a more object-oriented fashion. In Xpress 9.5 the C++ API was extended in the same way. The new API is fully integrated with the low-level Xpress Solver API, including full support for nonlinear problems, and has been designed for high performance. The new API is a replacement for BCL, which will be deprecated in future Xpress releases.

For more information, see the Solver Java User Guide, the Solver .NET User Guide and the Solver C++ User Guide.

An overview of BCL

The FICO^® Xpress BCL Builder Component Library provides an environment in which the Xpress user may readily formulate and solve linear, mixed integer and quadratic programming models. Using BCL's extensive collection of functions, complicated models may be swiftly and simply constructed, preparing problems for optimization. Not merely limited to specific model construction, however, BCL's flexibility makes it the ideal engine for embedding in custom applications for the construction of generic modeling software. In combination with the FICO^® Xpress Optimizer, the two form a powerful combination.

Model formulation using Xpress BCL is constraint-oriented. Such constraints may be built up either coefficient-wise, incrementally adding linear or quadratic terms until the constraint is complete, or through use of arrays of variables, constructing the constraint through a scalar product of variable and coefficient arrays. The former method allows for easier modification of models once constructed, whilst the latter enables swifter construction of new constraints.

BCL supports the full range of variable types available to users of the Xpress Optimizer: continuous, semi-continuous, binary, semi-continuous integer, general and partial integer variables, as well as Special Ordered Sets of types 1 and 2 (SOS1 and SOS2). With additional functions for specifying directives to aid the branch and bound tree search, BCL enables preparation of every aspect of complicated (mixed) integer programming problems.

To complement the model construction routines, BCL supports a number of functions which allow a completed model to be passed directly to the Xpress Optimizer, solved by the optimizer, and solution information reported back directly from BCL. For situations where the BCL solution functions do not provide enough capability to handle a particular user's requirements, problems may be manipulated using the Xpress Optimizer library functions. Such close interactivity between BCL and the Xpress Optimizer make these two libraries a perfect partnership.

BCL also supports a number of functions allowing easy input and output of model and solution data. In addition to a set of useful print functions, other functions also enable the export of constructed models as matrix files in a number of industry standard formats.

Note for Optimizer library users

BCL functions cover all aspects of modeling, and perform simple optimization tasks without making reference to the problem representation (matrix) used by the underlying solution algorithms. The more advanced Optimizer library user may nevertheless wish to access the problem matrix directly. It is possible to use all Optimizer library functions with the matrix generated by BCL. To this end, BCL provides several functions which specifically relate to the matrix representation.

The function XPRBloadmat explicitly transforms the constraint-wise representation in BCL into the matrix representation required by the Optimizer library. It is usually not necessary to call this function because BCL automatically carries out this transformation whenever required.

The functions XPRBgetcolnum and XPRBgetrownum return the column and row indices associated with BCL variables and constraints respectively. While loading the matrix with a call to XPRBloadmat, all variables that do not occur in any constraint and all empty constraints are ignored and variable and constraint indices are updated correspondingly (with negative indices indicating that a variable or constraint is not part of the active matrix in the Optimizer).

It should be stressed that BCL, and thus the arrays storing references to problem variables, does not keep track of any changes to the matrix occurring during the solution procedure within the Optimizer. This implies that if linear presolve or integer preprocessing is used, the correct solution information is available only after the postsolve has been carried out. This is usually done automatically if the solution algorithm terminates correctly (see the description of XPRBlpoptimize and XPRBmipoptimize in Chapter BCL C library functions for details).

If the matrix is altered directly with Optimizer library functions such as XPRSaddrows or XPRSchgcoef it is not possible to retrieve the modifications in the BCL model. In order to maintain a coherent status, any such modification has to be carried out in BCL, followed by a call to function XPRBloadmat.

Appendix Using BCL with the Optimizer library explains in more detail how to use Optimizer library functions within a BCL program. Interested users are directed there for details

Structure of this manual

The main body of the manual is essentially organized into two parts. It begins in Chapter Modeling with BCL, with a brief overview of common BCL functions and their usage, covering model management, construction, solution and the output of information following optimization. These ideas are extended in Chapter Further modeling topics, to cover some of the more advanced or less well-known features of the library. The use of index sets, special ordered sets, quadratic programming and user error handling are all covered here.

Following the first two chapters, the remainder forms the main reference section of the manual. Chapter BCL C library functions details all functions in the library alphabetically, enabling swift access to information about function syntax and usage, accompanied by examples. This is followed in Chapters BCL in C++, BCL in Java, and BCL in .NET by a documentation of the C++ interface and summary descriptions of the Java and .NET interfaces. A list of BCL error and return codes and an overview of usage of BCL with the Xpress Optimizer library form the Appendices to the manual.

Please note that the full documentation of the Java and .NET interfaces is provided seperately, see subdirectories docs/bcl/dhtml/javadoc and docs/bcl/bcl.net/HTML of the Xpress installation directory.

Conventions used

Throughout the manual standard typographic conventions have been used, representing computer code fragments with a fixed width font, whilst equations and equation variables appear in italic type. Where several possibilities exist for the library functions, those with C syntax have been used, and C style conventions have been used for structures such as arrays etc. Where appropriate, the following have also been employed:

• square brackets [...] contain optional material;
• curly brackets {...} contain optional material, of which one must be chosen;
• entities in italics which appear in expressions stand for meta-variables. The description following the meta-variable describes how it is to be used;
• the vertical bar symbol | is found on many keyboards as a vertical line with a small gap in the middle, but often confusingly displays on screen without the small gap in the middle. In UNIX it is referred to as the pipe symbol. Note that this symbol is not the same as the character sometimes used to draw boxes on a PC screen. In ASCII, the | symbol is 7C in hexadecimal, 124 decimal.