OptimizationStrategy

OptimizationStrategy(
    name: str | None = None,
    dynamic_params: dict[str, ParamValueType] | None = None,
    ignore_infeasible_diversity_up_to_fraction: float = -1.0,
)

Bases: StrategyBase, ABC

Base class for strategies that iteratively improve a selection via swap operations.

Use the factory methods (random_swaps, guided_swaps, smart_swaps) to create instances, or use solver presets which select appropriate strategies automatically.

Initialize the optimization strategy.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	optional name of the strategy; if omitted class name is used.	`None`
`dynamic_params`	`dict[str, ParamValueType] \| None`	optional dictionary of parameters that are potentially adjusted each iteration. The values of this dictionary are triaged by type, with different action taken: ParameterSchedule these parameters are updated each iteration based on a schedule, which essentially maps progress_fraction -> parameter value. AdaptiveSampler these parameters are sampled from a distribution in each iteration, which is adapted based on success/failure of the resulting swaps. other (float, int, ...) these parameters are fixed for the duration of the strategy.	`None`
`ignore_infeasible_diversity_up_to_fraction`	`float`	float between 0 and 1. If provided, we compare solution scores using the flag 'ignore_infeasible_diversity' until the step has progressed up to this fraction. This allows optimization strategies to focus on satisfying constraints first before trying to improve diversity. Trying to improve diversity while still infeasible wrt constraints, can steer away the solution from more feasible regions of the search space, in case of hard-to-satisfy, overlapping constraints. This parameter will influence how the instance field 'ignore_infeasible_diversity' is set. When not provided it is always False; when provided it will start as True and will get set to False at the appropriate time during optimization.	`-1.0`

perform_n_iterations

perform_n_iterations(
    state: SolverState,
    n_iters: int,
    current_progress_frac: float,
    progress_frac_per_iter: float,
)

Perform n iterations of the optimization strategy, modifying the solver state in-place.

Parameters:

Name	Type	Description	Default
`state`	`SolverState`	(SolverState) current solver state to be modified and used to extract properties of current state.	required
`n_iters`	`int`	(int) number of iterations to perform.	required
`current_progress_frac`	`float`	(float) fraction in [0.0, 1.0] indicating current overall progress through total duration (iterations or time) configured for this SolverStep.	required
`progress_frac_per_iter`	`float`	(float) fraction in [0.0, 1.0] indicating how much progress each iteration contributes towards the total duration configured for this SolverStep. For time-based solver step configurations, this can be an estimate.	required

initial_param_value `staticmethod`

initial_param_value(param: ParamValueType) -> float

Helper method to get the initial value of a parameter that may be either dynamic or fixed. Intended for use inside constructors of child classes.

Parameters:

Name	Type	Description	Default
`param`	`ParamValueType`	(ParamValueType) parameter to get initial value for	required

Returns:

Type	Description
`float`	(float) initial value of the parameter

random_swaps `classmethod`

random_swaps() -> Self

Baseline strategy: randomly removes and adds vectors, keeping swaps that improve the score.

guided_swaps `classmethod`

guided_swaps(
    min_swap_size: int = 1,
    max_swap_size: int = 1,
    swap_size_lambda: float | ParameterSchedule = 1.0,
    constraint_softness: float | ParameterSchedule = 0.0,
    p_add_constraint_aware: float | ParameterSchedule = 1.0,
    remove_selectivity_modifier: float | ParameterSchedule = 0.0,
    add_selectivity_modifier: float | ParameterSchedule = 0.0,
) -> Self

Distance-guided swap strategy: biased towards removing low-separation vectors and adding high-separation ones. Supports scheduled parameters for constraint softness and selectivity.

smart_swaps `classmethod`

smart_swaps(
    swap_size_max: int,
    nc_remove_max: int,
    nc_add_max: int,
    tau_learn: float = 100.0,
    ignore_infeasible_diversity_up_to_fraction: float = -1.0,
    cost_awareness: float = 0.0,
) -> Self

Adaptive swap strategy that learns effective swap sizes and candidate selection strategies during optimization. Used by the SMART and THOROUGH presets.

OptimizationStrategy