Solver Option Guide

Solver Option Guide
- How to Set Solver Option
  - C++
  - Python
- List of Options

How to Set Solver Option

The options of the PRINTEMPS solver can be configured using a printemps::option::Option object (in C++) or a printemps.Option object (in Python). Options can also be loaded directly from a JSON file.

C++

#include <printemps.h>

printemps::model::IPModel model;
/// The modeling code is omitted.

printemps::option::Option option;
option.output.verbose = printemps::option::verbose::Full;
option.tabu_search.iteration_max = 10000;
option.cdcl.is_enabled = true;

/// Alternatively, load from a JSON file:
/// printemps::option::Option option("path/to/option.json");

/// The option object is set as the 2nd argument of printemps::solver::solve().
auto result = printemps::solver::solve(&model, option);

Python

import printemps

model = printemps.IPModel()
# The modeling code is omitted.

option = printemps.Option()
option.output.verbose = printemps.Verbose.Full
option.tabu_search.iteration_max = 10000
option.cdcl.is_enabled = True

# Alternatively, load from a JSON file:
# option = printemps.Option("path/to/option.json")

result = printemps.solve(model, option)

List of Options

General Options

Name	Type	Default	Description
`iteration_max`	`int`	`100`	Allowed maximum number of outer loop iterations.
`time_max`	`double`	`120`	Allowed maximum computational time for optimization calculation (specified in seconds).
`time_offset`	`double`	`0.0`	Time offset added to the elapsed computation time (specified in seconds).
`target_objective_value`	`double`	`1E100` or `-1E100` or `0`	Target objective function value. If the objective function of the feasible incumbent reaches `target_objective_value`, the optimization calculation will be terminated with status `REACH_TARGET`. For minimization and maximization problems, `-1E100` and `1E100` are set as default values, respectively. If the objective function is not defined, the target is set to `0`, and the optimization terminates once a feasible solution is found.
`seed`	`int`	`1`	Seed value for the pseudo-random number generator.
`is_enabled_fast_evaluation`	`bool`	`true`	If this option is set to `true`, optimized fast move evaluation is used.

Penalty Options

Name	Type	Default	Description
`penalty_coefficient_relaxing_rate`	`double`	`0.9`	If the augmented objective incumbent obtained by a tabu search is feasible, all penalty coefficients will be relaxed by multiplying them by `penalty_coefficient_relaxing_rate`.
`penalty_coefficient_tightening_rate`	`double`	`1.0`	If the augmented objective incumbent obtained by a tabu search is not feasible, penalty coefficients corresponding to violating constraints will be tightened by adding the violation multiplied by `penalty_coefficient_tightening_rate`.
`penalty_coefficient_pullback_rate`	`double`	`1E-4`	Pullback rate to recover penalty coefficients for escaping stagnation.
`initial_penalty_coefficient`	`double`	`1E7`	Initial penalty coefficient value. The penalty coefficients corresponding to all constraints are initialized by `initial_penalty_coefficient`.
`is_enabled_group_penalty_coefficient`	`bool`	`false`	If this option is set to `true`, the penalty coefficients for constraints belonging to the same constraint group are aligned to the largest one in the group. Here, "constraint groups" are constraints that share a common symbol and are distinguished by their indices.

Parallel Options

Name	Type	Default	Description
`is_enabled_move_evaluation_parallelization`	`bool`	`true`	If this option is set to `true`, evaluations of solutions will be parallelized using OpenMP.
`is_enabled_move_update_parallelization`	`bool`	`true`	If this option is set to `true`, updating the neighborhood of the current solution will be parallelized using OpenMP.
`is_enabled_cdcl_parallelization`	`bool`	`true`	If this option is set to `true`, the CDCL search is parallelized with portfolio search across multiple threads using OpenMP.
`number_of_threads_move_evaluation`	`int`	`-1`	Number of OpenMP threads for neighborhood move evaluation. `-1` automatically adapts to the maximum available hardware threads.
`number_of_threads_move_update`	`int`	`-1`	Number of OpenMP threads for neighborhood move update. `-1` automatically adapts to the maximum available hardware threads.
`number_of_threads_cdcl`	`int`	`4`	Number of OpenMP threads for parallel CDCL portfolio search (clamped to the maximum available hardware threads).
`is_enabled_thread_count_optimization`	`bool`	`true`	If this option is set to `true`, the number of OpenMP threads dynamically adapts during execution to optimize computational efficiency.
`thread_count_optimization_decay_factor`	`double`	`0.5`	Decay factor for the thread count optimizer.

Preprocess Options

