Parameters of CP Optimizer
Users can browse CP Optimizer parameters, organized by topics.
In CP Optimizer, the parameters are represented by the enumerations
IntParam
and NumParam
.
Some of the integer values for parameters in the enumeration IntParam
are listed in the
enumeration ParameterValues
.
In the C++ API, these enumerations are
IloCP::IntParam
and IloCP::NumParam
,
and some of the values of the parameters are
IloCP::ParameterValues
.
The parameters and values are named with the prefix IloCP::
. For example:
cp.setParameter(IloCP::AllDiffInferenceLevel, IloCP::Basic);
In the Java™ API, these enumerations are
IloCP.IntParam
and
IloCP.DoubleParam
.
The parameters and values are named with the prefix IloCP.IntParam
and IloCP.DoubleParam
. For example:
cp.setParameter(IloCP.IntParam.AllDiffInferenceLevel, IloCP.ParameterValues.Basic);
In the C# API, these enumerations are
CP.IntParam
and
CP.DoubleParam
.
The parameters and values are named with the prefix CP.IntParam
and CP.DoubleParam
. For example:
cp.SetParameter(CP.IntParam.AllDiffInferenceLevel, CP.ParameterValues.Basic);
Display and output
- LogVerbosity.
- This parameter determines the verbosity of the search log.
- Type: Int
- Possible values:
Quiet
,Terse
,Normal
, andVerbose
. ModeQuiet
does not display any information, the other modes display progressively more information. - Default value:
Normal
. - Note: 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.
- 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 everyk
branches (search decisions). - Type: Int
- Possible values: Positive integers.
- 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
- 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.
- Type: Int
- Possible values: Integers from 0 to 3.
- Default value: 2.
- PrintModelDetailsInMessages.
- Whenever CP Optimizer prints an error or warning message, it can also print the relevant part of the input model (in CPO file format). This parameter controls printing of this additional information.
- Type: Int
- Possible values:
On
andOff
. - Default value:
On
.
- ModelAnonymizer.
- This parameter controls anonymization of a model dumped via the
dumpModel
method. 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. - Type: Int
- Possible values:
Off
andOn
. - Default value:
Off
.
- This parameter controls anonymization of a model dumped via the
- 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). When the value is
Off
then CP Optimizer ignores locations in the input model and also does not export them in CPO file format. - Type: Int
- Possible values:
On
andOff
. - Default value:
On
. - Note: In C++, you can only make use of file locations via the
ILOADD
macro for adding objects to a model (see the examples cpofileformat.cpp, facility_explanations.cpp and sched_conflict.cpp). For Java, this should happen automatically as long as you do not use the option-g
to disable file and line debugging when you compile your code.
- 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). When the value is
- KPIDisplay
- This parameter controls how your defined KPIs are displayed in the log. You can display your KPIs either on one line or on several lines.
- Type: Int
- Possible values:
SingleLine
andMultipleLines
- Default value:
SingleLine
Presolve
- Presolve.
- This parameter controls the presolve of the model to produce more compact formulations and to achieve more domain reduction.
- Type: Int
- Possible values:
On
(presolve is activated) andOff
(presolve is deactivated). - Default value:
On
.
Optimality tolerances
- 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. - Type: Float
- Possible values: Floating-point values from 0.0 to
IloInfinity
. - Default value: 0.
- 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.
- 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.
This parameter is used in conjunction with
OptimalityTolerance
. The optimality of a solution is proven if either of the two parameters' criteria are fulfilled. - Type: Float
- Possible values: Floating-point values from 0.0 to
IloInfinity
. - Default value: 1e-4.
- 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.
This parameter is used in conjunction with
Search control
- 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
(withn
greater than one), the CP optimizer will createn
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. - 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.
- Type: Int
- Possible values:
Auto
and positive integers. - Default value:
Auto
. This amounts to using as many workers as there are CPU cores available on the machine.
- This parameter sets the number of workers to run in parallel to solve your model. If the number of
workers is set to
- 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 toRestart
, a depth-first search that restarts from time to time is applied. When set toMultiPoint
, a method that combines a set of - possibly partial - solutions is applied. When set toAuto
in sequential mode, this value chooses the appropriate search method to be used. In generalAuto
will be the Restart search. The default value isAuto
. - 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 ofSearchType
isAuto
, 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. - When
SearchType
is set toNeighborhood
, then a local search method will be used on all workers. The local search method works on full assignments and so can explore assignments which violate constraints. By changing small parts of the current assignment, the search method tries to reduce the constraint violation. If the search finds a feasible solution (zero violations), the search will then also work on optimizing the objective. The search works best on lightly constrained problems. This feature is experimental, and will remain in Beta in CPLEX Studio version 22.1.0 (over the course of 2022) while we refine and improve it. We welcome feedback tocos-beta@wwpdl.vnet.ibm.com
. This feature currently has some restrictions. Models with some specific features are not supported: those containing interval variables, those withStaticLex
objectives, and those with black-box expressions. No workers will be launched with this search whenSearchType=Auto
. You need to useSearchType=Neighborhood
to switch all workers to this mode. Search phases will have no effect on the search.
- This parameter determines the type of search that is applied when solving a problem. When set to
-
- Type: Int
- Possible values:
Auto
,DepthFirst
,Restart
,MultiPoint
, andNeighborhood
.
- RandomSeed.
- The search uses some randomization in some strategies. This parameter sets the seed of the random generator used by these strategies.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value: 0.
- RestartFailLimit.
- When
SearchType
is set toRestart
, 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. This value can increase after each restart: see the parameterRestartGrowthFactor
. - Type: Int
- Possible values: From 0 to
IloIntMax
. - Default value: 100.
- When
- RestartGrowthFactor.
- When
SearchType
is set toRestart
, 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 wasf
after a restart, for next run, the new fail limit will bef
times the value of this parameter. The initial fail limit can be controlled with the parameterRestartFailLimit
. - Type: Float
- Possible values: Floating-point values from 1.0 to
IloInfinity
. - Default value: 1.05.
- When
- 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. The strength of probing can be defined by parameter
DynamicProbingStrength
. Dynamic probing only has an effect when using theRestart
search type, on problems without interval variables. - Type: Int
- Possible values:
Auto
(dynamic probing is activated and its strength is adjusted adaptively),On
(dynamic probing is activated with a constant strength), andOff
(dynamic probing is deactivated). - Default value:
Auto
.
- 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. The strength of probing can be defined by parameter
- DynamicProbingStrength.
- This parameter controls the effort which is dedicated to dynamic probing. It determines the ratio P/R where P is the
effort dedicated to dynamic probing, and R is the rest of the search effort.
Changing this parameter has no effect unless the
DynamicProbing
parameter is set toAuto
orOn
. WhenDynamicProbing
has valueOn
, the probing strength is held constant throughout the search process. WhenDynamicProbing
has valueAuto
, the probing strength starts off at the specified value and is thereafter adjusted automatically. - Type: Float
- Possible values: Floating-point 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.
- Default value: 0.03, meaning that around 3% of total search time is dedicated to dynamic probing.
- This parameter controls the effort which is dedicated to dynamic probing. It determines the ratio P/R where P is the
effort dedicated to dynamic probing, and R is the rest of the search effort.
Changing this parameter has no effect unless the
- 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.
- Type: Int
- Possible values are integers from 0 to
IloIntMax
. - Default value is 30.
- TemporalRelaxation.
- This advanced parameter can be used to control the usage of a temporal relaxation internal to the invoking IloCP engine.
For some models, using the relaxation becomes inefficient, and you may deactivate the use of the temporal relaxation using
value
Off
. - Type: Int
- Possible values:
On
andOff
. - Default value:
On
, meaning the relaxation is used in the engine when needed.
- This advanced parameter can be used to control the usage of a temporal relaxation internal to the invoking IloCP engine.
For some models, using the relaxation becomes inefficient, and you may deactivate the use of the temporal relaxation using
value
- 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 the 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 toRestart
orAuto
.When the value isOn
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 theFailureDirectedSearchMaxMemory
parameter. - Type: Int
- Possible values:
On
andOff
. - Default value:
On
.
- 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 the 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
- 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 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 the given number of workers. The value does not have to be integer. For example, a value of 1.5 means that the first worker spends 100% of its time on failure-directed search, the second worker spends 50% of its time on failure-directed search, and the remainder spend none of their time.
- For more information about failure-directed search see parameter
FailureDirectedSearch
. - Type: Float
- Possible values:
Auto
and floating-point values from 1.0 toIloInfinity
. - Default value:
Auto
.
- FailureDirectedSearchMaxMemory.
- This parameter controls the maximum amount of memory (in bytes) available to failure-directed search (see
FailureDirectedSearchMaxMemory
). 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.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value: 104,857,600 (100MB).
- This parameter controls the maximum amount of memory (in bytes) available to failure-directed search (see
- AutomaticReplay.
- This parameter is an advanced, low-level one for controlling the behavior of
solve()
andnext()
. When the model being solved has an objective and solve is used, or whenstartNewSearch
andnext
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. - A typical reason for setting this parameter to
Off
is, for instance, if you use your own custom goal, 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. - Type: Int
- Possible values:
On
andOff
. - Default value:
On
.
- This parameter is an advanced, low-level one for controlling the behavior of
Search limits
- TimeLimit.
- This parameter limits the CPU time spent solving before terminating a search. The time is given in seconds.
- Type: Float
- Possible values: Floating-point values from 0.0 to
IloInfinity
. - Default value:
IloInfinity
, does not set any limit.
- TimeMode.
- This parameter defines how time is measured in CP Optimizer. 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. - Type: Int
- Possible values:
ElapsedTime
andCPUTime
. - Default value:
ElapsedTime
.
- This parameter defines how time is measured in CP Optimizer. CP Optimizer uses time for both display purposes and for
limiting the search via
- FailLimit.
- This parameter limits the number of failures that can occur before terminating the search.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- ChoicePointLimit.
- This parameter limits the number of choice points that are created before terminating a search.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- 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
andx != 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). - Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- 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:
- SolutionLimit.
- This parameter limits the number of feasible solutions that are found before terminating a search.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
Inference levels for constraint propagation
- DefaultInferenceLevel.
- This parameter specifies the general inference level for constraints whose particular inference level is
Default
. - Type: Int
- Possible values: (In increasing order of inference strength.)
Low
,Basic
,Medium
, andExtended
. - Default value:
Basic
.
- This parameter specifies the general inference level for constraints whose particular inference level is
- AllDiffInferenceLevel.
- This parameter specifies the inference level for every
AllDiff
constraint extracted to the invoking CP instance. - Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of allAllDiff
constraints to be controlled viaDefaultInferenceLevel
.
- This parameter specifies the inference level for every
- DistributeInferenceLevel.
- This parameter specifies the inference level for every distribution constraint extracted to the invoked CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of all distribution constraints to be controlled viaDefaultInferenceLevel
.
- CountInferenceLevel.
- This parameter specifies the inference level for every counting constraint extracted to the invoked CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of all counting constraints to be controlled viaDefaultInferenceLevel
.
- CountDifferentInferenceLevel.
- This parameter specifies the inference level for every
countDifferent
constraint extracted to the invoking CP instance. - Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of allcountDifferent
constraints to be controlled viaDefaultInferenceLevel
.
- This parameter specifies the inference level for every
- SequenceInferenceLevel.
- This parameter specifies the inference level for every sequence constraint extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of all sequence constraints to be controlled viaDefaultInferenceLevel
.
- AllMinDistanceInferenceLevel.
- This parameter specifies the inference level for every
allMinDistance
constraint extracted to the invoking CP instance. - Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of allallMinDistance
constraints to be controlled viaDefaultInferenceLevel
.
- This parameter specifies the inference level for every
- ElementInferenceLevel.
- This parameter specifies the inference level for every element constraint extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the inference strength of all element constraints to be controlled viaDefaultInferenceLevel
.
- PrecedenceInferenceLevel.
- This parameter specifies the inference level for every precedence constraint extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the precedence strength of all element constraints to be controlled viaDefaultInferenceLevel
.
- IntervalSequenceInferenceLevel.
- This parameter specifies the inference level for every interval sequence variable extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the precedence strength of all interval sequence variable to be controlled viaDefaultInferenceLevel
.
- NoOverlapInferenceLevel.
- This parameter specifies the inference level for every no overlap constraint extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the precedence strength of all no overlap constraint to be controlled viaDefaultInferenceLevel
.
- CumulFunctionInferenceLevel.
- This parameter specifies the inference level for every cumul function extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the precedence strength of all cumul functions to be controlled viaDefaultInferenceLevel
.
- StateFunctionInferenceLevel.
- This parameter specifies the inference level for every state function extracted to the invoking CP instance.
- Type: Int
- Possible values:
Default
,Low
,Basic
,Medium
, andExtended
. - Default value:
Default
, which allows the precedence strength of all state functions to be controlled viaDefaultInferenceLevel
.
Failure explanation
- LogSearchTags.
- This parameter controls the log activation. When set to
On
, the engine will display failure tags (indices) in the engine log when solving the model. To specify the failures to explain, the member functionsexplainFailure(IloInt failureTag)
orexplainFailure(IloIntArray tagArray)
needs to be called with the failure tags as the parameter. Several failures tags can be added. The member functionclearExplanations
is used to clear the set of failure tags to be explained. To be able to see failure tags and explanations, the parameterSearchType
must be set toDepthFirst
and the parameterWorkers
to 1. - Type: Int
- Possible values:
On
andOff
. - Default value:
Off
.
- This parameter controls the log activation. When set to
Conflict refiner
- ConflictRefinerTimeLimit.
- This parameter limits the CPU time spent before terminating the conflict refiner.
- Type: Float
- Possible values: Floating-point values from 0.0 to
IloInfinity
. - Default value:
IloInfinity
, which does not set any limit.
- ConflictRefinerIterationLimit.
- This parameter limits the number of iterations that are made before terminating the conflict refiner.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- ConflictRefinerBranchLimit.
- This parameter limits the total number of branches that are made before terminating the conflict refiner.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- ConflictRefinerFailLimit.
- This parameter limits the total number of failures that can occur before terminating the conflict refiner.
- Type: Int
- Possible values: Integers from 0 to
IloIntMax
. - Default value:
IloIntMax
, which does not set any limit.
- ConflictRefinerOnVariables.
- This parameter specifies whether the conflict refiner should refine variables domains.
- Type: Int
- Possible values:
On
(conflict refiner will refine both constraints and variables domains) andOff
(conflict refiner will only refine constraints). - Default value:
Off
.