Initial cuGraph C API - biased RW, C tests, script updates, cmake files, C library helpers

build.sh

@@ -119,7 +119,9 @@ if hasArg uninstall; then
     # uninstall libcugraph
     if [[ "$INSTALL_PREFIX" != "" ]]; then
         rm -rf ${INSTALL_PREFIX}/include/cugraph
+        rm -rf ${INSTALL_PREFIX}/include/cugraph_c
         rm -f ${INSTALL_PREFIX}/lib/libcugraph.so
+        rm -f ${INSTALL_PREFIX}/lib/libcugraph_c.so
     fi
     # This may be redundant given the above, but can also be used in case
     # there are other installed files outside of the locations above.

ci/test.sh

@@ -70,12 +70,21 @@ if (python ${CUGRAPH_ROOT}/ci/utils/is_pascal.py); then
     echo "WARNING: skipping C++ tests on Pascal GPU arch."
 else
     echo "C++ gtests for cuGraph (single-GPU only)..."
-    for gt in $(find ./tests -name "*_TEST" | grep -v "MG_" || true); do
+    for gt in $(find ./tests -name "*_TEST" | grep -v "MG_\|CAPI_" || true); do
         test_name=$(basename $gt)
         echo "Running gtest $test_name"
         ${gt} ${GTEST_FILTER} ${GTEST_ARGS}
         echo "Ran gtest $test_name : return code was: $?, test script exit code is now: $EXITCODE"
     done
+    # FIXME: the C API tests do not generate XML, so CI systems will not show
+    # them in the GUI. Failing C API tests will still fail CI though, and the
+    # output will appear in logs.
+    for ct in $(find ./tests -name "CAPI_*_TEST"); do
+        test_name=$(basename $ct)
+        echo "Running C API test $test_name"
+        ${ct}
+        echo "Ran C API test $test_name : return code was: $?, test script exit code is now: $EXITCODE"
+    done
 fi
 
 echo "Python pytest for pylibcugraph..."

cpp/CMakeLists.txt

@@ -49,27 +49,27 @@ list(APPEND usable_arch_values ${latest_arch})
 
 set(CMAKE_CUDA_ARCHITECTURES ${usable_arch_values})
 
-
 # Write the version header
 rapids_cmake_write_version_file(include/cugraph/version_config.hpp)
+rapids_cmake_write_version_file(include/cugraph_c/version_config.hpp)
 
-###################################################################################################
-# - build type ------------------------------------------------------------------------------------
+################################################################################
+# - build type -----------------------------------------------------------------
 
 # Set a default build type if none was specified
 rapids_cmake_build_type(Release)
 
-##############################################################################
-# - User Options  ------------------------------------------------------------
+################################################################################
+# - User Options  --------------------------------------------------------------
 
 option(BUILD_CUGRAPH_MG_TESTS "Build cuGraph multigpu algorithm tests" OFF)
 set(BLAS_LIBRARIES "" CACHE STRING "Location of BLAS library for FAISS build.")
 option(BUILD_STATIC_FAISS "Build the FAISS library for nearest neighbors search on GPU" OFF)
 option(CMAKE_CUDA_LINEINFO "Enable the -lineinfo option for nvcc (useful for cuda-memcheck / profiler" OFF)
 option(BUILD_TESTS "Configure CMake to build tests" ON)
 
