Merge pull request #6 from JetBrains-Research/master

Pulling changes

Author: Krekep

CMakeLists.txt

@@ -2,13 +2,14 @@
 # Add this file as sub-directory to your project to use library functionality
 
 cmake_minimum_required(VERSION 3.15 FATAL_ERROR)
-project(cubool LANGUAGES CXX)
+project(cuBool LANGUAGES CXX)
 
 # Exposed to the user build options
-option(CUBOOL_WITH_CUDA       "Build library with cuda backend (default)" ON)
-option(CUBOOL_WITH_SEQUENTIAL "Build library with cpu sequential backend (fallback)" ON)
-option(CUBOOL_WITH_NAIVE      "Build library with naive and naive-shared dense matrix multiplication" OFF)
-option(CUBOOL_BUILD_TESTS     "Build project unit-tests with gtest" ON)
+option(CUBOOL_WITH_CUDA          "Build library with cuda backend (default)" ON)
+option(CUBOOL_WITH_SEQUENTIAL    "Build library with cpu sequential backend (fallback)" ON)
+option(CUBOOL_WITH_NAIVE         "Build library with naive and naive-shared dense matrix multiplication" OFF)
+option(CUBOOL_BUILD_TESTS        "Build project unit-tests with gtest" ON)
+option(CUBOOL_COPY_TO_PY_PACKAGE "Copy compiled shared library into python package folder (for package use purposes)" ON)
 
 set(CUBOOL_VERSION_MAJOR 1)
 set(CUBOOL_VERSION_MINOR 0)

README.md

