shufflesnap 0.3.0__tar.gz

shufflesnap-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    name: Tests (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.12", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and test dependencies
+        run: python -m pip install -U pip && python -m pip install -e '.[test]'
+
+      - name: Run tests
+        run: python -m pytest -q
+
+  dist:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: pip
+
+      - name: Install release tooling
+        run: python -m pip install -U pip build twine pytest scipy
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Smoke test sdist install
+        run: python -m pip install --force-reinstall dist/*.tar.gz && python -m pytest -q tests/test_smoke.py
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: ci-dist
+          path: dist/*
+          if-no-files-found: error

shufflesnap-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+          cache: pip
+
+      - name: Install build tooling
+        run: python -m pip install -U pip build twine pytest scipy
+
+      - name: Build sdist
+        run: python -m build --sdist
+
+      - name: Check sdist metadata
+        run: python -m twine check dist/*
+
+      - name: Smoke test sdist install
+        run: python -m pip install --force-reinstall dist/*.tar.gz && python -m pytest -q tests/test_smoke.py
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist-sdist
+          path: dist/*
+          if-no-files-found: error
+
+  build-wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    env:
+      CIBW_ENVIRONMENT_MACOS: MACOSX_DEPLOYMENT_TARGET=11.0
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-15-intel, macos-14]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: pypa/cibuildwheel@v3.3.0
+        with:
+          output-dir: wheelhouse
+
+      - uses: actions/upload-artifact@v6
+        with:
+          name: dist-${{ matrix.os }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build-sdist, build-wheels]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/shufflesnap
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          pattern: dist-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

shufflesnap-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.pytest_cache/
+.scikit-build/
+.venv*/
+build/
+dist/
+wheelhouse/
+
+__pycache__/
+*.py[cod]
+
+examples/basic_usage_output.png

shufflesnap-0.3.0/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.18)
+project(shufflesnap LANGUAGES CXX)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(nanobind CONFIG REQUIRED)
+
+nanobind_add_module(_core src/core.cpp)
+target_compile_features(_core PRIVATE cxx_std_17)
+
+install(TARGETS _core LIBRARY DESTINATION shufflesnap)