-###################################################################################################
-# - compiler options ------------------------------------------------------------------------------
+################################################################################
+# - compiler options -----------------------------------------------------------
 
 rapids_find_package(CUDAToolkit REQUIRED
     BUILD_EXPORT_SET    cugraph-exports
@@ -103,8 +103,8 @@ if(CMAKE_BUILD_TYPE MATCHES Debug)
     list(APPEND CUGRAPH_CUDA_FLAGS -G -Xcompiler=-rdynamic)
 endif()
 
-###################################################################################################
-# - find openmp -----------------------------------------------------------------------------------
+################################################################################
+# - find openmp ----------------------------------------------------------------
 
 find_package(OpenMP)
 if(OpenMP_FOUND)
@@ -113,22 +113,20 @@ if(OpenMP_FOUND)
 endif()
 
 
-###################################################################################################
-# - find blas -------------------------------------------------------------------------------------
+################################################################################
+# - find blas ------------------------------------------------------------------
 
 if(NOT DEFINED BLAS_LIBRARIES)
   find_package( BLAS REQUIRED )
 else()
   message(STATUS "Manually setting BLAS to ${BLAS_LIBRARIES}")
 endif()
 
-###################################################################################################
-# - find CPM based dependencies  ------------------------------------------------------------------
-
+################################################################################
+# - find CPM based dependencies  -----------------------------------------------
 
 rapids_cpm_init()
 
-
 include(cmake/thirdparty/get_thrust.cmake)
 include(cmake/thirdparty/get_faiss.cmake)
 include(cmake/thirdparty/get_nccl.cmake)
@@ -145,9 +143,8 @@ if(BUILD_TESTS)
   include(cmake/thirdparty/get_gtest.cmake)
 endif()
 
-
-###################################################################################################
-# - library targets -------------------------------------------------------------------------------
+################################################################################
+# - libcugraph library target --------------------------------------------------
 
 add_library(cugraph SHARED
     src/detail/utility_wrappers.cu
@@ -218,6 +215,8 @@ add_library(cugraph SHARED
     src/visitors/graph_envelope.cpp
     src/visitors/visitors_factory.cpp
     src/visitors/bfs_visitor.cpp
+    src/visitors/rw_visitor.cpp
+    src/visitors/graph_make_visitor.cpp
 )
 
 set_target_properties(cugraph
@@ -252,8 +251,9 @@ target_link_options(cugraph PRIVATE "${CUGRAPH_BINARY_DIR}/fatbin.ld")
 
 add_library(cugraph::cugraph ALIAS cugraph)
 
-###################################################################################################
-# - include paths ---------------------------------------------------------------------------------
+################################################################################
+# - include paths --------------------------------------------------------------
+
 target_include_directories(cugraph
     PRIVATE
         "${CMAKE_CURRENT_SOURCE_DIR}/../thirdparty"
@@ -264,8 +264,8 @@ target_include_directories(cugraph
         "$<INSTALL_INTERFACE:include>"
 )
 
-###################################################################################################
-# - link libraries --------------------------------------------------------------------------------
+################################################################################
+# - link libraries -------------------------------------------------------------
 target_link_libraries(cugraph
     PUBLIC
         rmm::rmm
@@ -285,7 +285,7 @@ target_link_libraries(cugraph
 
 if(OpenMP_CXX_FOUND)
 target_link_libraries(cugraph PRIVATE
-###################################################################################################
+################################################################################
 ###   Use ${OpenMP_CXX_LIB_NAMES} instead of OpenMP::OpenMP_CXX to avoid the following warnings.
 ###
 ###   Cannot generate a safe runtime search path for target TARGET_NAME
@@ -334,17 +334,62 @@ target_link_libraries(cugraph PRIVATE
     ${OpenMP_CXX_LIB_NAMES})
 endif()
 
+################################################################################
+# - C-API library --------------------------------------------------------------
+
+add_library(cugraph_c SHARED
+        src/c_api/cugraph_api.cpp
+        )
+add_library(cugraph::cugraph_c ALIAS cugraph_c)
 
-###################################################################################################
-# - generate tests --------------------------------------------------------------------------------
+# Currently presuming we aren't calling any CUDA kernels in cugraph_c
+
+set_target_properties(cugraph_c
+    PROPERTIES BUILD_RPATH                         "\$ORIGIN"
+               INSTALL_RPATH                       "\$ORIGIN"
+               # set target compile options
+               CXX_STANDARD                        17
+               CXX_STANDARD_REQUIRED               ON
+               INTERFACE_POSITION_INDEPENDENT_CODE ON
+)
+
+target_compile_options(cugraph_c
+            PRIVATE "$<$<COMPILE_LANGUAGE:CXX>:${CUGRAPH_CXX_FLAGS}>"
+)
+
+################################################################################
+# - C-API include paths --------------------------------------------------------
+target_include_directories(cugraph_c
+    PRIVATE
+        "${CMAKE_CURRENT_SOURCE_DIR}/src"
+    PUBLIC
+        "$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>"
+        "$<INSTALL_INTERFACE:include>"
+)
+
+################################################################################
+# - C-API link libraries -------------------------------------------------------
+target_link_libraries(cugraph_c
+        PUBLIC
+                FAISS::FAISS
+                CUDA::cublas
+                CUDA::curand
+                CUDA::cusolver
+                CUDA::cusparse
+        PRIVATE
+                cugraph::cugraph
+)
+
+################################################################################
+# - generate tests -------------------------------------------------------------
 
 if(BUILD_TESTS)
   include(CTest)
   add_subdirectory(tests)
 endif()
 
-###################################################################################################
-# - install targets -------------------------------------------------------------------------------
+################################################################################
+# - install targets ------------------------------------------------------------
 rapids_cmake_install_lib_dir( lib_dir )
 include(CPack)
 
@@ -358,8 +403,18 @@ install(DIRECTORY include/cugraph/
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/include/cugraph/version_config.hpp
         DESTINATION include/cugraph)
 
-################################################################################################
-# - install export -------------------------------------------------------------------------------
+install(TARGETS cugraph_c
+        DESTINATION ${lib_dir})
+
+install(DIRECTORY include/cugraph_c/
+        DESTINATION include/cugraph_c)
+
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/include/cugraph_c/version_config.hpp
+        DESTINATION include/cugraph_c)
+
+################################################################################
+# - install export -------------------------------------------------------------
+
 set(doc_string
 [=[
 Provide targets for cuGraph.
@@ -376,24 +431,24 @@ thrust_create_target(cugraph::Thrust FROM_OPTIONS)
 
  rapids_export(INSTALL cugraph
     EXPORT_SET cugraph-exports
-    GLOBAL_TARGETS cugraph
+    GLOBAL_TARGETS cugraph cugraph_c
     NAMESPACE cugraph::
     DOCUMENTATION doc_string
     FINAL_CODE_BLOCK code_string
     )
 
-################################################################################################
-# - build export -------------------------------------------------------------------------------
+################################################################################
+# - build export ---------------------------------------------------------------
 rapids_export(BUILD cugraph
     EXPORT_SET cugraph-exports
-    GLOBAL_TARGETS cugraph
+    GLOBAL_TARGETS cugraph cugraph_c
     NAMESPACE cugraph::
     DOCUMENTATION doc_string
     FINAL_CODE_BLOCK code_string
     )
 
-###################################################################################################
-# - make documentation ----------------------------------------------------------------------------
+################################################################################
+# - make documentation ---------------------------------------------------------
 # requires doxygen and graphviz to be installed
 # from build directory, run make docs_cugraph
 

cpp/include/cugraph/algorithms.hpp

@@ -15,6 +15,8 @@
  */
 #pragma once
 
+#include <cugraph/api_helpers.hpp>
+
 #include <cugraph/dendrogram.hpp>
 #include <cugraph/graph.hpp>
 #include <cugraph/graph_view.hpp>
@@ -1309,8 +1311,8 @@ extract_ego(raft::handle_t const& handle,
  * (compressed) format; when padding is used the output is a matrix of vertex paths and a matrix of
  * edges paths (weights); in this case the matrices are stored in row major order; the vertex path
  * matrix is padded with `num_vertices` values and the weight matrix is padded with `0` values;
- * @param selector_type identifier for sampling strategy: uniform, biased, etc.; possible
- * values{0==uniform, 1==biased}; defaults to 0 == uniform;
+ * @param sampling_strategy pointer for sampling strategy: uniform, biased, etc.; possible
+ * values{0==uniform, 1==biased, 2==node2vec}; defaults to nullptr == uniform;
  * @return std::tuple<rmm::device_uvector<vertex_t>, rmm::device_uvector<weight_t>,
  * rmm::device_uvector<index_t>> Triplet of either padded or coalesced RW paths; in the coalesced
  * case (default), the return consists of corresponding vertex and edge weights for each, and
@@ -1330,8 +1332,8 @@ random_walks(raft::handle_t const& handle,
              typename graph_t::vertex_type const* ptr_d_start,
              index_t num_paths,
              index_t max_depth,
-             bool use_padding  = false,
-             int selector_type = 0);
+             bool use_padding                                     = false,
+             std::unique_ptr<sampling_params_t> sampling_strategy = nullptr);
 
 /**
  * @brief Finds (weakly-connected-)component IDs of each vertices in the input graph.

cpp/include/cugraph/api_helpers.hpp

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2021, 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.
+ */
+
+// Andrei Schaffer, aschaffer@nvidia.com
+//
+// This is a collection of aggregates used by (parts of) the API defined in algorithms.hpp;
+// These aggregates get propagated to the C-only API (which is why they're non-template aggregates)
+
+#pragma once
+
+namespace cugraph {
+
+enum class sampling_strategy_t : int { UNIFORM = 0, BIASED, NODE2VEC };
+
+struct sampling_params_t {
+  sampling_params_t(void) {}
+
+  sampling_params_t(int sampling_type, double p = 1.0, double q = 1.0)
+    : sampling_type_(static_cast<sampling_strategy_t>(sampling_type)), p_(p), q_(q)
+  {
+  }
+
+  sampling_strategy_t sampling_type_{sampling_strategy_t::UNIFORM};
+
+  // node2vec specific:
+  //
+  double p_;
+  double q_;
+};
+}  // namespace cugraph

cpp/include/cugraph/visitors/bfs_visitor.hpp

@@ -56,6 +56,12 @@ struct bfs_visitor<vertex_t,
     static return_t r{};
     return r;
   }
+
+  return_t&& get_result(void) override
+  {
+    static return_t r{};
+    return std::move(r);
+  }
 };
 
 template <typename vertex_t, typename edge_t, typename weight_t, bool st, bool mg>
@@ -71,6 +77,8 @@ struct bfs_visitor<vertex_t,
 
   return_t const& get_result(void) const override { return result_; }
 
+  return_t&& get_result(void) override { return std::move(result_); }
+
  private:
   erased_pack_t& ep_;
   return_t result_;