Pairwise Multipoint Equals Count function (#1022)

This contribution adds `pairwise_multipoint_equals_count` to the column and header-only APIs. `pairwise_multipoint_equals_count` counts the number of times that each point in the lhs occurs in the rhs.

```
auto result = pairwise_multipoint_equals_count(
    {{{0, 0}},{{1, 1, 2, 2}},{{0, 0}, {1, 1}, {2, 2}}},
    {
        {{0, 0}, {1, 1}, {2, 2}}
        {{0, 0}, {1, 1}, {2, 2}}
        {{0, 0}, {1, 1}, {2, 2}}
    }
)
result = {1, 2, 3}
```

Written while pairing with @isVoid.

Authors:
  - H. Thomson Comer (https://github.com/thomcom)
  - Michael Wang (https://github.com/isVoid)

Approvers:
  - Michael Wang (https://github.com/isVoid)
  - Mark Harris (https://github.com/harrism)

URL: #1022

Author: thomcom

cpp/CMakeLists.txt

@@ -122,6 +122,7 @@ add_library(cuspatial
     src/join/quadtree_point_in_polygon.cu
     src/join/quadtree_point_to_nearest_linestring.cu
     src/join/quadtree_bbox_filtering.cu
+    src/spatial/pairwise_multipoint_equals_count.cu
     src/spatial/polygon_bounding_box.cu
     src/spatial/linestring_bounding_box.cu
     src/spatial/point_in_polygon.cu

cpp/include/cuspatial/detail/geometry_collection/multipoint_ref.cuh

@@ -15,6 +15,7 @@
  */
 #pragma once
 #include <cuspatial/cuda_utils.hpp>
+#include <cuspatial/detail/iterator.hpp>
 
 #include <thrust/distance.h>
 

cpp/include/cuspatial/detail/pairwise_multipoint_equals_count.cuh

@@ -0,0 +1,108 @@
+/*
+ * Copyright (c) 2023, 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/cuda_utils.hpp>
+#include <cuspatial/detail/utility/zero_data.cuh>
+#include <cuspatial/error.hpp>
+#include <cuspatial/geometry/vec_2d.hpp>
+#include <cuspatial/iterator_factory.cuh>
+#include <cuspatial/range/multipoint_range.cuh>
+#include <cuspatial/range/range.cuh>
+#include <cuspatial/traits.hpp>
+
+#include <rmm/cuda_stream_view.hpp>
+#include <rmm/device_uvector.hpp>
+#include <rmm/exec_policy.hpp>
+
+#include <thrust/binary_search.h>
+#include <thrust/sort.h>
+#include <thrust/transform.h>
+
+#include <iterator>
+#include <type_traits>
+
+namespace cuspatial {
+
+namespace detail {
+
+template <class MultiPointRangeA, class MultiPointRangeB, class OutputIt>
+void __global__ pairwise_multipoint_equals_count_kernel(MultiPointRangeA lhs,
+                                                        MultiPointRangeB rhs,
+                                                        OutputIt output)
+{
+  using T = typename MultiPointRangeA::point_t::value_type;
+
+  for (auto idx = threadIdx.x + blockIdx.x * blockDim.x; idx < lhs.num_points();
+       idx += gridDim.x * blockDim.x) {
+    auto geometry_id    = lhs.geometry_idx_from_point_idx(idx);
+    vec_2d<T> lhs_point = lhs.point_begin()[idx];
+    auto rhs_multipoint = rhs[geometry_id];
+
+    atomicAdd(
+      &output[geometry_id],
+      thrust::binary_search(thrust::seq, rhs_multipoint.begin(), rhs_multipoint.end(), lhs_point));
+  }
+}
+
+}  // namespace detail
+
+template <class MultiPointRangeA, class MultiPointRangeB, class OutputIt>
+OutputIt pairwise_multipoint_equals_count(MultiPointRangeA lhs,
+                                          MultiPointRangeB rhs,
+                                          OutputIt output,
+                                          rmm::cuda_stream_view stream)
+{
+  using T       = typename MultiPointRangeA::point_t::value_type;
+  using index_t = typename MultiPointRangeB::index_t;
+
+  static_assert(is_same_floating_point<T, typename MultiPointRangeB::point_t::value_type>(),
+                "Origin and input must have the same base floating point type.");
+
+  CUSPATIAL_EXPECTS(lhs.size() == rhs.size(), "lhs and rhs inputs should have the same size.");
+
+  if (lhs.size() == 0) return output;
+
+  // Create a sorted copy of the rhs points.
+  auto key_it = make_geometry_id_iterator<index_t>(rhs.offsets_begin(), rhs.offsets_end());
+
+  rmm::device_uvector<index_t> rhs_keys(rhs.num_points(), stream);
+  rmm::device_uvector<vec_2d<T>> rhs_point_sorted(rhs.num_points(), stream);
+
+  thrust::copy(rmm::exec_policy(stream), key_it, key_it + rhs.num_points(), rhs_keys.begin());
+  thrust::copy(
+    rmm::exec_policy(stream), rhs.point_begin(), rhs.point_end(), rhs_point_sorted.begin());
+
+  auto rhs_with_keys =
+    thrust::make_zip_iterator(thrust::make_tuple(rhs_keys.begin(), rhs_point_sorted.begin()));
+
+  thrust::sort(rmm::exec_policy(stream), rhs_with_keys, rhs_with_keys + rhs.num_points());
+
+  auto rhs_sorted = multipoint_range{
+    rhs.offsets_begin(), rhs.offsets_end(), rhs_point_sorted.begin(), rhs_point_sorted.end()};
+
+  detail::zero_data_async(output, output + lhs.size(), stream);
+  auto [tpb, n_blocks] = grid_1d(lhs.num_points());
+  detail::pairwise_multipoint_equals_count_kernel<<<n_blocks, tpb, 0, stream.value()>>>(
+    lhs, rhs_sorted, output);
+
+  CUSPATIAL_CHECK_CUDA(stream.value());
+
+  return output + lhs.size();
+}
+
+}  // namespace cuspatial

cpp/include/cuspatial/geometry_collection/multipoint_ref.cuh

@@ -26,9 +26,9 @@ namespace cuspatial {
  */
 template <typename VecIterator>
 class multipoint_ref {
+ public:
   using point_t = iterator_value_type<VecIterator>;
 
- public:
   CUSPATIAL_HOST_DEVICE multipoint_ref(VecIterator begin, VecIterator end);
 
   /// Return iterator to the starting point of the multipoint.

cpp/include/cuspatial/pairwise_multipoint_equals_count.cuh

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2023, 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/geometry/vec_2d.hpp>
+
+#include <rmm/cuda_stream_view.hpp>
+
+#include <iterator>
+
+namespace cuspatial {
+
+/**
+ * @brief Count the number of equal points in multipoint pairs.
+ *
+ * Given two ranges of multipoints, this function counts points in the left-hand
+ * multipoint that exist in the corresponding right-hand multipoint.
+ *
+ * @example
+ *
+ * lhs: { {0, 0} }
+ * rhs: { {0, 0}, {1, 1}, {2, 2}, {3, 3} }
+ * count: { 1 }
+
+ * lhs: { {0, 0}, {1, 1}, {2, 2}, {3, 3} }
+ * rhs: { {0, 0} }
+ * count: { 1 }
+
+ * lhs: { { {3, 3}, {3, 3}, {0, 0} }, { {0, 0}, {1, 1}, {2, 2} }, { {0, 0} } }
+ * rhs: { { {0, 0}, {2, 2}, {1, 1} }, { {2, 2}, {0, 0}, {1, 1} }, { {1, 1} } }
+ * count: { 1, 3, 0 }
+ *
+ * @note All input iterators must conform to the specification defined by
+ * `multipoint_range.cuh` and the output iterator must be able to accept for
+ * storage values of type
+ * `uint32_t`.
+ *
+ * @param[in]  lhs_first multipoint_range of first array of multipoints
+ * @param[in]  rhs_first multipoint_range of second array of multipoints
+ * @param[out] count_first: beginning of range of uint32_t counts
+ * @param[in]  stream: The CUDA stream on which to perform computations and allocate memory.
+ * @tparam MultiPointRangeA The multipolygon range to compare point equality from
+ * @tparam MultiPointRangeB The multipolygon range to compare point equality to
+ * @tparam OutputIt Iterator over uint32_t. Must meet the requirements of
+ * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible and mutable.
+ *
+ * @return Output iterator to the element past the last count result written.
+ *
+ * [LinkLRAI]: https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator
+ * "LegacyRandomAccessIterator"
+ */
+template <class MultiPointRangeA, class MultiPointRangeB, class OutputIt>
+OutputIt pairwise_multipoint_equals_count(MultiPointRangeA lhs_first,
+                                          MultiPointRangeB rhs_first,
+                                          OutputIt count_first,
+                                          rmm::cuda_stream_view stream = rmm::cuda_stream_default);
+
+}  // namespace cuspatial
+
+#include <cuspatial/detail/pairwise_multipoint_equals_count.cuh>

cpp/include/cuspatial/pairwise_multipoint_equals_count.hpp

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2023, 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 <cudf/types.hpp>
+
+#include <cuspatial/column/geometry_column_view.hpp>
+
+#include <rmm/mr/device/per_device_resource.hpp>
+
+#include <memory>
+
+namespace cuspatial {
+
+/**
+ * @addtogroup spatial
+ * @brief Count the number of equal points in pairs of multipoints..
+ *
+ * Given two columns of multipoints, returns a column containing the
+ * count of points in each multipoint from `lhs` that exist in the
+ * corresponding multipoint in `rhs`.
+ *
+ * @param lhs Geometry column of multipoints with interleaved coordinates
+ * @param rhs Geometry column of multipoints with interleaved coordinates
+ * @param mr Device memory resource used to allocate the returned column.
+ * @return A column of size len(lhs) containing the number of points in each
+ * multipoint from `lhs` that are equal to a point in the corresponding
+ * multipoint in `rhs`.
+ *
+ * @throw cuspatial::logic_error if `lhs` and `rhs` have different coordinate
+ * types or lengths.
+ *
+ * @example
+ * ```
+ * lhs: MultiPoint(0, 0)
+ * rhs: MultiPoint((0, 0), (1, 1), (2, 2), (3, 3))
+ * result: 1
+
+ * lhs: MultiPoint((0, 0), (1, 1), (2, 2), (3, 3))
+ * rhs: MultiPoint((0, 0))
+ * result: 1
+
+ * lhs: (
+ *        MultiPoint((3, 3), (3, 3), (0, 0)),
+ *        MultiPoint((0, 0), (1, 1), (2, 2)),
+ *        MultiPoint((0, 0))
+ *      )
+ * rhs: (
+ *        MultiPoint((0, 0), (2, 2), (1, 1)),
+ *        MultiPoint((2, 2), (0, 0), (1, 1)),
+ *        MultiPoint((1, 1))
+ *      )
+ * result: ( 1, 3, 0 )
+ */
+std::unique_ptr<cudf::column> pairwise_multipoint_equals_count(
+  geometry_column_view const& lhs,
+  geometry_column_view const& rhs,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+}  // namespace cuspatial

cpp/include/cuspatial_test/base_fixture.hpp

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+#pragma once
+
 #include <rmm/cuda_stream_view.hpp>
 #include <rmm/mr/device/per_device_resource.hpp>