megalap 0.1.1__tar.gz

megalap-0.1.1/.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
+
+      - 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

megalap-0.1.1/.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
+
+      - 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/megalap
+    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

megalap-0.1.1/.gitignore

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

megalap-0.1.1/CMakeLists.txt

@@ -0,0 +1,10 @@
+cmake_minimum_required(VERSION 3.18)
+project(megalap 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 megalap)

megalap-0.1.1/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.

megalap-0.1.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: megalap
+Version: 0.1.1
+Summary: Native dense LAP and windowed cleanup kernels for point-to-grid assignment.
+Keywords: assignment,lap,point-cloud,grid,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/megalap
+Project-URL: Repository, https://github.com/kylemcdonald/megalap
+Project-URL: Issues, https://github.com/kylemcdonald/megalap/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"
+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
+
+# megalap
+
+`megalap` is a Python package with a native C++ core and `nanobind` bindings for point-to-grid assignment.
+
+The public API has three functions:
+
+1. `linear_sum_assignment(cost_matrix)`
+2. `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, ...)`
+3. `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, ...)`
+
+## Install
+
+```bash
+python -m pip install megalap
+```
+
+To run the matplotlib example from the source tree:
+
+```bash
+python -m pip install -e '.[examples]'
+python examples/basic_usage.py
+```
+
+## API
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square linear assignment problem 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`
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, ...)`
+
+Run the overlapping-window cleanup kernel using native C++ threads.
+
+Key options:
+
+- `window_size=6`
+- `num_threads=None` to use `std::thread::hardware_concurrency()`
+- `num_threads=1` to force serial execution
+- `fixed_suffix_count` to keep a suffix of target cells fixed
+
+Returns a dict with:
+
+- `assignment`
+- `passes_completed`
+- `elapsed_s`
+- `final_cost`
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, ...)`
+
+High-level wrapper for snapping a 2D point cloud onto a destination grid.
+
+Behavior:
+
+- chooses a destination grid automatically when `width` and `height` are omitted
+- prefers exact rectangular sizes with aspect ratio in `[1:1, 2:1]`
+- falls back to a near-square enclosing grid in that same band when exact factors do not exist
+- pads with edge ghost points when the chosen grid has more cells than real points
+- runs the native LAP solver and `30s` of cleanup by default
+- set `cleanup_seconds=0.0` to disable cleanup
+
+Returns:
+
+- `grid_points`: `(n, 2)` float64 NumPy array of assigned destination points in original point order
+- `assignment`: `(n,)` int64 NumPy array of destination-grid indices in original point order
+- `(width, height)`: destination-grid size tuple
+
+## More
+
+- Source repository: https://github.com/kylemcdonald/megalap
+- Issue tracker: https://github.com/kylemcdonald/megalap/issues
+- Example scripts: https://github.com/kylemcdonald/megalap/tree/main/examples

megalap-0.1.1/PUBLISHING.md

@@ -0,0 +1,60 @@
+# Publishing `megalap`
+
+## Local validation
+
+From the repository root:
+
+```bash
+python -m pip install -U build twine pytest
+python -m build
+python -m twine check dist/*
+python -m pip install --force-reinstall dist/*.whl
+python -m pytest -q
+```
+
+## Continuous integration
+
+The repository includes:
+
+- [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for editable-install tests and distribution checks
+- [`.github/workflows/release.yml`](.github/workflows/release.yml) for tagged multi-platform releases
+
+`release.yml` builds:
+
+- one source distribution on Linux
+- wheels on Linux, macOS Intel, macOS Apple Silicon, and Windows
+
+## One-time PyPI setup
+
+Before `release.yml` can publish to PyPI:
+
+1. Create the `megalap` project on PyPI.
+2. Configure PyPI trusted publishing for GitHub repository `kylemcdonald/megalap`.
+3. Set the trusted publisher workflow file to `.github/workflows/release.yml`.
+4. Add a GitHub `pypi` environment if you want environment protection on releases.
+
+## Release steps
+
+1. Update `version` in `pyproject.toml`.
+2. Commit and push to `main`.
+3. Wait for `.github/workflows/ci.yml` to pass.
+4. Create and push a tag like `v0.1.0`.
+5. Confirm the release workflow uploads the sdist and wheels, then publishes them to PyPI.
+
+## Optional dry run
+
+If you want to verify the package manually before a real release:
+
+```bash
+python -m pip install -U pytest
+python -m build
+python -m pip install --force-reinstall dist/*.tar.gz
+python -m pytest -q
+python -m pip install --force-reinstall dist/*.whl
+python -m pytest -q
+```
+
+## Notes
+
+- The repository README keeps the hero image. PyPI uses `README_PYPI.md` as the package long description so the package page does not depend on local image assets.
+- The release workflow uses `cibuildwheel` so PyPI receives Linux, macOS, and Windows wheels instead of a single local platform wheel.

megalap-0.1.1/README.md

@@ -0,0 +1,157 @@
+# megalap
+
+`megalap` is a Python package with a native C++ core and `nanobind` bindings for point-to-grid assignment work.
+
+The public API is intentionally small:
+
+1. `linear_sum_assignment(cost_matrix)`
+2. `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, ...)`
+3. `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, ...)`
+
+## Showcase
+
+`512x512` meandering point cloud, recursive `8x8` seed, `30s` of native `6x6` cleanup, 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`.
+
+![megalap triptych showcase](assets/showcase_triptych_512.png)
+
+## Install
+
+From PyPI:
+
+```bash
+python -m pip install megalap
+```
+
+From a local checkout:
+
+```bash
+python -m pip install -e .
+```
+
+## API
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square LAP with the native C++ Jonker-Volgenant implementation.
+
+Inputs:
+
+- `cost_matrix`: `float64` array-like of shape `(n, n)`
+
+Returns:
+
+- `row_ind`: `int64` NumPy array of shape `(n,)`
+- `col_ind`: `int64` NumPy array of shape `(n,)`
+- `total_cost`: Python `float`
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, window_size=6, margin=0.03, num_threads=None, fixed_suffix_count=0)`
+
+Run the native overlapping-window cleanup kernel.
+
+Behavior:
+
+- uses the C++ backend
+- solves each phase as multiple independent small JV problems
+- runs same-phase window solves in parallel with native C++ threads
+- `num_threads=None` uses `std::thread::hardware_concurrency()`
+- `num_threads=1` forces serial cleanup
+- `fixed_suffix_count` can keep a suffix of target cells locked, which is useful for padded ghost points
+
+Inputs:
+
+- `points`: `float64` array-like of shape `(n, 2)`
+- `initial_assignment`: `int64` array-like of shape `(n,)`
+- `rows`, `cols`: target grid dimensions
+- `budget_seconds`: cleanup wall-clock budget
+- `window_size`: default `6`
+- `margin`: normalized grid margin
+- `num_threads`: optional thread count override
+- `fixed_suffix_count`: number of trailing target cells to keep fixed during cleanup
+
+Returns a Python `dict` with:
+
+- `assignment`: final `int64` NumPy array
+- `passes_completed`
+- `elapsed_s`
+- `final_cost`
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, window_size=6, margin=0.03, num_threads=None)`
+
+High-level point-cloud wrapper.
+
+Behavior:
+
+- chooses a destination grid automatically when `width` and `height` are omitted
+- prefers exact rectangular sizes with aspect ratio in `[1:1, 2:1]`
+- if no exact factorization exists in that range, chooses a near-square enclosing grid in that same band
+- pads with edge ghost points when the grid has more cells than real points
+- runs the native JV LAP
+- runs `30s` of cleanup by default
+- set `cleanup_seconds=0.0` to disable cleanup
+- passes `num_threads` through to the native cleanup kernel
+
+Returns three values:
+
+- `grid_points`: `(n, 2)` float64 NumPy array of assigned destination-grid positions, in the original source-point order
+- `assignment`: `(n,)` int64 NumPy array of destination-grid indices for the original source points
+- `(width, height)`: destination-grid size tuple
+
+## Example
+
+See [examples/basic_usage.py](examples/basic_usage.py).
+
+Run it after installation:
+
+```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
+```
+
+That renderer uses NumPy directly and writes the PNG without matplotlib.
+
+For release instructions, see [PUBLISHING.md](PUBLISHING.md).
+
+## Cleanup Threading Benchmark
+
+There is a small reproducible threading benchmark at [examples/benchmark_threads.py](examples/benchmark_threads.py).
+
+Run it with:
+
+```bash
+python examples/benchmark_threads.py
+```
+
+On this machine (`16` logical CPUs), using a `256x256` meandering point cloud, identity seed assignment, `window_size=6`, and a `1.0s` cleanup budget, the median of `3` runs was:
+
+| mode | median elapsed | median passes | median passes/s |
+|---|---:|---:|---:|
+| `num_threads=1` | `1.028 s` | `3` | `2.92` |
+| `num_threads=None` | `1.026 s` | `31` | `30.20` |
+
+So the default threaded path improved cleanup throughput by about `10.3x` on that benchmark.
+
+## Notes
+
+- `linear_sum_assignment()` currently expects a square cost matrix.
+- `snap_to_grid()` handles non-rectangular point counts by padding with visible ghost points along the trailing edge of the chosen destination grid.
+- The cleanup kernel uses overlapping windows of at most `6x6`, so the native small-JV kernel is specialized for up to `36` points per window.
+- The native cleanup kernel uses standard C++ threads and does not depend on OpenMP.
+- GitHub Actions builds release artifacts for Linux, macOS, and Windows wheels, plus an sdist.

megalap-0.1.1/README_PYPI.md

@@ -0,0 +1,77 @@
+# megalap
+
+`megalap` is a Python package with a native C++ core and `nanobind` bindings for point-to-grid assignment.
+
+The public API has three functions:
+
+1. `linear_sum_assignment(cost_matrix)`
+2. `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, ...)`
+3. `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, ...)`
+
+## Install
+
+```bash
+python -m pip install megalap
+```
+
+To run the matplotlib example from the source tree:
+
+```bash
+python -m pip install -e '.[examples]'
+python examples/basic_usage.py
+```
+
+## API
+
+### `linear_sum_assignment(cost_matrix)`
+
+Solve a dense square linear assignment problem 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`
+
+### `window_cleanup(points, initial_assignment, rows, cols, budget_seconds, ...)`
+
+Run the overlapping-window cleanup kernel using native C++ threads.
+
+Key options:
+
+- `window_size=6`
+- `num_threads=None` to use `std::thread::hardware_concurrency()`
+- `num_threads=1` to force serial execution
+- `fixed_suffix_count` to keep a suffix of target cells fixed
+
+Returns a dict with:
+
+- `assignment`
+- `passes_completed`
+- `elapsed_s`
+- `final_cost`
+
+### `snap_to_grid(points, width=None, height=None, cleanup_seconds=30.0, ...)`
+
+High-level wrapper for snapping a 2D point cloud onto a destination grid.
+
+Behavior:
+
+- chooses a destination grid automatically when `width` and `height` are omitted
+- prefers exact rectangular sizes with aspect ratio in `[1:1, 2:1]`
+- falls back to a near-square enclosing grid in that same band when exact factors do not exist
+- pads with edge ghost points when the chosen grid has more cells than real points
+- runs the native LAP solver and `30s` of cleanup by default
+- set `cleanup_seconds=0.0` to disable cleanup
+
+Returns:
+
+- `grid_points`: `(n, 2)` float64 NumPy array of assigned destination points in original point order
+- `assignment`: `(n,)` int64 NumPy array of destination-grid indices in original point order
+- `(width, height)`: destination-grid size tuple
+
+## More
+
+- Source repository: https://github.com/kylemcdonald/megalap
+- Issue tracker: https://github.com/kylemcdonald/megalap/issues
+- Example scripts: https://github.com/kylemcdonald/megalap/tree/main/examples

megalap-0.1.1/examples/basic_usage.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import pathlib
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import megalap
+
+
+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 = megalap.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"megalap 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()