Class Parameters

Namespace: OptalCP

Assembly: OptalCP.dll

Parameters specify how the solver should behave.

public class Parameters

Inheritance: object

Parameters

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Parameters specify how the solver should behave. For example, the number of workers (threads) to use, the time limit, etc.

Parameters can be passed to the solver functions Model.Solve and Solver.Solve.

Example:

In the following example, we are using the _TimeLimit_ parameter to specify that the solver should stop after 5 minutes. We also specify that the solver should use 4 threads. Finally, we specify that the solver should use _FDS_ search (in all threads).

var parameters = new Parameters {
    timeLimit = 300,    // In seconds, i.e. 5 minutes
    nbWorkers = 4,     // Use 4 threads
    searchType = "FDS",
};
var result = myModel.Solve(parameters);

Worker-specific parameters

Some parameters can be specified differently for each worker. For example, some workers may use LNS search while others use FDS search. To specify worker-specific parameters, use the workers parameter and pass an array of WorkerParameters.

Not all parameters can be specified per worker. For example, TimeLimit is a global parameter. See WorkerParameters for the list of parameters that can be specified per worker.

If a parameter is not set specifically for a worker, the global value is used.

Example:

In the following example, we are going to use 4 workers; two of them will run FDS search and the remaining two will run LNS search. In addition, workers that use FDS search will use increased propagation levels.

// Parameters for a worker that uses FDS search:
var fdsWorker = new WorkerParameters {
    searchType = "FDS",
    noOverlapPropagationLevel = 4,
    cumulPropagationLevel = 3,
    reservoirPropagationLevel = 2,
};
// Global parameters:
var parameters = new Parameters {
    timeLimit = 60,
    searchType = "LNS",
    nbWorkers = 4,
    workers = new List<WorkerParameters> { fdsWorker, fdsWorker },
};
var result = myModel.Solve(parameters);

See also:

WorkerParameters — for worker-specific parameters.

Constructors

Parameters()

Parameters specify how the solver should behave.

public Parameters()

Remarks

Parameters specify how the solver should behave. For example, the number of workers (threads) to use, the time limit, etc.

Parameters can be passed to the solver functions Model.Solve and Solver.Solve.

Example:

var parameters = new Parameters {
    timeLimit = 300,    // In seconds, i.e. 5 minutes
    nbWorkers = 4,     // Use 4 threads
    searchType = "FDS",
};
var result = myModel.Solve(parameters);

Worker-specific parameters

Not all parameters can be specified per worker. For example, TimeLimit is a global parameter. See WorkerParameters for the list of parameters that can be specified per worker.

If a parameter is not set specifically for a worker, the global value is used.

Example:

// Parameters for a worker that uses FDS search:
var fdsWorker = new WorkerParameters {
    searchType = "FDS",
    noOverlapPropagationLevel = 4,
    cumulPropagationLevel = 3,
    reservoirPropagationLevel = 2,
};
// Global parameters:
var parameters = new Parameters {
    timeLimit = 60,
    searchType = "LNS",
    nbWorkers = 4,
    workers = new List<WorkerParameters> { fdsWorker, fdsWorker },
};
var result = myModel.Solve(parameters);

See also:

WorkerParameters — for worker-specific parameters.

Properties

absoluteGapTolerance

Stop the search when the gap is below the tolerance

public double? absoluteGapTolerance { get; set; }

Property Value

double?

Remarks

The search is stopped if the absolute difference between the current solution value and current lower/upper bound is not bigger than the specified value.

This parameter works together with Parameters.relativeGapTolerance as an OR condition: the search stops when either the absolute gap or the relative gap is within tolerance.

The parameter takes a floating point value.

The default value is 0.

allocationBlockSize

The minimal amount of memory in kB for a single allocation

public long? allocationBlockSize { get; set; }

Property Value

long?

Remarks

The solver allocates memory in blocks. This parameter sets the minimal size of a block. Larger blocks mean a higher risk of wasting memory. However, larger blocks may also lead to better performance, particularly when the size matches the page size supported by the operating system.

The value of this parameter must be a power of 2.

The default value of 2048 means 2MB, which means that up to ~12MB can be wasted per worker in the worst case.

The parameter takes an integer value in range 4..1073741824.

The default value is 2048.

color

Whether to colorize output to the terminal

public string? color { get; set; }

Property Value

string

Remarks

This parameter controls when terminal output is colorized. Possible values are:

Never: don't colorize the output.
Auto: colorize if the output is a supported terminal.
Always: always colorize the output.

The default value is Auto.

cumulPropagationLevel

How much to propagate constraints on cumul functions

public long? cumulPropagationLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of propagation done for cumulative constraints (e.g., cumul <= limit) when used with a sum of Model.Pulse pulses.

Higher levels use more sophisticated algorithms that can detect more infeasibilities and prune more values from domains, but at the cost of increased computation time.

Propagation levels:

Level 1: Basic timetable propagation
Level 2: Adds time-table edge-finding
Level 3: Maximum propagation with all available algorithms

Automatic selection (level 0):

When set to 0 (the default), the propagation level is determined automatically based on the Parameters.preset:

Default preset: Uses level 3 (maximum propagation)
Large preset: Uses level 1 (minimum propagation for scalability)

Performance considerations:

More propagation doesn't necessarily mean better overall performance. The trade-off depends on your problem:

Resource-constrained problems with tight capacity limits often benefit from higher propagation levels because cumulative reasoning can prune many infeasible assignments.
Problems with loose resource constraints may not benefit much from higher levels because the extra computation doesn't lead to significant pruning.
Very large problems may perform better with lower propagation levels because the overhead becomes prohibitive.
FDS search (see Parameters.searchType) typically benefits from higher propagation levels.

