HilbertCurve

https://pypi.org/project/hilbertcurve/
Admin
HilbertCurve is a Python package that converts between one-dimensional distances along a Hilbert...
Tokens:5,216
Snippets:48
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install hilbertcurve Package

Source: https://pypi.org/project/hilbertcurve

Install the package using pip. This is the standard way to add the library to your Python environment.

```bash
pip install hilbertcurve
```

--------------------------------

### Get Distance Type from Points

Source: https://pypi.org/project/hilbertcurve

Demonstrates how the `match_type` argument in `distances_from_points` affects the output type. By default, it returns a list. Setting `match_type=True` returns a numpy.ndarray if the input is compatible.

```python
from hilbertcurve.hilbertcurve import HilbertCurve
import numpy as np
p=1; n=2
hilbert_curve = HilbertCurve(p, n)
num_points = 10_000
points = np.random.randint(
        low=0,
        high=hilbert_curve.max_x + 1,
        size=(num_points, hilbert_curve.n)
    )
distances = hilbert_curve.distances_from_points(points)
print(type(distances))

distances = hilbert_curve.distances_from_points(points, match_type=True)
print(type(distances))
```

--------------------------------

### HilbertCurve Initialization with Multiprocessing

Source: https://pypi.org/project/hilbertcurve

Demonstrates how to initialize the HilbertCurve class and utilize multiple processes for faster calculations using the `n_procs` argument.

```APIDOC
## HilbertCurve Initialization

### Description
Initialize the HilbertCurve with the order `p` and the number of dimensions `n`. The `n_procs` argument controls multiprocessing for supported methods.

### Parameters
*   **p** (int) - The order of the Hilbert curve.
*   **n** (int) - The number of dimensions.
*   **n_procs** (int) - Number of processes to use for multiprocessing.
    *   `0`: Disable multiprocessing.
    *   `-1`: Use all available processes.
    *   `positive integer`: Use the specified number of processes.

### Request Example
```python
from hilbertcurve.hilbertcurve import HilbertCurve
import numpy as np

p=1; n=2
hilbert_curve = HilbertCurve(p, n, n_procs=-1)
num_points = 100_000
points = np.random.randint(
    low=0,
    high=hilbert_curve.max_x + 1,
    size=(num_points, hilbert_curve.n)
)
distances = hilbert_curve.distances_from_points(points)
```
```

--------------------------------

### Handle Large Integers with HilbertCurve

Source: https://pypi.org/project/hilbertcurve/2.0.5

Demonstrates calculating Hilbert curve points from a very large distance integer, showcasing Python's support for arbitrarily large integers.

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

--------------------------------

### Configure Multiprocessing for HilbertCurve

Source: https://pypi.org/project/hilbertcurve/2.0.5

Use the n_procs keyword argument when creating a HilbertCurve instance to control the number of processes for parallel calculations. A value of -1 utilizes all available processes.

```python
>>> from hilbertcurve.hilbertcurve import HilbertCurve
>>> p=1; n=2
>>> hilbert_curve = HilbertCurve(p, n, n_procs=-1)
>>> num_points = 100_000
>>> points = np.random.randint(
        low=0,
        high=hilbert_curve.max_x + 1,
        size=(num_points, hilbert_curve.n)
    )
>>> distances = hilbert_curve.distances_from_points(points)
```

--------------------------------

### Generate Points from Distances

Source: https://pypi.org/project/hilbertcurve

Calculate n-dimensional points given their 1D distance along a Hilbert curve. Requires initializing HilbertCurve with dimensions (p) and number of dimensions (n).

```python
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}')
```

--------------------------------

### C Code Excerpt for Hilbert Curve Transformation

Source: https://pypi.org/project/hilbertcurve

This C code excerpt from John Skilling's work illustrates the transformation between Hilbert transpose and geometrical axes, fundamental to the Hilbert curve mapping.

