2D API¶

Public 2D Hilbert API.

This module provides the main user-facing API for 2D Hilbert encoding and decoding:

hilbert_encode_2d
hilbert_decode_2d

These accept either Python/NumPy scalar integers (scalar mode) or NumPy integer arrays (array mode).

For advanced use (embedding Hilbert encode/decode into your own Numba-compiled code), this module also exposes kernel accessors:

get_hilbert_encode_2d_kernel
get_hilbert_decode_2d_kernel

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_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.

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_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)`.