Getting started with the C++ API

Topics covered in this chapter:

Instantiating the XpressProblem class

While all low-level APIs to the Xpress Solver describe the problem in terms of a matrix using row and column indices, the XpressProblem provides a more abstract view on the problem by using variable and constraint objects.

In order to create an object-oriented problem you need an instance of the XpressProblem class. The constructor of that class takes zero, one, or two strings. The first string is the name to be assigned to the problem, the second string points to your license file. Either string may be std::nullopt or may be omitted. If your license can be found without explicit license file information (for example because it is in a default location) then you can omit the license argument to the constructor.

An instance of XpressProblem wraps native resources, so it is good practice to release these resources as soon as the object is no longer needed, for example:

XpressProblem prob; // Releases resources when it goes out of scope

Creating variables

The first step in stating an optimization problem is creating the required decision variables. Variables are created following the "builder pattern". This pattern starts with calling the addVariables() function. This function returns a builder that can be modified (see below) and can be turned into an array or a map of variables using its toArray() or toMap() functions, respectively.

For example:

prob.addVariables(5).toArray();

creates an array of five variables, where all variables have default properties (lower bound zero, upper bound infinity, no name, continuous).

Similarly,

prob.addVariables(std::vector<std::string>{ "a", "b" }).toMap();

creates a map with two variables. The keys in this map are the two strings "a" and "b" (passed as first argument to the function) and the values in the map are the variables that were created for the strings. Again, these variables have all properties at default values.

Builders can be modified before calling toArray() or toMap(). For this purpose, builders provide a number of with functions. For example, function withLB changes the lower bound of all the variables the builder will create after this function was called:

prob.addVariables(5).withLB(1).toArray();

The statment above again creates five variables, but this time all the variables have a lower bound of 1.

Properties cannot only be changed to a constant value. They can also be changed to value that depends on the variable being created. Consider

prob.addVariables(5).withLB([](auto i){ return i;}).toArray();

This creates five variables. The first variable has a lower bound of 0. The second variable has a lower bound of 1. The third has a lower bound of 2 and so on. What happens here is that the function passed to withLB is invoked for every variable created in order to generate the lower for this particular variable.

Similarly, consider

prob.addVariables(std::vector<std::string>{ "a", "b" })
    .withName([](auto s){ return "x"+s; })
    .toMap();

This creates the same map of variables as before, but this time the variables get names. The names are constructed from the strings that were passed to the function. These strings are passed as parameter s to the function that was registered with withName.

The functions to modify a variable builder are the following

withLB

to specify the lower bound, the default is zero

withUB

to specify the upper bound, the default is infinity

withName

to specify the name, the default is no name

withType

to specify the variable type (continuous, integer, binary, ...), the default type is continuous

withLimit

to specify the limit for semi-continuous, semi-integer or partial integer variables, the default is zero

For example, to create an array of 5 integer variables with lower bound 1, upper bound 2, and names "x1", "x2", ... use

std::vector<Variable> x = prob.addVariables(5)
                   .withLB(1)
                   .withUB(2)
                   .withType(xpress::ColumnType::Integer)
                   .withName([](auto i){ return xpress::format("x%d", i+1); })
                   .toArray();

The addVariables() functions are also overloaded to create multi-dimensional arrays or maps of variables. In order to do that, instead of passing a single dimension count or collection, pass as many counts or collections as there are dimensions:

auto x = prob.addVariables(2, 3, 4)
                     .withName("x[%d][%d][%d]")
                     .toArray();
std::vector<Type1> c1 = ...;  // Or any other iterable container type
std::list<Type2> c2 = ...;    // Or any other iterable container type
std::vector<Type3> c3 = ...;  // Or any other iterable container type
HashMap3<Type1,Type2,Type3,Variable> x = prob.addVariables(c1, c2, c3)
                                             .withName("x[%s][%s][%s]")
                                             .toMap();

Using function addVariable() it is also posible to create a single variable. This function does not follow the builder pattern but instead takes all the variable properties as arguments:

// Unnamed continuous variable in [0,infinity)
x = prob.addVariable();
// Integer variable in [2,3] with the name "x"
x = prob.addVariable(2, 3, ColumnType::Integer, "x"); 

There are more overloads for addVariable(), please refer to the reference documentation for further details.

Note that variables are specific to a problem. In other words, an instance of Variable can be used only with the XpressProblem instance that created it. If you use a variable with a problem that did not create it then this will raise an exception.

Creating constraints

