metaheuristic_designer.stopping_condition module#

Module for algorithm stopping conditions and progress metric evaluation.

class StoppingCondition[source]#

Bases: ABC

Methods

`get_progress`()	Compute the current progress (0-1) according to the progress metric.
`get_state`()	Return a dictionary with the current state of the stopping condition.
`is_finished`([finished])	Given the state of the algorithm, returns wether we have finished or not.
`restart`()	Reset all counters and timers for a fresh run.
`update`(algorithm)	Advance internal counters after one generation.

abstract restart()[source]#: Reset all counters and timers for a fresh run.

abstract update(algorithm)[source]#

Advance internal counters after one generation.

Parameters:

current_populationPopulation: The population at the end of the current generation. Its best objective is used to update convergence tracking.

Parameters:

algorithm (Algorithm)

abstract is_finished(finished=False)[source]#

Given the state of the algorithm, returns wether we have finished or not.

Return type:

bool

Parameters:

real_time_start: float: The time in seconds that passed since the algorithm was executed.
cpu_time_start: float: The time in seconds that the CPU has executed code in this algorithm.

Returns:

has_stopped: bool: Whether the algorithm has reached its end

Parameters:

finished (bool)

abstract get_progress()[source]#

Compute the current progress (0-1) according to the progress metric.

Return type:

float

Parameters:

gen: int: The number of generations that has passed.
real_time_start: float: The time in seconds that passed since the algorithm was executed.
cpu_time_start: float: The time in seconds that the CPU has executed code in this algorithm.

Returns:

float: A value between 0 (start) and 1 (finished).

abstract get_state()[source]#

Return a dictionary with the current state of the stopping condition.

Return type:

dict

Returns:

dict: Keys include iterations, evaluations, times, and configuration limits.

class ParsedStoppingCondition(condition_str, progress_metric_str=None, max_iterations=None, max_evaluations=None, real_time_limit=None, cpu_time_limit=None, objective_target=None, max_patience=None, optimization_mode='max')[source]#

Bases: StoppingCondition

Encapsulate the logic that decides when an optimization run should end.

A stopping condition is built from a logical expression that combines tokens with and, or and parentheses. Each token has a corresponding numeric limit. The same expression (or a separate one) can be used to compute a progress value between 0 and 1 for parameter schedules.

Parameters:

condition_strstr: Logical expression defining when to stop (e.g. "max_iterations or real_time_limit").
progress_metric_strstr, optional: Logical expression defining how to compute the 0-1 progress value. Defaults to condition_str.
max_iterationsint, optional: Maximum number of generations.
max_evaluationsint, optional: Maximum number of objective function evaluations.
real_time_limitfloat, optional: Wall-clock time limit in seconds.
cpu_time_limitfloat, optional: CPU time limit in seconds.
objective_targetfloat, optional: Target value for the raw objective.
max_patienceint, optional: Consecutive iterations without improvement before "convergence" triggers.
optimization_modestr, optional: "max" or "min", how the objective target and convergence are evaluated.

Attributes:

cpu_time_limit
max_evaluations
max_iterations
max_patience
objective_target
progress_metric_str
real_time_limit

Parameters:

condition_str (str)
progress_metric_str (str | None)
max_iterations (int)
max_evaluations (int)
real_time_limit (float)
cpu_time_limit (float)
objective_target (float)
max_patience (int)
optimization_mode (str)

Methods

`get_progress`()	Compute the current progress (0-1) according to the progress metric.
`get_state`()	Return a dictionary with the current state of the stopping condition.
`is_finished`([finished])	Given the state of the algorithm, returns wether we have finished or not.
`restart`()	Reset all counters and timers for a fresh run.
`update`(algorithm)	Advance internal counters after one generation.

condition_str: str#

progress_metric_str: Optional[str] = None#

max_iterations: int = None#

max_evaluations: int = None#

real_time_limit: float = None#

cpu_time_limit: float = None#

objective_target: float = None#

max_patience: int = None#

optimization_mode: str = 'max'#

restart()[source]#: Reset all counters and timers for a fresh run.

update(algorithm)[source]#

Advance internal counters after one generation.

Parameters:

current_populationPopulation: The population at the end of the current generation. Its best objective is used to update convergence tracking.

Parameters:

algorithm (Algorithm)

is_finished(finished=False)[source]#

Given the state of the algorithm, returns wether we have finished or not.

Return type:

bool

Parameters:

real_time_start: float: The time in seconds that passed since the algorithm was executed.
cpu_time_start: float: The time in seconds that the CPU has executed code in this algorithm.

Returns:

has_stopped: bool: Whether the algorithm has reached its end

Parameters:

finished (bool)

get_progress()[source]#

Compute the current progress (0-1) according to the progress metric.

Return type:

float

Parameters:

gen: int: The number of generations that has passed.
real_time_start: float: The time in seconds that passed since the algorithm was executed.
cpu_time_start: float: The time in seconds that the CPU has executed code in this algorithm.

Returns:

float: A value between 0 (start) and 1 (finished).

get_state()[source]#

Return a dictionary with the current state of the stopping condition.

Return type:

dict

Returns:

dict: Keys include iterations, evaluations, times, and configuration limits.

parse_stopping_cond(condition_str)[source]#

This function parses an expression of the form “neval or cpu_time” into a tree structure so that it can be further processed.

Return type:

List[Union[str, List]]

Parameters:

condition_str: str: The string to be parsed.

Returns:

token_list: List[str | List]: The list of tokens representing the original string.

Parameters:

condition_str (str)

process_condition(cond_parsed, neval, ngen, real_time, cpu_time, target, patience)[source]#

This function receives as an input an expression for the stopping condition and the truth variable of the possible stopping conditions and returns wether to stop or not.

Return type:

bool

Parameters:

cond_parsed: List[str | List]: The list of tokens representing the parsed stopping condition.
neval: int: Number of function evaluations done.
ngen: int: Number of iterations done by the algorithm
real_time: float: Time since the start of the algorithm.
cpu_time: float: Time dedicated by the CPU to optimizing our function.
target: float: Fitness target.
patience: int: Number of time the algorithm has reached the same fitness value in a row.

Returns:

has_stopped: bool: Whether the algorithm has reached its end

Parameters:

cond_parsed (List[str | List])
neval (int)
ngen (int)
real_time (float)
cpu_time (float)
target (float)
patience (int)

process_progress(cond_parsed, neval, ngen, real_time, cpu_time, target, patience)[source]#

This function receives as an input an expression for the stopping condition and the truth variable of the possible stopping conditions and returns wether to stop or not.

Return type:

float

Parameters:

cond_parsed: List[str | List]: The list of tokens representing the parsed stopping condition.
neval: int: Number of function evaluations done.
ngen: int: Number of iterations done by the algorithm
real_time: float: Time since the start of the algorithm.
cpu_time: float: Time dedicated by the CPU to optimizing our function.
target: float: Fitness target.
patience: int: Number of time the algorithm has reached the same fitness value in a row.

Returns:

has_stopped: bool: Indicator of how close it the algorithm to finishing, 1 means the algorithm should be stopped.

Parameters:

cond_parsed (List[str | List])
neval (int)
ngen (int)
real_time (float)
cpu_time (float)
target (float)
patience (int)