Package API¶

This page documents the top-level hilbertsfc package exports (including cache helpers).

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

clear_all_caches ¶

clear_all_caches() -> None

Clear LUT caches and kernel builder caches.

clear_kernel_caches ¶

clear_kernel_caches() -> None

Clear all registered kernel builder caches.

clear_lut_caches ¶

clear_lut_caches() -> None

Clear all registered LUT caches.

get_hilbert_decode_2d_kernel ¶

get_hilbert_decode_2d_kernel(
    nbits: int,
) -> Callable[[IntScalar], tuple[int, int]]

Return a Numba-compiled scalar 2D Hilbert decoder.

This is the low-level kernel used by :func:hilbert_decode_2d in scalar mode. It is intended for fusing into your own @numba.njit loops.

Parameters:

Name	Type	Description	Default
`nbits`	`int`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis).	required

Returns:

Type	Description
`callable`	A Numba-compiled function with signature `(index: int) -> (x: int, y: int)`.

get_hilbert_decode_3d_kernel ¶

get_hilbert_decode_3d_kernel(
    nbits: int, *, lut_dtype: LutUIntDTypeLike = np.uint16
) -> Callable[[IntScalar], tuple[int, int, int]]

Return a Numba-compiled scalar 3D Hilbert decoder.

This is the low-level kernel used by :func:hilbert_decode_3d in scalar mode and is intended for fusing into your own @numba.njit loops.

Parameters:

Name	Type	Description	Default
`nbits`	`int`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis).	required
`lut_dtype`	`LutUIntDTypeLike`	Element dtype used for the internal lookup tables. See :func:`get_hilbert_encode_3d_kernel` for the performance tradeoff.	`uint16`

Returns:

Type	Description
`callable`	A Numba-compiled function with signature `(index: int) -> (x: int, y: int, z: int)`.

get_hilbert_encode_2d_kernel ¶

get_hilbert_encode_2d_kernel(
    nbits: int,
) -> Callable[[IntScalar, IntScalar], int]

Return a Numba-compiled scalar 2D Hilbert encoder.

This is the low-level kernel used by :func:hilbert_encode_2d in scalar mode. It is intended for fusing into your own @numba.njit loops.

Parameters:

Name	Type	Description	Default
`nbits`	`int`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis).	required

Returns:

Type	Description
`callable`	A Numba-compiled function with signature `(x: int, y: int) -> int`.

get_hilbert_encode_3d_kernel ¶

get_hilbert_encode_3d_kernel(
    nbits: int, *, lut_dtype: LutUIntDTypeLike = np.uint16
) -> Callable[[IntScalar, IntScalar, IntScalar], IntScalar]

Return a Numba-compiled scalar 3D Hilbert encoder.

This is the low-level kernel used by :func:hilbert_encode_3d in scalar mode and is intended for fusing into your own @numba.njit loops.

Parameters:

Name	Type	Description	Default
`nbits`	`int`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis).	required
`lut_dtype`	`LutUIntDTypeLike`	Element dtype used for the internal lookup tables. Default is `uint16` (smallest; ~3 KiB LUT footprint). When fusing into a cache-intensive kernel, keeping the LUT small can help. For best throughput, it is usually better to match `lut_dtype` to your index dtype (`uint16`/`uint32`/`uint64`), which increases LUT size (~6 KiB for `uint32`, ~12 KiB for `uint64`) but reduces widening. In isolation, even the larger LUTs typically fit comfortably within the per-core L1 data cache of modern CPUs.	`uint16`

Returns:

Type	Description
`callable`	A Numba-compiled function with signature `(x: int, y: int, z: int) -> int`.

hilbert_decode_2d ¶

hilbert_decode_2d(
    index: IntScalar | IntArray,
    *,
    nbits: int | None = None,
    out_xs: IntArray | None = None,
    out_ys: IntArray | None = None,
    parallel: bool = False,
) -> tuple[int, int] | tuple[IntArray, IntArray]

Decode a Hilbert index to 2D coordinates.

This is a unified entrypoint:

Scalar mode: if index is a scalar integer, returns (x, y) as Python int.
Array mode: if index is a NumPy integer array, returns (xs, ys) as NumPy arrays and supports out_xs=/out_ys=.

Parameters:

Name	Type	Description	Default
`index`	`IntScalar \| IntArray`	Hilbert index or indices to decode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer array. Boolean inputs are rejected.	required
`nbits`	`int \| None`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis). For best performance and tighter output dtypes, set this to the tightest bound that fits your coordinate range. Must satisfy `1 <= nbits <= 32`. When specified, it must not exceed the effective bits supported by the index dtype. Bits outside the domain are ignored. If `None` (default), inferred from the index dtype: For arrays: uses `index_bits / 2`, where index_bits is the effective bits of the index dtype. For example, `uint16` → 8 bits, `uint64` → 32 bits, `int64` → 31 bits (sign bit excluded). For Python scalars: defaults to 32.	`None`
`out_xs`	`IntArray \| None`	Optional output buffers for array mode. Either provide both or neither. Must have the same shape as `index` and an integer dtype wide enough to hold values in `[0, 2**nbits)` (unsigned). Not allowed in scalar mode.	`None`
`out_ys`	`IntArray \| None`	Optional output buffers for array mode. Either provide both or neither. Must have the same shape as `index` and an integer dtype wide enough to hold values in `[0, 2**nbits)` (unsigned). Not allowed in scalar mode.	`None`
`parallel`	`bool`	Array mode: if `True`, the underlying Numba kernel may use parallel execution. Scalar mode: accepted for API consistency, but ignored. If `True`, a `UserWarning` is emitted. The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.	`False`

