Refactor haversine_distance to a header-only API

CHANGELOG.md

@@ -1,3 +1,7 @@
+# cuSpatial 22.04.00 (Date TBD)
+
+Please see https://github.com/rapidsai/cuspatial/releases/tag/v22.04.00a for the latest changes to this development branch.
+
 # cuSpatial 22.02.00 (Date TBD)
 
 Please see https://github.com/rapidsai/cuspatial/releases/tag/v22.02.00a for the latest changes to this development branch.

conda/environments/cuspatial_dev_cuda11.0.yml

@@ -7,7 +7,7 @@ channels:
 dependencies:
   - clang=11.1.0
   - clang-tools=11.1.0
-  - cudf=22.02.*
+  - cudf=22.04.*
   - cudatoolkit=11.0
   - gdal>=3.0.2
   - geopandas>=0.9.0,<0.10.0a0

conda/environments/cuspatial_dev_cuda11.1.yml

@@ -7,7 +7,7 @@ channels:
 dependencies:
   - clang=11.1.0
   - clang-tools=11.1.0
-  - cudf=22.02.*
+  - cudf=22.04.*
   - cudatoolkit=11.1
   - gdal>=3.0.2
   - geopandas>=0.9.0,<0.10.0a0

conda/environments/cuspatial_dev_cuda11.2.yml

@@ -7,7 +7,7 @@ channels:
 dependencies:
   - clang=11.1.0
   - clang-tools=11.1.0
-  - cudf=22.02.*
+  - cudf=22.04.*
   - cudatoolkit=11.2
   - gdal>=3.0.2
   - geopandas>=0.9.0,<0.10.0a0

cpp/CMakeLists.txt

@@ -28,7 +28,7 @@ elseif(CMAKE_CUDA_ARCHITECTURES STREQUAL "")
   set(CUSPATIAL_BUILD_FOR_DETECTED_ARCHS TRUE)
 endif()
 
-project(CUSPATIAL VERSION 22.02.00 LANGUAGES C CXX)
+project(CUSPATIAL VERSION 22.04.00 LANGUAGES C CXX)
 
 # Needed because GoogleBenchmark changes the state of FindThreads.cmake,
 # causing subsequent runs to have different values for the `Threads::Threads` target.

