Metadata-Version: 2.4
Name: h3_turbo_sm90
Version: 1.0.2
Summary: SYCL-accelerated H3 geospatial library
Home-page: https://github.com/example/h3-sycl-bridge
Author: Craig
License: MIT
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Requires-Python: ~=3.12.0
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: h3>=4.0.0
Requires-Dist: nbformat
Provides-Extra: spark
Requires-Dist: pyspark; extra == "spark"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# H3 Turbo

## Python API

H3 Turbo provides drop-in replacements for common H3 functions, optimized for NumPy arrays and GPU acceleration.

## Installation

**Requirement:** H3 Turbo currently only supports Python 3.12 running on Ubuntu 24.04.x LTS.

Install the package matching your GPU architecture:

| Architecture | Hardware | Install Command |
| :--- | :--- | :--- |
| **Ampere** | NVIDIA A100 | `pip install h3-turbo-sm80` |
| **Ada Lovelace** | NVIDIA L4, RTX 4090 | `pip install h3-turbo-sm89` |
| **Hopper** | NVIDIA H100 | `pip install h3-turbo-sm90` |
| **Blackwell** | NVIDIA B200 | `pip install h3-turbo-sm100` |

*Note: Regardless of the package installed, use `import h3_turbo` in your code.*

## Benchmark files and example usage for h3_turbo
Jupyter notebooks with results can be found [here](https://github.com/cflockhart/fluidgeo_web). 

```python
import h3_turbo
import numpy as np

# 1. Lat/Lon to Cell
lats = np.random.uniform(37.7, 37.8, 1_000_000)
lngs = np.random.uniform(-122.5, -122.4, 1_000_000)
resolution = 9

# Returns uint64 array of H3 indices
cells = h3_turbo.latlng_to_cell(lats, lngs, resolution)

# 2. Cell to Parent
parent_res = 5
parents = h3_turbo.cell_to_parent(cells, parent_res)

# 3. Grid Disk (k-ring)
k = 2
# Returns (N, max_k_size) array, padded with 0s
disks = h3_turbo.grid_disk(cells, k)

# 4. Cell to Boundary
# Returns (N, 7, 2) array of [lat, lng] coordinates
boundaries = h3_turbo.cell_to_boundary(cells)

# 5. Spatial Join (Point-in-Polygon)
# Efficiently check if points are within a set of zones
zones = np.array([0x8928308280fffff], dtype=np.uint64)
mask = h3_turbo.spatial_join(cells, zones, resolution)
```

## Spark / Databricks Integration

H3 Turbo includes optimized Pandas UDFs for PySpark.

```python
from pyspark.sql.functions import col
from spark_h3_turbo import (
    latlons_to_h3s_udf,
    cell_to_parent_udf,
    grid_disk_udf,
    spatial_join_udf
)

# 1. Lat/Lon to Cell
df = df.withColumn("h3", latlons_to_h3s_udf(9)(col("lat"), col("lon")))

# 2. Cell to Parent
df = df.withColumn("parent", cell_to_parent_udf(5)(col("h3")))

# 3. Grid Disk
df = df.withColumn("kring", grid_disk_udf(2)(col("h3")))

# 4. Spatial Join (Broadcast)
zones_list = [0x8928308280fffff] # List of H3 integers
df = df.withColumn("in_zone", spatial_join_udf(zones_list, 9)(col("h3")))
```
When choosing a wheel file or Docker image for AWS, refer to the following table:

| AWS Instance | GPU | Architecture | GPU_ARCH |
| :--- | :--- | :--- | :--- |
| `g4dn` | NVIDIA T4 | Turing | `sm_75` |
| `g5` | NVIDIA A10G | Ampere | `sm_86` |
| `p4d` | NVIDIA A100 | Ampere | `sm_80` |
| `g6` | NVIDIA L4 | Ada Lovelace | `sm_89` |
| `g6e` | NVIDIA L40S | Ada Lovelace | `sm_89` |
| `p5` | NVIDIA H100 | Hopper | `sm_90` |
| `p5e` | NVIDIA H200 | Hopper | `sm_90` |
| `g7e` | NVIDIA B200 | Blackwell | `sm_100` |
