max-div
A versatile, high-performance solver for Maximum Diversity Problems — select the k most
diverse of n items, under optional fairness constraints.
Highlights
-
⚡ obtains near-optimal results within seconds-to-one-minute for problems up to
n=200k -
⏱️ runs within an arbitrary solve budget — wall-clock time or iteration count
-
🚀 leverages numba JIT-compilation for maximum speed without relying on pre-compiled binaries
-
⚖️ natively supports flexible fairness constraints
-
uniquely supports constraints with overlapping groups & ranged counts
-
returns the least infeasible solution (with configurable weighted linear or quadratic penalties) when constraints conflict
-
provides proofs of (in)feasibility
-
-
📐 uniquely supports 8+ distance metrics (L1, L2, L∞, L−∞, Minkowski, cosine, geometric mean, single-dimension — or precomputed distances) and 5 diversity metrics (minimum, mean, geomean & harmonic separation + mean pairwise distance) in any combination — including hybrid objectives that combine several diversity terms, each over its own distance
-
💾 computes item distances eagerly when memory allows (maximum speed), lazily when problem size requires (minimal memory usage)
-
🤝 leverages multi-core CPUs with parallel workers in independent, cooperative or dynamically grouped configurations, without duplicating core problem data
The benchmarks compare max-div in depth with the other freely available solvers.
Installation
pip install max-div
Python 3.12+; free-threaded builds (3.14t) are supported and CI-tested (see the installation notes for the numba version they require).
Quick start
import numpy as np
from max_div import MaxDivProblem, MaxDivSolverBuilder, seconds
rng = np.random.default_rng(42)
vectors = rng.random((200, 5)) # 200 points in 5 dimensions
# select the 20 most diverse, improving for up to 5 seconds
problem = MaxDivProblem.new(vectors, k=20)
solution = MaxDivSolverBuilder(problem).with_preset(seconds(5)).build().solve()
print(solution.i_selected) # indices of the selected items
With fairness constraints
Require a minimum and/or maximum number of selected items from given subsets — useful for fair representation across groups. Groups may overlap, and infeasible constraints degrade gracefully to the least-infeasible selection rather than failing.
from max_div import Constraint
# require between 8 and 12 of the selected items from each half of the data
constraints = [
Constraint(int_set=set(range(0, 100)), min_count=8, max_count=12),
Constraint(int_set=set(range(100, 200)), min_count=8, max_count=12),
]
problem = MaxDivProblem.new(vectors, k=20, constraints=constraints)
Documentation
Full documentation lives at max-div.readthedocs.io, including:
- Getting started — installation, distance and diversity metrics, solver presets
- Comparison with other tools — how max-div relates to exact solvers, greedy pickers, clustering and samplers
- Benchmarks — the measured comparison against third-party tools
License
Licensed under the Apache License 2.0.
1 maintainer
Release files for max-div 0.18.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| max_div-0.18.0.tar.gz | 227.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| max_div-0.18.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 569.9 kB
Release files / max_div-0.18.0.tar.gz
| Download URL | max_div-0.18.0.tar.gz |
|---|---|
| Size | 227.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e549482dca6a39774835f19f82c9899870a46bf74633b5bc28003e4731bfc39
|
|
BLAKE2b-256 checksum How to use checksums |
2e4b57f64e31d4357ee4a0ba15121801be9b1d5940b003788f361aaf583ce34b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / max_div-0.18.0-py3-none-any.whl
| Download URL | max_div-0.18.0-py3-none-any.whl |
|---|---|
| Size | 342.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3b413b21186212a09bd27fe0370bba0885241e9d0faed327466cc24cde841f83
|
|
BLAKE2b-256 checksum How to use checksums |
dc4132ecaa34c860d13165561aa71490a61caf10a2bd0f732e8a433f0535f7e0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
