metaheuristic_designer.parameter_schedules package

Submodules

metaheuristic_designer.parameter_schedules.exponential_decay_schedule module

Schedule that decays a value exponentially, either continuously or iteratively.

class ExponentialDecaySchedule(init_value: float, final_value: float = 0, alpha: float = 0.9, iterative: bool = True)

Bases: SchedulableParameter

Schedule that exponentially decays a value from init_value towards final_value.

In iterative mode (iterative=True, the default), the current value is multiplied by alpha each time the schedule is evaluated. In continuous mode, the decay follows the function final_value + (init_value - final_value) * exp(-alpha * progress).

Parameters:

• init_value (float) – Starting value at progress 0.

• final_value (float, optional) – Asymptotic value (default 0).

• alpha (float, optional) – Decay factor. In iterative mode it must be in (0, 1); in continuous mode it controls the rate of decay.

• iterative (bool, optional) – If True (default), the value is updated step-by-step. If False, decay is computed directly from progress.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

metaheuristic_designer.parameter_schedules.linear_schedule module

Schedule that changes a value linearly between two endpoints.

class LinearSchedule(init_value: float, final_value: float)

Bases: SchedulableParameter

Schedule that interpolates linearly between init_value and final_value.

Parameters:

• init_value (float) – Value at progress 0.

• final_value (float) – Value at progress 1.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

metaheuristic_designer.parameter_schedules.logistic_schedule module

Schedule that follows a sigmoidal (logistic) transition between two values.

class LogisticSchedule(init_value: float, final_value: float, k: float = 10, exact_bounds: bool = False)

Bases: SchedulableParameter

Schedule that transitions between two values following a sigmoid curve.

The steepness is controlled by k. When exact_bounds is True, the output is rescaled to exactly start at init_value and end at final_value.

Parameters:

• init_value (float) – Starting value.

• final_value (float) – Target value.

• k (float, optional) – Steepness of the logistic curve (default 10).

• exact_bounds (bool, optional) – If True, the output is rescaled to hit the exact bounds at progress 0 and 1.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

metaheuristic_designer.parameter_schedules.random_schedule module

Schedule that picks a random value at each evaluation.

class RandomSchedule(init_value: float, final_value: float, random_state: int | Generator | None = None)

Bases: SchedulableParameter

Schedule that returns a uniform random value between init_value and final_value at every call, ignoring progress.

Parameters:

• init_value (float) – Lower bound of the random interval.

• final_value (float) – Upper bound of the random interval.

• random_state (RNGLike, optional) – Random number generator.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

metaheuristic_designer.parameter_schedules.step_schedule module

Schedule that changes value at discrete progress thresholds.

class StepSchedule(steps: dict[float, Any])

Bases: SchedulableParameter

Schedule defined by a dictionary of progress-value pairs.

At progress p, the schedule returns the value associated with the largest key ≤ p. This produces a step function.

Parameters:

steps (dict) – Mapping of progress thresholds (floats in [0, 1]) to the values that should be active at or after that threshold.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

metaheuristic_designer.parameter_schedules.threshold_schedule module

Schedule that switches between two values at a fixed progress threshold.

class ThresholdSchedule(init_value: float, final_value: float, threshold: float = 0.5)

Bases: SchedulableParameter

Schedule that returns init_value until progress reaches threshold, then switches to final_value.

Parameters:

• init_value (float) – Value used before the threshold.

• final_value (float) – Value used after the threshold.

• threshold (float, optional) – Progress point at which the switch occurs (default 0.5).

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

Module contents

Built-in parameter schedules for dynamic algorithm configuration.

class LinearSchedule(init_value: float, final_value: float)

Bases: SchedulableParameter

Schedule that interpolates linearly between init_value and final_value.

Parameters:

• init_value (float) – Value at progress 0.

• final_value (float) – Value at progress 1.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class LogisticSchedule(init_value: float, final_value: float, k: float = 10, exact_bounds: bool = False)

Bases: SchedulableParameter

Schedule that transitions between two values following a sigmoid curve.

The steepness is controlled by k. When exact_bounds is True, the output is rescaled to exactly start at init_value and end at final_value.

Parameters:

• init_value (float) – Starting value.

• final_value (float) – Target value.

• k (float, optional) – Steepness of the logistic curve (default 10).

• exact_bounds (bool, optional) – If True, the output is rescaled to hit the exact bounds at progress 0 and 1.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class RandomSchedule(init_value: float, final_value: float, random_state: int | Generator | None = None)

Bases: SchedulableParameter