Once you have created some Variable objects, you can start creating constraints on them. The most basic kind of constraints are inequality constraints. They represent constraints of one of the following types:

expression1 <= expression2
expression1 >= expression2
expression1 == expression2
expression1 in [lb,ub]

Here expression1 is called the left-hand side (frequently referred to as "lhs") and expression" is called the right-hand side (frequently referred to as "rhs"). The operator between the two expressions is called the "sense" of the constraint. The last constraint above is called a range constraint and requires expression1 to be between lb and ub. Note that there are no "not equal" or strict inequality operators since these are not supported by the theory of mathematical programming on which Xpress is built. Strictily speaking, "==" and "in" are not inequalities, but in this document and in the programming API we still call those an inequality.

Examples of expressions are

\[ x_1 + 2x_3 \qquad\qquad x_1^2 + x_2 + 4\qquad\qquad \sin(x_1) \]

The first type of expression is called a "linear" expression (it only involves linear terms), the second one is called a "quadratic" expression (it involves linear and quadratic terms), the third one is called a "nonlinear" expression (it involves terms that are neither linear nor quadratic).

In order to create an inequality constraint, you first need an expression, so we start by explaining how to create a linear expression.

Creating linear expressions

There are several ways to construct a linear expression:

Use an instance of class Variable.

The Variable class extends the Expression class, so it can be used whenever an expression is required.

Multiply a variable by a constant.

Class Variable provides member function mul() that returns a linear term representing a multiplication of the variable with the given constant.

Construct an expression using scalarProduct().

The scalarProduct() function constructs a linear expression by elementwise multiplying a vector of variables by a vector of numbers.

Construct an expression using sum().

The sum() function takes arbitrary expressions and sums them up to build a new expression.

Construct an expression by accumulating terms in a LinExpression.

The (abstract) LinExpression class provides member functions addTerm() and setConstant() or addConstant() to build up an expression piecemeal. An empty linear expression can be constructed using the static LinExpression::create() function.

There also is a ConstantExpression class and a static member function constant() that can be used to represent expressions that only have a constant term.

Examples:

vector<Variable> x = ...;
Expression t = x[0].mul(1.5);                         // 1.5*x[0]
Expression p = scalarProduct(x, vector<double>{2,3}); // 2.0*x[0] + 3.0*x[1]
Expression s = sum(t, p);                             // 3.5*x[0] + 3.0*x[1]
LinExpression e = LinExpression.create();
e.addTerm(x[0], 1.5);                                 // 1.5*x[0]
e.addTerm(x[1], 2.5);                                 // 1.5*x[0] + 2.5*x[1]
e.setConstant(3.0);                                   // 1.5*x[0] + 2.5*x[1] + 3.0
constant(5);                                          // 5.0

The API also overloads operators +, -, *, / to make it even easier to create expressions:

e = 3.5 * x[0] + 2.5 * x[1];

Note that LinExpression is an abstract class for which two implementations exist: LinTermMap and LinTermList. LinExpression::create() will create an instance of LinTermMap which is the most versatile implementation but not necessarily the most efficient one. The next two paragraphs explain the difference between the two implementations.

The first implementation is class LinTermMap. As the name suggests, this implementation is backed up by a map: internally the expression is represented as a map that maps variables to their respective coefficients. This implementation is very flexible and allows for all kind of modifications of the expression, in particular it allows directly setting coefficients for variables by means of the setCoefficient() function. On the downside, accessing coefficients incurs some runtime overhead.

The second implementation is class LinTermList. This keeps all coefficients in a simple list. Consequently, you cannot query coeffcients and can also not explicitly set coefficients for certain variables. Another problem is that duplicate terms (multiple terms for the same variable) require explicit handling. The upside is that this implementation is more efficient. When using this class, make sure you understand the implications and assumptions that this class makes. These are stated in the reference documentation.

As a rule of thumb, the LinTermMap implementation should be used, unless it turns out to be prohibitively expensive with respect to performance of building expressions.

Creating constraints from expressions

Once you have created expressions, you can start building constraints from them. For this purpose, the Expression class provides member functions leq, geq, eq that create a less-than-or-equal, greater-than-or-equal, or equal-to constraint respectively. These functions produce a constraint definition than can then be added to a problem using the addConstraint() function.

For example:

Expression lhs = sum(x[1], x[2].mul(2.0));
prob.addConstraint(lhs.leq(4.0));  // Adds constraint x[1] + 2 * x[2] <= 4

The API overloads operators "<=", ">=" and "==" so that you can write the above code as