cpp/include/cuspatial/experimental/detail/haversine.hpp

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * 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.
+ */
+
+#pragma once
+
+#include "cuspatial/types.hpp"
+#include <cuspatial/constants.hpp>
+#include <cuspatial/error.hpp>
+
+#include <rmm/cuda_stream_view.hpp>
+#include <rmm/exec_policy.hpp>
+#include <rmm/mr/device/device_memory_resource.hpp>
+#include <rmm/mr/device/per_device_resource.hpp>
+
+#include <thrust/iterator/constant_iterator.h>
+#include <thrust/iterator/zip_iterator.h>
+#include <thrust/transform.h>
+#include <thrust/tuple.h>
+
+#include <type_traits>
+
+namespace cuspatial {
+
+namespace detail {
+
+template <typename T>
+struct haversine_distance_functor {
+  haversine_distance_functor(T radius) : radius_(radius) {}
+
+  __device__ T operator()(location_2d<T> a_lonlat, location_2d<T> b_lonlat)
+  {
+    auto ax = a_lonlat.longitude * DEGREE_TO_RADIAN;
+    auto ay = a_lonlat.latitude * DEGREE_TO_RADIAN;
+    auto bx = b_lonlat.longitude * DEGREE_TO_RADIAN;
+    auto by = b_lonlat.latitude * DEGREE_TO_RADIAN;
+
+    // haversine formula
+    auto x        = (bx - ax) / 2;
+    auto y        = (by - ay) / 2;
+    auto sinysqrd = sin(y) * sin(y);
+    auto sinxsqrd = sin(x) * sin(x);
+    auto scale    = cos(ay) * cos(by);
+
+    return 2 * radius_ * asin(sqrt(sinysqrd + sinxsqrd * scale));
+  }
+
+  T radius_{};
+};
+
+template <class LonLatItA,
+          class LonLatItB,
+          class OutputIt,
+          class Location = typename std::iterator_traits<LonLatItA>::value_type,
+          class T        = typename Location::value_type>
+OutputIt haversine_distance(LonLatItA a_lonlat_first,
+                            LonLatItA a_lonlat_last,
+                            LonLatItB b_lonlat_first,
+                            OutputIt distance_first,
+                            T const radius               = EARTH_RADIUS_KM,
+                            rmm::cuda_stream_view stream = rmm::cuda_stream_default)
+{
+  using LocationB = typename std::iterator_traits<LonLatItB>::value_type;
+  static_assert(std::conjunction_v<std::is_same<location_2d<T>, Location>,
+                                   std::is_same<location_2d<T>, LocationB>>,
+                "Inputs must be cuspatial::location_2d");
+  static_assert(
+    std::conjunction_v<std::is_floating_point<T>,
+                       std::is_floating_point<typename LocationB::value_type>,
+                       std::is_floating_point<typename std::iterator_traits<OutputIt>::value_type>>,
+    "Haversine distance supports only floating-point coordinates.");
+
+  CUSPATIAL_EXPECTS(radius > 0, "radius must be positive.");
+
+  return thrust::transform(rmm::exec_policy(stream),
+                           a_lonlat_first,
+                           a_lonlat_last,
+                           b_lonlat_first,
+                           distance_first,
+                           haversine_distance_functor<T>(radius));
+}
+}  // namespace detail
+
+template <class LonLatItA, class LonLatItB, class OutputIt, class Location, class T>
+OutputIt haversine_distance(LonLatItA a_lonlat_first,
+                            LonLatItA a_lonlat_last,
+                            LonLatItB b_lonlat_first,
+                            OutputIt distance_first,
+                            T const radius)
+{
+  return detail::haversine_distance(a_lonlat_first,
+                                    a_lonlat_last,
+                                    b_lonlat_first,
+                                    distance_first,
+                                    radius,
+                                    rmm::cuda_stream_default);
+}
+
+}  // namespace cuspatial

cpp/include/cuspatial/experimental/haversine.hpp

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * 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.
+ */
+
+#pragma once
+
+#include <cuspatial/constants.hpp>
+
+#include <rmm/mr/device/device_memory_resource.hpp>
+#include <rmm/mr/device/per_device_resource.hpp>
+
+namespace cuspatial {
+
+/**
+ * brief Compute haversine distances between points in set A to the corresponding points in set B.
+ *
+ * Computes N haversine distances, where N is `std::distance(a_lon_first, a_lon_last)`.
+ * The distance for each `(a_lon[i], a_lat[i])` and `(b_lon[i], b_lat[i])` point pair is assigned to
+ * `distance_first[i]`. `distance_first` must be an iterator to output storage allocated for N
+ * distances.
+ *
+ * https://en.wikipedia.org/wiki/Haversine_formula
+ *
+ * @param[in]  a_lonlat_first: beginning of range of (longitude, latitude) locations in set A
+ * @param[in]  a_lonlat_last: end of range of (longitude, latitude) locations in set A
+ * @param[in]  b_lonlat_first: beginning of range of (longitude, latitude) locations in set B
+ * @param[out] distance_first: beginning of output range of haversine distances
+ * @param[in]  radius: radius of the sphere on which the points reside. default: 6371.0
+ *            (approximate radius of Earth in km)
+ *
+ * All iterators must have the same floating-point `value_type`.
+ *
+ * Computed distances will have the same units as `radius`.
+ *
+ * @tparam LonLatItA Iterator to input location set A. Must meet the requirements of
+ * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible.
+ * @tparam LonLatItB Iterator to input location set B. Must meet the requirements of
+ * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible.
+ * @tparam OutputIt Output iterator. Must meet the requirements of
+ * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible.
+ * @tparam Location The `value_type` of `LonLatItA` and `LonLatItB`. Must be
+ * `cuspatial::location_2d<T>`.
+ * @tparam T The underlying coordinate type. Must be a floating-point type.
+ *
+ * @return Output iterator to the element past the last distance computed.
+ *
+ * [LinkLRAI]: https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator
+ * "LegacyRandomAccessIterator"
+ */
+template <class LonLatItA,
+          class LonLatItB,
+          class OutputIt,
+          class Location = typename std::iterator_traits<LonLatItA>::value_type,
+          class T        = typename Location::value_type>
+OutputIt haversine_distance(LonLatItA a_lonlat_first,
+                            LonLatItA a_lonlat_last,
+                            LonLatItB b_lonlat_first,
+                            OutputIt distance_first,
+                            T const radius = EARTH_RADIUS_KM);
+}  // namespace cuspatial
+
+#include <cuspatial/experimental/detail/haversine.hpp>

