Module docplex.cp.parameters

This module handles the public parameters that can be assigned to CP Optimizer to configure the solving of a model.

The class CpoParameters contains the list of modifiable parameters expressed as properties with getters and setters. For the parameters that require special values, those values are given as constants.

Changing the value of a parameter can be done in multiple ways. For example, the TimeLimit can be set to 60s with:

• params.TimeLimit = 60

• params.set_TimeLimit(60)

• params[‘TimeLimit’] = 60

• params.set_attribute(‘TimeLimit’, 60)

Retrieving the value of a parameter can be done in the same way using:

• v = params.TimeLimit

• v = params.get_TimeLimit()

• v = params[‘TimeLimit’]

• v = params.get_attribute(‘TimeLimit’)

If a parameter is not set, the value returned by the first two access forms is None. The last access form (element of a dictionary) raises an exception.

Setting a parameter value to None is equivalent to force its default value. This may be for example useful to reset at solve time a parameter that has been set at model level.

Getting the list of all parameters that have been changed can be done by calling the method keys().

Note that the PEP8 naming convention is not applied here, to keep parameter names as they are in the solver, so that they can be referenced in solver logs.

Summary of parameters

The following list gives the summary of all public parameters.

Display and output

• LogVerbosity: Determines the verbosity of the search log. The value is a symbol in [‘Quiet’, ‘Terse’, ‘Normal’, ‘Verbose’]. Default value is ‘Normal’.

• LogPeriod: Controls how often the log information is displayed. The value is an integer strictly greater than 0. Default value is 1000.

• WarningLevel: Level of warnings issued by CP Optimizer when a solve is launched. The value is an integer in [0..3]. Default value is 2.

• PrintModelDetailsInMessages: Controls printing of additional information on error and warning messages. The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

• ModelAnonymizer: Controls anonymization of a model dumped via dumpModel. The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

• UseFileLocations: Controls whether location information (file, line) is added to the model. The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

• LogSearchTags: Controls the activation of search failure tags. The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

• KPIDisplay: Controls the display of the KPI values in the log. The value is a symbol in [‘SingleLine’, ‘MultipleLines’]. Default value is ‘SingleLine’.

Presolve

• Presolve: Controls the presolve of the model to produce more compact formulations and to achieve more domain reduction.

Optimality tolerances

• OptimalityTolerance: Absolute tolerance on the objective value for optimization models. The value is a positive float. Default value is 1e-09.

• RelativeOptimalityTolerance: Relative tolerance on the objective value for optimization models. The value is a non-negative float. Default value is 0.0001.

Search control

• Workers: Number of workers to run in parallel to solve the model. The value is a positive integer. Default value is Auto.

• SearchType: Type of search that is applied when solving a problem. The value is a symbol in [‘DepthFirst’, ‘Restart’, ‘MultiPoint’, ‘IterativeDiving’, ‘Neighborhood’, ‘Auto’]. Default value is ‘Auto’.

• RandomSeed: Seed of the random generator used by search strategies. The value is a non-negative integer. Default value is 0.

• RestartFailLimit: Controls the number of failures that must occur before restarting search. The value is an integer greater than 0. Default value is 100.

• RestartGrowthFactor: Controls the increase of the number of failures between restarts. The value is a float greater or equal to 1. Default value is 1.15.

• DynamicProbing: Controls probing carried out during search. The value is a symbol in [‘On’, ‘Off’, ‘Auto’]. Default value is ‘Auto’.

• DynamicProbingStrength: Controls the effort which is dedicated to dynamic probing. The value is a float in [0.001..1000]. Default value is 0.03.

• MultiPointNumberOfSearchPoints: Controls the number of solutions manipulated by the multi-point search algorithm. The value is an integer strictly greater than 1. Default value is 30.

• TemporalRelaxation: Advanced parameter can be used to control the usage of a temporal relaxation. Possible values are ‘On’ or ‘Off’.

• FailureDirectedSearch: Controls usage of failure-directed search. Possible values are ‘On’ or ‘Off’.

• FailureDirectedSearchEmphasis: Controls how much time CP Optimizer invests into failure-directed search once it is started. The value is a non-negative integer, or None (default) that does not set any limit.

• FailureDirectedSearchMaxMemory: Controls the maximum amount of memory available to failure-directed search The value is a non-negative integer, or None that does not set any limit. Default value is 104857600.

• AutomaticReplay: Low-level control of the behavior of solve() and next(). Possible values are ‘On’ or ‘Off’.

Search limits

• TimeLimit: Limits the CPU or elapsed time spent solving before terminating a search. The value is a non-negative float, or None (default) that does not set any limit.

• TimeMode: Defines how time is measured in CP Optimizer. The value is a symbol in [‘CPUTime’, ‘ElapsedTime’]. Default value is ‘ElapsedTime’.

• FailLimit: Limits the number of failures that can occur before terminating the search. The value is a non-negative integer, or None (default) that does not set any limit.

