[Code] Update:

- Add set element c api and expose it into python
- Add more doc intp python
- Minor readme fixes

Author: EgorOrachyov

README.md

@@ -5,6 +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/pip-cybool-%233776ab)](https://test.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 
@@ -36,6 +37,7 @@ prototyping algorithms on a local computer for later running on a powerful serve
 - [X] CSR submatrix
 - [X] CSR matrix reduce
 - [X] CSR slicing
+- [ ] Matrix cached filling
 - [X] Sequential fallback backend for CPU
 - [X] Device capabilities query
 - [ ] IO matrix loading from mtx file
@@ -206,7 +208,7 @@ wrapper can be used to compute the same transitive closure problem for the
 directed graph within python environment:
 
 ```python
-from python import pycubool
+import pycubool
 
 def transitive_closure(a: pycubool.Matrix):
     """

cubool/CMakeLists.txt

@@ -23,7 +23,9 @@ set(CUBOOL_SOURCES
     sources/core/matrix.cpp
     sources/core/matrix.hpp
     sources/io/logger.cpp
-    sources/io/logger.hpp)
+    sources/io/logger.hpp
+    sources/utils/exclusive_scan.hpp
+        )
 
 set(CUBOOL_C_API_SOURCES
     include/cubool/cubool.h
@@ -36,6 +38,7 @@ set(CUBOOL_C_API_SOURCES
     sources/cuBool_SetupLogger.cpp
     sources/cuBool_Matrix_New.cpp
     sources/cuBool_Matrix_Build.cpp
+    sources/cuBool_Matrix_SetElement.cpp
     sources/cuBool_Matrix_ExtractPairs.cpp
     sources/cuBool_Matrix_ExtractSubMatrix.cpp
     sources/cuBool_Matrix_Duplicate.cpp
@@ -101,8 +104,7 @@ if (CUBOOL_WITH_SEQUENTIAL)
         sources/sequential/sq_reduce.cpp
         sources/sequential/sq_reduce.hpp
         sources/sequential/sq_submatrix.cpp
-        sources/sequential/sq_submatrix.hpp
-        sources/sequential/sq_exclusive_scan.hpp)
+        sources/sequential/sq_submatrix.hpp)
 endif()
 
 # Shared library object config

cubool/include/cubool/cubool.h

@@ -90,6 +90,8 @@ typedef enum cuBool_Hint {
     CUBOOL_HINT_LOG_WARNING = 0x64,
     /** Logging hint: log all messages */
     CUBOOL_HINT_LOG_ALL = 0x128,
+    /** No duplicates in the build data */
+    CUBOOL_HINT_NO_DUPLICATES = 0x256
 } cuBool_Hint;
 
 /** Hit mask */
@@ -225,7 +227,9 @@ CUBOOL_EXPORT CUBOOL_API cuBool_Status cuBool_Matrix_New(
  * Build sparse matrix from provided pairs array. Pairs are supposed to be stored
  * as (rows[i],cols[i]) for pair with i-th index.
  *
+ * @note This function automatically reduces duplicates
  * @note Pass CUBOOL_HINT_VALUES_SORTED if values already in the row-col order.
+ * @note Pass CUBOOL_HINT_NO_DUPLICATES if values has no duplicates
  *
  * @param matrix Matrix handle to perform operation on
  * @param rows Array of pairs row indices
@@ -243,6 +247,23 @@ CUBOOL_EXPORT CUBOOL_API cuBool_Status cuBool_Matrix_Build(
     cuBool_Hints hints
 );
 
+/**
+ * Sets specified (i, j) value of the matrix to True.
+ *
+ * @note This function automatically reduces duplicates
+ *
+ * @param matrix Matrix handle to perform operation on
+ * @param i Row index
+ * @param j Column Index
+ *
+ * @return Error code on this operation
+ */
+CUBOOL_EXPORT CUBOOL_API cuBool_Status cuBool_Matrix_SetElement(
+    cuBool_Matrix matrix,
+    cuBool_Index i,
+    cuBool_Index j
+);
+
 /**
  * Reads matrix data to the host visible CPU buffer as an array of values pair.
  *

cubool/sources/backend/matrix_base.hpp

@@ -37,7 +37,8 @@ namespace cubool {
     public:
         virtual ~MatrixBase() = default;
 
-        virtual void build(const index *rows, const index *cols, size_t nvals, bool isSorted) = 0;
+        virtual void setElement(index i, index j) = 0;
+        virtual void build(const index *rows, const index *cols, size_t nvals, bool isSorted, bool hasDuplicates) = 0;
         virtual void extract(index* rows, index* cols, size_t &nvals) = 0;
         virtual void extractSubMatrix(const MatrixBase& otherBase, index i, index j, index nrows, index ncols) = 0;
 

cubool/sources/core/library.cpp

@@ -45,7 +45,7 @@
 namespace cubool {
 
     std::unordered_set<class MatrixBase*> Library::mAllocated;
-    BackendBase* Library::mBackend = nullptr;
+    std::shared_ptr<class BackendBase> Library::mBackend = nullptr;
     std::shared_ptr<class Logger>  Library::mLogger = std::make_shared<DummyLogger>();
     bool Library::mRelaxedRelease = false;
 
@@ -57,75 +57,61 @@ namespace cubool {
         // If user do not force the cpu backend usage
         if (!preferCpu) {
 #ifdef CUBOOL_WITH_CUDA
-            mBackend = new CudaBackend();
+            mBackend = std::make_shared<CudaBackend>();
             mBackend->initialize(initHints);
 
             // Failed to setup cuda, release backend and go to try cpu
             if (!mBackend->isInitialized()) {
-                delete mBackend;
                 mBackend = nullptr;
-
                 mLogger->logWarning("Failed to initialize Cuda backend");
             }
 #endif
         }
 
 #ifdef CUBOOL_WITH_SEQUENTIAL
         if (mBackend == nullptr) {
-            mBackend = new SqBackend();
+            mBackend = std::make_shared<SqBackend>();
             mBackend->initialize(initHints);
 
             // Failed somehow setup
             if (!mBackend->isInitialized()) {
-                delete mBackend;
                 mBackend = nullptr;
-
                 mLogger->logWarning("Failed to initialize Cpu fallback backend");
             }
         }
 #endif
 
         CHECK_RAISE_ERROR(mBackend != nullptr, BackendError, "Failed to select backend");
-        mRelaxedRelease = initHints & CUBOOL_HINT_RELAXED_FINALIZE;
-
-        // Log device caps
-        cuBool_DeviceCaps caps;
-        queryCapabilities(caps);
 
-        std::stringstream ss;
-
-        if (caps.cudaSupported) {
-            ss << "Cuda device capabilities" << std::endl
-               << " name: " << caps.name << std::endl
-               << " major: " << caps.major << std::endl
-               << " minor: " << caps.minor << std::endl
-               << " warp size: " << caps.warp << std::endl
-               << " globalMemoryKiBs: " << caps.globalMemoryKiBs << std::endl
-               << " sharedMemoryPerMultiProcKiBs: " << caps.sharedMemoryPerMultiProcKiBs << std::endl
-               << " sharedMemoryPerBlockKiBs: " << caps.sharedMemoryPerBlockKiBs << std::endl;
-        }
-        else {
-            ss << "Cuda device is not presented";
-        }
-
-        mLogger->logInfo(ss.str());
+        // If initialized, post-init actions
+        mRelaxedRelease = initHints & CUBOOL_HINT_RELAXED_FINALIZE;
+        logDeviceInfo();
     }
 
     void Library::finalize() {
         if (mBackend) {
             // Release all allocated resources implicitly
             if (mRelaxedRelease) {
                 for (auto m: mAllocated) {
+                    std::stringstream s;
+                    s << "Implicitly release matrix instance " << m;
+
+                    mLogger->logWarning(s.str());
                     delete m;
                 }
 
                 mAllocated.clear();
             }
 
+            // Some final message
+            mLogger->logInfo("** cuBool:Finalize backend **");
+
             // Remember to finalize backend
             mBackend->finalize();
-            delete mBackend;
             mBackend = nullptr;
+
+            // Release (possibly setup text logger) logger, reassign dummy
+            mLogger = std::make_shared<DummyLogger>();
         }
     }
 
@@ -179,14 +165,18 @@ namespace cubool {
                     file << "Level::Always";
             }
             file << std::setw(-1) << "] ";
-            file << message << std::endl <<  std::endl;
+            file << message << std::endl;
         });
 
         // Assign new text logger
         mLogger = textLogger;
 
         // Initial message
         mLogger->logInfo("*** cuBool::Logger file ***");
+
+        // Also log device capabilities
+        if (isBackedInitialized())
+            logDeviceInfo();
     }
 
     MatrixBase *Library::createMatrix(size_t nrows, size_t ncols) {
@@ -222,6 +212,34 @@ namespace cubool {
         mBackend->queryCapabilities(caps);
     }
 
+    void Library::logDeviceInfo() {
+        // Log device caps
+        cuBool_DeviceCaps caps;
+        queryCapabilities(caps);
+
+        std::stringstream ss;
+
+        if (caps.cudaSupported) {
+            ss << "Cuda device capabilities" << std::endl
+               << " name: " << caps.name << std::endl
+               << " major: " << caps.major << std::endl
+               << " minor: " << caps.minor << std::endl
+               << " warp size: " << caps.warp << std::endl
+               << " globalMemoryKiBs: " << caps.globalMemoryKiBs << std::endl
+               << " sharedMemoryPerMultiProcKiBs: " << caps.sharedMemoryPerMultiProcKiBs << std::endl
+               << " sharedMemoryPerBlockKiBs: " << caps.sharedMemoryPerBlockKiBs << std::endl;
+        }
+        else {
+            ss << "Cuda device is not presented";
+        }
+
+        mLogger->logInfo(ss.str());
+    }
+
+    bool Library::isBackedInitialized() {
+        return mBackend != nullptr;
+    }
+
     class Logger * Library::getLogger() {
         return mLogger.get();
     }

cubool/sources/core/library.hpp

@@ -42,11 +42,13 @@ namespace cubool {
         static void releaseMatrix(class MatrixBase *matrixBase);
         static void handleError(const std::exception& error);
         static void queryCapabilities(cuBool_DeviceCaps& caps);
+        static void logDeviceInfo();
+        static bool isBackedInitialized();
         static class Logger* getLogger();
 
     private:
         static std::unordered_set<class MatrixBase*> mAllocated;
-        static class BackendBase* mBackend;
+        static std::shared_ptr<class BackendBase> mBackend;
         static std::shared_ptr<class Logger> mLogger;
         static bool mRelaxedRelease;
     };