shufflesnap-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle McDonald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shufflesnap-0.3.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: shufflesnap
+Version: 0.3.0
+Summary: Multiscale window solver for large point-to-grid assignment.
+Keywords: assignment,lap,point-cloud,grid,auction,jv
+Author: Kyle McDonald
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: C++
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Project-URL: Homepage, https://github.com/kylemcdonald/shufflesnap
+Project-URL: Repository, https://github.com/kylemcdonald/shufflesnap
+Project-URL: Issues, https://github.com/kylemcdonald/shufflesnap/issues
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.8; extra == "examples"
+Provides-Extra: test
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: scipy>=1.10; extra == "test"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: cibuildwheel>=3.0; extra == "release"
+Requires-Dist: twine>=5.1; extra == "release"
+Description-Content-Type: text/markdown
+
+# shufflesnap
+
+`shufflesnap` assigns large 2D point clouds to regular grids: every point gets its own grid cell, and the solver seeks a small total squared movement using multiscale local descent. It is a Python package with a native C++ core and `nanobind` bindings. The main use case is turning embeddings (UMAP, t-SNE, Isomap) into image atlases.
+
+Instead of building an `n x n` cost matrix, `shufflesnap` refines a trivial legal assignment by solving exact linear assignment problems inside small grid windows at multiple scales — coarse-to-fine strided windows repair global structure in a handful of rounds, then stride-1 windows polish. The assignment is legal after every round, the cost never increases, memory is linear in the number of points plus grid cells, and random initialization works well on the tested distributions. Final accuracy and the number of polishing rounds have no worst-case guarantee.
+
+The public API has three functions:
+
+1. `snap_to_grid(points, width=None, height=None, cleanup_seconds=None, ...)`
+2. `window_cleanup(points, initial_assignment, rows, cols, budget_seconds=None, ...)`
+3. `linear_sum_assignment(cost_matrix)`
+
+## Install
+
+```bash
+python -m pip install shufflesnap
+```
+
+To run the matplotlib example from the source tree:
+
+```bash
+python -m pip install -e '.[examples]'
+python examples/basic_usage.py
+```
+
+## API
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=None, ...)`
+
+High-level wrapper for snapping a 2D point cloud onto a destination grid. Inputs must use the same coordinate system as the target grid (default range `[0.03, 0.97]` per axis); the API does not normalize inputs.
+
+Behavior:
+
+- chooses a destination grid automatically when `width` and `height` are omitted: an exact factorization of `n` with aspect ratio in `[1:1, 2:1]` when one exists, otherwise a slightly larger near-square grid
+- supports any `n <= width * height` directly: the occupied cell subset is selected before cleanup and remains fixed
+- by default cleanup runs until none of the four scheduled half-offset tilings can improve the assignment; `cleanup_seconds` caps the time instead, and `0.0` returns the raw seed (a deterministic random permutation, with a fixed random cell subset when the grid has more cells than points)
+- `polish_all_offsets=True` adds one stride-1 sweep over every complete window placement after normal cleanup, reducing the remaining local error at additional cost
+- pass `mask` (a `(height, width)` bool array) to restrict which cells may be used — shaped atlases (circles, cut corners, a half-empty last row) work out of the box
+
+Returns:
+
+- `grid_points`: `(n, 2)` float64 NumPy array of assigned destination points in original point order
+- `assignment`: `(n,)` int64 NumPy array of destination-grid cell ids in original point order
+- `(width, height)`: destination-grid size tuple
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds=None, ...)`
+
+Improve any legal assignment with the native multiscale window cleanup kernel.
+
+Key options:
+
+- `budget_seconds=None` runs until converged (a full stride-1 round changes nothing)
+- `strides=None` uses the automatic coarse-to-fine schedule; pass a list to override
+- `window_size=6`
+- `all_offsets=True` uses all `window_size ** 2` tiling offsets instead of the default four and is substantially slower
+- `num_threads=None` to use `std::thread::hardware_concurrency()`
+- `fixed_suffix_count` to keep a suffix of target cells fixed; `cell_mask` to mark which cells may be used at all
+- `trace_rounds=True` to record per-round cost, elapsed time, and stride
+
+Returns a dict with `assignment`, `rounds_completed`, `elapsed_s`, `final_cost`, and `converged`.
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square linear assignment problem exactly with the native C++ Jonker-Volgenant implementation.
+
+Returns:
+
+- `row_ind`: `int64` NumPy array of shape `(n,)`
+- `col_ind`: `int64` NumPy array of shape `(n,)`
+- `total_cost`: Python `float`
+
+## More
+
+- Source repository: https://github.com/kylemcdonald/shufflesnap
+- Issue tracker: https://github.com/kylemcdonald/shufflesnap/issues
+- Example scripts: https://github.com/kylemcdonald/shufflesnap/tree/main/examples

shufflesnap-0.3.0/PUBLISHING.md

