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:
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.
This context is the context by default, referenced by the global variable ‘context’.
DOCLOUD_CONTEXT, that contains the configuration necessary to solve a model on DOcloud.
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.verbose = 0
This parameter controls the verbosity level of the log, between 0 and 9, if log_output is not None. The default value of 0 means no log.
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 = None
This parameter allows to associate a shorter alias to variables whose name is longer than the given length. In the CPO representation of the model, variable is declared with its original name and an alias is created to use it with a shorter name in model expressions, allowing to reduce the size of the generated CPO format.
In the returned solution, variable can be still retrieved with their original names.
By default, the value is None, which indicates 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.model.cache.size = 10000
This parameter gives the maximum capacity of the internal cache used to speed-up conversion of Python expressions into CPO expressions.
context.model.cache.active = True
This parameter allows to enable or disable the expression cache mechanism. Value os a boolean (True or False). Default value is True.
context.params.xxx
The parameter context.params is an instance of the classCpoParameters(in parameters.py) which describes all of the public solver parameters as properties.
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.enable_undocumented_params = False
This parameter allows to enable the possibility to set solving parameters that are not in the public parameters detailed in the classCpoParameters(in parameters.py).
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.add_conflict_as_cpo = True
This parameter indicates to include the conflict in CPO format in the conflict refiner result By default, this parameter is True.
context.solver.agent = ‘local’
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:
- local, the default agent, allowing to solve models locally using the CP Optimizer Interactive coming with versions of COS greater or equal to 12.7.0.
- docloud, the agent for solving a CPO model using the DOcplexcloud service.
If the CP Optimizer Interactive program cpoptimizer(.exe) is NOT detected in the system path, the default solver agent is automatically set to docloud instead of local.
context.solver.log_prefix = “[Solver] “
Prefix that is added to every message that is logged by the solver component.
Configuration of the local solving agent¶
context.solver.local.execfile
Name or full path of the CP Optimizer Interactive executable file. By default, it is set to cpoptimizer(.exe), which supposes that the program is visible from the system path.
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/.
context.solver.docloud.verify_ssl = True
This parameter allows to enable/disable the verification of SSL certificates.
context.solver.docloud.proxies = None
This parameter allows to optionally define proxies to be used in the connection with DOcplexcloud. It is a Python dictionary protocol_name / endpoint, as described in http://docs.python-requests.org/en/master/user/advanced/#proxies.
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.
context.solver.docloud.polling = Context(min=1, max=3, incr=0.2)
This parameter describes how the Python client polls the result of the solve on DOcplexcloud. Polling delay is inside an interval [min, max], starting by min, growing to max with the given increment.
Configuration for best performances¶
To configure the CP Python API for best performances, the following configuration settings may be used. Obviously, this performance is won at the cost of the loss of some features that may be useful in other cases.
context.verbose = 0
context.model.add_source_location = False
context.model.length_for_alias = 10
context.model.name_all_constraints = False
context.model.dump_directory = None
context.solver.trace_cpo = False
context.solver.trace_log = False
context.solver.add_log_to_solution = False