Returns:

Type	Description
`(int, int) or (ndarray, ndarray)`	The decoded coordinates. When output buffers are not provided in array mode, the coordinate dtype is chosen automatically: `uint8` if `nbits <= 8` `uint16` if `nbits <= 16` `uint32` if `nbits <= 32`

Raises:

Type	Description
`TypeError`	If boolean inputs are provided or if output buffers are used in scalar mode.
`ValueError`	If `nbits` is invalid or does not fit in the provided index/coord dtypes, or if output buffers are inconsistent (missing one of the pair) or have incorrect shapes.

hilbert_decode_3d ¶

hilbert_decode_3d(
    index: IntScalar | IntArray,
    *,
    nbits: int | None = None,
    out_xs: IntArray | None = None,
    out_ys: IntArray | None = None,
    out_zs: IntArray | None = None,
    parallel: bool = False,
) -> (
    tuple[int, int, int]
    | tuple[IntArray, IntArray, IntArray]
)

Decode a Hilbert index to 3D coordinates.

This is a unified entrypoint:

Scalar mode: if index is a scalar integer, returns (x, y, z) as Python int.
Array mode: if index is a NumPy integer array, returns (xs, ys, zs) as NumPy arrays and supports out_xs=/out_ys=/out_zs=.

Parameters:

Name	Type	Description	Default
`index`	`IntScalar \| IntArray`	Hilbert index or indices to decode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer array. Boolean inputs are rejected.	required
`nbits`	`int \| None`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis). For best performance and tighter output dtypes, set this to the tightest bound that fits your coordinate range. Must satisfy `1 <= nbits <= 21`. When specified, it must not exceed the effective bits supported by the index dtype. Bits outside the domain are ignored. If `None` (default), inferred from the index dtype: For arrays: uses `index_bits / 3`, where index_bits is the effective bits of the index dtype. For example, `uint32` → 10 bits, `uint64` → 21 bits, `int64` → 21 bits (63 bits effective / 3). For Python scalars: defaults to 21.	`None`
`out_xs`	`IntArray \| None`	Optional output buffers for array mode. Either provide all three or none. Must have the same shape as `index` and an integer dtype wide enough to hold values in `[0, 2**nbits)` (unsigned). Not allowed in scalar mode.	`None`
`out_ys`	`IntArray \| None`	Optional output buffers for array mode. Either provide all three or none. Must have the same shape as `index` and an integer dtype wide enough to hold values in `[0, 2**nbits)` (unsigned). Not allowed in scalar mode.	`None`
`out_zs`	`IntArray \| None`	Optional output buffers for array mode. Either provide all three or none. Must have the same shape as `index` and an integer dtype wide enough to hold values in `[0, 2**nbits)` (unsigned). Not allowed in scalar mode.	`None`
`parallel`	`bool`	Array mode: if `True`, the underlying Numba kernel may use parallel execution. Scalar mode: accepted for API consistency, but ignored. If `True`, a `UserWarning` is emitted. The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.	`False`

Returns:

Type	Description
`(int, int, int) or (ndarray, ndarray, ndarray)`	The decoded coordinates. When output buffers are not provided in array mode, the coordinate dtype is chosen automatically: `uint8` if `nbits <= 8` `uint16` if `nbits <= 16` `uint32` if `nbits <= 21`

Raises:

Type	Description
`TypeError`	If boolean inputs are provided or if output buffers are used in scalar mode.
`ValueError`	If `nbits` is invalid or does not fit in the provided index/coord dtypes, or if output buffers are inconsistent (not all three provided) or have incorrect shapes.

hilbert_encode_2d ¶

hilbert_encode_2d(
    x: IntScalar | IntArray,
    y: IntScalar | IntArray,
    *,
    nbits: int | None = None,
    out: IntArray | None = None,
    parallel: bool = False,
) -> int | IntArray

Encode 2D coordinates to a Hilbert index.

This is a unified entrypoint:

Scalar mode: if x and y are scalar integers, returns a Python int.
Array mode: if x and y are NumPy integer arrays, returns a NumPy array of indices (and supports out=).

Parameters:

