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`	Simulated annealing level.
`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.
`advanced_params`	Advanced parameters.

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_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_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_file`	Sets the path of the LocalSolver log file.
`get_log_file`	Returns the path of the LocalSolver log file.
`set_advanced_param`	Sets the value of an advanced parameter.
`get_advanced_param`	Returns the value of an advanced parameter.

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 state 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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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 strictly positive integer. The default number of threads is set to 2. Only allowed in state LSState.STOPPED.

By increasing the number of threads, you increase the robustness of the solver (that is, the chance to find better solutions). However, we recommend you to avoid running a number of threads which exceeds the number of cores available on your machine. Since the performance of the solver is sensible to the number of cache misses, the recommended ratio for maximizing its efficiency is to launch at most k/2 searches with k the number of cores of your hardware.

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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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 state LSState.STOPPED.

This is not allowed if you have defined multiple phases. Use LSPhase.set_time_limit() to set the limit for each phase instead.

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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

This is not allowed if you have defined multiple phases. Use LSPhase.get_time_limit() instead.

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 state LSState.STOPPED.

This is not allowed if you have defined multiple phases. Use LSPhase.set_iteration_limit() to set the limit for each phase instead.

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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

This is not allowed if you have defined multiple phases. Use LSPhase.get_iteration_limit() instead.

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.0: The annealing level hasn’t 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 state LSState.STOPPED.

If set to 0, the search heuristic is equivalent to a standard descent: moves deteriorating the current solution are rejected. By increasing this parameter, you increase the number of uphill moves (that is, moves deteriorating the objective value of the current solution): this increases chances to reach better solutions (diversification), but slows the convergence of the search.

You can also use the shortcut member annealing_level

Parameters:	level (`int`) – Simulated annealing level.

LSParam.get_annealing_level()¶

Gets the simulated annealing level.

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

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

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. 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_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 states LSState.STOPPED.

Parameters:	obj_index (`int`) – Index of the objective threshold – Objective threshold. The threshold can be a double or an integer.
Since:	8.0

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.0

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 state 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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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 state 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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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 state 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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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_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.STOPPED or LSState.MODELING.

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_advanced_param(key, value)¶

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.STOPPED or LSState.MODELING.

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)¶

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. Only allowed in states LSState.PAUSED or LSState.STOPPED.

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().

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¶: Simulated annealing level. It is a shortcut for get_annealing_level() and set_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.advanced_params¶: Advanced parameters. It is a shortcut for get_advanced_param() and set_advanced_param(). The returned object can be indexed with strings. Please not 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`