LSParam Class

class localsolver.LSParam

Solving parameters. This class contains some methods allowing you to parameterize the resolution of the model. For the sake of simplicity, only a few parameters are actually offered to tune the search.

Summary

Attributes

seed

Seed of the pseudo-random number generator used by the solver.

nb_threads

Number of threads used to parallelize the search.

time_limit

Time limit in seconds.

iteration_limit

Iteration limit.

annealing_level

Deprecated since version 8.5: The annealing level doesn’t have a significant influence on the search anymore.

verbosity

Verbosity level of the solver.

time_between_displays

Time in seconds between two consecutive displays.

time_between_ticks

Time in seconds between two consecutive ticks.

iteration_between_ticks

Number of iterations between two consecutive ticks.

log_file

Path of the LocalSolver log file.

log_writer

The writer used by LocalSolver for its logging.

advanced_params

Reserved for maintenance purpose.

Methods

set_seed

Sets the seed of the pseudo-random number generator used by the solver.

get_seed

Gets the seed of the pseudo-random number generator used by the solver.

set_nb_threads

Sets the number of threads used to parallelize the search.

get_nb_threads

Gets the number of threads.

set_time_limit

Sets the time limit in seconds.

get_time_limit

Gets the time limit in seconds.

set_iteration_limit

Sets a limit on the number of iterations.

get_iteration_limit

Gets the limit on the number of iterations.

set_annealing_level

Sets the simulated annealing level.

get_annealing_level

Gets the simulated annealing level.

set_verbosity

Sets the verbosity level of the solver.

get_verbosity

Gets the verbosity level of the solver.

set_time_between_displays

Sets the time in seconds between two consecutive displays in console while the solver is running.

get_time_between_displays

Gets the time in seconds between two consecutive displays in console while the solver is running.

set_time_between_ticks

Sets the time in seconds between two events of type LSCallbackType.TIME_TICKED.

get_time_between_ticks

Gets the time in seconds between two events of type LSCallbackType.TIME_TICKED.

set_iteration_between_ticks

Sets the number of iterations between two events of type LSCallbackType.ITERATION_TICKED.

get_iteration_between_ticks

Gets the number of iterations between two events of type LSCallbackType.ITERATION_TICKED.

set_log_writer

Sets the writer used by LocalSolver for its logging.

get_log_writer

Returns the writer used by LocalSolver for its logging.

set_log_file

Sets the path of the LocalSolver log file.

get_log_file

Returns the path of the LocalSolver log file.

set_objective_threshold

Sets the threshold of the objective with the given index.

get_objective_threshold

Gets the threshold of the objective with the given index.

set_objective_bound

Sets the bound of the objective with the given index.

get_objective_bound

Gets the bound of the objective with the given index.

set_advanced_param

Reserved for maintenance purpose.

get_advanced_param

Reserved for maintenance purpose.

Special methods

__str__

Returns a string representation of these parameters.

Instance methods

LSParam.set_seed(seed)

Sets the seed of the pseudo-random number generator used by the solver. The seed must be a positive integer. The default seed is set to 0. Only allowed in states LSState.MODELING or LSState.STOPPED.

The search for solutions is highly randomized. Fixing the seed and the number of iterations of the solver allows you to reproduce exactly its results over several runs.

You can also use the shortcut member seed

Parameters

seed (int) – Seed of the pseudo-random number generator.

LSParam.get_seed()

Gets the seed of the pseudo-random number generator used by the solver.

You can also use the shortcut member seed

Returns

Seed of the pseudo-random number generator.

Return type

int

LSParam.set_nb_threads(nb_threads)

Sets the number of threads used to parallelize the search. The number of threads must be a positive integer. The default number of threads is set to 0 which means that the number of threads is automatically adapted to your computer and to your optimization model. Only allowed in states LSState.MODELING or LSState.STOPPED.

This parameter is indicative, if needed LocalSolver may use more threads. The actual number of threads can also vary during the search.

You can also use the shortcut member nb_threads

Parameters

nb_threads (int) – Number of threads.

LSParam.get_nb_threads()

Gets the number of threads. By convention, value 0 means that the number of threads is automatically adapted to your computer and to your optimization model. You can also use the shortcut member nb_threads

Returns

Number of threads.

Return type

int

LSParam.set_time_limit(time_limit)

Sets the time limit in seconds. Only allowed in states LSState.MODELING or LSState.STOPPED

You can also use the shortcut member time_limit

Parameters

time_limit (int) – Time limit in seconds.

LSParam.get_time_limit()

Gets the time limit in seconds.

You can also use the shortcut member time_limit

Returns

Time limit in seconds.

Return type

int

LSParam.set_iteration_limit(iteration_limit)

