Metadata-Version: 2.2
Name: h3_turbo
Version: 0.1.10
Summary: SYCL-accelerated H3 geospatial joins
Author: FluidGeo LLC, Craig Flockhart
License: ========================================================================
         H3-Turbo (FluidGeo LLC) - Third-Party Open Source Notices
         ========================================================================
         
         This software, H3-Turbo, is a proprietary product of FluidGeo LLC. 
         H3-Turbo incorporates and leverages several open-source libraries. 
         FluidGeo LLC acknowledges the following authors and contributors 
         and provides the required license notices below.
         
         ------------------------------------------------------------------------
         1. H3 Discrete Global Grid System
         ------------------------------------------------------------------------
         Source: https://github.com/uber/h3
         License: Apache License, Version 2.0
         
         Copyright (c) 2016-2022 Uber Technologies, Inc.
         
         Licensed under the Apache License, Version 2.0 (the "License");
         you may not use this file except in compliance with the License.
         You may obtain a copy of the License at
         
             http://www.apache.org/licenses/LICENSE-2.0
         
         Unless required by applicable law or agreed to in writing, software
         distributed under the License is distributed on an "AS IS" BASIS,
         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
         See the License for the specific language governing permissions and
         limitations under the License.
         
         *TRADEMARK NOTICE*: "H3" is a registered trademark of Uber Technologies, Inc. 
         H3-Turbo is an independent library and is not affiliated with or 
         endorsed by Uber Technologies, Inc.
         
         ------------------------------------------------------------------------
         2. NumPy
         ------------------------------------------------------------------------
         Source: https://github.com/numpy/numpy
         License: BSD 3-Clause "New" or "Revised" License
         
         Copyright (c) 2005-2023, NumPy Developers.
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
             * Redistributions of source code must retain the above copyright
               notice, this list of conditions and the following disclaimer.
             * Redistributions in binary form must reproduce the above copyright
               notice, this list of conditions and the following disclaimer in the
               documentation and/or other materials provided with the distribution.
             * Neither the name of the NumPy Developers nor the names of any
               contributors may be used to endorse or promote products derived
               from this software without specific prior written permission.
         
         ------------------------------------------------------------------------
         3. AdaptiveCpp (formerly hipSYCL)
         ------------------------------------------------------------------------
         Source: https://github.com/AdaptiveCpp/AdaptiveCpp
         License: BSD 2-Clause "Simplified" License
         
         Copyright (c) 2018-2024, AdaptiveCpp contributors. 
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
         ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED.
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: numpy
Requires-Dist: h3
Requires-Dist: pandas
Requires-Dist: intel-openmp; platform_machine == "x86_64"
Provides-Extra: spark
Requires-Dist: pyspark; extra == "spark"
Requires-Dist: pyarrow>=15.0.0; extra == "spark"
Description-Content-Type: text/markdown

# H3 SYCL Bridge

## ⚖️ Licensing
FluidGeo H3-Turbo is offered under a dual-license model:
* **Academic & Non-Commercial:** Free for research and educational purposes.
* **Commercial & Enterprise:** A yearly subscription is required for production environments. 
  * *Features: 1,186x speedup on Blackwell, zero-copy pinned memory, and priority SYCL kernel support.*

For enterprise trial keys and pricing, contact: **info@fluidgeollc.com**

## Installation

H3-Turbo is available on PyPI and comes with pre-compiled "fat" wheels for Linux (CUDA 12.x) supporting NVIDIA Ampere, Ada Lovelace, Hopper, and Blackwell architectures.

```bash
pip install h3-turbo
```

## Python API

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

```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 (
    latlng_to_cell_udf,
    cell_to_parent_udf,
    grid_disk_udf,
    spatial_join_udf
)

# 1. Lat/Lon to Cell
df = df.withColumn("h3", latlng_to_cell_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")))
```