prob.addConstraint(x[1] + 2 * x[2] <= 4);  // Adds constraint x[1] + 2 * x[2] <= 4

In addition to inequality constraints, you can also create ranged constraints that bound an expression from below and above. This is done using the in() member function of the Expression class:

Expression expr = ...;
prob.addConstraint(expr.in(2, 5)); // Add constraint 2 <= expr <= 5

Creating quadratic expressions

Quadratic expressions are created in similar ways as linear expressions.

Starting from a variable.

Starting from a Variable instance, a quadratic expression can be built using the mul function: x.mul(y).mul(3) creates the quadratic term 3*x*y.

Using function scalarProduct.

QuadExpression::scalarProduct() is for quadratic expressions what LinExpression::scalarProduct() is for linear expressions. This function multiplies three vectors element by element to create a new quadratic expression.

Using the QuadExpression class directly.

Using QuadExpression::create() an empty instance of QuadExpression can be created. This instance can then be modified using addTerm(), setConstant() and addConstant().

Examples:

Variable[2] x = ...;
Expression t = x[0].mul(x[1]).mul(1.5);                // 1.5*x[0]*x[1]
Expression p = scalarProduct(x, y, new double[]{2,3}); // 2.0*x[0]*y[0]+3.0*x[1]*y[1]
QuadExpression e = QuadExpression.create();
e.addTerm(x[0], x[1], 1.5);                            // 1.5*x[0]*x[1]
e.addTerm(x[1], 2.5);                                  // 1.5*x[0]*x[1]+2.5*x[1]
e.setConstant(3.0);                                    // 1.5*x[0]*x[1]+2.5*x[1]+3.0

There also is some limited operator overloading. So for variables x and y and a quadratic expression q you can create quadratic terms like this:

Expression term = x * x * 3.5;
q.addTerm(2.5 * x);
q.addTerm(3.5 * x * y);
prob.addConstraint(3.5 * x * y <= 3);

Creating nonlinear expressions

Nonlinear expressions are represented by expression trees. Each node in such a tree is an instance of class FormulaExpression (or a subclass of it). The full expression is represented by the root node of that tree.

In order to create an expression tree you can either create the nodes directly using their constructor or you can use the static utility functions provided by class FormulaExpression:

using xpress::objects::utils::cos;
using xpress::objects::utils::sin;

Variable x = ...;
Expression nonLinear = sin(cos(x));

The classes that implement nodes in an expression tree can be found in xpress::objects and are

BinaryExpression

represents binary operations, such as addition, subtraction, exponentiation, etc.

UnaryExpression

represents unary operations such as unary minus (negation)

ColumnReferenceExpression

represents a reference to a column/variable

InternalFunctionExpression

represents a call to an elementary mathematical function

UserFunctionExpression

represents a call to a user function. Note that instances of this class can also be created by calling funcion call() on the corresponding user function object (see AbstractUserFunction).

Once a nonlinear expression is created, it can be used like any other expression to build a constraint:

prob.addConstraint(sin(x).leq(cos(x)));       // sin(x) <= cos(x)
prob.addConstraint(min(x, y).leq(pow(a, b))); // min(x,y) <= a^b

The arguments to nonlinear expressions can be instances of any class in xpress::objects that extends the Expression class. In particular, they can be instances of LinExpression, QuadExpression, Variable etc. While this is very flexible, it is still recommended that you use LinExpression, QuadExpression or functions sum(), scalarProduct to create linear or quadratic expressions. This is usually more efficient with respect to memory and time.

Setting the objective function

The objective function is set using function setObjective(). There are two overloads for this function, one that specifies the objective sense and one that does not:

setObjective(Expression obj, ObjSense sense);
setObjective(Expression obj);

The default optimization sense is "minimize".

The expression passed to the function can be a linear or quadratic expression.

Solving the problem

Once the problem is set up, it can be optimized. This happens by means of the optimize() function. This function will start optimization and return only once the optimal solution is found, the problem is found infeasible, or some resource limit was hit.

Once the function returns, you need to query the SOLVESTATUS and SOLSTATUS attributes to understand what caused the function to stop. This is done by querying getSolveStatus() and getSolStatus() respectively. The values returned by that indicate why the solution process stopped and what kind of solution is available.

XpressProblem prob;
auto x = ...;
... // Build the model here
prob.optimize();
if (prob.attributes.getSolStatus() == xpress::SolStatus::OPTIMAL) {
  auto sol = prob.getSolution();
  for (Variable v : x)
    std::cout << v.getName() << " " << v.getValue(sol) << std::endl;
}