Sets a limit on the number of iterations. Fixing the seed and the number of iterations ensures the reproducibility of results over several runs. Only allowed in states LSState.MODELING or LSState.STOPPED

You can also use the shortcut member iteration_limit

Parameters

iteration_limit (int) – Iteration limit.

LSParam.get_iteration_limit()

Gets the limit on the number of iterations.

You can also use the shortcut member iteration_limit

Returns

Iteration limit.

Return type

int

LSParam.set_annealing_level(level)

Sets the simulated annealing level.

Deprecated since version 8.5: The annealing level doesn’t have a significant influence on the search anymore. The tuning of this parameter won’t be allowed in a future version.

The level must be an integer between 0 and 9. The default simulated annealing level is set to 1. Only allowed in states LSState.MODELING or LSState.STOPPED.

Parameters

level (int) – Simulated annealing level.

LSParam.get_annealing_level()

Gets the simulated annealing level.

Deprecated since version 8.5: The annealing level doesn’t have a significant influence on the search anymore. The tuning of this parameter won’t be allowed in a future version.

You can also use the shortcut member annealing_level

Returns

Simulated annealing level.

Return type

int

LSParam.set_verbosity(verbosity)

Sets the verbosity level of the solver. The default verbosity is set to 1. Only allowed in states LSState.MODELING or LSState.STOPPED. There are 3 defined verbosity levels :

  • 0: All the traces are disabled.

  • 1: Normal verbosity. This is the default level.

  • 2: Detailed verbosity. Displays statistics during the search.

You can also use the shortcut member verbosity

Parameters

verbosity (int) – Verbosity level: 0, 1, 2.

LSParam.get_verbosity()

Gets the verbosity level of the solver.

You can also use the shortcut member verbosity

Returns

verbosity Verbosity level: 0, 1 or 2.

Return type

int

LSParam.set_time_between_displays(time_between_displays)

Sets the time in seconds between two consecutive displays in console while the solver is running. The default time between displays is set to 1 second. Only allowed in states LSState.MODELING or LSState.STOPPED.

You can also use the shortcut member time_between_displays

Parameters

time_between_displays (int) – Time in seconds between displays.

LSParam.get_time_between_displays()

Gets the time in seconds between two consecutive displays in console while the solver is running.

You can also use the shortcut member time_between_displays

Returns

Time in seconds between displays.

Return type

int

LSParam.set_time_between_ticks(time_between_ticks)

Sets the time in seconds between two events of type LSCallbackType.TIME_TICKED. The default time between ticks is set to 1 second. Only allowed in states LSState.MODELING or LSState.STOPPED.

You can also use the shortcut member time_between_ticks

Parameters

time_between_ticks (int) – Time in seconds between ticks.

Since

6.0

LSParam.get_time_between_ticks()

Gets the time in seconds between two events of type LSCallbackType.TIME_TICKED.

You can also use the shortcut member time_between_ticks

Returns

Time in seconds between ticks.

Return type

int

Since

6.0

LSParam.set_iteration_between_ticks(iteration_between_ticks)

Sets the number of iterations between two events of type LSCallbackType.ITERATION_TICKED. The default number of iterations is 10,000. Only allowed in states LSState.MODELING or LSState.STOPPED.

You can also use the shortcut member iteration_between_ticks

Parameters

iteration_between_ticks (long) – Number of iterations between ticks.

Since

6.0

LSParam.get_iteration_between_ticks()

Gets the number of iterations between two events of type LSCallbackType.ITERATION_TICKED.

You can also use the shortcut member iteration_between_ticks

Returns

Number of iterations between ticks.

Return type

long

Since

6.0

LSParam.set_log_writer(writer)

Sets the writer used by LocalSolver for its logging. By default, this parameter is initialized to sys.stdout (standard output). To tune the logging verbosity of the output see set_verbosity.

The writer must be a io.TextIOBase like object. In particular the writer must implement at least a single write method that takes a string as parameter.

Note that you can specify both the log writer and the log file by using the method set_log_file().

Parameters

writer – Writer for the logging or None to disable logging.

Since

9.5

LSParam.get_log_writer()

Returns the writer used by LocalSolver for its logging. The default value is initialized to the standard output sys.stdout.

To tune the logging verbosity of the output or to disable logging, see set_verbosity().

Returns

The writer used by LocalSolver for its logging or None if logging is disabled.

Since

9.5

LSParam.set_log_file(path)

Sets the path of the LocalSolver log file. If the path is empty, no log will be saved. To tune the logging verbosity, see set_verbosity(). Only allowed in states LSState.MODELING or LSState.STOPPED.

You can also use the shortcut member log_file

Parameters

path (str) – Path of the log file. Leave empty to disable the file logging mechanism.

LSParam.get_log_file()

Returns the path of the LocalSolver log file. If no log file was specified, an empty string is returned.