Name	Type	Default	Description
`is_enabled_presolve`	`bool`	`true`	If this option is set to `true`, redundant decision variables and constraints will be fixed or removed. Infeasibility detection is also performed.
`is_enabled_remove_duplicated_constraints`	`bool`	`true`	If this option is set to `true`, duplicated constraints will be extracted and removed. This option works only if `is_enabled_presolve` is set to `true`.
`is_enabled_remove_implicit_fixed_variables`	`bool`	`true`	If this option is set to `true`, implicit fixed variables will be extracted and removed. This option works only if `is_enabled_presolve` is set to `true`.
`is_enabled_remove_redundant_set_variables`	`bool`	`true`	If this option is set to `true`, redundant decision variables included in set partitioning/packing/covering constraints will be extracted and fixed at `0`. This option works only if `is_enabled_presolve` is set to `true`.
`is_enabled_remove_redundant_set_constraints`	`bool`	`true`	If this option is set to `true`, redundant set partitioning and exclusive OR constraints will be extracted and removed. This option works only if `is_enabled_presolve` is set to `true`.
`is_enabled_extract_implicit_equality_constraints`	`bool`	`true`	If this option is set to `true`, inequality constraint pairs that implicitly define equality constraints will be extracted and replaced with the corresponding equality constraints.
`is_enabled_online_bounding`	`bool`	`true`	If this option is set to `true`, lower and upper bounds of decision variables will be successively tightened based on the incumbent objective value obtained during the optimization process.
`is_enabled_initial_value_correction`	`bool`	`true`	If this option is set to `true`, initial values of decision variables will be corrected as necessary so that they satisfy their lower and upper bounds.
`is_enabled_partial_feasible_enumeration`	`bool`	`true`	If this option is set to `true`, partial feasible solutions will be enumerated to fix variables. This option works only if `is_enabled_presolve` is set to `true`.
`is_enabled_extract_dependent_exclusive_or`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Exclusive OR` constraints.
`is_enabled_extract_dependent_exclusive_nor`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Exclusive NOR` constraints.
`is_enabled_extract_dependent_inverted_integers`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Inverted Integers` constraints.
`is_enabled_extract_dependent_balanced_integers`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Balanced Integers` constraints.
`is_enabled_extract_dependent_constant_sum_integers`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Constant Sum Integers` constraints.
`is_enabled_extract_dependent_constant_difference_integers`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Constant Difference Integers` constraints.
`is_enabled_extract_dependent_constant_ratio_integers`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Constant Ratio Integers` constraints.
`is_enabled_extract_dependent_trinomial_exclusive_nor`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Trinomial Exclusive NOR` constraints.
`is_enabled_extract_dependent_all_or_nothing`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `All Or Nothing` constraints.
`is_enabled_extract_dependent_intermediate`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted from `Intermediate` constraints.
`is_enabled_extract_dependent_using_partial_feasible_enumeration`	`bool`	`true`	If this option is set to `true`, dependent variables are extracted using partial feasible enumeration.

Restart Options

Name	Type	Default	Description
`restart_mode`	`printemps::option::` `restart_mode::` `RestartMode`	`Smart`	Mode for selecting search restart solutions. `Simple`: Naive restart. `Smart`: History-informed restart.

Neighborhood Options