Name	Type	Description	Default
`x`	`IntScalar \| IntArray`	Coordinates to encode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer arrays of identical shape. Boolean inputs are rejected.	required
`y`	`IntScalar \| IntArray`	Coordinates to encode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer arrays of identical shape. Boolean inputs are rejected.	required
`nbits`	`int \| None`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis). For best performance and tighter output dtypes, set this to the tightest bound that fits your coordinate range. Must satisfy `1 <= nbits <= 32`. When specified, it must also fit in the effective bits of the largest coordinate dtype. Bits outside the domain are ignored. If `None` (default), inferred from the input dtype: For arrays: uses the effective bits of the coordinate dtype, capped at 32. For example, `uint16` → 16 bits, `int16` → 15 bits (sign bit excluded), `uint64` or `int64` → 32 bits (algorithm maximum). For Python scalars: defaults to 32. For array mode, if the inferred value exceeds the algorithm maximum (32 bits), a `UserWarning` is emitted and `nbits` is capped at 32.	`None`
`out`	`IntArray \| None`	Optional output array for array mode. Must have the same shape as `x`/`y` and an integer dtype wide enough to hold `2*nbits` bits (unsigned). Not allowed in scalar mode.	`None`
`parallel`	`bool`	Array mode: if `True`, the underlying Numba kernel may use parallel execution. Scalar mode: accepted for API consistency, but ignored. If `True`, a `UserWarning` is emitted. The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.	`False`

Returns:

Type	Description
`int or ndarray`	Scalar mode: the Hilbert index as Python `int`. Array mode: an array of unsigned indices. When `out` is not provided, the output dtype is chosen automatically: `uint8` if `nbits <= 4` `uint16` if `nbits <= 8` `uint32` if `nbits <= 16` `uint64` otherwise up to `nbits <= 32`

Raises:

Type	Description
`TypeError`	If `x` and `y` are not both scalars or not both arrays, if boolean inputs are provided, or if `out` is used in scalar mode.
`ValueError`	If `nbits` is invalid, if array inputs have mismatched shapes, or if `out` has the wrong shape or an insufficient dtype.

hilbert_encode_3d ¶

hilbert_encode_3d(
    x: IntScalar | IntArray,
    y: IntScalar | IntArray,
    z: IntScalar | IntArray,
    *,
    nbits: int | None = None,
    out: IntArray | None = None,
    parallel: bool = False,
) -> int | IntArray

Encode 3D coordinates to a Hilbert index.

This is a unified entrypoint:

Scalar mode: if x, y, z are scalar integers, returns a Python int.
Array mode: if x, y, z are NumPy integer arrays, returns a NumPy array of indices (and supports out=).

Parameters:

Name	Type	Description	Default
`x`	`IntScalar \| IntArray`	Coordinates to encode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer arrays of identical shape. Boolean inputs are rejected.	required
`y`	`IntScalar \| IntArray`	Coordinates to encode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer arrays of identical shape. Boolean inputs are rejected.	required
`z`	`IntScalar \| IntArray`	Coordinates to encode. Scalar mode: Python `int` or NumPy integer scalar. Array mode: NumPy integer arrays of identical shape. Boolean inputs are rejected.	required
`nbits`	`int \| None`	Number of coordinate bits (grid domain is `[0, 2**nbits)` per axis). For best performance and tighter output dtypes, set this to the tightest bound that fits your coordinate range. Must satisfy `1 <= nbits <= 21`. When specified, it must also fit in the effective bits of the largest coordinate dtype. Bits outside the domain are ignored. If `None` (default), inferred from the input dtype: For arrays: uses the effective bits of the coordinate dtype, capped at 21. For example, `uint16` → 16 bits, `int16` → 15 bits (sign bit excluded), `uint64` or `int64` → 21 bits (algorithm maximum). For Python scalars: defaults to 21. For array mode, if the inferred value exceeds the algorithm maximum (21 bits), a `UserWarning` is emitted and `nbits` is capped at 21.	`None`
`out`	`IntArray \| None`	Optional output array for array mode. Must have the same shape as `x`/`y`/`z` and an integer dtype wide enough to hold `3*nbits` bits (unsigned). Not allowed in scalar mode.	`None`
`parallel`	`bool`	Array mode: if `True`, the underlying Numba kernel may use parallel execution. Scalar mode: accepted for API consistency, but ignored. If `True`, a `UserWarning` is emitted. The number of threads can be controlled with the environment variable `NUMBA_NUM_THREADS` or during runtime with `numba.set_num_threads()`.	`False`

Returns:

Type	Description
`int or ndarray`	Scalar mode: the Hilbert index as Python `int`. Array mode: an array of unsigned indices. When `out` is not provided, the output dtype is chosen automatically: `uint8` if `nbits <= 2` `uint16` if `nbits <= 5` `uint32` if `nbits <= 10` `uint64` otherwise up to `nbits <= 21`

Raises:

Type	Description
`TypeError`	If inputs are mixed between scalar and array modes, if boolean inputs are provided, or if `out` is used in scalar mode.
`ValueError`	If `nbits` is invalid, if array inputs have mismatched shapes, or if `out` has the wrong shape or an insufficient dtype.