```c
//+++++++++++++++++++++++++++ PUBLIC-DOMAIN SOFTWARE ++++++++++++++++++++++++++
// Functions: TransposetoAxes  AxestoTranspose
// Purpose:   Transform in-place between Hilbert transpose and geometrical axes
// Example:   b=5 bits for each of n=3 coordinates.
//            15-bit Hilbert integer = A B C D E F G H I J K L M N O is stored
//            as its Transpose
//                   X[0] = A D G J M                X[2]|
//                   X[1] = B E H K N    <------->       | /X[1]
//                   X[2] = C F I L O               axes |
//                          high  low                    0------ X[0]
//            Axes are stored conveniently as b-bit integers.
// Author:    John Skilling  20 Apr 2001 to 11 Oct 2003
```

--------------------------------

### Configure Multiprocessing for HilbertCurve

Source: https://pypi.org/project/hilbertcurve

Use the n_procs keyword argument when creating a HilbertCurve instance to control the number of processes for parallel calculations. A value of -1 uses all available processes, 0 disables multiprocessing, and any positive integer specifies the number of processes.

```python
n_procs (int): number of processes to use
    0 = dont use multiprocessing
   -1 = use all available processes
    any other positive integer = number of processes to use
```

```python
>>> from hilbertcurve.hilbertcurve import HilbertCurve
>>> p=1; n=2
>>> hilbert_curve = HilbertCurve(p, n, n_procs=-1)
>>> num_points = 100_000
>>> points = np.random.randint(
        low=0,
        high=hilbert_curve.max_x + 1,
        size=(num_points, hilbert_curve.n)
    )
>>> distances = hilbert_curve.distances_from_points(points)
```

--------------------------------

### Handle Large Integers with HilbertCurve

Source: https://pypi.org/project/hilbertcurve

Python's support for arbitrarily large integers allows HilbertCurve calculations to handle very large numbers for coordinates and distances, even for high-dimensional curves.

```python
>>> 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]
```

--------------------------------

### Generate Distances from Points

Source: https://pypi.org/project/hilbertcurve

Calculate the 1D distance along a Hilbert curve given n-dimensional points. Requires initializing HilbertCurve with dimensions (p) and number of dimensions (n).

```python
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}')
```

--------------------------------

### distance_from_point (Version 2.0)

Source: https://pypi.org/project/hilbertcurve

Converts a single n-dimensional point to its corresponding distance along the Hilbert curve.

```APIDOC
## distance_from_point

### Description
Converts a single n-dimensional point to its corresponding distance along the Hilbert curve.

### Method Signature
`distance_from_point(self, point: Iterable[int]) -> int`

### Parameters
*   **point** (Iterable[int]) - An iterable of integers representing the n-dimensional coordinates of the point.

### Returns
An integer representing the distance along the Hilbert curve.
```

--------------------------------

### distances_from_points (single point)

Source: https://pypi.org/project/hilbertcurve/2.0.5

Converts an iterable of n-dimensional points to their corresponding Hilbert distances. This overload handles multiple points and can utilize multiprocessing.

```APIDOC
## distances_from_points

### Description
Converts an iterable of n-dimensional points to their corresponding Hilbert distances. Supports multiprocessing.

### Method
`distances_from_points(points: Iterable[Iterable[int]], match_type: bool=False) -> Iterable[int]`

### Parameters
* **points** (Iterable[Iterable[int]]) - An iterable of n-dimensional points to convert.
* **match_type** (bool) - If True, the output type will match the input type (e.g., list, tuple, ndarray). Defaults to False.

### Returns
An iterable of Hilbert distances.
```

--------------------------------

### HilbertCurve Class Methods

Source: https://pypi.org/project/hilbertcurve/2.0.5

The HilbertCurve class provides methods to convert between a one-dimensional distance along a Hilbert curve and n-dimensional points. It also offers metadata derived from the construction parameters.

