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)

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

then we can refer to its index (which will be 0 here as it is the first variable added to the problem), by its object name, i.e., x, and by its given name "myvar", in the three following (equivalent) ways:

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.

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.add*Callback methods. Calling these functions outside of a callback may result in an error and trigger termination of the optimization process.

Deprecated functionality

The following functions are deprecated or have been removed.