• ChoicePointLimit: Limits the number of choice points that are created before terminating a search. The value is a non-negative integer, or None (default) that does not set any limit.

• BranchLimit: Limits the number of branches that are made before terminating a search. The value is a non-negative integer, or None (default) that does not set any limit.

• SolutionLimit: Limits the number of feasible solutions that are found before terminating a search. The value is a non-negative integer, or None (default) that does not set any limit.

Inference levels for constraint propagation

For all following attributes, possible values are ‘Default’, ‘Low’, ‘Basic’, Medium’ or ‘Extended’. Default value is ‘Default’.

• DefaultInferenceLevel: General inference level for constraints whose particular inference level is Default.

• AllDiffInferenceLevel: Inference level for every constraint allDiff.

• DistributeInferenceLevel: Inference level for every constraint Distribute.

• CountInferenceLevel: Inference level for every constraint Count extracted to the invoked CP instance.

• CountDifferentInferenceLevel: Inference level for every constraint CountDifferent.

• SequenceInferenceLevel: Inference level for every constraint Sequence.

• AllMinDistanceInferenceLevel: Inference level for every constraint allMinDistance.

• ElementInferenceLevel: Inference level for every element constraint.

• PrecedenceInferenceLevel: Inference level for precedence constraints between interval variables.

• IntervalSequenceInferenceLevel: Inference level for the maintenance of the domain of every interval sequence variable.

• NoOverlapInferenceLevel: Inference level for every constraint NoOverlap extracted.

• CumulFunctionInferenceLevel: Inference level for constraints on expression CumulFunctionExpr.

• StateFunctionInferenceLevel: Inference level for constraints on state functions StateFunction.

Conflict refiner

• ConflictRefinerTimeLimit: Limits the CPU time spent before terminating the conflict refiner. The value is a non-negative float, or None (default) that does not set any limit.

• ConflictRefinerIterationLimit: Limits the number of iterations that are made before terminating the conflict refiner. The value is a non-negative integer, or None (default) that does not set any limit.

• ConflictRefinerBranchLimit: Limits the total number of branches that are made before terminating the conflict refiner. The value is a non-negative integer, or None (default) that does not set any limit.

• ConflictRefinerFailLimit: Limits the total number of failures that can occur before terminating the conflict refiner. The value is a non-negative integer, or None (default) that does not set any limit.

• ConflictRefinerOnVariables: Specifies whether the conflict refiner should refine variables domains. The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

Private parameters

A private parameter can only be set using the method set_attribute(), giving its name as a string and its value. In this case, there is no local checking of the validity of the parameter or its value at modeling time. If there is any error, it is detected only at solve time.

Detailed description

class docplex.cp.parameters.CpoParameters(**kwargs)

Bases: Context

Class handling solving parameters

Constructor

This constructor takes a variable number of optional arguments that allow to set parameters directly. For example:

myparams = CpoParameters(TimeLimit=20, LogPeriod=5000))

Parameters:

kwargs – (Optional) Any individual parameter as defined in this class.

property AllDiffInferenceLevel

This parameter specifies the inference level for every constraint AllDiff extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all AllDiff constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property AllMinDistanceInferenceLevel

This parameter specifies the inference level for every constraint AllMinDistance extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all AllMinDistance constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property AutomaticReplay

This parameter is an advanced, low-level one for controlling the behavior of solve() and next(). When the model being solved has an objective and solve is used, or when startNewSearch and next are used to produce multiple solutions, the solver may have a need to replay the last (or best) solution found. This can, in some cases, involve re-invoking the strategy which produced the solution. Normally this is only necessary if you use low level “Ilc” interfaces to specify problem elements not in the model (instance of Model). This parameter can take the values On or Off. The default value is On. A typical reason for setting this parameter to Off is, for instance, if you use your own custom goal (instance of IlcGoal), and this goal is not deterministic (does not do the same thing when executed twice). In this instance, the replay will not work correctly, and you can use this parameter to disable replay.

This parameter is deprecated since release 2.3.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property BranchLimit

This parameter limits the number of branches that are made before terminating a search. A branch is a decision made at a choice point in the search, a typical node being made up of two branches, for example: x == value and x != value. A branch is only counted at the moment a decision is executed, not when the two branches of the choice point are decided. A branch is counted even if the decision leads to an inconsistency (failure).

The value is a non-negative integer, or None (default) that does not set any limit.

property ChoicePointLimit

This parameter limits the number of choice points that are created before terminating a search.

The value is a non-negative integer, or None (default) that does not set any limit.

property ConflictRefinerBranchLimit

This parameter limits the total number of branches that are made before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

property ConflictRefinerFailLimit

This parameter limits the total number of failures that can occur before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

property ConflictRefinerIterationLimit

This parameter limits the number of iterations that are made before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

property ConflictRefinerOnVariables

This parameter specifies whether the conflict refiner should refine variables domains. Possible values for this parameter are On (conflict refiner will refine both constraints and variables domains) and Off (conflict refiner will only refine constraints).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

