MaxDivProblem

MaxDivProblem dataclass

MaxDivProblem(
    *, k: int, diversity_metric: DiversityMetric, constraints: list[Constraint]
)

Bases: ABC

Immutable definition of a Maximum Diversity Problem.

A problem consists of n items of which k must be selected, a diversity metric, and optionally a list of fairness constraints. Two flavors exist, differing in how item dissimilarity is defined:

• VectorMaxDivProblem — items are vectors and distances are computed with a chosen distance metric; created via new.
• DistanceMaxDivProblem — pairwise distances are supplied directly, for custom or non-Euclidean metrics; created via from_distances.

Use the new / from_distances factory methods to create instances with validation.

n abstractmethod property

n: int

Number of items in the problem.

condensed_distances abstractmethod

condensed_distances() -> NDArray[float32]

Return the condensed pairwise-distance vector (scipy layout), computing it if needed.

new classmethod

new(
    vectors: ndarray,
    k: int,
    distance_metric: DistanceMetric = L2_EUCLIDEAN,
    diversity_metric: DiversityMetric = GEOMEAN_SEPARATION,
    constraints: list[Constraint] | None = None,
) -> VectorMaxDivProblem

Create a new VectorMaxDivProblem with validation.

Parameters:

Name	Type	Description	Default
vectors	ndarray	2D numpy array of shape (n, d) with at least 3 rows. Converted to float32 automatically if needed.	required
k	int	Number of items to select (must satisfy 2 <= k <= n).	required
distance_metric	DistanceMetric	Distance metric for pairwise distances.	L2_EUCLIDEAN
diversity_metric	DiversityMetric	Diversity metric to maximize.	GEOMEAN_SEPARATION
constraints	list[Constraint] | None	Optional list of fairness constraints.	None

from_distances classmethod

from_distances(
    distances: ndarray,
    k: int,
    diversity_metric: DiversityMetric = GEOMEAN_SEPARATION,
    constraints: list[Constraint] | None = None,
) -> DistanceMaxDivProblem

Create a new DistanceMaxDivProblem from precomputed pairwise distances, with validation.

Accepts either a square symmetric (n, n) distance matrix or a condensed distance vector of length n*(n-1)/2 (scipy layout, as produced by scipy.spatial.distance.pdist). Distances are converted to float32 internally.

Parameters:

Name	Type	Description	Default
distances	ndarray	Square symmetric (n, n) matrix with zero diagonal, or condensed 1D vector of length n*(n-1)/2, with at least 3 items. All values must be finite and non-negative.	required
k	int	Number of items to select (must satisfy 2 <= k <= n).	required
diversity_metric	DiversityMetric	Diversity metric to maximize.	GEOMEAN_SEPARATION
constraints	list[Constraint] | None	Optional list of fairness constraints.	None