If you're unsure, start with the automatic selection (level 0) and let the preset choose.

var model = new Model();
// ... build your model with cumulative constraints ...

// Let the preset decide (default)
var result = model.Solve();

// Or use maximum propagation for resource-constrained problems
result = model.Solve(new Parameters { cumulPropagationLevel = 3 });

// Or use minimum propagation for very large problems
result = model.Solve(new Parameters { cumulPropagationLevel = 1 });

See also:

Parameters.preset — for automatic configuration of propagation levels.
Parameters.searchType — for choosing the search algorithm.
Model.Pulse — for creating pulse contributions to cumulative functions.

fdsAdditionalStepRatio

Domain split ratio when run out of choices

public double? fdsAdditionalStepRatio { get; set; }

Property Value

double?

Remarks

When all choices are decided, and a greedy algorithm cannot find a solution, then more choices are generated by splitting domains into the specified number of pieces.

The parameter takes a floating point value in range 2.0..Infinity.

The default value is 7.

fdsBothFailRewardFactor

How much to improve rating when both branches fail immediately

public double? fdsBothFailRewardFactor { get; set; }

Property Value

double?

Remarks

This parameter sets a bonus reward for a choice when both left and right branches fail immediately. Current rating of both branches is multiplied by the specified value.

The parameter takes a floating point value in range 0..1.

The default value is 0.98.

fdsBranchOnObjective

Whether to generate choices for objective expression/variable

public bool? fdsBranchOnObjective { get; set; }

Property Value

bool?

Remarks

This option controls the generation of choices on the objective. It works regardless of the objective is given by an expression or a variable.

The default value is False.

fdsBranchOrdering

Controls which side of a choice is explored first (considering the rating).

public string? fdsBranchOrdering { get; set; }

Property Value

string

Remarks

This option can take the following values:

FailureFirst: Explore the failure side first.
FailureLast: Explore the failure side last.
Random: Explore either side randomly.

The default value is FailureFirst.

fdsDualResetRatings

Whether to reset ratings when a new LB is proved

public bool? fdsDualResetRatings { get; set; }

Property Value

bool?

Remarks

When this parameter is on, and FDSDual proves a new lower bound, then all ratings are reset to default values.

The default value is False.

fdsDualStrategy

A strategy to choose objective cuts during FDSDual search.

public string? fdsDualStrategy { get; set; }

Property Value

string

Remarks

Possible values are:

Minimum: Always change the cut by the minimum amount.
Random: At each restart, randomly choose a value in range LB..UB. The default.
Split: Always split the current range LB..UB in half.

The default value is Random.

fdsEpsilon

How often to chose a choice randomly

public double? fdsEpsilon { get; set; }

Property Value

double?

Remarks

Probability that a choice is taken randomly. A randomly selected choice is not added to the search tree automatically. Instead, the choice is tried, its rating is updated, but it is added to the search tree only if one of the branches fails. The mechanism is similar to strong branching.

The parameter takes a floating point value in range 0.0..0.99999.

The default value is 0.1.

fdsEventTimeInfluence

Influence of event time to initial choice rating

public double? fdsEventTimeInfluence { get; set; }

Property Value

double?

Remarks

When non-zero, the initial choice rating is influenced by the date of the choice. This way, very first choices in the search should be taken chronologically.

The parameter takes a floating point value in range 0..1.

The default value is 0.

fdsFixedAlpha

When non-zero, alpha factor for rating updates

public double? fdsFixedAlpha { get; set; }

Property Value

double?

Remarks

When this parameter is set to a non-zero, parameter FDSRatingAverageLength is ignored. Instead, the rating of a branch is computed as an exponential moving average with the given parameter alpha.

The parameter takes a floating point value in range 0..1.

The default value is 0.

fdsInitialRating

Initial rating for newly created choices

public double? fdsInitialRating { get; set; }

Property Value

double?

Remarks

Default rating for newly created choices. Both left and right branches get the same rating. Choice is initially permuted so that bigger domain change is the left branch.

The parameter takes a floating point value in range 0.0..2.0.

The default value is 0.5.

fdsInitialRestartLimit

Fail limit for the first restart

public long? fdsInitialRestartLimit { get; set; }

Property Value

long?

Remarks

Failure-directed search is periodically restarted: explored part of the current search tree is turned into a no-good constraint, and the search starts again in the root node. This parameter specifies the size of the very first search tree (measured in number of failures).

The parameter takes an integer value in range 1..9223372036854775807.

The default value is 100.

fdsLengthStepRatio

Choice step relative to average length

public double? fdsLengthStepRatio { get; set; }

Property Value

double?

Remarks

Ratio of initial choice step size to the minimum length of interval variable. When FDSUniformChoiceStep is set, this ratio is used to compute global choice step using the average of interval var length. When FDSUniformChoiceStep is not set, this ratio is used to compute the choice step for every interval var individually.

The parameter takes a floating point value in range 0.0..Infinity.

The default value is 0.699999988079071.

fdsMaxCounterAfterRestart

Truncate choice use counts after a restart to this value

public long? fdsMaxCounterAfterRestart { get; set; }

Property Value

long?

Remarks

The idea is that ratings learned in the previous restart are less valid in the new restart. Using this parameter, it is possible to truncate use counts on choices so that new local ratings will have bigger weights (when FDSFixedAlpha is not used).

The parameter takes an integer value.

The default value is 255.

fdsMaxCounterAfterSolution

Truncate choice use counts after a solution is found

public long? fdsMaxCounterAfterSolution { get; set; }

