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 Aug 26, 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 Aug 26, 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

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.14.2.tar.gz (191.9 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.14.2-py3-none-any.whl (294.2 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for max_div-0.14.2.tar.gz
Algorithm Hash digest
SHA256 d6a7d2a753415b25e2a76fe40cdd981bda13364af32fc882acb1c38fa702be6d
MD5 ad549c221e5b40b2bb6e1f7542953bce
BLAKE2b-256 2f887602cb3850310305eb0cc080bbd8edbaff67dbe514a353033aab7adc58b1

See more details on using hashes here.

Provenance

The following attestation bundles were made for max_div-0.14.2.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.14.2-py3-none-any.whl.

File metadata

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

File hashes

Hashes for max_div-0.14.2-py3-none-any.whl
Algorithm Hash digest
SHA256 21a8f89b314656a546282a6f4c4c905a5e3244bae5dc19e238851580357c8c05
MD5 51720c56b6ce512b634343daece54cb8
BLAKE2b-256 1b758293582c7113bce5427ad3fb93ff9770c12c4c685f02f68a5bc043ebc48d

See more details on using hashes here.

Provenance

The following attestation bundles were made for max_div-0.14.2-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

This release

0.14.2 This release

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

0.8.5

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