solver

solver

InitializationStrategy 

InitializationStrategy(name: str | None = None)

Bases: StrategyBase, ABC

get_next_samples abstractmethod 

get_next_samples(
    state: SolverState, k_remaining: int | int32
) -> NDArray[int32]

Return next batch of samples to be added to the initial selection.

This method is called repeatedly by the Solver, until enough samples have been selected to reach the desired selection size.

Parameters:

Name Type Description Default
state SolverState

(SolverState) The current solver state, to fetch problem size, constraints, distances, etc..., so initial selection can be made in an informed way.

 required
k_remaining int | int32

(int) number of samples that remain to be selected.

 required

Returns:

Type Description
NDArray[int32]

np.array of unique np.int32 values, shape=(b,), with indices of samples to be added to the selection. b can be any value in range [1, k_remaining]. Samples should be unique and not yet selected.

fast classmethod 

fast() -> Self

Create a InitFast initialization strategy.

random_one_shot classmethod 

random_one_shot(
    uniform: bool = False, ignore_constraints: bool = False
) -> Self

Create a InitRandomOneShot initialization strategy.

random_batched classmethod 

random_batched(b: int, ignore_constraints: bool = False) -> Self

Create a InitRandomBatched initialization strategy.

eager classmethod 

eager(nc: int, ignore_constraints: bool = False) -> Self

Create a InitEager initialization strategy.

MaxDivSolver 

MaxDivSolver(
    vectors: ndarray,
    k: int,
    distance_metric: DistanceMetric,
    diversity_metric: DiversityMetric,
    diversity_tie_breakers: list[DiversityMetric],
    constraints: list[Constraint],
    solver_steps: list[SolverStep],
    seed: int = 42,
)

Class that represents a combination of... - a maximum diversity problem (potentially with fairness constraints) - a solver configuration for that problem

The class allows solving the said problem with the said configuration, resulting in a MaxDivSolution object.

It is STRONGLY recommended to use the MaxDivSolverBuilder class to create instances of this class, since it provides convenient defaults, presets and validation of the configuration.

Initialize the MaxDivSolver with the given configuration.

Parameters:

Name Type Description Default
vectors ndarray

(n x d ndarray) A set of n vectors in d dimensions.

 required
k int

(int) The number of vectors to be selected from the input set ('universe').

 required
distance_metric DistanceMetric

(DistanceMetric) The distance metric to use.

 required
diversity_metric DiversityMetric

(DiversityMetric) The diversity metric to use.

 required
diversity_tie_breakers list[DiversityMetric]

(list[DiversityMetric]) A list of diversity tie-breaker metrics to use.

 required
constraints list[Constraint]

(list[Constraint]) A list of m constraints to try to satisfy during solving.

 required
solver_steps list[SolverStep]

(list[SolverStep]) A list of solver steps to execute, the first of which needs to be an InitializationStep, while all latter ones need to be OptimizationSteps.

 required
seed int

(int) Random seed for the solver.

 42

solve 

solve(verbosity: int = 10) -> MaxDivSolution

Solve the maximum diversity problem with the given configuration.

Parameters:

Name Type Description Default
verbosity int

(int) The verbosity level. 0 = silent, 10 = tqdm progress bar per solver step 2x = progress table with iteration count, metrics, elapsed time, ... 20 --> slowest updates (spacing increasing with 10%) 21 --> slower updates (spacing increasing with 5%) 22 --> faster updates (spacing increasing with 2%) 23 --> fastest updates (spacing increasing with 1%)

   25  -->  debug mode       (1% spacing + debug info column)
10

Returns:

Type Description
MaxDivSolution

A MaxDivSolution object representing the solution found.

MaxDivSolverBuilder 

MaxDivSolverBuilder(problem: MaxDivProblem)

Initialize the MaxDivSolverBuilder.

with_preset 

with_preset(
    target_duration: TargetDuration, preset: SolverPreset = DEFAULT
) -> Self

Configure the builder with specified preset settings (overriding any previous settings): - Appropriate initialization strategy (most accurate strategy+settings taking est. <5% of total time) - Appropriate optimization strategy - Default diversity tie-breakers

Please make sure to set diversity metric prior to calling this method, as it influences the choices.

Parameters:

Name Type Description Default
target_duration TargetDuration

Target duration for the init+optim phases (either in time or iterations). --> rule of thumb for #iterations : 10-100x 'k' should be a good starting point.

 required
preset SolverPreset

Preset to use (default: SolverPreset.DEFAULT)

 DEFAULT

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

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

SolverPreset

Bases: StrEnum

all_sorted classmethod 

all_sorted() -> list[SolverPreset]

Return list of unique (as in 'resolve_alias'), sorted presets.

TargetDuration

Bases: ABC

value abstractmethod 

value() -> float

numerical value (without unit) of the target duration