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, and Verbose. Mode Quiet 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 every k branches (search decisions).
    • Type: Int
    • Possible values: Positive integers.
  • 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 and Off.
    • 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 and On.
    • Default value: Off.
  • 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 and Off.
    • 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.
  • 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 and MultipleLines
    • 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) and Off (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.
  • 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.

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 (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.
    • 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.
  • 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 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.
    • When SearchType is set to Neighborhood, 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 to cos-beta@wwpdl.vnet.ibm.com. This feature currently has some restrictions. Models with some specific features are not supported: those containing interval variables, those with StaticLex objectives, and those with black-box expressions. No workers will be launched with this search when SearchType=Auto. You need to use SearchType=Neighborhood to switch all workers to this mode. Search phases will have no effect on the search.
    • Type: Int
    • Possible values: Auto, DepthFirst, Restart, MultiPoint, and Neighborhood.
  • 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 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. This value can increase after each restart: see the parameter RestartGrowthFactor.
    • Type: Int
    • Possible values: From 0 to IloIntMax.
    • Default value: 100.
  • 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. The initial fail limit can be controlled with the parameter RestartFailLimit.
    • Type: Float
    • Possible values: Floating-point values from 1.0 to IloInfinity.
    • Default value: 1.05.
  • 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 the Restart 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), and Off (dynamic probing is deactivated).
    • Default value: Auto.
  • 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 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.
    • 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.
  • 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 and Off.
    • Default value: On, meaning the relaxation is used in the engine when needed.
  • 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 to Restart or Auto.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.
    • Type: Int
    • Possible values: On and Off.
    • Default value: On.
  • 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 to IloInfinity.
    • 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).
  • 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.
    • 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 and Off.
    • Default value: On.

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 and CPUTime.
    • Default value: ElapsedTime.
  • 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 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).
    • Type: Int
    • Possible values: Integers from 0 to IloIntMax.
    • Default value: IloIntMax, which does not set any limit.
  • 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, and Extended.
    • Default value: Basic.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all AllDiff constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all distribution constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all counting constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all countDifferent constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all sequence constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all allMinDistance constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the inference strength of all element constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the precedence strength of all element constraints to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the precedence strength of all interval sequence variable to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the precedence strength of all no overlap constraint to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the precedence strength of all cumul functions to be controlled via DefaultInferenceLevel.
  • 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, and Extended.
    • Default value: Default, which allows the precedence strength of all state functions to be controlled via DefaultInferenceLevel.

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 functions explainFailure(IloInt failureTag) or explainFailure(IloIntArray tagArray) needs to be called with the failure tags as the parameter. Several failures tags can be added. The member function clearExplanations is used to clear the set of failure tags to be explained. To be able to see failure tags and explanations, the parameter SearchType must be set to DepthFirst and the parameter Workers to 1.
    • Type: Int
    • Possible values: On and Off.
    • Default value: Off.

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) and Off (conflict refiner will only refine constraints).
    • Default value: Off.