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.
Each of these files is searched first in the directory where the Pyton main file is located, then in the current directory, and finally in the PYTHONPATH. The first one that is found is read. Final set of parameters is obtained by reading first this module, and then those listed above.
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.factorize_expressions = True
This parameter indicates to factorize common expressions when generating the model in CPO file format.
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.sort_names = None
This parameter precise how the variables are sorted when declared in the CPO file.
The value can be None for no sort, ‘alphabetical’ to sort in alphabetical order, or ‘natural’ to sort in natural order (meaning for example that X11 will be declared after X2, which is not the case in alphabetical order).
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_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 True for a local solve, but is set to False if remote solve or if the Python interpreter is considered as running in a notebook (if module ipykernel is detected in system modules).
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.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.
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)”, and is searched in the file system using the strategy described below.
Configuration of the lib solving agent¶
context.solver.lib.libfile
Name or full path of the CP Optimizer library file. By default, it is set to “lib_cpo_solver_*(.dll)”, and is searched in the file system using the strategy described below.
Search for executable or library files¶
If an executable or library file is not given with its full path, it is searched in the file system in a list of directories that is built in this order:
- the directory where the main Python file is located,
- the current directory,
- all directories of the environment variables ‘LD_LIBRARY_PATH’ or ‘DYLD_LIBRARY_PATH’ if defined,
- all directories of the environment variable ‘PATH’.
If the file name contains an “*”, and if there are multiple files matching the pattern, the most recent is selected.
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.model.sort_names = None
context.solver.trace_cpo = False
context.solver.trace_log = False
context.solver.add_log_to_solution = False