Property Value

long?

Remarks

Similar to Parameters.fdsMaxCounterAfterRestart, this parameter allows truncating use counts on choices when a solution is found.

The parameter takes an integer value.

The default value is 255.

fdsMaxInitialChoicesPerVariable

Maximum number of choices generated initially per a variable

public long? fdsMaxInitialChoicesPerVariable { get; set; }

Property Value

long?

Remarks

Initial domains are often very large (e.g., 0..IntervalMax). Therefore initial number of generated choices is limited: only choices near startMin are kept.

The parameter takes an integer value in range 2..2147483647.

The default value is 90.

fdsMaxInitialLengthChoices

Maximum number of initial choices on length of an interval variable

public long? fdsMaxInitialLengthChoices { get; set; }

Property Value

long?

Remarks

When non-zero, this parameter limits the number of initial choices generated on length of an interval variable. When zero (the default), no choices on length are generated.

The parameter takes an integer value in range 0..2147483647.

The default value is 0.

fdsMinIntVarChoiceStep

Minimum step when generating choices for integer variables.

public long? fdsMinIntVarChoiceStep { get; set; }

Property Value

long?

Remarks

Steps between choices for integer variables are never smaller than the specified value.

The parameter takes an integer value in range 1..1073741823.

The default value is 1073741823.

fdsMinLengthChoiceStep

Maximum step when generating initial choices for length of an interval variable

public long? fdsMinLengthChoiceStep { get; set; }

Property Value

long?

Remarks

Steps between choices for length of an interval variable are never bigger than the specified value.

The parameter takes an integer value in range 1..1073741823.

The default value is 1073741823.

fdsPresenceStatusChoices

Whether to generate choices on presence status

public bool? fdsPresenceStatusChoices { get; set; }

Property Value

bool?

Remarks

Choices on start time also include a choice on presence status. Therefore, dedicated choices on presence status only are not mandatory.

The default value is True.

fdsRatingAverageComparison

Whether to compare the local rating with the average

public string? fdsRatingAverageComparison { get; set; }

Property Value

string

Remarks

Possible values are:

Off (the default): No comparison is done.
Global: Compare with the global average.
Depth: Compare with the average on the current search depth

Arithmetic average is used for global and depth averages.

The default value is Off.

fdsRatingAverageLength

Length of average rating computed for choices

public long? fdsRatingAverageLength { get; set; }

Property Value

long?

Remarks

For the computation of rating of a branch. Arithmetic average is used until the branch is taken at least FDSRatingAverageLength times. After that exponential moving average is used with parameter alpha = 1 - 1 / FDSRatingAverageLength.

The parameter takes an integer value in range 0..254.

The default value is 25.

fdsReductionFactor

Reduction factor R for rating computation

public string? fdsReductionFactor { get; set; }

Property Value

string

Remarks

Possible values are:

Normal (the default): Normal reduction factor.
Zero: Factor is not used (it is 0 all the time).
Random: A random number in the range [0,1] is used instead.

The default value is Normal.

fdsReductionWeight

Weight of the reduction factor in rating computation

public double? fdsReductionWeight { get; set; }

Property Value

double?

Remarks

When computing the local rating of a branch, multiply reduction factor by the given weight.

The parameter takes a floating point value in range 0.0..Infinity.

The default value is 1.

fdsResetRestartsAfterSolution

Reset restart size after a solution is found (ignored in Luby)

public bool? fdsResetRestartsAfterSolution { get; set; }

Property Value

bool?

Remarks

When this parameter is set (the default), then restart limit is set back to Parameters.fdsInitialRestartLimit when a solution is found.

The default value is True.

fdsRestartGrowthFactor

Growth factor for fail limit after each restart

public double? fdsRestartGrowthFactor { get; set; }

Property Value

double?

Remarks

After each restart, the fail limit for the restart is multiplied by the specified factor. This parameter is ignored when Parameters.fdsRestartStrategy is Luby.

The parameter takes a floating point value in range 1.0..Infinity.

The default value is 1.15.

fdsRestartStrategy

Restart strategy to use

public string? fdsRestartStrategy { get; set; }

Property Value

string

Remarks

This parameter specifies how the restart limit (maximum number of failures) changes from restart to restart. Possible values are:

Geometric (the default): After each restart, restart limit is multiplied by Parameters.fdsRestartGrowthFactor.
Nested: Similar to Geometric but the limit is changed back to Parameters.fdsInitialRestartLimit each time a new maximum limit is reached.
Luby: Luby restart strategy is used. Parameter Parameters.fdsRestartGrowthFactor is ignored.

The default value is Geometric.

fdsReuseClosing

Whether always reuse closing choice

public bool? fdsReuseClosing { get; set; }

Property Value

bool?

Remarks

Most of the time, FDS reuses closing choice automatically. This parameter enforces it all the time.

The default value is False.

fdsStrongBranchingCriterion

How to choose the best choice in strong branching

public string? fdsStrongBranchingCriterion { get; set; }

Property Value

string

Remarks

Possible values are:

Both: Choose the the choice with best combined rating.
Left (the default): Choose the choice with the best rating of the left branch.
Right: Choose the choice with the best rating of the right branch.

The default value is Left.

fdsStrongBranchingDepth

Up-to what search depth apply strong branching

public long? fdsStrongBranchingDepth { get; set; }

Property Value

long?

Remarks

Strong branching is typically used in the root node. This parameter controls the maximum search depth when strong branching is used.

The parameter takes an integer value.

The default value is 6.

fdsStrongBranchingSize

Number of choices to try in strong branching

public long? fdsStrongBranchingSize { get; set; }