Schedule that returns a uniform random value between init_value and final_value at every call, ignoring progress.

Parameters:

• init_value (float) – Lower bound of the random interval.

• final_value (float) – Upper bound of the random interval.

• random_state (RNGLike, optional) – Random number generator.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class SchedulableParameter(random_state: int | Generator | None = None)

Bases: ABC

Abstract base for parameters that depend on the optimization progress.

A schedulable parameter is a callable that receives a progress value between 0 and 1 and returns the parameter’s value at that point. Subclasses implement evaluate().

Parameters:

random_state (RNGLike, optional) – Random number generator, made available for subclasses that need stochastic schedules.

abstract evaluate(progress: float) → Any

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class StepSchedule(steps: dict[float, Any])

Bases: SchedulableParameter

Schedule defined by a dictionary of progress-value pairs.

At progress p, the schedule returns the value associated with the largest key ≤ p. This produces a step function.

Parameters:

steps (dict) – Mapping of progress thresholds (floats in [0, 1]) to the values that should be active at or after that threshold.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class ThresholdSchedule(init_value: float, final_value: float, threshold: float = 0.5)

Bases: SchedulableParameter

Schedule that returns init_value until progress reaches threshold, then switches to final_value.

Parameters:

• init_value (float) – Value used before the threshold.

• final_value (float) – Value used after the threshold.

• threshold (float, optional) – Progress point at which the switch occurs (default 0.5).

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class ExponentialDecaySchedule(init_value: float, final_value: float = 0, alpha: float = 0.9, iterative: bool = True)

Bases: SchedulableParameter

Schedule that exponentially decays a value from init_value towards final_value.

In iterative mode (iterative=True, the default), the current value is multiplied by alpha each time the schedule is evaluated. In continuous mode, the decay follows the function final_value + (init_value - final_value) * exp(-alpha * progress).

Parameters:

• init_value (float) – Starting value at progress 0.

• final_value (float, optional) – Asymptotic value (default 0).

• alpha (float, optional) – Decay factor. In iterative mode it must be in (0, 1); in continuous mode it controls the rate of decay.

• iterative (bool, optional) – If True (default), the value is updated step-by-step. If False, decay is computed directly from progress.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class ProbabilityAnnealingSchedule(temperature_init=100, iterations=100, alpha=0.99, random_state=None)

Bases: StridedSchedule

Annealing strategies for probabilities.

Holds a temperature parameter that is exponentially decayed and transformed into a probability using an ExponentialDecaySchedule internally.

Parameters:

• temperature_init (int, optional) – Initial temperature, by default 100

• iterations (int, optional) – iterations to keep the previous parameter without updating, by default 100

• alpha (float, optional) – multiplier to apply to the temperature each update, by default 0.99

• random_state – Random state.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class StridedSchedule(subschedule: SchedulableParameter, iterations: int = 100)

Bases: SchedulableParameter

Schedule that applies a subschedule when a number of iterations have passed, keeping the previous value between updates.

Parameters:

• subschedule (SchedulableParameter) – Parameter schedule to modify the parameter each iterations iterations.

• iterations (int, optional) – iterations to keep the current value unchanged, by default 100

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class CosineSchedule(amplitude: float = 1, frequency: float | None = None, phase: float = 0, offset: float = 0)

Bases: SchedulableParameter

Schedule that models the parameter as a cosine wave in the range [0, 1].

Parameters:

• amplitude (float) – Amplitude of the cosine wave.

• frequency (float) – Frequency of the cosine wave.

• phase (float) – Phase of the cosine wave.

• offset (float) – Offset of the cosine wave.

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.

class NoisySchedule(subschedule: SchedulableParameter, noise_level: float = 0.01)

Bases: SchedulableParameter

Schedule that applies gaussian noise to a subschedule.

Parameters:

• subschedule (SchedulableParameter) – Parameter schedule to modify the parameter each iterations iterations.

• noise_level (float, optional) – Standard deviation of the gaussian noise applied to the parameter value

evaluate(progress: float) → float

Return the parameter value at the given progress.

Parameters:

progress (float) – Current progress, a number between 0 (start) and 1 (end).

Returns:

The parameter value at this stage of the optimization.

Return type:

Any

Notes

The return value is not restricted to numbers. You can return: * a float (e.g., a linearly decaying mutation strength), * an int (e.g., a discrete number of mutated components), * a bool (e.g., switching on/off a feature after a threshold), * a string (e.g., switching between strategies), or * any other object that the consuming component expects.

This makes schedules suitable for changing discrete algorithm choices as well as continuous numerical parameters.