@@ -0,0 +1,47 @@
+# Publishing `shufflesnap`
+
+The distribution name, import package, native extension destination, repository URLs, and GitHub Actions workflow all use `shufflesnap`. The prepared version is 0.3.0.
+
+## Current release status
+
+The new PyPI project is not published yet. As of 2026-09-15, its public project endpoint returned 404. Publishing a renamed distribution creates a new PyPI project; it does not migrate existing installations or transfer the old project's releases. Keep the previous distribution available for existing users.
+
+This workspace has GitHub authentication but no configured PyPI upload credentials. The repository uses GitHub OIDC trusted publishing, which must be configured separately for the new project name.
+
+## One-time account setup
+
+In [PyPI publishing settings](https://pypi.org/manage/account/publishing/), add a **pending publisher** with:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name | `shufflesnap` |
+| GitHub owner | `kylemcdonald` |
+| Repository | `shufflesnap` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+The workflow filename field takes `release.yml`, not the full path. The repository already has the `pypi` environment. See [PyPI's new-project instructions](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+## Validate locally
+
+From the library repository:
+
+```bash
+python -m pip install -U build twine pytest scipy
+python -m build
+python -m twine check dist/*
+python -m pip install --force-reinstall dist/*.whl
+python -m pytest -q
+```
+
+Test an sdist installation in a separate environment as well. CI checks editable installations on Linux, macOS, and Windows and builds distributions. The release workflow builds wheels for Linux, Windows, and both macOS architectures.
+
+## Publish after account setup and review
+
+1. Push the reviewed source and confirm CI passes.
+2. Create and push the release tag `v0.3.0`, or dispatch `release.yml` on the reviewed commit.
+3. Confirm all wheel jobs and the PyPI publish job succeed.
+4. In a clean environment, run `pip install shufflesnap` and verify `import shufflesnap`.
+5. Update any release-status prose and confirm the package link before submitting the paper.
+
+Do not tag solely to test PyPI configuration: the release workflow publishes publicly. `README_PYPI.md` is the package long description; `README.md` also includes the visual example.

shufflesnap-0.3.0/README.md

@@ -0,0 +1,130 @@
+# shufflesnap
+
+`shufflesnap` assigns large 2D point clouds to regular grids: every point gets its own grid cell, and the solver seeks a small total squared movement using multiscale local descent. It is a Python package with a native C++ core and `nanobind` bindings.
+
+The main use case is turning embeddings (UMAP, t-SNE, Isomap) into image atlases: millions of points, one thumbnail per cell, no overlap.
+
+The public API is three functions:
+
+1. `snap_to_grid(points, ...)` — the high-level entry point
+2. `window_cleanup(points, initial_assignment, rows, cols, ...)` — the multiscale solver behind it
+3. `linear_sum_assignment(cost_matrix)` — a native dense square Jonker-Volgenant solver
+
+## How it works
+
+`shufflesnap` never builds the `n x n` cost matrix that makes exact dense assignment infeasible at scale (a million points would need 7.3 TiB). Instead it starts from a trivial legal assignment and repeatedly solves exact linear assignment problems inside small windows of the grid — at multiple scales.
+
+A window is at most `6x6` cells. At stride 1, windows cover contiguous cells and fix local defects. At stride `s`, the same windows cover every `s`-th cell, so one exact `36`-cell solve can move points all the way across the grid. One coarse-to-fine sweep (stride halving from grid-spanning down to 1, like the gap sequence in shell sort) repairs global structure in a handful of rounds; stride-1 rounds then polish until the budget expires or nothing changes.
+
+Each default round uses four tilings offset by half a window on either axis. Shifted tilings are clipped into smaller disjoint windows at the far grid edges; the omitted leading half-window remains covered by the unshifted phases.
+
+Properties:
+
+- **Anytime and monotone.** The assignment is legal after every round and the cost never increases.
+- **Self-seeding.** The default seed is a deterministic random permutation: on the tested nonuniform benchmarks it usually reaches lower final costs than a raster-sorted seed. There is no worst-case approximation guarantee.
+- **Linear memory.** No global cost matrix, ever.
+- **Parallel.** All windows in a phase are disjoint and solved on native C++ threads.
+- **Predetermined occupancy.** If `n < width * height`, the occupied cell subset is selected before cleanup and remains fixed.
+
+## Showcase
+
+`512x512` meandering point cloud, rendered as a three-panel hero image on a black background:
+
+1. the initial point cloud
+2. a `50%` interpolated view
+3. the final grid
+
+All three panels use the same Lab-derived coloring with source `x/y` mapped into `a/b`.
+
+![shufflesnap triptych showcase](assets/showcase_triptych_512.png)
+
+## Install
+
+From PyPI:
+
+```bash
+python -m pip install shufflesnap
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e .
+```
+
+## API
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=None, window_size=6, margin=0.03, num_threads=None, mask=None, polish_all_offsets=False)`
+
+Assign a 2D point cloud to distinct cells of a regular grid.
+
+- `points`: `(n, 2)` float64 array-like, in the same coordinates as the target grid (default range `[0.03, 0.97]` on each axis); inputs are not automatically normalized
+- `width`, `height`: destination grid; omitted, a near-square grid with aspect ratio in `[1:1, 2:1]` is chosen (an exact factorization of `n` when one exists, otherwise a slightly larger grid with occupancy fixed before cleanup)
+- `cleanup_seconds`: optional wall-clock cap; by default cleanup runs until none of the four scheduled half-offset tilings can improve the assignment; `0.0` returns the raw seed (a deterministic random permutation, with a fixed random cell subset when the grid has more cells than points)
+- `polish_all_offsets`: after normal cleanup, run one stride-1 sweep over all `window_size ** 2` tiling offsets; this tests every complete window placement and can reduce the remaining local error at additional cost
+- `mask`: optional `(height, width)` bool array restricting which cells may be used, e.g. to shape the atlas or choose its occupied region
+- `num_threads`: `None` uses all hardware threads
+
+Returns:
+
+- `grid_points`: `(n, 2)` float64 array of assigned grid positions, in input order
+- `assignment`: `(n,)` int64 array of destination cell ids (`row * width + col`)
+- `(width, height)`: the destination grid size
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds=None, window_size=6, margin=0.03, num_threads=None, fixed_suffix_count=0, strides=None, trace_rounds=False, cell_mask=None, all_offsets=False)`
+
+Improve any legal assignment with multiscale window cleanup.
+
+- `points` may number fewer than `rows * cols`; cells unoccupied in `initial_assignment` remain unavailable throughout cleanup
+- `budget_seconds=None` runs until converged (a full stride-1 round changes nothing)
+- `strides=None` uses `default_stride_schedule(rows, cols, window_size)`: one round per stride, coarse to fine, then stride 1 repeats. Pass a custom list of strides (ints or `(row, col)` pairs) to override; the last entry repeats.
+- `all_offsets=False` uses the four scheduled tilings at offsets `0` and `window_size // 2` on each axis; `True` uses all `window_size ** 2` tiling offsets and is substantially slower
+- `fixed_suffix_count` keeps a suffix of target cells locked; `cell_mask` marks which cells may be used at all
+- `trace_rounds=True` adds per-round `round_elapsed_s`, `round_costs`, `round_strides` arrays to the result
+
+Returns a dict with `assignment`, `rounds_completed`, `elapsed_s`, `final_cost`, and `converged`.
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square LAP exactly with the native C++ Jonker-Volgenant implementation. Useful for small problems and for auditing `window_cleanup` results.
+
+Returns `(row_ind, col_ind, total_cost)`.
+
+## Example
+
+```python
+import numpy as np
+import shufflesnap
+
+points = np.random.default_rng(0).random((100_000, 2))
+grid_points, assignment, (width, height) = shufflesnap.snap_to_grid(points)
+```
+
+See [examples/basic_usage.py](examples/basic_usage.py) for a rendered example:
+
+```bash
+python -m pip install -e '.[examples]'
+python examples/basic_usage.py
+```
+
+The showcase image above was generated with:
+
+```bash
+python examples/render_showcase.py \
+  --grid-width 512 \
+  --grid-height 512 \
+  --image-width 512 \
+  --image-height 512 \
+  --cleanup-seconds 30 \
+  --output assets/showcase_triptych_512.png
+```
+
+For release instructions, see [PUBLISHING.md](PUBLISHING.md).
+
+## Notes
+
+- `linear_sum_assignment()` expects a square cost matrix.
+- The cleanup kernel uses windows of at most `6x6`, so the native small-LAP kernel is specialized for up to `36` occupied cells per window.
+- The native cleanup kernel uses standard C++ threads and does not depend on OpenMP.
+- With `budget_seconds=None` (run to convergence), assignments are deterministic for fixed inputs and parameters, independent of thread count. With a finite budget, the number of completed rounds can vary with machine load.
+- GitHub Actions builds release artifacts for Linux, macOS, and Windows wheels, plus an sdist.

shufflesnap-0.3.0/README_PYPI.md

@@ -0,0 +1,76 @@
+# shufflesnap
+
+`shufflesnap` assigns large 2D point clouds to regular grids: every point gets its own grid cell, and the solver seeks a small total squared movement using multiscale local descent. It is a Python package with a native C++ core and `nanobind` bindings. The main use case is turning embeddings (UMAP, t-SNE, Isomap) into image atlases.
+
+Instead of building an `n x n` cost matrix, `shufflesnap` refines a trivial legal assignment by solving exact linear assignment problems inside small grid windows at multiple scales — coarse-to-fine strided windows repair global structure in a handful of rounds, then stride-1 windows polish. The assignment is legal after every round, the cost never increases, memory is linear in the number of points plus grid cells, and random initialization works well on the tested distributions. Final accuracy and the number of polishing rounds have no worst-case guarantee.
+
+The public API has three functions:
+
+1. `snap_to_grid(points, width=None, height=None, cleanup_seconds=None, ...)`
+2. `window_cleanup(points, initial_assignment, rows, cols, budget_seconds=None, ...)`
+3. `linear_sum_assignment(cost_matrix)`
+
+## Install
+
+```bash
+python -m pip install shufflesnap
+```
+
+To run the matplotlib example from the source tree:
+
+```bash
+python -m pip install -e '.[examples]'
+python examples/basic_usage.py
+```
+
+## API
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=None, ...)`
+
+High-level wrapper for snapping a 2D point cloud onto a destination grid. Inputs must use the same coordinate system as the target grid (default range `[0.03, 0.97]` per axis); the API does not normalize inputs.
+
+Behavior:
+
+- chooses a destination grid automatically when `width` and `height` are omitted: an exact factorization of `n` with aspect ratio in `[1:1, 2:1]` when one exists, otherwise a slightly larger near-square grid
+- supports any `n <= width * height` directly: the occupied cell subset is selected before cleanup and remains fixed
+- by default cleanup runs until none of the four scheduled half-offset tilings can improve the assignment; `cleanup_seconds` caps the time instead, and `0.0` returns the raw seed (a deterministic random permutation, with a fixed random cell subset when the grid has more cells than points)
+- `polish_all_offsets=True` adds one stride-1 sweep over every complete window placement after normal cleanup, reducing the remaining local error at additional cost
+- pass `mask` (a `(height, width)` bool array) to restrict which cells may be used — shaped atlases (circles, cut corners, a half-empty last row) work out of the box
+
+Returns:
+
+- `grid_points`: `(n, 2)` float64 NumPy array of assigned destination points in original point order
+- `assignment`: `(n,)` int64 NumPy array of destination-grid cell ids in original point order
+- `(width, height)`: destination-grid size tuple
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds=None, ...)`
+
+Improve any legal assignment with the native multiscale window cleanup kernel.
+
+Key options:
+
+- `budget_seconds=None` runs until converged (a full stride-1 round changes nothing)
+- `strides=None` uses the automatic coarse-to-fine schedule; pass a list to override
+- `window_size=6`
+- `all_offsets=True` uses all `window_size ** 2` tiling offsets instead of the default four and is substantially slower
+- `num_threads=None` to use `std::thread::hardware_concurrency()`
+- `fixed_suffix_count` to keep a suffix of target cells fixed; `cell_mask` to mark which cells may be used at all
+- `trace_rounds=True` to record per-round cost, elapsed time, and stride
+
+Returns a dict with `assignment`, `rounds_completed`, `elapsed_s`, `final_cost`, and `converged`.
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square linear assignment problem exactly with the native C++ Jonker-Volgenant implementation.
+
+Returns:
+
+- `row_ind`: `int64` NumPy array of shape `(n,)`
+- `col_ind`: `int64` NumPy array of shape `(n,)`
+- `total_cost`: Python `float`
+
+## More
+
+- Source repository: https://github.com/kylemcdonald/shufflesnap
+- Issue tracker: https://github.com/kylemcdonald/shufflesnap/issues
+- Example scripts: https://github.com/kylemcdonald/shufflesnap/tree/main/examples

