hilbertcurve

Because the package leverages Python's arbitrary-precision integers, it can handle extremely high-iteration Hilbert curves. For example, a curve with $p=512$ and $n=10$ can represent coordinates with hundreds of digits and distances with over a thousand digits.

p = 512; n = 10
hilbert_curve = HilbertCurve(p, n)
ii = 123456789101112131415161718192021222324252627282930
point = hilbert_curve.points_from_distances([ii])[0]
print(f'point = {point}')

# point = [121075, 67332, 67326, 108879, 26637, 43346, 23848, 1551, 68130, 84004]

Install the package using the standard Python package manager:

pip install hilbertcurve

To speed up calculations for large datasets, you can enable multiprocessing by passing the n_procs keyword argument when instantiating HilbertCurve.

This applies to the following methods:

• points_from_distances(distances, match_type=False)
• distances_from_points(points, match_type=False)

n_procs values:

• 0: Do not use multiprocessing.
• -1: Use all available processes.
• positive integer: Use exactly that many processes.

from hilbertcurve.hilbertcurve import HilbertCurve
# Use all available cores
hilbert_curve = HilbertCurve(p=1, n=2, n_procs=-1)

Use the HilbertCurve class to map one-dimensional distances along a Hilbert curve to $n$-dimensional coordinates.

Initialize the curve with p (number of iterations) and n (number of dimensions). Use points_from_distances to process multiple distances at once.

from hilbertcurve.hilbertcurve import HilbertCurve
p=1; n=2
hilbert_curve = HilbertCurve(p, n)
distances = list(range(4))
points = hilbert_curve.points_from_distances(distances)
for point, dist in zip(points, distances):
    print(f'point(h={dist}) = {point}')

# Output:
# point(h=0) = [0, 0]
# point(h=1) = [0, 1]
# point(h=2) = [1, 1]
# point(h=3) = [1, 0]

Use the HilbertCurve class to map $n$-dimensional coordinates to their one-dimensional distance along the curve.

Initialize the curve with p (number of iterations) and n (number of dimensions). Use distances_from_points to process multiple points at once.

from hilbertcurve.hilbertcurve import HilbertCurve
p=1; n=2
hilbert_curve = HilbertCurve(p, n)
points = [[0,0], [0,1], [1,1], [1,0]]
distances = hilbert_curve.distances_from_points(points)
for point, dist in zip(points, distances):
    print(f'distance(x={point}) = {dist}')

# Output:
# distance(x=[0, 0]) = 0
# distance(x=[0, 1]) = 1
# distance(x=[1, 1]) = 2
# distance(x=[1, 0]) = 3

The HilbertCurve class provides the following public methods for coordinate and distance conversion.

Arguments typed as Iterable[int] support lists, tuples, and 1-D numpy arrays. Arguments typed as Iterable[Iterable[int]] support lists of lists, tuples of tuples, and 2-D numpy arrays with shape (num_points, num_dimensions).

The match_type keyword argument, when set to True, forces the output iterable to match the type of the input iterable (e.g., if you pass a numpy array, you get a numpy array back).