property ConflictRefinerTimeLimit

This parameter limits the CPU time spent before terminating the conflict refiner.

The value is a non-negative float, or None (default) that does not set any limit.

property CountDifferentInferenceLevel

This parameter specifies the inference level for every constraint CountDifferent extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all CountDifferent constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property CountInferenceLevel

This parameter specifies the inference level for every constraint Count extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Count constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property CumulFunctionInferenceLevel

This parameter specifies the inference level for constraints on expressions CumulFunctionExpr extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all constraints on CumulFunctionExpr to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property DefaultInferenceLevel

This parameter specifies the general inference level for constraints whose particular inference

level is Default. Possible values for this parameter (in increasing order of inference strength) are Low, Basic, Medium, and Extended.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property DistributeInferenceLevel

This parameter specifies the inference level for every constraint Distribute extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Distribute constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property DynamicProbing

This parameter controls probing carried out during search. Probing can be useful on some problems as it can make stronger inferences on combinations of constraints. Possible values for this parameter are On (dynamic probing is activated with a constant strength), Auto (dynamic probing is activated and its strength is adjusted adaptively) and Off (dynamic probing is deactivated). The strength of probing can be defined by parameter DynamicProbingStrength. Dynamic probing only has an effect when using the “Restart” (Restart) search type, on problems without interval variables.

The value is a symbol in [‘On’, ‘Off’, ‘Auto’]. Default value is ‘Auto’.

property DynamicProbingStrength

This parameter controls the effort which is dedicated to dynamic probing. It is expressed as a factor of the total search effort: changing this parameter has no effect unless the DynamicProbing parameter is set to Auto or On. When DynamicProbing has value On, the probing strength is held constant throughout the search process. When DynamicProbing has value Auto, the probing strength starts off at the specified value and is thereafter adjusted automatically. Possible values for this parameter range from 0.001 to 1000. A value of 1.0 indicates that dynamic probing will consume a roughly equal amount of effort as the rest of the search. The default value of this parameter is 0.03, meaning that around 3% of total search time is dedicated to dynamic probing.

The value is a float in [0.001..1000]. Default value is 0.03.

property ElementInferenceLevel

This parameter specifies the inference level for every element constraint extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all element constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property FailLimit

This parameter limits the number of failures that can occur before terminating the search.

The value is a non-negative integer, or None (default) that does not set any limit.

property FailureDirectedSearch

This parameter controls usage of failure-directed search. Failure-directed search assumes that there is no (better) solution or that such a solution is very hard to find. Therefore it focuses on a systematic exploration of search space, first eliminating assignments that are most likely to fail. Failure-directed search is used only for scheduling problems (i.e. models containing interval variables) and only when the parameter SearchType is set to Restart or Auto. Legal values for the FailureDirectedSearch parameter are On (the default) and Off. When the value is On then CP Optimizer starts failure-directed search when other search strategies are (no longer) successful and when the memory necessary for the search does not exceed the value set by the FailureDirectedSearchMaxMemory parameter.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property FailureDirectedSearchEmphasis

This parameter controls how much time CP Optimizer invests into failure-directed search once it is started. The default value Auto means that CP Optimizer observes the actual performance of failure-directed search and decides automatically how much time is invested. Any other value means that once failure-directed search has started, it is used by given number of workers. The value does not have to be integer. For example, value 1.5 means that first worker spends 100% of the time by failure-directed search, second worker 50% and remaining workers 0%. See also Workers For more information about failure-directed search see parameter FailureDirectedSearch.

The value is a non-negative integer, or None or Auto (default) that does not set any limit.

property FailureDirectedSearchMaxMemory

This parameter controls the maximum amount of memory (in bytes) available to failure-directed search (see FailureDirectedSearchMaxMemory). The default value is 104,857,600 (100MB). Failure-directed search can sometimes consume a lot of memory, especially when end times of interval variables are not bounded. Therefore it is usually not started immediately, but only when the effective horizon (time period over which CP Optimizer must reason) becomes small enough for failure-directed search to operate inside the memory limit specified by this parameter. For many types of scheduling problems, the effective horizon tends to reduce when CP Optimizer finds a better solution (often most significantly when the initial solution is found). Therefore, when each new solution is found, CP Optimizer decides whether or not to turn on failure-directed search. Note that this parameter does not influence the effectiveness of failure-directed search, once started. Its purpose is only to control the point at which failure-directed search will begin to function.

The value is a non-negative integer, or None that does not set any limit. Default value is 104857600.

property IntervalSequenceInferenceLevel

This parameter specifies the inference level for the maintenance of the domain of every interval sequence variable IntervalSequenceVar extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all IntervalSequenceVar to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. default value is ‘Default’.

property KPIDisplay

This parameter determines how KPIs are displayed in the log during the search.

The value is a symbol in [‘SingleLine’, ‘MultipleLines’]. Default value is ‘SingleLine’.

New in version 2.8, for CPO solver version 12.9.0 and higher.

