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

max-div logo

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

  • 🚀 leverages numba JIT-compilation for maximum speed without relying on pre-compiled binaries

  • ⚖️ natively supports flexible fairness constraints

    • uniquely supports constraints with overlapping sets & ranged counts

    • returns the least infeasible solution (with configurable weighted linear or quadratic penalties) when constraints conflict

    • provides proofs of (in)feasibility

  • 📐 uniquely supports 5+ distance metrics (L1, L2, L∞, Minkowski, cosine — or precomputed distances) and 4 diversity metrics (minimum, mean & geomean separation + mean pairwise distance) in any combination

  • 💾 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

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

The benchmarks compare max-div in depth with 10 other freely available solvers.

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 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:
Latest release

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 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

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.15.0.tar.gz (198.7 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.15.0-py3-none-any.whl (303.1 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: max_div-0.15.0.tar.gz
  • Upload date:
  • Size: 198.7 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.15.0.tar.gz
Algorithm Hash digest
SHA256 0f8fedec2dbe7e3359334fb65f1ff0130541f9274e4927c88a7ef34308df22cb
MD5 f07b6decd0411c6015fe2c0836993020
BLAKE2b-256 9eaf7b8f01afc7aa0e284ee4cb187a0488af40f8f06d124b2bfc9bd8d26a1769

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: max_div-0.15.0-py3-none-any.whl
  • Upload date:
  • Size: 303.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.15.0-py3-none-any.whl
Algorithm Hash digest
SHA256 01d0d8c991ffdf773b0c55ae28ad76fa2d2600e34290a44ed64037019b424943
MD5 1907419c74f6eb2aeee6cf6f0a27a81c
BLAKE2b-256 2fd0f8baf8cfd478c7ecd9cfc866e8461719cca81157920de8726379bbd88033

See more details on using hashes here.

Provenance

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

This release

0.15.0 This release

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

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