Add nvtext::minhash function

cpp/CMakeLists.txt

@@ -578,6 +578,7 @@ add_library(
   src/text/detokenize.cu
   src/text/edit_distance.cu
   src/text/generate_ngrams.cu
+  src/text/minhash.cu
   src/text/ngrams_tokenize.cu
   src/text/normalize.cu
   src/text/replace.cu

cpp/include/nvtext/minhash.hpp

@@ -0,0 +1,52 @@
+/*
+ * 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/column/column.hpp>
+#include <cudf/hashing.hpp>
+#include <cudf/strings/strings_column_view.hpp>
+
+namespace nvtext {
+/**
+ * @addtogroup nvtext_minhash
+ * @{
+ * @file
+ */
+
+/**
+ * @brief Returns the minhash value for each string
+ *
+ * Hash values are computed from substrings of each string and the
+ * minimum hash value is returned for each string.
+ *
+ * All null row entries are ignored and the output contains all valid rows.
+ *
+ * @param input Strings column to compute minhash
+ * @param width The character width used for apply substrings;
+ *              Any string smaller than this width will not be hashed.
+ *              Default is 4 characters.
+ * @param seed Seed value used for the MurmurHash3_32 algorithm
+ * @param mr Device memory resource used to allocate the returned column's device memory
+ * @return Minhash values for each string in input
+ */
+std::unique_ptr<cudf::column> minhash(
+  cudf::strings_column_view const& input,
+  cudf::size_type width               = 4,
+  cudf::hash_value_type seed          = cudf::DEFAULT_HASH_SEED,
+  rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
+
+/** @} */  // end of group
+}  // namespace nvtext

cpp/src/text/minhash.cu

@@ -0,0 +1,104 @@
+/*
+ * 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.
+ */
+
+#include <nvtext/minhash.hpp>
+
+#include <cudf/column/column.hpp>
+#include <cudf/column/column_device_view.cuh>
+#include <cudf/column/column_factories.hpp>
+#include <cudf/detail/hashing.hpp>
+#include <cudf/detail/null_mask.hpp>
+#include <cudf/detail/nvtx/ranges.hpp>
+#include <cudf/detail/utilities/device_operators.cuh>
+#include <cudf/detail/utilities/hash_functions.cuh>
+#include <cudf/strings/string_view.cuh>
+#include <cudf/utilities/default_stream.hpp>
+#include <cudf/utilities/error.hpp>
+
+#include <rmm/cuda_stream_view.hpp>
+#include <rmm/exec_policy.hpp>
+
+#include <thrust/iterator/counting_iterator.h>
+#include <thrust/transform.h>
+
+namespace nvtext {
+namespace detail {
+namespace {
+
+struct minhash_fn {
+  cudf::column_device_view d_strings;
+  cudf::size_type width;
+  cudf::hash_value_type seed;
+
+  __device__ cudf::hash_value_type operator()(cudf::size_type idx) const
+  {
+    if (d_strings.is_null(idx)) return 0;
+    auto const d_str = d_strings.element<cudf::string_view>(idx);
+
+    auto mh = cudf::hash_value_type{0};
+    for (cudf::size_type pos = 0; pos < d_str.length() - (width - 1); ++pos) {
+      auto const ss     = d_str.substr(pos, width);
+      auto const hasher = cudf::detail::MurmurHash3_32<cudf::string_view>{seed};
+      auto const hvalue = hasher(ss);
+      // cudf::detail::hash_combine(seed, hasher(ss)); matches cudf::hash() result
+
+      mh = mh > 0 ? cudf::detail::min(hvalue, mh) : hvalue;
+    }
+
+    return mh;
+  }
+};
+
+}  // namespace
+
+std::unique_ptr<cudf::column> minhash(cudf::strings_column_view const& input,
+                                      cudf::size_type width,
+                                      cudf::hash_value_type seed,
+                                      rmm::cuda_stream_view stream,
+                                      rmm::mr::device_memory_resource* mr)
+{
+  CUDF_EXPECTS(width > 1, "Parameter width should be an integer value of 2 or greater");
+
+  auto output_type = cudf::data_type{cudf::type_to_id<cudf::hash_value_type>()};
+  if (input.is_empty()) { return cudf::make_empty_column(output_type); }
+
+  auto const d_strings = cudf::column_device_view::create(input.parent(), stream);
+
+  auto hashes =
+    cudf::make_numeric_column(output_type, input.size(), cudf::mask_state::UNALLOCATED, stream, mr);
+  auto d_hashes = hashes->mutable_view().data<cudf::hash_value_type>();
+
+  auto const itr = thrust::make_counting_iterator<cudf::size_type>(0);
+  auto const fn  = minhash_fn{*d_strings, width, seed};
+  thrust::transform(rmm::exec_policy(stream), itr, itr + input.size(), d_hashes, fn);
+
+  hashes->set_null_mask(cudf::detail::copy_bitmask(input.parent(), stream, mr), input.null_count());
+
+  return hashes;
+}
+
+}  // namespace detail
+
+std::unique_ptr<cudf::column> minhash(cudf::strings_column_view const& input,
+                                      cudf::size_type width,
+                                      cudf::hash_value_type seed,
+                                      rmm::mr::device_memory_resource* mr)
+{
+  CUDF_FUNC_RANGE();
+  return detail::minhash(input, width, seed, cudf::get_default_stream(), mr);
+}
+
+}  // namespace nvtext

cpp/tests/CMakeLists.txt

@@ -444,6 +444,7 @@ ConfigureTest(
   TEXT_TEST
   text/bpe_tests.cpp
   text/edit_distance_tests.cpp
+  text/minhash_tests.cpp
   text/ngrams_tests.cpp
   text/ngrams_tokenize_tests.cpp
   text/normalize_tests.cpp

cpp/tests/text/minhash_tests.cpp

@@ -0,0 +1,56 @@
+/*
+ * 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.
+ */
+
+#include <cudf/column/column.hpp>
+#include <cudf/strings/strings_column_view.hpp>
+#include <nvtext/minhash.hpp>
+
+#include <cudf_test/base_fixture.hpp>
+#include <cudf_test/column_utilities.hpp>
+#include <cudf_test/column_wrapper.hpp>
+
+#include <vector>
+
+struct MinHashTest : public cudf::test::BaseFixture {
+};
+
+TEST_F(MinHashTest, Basic)
+{
+  auto input = cudf::test::strings_column_wrapper({"doc 1", "", "this is doc 2", "", "doc 3"},
+                                                  {1, 0, 1, 1, 1});
+
+  auto view = cudf::strings_column_view(input);
+
+  auto results = nvtext::minhash(view);
+
+  auto expected = cudf::test::fixed_width_column_wrapper<cudf::hash_value_type>(
+    {1207251914u, 0u, 21141582u, 0u, 1207251914u}, {1, 0, 1, 1, 1});
+  CUDF_TEST_EXPECT_COLUMNS_EQUAL(*results, expected);
+}
+
+TEST_F(MinHashTest, EmptyTest)
+{
+  auto input   = cudf::make_empty_column(cudf::data_type{cudf::type_id::STRING});
+  auto view    = cudf::strings_column_view(input->view());
+  auto results = nvtext::minhash(view);
+  EXPECT_EQ(results->size(), 0);
+}
+
+TEST_F(MinHashTest, ErrorsTest)
+{
+  auto input = cudf::test::strings_column_wrapper({"pup"});
+  EXPECT_THROW(nvtext::minhash(cudf::strings_column_view(input), 0), cudf::logic_error);
+}

python/cudf/cudf/_lib/cpp/nvtext/minhash.pxd

@@ -0,0 +1,17 @@
+# Copyright (c) 2023, NVIDIA CORPORATION.
+
+from libc.stdint cimport uint32_t
+from libcpp.memory cimport unique_ptr
+
+from cudf._lib.cpp.column.column cimport column
+from cudf._lib.cpp.column.column_view cimport column_view
+from cudf._lib.cpp.types cimport size_type
+
+
+cdef extern from "nvtext/minhash.hpp" namespace "nvtext" nogil:
+
+    cdef unique_ptr[column] minhash(
+        const column_view &strings,
+        size_type ngrams,
+        uint32_t seed
+    ) except +

python/cudf/cudf/_lib/nvtext/CMakeLists.txt

@@ -1,5 +1,5 @@
 # =============================================================================
-# Copyright (c) 2022, NVIDIA CORPORATION.
+# Copyright (c) 2022-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
@@ -12,8 +12,8 @@
 # the License.
 # =============================================================================
 
-set(cython_sources edit_distance.pyx generate_ngrams.pyx ngrams_tokenize.pyx normalize.pyx
-                   replace.pyx stemmer.pyx subword_tokenize.pyx tokenize.pyx
+set(cython_sources edit_distance.pyx generate_ngrams.pyx minhash.pyx ngrams_tokenize.pyx
+                   normalize.pyx replace.pyx stemmer.pyx subword_tokenize.pyx tokenize.pyx
 )
 set(linked_libraries cudf::cudf)
 rapids_cython_create_modules(

python/cudf/cudf/_lib/nvtext/minhash.pyx

@@ -0,0 +1,33 @@
+# Copyright (c) 2023, NVIDIA CORPORATION.
+
+from cudf.core.buffer import acquire_spill_lock
+
+from libc.stdint cimport uint32_t
+from libcpp.memory cimport unique_ptr
+from libcpp.utility cimport move
+
+from cudf._lib.column cimport Column
+from cudf._lib.cpp.column.column cimport column
+from cudf._lib.cpp.column.column_view cimport column_view
+from cudf._lib.cpp.nvtext.minhash cimport minhash as cpp_minhash
+from cudf._lib.cpp.types cimport size_type
+
+
+@acquire_spill_lock()
+def minhash(Column strings, int width, int seed=0):
+
+    cdef column_view c_strings = strings.view()
+    cdef size_type c_width = width
+    cdef uint32_t c_seed = seed
+    cdef unique_ptr[column] c_result
+
+    with nogil:
+        c_result = move(
+            cpp_minhash(
+                c_strings,
+                c_width,
+                c_seed
+            )
+        )
+
+    return Column.from_unique_ptr(move(c_result))

python/cudf/cudf/_lib/strings/__init__.py

@@ -1,9 +1,10 @@
-# Copyright (c) 2020-2022, NVIDIA CORPORATION.
+# Copyright (c) 2020-2023, NVIDIA CORPORATION.
 from cudf._lib.nvtext.edit_distance import edit_distance, edit_distance_matrix
 from cudf._lib.nvtext.generate_ngrams import (
     generate_character_ngrams,
     generate_ngrams,
 )
+from cudf._lib.nvtext.minhash import minhash
 from cudf._lib.nvtext.ngrams_tokenize import ngrams_tokenize
 from cudf._lib.nvtext.normalize import normalize_characters, normalize_spaces
 from cudf._lib.nvtext.replace import filter_tokens, replace_tokens

python/cudf/cudf/core/column/string.py

@@ -5226,6 +5226,32 @@ def edit_distance_matrix(self) -> SeriesOrIndex:
             libstrings.edit_distance_matrix(self._column)
         )
 
+    def minhash(self, n: int = 4, seed: int = 0) -> SeriesOrIndex:
+        """
+        Compute the minhash of a strings column.
+
+        Parameters
+        ----------
+        n : int
+            The width of the substring to hash.
+            Default of 4 characters.
+        seed : int
+            The seed used for the hash algorithm.
+            Default is 0.
+
+        Examples
+        --------
+        >>> import cudf
+        >>> str_series = cudf.Series(['this is my', 'favorite book'])
+        >>> str_series.str.minhash()
+        0    2012639418
+        1    182731933
+        dtype: int32
+        """
+        return self._return_or_inplace(
+            libstrings.minhash(self._column, n, seed)
+        )
+
 
 def _massage_string_arg(value, name, allow_col=False):
     if isinstance(value, str):