CPLEX Python API Reference Manual

Contents:

• Cplex
  • Cplex package
  • cplex._internal package
• Python tutorial
  • Design of CPLEX in a Python application
  • Starting the CPLEX Python API
  • Accessing the module cplex
  • Building and solving a small LP with Python
  • Reading and writing CPLEX models to files with Python
  • Selecting an optimizer in Python
  • Example: reading a problem from a file lpex2.py
  • Modifying and re-optimizing in the CPLEX Python API
  • Example: modifying a model lpex3.py
  • Using CPLEX parameters in the CPLEX Python API
• CPLEX for Python users
  • CPLEX for Python users
  • Why Python?
  • Meet the Python API
  • Modifying and querying problem data in the Python API
  • Using polymorphism in the Python API
  • Example: generating a histogram
  • Querying solution information in the Python API
  • Examining variables with nonzero values in a solution
  • Displaying high precision nonzero values of a solution
  • Managing CPLEX parameters in the Python API
  • Using callbacks in the Python API
  • Example: displaying solutions with increased precision from the Python API
  • Example: examining the simplex tableau in the Python API
  • Example: solving a sequence of related problems in the Python API
  • Example: complex termination criteria in a callback

IBM CPLEX Python API Reference Manual

The CPLEX Python API is provided through a Python package called cplex. This package enables access to the CPLEX Callable Library directly from the Python programming language. It can be used interactively via the Python interpreter or for developing scripts and full-scale applications.

Available Python Interfaces

CPLEX offers two main ways for Python users to build optimization models:

1. CPLEX Python API

• A low-level API for directly interacting with the CPLEX engine

• Fully documented in this reference manual

• Suitable for users who want fine-grained control over optimization models

2. DOcplex (Decision Optimization CPLEX Modeling for Python)

A higher-level modeling library that simplifies model creation. DOcplex consists of two modules:

• docplex.mp (DOcplex.MP) Used forMathematical Programming (Linear Programming, Mixed-Integer Programming)

• docplex.cp (DOcplex.CP) Used forConstraint Programming

For more details, refer to:

• DOcplex documentation and landing page

• CPLEX Python examples for practical usage

Installation

The CPLEX Python API can be installed using either pip or conda:

If you are using the conda command to install, then you should make sure the correct channel will be searched.

You can add the right channel in the active environment with a command like:

conda config --add channels ibmdecisionoptimization

The following commands install the Community Edition CPLEX and CP Optimizer run-times as well as the low-level Python interface to CPLEX.

PyPI:

pip install cplex

Anaconda:

conda install cplex

The following commands install the higher-level “docplex” Python package which includes CPLEX and CP Optimizer modeling and solving support. The Community Edition run-times which come as standard are limited in the size of the optimization problems that they can solve. To upgrade the Community Edition runtimes and remove size limitations, use the command “docplex” which was installed when you installed the “docplex” module with pip and conda.

PyPI:

pip install docplex

Anaconda:

conda install docplex

Running:

docplex config --upgrade Full_Path_To_This_CPLEX_Studio_Installation

will upgrade the CPLEX and CP Optimizer Python run-times from the Community Edition version to a size-unlimited version.

What you need to know

This manual assumes that you are familiar with the Python programming language.

This manual also assumes that you are familiar with the operating system on which you are using CPLEX and have the appropriate version of Python installed on your system. For information about supported platforms, see Detailed System Requirements (DSR) on your IBM customer support site.

For interactive use, the tab completion functionality provided by the Python module rlcompleter is extremely useful as you browse the CPLEX Python API. GNU/Linux systems typically include this package by default. Mac users are advised to install the package readline for their system. Windows users are advised either to use IDLE, the Python IDE distributed with Python, or to install the package readline for their system.

Structure of the package cplex

The CPLEX Python API is an object-oriented API providing most of its functionality through the class Cplex defined in the top level of the package cplex. This class has a number of methods, such as Cplex.read and Cplex.solve for operating on optimization problems, but most of its functionality is provided through methods of data attributes such as Cplex.linear_constraints, Cplex.objective, and Cplex.solution. These objects provide methods for modifying and querying data associated with the corresponding parts of an optimization problem. These objects are instances of classes defined within the subpackage cplex._internal. As its name suggests, classes and other data defined in the package cplex._internal are not to be instantiated or otherwise accessed directly by the user, but rather should only be accessed as attributes of an instance of the object Cplex.