Property Value

long?

Remarks

Strong branching means that instead of taking a choice with the best rating, we take the specified number (FDSStrongBranchingSize) of best choices, try them in dry-run mode, measure their local rating, and then chose the one with the best local rating.

The parameter takes an integer value.

The default value is 10.

fdsUniformChoiceStep

Whether all initial choices have the same step length

public bool? fdsUniformChoiceStep { get; set; }

Property Value

bool?

Remarks

When set, then initial choices generated on interval variables will have the same step size.

The default value is True.

fdsUseNogoods

Whether to use or not nogood constraints

public bool? fdsUseNogoods { get; set; }

Property Value

bool?

Remarks

By default, no-good constraint is generated after each restart. This parameter allows to turn no-good constraints off.

The default value is True.

infoTraceLevel

Level of information trace

public long? infoTraceLevel { get; set; }

Property Value

long?

Remarks

This parameter is available only in the development edition of the solver.

When set to a value bigger than zero, the solver prints various high-level information. The higher the value, the more information is printed.

The parameter takes an integer value in range 0..5.

The default value is 0.

integralPropagationLevel

How much to propagate integral expression

public long? integralPropagationLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of propagation done for Model.Integral expressions. In particular, it controls whether the propagation also affects the minimum and the maximum length of the associated interval variable:

1: The length is updated only once during initial constraint propagation.
2: The length is updated every time the expression is propagated.

The parameter takes an integer value in range 1..2.

The default value is 1.

lnsMode

LNS solution pool strategy.

public string? lnsMode { get; set; }

Property Value

string

Remarks

Controls how LNS manages its solution pool.

Robust: Maintain multiple solution tiers for diverse exploration (the default). The solver keeps several solutions of varying quality and occasionally works on improving worse solutions. This provides robustness against getting stuck in local optima.
Focused: Concentrate all LNS effort on improving the best solution. Secondary solution tiers are disabled, reducing memory and CPU overhead. Recommended for large problems where maintaining multiple solutions is too expensive.

The Large Parameters.preset automatically selects Focused mode. If you explicitly set lnsMode, your value takes precedence over the preset.

var model = new Model();
// ... build your model ...

// Default: robust mode with multiple solution tiers
var result = model.Solve();

// Focused mode for large problems
result = model.Solve(new Parameters { lnsMode = "Focused" });

// Or use the Large preset, which enables Focused mode automatically
result = model.Solve(new Parameters { preset = "Large" });

See also:

Parameters.preset — for automatic configuration based on problem size.
Parameters.searchType — for choosing the search algorithm.

lnsUseWarmStartOnly

Use only the user-provided warm start as the initial solution in LNS

public bool? lnsUseWarmStartOnly { get; set; }

Property Value

bool?

Remarks

When this parameter is on, the solver will use only the user-specified warm start solution for the initial solution phase in LNS. If no warm start is provided, the solver will search for its own initial solution as usual.

The default value is False.

logLevel

Level of the log

public long? logLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of text the solver writes on standard output. The solver is completely silent when this option is set to 0.

The parameter takes an integer value in range 0..3.

The default value is 2.

logPeriod

How often to print log messages (in seconds)

public double? logPeriod { get; set; }

Property Value

double?

Remarks

When Parameters.logLevel ≥ 2 then solver writes a log message every logPeriod seconds. The log message contains the current statistics about the solve: number of branches, number of fails, memory used, etc.

The parameter takes a floating point value in range 0.01..Infinity.

The default value is 10.

nbWorkers

Number of threads dedicated to search

public long? nbWorkers { get; set; }

Property Value

long?

Remarks

When this parameter is 0 (the default), the number of workers is determined the following way:

If environment variable OPTALCP_NB_WORKERS is set, its value is used.
Otherwise, all available cores are used.

The parameter takes an integer value.

The default value is 0.

noOverlapPropagationLevel

How much to propagate noOverlap constraints

public long? noOverlapPropagationLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of propagation done for noOverlap constraints. Higher levels use more sophisticated algorithms that can detect more infeasibilities and prune more values from domains, but at the cost of increased computation time.

Propagation levels:

Level 1: Basic timetable propagation only
Level 2: Adds detectable precedences algorithm
Level 3: Adds edge-finding reasoning
Level 4: Maximum propagation with all available algorithms

Automatic selection (level 0):

When set to 0 (the default), the propagation level is determined automatically based on the Parameters.preset:

Default preset: Uses level 4 (maximum propagation)
Large preset: Uses level 1 (minimum propagation for scalability)

Performance considerations:

More propagation doesn't necessarily mean better overall performance. The trade-off depends on your problem:

Dense scheduling problems with many overlapping intervals often benefit from higher propagation levels because the extra pruning reduces the search space significantly.
Sparse problems or very large problems may perform better with lower propagation levels because the overhead of sophisticated algorithms outweighs the benefit.
FDS search (see Parameters.searchType) typically benefits from higher propagation levels because it relies on strong propagation to guide the search.

If you're unsure, start with the automatic selection (level 0) and let the preset choose. You can then experiment with explicit levels if needed.

var model = new Model();
// ... build your model with noOverlap constraints ...

// Let the preset decide (default)
var result = model.Solve();

// Or use maximum propagation for dense problems
result = model.Solve(new Parameters { noOverlapPropagationLevel = 4 });

// Or use minimum propagation for very large problems
result = model.Solve(new Parameters { noOverlapPropagationLevel = 1 });

See also:

Parameters.preset — for automatic configuration of propagation levels.
Parameters.searchType — for choosing the search algorithm.
Model.NoOverlap — for creating noOverlap constraints.

