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 17, 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 17, 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.13.0.tar.gz (185.6 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.13.0-py3-none-any.whl (285.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: max_div-0.13.0.tar.gz
  • Upload date:
  • Size: 185.6 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.13.0.tar.gz
Algorithm Hash digest
SHA256 901eed6db0b68b3b6d5cb464a9baaf7c22abc9042534d32549a3c05115783cc3
MD5 3c8f26e70d58094f76cd567f1ee8e51f
BLAKE2b-256 fb188f8f4d1cdacd95d8555b858533aedc79e9b7f43d397c9a84010cb75374e1

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: max_div-0.13.0-py3-none-any.whl
  • Upload date:
  • Size: 285.1 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.13.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7d2d62eb5621dda9102d0c6ce3e14202401ffa6bf10fd1a56b73b9e5038717e3
MD5 d81b15e3d127e9dfb516750cd61b7942
BLAKE2b-256 77091b3b981a48fe9ac20dc40501c9c6a191eb65d7343db5044ab8571a2edb77

See more details on using hashes here.

Provenance

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

This release

0.13.0 This release

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