column_utilities.hpp

/*
 * Copyright (c) 2019-2024, 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/column/column_view.hpp>
#include <cudf/detail/utilities/vector_factories.hpp>
#include <cudf/null_mask.hpp>
#include <cudf/strings/strings_column_view.hpp>
#include <cudf/types.hpp>
#include <cudf/utilities/default_stream.hpp>
#include <cudf/utilities/error.hpp>
 
#include <thrust/host_vector.h>
#include <thrust/iterator/transform_iterator.h>
 
namespace cudf::test {
 
enum class debug_output_level {
  FIRST_ERROR = 0,  // print first error only
  ALL_ERRORS,       // print all errors
  QUIET             // no debug output
};
 
constexpr size_type default_ulp = 4;
 
namespace detail {
 
bool expect_column_properties_equal(cudf::column_view const& lhs,
                                    cudf::column_view const& rhs,
                                    debug_output_level verbosity = debug_output_level::FIRST_ERROR);
 
bool expect_column_properties_equivalent(
  cudf::column_view const& lhs,
  cudf::column_view const& rhs,
  debug_output_level verbosity = debug_output_level::FIRST_ERROR);
 
bool expect_columns_equal(cudf::column_view const& lhs,
                          cudf::column_view const& rhs,
                          debug_output_level verbosity = debug_output_level::FIRST_ERROR);
 
bool expect_columns_equivalent(cudf::column_view const& lhs,
                               cudf::column_view const& rhs,
                               debug_output_level verbosity = debug_output_level::FIRST_ERROR,
                               size_type fp_ulps            = cudf::test::default_ulp);
 
void expect_equal_buffers(void const* lhs, void const* rhs, std::size_t size_bytes);
 
}  // namespace detail
 
void expect_column_empty(cudf::column_view const& col);
 
std::vector<bitmask_type> bitmask_to_host(cudf::column_view const& c);
 
bool validate_host_masks(std::vector<bitmask_type> const& expected_mask,
                         std::vector<bitmask_type> const& got_mask_begin,
                         size_type number_of_elements);
 
template <typename T, std::enable_if_t<not cudf::is_fixed_point<T>()>* = nullptr>
std::pair<thrust::host_vector<T>, std::vector<bitmask_type>> to_host(column_view c)
{
  thrust::host_vector<T> host_data(c.size());
  CUDF_CUDA_TRY(cudaMemcpy(host_data.data(), c.data<T>(), c.size() * sizeof(T), cudaMemcpyDefault));
  return {host_data, bitmask_to_host(c)};
}
 
// This signature is identical to the above overload apart from SFINAE so
// doxygen sees it as a duplicate.
 
template <typename T, std::enable_if_t<cudf::is_fixed_point<T>()>* = nullptr>
std::pair<thrust::host_vector<T>, std::vector<bitmask_type>> to_host(column_view c)
{
  using namespace numeric;
  using Rep = typename T::rep;
 
  auto host_rep_types = thrust::host_vector<Rep>(c.size());
 
  CUDF_CUDA_TRY(
    cudaMemcpy(host_rep_types.data(), c.begin<Rep>(), c.size() * sizeof(Rep), cudaMemcpyDefault));
 
  auto to_fp = [&](Rep val) { return T{scaled_integer<Rep>{val, scale_type{c.type().scale()}}}; };
  auto begin = thrust::make_transform_iterator(std::cbegin(host_rep_types), to_fp);
  auto const host_fixed_points = thrust::host_vector<T>(begin, begin + c.size());
 
  return {host_fixed_points, bitmask_to_host(c)};
}
 
template <>
inline std::pair<thrust::host_vector<std::string>, std::vector<bitmask_type>> to_host(column_view c)
{
  thrust::host_vector<std::string> host_data(c.size());
  auto stream = cudf::get_default_stream();
  if (c.size() > c.null_count()) {
    auto const scv     = strings_column_view(c);
    auto const h_chars = cudf::detail::make_std_vector_sync<char>(
      cudf::device_span<char const>(scv.chars_begin(stream), scv.chars_size(stream)), stream);
    auto const h_offsets = cudf::detail::make_std_vector_sync(
      cudf::device_span<cudf::size_type const>(scv.offsets().data<cudf::size_type>() + scv.offset(),
                                               scv.size() + 1),
      stream);
 
    // build std::string vector from chars and offsets
    std::transform(
      std::begin(h_offsets),
      std::end(h_offsets) - 1,
      std::begin(h_offsets) + 1,
      host_data.begin(),
      [&](auto start, auto end) { return std::string(h_chars.data() + start, end - start); });
  }
  return {std::move(host_data), bitmask_to_host(c)};
}
 
}  // namespace cudf::test
 
// Macros for showing line of failure.
#define CUDF_TEST_EXPECT_COLUMN_PROPERTIES_EQUAL(lhs, rhs)        \
  do {                                                            \
    SCOPED_TRACE(" <--  line of failure\n");                      \
    cudf::test::detail::expect_column_properties_equal(lhs, rhs); \
  } while (0)
 
#define CUDF_TEST_EXPECT_COLUMN_PROPERTIES_EQUIVALENT(lhs, rhs)        \
  do {                                                                 \
    SCOPED_TRACE(" <--  line of failure\n");                           \
    cudf::test::detail::expect_column_properties_equivalent(lhs, rhs); \
  } while (0)
 
#define CUDF_TEST_EXPECT_COLUMNS_EQUAL(lhs, rhs...)     \
  do {                                                  \
    SCOPED_TRACE(" <--  line of failure\n");            \
    cudf::test::detail::expect_columns_equal(lhs, rhs); \
  } while (0)
 
#define CUDF_TEST_EXPECT_COLUMNS_EQUIVALENT(lhs, rhs...)     \
  do {                                                       \
    SCOPED_TRACE(" <--  line of failure\n");                 \
    cudf::test::detail::expect_columns_equivalent(lhs, rhs); \
  } while (0)
 
#define CUDF_TEST_EXPECT_EQUAL_BUFFERS(lhs, rhs, size_bytes)        \
  do {                                                              \
    SCOPED_TRACE(" <--  line of failure\n");                        \
    cudf::test::detail::expect_equal_buffers(lhs, rhs, size_bytes); \
  } while (0)