Note that there are overloads of the optimize() function that return the solve and solution status in additional arguments.

Setting solver controls

The Xpress Solver behavior and the solution strategy can be tweaked by setting solver controls.

Controls are accessible via getter and setter functions of the XpressProblem::controls field (more precisely, the field of the XPRSProblem superclass). For example, to stop the solver after 30 seconds, set the timelimit control:

prob.controls.setTimeLimit(30);
std::cout << "Time limit set to " << prob.controls.getTimeLimit() << std::endl;

Querying the solution

Once a solution is obtained (remember to check the solution status after calling optimize), the values of that solution can be queried in two different ways. The most efficient way is to call the getSolution() function of the XpressProblem instances, store the values in an array and then invoke the Variable's getValue() function on that array:

Variable x = ...;
prob.optimize();
std::vector<double> sol = prob.getSolution();
std::cout << x.getValue(sol) << std::endl;

Another way to get the solution value for a variable is to directly call the getSolution() function on the Variable instance:

Variable x = ...;
prob.optimize();
std::cout << x.getSolution() << std::endl;

This is less efficient when querying multiple variable values since it performs multiple queries against the underlying optimizer.

Similarly to solution values, you can query slacks of Inequality instances as well as reduced costs and dual multipliers in case of purely continuous problems. This is done by using functions getSlacks(), getRedCosts(), getDuals(), respectively. These return an array of values that can then be accessed using Variable::getValue() or Inequality::getValue(), just like in the case of solution values. Similarly, there are Inequality::getSlack(), Variable::getRedCost(), Inequality::getDual() that return the same information for an individual object – and to which the same caveats as for solution values apply.

A full example

The below code models a very simple Knapsack problem. The objective in this model is to maximize \[ 5x_1 + 4x_2 + 3x_3 + 8x_4 \] such that \[ 2x_1 + 5x_2 + 7x_3 + 9x_4 \leq 12 \] and all variables are binary.

#include <xpress.hpp>

using namespace xpress;
using namespace xpress::objects;
using xpress::objects::utils::scalarProduct;

std::array<double,4> weight{ 2, 5, 7, 9 };
std::array<double,4> profit{ 5, 4, 3, 8 };
double capacity = 12;

int main() {
  XpressProblem prob;

  // Create one binary variable for each item to model whether the
  // item is selected (variable is one) or not (variable is zero).
  auto x = prob.addVariables(weight.size())
    .withType(ColumnType::Binary)
    .withName([](auto i){ return xpress::format("x%d", i + 1); })
    .toArray();

  // Respect capacity constraint.
  prob.addConstraint(scalarProduct(x, weight) <= capacity);

  // Maximize profit.
  prob.setObjective(scalarProduct(x, profit),
                    ObjSense::Maximize);

  prob.writeProb("example.lp", "l");
  prob.callbacks.addMessageCallback(XpressProblem::console);
  prob.optimize();

  if (prob.attributes.getSolStatus() == SolStatus::Optimal) {
    std::cout << "Maximum profit: " << prob.attributes.getObjVal() << std::endl;
    auto sol = prob.getSolution();
    for (int i = 0; i < x.size(); ++i) {
      if (x[i].getValue(sol) > 0.5)
        std::cout << "Item " << (i+1) << " was selected" << std::endl;
    }
  }
}

Important implementation details

The XpressProblem class and RAII

The XpressProblem class serves as RAII container for Xpress licenses. That means, the constructor acquires a license and the destructor releases it. For this reason the copy and move constructor as well as the assignment operators of the XpressProblem class are deleted.

In order to pass around instances of XpressProblem you must pass them around as (smart) pointers or references. The same holds for containers of XpressProblem instances. For example, the following is not possible:

std::vector<XpressProblem> problems;

A vector of problems can instead be created as

std::vector<std::unique_ptr<XpressProblem>> problems;

or

std::vector<std::shared_ptr<XpressProblem>> problems;

You could also use a vector of raw pointers but that would defeat the purpose of RAII.

Handle classes

The Xpress C++ API makes extensive use of handle objects, such as Variable, Inequality, and Expression.

These handles behave very similarly to smart pointers. Thus copying and assigning them is cheap because they just create another reference to an existing object.

In order to downcast a handle, you cannot use dynamic_cast. Instead you have to use the cast function:

Expression expr = ...;
	  LinExpression linExpr = expr.cast<LinExpression>();