hilbertsfc 0.1.0__tar.gz

hilbertsfc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Remco Leijenaar
+
+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.

hilbertsfc-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: hilbertsfc
+Version: 0.1.0
+Summary: Ultra-fast 2D and 3D Hilbert space-filling curve encode/decode kernels (NumPy + Numba).
+Keywords: hilbert,space-filling-curve,sfc,numba,numpy,indexing
+Author: Remco Leijenaar
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: numba>=0.59.0
+Requires-Dist: numpy>=1.26.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://remcofl.github.io/HilbertSFC/
+Project-URL: Source, https://github.com/remcofl/HilbertSFC
+Project-URL: Documentation, https://remcofl.github.io/HilbertSFC/
+Project-URL: Issues, https://github.com/remcofl/HilbertSFC/issues
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD033 MD041 -->
+---
+<h1 align="center">
+HilbertSFC
+</h1>
+
+<p align="center">
+  <a href="https://github.com/remcofl/HilbertSFC/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-97ca00?style=flat-square" alt="License">
+  </a>
+  <a href="https://remcofl.github.io/HilbertSFC/">
+    <img src="https://img.shields.io/badge/Docs-API%20%26%20Guide-0A7F8E?style=flat-square" alt="Documentation">
+  </a>
+  <a href="https://pypi.org/project/hilbertsfc/">
+    <img src="https://img.shields.io/pypi/v/hilbertsfc?label=PyPI&style=flat-square" alt="PyPI">
+  </a>
+  <a href="https://pypi.org/project/hilbertsfc/">
+    <img src="https://img.shields.io/pypi/pyversions/hilbertsfc?label=Python&style=flat-square" alt="Python versions">
+  </a>
+  <a href="https://github.com/remcofl/HilbertSFC/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/remcofl/HilbertSFC/ci.yml?branch=main&label=CI&style=flat-square" alt="CI">
+  </a>
+</p>
+
+<p align="center">
+    <strong>Ultra-fast 2D &amp; 3D Hilbert space-filling curve encode/decode kernels for Python.</strong>
+</p>
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/remcofl/HilbertSFC/refs/heads/main/docs/img/hilbert2d_grid.png" width="420" align="middle" alt="2D Hilbert curves for nbits 1..5" />
+    <img src="https://raw.githubusercontent.com/remcofl/HilbertSFC/refs/heads/main/docs/img/hilbert3d_grid.webp" width="340" align="middle" hspace="5" alt="3D Hilbert curves animation grid for nbits 1..4" />
+</p>
+
+<p align="center">
+    <sub>2D Hilbert curves (nbits 1..5) and 3D Hilbert curves (nbits 1..4, animated).</sub>
+</p>
+
+---
+
+This project is **performance-first** and **implemented entirely in Python**. The hot kernels are JIT-compiled with Numba and tuned for:
+
+- **Branchless, fully unrolled inner loops**
+- **SIMD via LLVM vector intrinsics**
+- **Small, L1-cache-friendly lookup tables (LUTs)**
+- **Reduced dependency chains for better ILP and MLP**
+- **Optional multi-threading for batch operations**
+
+It provides both convenient Python APIs and *kernel accessors* designed to be embedded into other Numba kernels.
+
+## Performance
+
+**HilbertSFC** is orders of magnitude faster than existing Python implementations. It also outperforms the **Fast Hilbert** implementation in Rust by a factor of ~7x. In fact, **HilbertSFC** takes only ~8 CPU cycles per point for 2D encode/decode of 32-bit coordinates.
+
+#### 2D Points - Random, `nbits=32`, `n=5,000,000`
+
+| Implementation | ns/pt (enc) | ns/pt (dec) | Mpts/s (enc) | Mpts/s (dec) |
+| --- | ---: | ---: | ---: | ---: |
+| 🔥**hilbertsfc (multi-threaded)** | 0.53 | 0.57 | 1883.52 | 1742.08 |
+| 🔥**hilbertsfc (Python)** | 1.84 | 1.88 | 543.60 | 532.77 |
+| [fast_hilbert (Rust)](https://crates.io/crates/fast_hilbert) | 13.71 | 13.47 | 72.92 | 74.23 |
+| [hilbert_2d (Rust)](https://crates.io/crates/hilbert_2d) | 121.23 | 101.34 | 8.25 | 9.87 |
+| [hilbert-bytes (Python)](https://pypi.org/project/hilbert-bytes/) | 2997.51 | 2642.86 | 0.334 | 0.378 |
+| [numpy-hilbert-curve (Python)](https://pypi.org/project/numpy-hilbert-curve/) | 7606.88 | 5075.58 | 0.131 | 0.197 |
+| [hilbertcurve (Python)](https://pypi.org/project/hilbertcurve/) | 14355.76 | 10411.20 | 0.0697 | 0.0961 |
+
+> **System info:** Intel Core Ultra 7 258v, Ubuntu 24.04.4, Python 3.12.12, Numba 0.63.1
+
+Additional benchmarks and details are available in the [benchmark.md](https://github.com/remcofl/HilbertSFC/blob/main/benchmark.md).
+
+For a deep dive into how the HilbertSFC kernels are derived and why the implementation maps well to modern CPUs (FSM/LUT formulation, dependency chains, ILP/MLP, unrolling, constant folding, vectorization, gathers), see the [performance deep dive notebook](https://github.com/remcofl/HilbertSFC/blob/main/notebooks/hilbertsfc_performance_deep_dive.ipynb).
+
+## Quickstart
+
+### Installation
+
+With pip:
+
+```bash
+pip install hilbertsfc
+```
+
+Or with uv:
+
+```bash
+uv add hilbertsfc
+```
+
+### Usage
+
+Hilbert curves map multi-dimensional integer coordinates onto a single scalar index while preserving spatial locality. `hilbertsfc` provides an encode and decode API for 2D and 3D coordinates that support both scalar values and vectorized array inputs.
+
+The `nbits` parameter specifies the number of bits per coordinate, defining the grid domain as `[0, 2**nbits)`. If omitted, it's inferred from the input array dtype (for arrays) or defaults to the maximum (32 for 2D, 21 for 3D).
+
+#### Scalar 2D
+
+Encode a single `(x, y)` coordinate into a Hilbert index, and decode it back:
+
+```python
+from hilbertsfc import hilbert_decode_2d, hilbert_encode_2d
+
+index = hilbert_encode_2d(17, 23, nbits=10)  # index = 534
+x, y = hilbert_decode_2d(index, nbits=10)    # x, y = (17, 23)
+```
+
+#### Batch 2D
+
+The same functions operate elementwise on NumPy arrays, preserving shape and avoiding Python loops:
+
+```python
+import numpy as np
+from hilbertsfc import hilbert_decode_2d, hilbert_encode_2d
+
+xs = np.arange(1024, dtype=np.uint16)
+ys = xs[::-1]
+
+indices = hilbert_encode_2d(xs, ys, nbits=10)    # shape (1024,), dtype uint32
+xs2, ys2 = hilbert_decode_2d(indices, nbits=10)  # xs2 = xs, ys2 = ys
+```
+
+This is the preferred use for high-throughput workloads. It can be further accelerated with `parallel=True`.
+
+#### Batch 3D
+
+3D works identically, mapping `(x, y, z)` coordinates to a single Hilbert index:
+
+```python
+import numpy as np
+from hilbertsfc import hilbert_decode_3d, hilbert_encode_3d
+
+nbits = 10
+n = 10_000
+rng = np.random.default_rng(0)
+
+xs = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+ys = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+zs = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+
+indices = hilbert_encode_3d(xs, ys, zs, nbits=nbits)      # shape (10000,), dtype uint32
+xs2, ys2, zs2 = hilbert_decode_3d(indices, nbits=nbits)   # xs2 = xs, ys2 = ys, zs2 = zs
+```
+
+This is can be useful for applications like 3D spatial indexing, volumetric data processing, compression, and more.
+
+#### Embedding kernels in your own Numba code
+
+While the main API is designed for ease of use, the package also provides *kernel accessors* that expose the scalar encode/decode kernels. This allows you to embed the Hilbert curve logic directly into your own Numba kernels, enabling further optimizations like loop fusion and reduced Python call overhead.
+
+Example embedding the 2D encode kernel:
+
+```python
+import numpy as np
+import numba as nb
+
+from hilbertsfc import get_hilbert_encode_2d_kernel
+
+encode_2d_10 = get_hilbert_encode_2d_kernel(nbits=10)
+
+@nb.njit
+def encode_many(xs: np.ndarray, ys: np.ndarray) -> np.ndarray:
+    out = np.empty(xs.shape, dtype=np.uint32)
+    for i in range(xs.size):
+        out[i] = encode_2d_10(xs[i], ys[i])
+    return out
+```
+
+The same pattern works for decode and for 3D kernels.
+
+### Demo Notebook
+
+For more examples, see the [demo notebook](https://github.com/remcofl/HilbertSFC/blob/main/notebooks/hilbertsfc_demo.ipynb) which includes visualizations of the curves and embedding the kernels into custom Numba code.
+
+## API notes
+
+- `nbits` specifies the number of bits per coordinate. Coordinates must be in `[0, 2**nbits)`. A tighter `nbits` improves performance and reduces output dtypes. Excess bits are ignored.
+- Hilbert indices obtained with a certain `nbits` are compatible with those from another `nbits`, given that the coordinates are within the valid range. This is because the kernels resolve the starting state parity to ensure compatibility.
+- The batched API accepts arbitrary shapes and preserves the input shape. The requirement is that inputs/outputs support a *zero-copy* 1D view. Most strided views are supported but they can reduce performance since the kernels are close to memory-bandwidth bound.
+- You can pass `out=...` buffers for batch encode, and `out_xs/out_ys/out_zs` for batch decode. This can for example be useful to write into memory-mapped arrays or to reuse buffers across multiple calls.
+- `parallel=True` dispatches the parallel version of the kernel (when available). The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.
+
+## Documentation
+
+[Documentation](https://remcofl.github.io/HilbertSFC/) is hosted online. It includes a quick start guide, and API reference.
+
+To serve the docs locally:
+
+```bash
+uv run --no-dev --group docs mkdocs serve
+```
+
+Build a static site into `site/`:
+
+```bash
+uv run --no-dev --group docs mkdocs build
+```
+
+## Development
+
+The repo uses `uv` for environment management. CI and local development workflows (lint, tests, type checking, docs) are automated with `nox`.
+
+Sync a local environment with dev dependencies:
+
+```bash
+uv sync
+```
+
+Run the full `nox` suite:
+
+```bash
+uvx nox
+```
+
+More details are in [CONTRIBUTING.md](https://github.com/remcofl/HilbertSFC/blob/main/CONTRIBUTING.md).
+
+## Cache control
+
+If you want to clear cached kernels and lookup tables (e.g., for benchmarking or testing), you can use the `clear_all_caches()` function:
+
+```python
+from hilbertsfc import clear_all_caches
+
+clear_all_caches()
+```

hilbertsfc-0.1.0/README.md

@@ -0,0 +1,222 @@
+<!-- markdownlint-disable MD033 MD041 -->
+---
+<h1 align="center">
+HilbertSFC
+</h1>
+
+<p align="center">
+  <a href="https://github.com/remcofl/HilbertSFC/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-97ca00?style=flat-square" alt="License">
+  </a>
+  <a href="https://remcofl.github.io/HilbertSFC/">
+    <img src="https://img.shields.io/badge/Docs-API%20%26%20Guide-0A7F8E?style=flat-square" alt="Documentation">
+  </a>
+  <a href="https://pypi.org/project/hilbertsfc/">
+    <img src="https://img.shields.io/pypi/v/hilbertsfc?label=PyPI&style=flat-square" alt="PyPI">
+  </a>
+  <a href="https://pypi.org/project/hilbertsfc/">
+    <img src="https://img.shields.io/pypi/pyversions/hilbertsfc?label=Python&style=flat-square" alt="Python versions">
+  </a>
+  <a href="https://github.com/remcofl/HilbertSFC/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/remcofl/HilbertSFC/ci.yml?branch=main&label=CI&style=flat-square" alt="CI">
+  </a>
+</p>
+
+<p align="center">
+    <strong>Ultra-fast 2D &amp; 3D Hilbert space-filling curve encode/decode kernels for Python.</strong>
+</p>
+
+<p align="center">
+    <img src="https://raw.githubusercontent.com/remcofl/HilbertSFC/refs/heads/main/docs/img/hilbert2d_grid.png" width="420" align="middle" alt="2D Hilbert curves for nbits 1..5" />
+    <img src="https://raw.githubusercontent.com/remcofl/HilbertSFC/refs/heads/main/docs/img/hilbert3d_grid.webp" width="340" align="middle" hspace="5" alt="3D Hilbert curves animation grid for nbits 1..4" />
+</p>
+
+<p align="center">
+    <sub>2D Hilbert curves (nbits 1..5) and 3D Hilbert curves (nbits 1..4, animated).</sub>
+</p>
+
+---
+
+This project is **performance-first** and **implemented entirely in Python**. The hot kernels are JIT-compiled with Numba and tuned for:
+
+- **Branchless, fully unrolled inner loops**
+- **SIMD via LLVM vector intrinsics**
+- **Small, L1-cache-friendly lookup tables (LUTs)**
+- **Reduced dependency chains for better ILP and MLP**
+- **Optional multi-threading for batch operations**
+
+It provides both convenient Python APIs and *kernel accessors* designed to be embedded into other Numba kernels.
+
+## Performance
+
+**HilbertSFC** is orders of magnitude faster than existing Python implementations. It also outperforms the **Fast Hilbert** implementation in Rust by a factor of ~7x. In fact, **HilbertSFC** takes only ~8 CPU cycles per point for 2D encode/decode of 32-bit coordinates.
+
+#### 2D Points - Random, `nbits=32`, `n=5,000,000`
+
+| Implementation | ns/pt (enc) | ns/pt (dec) | Mpts/s (enc) | Mpts/s (dec) |
+| --- | ---: | ---: | ---: | ---: |
+| 🔥**hilbertsfc (multi-threaded)** | 0.53 | 0.57 | 1883.52 | 1742.08 |
+| 🔥**hilbertsfc (Python)** | 1.84 | 1.88 | 543.60 | 532.77 |
+| [fast_hilbert (Rust)](https://crates.io/crates/fast_hilbert) | 13.71 | 13.47 | 72.92 | 74.23 |
+| [hilbert_2d (Rust)](https://crates.io/crates/hilbert_2d) | 121.23 | 101.34 | 8.25 | 9.87 |
+| [hilbert-bytes (Python)](https://pypi.org/project/hilbert-bytes/) | 2997.51 | 2642.86 | 0.334 | 0.378 |
+| [numpy-hilbert-curve (Python)](https://pypi.org/project/numpy-hilbert-curve/) | 7606.88 | 5075.58 | 0.131 | 0.197 |
+| [hilbertcurve (Python)](https://pypi.org/project/hilbertcurve/) | 14355.76 | 10411.20 | 0.0697 | 0.0961 |
+
+> **System info:** Intel Core Ultra 7 258v, Ubuntu 24.04.4, Python 3.12.12, Numba 0.63.1
+
+Additional benchmarks and details are available in the [benchmark.md](https://github.com/remcofl/HilbertSFC/blob/main/benchmark.md).
+
+For a deep dive into how the HilbertSFC kernels are derived and why the implementation maps well to modern CPUs (FSM/LUT formulation, dependency chains, ILP/MLP, unrolling, constant folding, vectorization, gathers), see the [performance deep dive notebook](https://github.com/remcofl/HilbertSFC/blob/main/notebooks/hilbertsfc_performance_deep_dive.ipynb).
+
+## Quickstart
+
+### Installation
+
+With pip:
+
+```bash
+pip install hilbertsfc
+```
+
+Or with uv:
+
+```bash
+uv add hilbertsfc
+```
+
+### Usage
+
+Hilbert curves map multi-dimensional integer coordinates onto a single scalar index while preserving spatial locality. `hilbertsfc` provides an encode and decode API for 2D and 3D coordinates that support both scalar values and vectorized array inputs.
+
+The `nbits` parameter specifies the number of bits per coordinate, defining the grid domain as `[0, 2**nbits)`. If omitted, it's inferred from the input array dtype (for arrays) or defaults to the maximum (32 for 2D, 21 for 3D).
+
+#### Scalar 2D
+
+Encode a single `(x, y)` coordinate into a Hilbert index, and decode it back:
+
+```python
+from hilbertsfc import hilbert_decode_2d, hilbert_encode_2d
+
+index = hilbert_encode_2d(17, 23, nbits=10)  # index = 534
+x, y = hilbert_decode_2d(index, nbits=10)    # x, y = (17, 23)
+```
+
+#### Batch 2D
+
+The same functions operate elementwise on NumPy arrays, preserving shape and avoiding Python loops:
+
+```python
+import numpy as np
+from hilbertsfc import hilbert_decode_2d, hilbert_encode_2d
+
+xs = np.arange(1024, dtype=np.uint16)
+ys = xs[::-1]
+
+indices = hilbert_encode_2d(xs, ys, nbits=10)    # shape (1024,), dtype uint32
+xs2, ys2 = hilbert_decode_2d(indices, nbits=10)  # xs2 = xs, ys2 = ys
+```
+
+This is the preferred use for high-throughput workloads. It can be further accelerated with `parallel=True`.
+
+#### Batch 3D
+
+3D works identically, mapping `(x, y, z)` coordinates to a single Hilbert index:
+
+```python
+import numpy as np
+from hilbertsfc import hilbert_decode_3d, hilbert_encode_3d
+
+nbits = 10
+n = 10_000
+rng = np.random.default_rng(0)
+
+xs = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+ys = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+zs = rng.integers(0, 2**nbits, size=n, dtype=np.uint32)
+
+indices = hilbert_encode_3d(xs, ys, zs, nbits=nbits)      # shape (10000,), dtype uint32
+xs2, ys2, zs2 = hilbert_decode_3d(indices, nbits=nbits)   # xs2 = xs, ys2 = ys, zs2 = zs
+```
+
+This is can be useful for applications like 3D spatial indexing, volumetric data processing, compression, and more.
+
+#### Embedding kernels in your own Numba code
+
+While the main API is designed for ease of use, the package also provides *kernel accessors* that expose the scalar encode/decode kernels. This allows you to embed the Hilbert curve logic directly into your own Numba kernels, enabling further optimizations like loop fusion and reduced Python call overhead.
+
+Example embedding the 2D encode kernel:
+
+```python
+import numpy as np
+import numba as nb
+
+from hilbertsfc import get_hilbert_encode_2d_kernel
+
+encode_2d_10 = get_hilbert_encode_2d_kernel(nbits=10)
+
+@nb.njit
+def encode_many(xs: np.ndarray, ys: np.ndarray) -> np.ndarray:
+    out = np.empty(xs.shape, dtype=np.uint32)
+    for i in range(xs.size):
+        out[i] = encode_2d_10(xs[i], ys[i])
+    return out
+```
+
+The same pattern works for decode and for 3D kernels.
+
+### Demo Notebook
+
+For more examples, see the [demo notebook](https://github.com/remcofl/HilbertSFC/blob/main/notebooks/hilbertsfc_demo.ipynb) which includes visualizations of the curves and embedding the kernels into custom Numba code.
+
+## API notes
+
+- `nbits` specifies the number of bits per coordinate. Coordinates must be in `[0, 2**nbits)`. A tighter `nbits` improves performance and reduces output dtypes. Excess bits are ignored.
+- Hilbert indices obtained with a certain `nbits` are compatible with those from another `nbits`, given that the coordinates are within the valid range. This is because the kernels resolve the starting state parity to ensure compatibility.
+- The batched API accepts arbitrary shapes and preserves the input shape. The requirement is that inputs/outputs support a *zero-copy* 1D view. Most strided views are supported but they can reduce performance since the kernels are close to memory-bandwidth bound.
+- You can pass `out=...` buffers for batch encode, and `out_xs/out_ys/out_zs` for batch decode. This can for example be useful to write into memory-mapped arrays or to reuse buffers across multiple calls.
+- `parallel=True` dispatches the parallel version of the kernel (when available). The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.
+
+## Documentation
+
+[Documentation](https://remcofl.github.io/HilbertSFC/) is hosted online. It includes a quick start guide, and API reference.
+
+To serve the docs locally:
+
+```bash
+uv run --no-dev --group docs mkdocs serve
+```
+
+Build a static site into `site/`:
+
+```bash
+uv run --no-dev --group docs mkdocs build
+```
+
+## Development
+
+The repo uses `uv` for environment management. CI and local development workflows (lint, tests, type checking, docs) are automated with `nox`.
+
+Sync a local environment with dev dependencies:
+
+```bash
+uv sync
+```
+
+Run the full `nox` suite:
+
+```bash
+uvx nox
+```
+
+More details are in [CONTRIBUTING.md](https://github.com/remcofl/HilbertSFC/blob/main/CONTRIBUTING.md).
+
+## Cache control
+
+If you want to clear cached kernels and lookup tables (e.g., for benchmarking or testing), you can use the `clear_all_caches()` function:
+
+```python
+from hilbertsfc import clear_all_caches
+
+clear_all_caches()
+```

hilbertsfc-0.1.0/pyproject.toml

@@ -0,0 +1,129 @@
+[project]
+name = "hilbertsfc"
+version = "0.1.0"
+description = "Ultra-fast 2D and 3D Hilbert space-filling curve encode/decode kernels (NumPy + Numba)."
+readme = "README.md"
+authors = [{ name = "Remco Leijenaar" }]
+requires-python = ">=3.12"
+dependencies = ["numba>=0.59.0", "numpy>=1.26.0"]
+license = "MIT"
+license-files = ["LICENSE"]
+
+keywords = [
+    "hilbert",
+    "space-filling-curve",
+    "sfc",
+    "numba",
+    "numpy",
+    "indexing",
+]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://remcofl.github.io/HilbertSFC/"
+Source = "https://github.com/remcofl/HilbertSFC"
+Documentation = "https://remcofl.github.io/HilbertSFC/"
+Issues = "https://github.com/remcofl/HilbertSFC/issues"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+bench = [
+    "hilbert-bytes>=0.6.0",
+    "hilbertcurve>=2.0.5",
+    "numpy-hilbert-curve>=1.0.1",
+]
+dev = [
+    { include-group = "test" },
+    { include-group = "typecheck" },
+    "prek>=0.3.1",
+    "ruff>=0.15.0",
+    "nox>=2025.11.12",
+]
+docs = [
+    "mkdocs>=1.6.1,<2",
+    "mkdocs-material>=9.6.0",
+    "mkdocstrings[python]>=0.30.0",
+    "pymdown-extensions>=10.14.0",
+    "ruff>=0.15.0",
+]
+notebooks = [
+    "ipykernel>=7.2.0",
+    "matplotlib>=3.10.8",
+    "rich>=14.3.2",
+    "numpy>=2.3.5",
+    "pandas>=3.0.1",
+]
+scripts = [
+    "matplotlib>=3.10.8",
+    "numpy>=2.3.5",
+    "pillow>=12.1.0",
+    "rich>=14.3.2",
+]
+test = ["pytest>=9.0.2"]
+typecheck = ["pyright>=1.1.408", "pyrefly>=0.51.0", "ty>=0.0.15"]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "N", "NPY", "UP"]
+ignore = []
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ty]
+src.include = ["src", "tests", "scripts", "notebooks"]
+
+[tool.pyright]
+include = ["src", "tests", "scripts", "notebooks"]
+pythonVersion = "3.12"
+typeCheckingMode = "basic"
+
+[tool.pyrefly]
+project-includes = ["src", "tests", "scripts", "notebooks"]
+python-version = "3.12.0"
+infer-with-first-use = false
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+markers = [
+    "slow: exhaustive tests that may take longer (deselect with '-m \"not slow\"')",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

hilbertsfc-0.1.0/src/hilbertsfc/__init__.py

@@ -0,0 +1,39 @@
+"""hilbertsfc package.
+
+This package is intended to host Hilbert space-filling curve kernels and their
+lookup tables as lazily-loaded package resources.
+
+Public API lives in:
+- ``hilbertsfc.hilbert2d``
+- ``hilbertsfc.hilbert3d``
+"""
+
+from __future__ import annotations
+
+from ._cache import clear_all_caches, clear_kernel_caches, clear_lut_caches
+from .hilbert2d import (
+    get_hilbert_decode_2d_kernel,
+    get_hilbert_encode_2d_kernel,
+    hilbert_decode_2d,
+    hilbert_encode_2d,
+)
+from .hilbert3d import (
+    get_hilbert_decode_3d_kernel,
+    get_hilbert_encode_3d_kernel,
+    hilbert_decode_3d,
+    hilbert_encode_3d,
+)
+
+__all__ = [
+    "clear_all_caches",
+    "clear_kernel_caches",
+    "clear_lut_caches",
+    "get_hilbert_decode_2d_kernel",
+    "get_hilbert_encode_2d_kernel",
+    "get_hilbert_decode_3d_kernel",
+    "get_hilbert_encode_3d_kernel",
+    "hilbert_decode_2d",
+    "hilbert_decode_3d",
+    "hilbert_encode_2d",
+    "hilbert_encode_3d",
+]