```APIDOC
## HilbertCurve Class Methods

### Description
Provides methods for converting between 1D distances and nD points on a Hilbert curve, along with metadata.

### Methods

- `point_from_distance(distance: int) -> Iterable[int]`
  Converts a 1D distance to an n-dimensional point.

- `points_from_distances(distances: Iterable[int], match_type: bool=False) -> Iterable[Iterable[int]]`
  Converts an iterable of 1D distances to an iterable of n-dimensional points. The `match_type` argument can force the output iterable to match the input iterable's type.

- `distance_from_point(point: Iterable[int]) -> int`
  Converts an n-dimensional point to a 1D distance.

- `distances_from_points(points: Iterable[Iterable[int]], match_type: bool=False) -> Iterable[int]`
  Converts an iterable of n-dimensional points to an iterable of 1D distances. The `match_type` argument can force the output iterable to match the input iterable's type.

### Metadata

- `n` (int): The number of dimensions.
- `p` (int): The number of iterations used in constructing the Hilbert curve.
- `max_x` (int): The maximum coordinate value along any dimension.
```

--------------------------------

### points_from_distances (single distance)

Source: https://pypi.org/project/hilbertcurve/2.0.5

Converts an iterable of Hilbert distances to their corresponding n-dimensional points. This overload handles multiple distances and can utilize multiprocessing.

```APIDOC
## points_from_distances

### Description
Converts an iterable of Hilbert distances to their corresponding n-dimensional points. Supports multiprocessing.

### Method
`points_from_distances(distances: Iterable[int], match_type: bool=False) -> Iterable[Iterable[int]]`

### Parameters
* **distances** (Iterable[int]) - An iterable of Hilbert distances to convert.
* **match_type** (bool) - If True, the output type will match the input type (e.g., list, tuple, ndarray). Defaults to False.

### Returns
An iterable of n-dimensional points.
```

--------------------------------

### distances_from_points

Source: https://pypi.org/project/hilbertcurve/2.0.5

Converts an iterable of n-dimensional points to their corresponding Hilbert distances. This method can utilize multiple cores if `n_procs` was specified during HilbertCurve instantiation.

```APIDOC
## distances_from_points

### Description
Converts n-dimensional points to Hilbert distances. Supports multiprocessing.

### Method
`distances_from_points(points: Iterable[Iterable[int]], match_type: bool=False) -> Iterable[int]`

### Parameters
* **points** (Iterable[Iterable[int]]) - An iterable of n-dimensional points to convert.
* **match_type** (bool) - If True, the output type will match the input type (e.g., list, tuple, ndarray). Defaults to False.

### Returns
An iterable of Hilbert distances.
```

--------------------------------

### distances_from_points

Source: https://pypi.org/project/hilbertcurve

Converts an iterable of n-dimensional points to their corresponding distances along the Hilbert curve. Supports multiprocessing.

```APIDOC
## distances_from_points

### Description
Converts one or more n-dimensional points to their corresponding distances along the Hilbert curve. This method can utilize multiple cores if `n_procs` is set during initialization.

### Method Signature
`distances_from_points(points: Iterable[Iterable[int]], match_type: bool=False) -> Iterable[int]`

### Parameters
*   **points** (Iterable[Iterable[int]]) - An iterable of n-dimensional points (each point is an iterable of integers).
*   **match_type** (bool) - If True, the output type will match the input type (e.g., list, tuple, ndarray). Defaults to False.

### Returns
An iterable of integers representing the distances along the Hilbert curve.
```

--------------------------------

### points_from_distances (Version 2.0)

Source: https://pypi.org/project/hilbertcurve

Converts a single distance to its corresponding n-dimensional point.

```APIDOC
## point_from_distance

### Description
Converts a single distance along the Hilbert curve to its corresponding n-dimensional coordinates.

### Method Signature
`point_from_distance(self, distance: int) -> Iterable[int]`

### Parameters
*   **distance** (int) - The distance along the Hilbert curve.

### Returns
An iterable of integers representing the n-dimensional coordinates of the point.
```

--------------------------------

### points_from_distances

Source: https://pypi.org/project/hilbertcurve

Converts multiple 1D distances along the Hilbert curve to n-dimensional points.

```APIDOC
## points_from_distances

### Description
Converts multiple 1D distances along the Hilbert curve to n-dimensional points.

### Method Signature
`points_from_distances(distances: Iterable[int], match_type: bool=False) -> Iterable[Iterable[int]]`

### Parameters
- **distances** (Iterable[int]) - An iterable of 1D distances along the Hilbert curve.
- **match_type** (bool, optional) - If True, the output iterable will match the type of the input iterable. Defaults to False.

### Returns
- Iterable[Iterable[int]] - An iterable of n-dimensional points.
```

