CI coverage tests docs-build-status PyPI Python License code style: ruff OpenSSF Scorecard

max-div logo

max-div

Configurable solver for Maximum Diversity Problems with optional fairness constraints: given n items — vectors or precomputed distances — select the k most diverse, optionally subject to per-group minimum/maximum quotas.

max-div is an anytime heuristic: it returns a good selection quickly and keeps improving it for as long as you allow (wall-clock time or iteration count). Two things set it apart among freely available tools: it is the only dedicated diversity solver with native support for overlapping fairness constraints, and the only one offering a geometric-mean separation objective — one of four diversity metrics it provides (minimum, mean, and geometric-mean separation, plus mean pairwise distance).

Feature comparison of max-div against exact solvers and one-shot pickers: distance metrics, diversity objectives, constraint handling, time budgets and practical scale

It fills the gap between exact MIP/CP solvers, which prove optimal answers but do not scale, and single-shot pickers, which are fast but at best have very limited support for constraints. The benchmarks show where it leads and where it does not.

Installation

pip install max-div

Python 3.11+; 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:

License

Licensed under the Apache License 2.0.

Project links

Data verified by PyPI on Jul 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.15.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for bert_pluymers from gravatar.com bert_pluymers

Credits

Author: Bert Pluymers

GitHub Statistics

Data verified by PyPI on Jul 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

docs

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

max_div-0.8.5.tar.gz (125.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

max_div-0.8.5-py3-none-any.whl (200.4 kB view details)

Uploaded Python 3

File details

Details for the file max_div-0.8.5.tar.gz.

File metadata

  • Download URL: max_div-0.8.5.tar.gz
  • Upload date:
  • Size: 125.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for max_div-0.8.5.tar.gz
Algorithm Hash digest
SHA256 83489c339a77f44bbc6eddac4bafd1ad9910d618271bd33288aca2574522b25a
MD5 7c8df6f8f56a6eaa1ddc86994a6304d8
BLAKE2b-256 0dea9f825c0468675b01468d324b0d9ba74a21a1541269ccfc85e380045d96ce

See more details on using hashes here.

Provenance

The following attestation bundles were made for max_div-0.8.5.tar.gz:

Publisher: release_tag.yml on bertpl/max-div

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file max_div-0.8.5-py3-none-any.whl.

File metadata

  • Download URL: max_div-0.8.5-py3-none-any.whl
  • Upload date:
  • Size: 200.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for max_div-0.8.5-py3-none-any.whl
Algorithm Hash digest
SHA256 844b0322885fdd0ec694c8c6a68d1431be1656b45700b47e265582ab33c6707e
MD5 36db280a6c3a02a46c75382d9cfd25c0
BLAKE2b-256 b459876b7d0db37055ac39bcbbaebd5a22bb60b3e50ad6219e7aa21a4be6a4d6

See more details on using hashes here.

Provenance

The following attestation bundles were made for max_div-0.8.5-py3-none-any.whl:

Publisher: release_tag.yml on bertpl/max-div

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.15.0

2 files

0.14.3

2 files

0.14.2

2 files

0.14.1

2 files

0.14.0

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.12.0

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.3

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

This release

0.8.5 This release

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page