property LogPeriod

The CP Optimizer search log includes information that is displayed periodically. This parameter controls how often that information is displayed. By setting this parameter to a value of k, the log is displayed every k branches (search decisions).

The value is an integer strictly greater than 0. Default value is 1000.

property LogVerbosity

This parameter determines the verbosity of the search log. The possible values are Quiet, Terse, Normal, and Verbose. Mode Quiet does not display any information, the other modes display progressively more information. The default value is Normal. The CP Optimizer search log is meant for visual inspection only, not for mechanized parsing. In particular, the log may change from version to version of CP Optimizer in order to improve the quality of information displayed in the log. Any code based on the log output for correct functioning may have to be updated when a new version of CP Optimizer is released.

The value is a symbol in [‘Quiet’, ‘Terse’, ‘Normal’, ‘Verbose’]. Default value is ‘Normal’.

property ModelAnonymizer

This parameter controls anonymization of a model dumped in CPO file format. The legal values of this parameter are Off and On. The default is Off. When the anonymizer is off, then names of variables and constraints in the model may be found in the output file. When the anonymizer is on, names given to variables or constraints in the model will not be reflected in the output file and standard anonymized names will be used.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

property MultiPointNumberOfSearchPoints

This parameter controls the number of (possibly partial) solutions manipulated by the multi-point search algorithm. The default value is 30. A larger value will diversify the search, with possible improvement in solution quality at the expense of a longer run time. A smaller value will intensify the search, resulting in faster convergence at the expense of solution quality. Note that memory consumption increases proportionally to this parameter, for each search point must store each decision variable domain.

The value is an integer strictly greater than 1. Default value is 30.

property NoOverlapInferenceLevel

This parameter specifies the inference level for every constraint NoOverlap extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all NoOverlap constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property OptimalityTolerance

This parameter sets an absolute tolerance on the objective value for optimization models. This means that when CP Optimizer reports an optimal solution found, then there is no solution which improves the objective by more than the value of this parameter. This parameter is used in conjunction with RelativeOptimalityTolerance. The optimality of a solution is proven if either of the two parameters’ criteria is fulfilled.

The value is a positive float. Default value is 1e-09.

property PrecedenceInferenceLevel

This parameter specifies the inference level for precedence constraints between interval variables extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength for precedence constraints between interval variables to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property Presolve

This parameter controls the presolve of the model to produce more compact formulations and to achieve more domain reduction. Possible values for this parameter are On (presolve is activated) and Off (presolve is deactivated).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property PrintModelDetailsInMessages

Whenever CP Optimizer prints an error or warning message, it can also print concerning part of the input model (in cpo file format). This parameter controls printing of this additional information. Possible values are On and Off, the Default value is ‘On’. See also WarningLevel.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property RandomSeed

The search uses some randomization in some strategies. This parameter sets the seed of the random generator used by these strategies.

The value is a non-negative integer. Default value is 0.

property RelativeOptimalityTolerance

This parameter sets a relative tolerance on the objective value for optimization models. This means that when CP Optimizer reports an optimal solution found, then there is no solution which improves the objective by more than the absolute value of the objective times the value of this parameter. The default value of this parameter is 1e-4. This parameter is used in conjunction with OptimalityTolerance. The optimality of a solution is proven if either of the two parameters’ criteria are fulfilled.

The value is a non-negative float. Default value is 0.0001.

property RestartFailLimit

When SearchType is set to Restart, a depth-first search is restarted after a certain number of failures. This parameter controls the number of failures that must occur before restarting search. Possible values range from 0 to Infinity. The default value is 100. This value can increase after each restart: see the parameter RestartGrowthFactor.

The value is an integer greater than 0. Default value is 100.

property RestartGrowthFactor

When SearchType is set to Restart, a depth-first search is restarted after a certain number of failures. This parameter controls the increase of this number between restarts. If the last fail limit was f after a restart, for next run, the new fail limit will be f times the value of this parameter. Possible values of this parameter range from 1.0 to Infinity. The default value is 1.05. The initial fail limit can be controlled with the parameter RestartFailLimit.

The value is a float greater or equal to 1. Default value is 1.15.

property SearchType

This parameter determines the type of search that is applied when solving a problem.

• When set to DepthFirst, a regular depth-first search is applied.

• When set to Restart, a depth-first search that restarts from time to time is applied.

• When set to MultiPoint, a method that combines a set of - possibly partial - solutions is applied.

• When set to IterativeDiving on scheduling problems (ones with at least one interval variable), a more aggressive diving technique is applied in order to find solutions to large problems more quickly.

• When set to Neighborhood, a search based on a solution neighborhood exploration should be used (feature in beta).

• When set to Auto in sequential mode, this value chooses the appropriate search method to be used. In general Auto will be the Restart search. The default value is Auto.

In parallel mode (i.e, when the number of workers is greater than one - see the Workers parameter), the different searches described above are spread over the workers. When the value of SearchType is Auto, then the decision of choosing the search type for a worker is automatically made; otherwise, all workers execute the same type of search. Note that in the latter case, the workers will not do the same exploration due to some randomness introduced to break ties in decision making.

