peclet-morton 0.1.0__tar.gz

peclet_morton-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,155 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  # ---- C++ tests on Linux/macOS, gcc & clang, BMI2 on/off, Debug/Release ----
+  cpp:
+    name: ${{ matrix.os }} / ${{ matrix.cc }} / bmi2=${{ matrix.bmi2 }} / ${{ matrix.build_type }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        bmi2: [ON, OFF]
+        build_type: [Debug, Release]
+        include:
+          - os: ubuntu-latest
+            cc: gcc
+            cxx: g++
+          - os: macos-latest
+            cc: clang
+            cxx: clang++
+        # also run clang on Linux
+        exclude: []
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure
+        run: >
+          cmake -S . -B build
+          -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+          -DMORTON_ENABLE_BMI2=${{ matrix.bmi2 }}
+          -DMORTON_BUILD_BINDINGS=OFF
+      - name: Build
+        run: cmake --build build -j
+      - name: Test
+        run: ctest --test-dir build --output-on-failure
+
+  # ---- clang on Linux (separate so the include: above stays simple) ---------
+  cpp-linux-clang:
+    name: ubuntu / clang / bmi2=${{ matrix.bmi2 }} / ${{ matrix.build_type }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        bmi2: [ON, OFF]
+        build_type: [Debug, Release]
+    env:
+      CC: clang
+      CXX: clang++
+    steps:
+      - uses: actions/checkout@v4
+      - run: >
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+          -DMORTON_ENABLE_BMI2=${{ matrix.bmi2 }} -DMORTON_BUILD_BINDINGS=OFF
+      - run: cmake --build build -j
+      - run: ctest --test-dir build --output-on-failure
+
+  # ---- AVX-512 + runtime-dispatch validation via Intel SDE ------------------
+  # The CI runners have no AVX-512, so we run the test binaries under Intel SDE,
+  # a userspace functional emulator. -skx emulates Skylake-X (AVX-512), so the
+  # AVX-512 batch kernels in morton/simd.hpp actually execute and are checked
+  # bit-for-bit against the scalar reference. The runtime-dispatch build (no
+  # -mbmi2) is then exercised across -snb (no BMI2 -> software), -hsw (BMI2,
+  # no AVX-512 -> PDEP) and -skx (BMI2 + AVX-512).
+  cpp-avx512-sde:
+    name: ubuntu / gcc / AVX-512 + dispatch via Intel SDE
+    runs-on: ubuntu-latest
+    # Intel rotates the SDE download URL/hash periodically; this validates the AVX-512 batch path
+    # under emulation but must not gate the build when the external download moves. Update the url +
+    # sha256 below when it 404s. (The scalar reference path is fully covered by the cpp jobs above.)
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Intel SDE
+        run: |
+          set -euo pipefail
+          url="https://downloadmirror.intel.com/915934/sde-external-10.8.0-2026-03-15-lin.tar.xz"
+          curl -sSL -o sde.tar.xz "$url"
+          echo "50b320cd226acef7a491f5b321fc1be3c3c7984f9e27a456e64894b5b0979dd3  sde.tar.xz" | sha256sum -c -
+          mkdir -p "$HOME/sde" && tar -xJf sde.tar.xz -C "$HOME/sde" --strip-components=1
+          echo "$HOME/sde" >> "$GITHUB_PATH"
+      - name: Build (default, BMI2 on; AVX-512 kernels compiled via target attribute)
+        run: |
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DMORTON_BUILD_BINDINGS=OFF
+          cmake --build build -j
+      - name: Tests under SDE Skylake-X (AVX-512 batch path executes)
+        run: sde64 -skx -- ./build/tests/morton_tests
+      - name: Build runtime-dispatch variant (no -mbmi2)
+        run: |
+          cmake -S . -B build_rt -DCMAKE_BUILD_TYPE=Release \
+            -DMORTON_ENABLE_BMI2=OFF -DMORTON_ENABLE_RUNTIME_DISPATCH=ON \
+            -DMORTON_BUILD_BINDINGS=OFF
+          cmake --build build_rt -j
+      - name: Runtime-dispatch tests across emulated CPUs
+        run: |
+          sde64 -snb -- ./build_rt/tests/morton_tests   # Sandy Bridge: no BMI2/AVX-512 -> software
+          sde64 -hsw -- ./build_rt/tests/morton_tests   # Haswell:     BMI2, no AVX-512 -> PDEP
+          sde64 -skx -- ./build_rt/tests/morton_tests   # Skylake-X:   BMI2 + AVX-512
+
+  # ---- C++ tests on Windows / MSVC ------------------------------------------
+  cpp-msvc:
+    name: windows / msvc / ${{ matrix.build_type }}
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build_type: [Debug, Release]
+    steps:
+      - uses: actions/checkout@v4
+      # MSVC has no __int128 and does not define __BMI2__, so the portable
+      # software path is exercised here; CMake only adds -mbmi2 if supported.
+      - run: cmake -S . -B build -DMORTON_BUILD_BINDINGS=OFF
+      - run: cmake --build build --config ${{ matrix.build_type }}
+      - run: ctest --test-dir build -C ${{ matrix.build_type }} --output-on-failure
+
+  # ---- Python wheel build + tests across versions ---------------------------
+  python:
+    name: python ${{ matrix.python }} (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install package (builds the extension via scikit-build-core)
+        run: pip install .
+      - name: Test (from a clean dir, against the installed package)
+        run: |
+          pip install pytest numpy
+          cd "${{ runner.temp }}"
+          python -m pytest "${{ github.workspace }}/bindings/python/tests" -q
+
+  # ---- Doxygen build (docs must generate without warnings) ------------------
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: sudo apt-get update && sudo apt-get install -y doxygen
+      - run: doxygen docs/Doxyfile
+      - uses: actions/upload-artifact@v4
+        with:
+          name: api-docs
+          path: docs/doxygen/html

peclet_morton-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Documentation
+
+# Build the Doxygen API docs (header-only C++17 in include/morton/) and publish them to GitHub Pages.
+# The CI workflow (ci.yml) also builds the docs as a "must generate" check on every push/PR; THIS
+# workflow additionally DEPLOYS them to Pages on pushes to main. Requires Pages to be enabled for the
+# repository with "Source: GitHub Actions" (Settings -> Pages). Can also be triggered manually.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'include/**'
+      - 'docs/**'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Doxygen + Graphviz
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+      - name: Build documentation
+        run: doxygen docs/Doxyfile
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/doxygen/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

peclet_morton-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,26 @@
+name: Quality
+
+# Lightweight, non-breaking code-quality gates. The Python job hard-fails on *critical* errors only
+# (syntax errors, undefined names, bad string formatting / comparisons — the classic stop-the-build
+# set), so it catches real bugs without drowning research scripts in style nits.
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  python-lint:
+    name: ruff (critical errors)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: Ruff critical-error check
+        run: |
+          ruff check . --select E9,F63,F7,F82 \
+            --exclude ".venv,venv,build,build_*,__pycache__,_deps,extern,legacy,notebooks"

peclet_morton-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Build sdist + binary wheels and publish to PyPI on a version tag.
+# Uses PyPI Trusted Publishing (OIDC) - configure the publisher on PyPI first;
+# no API token secret is needed.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish:
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

peclet_morton-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+build*/
+*.o
+*.so
+*.dylib
+*.dll
+__pycache__/
+*.pyc
+.pytest_cache/
+
+# generated docs
+/docs/doxygen/
+
+# built ctypes lib + py artifacts
+bindings/python/peclet/morton/libmortonarith_c*
+__pycache__/
+*.pyc
+.pytest_cache/

peclet_morton-0.1.0/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+A header-only **C++17** library for Morton (Z-order) codes whose distinguishing feature is **arithmetic directly in Morton space** — incrementing/adding along a single axis, neighbour finding, and Z-order stepping without the usual `decode → modify → re-encode` round trip. The original prototype (an arbitrary-width `BitArray`, a wide-code `Morton`, and an octree) lives in `legacy/`; the new fast core supersedes it for codes that fit in 64 bits.
+
+Read `docs/EVALUATION.md` for the honest assessment of what this contributes versus libmorton/morton-nd, and `docs/ROADMAP.md` for the plan.
+
+## Build / test / benchmark
+
+`DEVELOPMENT.md` is the canonical fresh-machine setup (prerequisites, ISA/platform notes, the full CUDA-via-clang toolkit-assembly recipe); the commands below are the day-to-day subset.
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j
+ctest --test-dir build --output-on-failure       # or ./build/tests/morton_tests
+./build/benchmarks/morton_bench                   # vs libmorton
+./build/benchmarks/morton_bench_batch             # SIMD/batch (cache vs out-of-cache)
+cmake --build build --target docs                 # Doxygen -> docs/doxygen/html
+
+# software (non-BMI2) path — must also pass:
+cmake -S . -B build_nobmi2 -DMORTON_ENABLE_BMI2=OFF && cmake --build build_nobmi2 -j
+
+# runtime-dispatch path (single portable binary, no -mbmi2, uses PDEP/AVX-512
+# when the CPU has them) — what the wheels build:
+cmake -S . -B build_rt -DMORTON_ENABLE_BMI2=OFF -DMORTON_ENABLE_RUNTIME_DISPATCH=ON && cmake --build build_rt -j
+
+# AVX-512 has no hardware on most dev machines / CI; validate it under Intel SDE
+# (userspace emulator, runs on AMD too). -skx => AVX-512 batch path executes:
+sde64 -skx -- ./build/tests/morton_tests
+# runtime-dispatch build across emulated CPUs (BMI2 present/absent):
+sde64 -snb -- ./build_rt/tests/morton_tests   # no BMI2/AVX-512 -> software fallback
+sde64 -hsw -- ./build_rt/tests/morton_tests   # BMI2, no AVX-512 -> PDEP path
+sde64 -skx -- ./build_rt/tests/morton_tests   # BMI2 + AVX-512
+
+# portable Kokkos GPU backend (opt-in; needs a Kokkos prefix on CMAKE_PREFIX_PATH
+# from ../tools/bootstrap_deps.sh <nvidia-cuda|host-openmp|lumi-hip>):
+cmake -S . -B build_kokkos -DMORTON_ENABLE_KOKKOS=ON \
+      -DCMAKE_PREFIX_PATH="$PWD/../extern/install/host-openmp" && cmake --build build_kokkos -j
+ctest --test-dir build_kokkos -R morton_kokkos_tests --output-on-failure
+
+# Python: proper wheel via scikit-build-core (pip install . from repo root)
+pip install .                                     # builds extension, bundles .so
+python -m pytest bindings/python/tests -q
+# or dev loop without installing:
+cmake --build build --target mortonarith_c        # drops .so into bindings/python/peclet/morton/
+PYTHONPATH=bindings/python python3 -m pytest bindings/python/tests -q
+```
+
+Note: the wheel build is driven by the root `pyproject.toml` → `MORTON_WHEEL=ON` in CMakeLists.txt, which builds only the binding and `return()`s early. Don't remove that early return or the wheel will also try to build tests/benchmarks.
+
+A single doctest case can be run with `./build/tests/morton_tests --test-case="<name>"` (doctest filters, e.g. `--subcase=...`, `--list-test-cases`).
+
+## Architecture (new core)
+
+Header dependency order: `morton.hpp` ← {`iterate.hpp`, `simd.hpp` ← `batch.hpp`}. (The octree was split
+out into the sibling `octree/` subproject — see below — and is no longer a core header.)
+
+### `morton/morton.hpp` — `Morton<unsigned Dim, unsigned Bits>`
+
+Interleaves `Dim` coordinates of `Bits` bits each. `Dim*Bits <= 64` uses a built-in `code_type`; **65–128 bits use `__uint128_t`** (guarded by `MORTON_HAS_INT128` / `__SIZEOF_INT128__`), so `Morton3D32` (96-bit) and `Morton2D64` (128-bit) work. Key design points:
+
+- **Encode/decode** go through `deposit`/`extract`. For `code_bits <= 64` they use BMI2 `_pdep_u64`/`_pext_u64` under `#if defined(__BMI2__)`, else a software fallback (`detail::spread_sw`/`compact_sw`). For `code_bits > 64` the software path is always used (PDEP is 64-bit only). Paths are cross-checked in tests; the BMI2=OFF build verifies the fallback emits no pdep/pext.
+- **Runtime dispatch** (`MORTON_ENABLE_RUNTIME_DISPATCH`, opt-in via the CMake option / compile define; gated to `MORTON_X86_RUNTIME_DISPATCH` on x86-64 GCC/Clang when `-mbmi2` is *not* set): a third `deposit`/`extract` branch calls `detail::pdep_u64_hw`/`pext_u64_hw` — `__attribute__((target("bmi2")))` helpers, so PDEP is emitted without a global `-mbmi2` — guarded by the cached `detail::cpu_has_bmi2()` (`__builtin_cpu_supports`). This yields one portable binary that's BMI2-fast at runtime. **Don't enable it by default for the plain BMI2=OFF build** — that build is contractually pdep-free (a test greps for it). It self-disables under `-mbmi2`/CUDA/non-x86. `MORTON_X86` / `cpu_has_bmi2`/`cpu_has_avx2`/`cpu_has_avx512f` live in `detail` and are shared with the SIMD path.
+- **`constexpr`**: `deposit`/`extract`/`encode`/`decode`/arithmetic are `constexpr`. They call the BMI2 intrinsic only when `!detail::is_consteval()` (which uses `__builtin_is_constant_evaluated()`, available at C++17 on GCC/Clang); in constant evaluation the software path runs. Don't "simplify" by removing the `is_consteval()` guard — the intrinsics aren't constexpr.
+- **The headline arithmetic** (`add`/`sub`/`inc`/`dec`/`neighbor`, O(1), branchless) operates on one axis' interleaved bits: to add to axis `d`, fill non-axis bits with 1s (`code | ~M`) so carries ripple across the gaps, add the dilated increment, keep only axis `d` (`& M`), OR back the others. **Wraps mod `2^Bits` per axis.** `add_sat`/`sub_sat`/`try_add`/`try_sub` are the non-wrapping variants.
+- **Neighbour/hierarchy helpers**: `face_neighbors()` (2·Dim, von Neumann), `all_neighbors()` (`3^Dim-1`, Moore), `ancestor(level)`/`child(level,oct)`/`child_index(level)` for octree navigation.
+- `field_mask`/`coord_max` use `sizeof(T)*CHAR_BIT` (not `numeric_limits::digits`, which isn't specialised for `__int128` under strict `-std=c++17`) to avoid `1<<width` UB. Per-axis masks are an `inline static constexpr std::array axis_masks_` (constexpr-usable *and* fast at runtime).
+
+### `morton/iterate.hpp` — region traversal + range search
+
+- `for_each_in_box` — row-major (axis 0 fastest) odometer of O(1) `inc`/`set`; never re-encodes the full tuple. **Profiling note:** for *dense* sweeps, per-cell re-encoding is faster (independent PDEPs pipeline; the arithmetic walk is a serial dependency chain). Its value is convenience + the Z-order variant.
+- `for_each_in_box_zorder` — increasing-code order via `detail::litmax_bigmin` (Tropf-Herzog). Also exposes `bigmin_in_box` / `litmax_in_box` for callers driving their own range scans. Validated exhaustively vs brute force.
+
+### `morton/batch.hpp` — vectorised bulk ops
+
+`batch::add/sub/step/encode2/encode3/decode2/decode3` over arrays. The masked-add loop auto-vectorises (AVX2 `vpaddq`/`vpand`/`vpor`); ~1.7× over scalar when cache-resident, memory-bound parity otherwise (`benchmarks/bench_batch.cpp`). On x86-64 GCC/Clang (`MORTON_X86`) each function **runtime-dispatches** to the explicit AVX-512 kernels in `simd.hpp` when `detail::cpu_has_avx512f()` and the code is 64-bit — transparently, with bit-for-bit identical results — else it falls through to this scalar loop.
+
+### `morton/simd.hpp` — explicit AVX-512 batch kernels
+
+Hand-written AVX-512 "magic-bits" spread/compact (`detail::avx512::{encode2,decode2,encode3,decode3,add64,sub64}`), 8 codes per iteration, with a scalar tail (so `n` need not be a multiple of 8). Each kernel is `__attribute__((target("avx512f")))`, so the TU needs **no** global `-mavx512f` and the rest of the binary stays portable; they only run when `cpu_has_avx512f()` is true. Coverage is the 64-bit-code, 32-bit-coord layouts: `encode/decode` for `(2,32)` and `(3,21)`, and `add/sub` for any 64-bit code (`(2,32)`,`(3,21)`,`(3,16)`); other layouts use the scalar path. **Validate changes here under Intel SDE** (`sde64 -skx`) — there's usually no AVX-512 hardware locally, and the tests compare the SIMD output against the scalar reference exhaustively.
+
+### `morton/wide_uint.hpp` — codes wider than 128 bits
+
+`detail::wide_uint<W>` is a minimal fixed-width (`W` × `u64`, little-endian) unsigned providing exactly the operators `Morton` uses (`+ - & | ^ ~ << >>`, comparisons, conversions to `u64`/`__int128`). `uint_for` selects it automatically when `Dim*Bits` exceeds the builtin width (64, or 128 with `__int128`). Cap is `MORTON_MAX_BITS` (default 256). The Morton class body is unchanged — it's all operators — so 192-bit (`Morton<3,64>`) and 256-bit (`Morton<2,128>`) "just work". Don't tune `wide_uint` for speed unless it becomes a hot path; it's deliberately simple.
+
+### `include/morton/kokkos.hpp` — portable Kokkos GPU backend (shares the core via `MORTON_HD`)
+
+The core's functions are prefixed with `MORTON_HD`. It now resolves to **`KOKKOS_FUNCTION`** when `MORTON_ENABLE_KOKKOS` is set and Kokkos is in the translation unit (so device/host attributes track whichever Kokkos backend — CUDA/HIP/OpenMP/Serial — is active), and falls back to `__host__ __device__` under `__CUDACC__`/`__HIPCC__`, and to nothing for an ordinary host build (so the CPU library is byte-for-byte unchanged). This lets the Kokkos kernels call the **same** `Morton<Dim,Bits>` code — no second implementation. Two gotchas baked into the core (still required under the Kokkos CUDA/HIP device pass):
+- `deposit`/`extract` guard PDEP/PEXT with `#if defined(__BMI2__) && !defined(__CUDA_ARCH__)` — never emit the x86 intrinsic in device code, even when the host is compiled `-mbmi2`. Don't drop the `!defined(__CUDA_ARCH__)`.
+- `axis_mask(d)` computes the mask under `__CUDA_ARCH__` instead of reading the host `static constexpr axis_masks_` array (can't reference a host static from device).
+
+`morton::kokkos` offers `Kokkos::View`-based bulk ops — `encode2/3`, `decode2/3`, per-axis `add`/`sub`/`step` (execution space deduced from the View) — plus `*_host` raw-pointer convenience wrappers (stage to device Views, run, copy back). `tests/kokkos/test_kokkos.cpp` validates device output bit-for-bit against the scalar `Morton<>` reference for all four binding layouts `(2,32) (2,16) (3,21) (3,16)`; `benchmarks/bench_kokkos.cpp` shows device-resident ~51 GMops/s (CUDA) vs PCIe-bound host round-trip.
+
+Build: opt-in with `-DMORTON_ENABLE_KOKKOS=ON` + `find_package(Kokkos CONFIG)` against the suite's bootstrapped prefix (`extern/install/<backend>` from `tools/bootstrap_deps.sh`) on `CMAKE_PREFIX_PATH`, exactly like `flow`/`dem`. Device sources stay plain `.cpp` — Kokkos 5.x routes them through the launch compiler (see `../cmake/SuiteKokkos.cmake`). The plain (non-Kokkos) build never touches Kokkos and is unchanged. **The raw-CUDA backend was retired** (was `cuda/`, `morton::cuda`); the last raw-CUDA tree is at the `pre-cuda-retirement` git tag.
+
+### Octree → sibling `octree/` project
+
+The octree is **no longer part of this library**. It moved to `octree/` (`morton_octree::Octree`, `octree/include/morton_octree/octree.hpp`), a separate project that depends on `morton::morton`. See `octree/PLAN.md`. `legacy/octree.hpp` remains the original prototype/reference.
+
+## Packaging / distribution
+
+- **CMake**: `install` exports a package config (`cmake/morton-config.cmake.in` → `find_package(morton CONFIG)` → `morton::morton`). The `-mbmi2` interface flag is guarded by `$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,AppleClang>` so it's safe to propagate to consumers.
+- **Conan** `conanfile.py`, **vcpkg** `packaging/vcpkg/morton/` (set REF/SHA512 at release).
+- **Python wheels**: `.github/workflows/release.yml` + cibuildwheel build with `MORTON_ENABLE_BMI2=OFF -DMORTON_ENABLE_RUNTIME_DISPATCH=ON` (via `CMAKE_ARGS`) — no global `-mbmi2` (so no SIGILL on old CPUs) but PDEP/PEXT and the AVX-512 batch kernels still kick in at runtime via `target`-attribute helpers + CPUID. One wheel, portable *and* fast. (On MSVC/non-x86 the dispatch self-disables → software path.) Source `pip install .` stays BMI2-on. The C ABI shim (`bindings/morton_c.cpp`) routes 64-bit-code configs through `batch::` so Python gets the dispatched paths; `(2,16)` (32-bit code) keeps the per-element path.
+
+## Conventions / gotchas
+
+- Everything is templated on compile-time `Dim` and `Bits`; that is what makes masks/shifts free. Don't add runtime dimension/bit-width to the hot path.
+- The arithmetic advantage is for **scattered/data-dependent neighbour access**, not dense sweeps — keep this framing in docs and benchmarks. Don't market the library as a faster encoder; it is at parity with libmorton on encode/decode.
+- `third_party/` vendors `doctest.h` and `libmorton/` purely for tests/benchmarks; they are not part of the shipped library.
+- Python bindings are deliberately dependency-free: a C ABI shim (`bindings/morton_c.cpp`, `extern "C"`, bulk array functions) + a `ctypes` wrapper. Supported configs are `(2,32) (2,16) (3,21) (3,16)`; adding one means adding a `DEFINE_2D/3D` instantiation *and* an entry in `_CONFIG` in `__init__.py`.
+
+## Legacy (`legacy/`)
+
+`legacy/octree.hpp` (linear octree over a `std::map<Morton,Cell>`), `legacy/morton.hpp` (CRTP `Morton` over arbitrary-width `BitArrayBase`), `legacy/bitarray.hpp`. These require **C++20** (`<bit>` `std::countr_zero`, fold expressions) and have no build target; the octree visualization notebook is `legacy/octree_visualize.ipynb` (dumps `llx lly urx ury` rows to `temp.dat`, plots with matplotlib). Porting the octree onto the new core is a roadmap item.

peclet_morton-0.1.0/CMakeLists.txt

@@ -0,0 +1,126 @@
+cmake_minimum_required(VERSION 3.16)
+project(morton_arithmetic VERSION 0.1.0 LANGUAGES CXX)
+
+# ---------------------------------------------------------------------------
+# Header-only interface library
+# ---------------------------------------------------------------------------
+add_library(morton INTERFACE)
+add_library(morton::morton ALIAS morton)
+target_include_directories(morton INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>)
+target_compile_features(morton INTERFACE cxx_std_17)
+
+option(MORTON_ENABLE_BMI2 "Use BMI2 PDEP/PEXT for encode/decode" ON)
+include(CheckCXXCompilerFlag)
+check_cxx_compiler_flag("-mbmi2" MORTON_HAS_MBMI2)
+if(MORTON_ENABLE_BMI2 AND MORTON_HAS_MBMI2)
+    # Only GCC/Clang understand -mbmi2; guard so the flag is safe to propagate
+    # to consumers of the installed package (MSVC/other compilers ignore it).
+    target_compile_options(morton INTERFACE
+        $<$<COMPILE_LANG_AND_ID:CXX,GNU,Clang,AppleClang>:-mbmi2>)
+endif()
+
+# Single-binary runtime ISA dispatch (x86-64 GCC/Clang). Builds *without*
+# -mbmi2 but still uses PDEP/PEXT when the running CPU has BMI2 (software path
+# otherwise), via per-function `target` attributes. Intended to be paired with
+# MORTON_ENABLE_BMI2=OFF (it self-disables when -mbmi2 is on). The AVX-512 batch
+# kernels are always runtime-dispatched and need no option. This lets a portable
+# distributable binary (e.g. a wheel) keep the BMI2/AVX-512 fast paths.
+option(MORTON_ENABLE_RUNTIME_DISPATCH
+    "Single-binary runtime BMI2 dispatch (build without -mbmi2)" OFF)
+if(MORTON_ENABLE_RUNTIME_DISPATCH)
+    target_compile_definitions(morton INTERFACE MORTON_ENABLE_RUNTIME_DISPATCH=1)
+endif()
+
+# Portable Kokkos backend (include/morton/kokkos.hpp). Opt-in: the plain build
+# (and the wheels) never touch Kokkos and stay bit-identical. When ON, Kokkos is
+# found via find_package(CONFIG) against the suite's bootstrapped install prefix
+# (extern/install/<backend>, from tools/bootstrap_deps.sh) or a cluster module --
+# the same single mechanism the rest of the suite uses. The backend (CUDA / HIP /
+# OpenMP / Serial) and architecture come from that Kokkos build, not from here.
+option(MORTON_ENABLE_KOKKOS "Build the portable Kokkos backend (and its tests/bench)" OFF)
+if(MORTON_ENABLE_KOKKOS)
+    find_package(Kokkos CONFIG REQUIRED)
+    message(STATUS "morton: Kokkos ${Kokkos_VERSION} (backends: ${Kokkos_DEVICES})")
+    target_compile_definitions(morton INTERFACE MORTON_ENABLE_KOKKOS=1)
+    target_link_libraries(morton INTERFACE Kokkos::kokkos)
+endif()
+
+# Wheel mode (driven by scikit-build-core via the root pyproject.toml): build
+# only the Python extension and install it into the package directory.
+option(MORTON_WHEEL "Build only the Python extension for a wheel" OFF)
+if(MORTON_WHEEL)
+    add_subdirectory(bindings)
+    # LIBRARY = .so/.dylib (Linux/macOS); RUNTIME = .dll (Windows — the actual loadable artifact for ctypes)
+    install(TARGETS mortonarith_c
+            LIBRARY DESTINATION peclet/morton
+            RUNTIME DESTINATION peclet/morton)
+    return()
+endif()
+
+# Only build the extras when this is the top-level project.
+if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+    option(MORTON_BUILD_TESTS "Build the test suite" ON)
+    option(MORTON_BUILD_BENCHMARKS "Build the benchmarks" ON)
+    option(MORTON_BUILD_BINDINGS "Build the C ABI shared library for Python" ON)
+
+    set(CMAKE_CXX_STANDARD 17)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
+    if(NOT CMAKE_BUILD_TYPE)
+        set(CMAKE_BUILD_TYPE Release CACHE STRING "" FORCE)
+    endif()
+
+    if(MORTON_BUILD_TESTS)
+        enable_testing()
+        add_subdirectory(tests)
+        if(MORTON_ENABLE_KOKKOS)
+            add_subdirectory(tests/kokkos)
+        endif()
+    endif()
+    if(MORTON_BUILD_BENCHMARKS)
+        add_subdirectory(benchmarks)
+    endif()
+    if(MORTON_BUILD_BINDINGS)
+        add_subdirectory(bindings)
+    endif()
+
+    # `cmake --build build --target docs` (if Doxygen is installed)
+    find_package(Doxygen)
+    if(DOXYGEN_FOUND)
+        add_custom_target(docs
+            COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_SOURCE_DIR}/docs/Doxyfile
+            WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+            COMMENT "Generating API documentation with Doxygen"
+            VERBATIM)
+    endif()
+endif()
+
+# ---------------------------------------------------------------------------
+# Install + CMake package config so consumers can `find_package(morton)`
+# ---------------------------------------------------------------------------
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+set(MORTON_CMAKE_DIR ${CMAKE_INSTALL_LIBDIR}/cmake/morton)
+
+install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
+install(TARGETS morton EXPORT mortonTargets)
+install(EXPORT mortonTargets
+    FILE morton-targets.cmake
+    NAMESPACE morton::
+    DESTINATION ${MORTON_CMAKE_DIR})
+
+configure_package_config_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/cmake/morton-config.cmake.in
+    ${CMAKE_CURRENT_BINARY_DIR}/morton-config.cmake
+    INSTALL_DESTINATION ${MORTON_CMAKE_DIR})
+write_basic_package_version_file(
+    ${CMAKE_CURRENT_BINARY_DIR}/morton-config-version.cmake
+    VERSION ${PROJECT_VERSION}
+    COMPATIBILITY SameMajorVersion
+    ARCH_INDEPENDENT)
+install(FILES
+    ${CMAKE_CURRENT_BINARY_DIR}/morton-config.cmake
+    ${CMAKE_CURRENT_BINARY_DIR}/morton-config-version.cmake
+    DESTINATION ${MORTON_CMAKE_DIR})