evoc-rs

Python bindings for evoc-rs: EVoC clustering for high-dimensional embeddings. The Rust crate does the work. This is a thin scikit-learn shaped layer over it.

Documentation: https://gregorlueg.github.io/evoc-rs/

Install

You can just install from PyPI.

uv pip install evoc-rs

Use

import numpy as np
import evoc_rs

rng = np.random.default_rng(0)
X = np.vstack([rng.normal(c * 20, 1, (500, 32)) for c in range(4)]).astype(np.float32)

model = evoc_rs.EVoC(n_neighbours=15).fit(X)

model.labels_  # the most persistent layer, -1 is noise
model.cluster_layers_  # (n_layers, n_samples), finest first
model.persistence_scores_  # (n_layers,), higher is more stable

Parameters go in the constructor, data goes into fit, results come off the fitted estimator. get_params, set_params, fit and fit_predict are all there, so it drops into scikit-learn pipelines and GridSearchCV without scikit-learn being an install requirement.

The hierarchy is the point

Most clustering libraries hand you one labelling. EVoC hands you several, one per granularity, ranked by how stable each is. labels_ picks the most persistent for you, but the interesting bit is often a layer or two either side:

for layer, score in zip(model.cluster_layers_, model.persistence_scores_):
    print(f"{layer.max() + 1:3d} clusters, persistence {score:.3f}")

Already know how many clusters you want? Pass approx_n_clusters and the finest layer is binary-searched for it, returning a single layer.

model = evoc_rs.EVoC(approx_n_clusters=8).fit(X)

How it works

Six stages, all in Rust:

  1. Approximate kNN graph, via ann-search-rs.
  2. Fuzzy simplicial set over that graph.
  3. Label-propagation initialisation.
  4. UMAP-like node embedding with a repulsion term tuned by noise_level.
  5. MST over mutual reachability distances in the embedding.
  6. Cluster layers pulled out of the tree by persistence.

Clustering the embedding rather than the original space is what makes it fast and what makes the hierarchy meaningful.

kNN backends

ann_algorithm picks the backend for stage 1. nndescent is the default and the right first choice for a self-kNN graph. exhaustive is exact, and worth it below roughly 10k points. hnsw, annoy, ivf, kmknn and balltree are all there if you have a reason.

Bring your own graph instead, if you already have one:

model = evoc_rs.EVoC().fit(X, precomputed_knn=(indices, distances))

Both arrays are (n_samples, k) and exclude self.

GPU

EVoCGpu moves the kNN stage onto the GPU via wgpu and leaves everything downstream on the CPU. That only pays off when the search dominates: many points, high dimension, or an exhaustive search. float32 only, because WGSL has no f64.

if evoc_rs.gpu_available():
    model = evoc_rs.EVoCGpu(n_neighbours=15).fit(X)

gpu_available() answers both "was this wheel built with GPU support" and "is there an adapter here" at once. The published wheel carries it.

Threads

evoc_rs.set_num_threads(8)  # cap it
evoc_rs.set_num_threads(0)  # back to one per core

Credit

Port of evoc by Leland McInnes. Where behaviour diverges, the Python original is the source of truth.

Project links

Data verified by PyPI on Sep 2, 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 GregorLueg from gravatar.com GregorLueg

Credits

Author: Gregor Lueg

GitHub Statistics

Data verified by PyPI on Sep 2, 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

MIT AND BSD-2-Clause

Requires

Python >=3.10

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 Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

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

evoc_rs-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.4 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

evoc_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl (4.8 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

evoc_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl (5.1 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file evoc_rs-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for evoc_rs-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c7f4b38590557ff600e86661852e82e35fff24d52ba1e5c6968109c0bbacc6fa
MD5 8dc8abed5ff00d98aaf3e849e3e5af62
BLAKE2b-256 4e062e9d436b0b1a9a6f7007bbef7acb612664e768e46603c4b53ec5815852c8

See more details on using hashes here.

Provenance

The following attestation bundles were made for evoc_rs-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: python-release.yml on GregorLueg/evoc-rs

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

File details

Details for the file evoc_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for evoc_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d25209e7a3a3b090e81bc3b60a4b32dd3c1a71bd10c79502ad2e93467785cdbf
MD5 eaa04956de2fcf937eca16bb38e4fc09
BLAKE2b-256 8ae5fb3763751e8201e149b0392b839710149660035e89b0b800d6d514b08b75

See more details on using hashes here.

Provenance

The following attestation bundles were made for evoc_rs-0.1.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: python-release.yml on GregorLueg/evoc-rs

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

File details

Details for the file evoc_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for evoc_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 a486cad62734708ef3824d346fb0a3c7e111384f9946ecb053bb927bfab186b0
MD5 df5ba4cc78b6af99cb29a95957dd00fc
BLAKE2b-256 822518d701ed24f2cd9d10995e98cf979c213b9d6a844b6fb20abe512b5b26f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for evoc_rs-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: python-release.yml on GregorLueg/evoc-rs

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.1.0 This release

3 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