@@ -5,7 +5,7 @@
 [![JB Research](https://jb.gg/badges/research-flat-square.svg)](https://research.jetbrains.org/)
 [![Ubuntu](https://github.com/JetBrains-Research/cuBool/workflows/Ubuntu/badge.svg?branch=master)](https://github.com/JetBrains-Research/cuBool/actions)
 [![License](https://img.shields.io/badge/license-MIT-orange)](https://github.com/JetBrains-Research/cuBool/blob/master/LICENSE)
-[![Package](https://img.shields.io/badge/pypi%20package-alpha-%233776ab)](https://test.pypi.org/project/pycubool/)
+[![Package](https://img.shields.io/badge/pypi%20package-1.0.0-%233776ab)](https://pypi.org/project/pycubool/)
 
 **cuBool** is a linear Boolean algebra library primitives and operations for 
 work with sparse matrices written on the NVIDIA CUDA platform. The primary 
@@ -28,6 +28,8 @@ for computations on CPU side only. This backend is selected automatically
 if Cuda compatible device is not presented in the system. This can be quite handy for 
 prototyping algorithms on a local computer for later running on a powerful server.  
 
+**PyPI package web page** is following [link](https://pypi.org/project/pycubool/).
+
 ### Features
 
 - [X] Library C interface
@@ -45,29 +47,50 @@ prototyping algorithms on a local computer for later running on a powerful serve
 - [X] Device capabilities query
 - [X] IO matrix loading from mtx file
 - [X] IO matrix saving into mtx file
-- [ ] IO matrix saving into gviz format
+- [X] IO matrix saving into gviz format
 - [X] IO user-defined file logging
 - [X] Wrapper for Python API
 - [X] Wrapper syntax sugar
 - [X] Tests for Python wrapper
 - [X] Pip package
-- [ ] Code examples
-- [ ] User guide
+- [X] Code examples
+- [X] User guide
 - [X] Unit Tests collection
-- [ ] Publish built artifacts and shared libs
-- [ ] Publish stable source code archives
+- [X] Publish built artifacts and shared libs
+- [X] Publish stable source code archives
+
+## Simple example
+
+Create sparse matrices, compute matrix-matrix product and print the result to the output:
+
+```python
+import pycubool as cb
+
+a = cb.Matrix.empty(shape=(2, 3))
+a[0, 0] = True
+a[1, 2] = True
+
+b = cb.Matrix.empty(shape=(3, 4))
+b[0, 1] = True
+b[0, 2] = True
+b[1, 3] = True
+b[2, 1] = True
+
+print(a, b, a.mxm(b), sep="\n")
+```
 
 ## Installation
 
-If you are running OS **Ubuntu 20.04** or higher you can download the official
+If you are running **Linux based** OS (tested on Ubuntu 20.04) you can download the official
 PyPI **pycubool** python package, which includes compiled library source code
 with Cuda and Sequential computations support. Installation process 
 requires only `python3` to be installed on your machine. Python can be installed 
 as follows [link](https://phoenixnap.com/kb/how-to-install-python-3-ubuntu).
 
 If all requirements are satisfied, run the following command to install PyPI package:
+
 ```shell script
-$ python3 -m pip install -i https://test.pypi.org/simple/ pycubool
+$ python3 -m pip install pycubool
 ``` 
 
 ## Getting Started
@@ -77,11 +100,11 @@ These steps are required if you want to build library for your specific platform
 
 ### Requirements
 
-- Linux Ubuntu (tested on 20.04)
+- Linux based (tested on Ubuntu 20.04)
 - CMake Version 3.15 or higher
-- CUDA Compatible GPU device
+- CUDA Compatible GPU device (to run Cuda computations)
 - GCC Compiler 
-- NVIDIA CUDA toolkit
+- NVIDIA CUDA toolkit (to build Cuda backend)
 - Python 3 (for `pycubool` library)
 - Git (to get source code)
 
@@ -237,9 +260,9 @@ wrapper can be used to compute the same transitive closure problem for the
 directed graph within python environment:
 
 ```python
-import pycubool
+import pycubool as cb
 
-def transitive_closure(a: pycubool.Matrix):
+def transitive_closure(a: cb.Matrix):
     """
     Evaluates transitive closure for the provided
     adjacency matrix of the graph.
@@ -296,7 +319,7 @@ cuBool
 ## Citation 
 
 ```ignorelang
-@online{cuBool,
+@MISC{cuBool,
   author = {Orachyov, Egor and Alimov, Pavel and Grigorev, Semyon},
   title = {cuBool: sparse Boolean linear algebra for Nvidia Cuda},
   year = 2020,

cubool/CMakeLists.txt

@@ -178,14 +178,16 @@ if (CUBOOL_BUILD_TESTS)
     add_subdirectory(tests)
 endif()
 
-# todo: Different platforms has specific naming conventions
-set(LIBRARY_FILE_NAME "libcubool.so")
-
-# Copy cubool library after build
-add_custom_command(
-    TARGET cubool POST_BUILD
-    COMMAND "${CMAKE_COMMAND}" -E
-    copy
-    "${CMAKE_BINARY_DIR}/cubool/${LIBRARY_FILE_NAME}"
-    "${CMAKE_BINARY_DIR}/python/pycubool"
-    COMMENT "Copy cubool lib into python folder")
+# Copy cubool library after build if allowed
+if (CUBOOL_COPY_TO_PY_PACKAGE)
+    # todo: Different platforms has specific naming conventions
+    set(LIBRARY_FILE_NAME "libcubool.so")
+
+    add_custom_command(
+        TARGET cubool POST_BUILD
+        COMMAND "${CMAKE_COMMAND}" -E
+        copy
+        "${CMAKE_BINARY_DIR}/cubool/${LIBRARY_FILE_NAME}"
+        "${CMAKE_BINARY_DIR}/python/pycubool"
+        COMMENT "Copy cubool compiled lib into python folder")
+endif()

cubool/include/cubool/cubool.h

@@ -32,7 +32,11 @@
 #endif
 
 // Preserve C names in shared library
-#define CUBOOL_EXPORT extern "C"
+#ifdef __cplusplus
+    #define CUBOOL_EXPORT extern "C"
+#else
+    #define CUBOOL_EXPORT
+#endif
 
 // Exporting/importing symbols for Microsoft Visual Studio
 #if (_MSC_VER && !__INTEL_COMPILER)
@@ -286,6 +290,9 @@ CUBOOL_EXPORT CUBOOL_API cuBool_Status cuBool_Matrix_SetMarker(
  * @note Pass null marker if you want to retrieve only the required marker buffer size.
  * @note After the function call the actual size of the marker is stored in the size variable.
  *
+ * @note size is set to the actual marker length plus null terminator symbol.
+ *       For marker "matrix" size variable will be set to 7.
+ *
  * @param matrix Matrix handle to perform operation on
  * @param[in,out] marker Where to store null-terminated UTF-8 encoded marker string.
  * @param[in,out] size Size of the provided buffer in bytes to save marker string.

cubool/sources/cuBool_Matrix_Marker.cpp

@@ -24,6 +24,7 @@
 
 #include <cuBool_Common.hpp>
 #include <cstring>
+#include <cmath>
 
 cuBool_Status cuBool_Matrix_Marker(
         cuBool_Matrix matrix,
@@ -37,11 +38,15 @@ cuBool_Status cuBool_Matrix_Marker(
 
         auto m = (cubool::Matrix*) matrix;
         auto actualSize = m->getDebugMarkerSizeWithNullT();
+        auto toCopy = std::min(*size, actualSize);
 
-        if (marker != nullptr && *size > 0) {
+        if (marker != nullptr && toCopy > 0) {
+            // C str (with \0)
             const auto* text = m->getDebugMarker();
-            std::memcpy(marker, text, *size);
-            marker[*size - 1] = '\0';
+            std::memcpy(marker, text, toCopy);
+
+            // Explicitly terminate (for case size < actualSize)
+            marker[toCopy - 1] = '\0';
         }
 
         *size = actualSize;

cubool/sources/cuda/matrix_csr.cu

@@ -24,7 +24,6 @@
 
 #include <cuda/matrix_csr.hpp>
 #include <core/error.hpp>
-#include <utils/exclusive_scan.hpp>
 #include <utils/timer.hpp>
 #include <algorithm>
 
@@ -96,7 +95,7 @@ namespace cubool {
         return mMatrixImpl.m_vals == 0;
     }
 
-    void MatrixCsr::transferToDevice(const std::vector<index> &rowOffsets, const std::vector<index> &colIndices) {
+    void MatrixCsr::transferToDevice(const std::vector<index> &rowOffsets, const std::vector<index> &colIndices) const {
         // Create device buffers and copy data from the cpu side
         thrust::device_vector<index, DeviceAlloc<index>> rowsDeviceVec(rowOffsets.size());
         thrust::device_vector<index, DeviceAlloc<index>> colsDeviceVec(colIndices.size());

cubool/sources/cuda/matrix_csr.hpp

@@ -65,7 +65,7 @@ namespace cubool {
         void clearAndResizeStorageToDim() const;
         bool isStorageEmpty() const;
         bool isMatrixEmpty() const;
-        void transferToDevice(const std::vector<index> &rowOffsets, const std::vector<index> &colIndices);
+        void transferToDevice(const std::vector<index> &rowOffsets, const std::vector<index> &colIndices) const;
         void transferFromDevice(std::vector<index> &rowOffsets, std::vector<index> &colIndices) const;
 
         // Uses nsparse csr matrix implementation as a backend

cubool/tests/test_matrix_misc.cpp

@@ -23,6 +23,7 @@
 /**********************************************************************************/
 
 #include <testing/testing.hpp>
+#include <cstring>
 
 TEST(cuBool_Matrix, Duplicate) {
     cuBool_Matrix matrix = nullptr, duplicated = nullptr;
@@ -98,4 +99,55 @@ TEST(cuBool_Matrix, ExtractPairs) {
     ASSERT_EQ(cuBool_Finalize(), CUBOOL_STATUS_SUCCESS);
 }
 
+TEST(cuBool_Matrix, Marker) {
+    cuBool_Matrix matrix = nullptr;
+    cuBool_Index m, n;
+
+    m = n = 100;
+
+    const cuBool_Index BUFFER_SIZE = 100;
+    const char* marker = "Test Matrix Marker";
+    cuBool_Index size = 0;
+    char buffer[BUFFER_SIZE];
+
+    ASSERT_EQ(cuBool_Initialize(CUBOOL_HINT_NO), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_New(&matrix, m, n), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_SetMarker(matrix, marker), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_Marker(matrix, nullptr, &size), CUBOOL_STATUS_SUCCESS);
+    ASSERT_LE(size, BUFFER_SIZE);
+    ASSERT_EQ(cuBool_Matrix_Marker(matrix, buffer, &size), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_Free(matrix), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Finalize(), CUBOOL_STATUS_SUCCESS);
+
+    ASSERT_EQ(std::strlen(buffer), size - 1);
+    ASSERT_LE(std::strcmp(marker, buffer), 0);
+
+    std::cout << "Source marker: " << marker << std::endl;
+    std::cout << "Returned marker: " << buffer << std::endl;
+}
+
+TEST(cuBool_Matrix, MarkerShort) {
+    cuBool_Matrix matrix = nullptr;
+    cuBool_Index m, n;
+
+    m = n = 100;
+
+    const cuBool_Index BUFFER_SIZE = 10;
+    const char* marker = "Test Matrix Marker";
+    cuBool_Index size = BUFFER_SIZE;
+    char buffer[BUFFER_SIZE];
+
+    ASSERT_EQ(cuBool_Initialize(CUBOOL_HINT_NO), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_New(&matrix, m, n), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_SetMarker(matrix, marker), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_Marker(matrix, buffer, &size), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Matrix_Free(matrix), CUBOOL_STATUS_SUCCESS);
+    ASSERT_EQ(cuBool_Finalize(), CUBOOL_STATUS_SUCCESS);
+
+    ASSERT_GE(std::strcmp(marker, buffer), 0);
+
+    std::cout << "Source marker: " << marker << std::endl;
+    std::cout << "Returned marker: " << buffer << std::endl;
+}
+
 CUBOOL_GTEST_MAIN