Introduction

Topics covered in this chapter:

The Xpress Python interface allows for creating and solving optimization problems using the Python^® programming language and the FICO Xpress Optimizer library. This manual describes how to use the Xpress Python interface.

Outline

The following chapters cover:

• Creating, handling, solving, and querying optimization problems (Chapter Modeling an optimization problem);
• Using Python numerical libraries such as NumPy to create optimization problems (Chapter Using Python numerical libraries);
• Setting and getting the value of parameters (controls and attributes) of a problem (Chapter Controls and Attributes);
• Using Python functions as callbacks for the Xpress Optimizer and the Xpress Nonlinear solver (Chapter Using Callbacks);
• Several examples of usage of the Xpress Python interface (Chapter Examples of use);
• A reference with all functions and parameters in the Python interface (Chapter Reference Manual).

It is assumed here that the reader has basic understanding of the Python programming language. Ample documentation on Python is available at http://docs.python.org, including a tutorial and a reference manual. Unless specified otherwise, Python 3 is used in all of the examples and code samples throughout this manual. The current version of the Xpress Python interface works on Python 3.8 to 3.12.

Other components of the FICO-Xpress Optimization suite can interface with Python, albeit not the same Python versions. The Mosel module python3, for example, works with Python 3.5 or later. See the Mosel Language Reference Manual for specifics, and more in general the Xpress Insight Installation Guide, Appendix A: Supported Platforms for information on Python support.

"Python" is a registered trademark of the Python Software Foundation.

Installing the Python Xpress module

The Xpress Python module can be installed from the two main Python repositories: The Python Package Index (PyPI) and the Conda repository. Installing the Xpress Python interface does not require one to install the whole Xpress suite, as all necessary libraries are provided.

The installation comes with a copy of the community license, which allows for solving linear and mixed-integer problems with up to 5000 total variables and constraints, and quadratic and general nonlinear problems with up to 200 variables and constraints. In addition, the number of nonlinear tokens (measure of the complexity for nonlinear expressions) is restricted to 1000, and the number of user functions (black-box optimization) is restricted to 1.

If you already have an Xpress license, please make sure to set the XPAUTH_PATH environment variable to the full path to the license file, xpauth.xpr. See also Section Troubleshooting the installation below.

The manual is located in the xpress/doc subdirectory of the Python installation folder, and its location can be identified by invoking the xpress.manual() function.

Installation from the Python Package Index (PyPI)

The Xpress Python interface is available on the PyPI server and can be installed with the following command:

pip install xpress

Packages for Python 3.8 to 3.12 are available, for Windows, Linux, and MacOS. The package contains the Python interface module, its documentation in PDF format, the Xpress Optimizer's libraries, various examples of use, and a copy of the community license (see https://www.fico.com/en/fico-xpress-community-license). Online documentation can be viewed at the FICO Xpress Optimization Help page.

The above command installs the latest version of the Xpress Python module. Earlier versions of the module can be installed by appending a "==VERSION" string to the module name, for instance

pip install xpress==8.11.2

Installation from Conda

A Conda package is available for download with the following command:

conda install -c fico-xpress xpress

The content of the Conda package is the same as that of the PyPI package. Similar to the PyPI package, Conda packages for Python 3.8 to 3.12 are available, for Windows, Linux, and MacOS. Similar to PyPI, the Conda installer fetches the latest version of the package but allows for installing earlier versions as in the following example (note that the Conda installer only uses a single "="):

conda install -c fico-xpress xpress=8.11.3

Note that the Xpress Conda package requires the `intel-openmp` package on Intel platforms, which is available on the `main` and `intel` Conda channels.

Installation from a package file

Customers can download selected older versions of the Xpress Conda and PyPI packages from the Xpress client area site by clicking on the Archived Downloads link. Package files downloaded from this site can be installed with the following commands:

conda install /path/to/xpress-package-file.tar.bz2  # Conda
pip install /path/to/xpress-package-file.whl        # PyPI

Troubleshooting the installation

Whether the Xpress Python module is downloaded from PyPI or from the Conda server, there are a few remarks that might help ensure that the installation works right away. The advice below is independent of the Python platform (PyCharm, Spyder, etc.) that may be in use.

The Xpress Python interface uses the Python package NumPy for some operation, hence NumPy must be installed. It is usually installed if a Conda installation is used, nevertheless ensure that a recent-enough version is installed.

After installation, a license is not strictly necessary as the embedded Community license is used. If you already have a license (for example, a trial license, a full license, or one from the Academic Partnership Program), you can set the XPAUTH_PATH environment variable to the full path to the license file. For example, if the license file is /home/brian/xpauth.xpr, then XPAUTH_PATH should be set to /home/brian/xpauth.xpr in order for the module to pick the right license.

If you installed the Xpress Optimization suite before downloading the Xpress Conda or PyPI package, the Xpress Python interface will try to use the license file your Xpress installation automatically:

• On Windows, the Xpress installer sets the XPRESSDIR environment variable to the installation directory, and the Xpress Python interface will look for a license file at %XPRESSDIR%\bin\xpauth.xpr.
• On Linux and MacOS, the Xpress installer creates a script named xpvars.sh in the bin folder of the Xpress installation. This script sets XPRESSDIR to the installation directory, and sets XPAUTH_PATH to the location of the license file. If xpvars.sh has been properly sourced into the shell environment where Python is executed, the Xpress Python interface will use this XPAUTH_PATH value to locate the license from your Xpress installation. If for some reason XPAUTH_PATH is not set, the Xpress Python interface will look for a license file at $XPRESSDIR/bin/xpauth.xpr.

If you do not want to use the license file from your Xpress installation, you can override this behaviour by setting the XPAUTH_PATH environment variable to the full path to the license file that you want to use.