Name	Type	Default	Description
`is_enabled_binary_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves that flip binary variables are enabled.
`is_enabled_integer_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves that increment or decrement integer variables are enabled.
`is_enabled_exclusive_or_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Exclusive OR` constraints are enabled.
`is_enabled_exclusive_nor_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Exclusive NOR` constraints are enabled.
`is_enabled_inverted_integers_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Inverted Integers` constraints are enabled.
`is_enabled_balanced_integers_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Balanced Integers` constraints are enabled.
`is_enabled_constant_sum_integers_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Constant Sum Integers` constraints are enabled.
`is_enabled_constant_difference_integers_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Constant Difference Integers` constraints are enabled.
`is_enabled_constant_ratio_integers_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Constant Ratio Integers` constraints are enabled.
`is_enabled_aggregation_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Aggregation` constraints are enabled.
`is_enabled_precedence_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Precedence` constraints are enabled.
`is_enabled_variable_bound_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Variable Bound` constraints are enabled.
`is_enabled_trinomial_exclusive_nor_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Trinomial Exclusive NOR` constraints are enabled.
`is_enabled_soft_selection_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves specialized for `Soft Selection` constraints are enabled.
`is_enabled_chain_move`	`bool`	`true`	If this option is set to `true`, two or more moves will be combined adaptively.
`is_enabled_two_flip_move`	`bool`	`false`	If this option is set to `true`, 2-flip move generator for correlated binary variable pairs is enabled.
`is_enabled_partial_feasible_enumeration_move`	`bool`	`true`	If this option is set to `true`, neighborhood moves generated by partial feasible enumeration are enabled.
`is_enabled_user_defined_move`	`bool`	`false`	If this option is set to `true`, user-defined neighborhood moves registered via callbacks are evaluated.
`chain_move_capacity`	`int`	`100000`	Allowed maximum number of candidate chain moves generated in each step.
`chain_move_reduce_mode`	`printemps::option::` `chain_move_reduce_mode::` `ChainMoveReduceMode`	`OverlapRate`	Mode used to filter and reduce candidate chain moves.
`chain_move_overlap_rate_threshold`	`double`	`0.2`	Overlap rate threshold for screening combined moves when `chain_move_reduce_mode` is `OverlapRate`.
`selection_mode`	`printemps::option::` `selection_mode::` `SelectionMode`	`Independent`	Rule to detect and extract selection constraints. `Off`: No selection constraints will be extracted. `Defined`: If a decision variable is included in more than one selection constraint, the selection constraint defined first will be extracted with higher priority. `Smaller`: If a decision variable is included in more than one selection constraint, the selection constraint with the smaller number of decision variables will be extracted with higher priority. `Larger`: If a decision variable is included in more than one selection constraint, the selection constraint with the larger number of decision variables will be extracted with higher priority. `Independent`: Selection constraints that do not share decision variables with each other will be extracted.
`improvability_screening_mode`	`printemps::option::` `improvability_screening_mode::` `ImprovabilityScreeningMode`	`Automatic`	Rule for screening neighborhood moves. `Off`: No screening. `Soft`: Only moves with objective or feasibility improvement will be selected. `Aggressive`: If the current solution is infeasible, only moves with feasibility improvement will be selected. `Intensive`: Similar to `Aggressive`, but moves will be more narrowly defined. `Automatic`: Depending on the search situation, either `Soft`, `Aggressive`, or `Intensive` screening will be automatically applied.
`is_enabled_integer_step_size_adjuster`	`bool`	`false`	If this option is set to `true`, adaptive integer step sizes are adjusted based on variable activity and domain bounds.

Output Options

Name	Type	Default	Description
`verbose`	`printemps::option::` `verbose::` `Verbose`	`Off`	Log level of standard output. `Off`: No output. `Warning`: Output only warning messages. `Outer`: Output warning messages and intermediate results of outer loops. `Inner`: Output warning messages and intermediate results of outer and inner tabu search loops. `Full`: Output full information.
`is_enabled_write_trend`	`bool`	`false`	If this option is set to `true`, search trend will be written in a text file named `trend.txt`. The output file can be visualized by `script/visualize_trend.py`.
`is_enabled_store_feasible_solutions`	`bool`	`false`	If this option is set to `true`, feasible solutions found in the search will be stored, and written in a JSON file named `feasible.json`. The output file can be visualized by `script/visualize_solutions.py`. Activating this option with large `feasible_solutions_capacity` would affect search performance especially for problems with too many feasible solutions.
`feasible_solutions_capacity`	`int`	`1000`	Allowed maximum number of the stored feasible solutions. If the capacity is exceeded, worse solutions will be clipped.
`is_enabled_print_search_behavior_summary`	`bool`	`true`	If this option is set to `true`, a summary of search behavior will be printed to the standard output.
`is_enabled_print_tree_summary`	`bool`	`true`	If this option is set to `true`, lists of frontier and locally optimal solutions will be printed to the standard output, based on the analysis of the tree structure of historical incumbent solutions.
`is_enabled_print_thread_count_optimizer_summary`	`bool`	`true`	If this option is set to `true`, a summary of the thread count optimizer will be printed to the standard output.
`is_enabled_print_variable_update_summary`	`bool`	`true`	If this option is set to `true`, lists of high and low frequent updated variables will be printed to the standard output.
`is_enabled_print_constraint_violation_summary`	`bool`	`true`	If this option is set to `true`, lists of high and low frequent satisfied constraints will be printed to the standard output.
`is_enabled_print_violation_and_penalty_summary`	`bool`	`true`	If this option is set to `true`, a list of violating constraints at the current solution and the update behavior of the penalty weights will be printed to the standard output.
`is_enabled_print_tabu_search_parameter`	`bool`	`true`	If this option is set to `true`, adjusted values for tabu search parameters will be printed to the standard output.

CDCL Options

Name	Type	Default	Description
`is_enabled`	`bool`	`true`	If this option is set to `true`, the CDCL (Conflict-Driven Clause Learning) solver runs as a feasibility search phase prior to tabu search.
`iteration_max`	`int`	`100000000`	Allowed maximum number of CDCL iterations.
`time_max`	`double`	`10.0`	Allowed maximum computational time for CDCL search (specified in seconds).
`log_interval`	`int`	`1000`	Iteration interval to print CDCL progress logs when verbose logging is enabled.
`conflict_max`	`int`	`-1`	Maximum number of conflicts allowed before stopping CDCL (`-1` means unlimited).
`initial_conflict_limit`	`int`	`100`	Initial conflict count threshold triggering a restart.

PDLP Options

Name	Type	Default	Description
`is_enabled`	`bool`	`false`	If this option is set to `true`, the first-order PDLP method solves the continuous LP relaxation.
`iteration_max`	`int`	`100000`	Allowed maximum number of PDLP iterations.
`time_max`	`double`	`120.0`	Allowed maximum computational time for PDLP (specified in seconds).
`tolerance`	`double`	`1E-5`	Convergence tolerance for primal and dual residuals.
`step_size_extend_exponent`	`double`	`-0.6`	Exponent for step size extension rule in PDLP.
`step_size_reduce_exponent`	`double`	`-0.3`	Exponent for step size reduction rule in PDLP.
`restart_threshold_sufficient`	`double`	`0.1`	Sufficient reduction threshold for restarting PDLP iterates.
`restart_threshold_necessary`	`double`	`0.9`	Necessary reduction threshold for restarting PDLP iterates.
`restart_threshold_artificial`	`double`	`0.5`	Artificial restart threshold in PDLP.
`restart_check_interval`	`int`	`10`	Iteration interval to evaluate restart conditions.
`convergence_check_interval`	`int`	`10`	Iteration interval to check residual convergence.
`counts_of_ruiz_scaling`	`int`	`10`	Number of Ruiz matrix equilibration scaling passes.
`is_enabled_pock_chambolle_scaling`	`bool`	`true`	If this option is set to `true`, Pock-Chambolle diagonal scaling is applied.
`log_interval`	`int`	`10`	Iteration interval to print calculation logs when verbose is `Full`.

Lagrange Dual Search Options

Name	Type	Default	Description
`is_enabled`	`bool`	`false`	If this option is set to `true`, an initial solution will be prepared by solving a lagrange dual problem by a subgradient method.
`iteration_max`	`int`	`10000`	Allowed maximum number of the lagrange dual search loop iterations.
`time_max`	`double`	`120`	Allowed maximum computational time for lagrange dual search (specified in seconds).
`step_size_extend_rate`	`double`	`1.05`	If it is observed that the step size is too small, the subgradient algorithm will extend the step size according to the value of this option. A larger value accelerates convergence but may also affect stability.
`step_size_reduce_rate`	`double`	`0.95`	If it is observed that the step size is too large, the subgradient algorithm will reduce the step size according to the value of this option.
`tolerance`	`double`	`1E-5`	The tolerance for determining convergence of the subgradient algorithm. It should be specified as a ratio to the absolute value of the Lagrangian.
`log_interval`	`int`	`10`	Iteration interval to print the calculation log to standard output. This option is effective only if `verbose` is set `Full`.

Local Search Options

Name	Type	Default	Description
`is_enabled`	`bool`	`true`	If this option is set to `true`, the initial solution will be improved by a greedy local search.
`iteration_max`	`int`	`10000`	Allowed maximum number of the local search loop iterations.
`time_max`	`double`	`120`	Allowed maximum computational time for local search (specified in seconds).
`log_interval`	`int`	`10`	Iteration interval to print the calculation log to standard output. This option is effective only if `verbose` is set `Full`.

Tabu Search Options

Name	Type	Default	Description
`iteration_max`	`int`	`200`	Allowed maximum number of one tabu search loop iterations.
`time_max`	`double`	`120`	Allowed maximum computational time for one tabu search (specified in seconds).
`log_interval`	`int`	`10`	Iteration interval to print the calculation log to standard output. This option is effective only if `verbose` is set `Full`.
`initial_tabu_tenure`	`int`	`10`	Initial tabu tenure. The value of a decision variable can not be changed again until the number of tabu tenure iterations has passed.
`tabu_tenure_randomize_rate`	`double`	`0.3`	Tabu tenure for each move will be randomized according to the value of this option. The value should be specified as the rate to the tabu tenure. For example, if the nominal tabu tenure is internally set `20` and `tabu_tenure_randomize_rate` is set `0.5`, the actual tabu tenure for each move will be set randomly in the range `[10, 30]`.
`tabu_mode`	`printemps::option::` `tabu_mode::` `TabuMode`	`All`	Rule to determine the acceptability (tabu or not) of a move from the current solution to a neighborhood solution for the case that the move consists of multiple variable changes. `All`: The move is not acceptable if all of the variables included in the move are "tabu". `Any`: The move is not acceptable if any variable included in the move is "tabu".