Reference Manual

Topics covered in this chapter:

Using this chapter

This chapter provides a list of functions available through the Xpress Python interface. For each function, the synopsis and an example are given.

In keeping with the Xpress Optimizer's C API, the name and order of the parameters used in these functions has been retained. However, in order to make optimal use of the greater flexibility provided by Python, the argument lists and the return value of some functions has been modified so as to obtain a more compact notation.

For example, for functions with a list as an argument, the number of elements of the list is not part of the arguments. Compare the call to the C function XPRSaddrows, where the parameters newrow and newnz must be passed, to its Python counterpart:

(C)      result = XPRSaddrows (prob, n, nnz, type,
                               rhs, NULL, mstart, indices, values);
(Python) p.addrows(type, rhs, None, mstart, indices, values)

As of version 8.12, the names in the C API have undergone a change in order to have more expressive names in the C API. The Python API was updated accordingly. The old names still work but are now deprecated. This reference documentation and all error messages refer to the new names.

In the Python version, the prob pointer is not provided as obviously addrows is a method of the problem class. The C variables n and nnz, which are assigned to arguments newrow and newnz, respectively, of the call to XPRSaddrows, are not necessary in the Python call as the length of rhs, mstart, etc. is inferred from the passed lists. If the lengths of all lists passed as arguments are not consistent with one another, an error will be returned.

Because lists (or tuples, generators, iterators, sequences) can be used as parameters of all functions in this manual, their size does not need to be passed explicitly as it is detected from the parameter itself. The interface will check the consistency and the content if the vector is referred to the variables or constraints, and will return an error in case of a mismatch.

When passing (lists, arrays, dictionaries of) variables, constraints, or SOSs, there are three ways of referring to these entities: by numerical index, by Python object, and by name. For instance, consider the problem.getSolution method, which admits both an empty argument and one or a list of variables. If we define a variable with a name as follows

p = xpress.problem()
x = p.addVariable(name='myvar')

print('x is ', p.getSolution(x))
print('x is ', p.getSolution(0))
print('x is ', p.getSolution('myvar'))

Another difference between the Python methods and their C API counterpart is that some output arguments are no longer passed (by reference) as arguments to the Python functions but rather are (part of) the value returned by the function. Where multiple scalar output parameters are returned by the C API function, some Python functions return a tuple containing all such output values.

The non-scalar parameters can instead be specified as lists, NumPy arrays, sequences, or generators when applicable. The output non-scalar parameters are stored as lists.

Optional parameters can be specified as None or skipped, provided the subsequent arguments are explicitly declared with their parameter name as Python allows:

p.addrows(rowtype=type, rhs=rhs, start=mstart,
           colind=indices, rowcoef=values)

Because the Python interface relies on the Xpress Optimizer C Application Program Interface, it is advisable to complement the knowledge in this reference manual with that of the Xpress Optimizer reference manual.

Format of the reference

The descriptions in the following pages report, for each function:

• Name;
• A short description of its purpose;
• Its synopsis, i.e., how it must be called. If it returns a value, then it will be presented as a Python assignment statement, otherwise it will be just shown as a call without a returned value; also, if it is a module function rather than a problem-specific function, it will be prefixed by xpress;
• A description of its arguments and whether each argument is optional;
• Error values;
• Associated controls;
• A sample usage of the function;
• Further useful information about the function;
• Related functions, parameters.

Note that all arguments defined in the remainder of this chapter as "array" or "vector" can be many other Python non-scalar objects: lists, generators, and NumPy arrays are admissible as parameters, except when specified (e.g. getControl). However, for simplicity we refer to non-scalar arguments as array.

Finally, some attributes and controls are referred to as uppercase words for clarity. For example, ROWS indicates the attribute "rows" of a problem, hence it is equivalent to problem.attributes.rows.

Classes of the Xpress module

Below is a list of classes used in all operations of the xpress module. While for a few of these classes an explicit constructor exists (for instance, xpress.problem and xpress.sos), objects of other classes, like xpress.linterm and xpress.expression, cannot be created with a constructor methods but are created using algebraic operators applied to constants, variables, and other expressions.

Global methods of the Xpress module

Below is a list of functions that are invoked from the Xpress module, i.e., they are not methods of the problem or the branchobj class and can be invoked after the import statement. The invocation is therefore as in the example that follows:

import xpress as xp
print(xp.getlasterror())
    

Methods of the class problem

The tables below show all methods of the class problem of the Xpress Python interface, with the exception of callbacks, which are listed separately. Their invocation is therefore to be preceded by a problem object (the class prefix problem. is omitted in the table for compactness), as follows:

import xpress as xp
p = xp.problem()
x = p.addVariable()
p.setObjective(x + 3 * x**2 + 2)
    

The following table contains the problem functions to be called for nonlinear problems.

Methods for branching objects

The following pages present the methods of the branchobj class, i.e., the methods used when creating and manipulating branching objects. Their invocation can be as follows:

import xpress as xp
b = xp.branchobj()
b.addbranches(3)
    

Methods for adding/removing callbacks of a problem object

The following pages present methods that can be called from a problem before optimization has started, to add or remove callbacks. All these methods are part of the problem class and have to be instantiated from a problem object.

Methods to be used within a callback of a problem object

The following methods can be called from within a callback function that has been passed in one of the problem.addcb* methods. Calling these functions outside of a callback may result in an error and trigger termination of the optimization process. We provide two tables: one is for the Optimizer and another for the nonlinear solvers.