cpp/include/cuspatial/experimental/type_utils.hpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2022, NVIDIA CORPORATION.
+ *
+ * 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.
+ */
+
+#include <cuspatial/types.hpp>
+
+#include <thrust/iterator/transform_iterator.h>
+#include <thrust/iterator/zip_iterator.h>
+
+namespace cuspatial {
+
+namespace {
+template <typename T>
+struct tuple_to_location_2d {
+  // using result_type = cuspatial::location_2d<T>;
+
+  CUSPATIAL_HOST_DEVICE cuspatial::location_2d<T> operator()(thrust::tuple<T, T> lonlat)
+  {
+    return cuspatial::location_2d<T>{thrust::get<0>(lonlat), thrust::get<1>(lonlat)};
+  }
+};
+
+}  // anonymous namespace
+
+// convert two iterators to an iterator<location_2d<T>
+template <typename LonIter, typename LatIter>
+auto to_location_2d(LonIter lon, LatIter lat)
+{
+  using T = typename std::iterator_traits<LonIter>::value_type;
+  static_assert(std::is_same_v<T, typename std::iterator_traits<LatIter>::value_type>,
+                "Iterator value_type mismatch");
+
+  auto zipped = thrust::make_zip_iterator(thrust::make_tuple(lon, lat));
+  return thrust::make_transform_iterator(zipped, tuple_to_location_2d<T>());
+}
+
+}  // namespace cuspatial

cpp/include/cuspatial/types.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, NVIDIA CORPORATION.
+ * Copyright (c) 2019-2022, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,18 +16,39 @@
 
 #pragma once
 
+#ifdef __CUDACC__
+#define CUSPATIAL_HOST_DEVICE __host__ __device__
+#else
+#define CUSPATIAL_HOST_DEVICE
+#endif
+
+#include <cstdint>
+
 namespace cuspatial {
 
+/**
+ * @brief A 2D location: latitude and longitude, altitude
+ *
+ * @tparam T the base type for the coordinates
+ */
+template <typename T>
+struct location_2d {
+  using value_type = T;
+  value_type longitude;
+  value_type latitude;
+};
+
 /**
  * @brief A 3D location: latitude, longitude, altitude
  *
  * @tparam T the base type for the coordinates
  */
 template <typename T>
 struct location_3d {
-  T latitude;
-  T longitude;
-  T altitude;
+  using value_type = T;
+  value_type longitude;
+  value_type latitude;
+  value_type altitude;
 };
 
 /**
@@ -46,16 +67,16 @@ struct coord_2d {
  *
  */
 struct its_timestamp {
-  uint32_t y   : 6;
-  uint32_t m   : 4;
-  uint32_t d   : 5;
-  uint32_t hh  : 5;
-  uint32_t mm  : 6;
-  uint32_t ss  : 6;
-  uint32_t wd  : 3;
-  uint32_t yd  : 9;
-  uint32_t ms  : 10;
-  uint32_t pid : 10;
+  std::uint32_t y   : 6;
+  std::uint32_t m   : 4;
+  std::uint32_t d   : 5;
+  std::uint32_t hh  : 5;
+  std::uint32_t mm  : 6;
+  std::uint32_t ss  : 6;
+  std::uint32_t wd  : 3;
+  std::uint32_t yd  : 9;
+  std::uint32_t ms  : 10;
+  std::uint32_t pid : 10;
 };
 
 }  // namespace cuspatial