Module docplex.cp.config¶
Configuration of the CP Optimizer Python API
This module is the top-level handler of the configuration parameters for the CP Optimizer Python API. It contains the default values of the different configuration parameters.
It should NOT be changed directly. The preferable way is to add at least one of the following files that contain the changes to be performed:
- cpo_config.py, a local set of changes on these parameters,
- cpo_config_<hostname>.py, a hostname dependent set of changes.
- docloud_config.py (for DOcloud url and key, file shared with docplex.mp package).
Final set of parameters is obtained by reading first this module, and then those listed above. These modules should be visible from the PYTHONPATH and are loaded in this order to overwrite default values.
This module also defines two global variables:
- DOCLOUD_CONTEXT, that contains the configuration necessary to solve a model on DOcloud. This context is the context by default, referenced by the global variable ‘context’.
- LOCAL_CONTEXT, that contains the configuration appropriate to solve a model with a local installation of the CPO solver. This configuration is available for solver with version number greater or equal to 12.7.0.
The method set_default() allows to set the default configuration to one that is predefined,
or another that has been totally customized.
If called as main, this module prints the actual configuration on standard output, including all customizations made using the mechanism described above.
Following sections describe the most important parameters that can be easily modified to customize the behavior of the Python API. All available parameters are available by consulting the source code of this module.
General parameters¶
context.log_output = sys.stdout
This parameter contains the default log stream. By default it is set to the standard output. A value of None can be used to disable all logs.
context.model.add_source_location = True
This parameter indicates that when the model is transformed into CPO format, additional information is added to correlate expressions with the Python file and line where it has been generated. If any error is raised by the solver during the solve, this information is provided in the error description, which allows for easier debugging.
context.model.length_for_alias = 15
This parameter enables the replacement of very long variable names by a shorter alias in the generated CPO format, allowing to reduce the size of the generated CPO file. By default, the value is 15. A value of None would indicate to always keep original variable names.
context.model.name_all_constraints = False
This parameter enables the naming of all constraints when the model is generated in CPO format. It is mandatory only if the refine conflict function is called. Anyway, if the refine conflict function is called, and if the CPO format of the model has already been generated, it is generated again with this option set in order to allow proper completion of the request. Setting it to True is preferable only if refine conflict function is called on a big model.
context.model.dump_directory = None
This parameter gives the name of a directory where the CPO files that are generated for solving models are stored for logging purpose.
If not None, the directory is created and generated models are stored in files named <model_name>.cpo.
context.params.*
The parameter context.params is an instance of the class CpoParameters (in parameters.py), which describes all of the public solver parameters as properties and is an extension of the base class Context.
The default configuration limits the solving time to 100 seconds by using following settings:
context.params.TimeMode = "ElapsedTime" context.params.TimeLimit = 100
Configuration of the model solving¶
context.solver.trace_cpo = False
This parameter indicates to trace the CPO model that is generated before submitting it for solving. The model is printed on the context.log_output stream, if given.
context.solver.trace_log = False
This parameter indicates to trace the log generated by the solver when solving the CPO model. The log is printed on the context.log_output stream, if given.
The default value of this parameter is False for a solve on the cloud, and True for a local solve.
context.solver.add_log_to_solution = True
This parameter indicates to add the solver log content to the solution object. By default, this parameter is True but it can be set to False if the log is very big or of no interest.
context.solver.agent = ‘docloud’
This parameter specifies the name of the solver agent that is used to solve the model. The value of this parameter is the name of a child context of context.solver, which contains necessary attributes that allow to create and run the required agent.
- There are two different agents described in the default configuration file:
- docloud, the default agent, for solving a CPO model using the DOcplexcloud service.
- angel, the agent allowing to solve models locally using the CP Optimizer Interactive coming with versions of COS greater or equal to 12.7.0.
Configuration of the docloud solving agent¶
context.solver.docloud.url = “https://api-oaas.docloud.ibmcloud.com/job_manager/rest/v1/”
This parameter is used to specify the URL of the DOcplexcloud service.
context.solver.docloud.key = “‘Set your key in docloud_config.py’”
This parameter contains the personal key for authorizing access to the DOcplexcloud service.
Access credentials (base URL and access key) can be retrieved after registration from http://developer.ibm.com/docloud/docs/api-key/.
These two parameters can be set in the docloud_config.py file.
context.solver.docloud.request_timeout = 30
This parameter contains the maximum time, in seconds, that a response is waited for after a unitary request to DOcplexcloud server.
context.solver.docloud.result_wait_extra_time = 60
This parameter is a time in seconds added to the expected solve time to compute the total result waiting timeout.
context.solver.docloud.clean_job_after_solve = True
This parameter indicates whether the job is automatically cleaned after the model is solved. If not set to True, the model stays on the DOcplexcloud server and is visible from its DropSolve interface. Note that the server may block future solving requests if there are too many jobs waiting.