You can also use the shortcut member log_file

Returns

The path of the log file or an empty string.

Return type

str

LSParam.set_objective_threshold(obj_index, threshold)

Sets the threshold of the objective with the given index. If the objective is minimized (respectively maximized), then the optimization of this objective is stopped as soon as this lower (respectively upper) threshold is reached. It can be useful for goal programming. Only allowed in state LSState.STOPPED.

Parameters
  • obj_index (int) – Index of the objective

  • threshold – Objective threshold. The threshold can be a double or an integer.

Since

8.5

LSParam.get_objective_threshold(obj_index)

Gets the threshold of the objective with the given index. Only allowed in states LSState.PAUSED or LSState.STOPPED.

Parameters

obj_index (int) – Index of the objective

Returns

The threshold of the objective

Return type

int or double

Since

8.5

LSParam.set_objective_bound(obj_index, bound)

Sets the bound of the objective with the given index.

Deprecated since version 8.5: This function will be removed in a future version. Please use set_objective_threshold() instead.

If the objective is minimized (respectively maximized), then the optimization of this objective is stopped as soon as this lower (respectively upper) bound is reached. It can be useful for goal programming. Only allowed in state LSState.STOPPED.

Parameters
  • obj_index (int) – Index of the objective

  • bound – Objective bound. The bound can be a double or an integer.

LSParam.get_objective_bound(obj_index)

Gets the bound of the objective with the given index.

Deprecated since version 8.5: This function will be removed in a future version. Please use get_objective_threshold() instead.

Only allowed in states LSState.PAUSED or LSState.STOPPED.

Parameters

obj_index (int) – Index of the objective

Returns

The bound of the objective

Return type

int or double

LSParam.set_advanced_param(key, value)

Reserved for maintenance purpose.

Sets the value of an advanced parameter. Advanced parameters are reserved for fine tuning or debugging and should not be used by end-users. Only allowed in states LSState.MODELING or LSState.STOPPED.

Advanced parameters can have string, double or integer values. You can also use the shortcut collection member advanced_params.

Parameters
  • key (str) – Name of the parameter to change

  • value – Value of the parameter. The value can be an integer, a double or a string.

LSParam.get_advanced_param(key)

Reserved for maintenance purpose.

Returns the value of an advanced parameter. Advanced parameters are reserved for fine tuning or debugging and should not be used by end-users. Throws an exception if the parameter does not exist.

Advanced parameters can have string, integer or double values. You can also use the shortcut collection member advanced_params.

Parameters

key (str) – Name of the parameter

Return type

int, double or str

Instance attributes

All get/set methods have their attribute counterpart. You can use them as shortcuts to improve the readability or your models and codes.

LSParam.seed

Seed of the pseudo-random number generator used by the solver. It is a shortcut for get_seed() and set_seed().

LSParam.nb_threads

Number of threads used to parallelize the search. It is a shortcut for get_nb_threads() and set_nb_threads(). Value 0 means that the number of threads is automatically adapted to your computer and to your optimization model.

LSParam.time_limit

Time limit in seconds. It is a shortcut for get_time_limit() and set_time_limit().

LSParam.iteration_limit

Iteration limit. It is a shortcut for get_iteration_limit() and set_iteration_limit().

LSParam.annealing_level

Deprecated since version 8.5: The annealing level doesn’t have a significant influence on the search anymore. The tuning of this parameter won’t be allowed in a future version.

Simulated annealing level.

LSParam.verbosity

Verbosity level of the solver. It is a shortcut for get_verbosity() and set_verbosity().

LSParam.time_between_displays

Time in seconds between two consecutive displays. It is a shortcut for get_time_between_displays() and set_time_between_displays().

LSParam.time_between_ticks

Time in seconds between two consecutive ticks. It is a shortcut for get_time_between_ticks() and set_time_between_ticks().

Since

6.0

LSParam.iteration_between_ticks

Number of iterations between two consecutive ticks. It is a shortcut for get_iteration_between_ticks() and set_iteration_between_ticks().

Since

6.0

LSParam.log_file

Path of the LocalSolver log file. It is a shortcut for get_log_file() and set_log_file().

LSParam.log_writer

The writer used by LocalSolver for its logging. It is a shortcut for get_log_writer() and set_log_writer().

Since

9.5

LSParam.advanced_params

Reserved for maintenance purpose.

Advanced parameters. Advanced parameters are reserved for fine tuning or debugging and should not be used by end-users. It is a shortcut for get_advanced_param() and set_advanced_param(). The returned object can be indexed with strings. Please note that the returned object is not iterable and you cannot apply the function len on it.

Special operators and methods

LSParam.__str__()

Returns a string representation of these parameters. Useful for debugging or logging purposes.

Returns

String representation.

Return type

str