positionPropagationLevel

How much to propagate position expressions on noOverlap constraints

public long? positionPropagationLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of propagation done for position expressions on noOverlap constraints. The bigger the value, the more algorithms are used for propagation. It means that more time is spent by the propagation, and possibly more values are removed from domains. However, more propagation doesn't necessarily mean better performance. FDS search (see Parameters.searchType) usually benefits from higher propagation levels.

The parameter takes an integer value in range 1..3.

The default value is 2.

preset

Preset configuration for solver parameters

public string? preset { get; set; }

Property Value

string

Remarks

Presets provide reasonable default values for multiple solver parameters at once. Instead of manually tuning individual parameters, you can select a preset that matches your problem characteristics. The solver will then configure search strategies and propagation levels appropriately.

Available presets:

Auto: The solver automatically selects a preset based on problem size (the default). Problems with more than 100,000 variables use Large, otherwise Default.
Default: Balanced configuration for most problems. Uses maximum propagation levels and distributes workers across different search strategies: half use LNS, 3/8 use FDS, and the rest use FDSDual. This provides a good mix of exploration and exploitation.
Large: Optimized for big problems with more than 100,000 variables. Uses minimum propagation to reduce overhead, all workers use LNS search, and Parameters.lnsMode is set to Focused. This trades propagation strength for scalability.

Parameters affected by presets:

The preset sets default values for the following parameters:

Parameters.searchType: How workers are distributed across LNS, FDS, and FDSDual
Parameters.lnsMode: LNS solution pool strategy (Large preset selects Focused)
Parameters.noOverlapPropagationLevel: Propagation strength for noOverlap constraints
Parameters.cumulPropagationLevel: Propagation strength for cumulative constraints

When you explicitly set any of these parameters, your value takes precedence over the preset's default. This allows you to use a preset as a starting point and fine-tune specific parameters as needed.

When to use presets:

Presets are a good starting point for most problems. They are not guaranteed to be optimal for your specific problem, but they provide reasonable defaults that work well in practice. If you find that the default preset is not working well for your problem, consider:

Trying the Large preset for very big problems, even if they have fewer than 100,000 variables
Explicitly setting Parameters.searchType to use a specific search strategy
Adjusting propagation levels based on your problem structure

var model = new Model();
// ... build your model ...

// Use automatic preset selection
var result = model.Solve();

// Or explicitly select a preset for a large problem
result = model.Solve(new Parameters { preset = "Large" });

// Or use Default preset but override search type
result = model.Solve(new Parameters { preset = "Default", searchType = "FDS" });

See also:

Parameters.searchType — for choosing the search algorithm.
Parameters.noOverlapPropagationLevel — for tuning noOverlap propagation.
Parameters.cumulPropagationLevel — for tuning cumulative propagation.

printLog

Where to write solver log output.

public TextWriter? printLog { get; set; }

Property Value

TextWriter

Remarks

Controls where solver log messages, warnings, and errors are written during solving.

null (default): Write to console (Console.Out)
A TextWriter instance: Write to the provided writer

Note that setting printLog to null only suppresses custom redirection; the solver still writes to console by default. The solver still emits log, warning, and error events that can be intercepted using callback properties (Solver.OnLog, Solver.OnWarning, Solver.OnError). To reduce the amount of logging at the source, use Parameters.logLevel.

ANSI colors: When writing to a stream, the solver automatically detects whether the stream supports colors by checking if it is a TTY. To override automatic detection, use the Parameters.color parameter.

If the output writer throws (e.g., a broken pipe), the solver stops as soon as possible.

Example:

var model = new Model();
// Default - logs to console
var result = model.Solve();
// Write logs to a file
using var logFile = new StreamWriter("solver.log");
var result2 = model.Solve(new Parameters { printLog = logFile });

See also:

Parameters.logLevel — to control verbosity.
Parameters.color — to override automatic color detection.

processExitTimeout

Timeout for solver process to exit after finishing

public double? processExitTimeout { get; set; }

Property Value

double?

Remarks

After the solver finishes, wait up to this many seconds for the process to exit. If it doesn't exit in time, it is silently killed.

The parameter takes a floating point value in range 0.0..Infinity.

The default value is 3.

propagationTraceLevel

Level of propagation trace

public long? propagationTraceLevel { get; set; }

Property Value

long?

Remarks

This parameter is available only in the development edition of the solver.

When set to a value bigger than zero, the solver prints a trace of the propagation, that is a line for every domain change. The higher the value, the more information is printed.

The parameter takes an integer value in range 0..5.

The default value is 0.

randomSeed

Random seed

public long? randomSeed { get; set; }

Property Value

long?

Remarks

The solver breaks ties randomly using a pseudorandom number generator. This parameter sets the seed of the generator.

Note that when Parameters.nbWorkers is more than 1 then there is also another source of randomness: the time it takes for a message to pass from one worker to another. Therefore with 1 worker the solver is deterministic (random behavior depends only on random seed). With more workers the solver is not deterministic.

Even with the same random seed, the solver may behave differently on different platforms. This can be due to different implementations of certain functions such as std::sort.

The parameter takes an integer value.

The default value is 1.

Environment variable OPTALCP_RANDOM_SEED

When randomSeed is not explicitly set (i.e. it remains at its default value of 1), the solver checks the environment variable OPTALCP_RANDOM_SEED. If the variable is set:

A numeric value (e.g. 42) is used directly as the random seed.
The special value RANDOM (case-insensitive) tells the solver to generate a time-based seed.

This is useful for randomizing test runs without changing application code.

relativeGapTolerance

Stop the search when the gap is below the tolerance

