ppcluster

Clustering kernels, in POST Python.

ppcluster reimplements scipy.cluster in POST Python — every kernel is fully-typed Python that runs under the standard CPython interpreter and compiles ahead-of-time to native code (a plain C shared library and a NumPy ufunc extension module) with the POST Python reference compiler.

Status: Planning — this repository is scaffolding, ready for an agent or contributor to claim. It is part of the PostSciPy effort to rebuild SciPy one subpackage at a time as the compiler's proving ground.

Primary compiler pressure this package generates: distance/argmin kernels, multi-output gufuncs.

Start here

1. Read the POST Python spec and the PostSciPy roadmap (package map, working rules, capability matrix).
2. Copy the layout of ppspecial, the exemplar package: ppcluster/ sources, tests/, scripts/build_native.py, scripts/build_ext.py, a pixi workspace with test / build-native / build-ext tasks, a git dependency on postpython, and a ROADMAP.md tracking targets and upstream requests.
3. Start with a slice from "Compiles today" below; land it as a small PR with tests in both execution modes.

First slices

Compiles today

• vq (vector quantization) as a multi-output gufunc (n,d),(k,d)->(n),(n) returning codes and distances
• whiten (n,d)->(n,d)
• A single k-means update step (n,d),(k,d)->(k,d) (assign + recompute centroids); a fixed-iteration kmeans loop on top

Blocked on compiler capabilities

File these as postpython issues with minimal reproducers when you start on them — the filing is part of the work and drives the compiler roadmap.

• hierarchy (linkage, dendrogram structures) — needs dynamic data structures; revisit after structs

Working rules (summary)

• Pure POST Python: no compiler-specific escape hatches; every kernel runs interpreted and compiled.
• scipy is the reference, never a runtime dependency. Tests may use it optionally; prefer deterministic hardcoded reference values.
• Compiler gaps go upstream as postpython issues with reproducers, not silent workarounds.
• Verify against a postpython checkout on main.
• Document accuracy targets and reference sources per function.

The full rules and the definition of done live in the PostSciPy roadmap.