The value is a symbol in [‘DepthFirst’, ‘Restart’, ‘MultiPoint’, ‘IterativeDiving’, ‘Neighborhood’, ‘Auto’]. Default value is ‘Auto’.

property SequenceInferenceLevel

This parameter specifies the inference level for every constraint Sequence extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Sequence constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property SolutionLimit

This parameter limits the number of feasible solutions that are found before terminating a search.

The value is a non-negative integer, or None (default) that does not set any limit.

property StateFunctionInferenceLevel

This parameter specifies the inference level for constraints on state functions StateFunction extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all constraints on state functions StateFunction to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

property TemporalRelaxation

This advanced parameter can be used to control the usage of a temporal relaxation internal to the invoking CP engine. This parameter can take values On or Off, with On being the default, meaning the relaxation is used in the engine when needed. For some models, using the relaxation becomes inefficient, and you may deactivate the use of the temporal relaxation using value Off.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property TimeLimit

This parameter limits the CPU time spent solving before terminating a search. The time is given in seconds.

The value is a non-negative float, or None (default) that does not set any limit.

property TimeMode

This parameter defines how time is measured in CP Optimizer, the two legal values being ElapsedTime and CPUTime. CP Optimizer uses time for both display purposes and for limiting the search via TimeLimit. Note that when multiple processors are available and the number of workers (Workers) is greater than one, then the CPU time can be greater than the elapsed time by a factor up to the number of workers.

The value is a symbol in [‘CPUTime’, ‘ElapsedTime’]. Default value is ‘ElapsedTime’.

property UseFileLocations