shufflesnap-0.3.0/examples/basic_usage.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import pathlib
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import shufflesnap
+
+
+def make_meandering_points(n: int, seed: int = 0, margin: float = 0.03) -> np.ndarray:
+    rng = np.random.default_rng(seed)
+    steps = rng.normal(loc=0.0, scale=1.0, size=(n, 2))
+    points = np.cumsum(steps, axis=0)
+    mins = points.min(axis=0)
+    maxs = points.max(axis=0)
+    span = np.maximum(maxs - mins, np.finfo(np.float64).eps)
+    points = (points - mins) / span
+    points = margin + (1.0 - 2.0 * margin) * points
+    return np.asarray(points, dtype=np.float64)
+
+
+def lab_to_srgb(points: np.ndarray) -> np.ndarray:
+    l = np.full(points.shape[0], 72.0, dtype=np.float64)
+    a = (points[:, 0] * 2.0 - 1.0) * 80.0
+    b = (points[:, 1] * 2.0 - 1.0) * 80.0
+
+    fy = (l + 16.0) / 116.0
+    fx = fy + a / 500.0
+    fz = fy - b / 200.0
+
+    epsilon = 216.0 / 24389.0
+    kappa = 24389.0 / 27.0
+
+    def invf(t: np.ndarray) -> np.ndarray:
+        t3 = t * t * t
+        return np.where(t3 > epsilon, t3, (116.0 * t - 16.0) / kappa)
+
+    x = 0.95047 * invf(fx)
+    y = invf(fy)
+    z = 1.08883 * invf(fz)
+
+    r_lin = 3.2404542 * x - 1.5371385 * y - 0.4985314 * z
+    g_lin = -0.9692660 * x + 1.8760108 * y + 0.0415560 * z
+    b_lin = 0.0556434 * x - 0.2040259 * y + 1.0572252 * z
+    rgb_lin = np.clip(np.column_stack([r_lin, g_lin, b_lin]), 0.0, 1.0)
+
+    threshold = 0.0031308
+    rgb = np.where(
+        rgb_lin <= threshold,
+        12.92 * rgb_lin,
+        1.055 * np.power(rgb_lin, 1.0 / 2.4) - 0.055,
+    )
+    return np.clip(rgb, 0.0, 1.0)
+
+
+def main() -> None:
+    points = make_meandering_points(32 * 32, seed=0)
+    grid_points, assignment, grid_size = shufflesnap.snap_to_grid(
+        points,
+        width=32,
+        height=32,
+        cleanup_seconds=0.5,
+    )
+
+    interp = points + 0.8 * (grid_points - points)
+    colors = lab_to_srgb(points)
+
+    fig, ax = plt.subplots(figsize=(8, 8), dpi=150, facecolor="black")
+    ax.set_facecolor("black")
+    ax.scatter(interp[:, 0], interp[:, 1], s=1, c=colors, marker="s", linewidths=0)
+    ax.set_xlim(0.0, 1.0)
+    ax.set_ylim(0.0, 1.0)
+    ax.set_aspect("equal")
+    ax.set_xticks([])
+    ax.set_yticks([])
+    ax.set_title(f"shufflesnap snap_to_grid · grid={grid_size[0]}x{grid_size[1]}", color="white")
+    fig.tight_layout()
+    output = pathlib.Path(__file__).with_name("basic_usage_output.png")
+    fig.savefig(output, facecolor=fig.get_facecolor(), bbox_inches="tight")
+    plt.close(fig)
+
+    print("grid_size:", grid_size)
+    print("assignment shape:", assignment.shape)
+    print("first five assigned indices:", assignment[:5])
+    print("wrote image:", output)
+
+
+if __name__ == "__main__":
+    main()