docplex.util.environment module¶
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 anddata.txt
, the data expected bysum.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
[source]¶ 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 methoddocplex.util.environment.get_environment()
that is provided in this module.-
get_available_core_count
()[source]¶ 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)[source]¶ 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)[source]¶ 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.
-
-
docplex.util.environment.
get_environment
()[source]¶ 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.