public double? relativeGapTolerance { get; set; }

Property Value

double?

Remarks

The search is stopped if the relative difference between the current solution value and current lower/upper bound is not bigger than the specified value.

This parameter works together with Parameters.absoluteGapTolerance as an OR condition: the search stops when either the absolute gap or the relative gap is within tolerance.

The parameter takes a floating point value.

The default value is 0.0001.

reservoirPropagationLevel

How much to propagate constraints on cumul functions

public long? reservoirPropagationLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the amount of propagation done for cumulative constraints (e.g., cumul <= limit, cumul >= limit) when used together with steps (Model.StepAtStart, Model.StepAtEnd, Model.StepAt). The bigger the value, the more algorithms are used for propagation. It means that more time is spent by the propagation, and possibly more values are removed from domains. More propagation doesn't necessarily mean better performance. FDS search (see Parameters.searchType) usually benefits from higher propagation levels.

The parameter takes an integer value in range 1..2.

The default value is 1.

searchTraceLevel

Level of search trace

public long? searchTraceLevel { get; set; }

Property Value

long?

Remarks

This parameter is available only in the development edition of the solver.

When set to a value bigger than zero, the solver prints a trace of the search. The trace contains information about every choice taken by the solver. The higher the value, the more information is printed.

The parameter takes an integer value in range 0..5.

The default value is 0.

searchType

Type of search to use

public string? searchType { get; set; }

Property Value

string

Remarks

This parameter controls which search algorithm the solver uses. Different search types have different strengths:

Auto: Automatically determined based on the Parameters.preset (the default). With the Default preset, workers are distributed across LNS, FDS, and FDSDual. With the Large preset, all workers use LNS.
LNS: Large Neighborhood Search. Starts from an initial solution and iteratively improves it by relaxing and re-optimizing parts of the solution. Good for finding high-quality solutions quickly, especially on large problems. Works best when a good initial solution can be found.
FDS: Failure-Directed Search. A systematic search that learns from failures to guide exploration. Uses restarts with no-good learning. Often effective at proving optimality and works well with strong propagation.
FDSDual: Failure-Directed Search working on objective bounds. Similar to FDS but focuses on proving bounds on the objective value. Useful for optimization problems where you want to know how far from optimal your solutions are.
SetTimes: Depth-first set-times search (not restarted). A simple chronological search that assigns start times in order. Can be effective for tightly constrained problems but generally less robust than other methods.

Interaction with presets:

When searchType is set to Auto, the actual search type is determined by the Parameters.preset:

Default preset: Distributes workers across different search types. Half use LNS, 3/8 use FDS, and the rest use FDSDual. This portfolio approach provides robustness across different problem types.
Large preset: All workers use LNS. For very large problems, the overhead of systematic search methods like FDS becomes prohibitive, so LNS is used exclusively.

If you explicitly set searchType to a specific value (not Auto), that value is used regardless of the preset.

var model = new Model();
// ... build your model ...

// Let the preset decide (default behavior)
var result = model.Solve();

// Or explicitly use FDS for systematic search
result = model.Solve(new Parameters { searchType = "FDS" });

// Or use LNS for quick solutions on large problems
result = model.Solve(new Parameters { searchType = "LNS" });

See also:

Parameters.preset — for automatic configuration of search and propagation.
Parameters.noOverlapPropagationLevel — which works well with FDS at higher levels.

simpleLBMaxIterations

Maximum number of feasibility checks

public long? simpleLBMaxIterations { get; set; }

Property Value

long?

Remarks

Simple lower bound is computed by binary search for the best objective value that is not infeasible by propagation. This parameter limits the maximum number of iterations of the binary search. When the value is 0, then simple lower bound is not computed at all.

The parameter takes an integer value in range 0..2147483647.

The default value is 2147483647.

simpleLBShavingRounds

Number of shaving rounds

public long? simpleLBShavingRounds { get; set; }

Property Value

long?

Remarks

When non-zero, the solver shaves on variable domains to improve the lower bound. This parameter controls the number of shaving rounds.

The parameter takes an integer value in range 0..2147483647.

The default value is 0.

simpleLBWorker

Which worker computes simple lower bound

public long? simpleLBWorker { get; set; }

Property Value

long?

Remarks

Simple lower bound is a bound such that infeasibility of a better objective can be proved by propagation only (without the search). The given worker computes simple lower bound before it starts the normal search. If a worker with the given number doesn't exist, then the lower bound is not computed.

The parameter takes an integer value in range -1..2147483647.

The default value is 0.

solutionLimit

Stop the search after the given number of solutions

public long? solutionLimit { get; set; }

Property Value

long?

Remarks

Terminates the solve after the specified number of solutions have been found and reported.

Automatic behavior (value 0):

When set to 0 (the default), the limit is determined automatically based on the problem type:

Decision problems (no objective): The solver stops after finding the first solution. This is usually what you want for feasibility problems.
Optimization problems: No limit is applied. The solver continues searching for better solutions until it proves optimality, hits another limit (like Parameters.timeLimit), or is stopped manually.

Explicit values:

You can set an explicit limit to control solution enumeration:

1: Stop after the first solution. Useful when you just need any feasible solution quickly, even for optimization problems.
N > 1: Find up to N solutions. Useful for:
- Generating multiple alternative solutions for warm starts
- Enumerating all solutions to small problems
- Finding a diverse set of solutions for analysis

Note on optimization problems:

For optimization problems, only improving solutions are counted. If you set solutionLimit=5, the solver will stop after finding 5 solutions, each better than the previous. Non-improving solutions (which can occur during the search) are not counted toward the limit.