This parameter controls whether CP Optimizer processes file locations. With each constraint, variable or expression it is possible to associate a source file location (file name and line number). CP Optimizer can use locations later for reporting errors and conflicts. Locations are also included in exported/dumped models (#line directives). Legal values for this parameter are On (the default) and Off. When the value is Off then CP Optimizer ignores locations in the input model and also does not export them in CPO file format (functions dumpModel and exportModel).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

property WarningLevel

This parameter controls the level of warnings issued by CP Optimizer when a solve is launched. Specifically, all warnings of level higher than this parameter are masked. Since CP Optimizer warning levels run from 1 to 3, setting this parameter to 0 turns off all warnings. Warnings issued may indicate potential errors or inefficiencies in your model. The default value of this parameter is 2. See also PrintModelDetailsInMessages.

The value is an integer in [0..3]. Default value is 2.

property Workers

This parameter sets the number of workers to run in parallel to solve your model. If the number of workers is set to n (with n greater than one), the CP optimizer will create n workers, each in their own thread, that will work together to solve the problem. The emphasis of these workers is more to find better feasible solutions and then to speed up the proof of optimality. The default value is Auto. This amounts to using as many workers as there are CPU cores available on the machine. Note that the memory required by CP Optimizer grows roughly linearly as the number of workers is increased. If you are solving a very large model on a multi-core processor and memory usage is an issue, it is advisable to specify a reduced number of workers, or even one worker, rather than use the default value.

The value is a positive integer. Default value is Auto.

add(ctx)

Add another parameters object to this one.

All attributes of given parameters are set in this one, except if there value is None. If one value is another context, it is cloned before being set.

Parameters:

ctx – Other parameters to add to this one.

get_AllDiffInferenceLevel()

This parameter specifies the inference level for every constraint AllDiff extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all AllDiff constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_AllMinDistanceInferenceLevel()

This parameter specifies the inference level for every constraint AllMinDistance extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all AllMinDistance constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_AutomaticReplay()

This parameter is an advanced, low-level one for controlling the behavior of solve() and next(). When the model being solved has an objective and solve is used, or when startNewSearch and next are used to produce multiple solutions, the solver may have a need to replay the last (or best) solution found. This can, in some cases, involve re-invoking the strategy which produced the solution. Normally this is only necessary if you use low level “Ilc” interfaces to specify problem elements not in the model (instance of Model). This parameter can take the values On or Off. The default value is On. A typical reason for setting this parameter to Off is, for instance, if you use your own custom goal (instance of IlcGoal), and this goal is not deterministic (does not do the same thing when executed twice). In this instance, the replay will not work correctly, and you can use this parameter to disable replay.

This parameter is deprecated since release 2.3.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_BranchLimit()

This parameter limits the number of branches that are made before terminating a search. A branch is a decision made at a choice point in the search, a typical node being made up of two branches, for example: x == value and x != value. A branch is only counted at the moment a decision is executed, not when the two branches of the choice point are decided. A branch is counted even if the decision leads to an inconsistency (failure).

The value is a non-negative integer, or None (default) that does not set any limit.

get_ChoicePointLimit()

This parameter limits the number of choice points that are created before terminating a search.

The value is a non-negative integer, or None (default) that does not set any limit.

get_ConflictRefinerBranchLimit()

This parameter limits the total number of branches that are made before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

get_ConflictRefinerFailLimit()

This parameter limits the total number of failures that can occur before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

get_ConflictRefinerIterationLimit()

This parameter limits the number of iterations that are made before terminating the conflict refiner.

The value is a non-negative integer, or None (default) that does not set any limit.

get_ConflictRefinerOnVariables()

This parameter specifies whether the conflict refiner should refine variables domains. Possible values for this parameter are On (conflict refiner will refine both constraints and variables domains) and Off (conflict refiner will only refine constraints).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

get_ConflictRefinerTimeLimit()

This parameter limits the CPU time spent before terminating the conflict refiner.

The value is a non-negative float, or None (default) that does not set any limit.

get_CountDifferentInferenceLevel()

This parameter specifies the inference level for every constraint CountDifferent extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all CountDifferent constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_CountInferenceLevel()

This parameter specifies the inference level for every constraint Count extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Count constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_CumulFunctionInferenceLevel()

This parameter specifies the inference level for constraints on expressions CumulFunctionExpr extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all constraints on CumulFunctionExpr to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_DefaultInferenceLevel()

This parameter specifies the general inference level for constraints whose particular inference level is Default. Possible values for this parameter (in increasing order of inference strength) are Low, Basic, Medium, and Extended.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_DistributeInferenceLevel()

This parameter specifies the inference level for every constraint Distribute extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Distribute constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_DynamicProbing()

This parameter controls probing carried out during search. Probing can be useful on some problems as it can make stronger inferences on combinations of constraints. Possible values for this parameter are On (dynamic probing is activated with a constant strength), Auto (dynamic probing is activated and its strength is adjusted adaptively) and Off (dynamic probing is deactivated). The strength of probing can be defined by parameter DynamicProbingStrength. Dynamic probing only has an effect when using the “Restart” (Restart) search type, on problems without interval variables.

The value is a symbol in [‘On’, ‘Off’, ‘Auto’]. Default value is ‘Auto’.

get_DynamicProbingStrength()

This parameter controls the effort which is dedicated to dynamic probing. It is expressed as a factor of the total search effort: changing this parameter has no effect unless the DynamicProbing parameter is set to Auto or On. When DynamicProbing has value On, the probing strength is held constant throughout the search process. When DynamicProbing has value Auto, the probing strength starts off at the specified value and is thereafter adjusted automatically. Possible values for this parameter range from 0.001 to 1000. A value of 1.0 indicates that dynamic probing will consume a roughly equal amount of effort as the rest of the search. The default value of this parameter is 0.03, meaning that around 3% of total search time is dedicated to dynamic probing.

The value is a float in [0.001..1000]. Default value is 0.03.

get_ElementInferenceLevel()

This parameter specifies the inference level for every element constraint extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all element constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_FailLimit()

This parameter limits the number of failures that can occur before terminating the search.

The value is a non-negative integer, or None (default) that does not set any limit.

get_FailureDirectedSearch()

This parameter controls usage of failure-directed search. Failure-directed search assumes that there is no (better) solution or that such a solution is very hard to find. Therefore it focuses on a systematic exploration of search space, first eliminating assignments that are most likely to fail. Failure-directed search is used only for scheduling problems (i.e. models containing interval variables) and only when the parameter SearchType is set to Restart or Auto. Legal values for the FailureDirectedSearch parameter are On (the default) and Off. When the value is On then CP Optimizer starts failure-directed search when other search strategies are (no longer) successful and when the memory necessary for the search does not exceed the value set by the FailureDirectedSearchMaxMemory parameter.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_FailureDirectedSearchEmphasis()

This parameter controls how much time CP Optimizer invests into failure-directed search once it is started. The default value Auto means that CP Optimizer observes the actual performance of failure-directed search and decides automatically how much time is invested. Any other value means that once failure-directed search has started, it is used by given number of workers. The value does not have to be integer. For example, value 1.5 means that first worker spends 100% of the time by failure-directed search, second worker 50% and remaining workers 0%. See also Workers For more information about failure-directed search see parameter FailureDirectedSearch.

The value is a non-negative integer, or None or Auto (default) that does not set any limit.

get_FailureDirectedSearchMaxMemory()

This parameter controls the maximum amount of memory (in bytes) available to failure-directed search (see FailureDirectedSearchMaxMemory). The default value is 104,857,600 (100MB). Failure-directed search can sometimes consume a lot of memory, especially when end times of interval variables are not bounded. Therefore it is usually not started immediately, but only when the effective horizon (time period over which CP Optimizer must reason) becomes small enough for failure-directed search to operate inside the memory limit specified by this parameter. For many types of scheduling problems, the effective horizon tends to reduce when CP Optimizer finds a better solution (often most significantly when the initial solution is found). Therefore, when each new solution is found, CP Optimizer decides whether or not to turn on failure-directed search. Note that this parameter does not influence the effectiveness of failure-directed search, once started. Its purpose is only to control the point at which failure-directed search will begin to function.

The value is a non-negative integer, or None that does not set any limit. Default value is 104857600.

get_IntervalSequenceInferenceLevel()

This parameter specifies the inference level for the maintenance of the domain of every interval sequence variable IntervalSequenceVar extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all IntervalSequenceVar to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. default value is ‘Default’.

get_KPIDisplay()

This parameter determines how KPIs are displayed in the log during the search.

The value is a symbol in [‘SingleLine’, ‘MultipleLines’]. Default value is ‘SingleLine’.

New in version 2.8, for CPO solver version 12.9.0 and higher.

get_LogPeriod()

The CP Optimizer search log includes information that is displayed periodically. This parameter controls how often that information is displayed. By setting this parameter to a value of k, the log is displayed every k branches (search decisions).

The value is an integer strictly greater than 0. Default value is 1000.

get_LogVerbosity()

This parameter determines the verbosity of the search log. The possible values are Quiet, Terse, Normal, and Verbose. Mode Quiet does not display any information, the other modes display progressively more information. The default value is Normal. The CP Optimizer search log is meant for visual inspection only, not for mechanized parsing. In particular, the log may change from version to version of CP Optimizer in order to improve the quality of information displayed in the log. Any code based on the log output for correct functioning may have to be updated when a new version of CP Optimizer is released.

The value is a symbol in [‘Quiet’, ‘Terse’, ‘Normal’, ‘Verbose’]. Default value is ‘Normal’.

get_ModelAnonymizer()

This parameter controls anonymization of a model dumped in CPO file format. The legal values of this parameter are Off and On. The default is Off. When the anonymizer is off, then names of variables and constraints in the model may be found in the output file. When the anonymizer is on, names given to variables or constraints in the model will not be reflected in the output file and standard anonymized names will be used.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘Off’.

get_MultiPointNumberOfSearchPoints()

This parameter controls the number of (possibly partial) solutions manipulated by the multi-point search algorithm. The default value is 30. A larger value will diversify the search, with possible improvement in solution quality at the expense of a longer run time. A smaller value will intensify the search, resulting in faster convergence at the expense of solution quality. Note that memory consumption increases proportionally to this parameter, for each search point must store each decision variable domain.

The value is an integer strictly greater than 1. Default value is 30.

get_NoOverlapInferenceLevel()

This parameter specifies the inference level for every constraint NoOverlap extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all NoOverlap constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_OptimalityTolerance()

This parameter sets an absolute tolerance on the objective value for optimization models. This means that when CP Optimizer reports an optimal solution found, then there is no solution which improves the objective by more than the value of this parameter. This parameter is used in conjunction with RelativeOptimalityTolerance. The optimality of a solution is proven if either of the two parameters’ criteria is fulfilled.

The value is a positive float. Default value is 1e-09.

get_PrecedenceInferenceLevel()

This parameter specifies the inference level for precedence constraints between interval variables extracted to the invoking CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength for precedence constraints between interval variables to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_Presolve()

This parameter controls the presolve of the model to produce more compact formulations and to achieve more domain reduction. Possible values for this parameter are On (presolve is activated) and Off (presolve is deactivated).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_PrintModelDetailsInMessages()

Whenever CP Optimizer prints an error or warning message, it can also print concerning part of the input model (in cpo file format). This parameter controls printing of this additional information. Possible values are On and Off, the Default value is ‘On’. See also WarningLevel.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_RandomSeed()

The search uses some randomization in some strategies. This parameter sets the seed of the random generator used by these strategies.

The value is a non-negative integer. Default value is 0.

get_RelativeOptimalityTolerance()

This parameter sets a relative tolerance on the objective value for optimization models. This means that when CP Optimizer reports an optimal solution found, then there is no solution which improves the objective by more than the absolute value of the objective times the value of this parameter. The default value of this parameter is 1e-4. This parameter is used in conjunction with OptimalityTolerance. The optimality of a solution is proven if either of the two parameters’ criteria are fulfilled.

The value is a non-negative float. Default value is 0.0001.

get_RestartFailLimit()

When SearchType is set to Restart, a depth-first search is restarted after a certain number of failures. This parameter controls the number of failures that must occur before restarting search. Possible values range from 0 to Infinity. The default value is 100. This value can increase after each restart: see the parameter RestartGrowthFactor.

The value is an integer greater than 0. Default value is 100.

get_RestartGrowthFactor()

When SearchType is set to Restart, a depth-first search is restarted after a certain number of failures. This parameter controls the increase of this number between restarts. If the last fail limit was f after a restart, for next run, the new fail limit will be f times the value of this parameter. Possible values of this parameter range from 1.0 to Infinity. The default value is 1.05. The initial fail limit can be controlled with the parameter RestartFailLimit.

The value is a float greater or equal to 1. Default value is 1.15.

get_SearchType()

This parameter determines the type of search that is applied when solving a problem.

• When set to DepthFirst, a regular depth-first search is applied.

• When set to Restart, a depth-first search that restarts from time to time is applied.

• When set to MultiPoint, a method that combines a set of - possibly partial - solutions is applied.

• When set to IterativeDiving on scheduling problems (ones with at least one interval variable), a more aggressive diving technique is applied in order to find solutions to large problems more quickly.

• When set to Neighborhood, a search based on a solution neighborhood exploration should be used (feature in beta).

• When set to Auto in sequential mode, this value chooses the appropriate search method to be used. In general Auto will be the Restart search. The default value is Auto.

In parallel mode (i.e, when the number of workers is greater than one - see the Workers parameter), the different searches described above are spread over the workers. When the value of SearchType is Auto, then the decision of choosing the search type for a worker is automatically made; otherwise, all workers execute the same type of search. Note that in the latter case, the workers will not do the same exploration due to some randomness introduced to break ties in decision making.

The value is a symbol in [‘DepthFirst’, ‘Restart’, ‘MultiPoint’, ‘IterativeDiving’, ‘Neighborhood’, ‘Auto’]. Default value is ‘Auto’.

get_SequenceInferenceLevel()

This parameter specifies the inference level for every constraint Sequence extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all Sequence constraints to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_SolutionLimit()

This parameter limits the number of feasible solutions that are found before terminating a search.

The value is a non-negative integer, or None (default) that does not set any limit.

get_StateFunctionInferenceLevel()

This parameter specifies the inference level for constraints on state functions StateFunction extracted to the invoked CP instance. Possible values for this parameter are Default, Low, Basic, Medium, and Extended. The default value is Default, which allows the inference strength of all constraints on state functions StateFunction to be controlled via DefaultInferenceLevel.

The value is a symbol in [‘Default’, ‘Low’, ‘Basic’, ‘Medium’, ‘Extended’]. Default value is ‘Default’.

get_TemporalRelaxation()

This advanced parameter can be used to control the usage of a temporal relaxation internal to the invoking CP engine. This parameter can take values On or Off, with On being the default, meaning the relaxation is used in the engine when needed. For some models, using the relaxation becomes inefficient, and you may deactivate the use of the temporal relaxation using value Off.

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_TimeLimit()

This parameter limits the CPU time spent solving before terminating a search. The time is given in seconds.

The value is a non-negative float, or None (default) that does not set any limit.

get_TimeMode()

This parameter defines how time is measured in CP Optimizer, the two legal values being ElapsedTime and CPUTime. CP Optimizer uses time for both display purposes and for limiting the search via TimeLimit. Note that when multiple processors are available and the number of workers (Workers) is greater than one, then the CPU time can be greater than the elapsed time by a factor up to the number of workers.

The value is a symbol in [‘CPUTime’, ‘ElapsedTime’]. Default value is ‘ElapsedTime’.

get_UseFileLocations()

This parameter controls whether CP Optimizer processes file locations. With each constraint, variable or expression it is possible to associate a source file location (file name and line number). CP Optimizer can use locations later for reporting errors and conflicts. Locations are also included in exported/dumped models (#line directives). Legal values for this parameter are On (the default) and Off. When the value is Off then CP Optimizer ignores locations in the input model and also does not export them in CPO file format (functions dumpModel and exportModel).

The value is a symbol in [‘On’, ‘Off’]. Default value is ‘On’.

get_WarningLevel()

This parameter controls the level of warnings issued by CP Optimizer when a solve is launched. Specifically, all warnings of level higher than this parameter are masked. Since CP Optimizer warning levels run from 1 to 3, setting this parameter to 0 turns off all warnings. Warnings issued may indicate potential errors or inefficiencies in your model. The default value of this parameter is 2. See also PrintModelDetailsInMessages.

The value is an integer in [0..3]. Default value is 2.

get_Workers()

This parameter sets the number of workers to run in parallel to solve your model. If the number of workers is set to n (with n greater than one), the CP optimizer will create n workers, each in their own thread, that will work together to solve the problem. The emphasis of these workers is more to find better feasible solutions and then to speed up the proof of optimality. The default value is Auto. This amounts to using as many workers as there are CPU cores available on the machine. Note that the memory required by CP Optimizer grows roughly linearly as the number of workers is increased. If you are solving a very large model on a multi-core processor and memory usage is an issue, it is advisable to specify a reduced number of workers, or even one worker, rather than use the default value.

The value is a positive integer. Default value is Auto.

get_default_value(name)

Get the default value of a given parameter name.

Parameters:

name – Parameter name

Returns:

Default parameter value, None if unknown

classmethod read_ops_file(infile)

Read an OPL-style .ops file, generating a parameter set. :param infile: Either a file name or an open file object.

Returns:

An instance of this class, containing the parameter settings.

reset_to_default()

Reset all the parameters to their default value.

Parameters are reset to their default value by being removed from this object.

class docplex.cp.parameters.ParameterDescriptor(name, type, deflt)

Bases: object

Parameter descriptor