--------------------------------

### distance_from_point

Source: https://pypi.org/project/hilbertcurve

Converts an n-dimensional point to its corresponding 1D distance along the Hilbert curve.

```APIDOC
## distance_from_point

### Description
Converts an n-dimensional point to its corresponding 1D distance along the Hilbert curve.

### Method Signature
`distance_from_point(point: Iterable[int]) -> int`

### Parameters
- **point** (Iterable[int]) - An n-dimensional point.

### Returns
- int - The 1D distance along the Hilbert curve.
```

--------------------------------

### point_from_distance

Source: https://pypi.org/project/hilbertcurve

Converts a 1D distance along the Hilbert curve to an n-dimensional point.

```APIDOC
## point_from_distance

### Description
Converts a 1D distance along the Hilbert curve to an n-dimensional point.

### Method Signature
`point_from_distance(distance: int) -> Iterable[int]`

### Parameters
- **distance** (int) - The 1D distance along the Hilbert curve.

### Returns
- Iterable[int] - An n-dimensional point.
```

--------------------------------

### points_from_distances

Source: https://pypi.org/project/hilbertcurve

Converts an iterable of distances along the Hilbert curve to their corresponding n-dimensional points. Supports multiprocessing.

```APIDOC
## points_from_distances

### Description
Converts one or more distances along the Hilbert curve to their corresponding n-dimensional coordinates. This method can utilize multiple cores if `n_procs` is set during initialization.

### Method Signature
`points_from_distances(distances: Iterable[int], match_type: bool=False) -> Iterable[Iterable[int]]`

### Parameters
*   **distances** (Iterable[int]) - An iterable of integers representing distances along the Hilbert curve.
*   **match_type** (bool) - If True, the output type will match the input type (e.g., list, tuple, ndarray). Defaults to False.

### Returns
An iterable of iterables, where each inner iterable represents the n-dimensional coordinates of a point.
```

--------------------------------

### distances_from_points

Source: https://pypi.org/project/hilbertcurve

Converts multiple n-dimensional points to their corresponding 1D distances along the Hilbert curve.

```APIDOC
## distances_from_points

### Description
Converts multiple n-dimensional points to their corresponding 1D distances along the Hilbert curve.

### Method Signature
`distances_from_points(points: Iterable[Iterable[int]], match_type: bool=False) -> Iterable[int]`

### Parameters
- **points** (Iterable[Iterable[int]]) - An iterable of n-dimensional points.
- **match_type** (bool, optional) - If True, the output iterable will match the type of the input iterable. Defaults to False.

### Returns
- Iterable[int] - An iterable of 1D distances along the Hilbert curve.
```

--------------------------------

### distance_from_coordinates (Pre-Version 2.0)

Source: https://pypi.org/project/hilbertcurve

Transforms a single n-dimensional point into its distance along the Hilbert curve. This method is available in versions prior to 2.0.

```APIDOC
## distance_from_coordinates

### Description
Transforms a single n-dimensional point into its distance along the Hilbert curve. This method was part of the API in versions prior to 2.0.

### Method Signature
`distance_from_coordinates(self, x_in: List[int]) -> int`

### Parameters
*   **x_in** (List[int]) - A list of integers representing the n-dimensional coordinates of the point.

### Returns
An integer representing the distance along the Hilbert curve.
```

--------------------------------

### coordinates_from_distance (Pre-Version 2.0)

Source: https://pypi.org/project/hilbertcurve

Transforms a single distance into its n-dimensional coordinates. This method is available in versions prior to 2.0.

```APIDOC
## coordinates_from_distance

### Description
Transforms a single distance along the Hilbert curve into its n-dimensional coordinates. This method was part of the API in versions prior to 2.0.

### Method Signature
`coordinates_from_distance(self, h: int) -> List[int]`

### Parameters
*   **h** (int) - The distance along the Hilbert curve.

### Returns
A list of integers representing the n-dimensional coordinates of the point.
```
Tokens:
Raw