Note on LNS and decision problems:

When using LNS search (see Parameters.searchType) on decision problems (no objective), be aware that LNS may report duplicate solutions. LNS works by iteratively improving a solution, and for decision problems without an objective to guide the search, it may find the same solution multiple times. If you need unique solutions, consider using FDS search instead, or filter duplicates in your application code.

var model = new Model();
// ... build your model ...

// Automatic behavior (default)
var result = model.Solve();

// Stop after first solution
result = model.Solve(new Parameters { solutionLimit = 1 });

// Find up to 10 solutions for warm starts
result = model.Solve(new Parameters { solutionLimit = 10 });

See also:

Parameters.timeLimit — for limiting solve time.

solver

Path to the solver executable or WebSocket URL.

public string? solver { get; set; }

Property Value

string

Remarks

Specifies how to connect to the solver.

The value should be a path to the optalcp executable (e.g., /usr/bin/optalcp). The API spawns the solver as a subprocess.

If not specified, the solver is searched as described in Solver.FindSolver.

See also:

Solver.FindSolver — for solver discovery logic.
Parameters.solverArgs — for additional subprocess arguments.

solverArgs

Additional command-line arguments for the solver subprocess.

public string[]? solverArgs { get; set; }

Property Value

string[]

Remarks

These arguments are passed directly to the solver subprocess when it is spawned. This parameter is only used in subprocess mode (not when connecting to a remote solver via WebSocket).

This can be useful for debugging or passing special flags to the solver that are not exposed through the Parameters API.

var model = new Model();
// ... build model ...

// Pass custom arguments to the solver
var result = model.Solve(new Parameters {
    solverArgs = new[] { "--some-debug-flag" },
    timeLimit = 60,
});

See also:

Parameters.solver — to specify a custom solver path.

timeLimit

Wall clock limit for execution in seconds

public double? timeLimit { get; set; }

Property Value

double?

Remarks

Caps the total wall-clock time spent by the solver. The timer starts as soon as the solve begins, and it includes presolve, search, and verification. When the limit is reached, all workers stop cooperatively. Leave it at the default Infinity to run without a time bound.

The parameter takes a floating point value in range 0.0..Infinity.

The default value is Infinity.

usePrecedenceEnergy

Whether to use precedence energy propagation algorithm

public long? usePrecedenceEnergy { get; set; }

Property Value

long?

Remarks

Precedence energy algorithm improves propagation of precedence constraints when an interval has multiple predecessors (or successors) which use the same resource (noOverlap or cumulative constraint). In this case, the predecessors (or successors) may be in disjunction. Precedence energy algorithm can leverage this information and propagate the precedence constraint more aggressively.

The parameter takes an integer value: 0 to disable, 1 to enable.

The default value is 0.

verifyExternalSolutions

Whether to verify correctness of external solutions

public bool? verifyExternalSolutions { get; set; }

Property Value

bool?

Remarks

External solutions can be passed to the solver as a warm start via Model.Solve, or using Solver.SendSolution during the search. Normally, all external solutions are checked before they are used. However, the check may be time consuming, especially if too many external solutions are sent simultaneously. This parameter allows to turn the check off.

The default value is True.

verifySolutions

When on, the correctness of solutions is verified

public bool? verifySolutions { get; set; }

Property Value

bool?

Remarks

Verification is an independent algorithm that checks whether all constraints in the model are satisfied (or absent), and that objective value was computed correctly. Verification is a somewhat redundant process as all solutions should be correct. Its purpose is to double-check and detect bugs in the solver.

The default value is False.

warningLevel

Level of warnings

public long? warningLevel { get; set; }

Property Value

long?

Remarks

This parameter controls the types of warnings the solver emits. When this parameter is set to 0 then no warnings are emitted.

The parameter takes an integer value in range 0..3.

The default value is 2.

workers

Per-worker parameter overrides.

public List<WorkerParameters>? workers { get; set; }

Property Value

List<WorkerParameters>

Remarks

Each worker can have its own parameters. If a parameter is not specified for a worker, then the global value is used.

Note that parameter Parameters.nbWorkers specifies the number of workers regardless of the length of this list.

See also:

WorkerParameters — for the list of parameters that can be set per worker.

Methods

CopyParameters(Parameters)

Creates a deep copy of the input Parameters object.

public static Parameters CopyParameters(Parameters @params)

Parameters

params Parameters: The Parameters object to copy

Returns

Parameters: A deep copy of the input Parameters object.

Remarks

Creates a deep copy of the input Parameters object. Afterwards, the copy can be modified without affecting the original Parameters object.

var parameters = new Parameters { timeLimit = 60, nbWorkers = 4 };
var copy = Parameters.CopyParameters(parameters);
copy.timeLimit = 120; // Does not affect original parameters

MergeParameters(Parameters, Parameters)

Merges two Parameters settings into a new one.

public static Parameters MergeParameters(Parameters @base, Parameters overrides)

Parameters

base Parameters: Base parameters that can be overridden
overrides Parameters: Parameters that will overwrite values from base

Returns

Parameters: The merged parameters object

Remarks

The new object contains all parameters from both inputs. If the same parameter is specified in both input objects, then the value from overrides is used.

Input objects are not modified.

var defaults = new Parameters { timeLimit = 60, nbWorkers = 4 };
var overrides = new Parameters { timeLimit = 120 };
var merged = Parameters.MergeParameters(defaults, overrides);
// merged = { timeLimit = 120, nbWorkers = 4 }

ParseKnownParameters(string[]?, Parameters?, string?, bool)

Parses OptalCP solver parameters from the command line, passing through unrecognized arguments.

