Setting up an optimization engine

Get IBM® optimizers

  • Mathematical programming (MP) models can be solved either with CPLEX® on the Cloud (DOcplexcloud) or with a local CPLEX installation (CPLEX Optimization Studio V12.6.3 or V12.7.0).
  • Constraint programming (CP) models can only be solved with CP Optimizer on the Cloud (DOcplexcloud).
  • You can get the solving capability you need here:
    • An IBM Decision Optimization on Cloud Service account and API key. You can register for a 30-day free trial or buy a subscription here.
    • IBM ILOG® CPLEX Optimization Studio Development or Deployment edition for solving with no engine limit or the Community Edition with engine limits. You can download the full CPLEX Community Edition here or you can download and install it from AnacondaCloud here.
    • IBM Academic Initiative for faculty members, research professionals: IBM Academic Initiative (AI) is a global program that faculty members, research professionals at accredited institutions, and qualifying members of standards organizations can join. Members can get full versions of a large selection of IBM software, including CPLEX at no charge. More information about IBM ILOG Optimization products in the IBM Academic Initiative can be found here.

Engine setup

Before you run the examples, you need to set up an optimization engine. The examples are written so that they use the IBM ILOG CPLEX Optimization Studio on your computer if the product is installed or will solve on the IBM Decision Optimization on Cloud service if CPLEX is not found.

Using the IBM Decision Optimization on Cloud service

To use the CPLEX or CP Optimizer algorithms on the cloud (DOcplexcloud), you will need to get 2 things:

  • the URL of the service to be called
  • the API key that corresponds to your personal account on this web service.

The API key will identify you on the IBM cloud and will also determine your computation rights. For example, a trial key will enable you to run 1 model at a time and queue a maximum of 5 jobs for a duration of 1 month. A paid subscription with bare metal will enable you to run multiple jobs in parallel. This key will also determine the type of CPU and RAM you can access, for example. You can generate multiple keys.

You can setup your credentials directly in your Python code using the context object as illustrated in some of the examples. This is especially useful if you use the cloud based IPython notebooks.

You can also place your credentials in a Python file: docplex will look for some predefined files. Indeed, DOcplex can search the PYTHONPATH for the following files in this specific order:

  • For a MP model:

    • cplex_config.py
    • cplex_config_<hostname>.py
    • docloud_config.py (must only contain context.solver.docloud configuration)

  • For a CP model:

    • cpo_config.py (depending on your modeling module)
    • cpo_config_<hostname>.py (depending on your modeling module)
    • docloud_config.py (must only contain context.solver.docloud configuration)

The docloud_config.py configuration file is shared between both modeling capabilities and must contain only common properties, while the other configuration files can contain specific properties such as engine parameters.

The following steps will guide you in getting the 2 strings you need and telling docplex to use them.

  1. Register for a trial account.

    Register for the DOcplexcloud free trial and use it free for 30 days. See Free trial.

  2. Get your API key.

    With your free trial, you can generate a key to access the DOcplexcloud API. Go to the Get API key & base URL page to generate the key after you register. This page also contains the base URL you must use for DOcplexcloud.

  3. The examples rely the specification of the API key either in the sample .py file or in a configuration file in your PYTHONPATH.

    The options are detailed below:

    1. Create a docloud_config.py file in any directory in your PYTHONPATH. For instance, you can create examples/docloud_config.py and add the examples directory to your PYTHONPATH. The docloud_config.py is a Python file containing code to configure the context used to solve problems:

      context.solver.docloud.url = YOUR_DOCLOUD_URL
context.solver.docloud.key = YOUR_API_KEY_HERE

    2. Edit each example .py file. Look for:

          """DOcplexcloud credentials can be specified with url and api_key.

...
    """
    url = "YOUR_DOCLOUD_URL"
    key = "YOUR_API_KEY_HERE"

      Edit your url and key.

Using IBM ILOG CPLEX Optimization Studio V12.7.0 on your computer

If you have IBM ILOG CPLEX Optimization Studio V12.7.0 installed (or V12.6.3), you need to add <cosdir>/<cplexdir>/python/<python_version>/<platform> to your PYTHONPATH.

  • <cosdir> is your CPLEX Optimization Studio installation directory.

  • <cplexdir> is your CPLEX installation directory.

  • <python_version> is:

    • 2.7 if your Python version is 2.7
    • 3.4 if your Python version is 3.4
    • 3.5 if your Python version is 3.5

  • <platform> is:

    • x64_win64 if your operating system is Windows
    • x86-64_linux if your operating system is Linux
    • x86-64_osx if your operating system is OS X

Note that if CPLEX is in the PYTHONPATH, then it overrides the DOcplexcloud credentials and solves locally, unless you use docloud as a solver agent. You change the solver agent by passing the agent parameter to the solve method of a model, or setting the context.solver.agent property.

More information about the DOcplexcloud solver service and CPLEX engines

You can read more about IBM Decision Optimization on Cloud (DOcplexcloud) here and its free trial version here.

You can read more about IBM ILOG CPLEX Optimization Studio here and its free Community Edition here.