Module docplex.util.environment

Representation of the DOcplex solving environment.

This module handles the various elements that allow an optimization program to run independently from the solving environment. This environment may be:

• on premise, using a local version of CPLEX Optimization Studio to solve MP problems, or
• on DOcplexcloud, with the Python program running inside the Python Worker.

As much as possible, the adaptation to the solving environment is automatic. The functions that are presented here are useful for handling very specific use cases.

The following code is a program that sums its input (sum.py):

import json
from docplex.util.environment import get_environment
if __name__ == "__main__":
    sum = 0
    # open program input named "data.txt" and sum the contents
    with get_environment().get_input_stream("data.txt") as input:
        for i in input.read().split():
            sum += int(i)
    # write the result as a simple json in program output "solution.json"
    with get_environment().get_output_stream("solution.json") as output:
        output.write(json.dumps({'result': sum}))

Let’s put some data in a data.txt file:

4 7 8
19

When you run sum.py with a Python interpreter, it opens the data.txt file and sums all of the integers in that file. The result is saved as a JSON fragment in file solution.json:

$ python sum.py
$ more solution.json
{"result": 38}

To submit the program to the DOcplexcloud service, we write a submit.py program that uses the DOcplexcloud Python API to create and submit a job. That job has two attachments:

• sum.py, the program to execute and
• data.txt, the data expected by sum.py.

After the solve is completed, the result of the program is downloaded and saved as solution.json:

from docloud.job import JobClient
if __name__ == "__main__":
    url = "ENTER_YOUR_URL_HERE"
    key = "ENTER_YOUR_KEY_HERE"
    client = JobClient(url, key)
    client.execute(input=["sum.py", "data.txt"], output="solution.json")

Then you run submit.py:

$ python submit.py
$ more solution.json
{"result": 38}

class docplex.util.environment.Environment

Bases: object

Methods for interacting with the execution environment.

Internally, the docplex package provides the appropriate implementation according to the actual execution environment. The correct instance of this class is returned by the method docplex.util.environment.get_environment() that is provided in this module.

get_available_core_count()

Returns the number of cores available for processing if the environment sets a limit.

This number is used in the solving engine as the number of threads.

Returns:The available number of cores or None if the environment does not limit the number of cores.

get_input_stream(name)

Get an input of the program as a stream (file-like object).

An input of the program is a file that is available in the working directory.

When run on DOcplexcloud, all input attachments are copied to the working directory before the program is run. get_input_stream lets you open the input attachments of the job.

Parameters:name – Name of the input object. Returns:A file object to read the input from.

get_output_stream(name)

Get a file-like object to write the output of the program.

The file is recorded as being part of the program output. This method can be called multiple times if the program contains multiple output objects.

When run on premise, the output of the program is written as files in the working directory. When run on DOcplexcloud, the files are attached as output attachments.

Parameters:name – Name of the output object. Returns:A file object to write the output to.

get_parameter(name)

Returns a parameter of the program.

On DOcplexcloud, this method returns the job parameter whose name is specified.

Parameters:name – The name of the parameter. Returns:The parameter whose name is specified.

docplex.util.environment.get_environment()

Returns the Environment object that represents the actual execution environment.

Returns:An instance of the Environment class that implements methods corresponding to actual execution environment.