public static (Parameters Parameters, List<string> Unrecognized) ParseKnownParameters(string[]? args = null, Parameters? defaults = null, string? usage = null, bool exitOnError = true)

Parameters

args string[]: Command-line arguments to parse. Defaults to Environment.GetCommandLineArgs() (skipping the executable name).
defaults Parameters: Default parameter values. CLI arguments override these.
usage string: Custom usage text shown before the parameter list when --help is used.
exitOnError bool: If true (default), exits on error or --help. If false, throws instead.

Returns

(Parameters Parameters, List<string> Unrecognized): A tuple containing the parsed parameters and the list of unrecognized arguments.

Remarks

Like ParseParameters, but unrecognized arguments are collected and returned instead of causing an error.

This is useful when your application has its own command-line arguments alongside OptalCP solver parameters. For example, running dotnet run -- --timeLimit 120 input.txt would parse --timeLimit 120 as a solver parameter and return input.txt as an unrecognized argument for your code to handle.

The defaults argument lets you specify sensible default values for your application. When users don't provide a parameter on the command line, the default value is used.

By default (exitOnError: true), parse errors and --help/--optalcpVersion flags cause the process to exit. Set exitOnError: false to throw instead, which is useful for testing or custom error handling.

If --help or -h is given, the method prints help starting with the usage argument (if provided), followed by the list of recognized parameters:

WorkerParameters can be specified for individual workers using --workerN. prefix. For example, --worker0.searchType FDS sets the search type for the first worker only.

Example:

// Parse solver parameters, collect input files as unrecognized args
var (parameters, inputFiles) = Parameters.ParseKnownParameters(
    defaults: new Parameters { timeLimit = 60 },
    usage: "Usage: myapp [OPTIONS] <input-file>..."
);
foreach (var file in inputFiles)
{
// Load and solve each input file:
var (model, _, _) = Model.FromJSON(File.ReadAllText(file));
model.Solve(parameters);
}

See also:

ParseParameters — to reject unrecognized arguments with an error.

ParseParameters(string[]?, Parameters?, string?, bool)

Parses OptalCP solver parameters from the command line.

public static Parameters ParseParameters(string[]? args = null, Parameters? defaults = null, string? usage = null, bool exitOnError = true)

Parameters

args string[]: Command-line arguments to parse. Defaults to Environment.GetCommandLineArgs() (skipping the executable name).
defaults Parameters: Default parameter values. CLI arguments override these.
usage string: Custom usage text shown before the parameter list when --help is used.
exitOnError bool: If true (default), exits on error or --help. If false, throws instead.

Returns

Parameters: The parsed parameters object.

Remarks

Parses OptalCP solver parameters from the command line and returns a Parameters object ready for use with Model.Solve.

Instead of hardcoding solver settings like time limits or worker counts in your code, you can let users configure them when running your application. For example, running dotnet run -- --timeLimit 120 --nbWorkers 8 would override any defaults. This makes your application flexible without requiring code changes for different scenarios.

The defaults argument lets you specify sensible default values for your application. When users don't provide a parameter on the command line, the default value is used.

By default (exitOnError: true), parse errors and --help/--optalcpVersion flags cause the process to exit. Set exitOnError: false to throw instead.

If --help or -h is given, the method prints help starting with the usage argument (if provided), followed by the list of recognized parameters:

WorkerParameters can be specified for individual worker(s) using the following prefixes:

--workerN. or --workersN. for worker N
--workerN-M. or --workersN-M. for workers in the range N to M

For example:

--worker0.searchType FDS sets the search type for the first worker only.
--workers4-8.noOverlapPropagationLevel 4 sets the propagation level of noOverlap constraint for workers 4, 5, 6, 7, and 8.

This method does not accept unrecognized arguments (they cause an error).

Example:

// Parse with defaults that CLI can override
var parameters = Parameters.ParseParameters(
    defaults: new Parameters { timeLimit = 60, nbWorkers = 4 },
    usage: "Usage: myapp [OPTIONS] <input-file>\n\nSolve scheduling problem."
);
var result = model.Solve(parameters);

See also:

ParseKnownParameters — to handle unrecognized arguments.

Table of Contents

Class Parameters

Remarks

Constructors

Parameters()

Remarks

Properties

absoluteGapTolerance

Property Value

Remarks

allocationBlockSize

Property Value

Remarks

color

Property Value

Remarks

cumulPropagationLevel

Property Value

Remarks

fdsAdditionalStepRatio

Property Value

Remarks

fdsBothFailRewardFactor

Property Value

Remarks

fdsBranchOnObjective

Property Value

Remarks

fdsBranchOrdering

Property Value

Remarks

fdsDualResetRatings

Property Value

Remarks

fdsDualStrategy

Property Value

Remarks

fdsEpsilon

Property Value

Remarks

fdsEventTimeInfluence

Property Value

Remarks

fdsFixedAlpha

Property Value

Remarks

fdsInitialRating

Property Value

Remarks

fdsInitialRestartLimit

Property Value

Remarks

fdsLengthStepRatio

Property Value

Remarks

fdsMaxCounterAfterRestart

Property Value

Remarks

fdsMaxCounterAfterSolution

Property Value

Remarks

fdsMaxInitialChoicesPerVariable

Property Value

Remarks

fdsMaxInitialLengthChoices

Property Value

Remarks

fdsMinIntVarChoiceStep

Property Value

Remarks

fdsMinLengthChoiceStep

Property Value

Remarks

fdsPresenceStatusChoices

Property Value

Remarks

fdsRatingAverageComparison

Property Value

Remarks

fdsRatingAverageLength