discrete_optimization.generic_tools.ls package

Submodules

discrete_optimization.generic_tools.ls.hill_climber module

class discrete_optimization.generic_tools.ls.hill_climber.HillClimber(problem: Problem, mutator: Mutation, restart_handler: RestartHandler, mode_mutation: ModeMutation, params_objective_function: ParamsObjectiveFunction | None = None, store_solution: bool = False, **kwargs)[source]

Bases: SolverDO, WarmstartMixin

initial_solution: Solution | None = None

Initial solution used for warm start.

set_warm_start(solution: Solution) → None[source]

Make the solver warm start from the given solution.

Will be ignored if arg initial_variable is set and not None in call to solve().

solve(nb_iteration_max: int, initial_variable: Solution | None = None, callbacks: list[Callback] | None = None, **kwargs: Any) → ResultStorage[source]

Generic solving function.

Parameters:

  • callbacks – list of callbacks used to hook into the various stage of the solve

  • **kwargs – any argument specific to the solver

Solvers deriving from SolverDo should use callbacks methods .on_step_end(), … during solve(). But some solvers are not yet updated and are just ignoring it.

Returns (ResultStorage): a result object containing potentially a pool of solutions to a discrete-optimization problem

class discrete_optimization.generic_tools.ls.hill_climber.HillClimberPareto(problem: Problem, mutator: Mutation, restart_handler: RestartHandler, mode_mutation: ModeMutation, params_objective_function: ParamsObjectiveFunction | None = None, store_solution: bool = False)[source]

Bases: HillClimber

solve(nb_iteration_max: int, initial_variable: Solution | None = None, update_iteration_pareto: int = 1000, callbacks: list[Callback] | None = None, **kwargs: Any) → ParetoFront[source]

Generic solving function.

Parameters:

  • callbacks – list of callbacks used to hook into the various stage of the solve

  • **kwargs – any argument specific to the solver

Solvers deriving from SolverDo should use callbacks methods .on_step_end(), … during solve(). But some solvers are not yet updated and are just ignoring it.

Returns (ResultStorage): a result object containing potentially a pool of solutions to a discrete-optimization problem

discrete_optimization.generic_tools.ls.simulated_annealing module

class discrete_optimization.generic_tools.ls.simulated_annealing.SimulatedAnnealing(problem: Problem, mutator: Mutation, restart_handler: RestartHandler, temperature_handler: TemperatureScheduling, mode_mutation: ModeMutation, params_objective_function: ParamsObjectiveFunction | None = None, store_solution: bool = False, **kwargs)[source]

Bases: SolverDO, WarmstartMixin

aggreg_from_dict: Callable[[dict[str, float]], float]
aggreg_from_sol: Callable[[Solution], float]

Computes aggregated fitness (or multi-objective depending on ParamsObjectiveFunction) from a solution.

initial_solution: Solution | None = None

Initial solution used for warm start.

set_warm_start(solution: Solution) → None[source]

Make the solver warm start from the given solution.

Will be ignored if arg initial_variable is set and not None in call to solve().

solve(nb_iteration_max: int, initial_variable: Solution | None = None, callbacks: list[Callback] | None = None, **kwargs: Any) → ResultStorage[source]

Generic solving function.

Parameters:

  • callbacks – list of callbacks used to hook into the various stage of the solve

  • **kwargs – any argument specific to the solver

Solvers deriving from SolverDo should use callbacks methods .on_step_end(), … during solve(). But some solvers are not yet updated and are just ignoring it.

Returns (ResultStorage): a result object containing potentially a pool of solutions to a discrete-optimization problem

class discrete_optimization.generic_tools.ls.simulated_annealing.TemperatureScheduling[source]

Bases: object

nb_iteration: int
abstractmethod next_temperature(move_accepted: bool = False) → float[source]

Update and return the next temperature.

Parameters:

move_accepted – Whether the last move was accepted. Used by threshold-based schedulers.

Returns:

The updated temperature

restart_handler: RestartHandler
temperature: float
class discrete_optimization.generic_tools.ls.simulated_annealing.TemperatureSchedulingFactor(initial_temperature: float, restart_handler: RestartHandler, cooling_factor: float = 0.99, temperature: float = None, coefficient: float = None)[source]

Bases: TemperatureScheduling

Geometric cooling schedule: T ← coefficient × T every iteration.

This scheduler cools the temperature by a constant factor at every iteration, regardless of acceptance rate. This is simpler but may cool too quickly compared to threshold-based approaches.

Parameters:

  • initial_temperature – Starting temperature (T0)

  • restart_handler – Handler for restarts

  • cooling_factor – Multiplicative factor (typically 0.95-0.9999) T_new = cooling_factor × T_old

next_temperature(move_accepted: bool = False) → float[source]

Cool temperature by constant factor (ignores move_accepted).

class discrete_optimization.generic_tools.ls.simulated_annealing.TemperatureSchedulingThresholdBased(initial_temperature: float, restart_handler: RestartHandler, cooling_factor: float = 0.99, n_moves_sampled_before_cooling: int = 60240, n_moves_accepted_before_cooling: int = 12049)[source]

Bases: TemperatureScheduling

Threshold-based geometric cooling: cool only when thresholds are reached.

This is the classic SA cooling schedule from Kirkpatrick et al. (1983) and used in many SA implementations. Temperature stays constant while exploring at each “temperature level”, and only decreases when enough moves have been sampled or accepted.

This approach allows more thorough exploration at each temperature level before cooling, often leading to better quality solutions compared to per-iteration cooling.

Implementation based on: - Kirkpatrick et al. (1983) - “Optimization by Simulated Annealing” - Ceschia et al. (2017) - “Solving discrete lot-sizing and scheduling…”

Parameters:

  • initial_temperature – Starting temperature (T0)

  • restart_handler – Handler for restarts

  • cooling_factor – Multiplicative factor when cooling (alpha, typically 0.95-0.99)

  • n_moves_sampled_before_cooling – Number of moves to sample before cooling (n_s) Temperature cools when this threshold is reached

  • n_moves_accepted_before_cooling – Number of accepted moves before cooling (n_a) Temperature cools when this threshold is reached (if reached before n_moves_sampled)

Note

Temperature cools when EITHER threshold is reached (OR condition). Typically n_moves_accepted < n_moves_sampled, so high acceptance early in search triggers faster cooling, while low acceptance later maintains temperature longer for continued exploration.

get_statistics() → dict[source]

Get statistics about the cooling schedule.

Returns:

Dictionary with cooling statistics

next_temperature(move_accepted: bool = False) → float[source]

Update temperature based on acceptance thresholds.

Parameters:

move_accepted – Whether the last move was accepted

Returns:

The current temperature (may or may not have changed)

Module contents