{"id":22001730,"url":"https://github.com/sparselinearalgebra/cubool","last_synced_at":"2026-03-08T21:38:55.415Z","repository":{"id":49605623,"uuid":"300269874","full_name":"SparseLinearAlgebra/cuBool","owner":"SparseLinearAlgebra","description":"Sparse linear Boolean algebra for Nvidia Cuda","archived":false,"fork":false,"pushed_at":"2025-04-21T10:33:50.000Z","size":40654,"stargazers_count":24,"open_issues_count":4,"forks_count":4,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-21T10:40:39.413Z","etag":null,"topics":["boolean-algebra","cplusplus","graph-algorithms","graph-analysis","graphblas","linear-algebra","nvidia-cuda","python","sparse-matrix"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pycubool/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SparseLinearAlgebra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-01T12:23:06.000Z","updated_at":"2025-01-30T03:18:39.000Z","dependencies_parsed_at":"2025-04-10T17:55:52.033Z","dependency_job_id":null,"html_url":"https://github.com/SparseLinearAlgebra/cuBool","commit_stats":null,"previous_names":["jetbrains-research/cubool"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparseLinearAlgebra%2FcuBool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparseLinearAlgebra%2FcuBool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparseLinearAlgebra%2FcuBool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SparseLinearAlgebra%2FcuBool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SparseLinearAlgebra","download_url":"https://codeload.github.com/SparseLinearAlgebra/cuBool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251860906,"owners_count":21655818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boolean-algebra","cplusplus","graph-algorithms","graph-analysis","graphblas","linear-algebra","nvidia-cuda","python","sparse-matrix"],"created_at":"2024-11-29T23:14:53.680Z","updated_at":"2026-03-08T21:38:55.407Z","avatar_url":"https://github.com/SparseLinearAlgebra.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Project logo](https://github.com/JetBrains-Research/cuBool/blob/master/docs/logo/cubool_logo_trsp.png?raw=true)\n\n# cuBool\n\n[![JB Research](https://jb.gg/badges/research-flat-square.svg)](https://research.jetbrains.org/)\n[![Ubuntu](https://github.com/JetBrains-Research/cuBool/workflows/Ubuntu/badge.svg?branch=master)](https://github.com/JetBrains-Research/cuBool/actions)\n[![License](https://img.shields.io/badge/license-MIT-orange)](https://github.com/JetBrains-Research/cuBool/blob/master/LICENSE)\n[![Package](https://img.shields.io/badge/pypi%20package-1.2.0-%233776ab)](https://pypi.org/project/pycubool/)\n\n**cuBool** is a linear Boolean algebra library primitives and operations for \nwork with sparse matrices written on the NVIDIA CUDA platform. The primary \ngoal of the library is implementation, testing and profiling algorithms for\nsolving *formal-language-constrained problems*, such as *context-free* \nand *regular* path queries with various semantics for graph databases.\nThe library provides C-compatible API, written in the GraphBLAS style.\n\n**The library** is shipped with python package **pycubool** - wrapper for\ncuBool library C API. This package exports library features and primitives \nin high-level format with automated resources management and fancy syntax sugar.\n\n**The primary library primitives** are sparse matrix and sparse vector of boolean values. \nThe library provides the most popular operations for matrix manipulation, \nsuch as construction from values, transpose, sub-matrix/sub-vector extraction, matrix-to-vector reduce, \nelement-wise addition, matrix-matrix, matrix-vector, vector-matrix multiplication, and Kronecker product.  \n\n**As a fallback** library provides sequential backend for mentioned above operations\nfor computations on CPU side only. This backend is selected automatically\nif Cuda compatible device is not presented in the system. This can be quite handy for \nprototyping algorithms on a local computer for later running on a powerful server.   \n\n**PyPI package web page** is following [link](https://pypi.org/project/pycubool/).\n\n### Features summary\n\n- C API for performance-critical computations\n- Python package for every-day tasks\n- Cuda backend for computations\n- Cpu backend for computations\n- Matrix/vector creation (empty, from data, with random data)\n- Matrix-matrix operations (multiplication, element-wise addition, element-wise multiplication, kronecker product)\n- Matrix-vector operations (matrix-vector and vector-matrix multiplication)\n- Vector-vector operations (element-wise addition, element-wise multiplication)\n- Matrix operations (equality, transpose, reduce to vector, extract sub-matrix)\n- Vector operations (equality, reduce to value, extract sub-vector)\n- Matrix/vector data extraction (as lists, as list of pairs)\n- Matrix/vector syntax sugar (pretty string printing, slicing, iterating through non-zero values)\n- IO (import/export matrix from/to `.mtx` file format)\n- GraphViz (export single matrix or set of matrices as a graph with custom color and label settings)\n- Debug (matrix string debug markers, logging) \n\n### Platforms\n\n- Linux-based OS (tested on Ubuntu 20.04)\n- Windows (coming soon)\n- macOS (coming soon)\n\n### Simple example\n\nCreate sparse matrices, compute matrix-matrix product and print the result to the output:\n\n```python\nimport pycubool as cb\n\na = cb.Matrix.empty(shape=(2, 3))\na[0, 0] = True\na[1, 2] = True\n\nb = cb.Matrix.empty(shape=(3, 4))\nb[0, 1] = True\nb[0, 2] = True\nb[1, 3] = True\nb[2, 1] = True\n\nprint(a, b, a.mxm(b), sep=\"\\n\")\n```\n\n### Performance\n\nSparse Boolean matrix-matrix multiplication evaluation results are listed bellow.\nMachine configuration: PC with Ubuntu 20.04, Intel Core i7-6700 3.40GHz CPU, DDR4 64Gb RAM, GeForce GTX 1070 GPU with 8Gb VRAM. \n\n![time](https://github.com/JetBrains-Research/cuBool/raw/master/docs/pictures/mxm-perf-time.svg?raw=true\u0026sanitize=true)\n![mem](https://github.com/JetBrains-Research/cuBool/raw/master/docs/pictures/mxm-perf-mem.svg?raw=true\u0026sanitize=true)\n\nThe matrix data is selected from the SuiteSparse Matrix Collection [link](https://sparse.tamu.edu).\n\n| Matrix name              | # Rows      | Nnz M       | Nnz/row   | Max Nnz/row | Nnz M^2     |\n|---                       |---:         |---:         |---:       |---:         |---:         |\n| SNAP/amazon0312          | 400,727     | 3,200,440   | 7.9       | 10          | 14,390,544  |\n| LAW/amazon-2008          | 735,323     | 5,158,388   | 7.0       | 10          | 25,366,745  |\n| SNAP/web-Google          | 916,428     | 5,105,039   | 5.5       | 456         | 29,710,164  |\n| SNAP/roadNet-PA          | 1,090,920   | 3,083,796   | 2.8       | 9           | 7,238,920   |\n| SNAP/roadNet-TX\t       | 1,393,383   | 3,843,320   | 2.7       | 12          | 8,903,897   |\n| SNAP/roadNet-CA\t       | 1,971,281   | 5,533,214   | 2.8       | 12          | 12,908,450  |\n| DIMACS10/netherlands_osm | 2,216,688   | 4,882,476   | 2.2       | 7           | 8,755,758   |\n  \nDetailed comparison is available in the full paper text at \n[link](https://github.com/YaccConstructor/articles/blob/master/2021/GRAPL/Sparse_Boolean_Algebra_on_GPGPU/Sparse_Boolean_Algebra_on_GPGPU.pdf).\n\n### Installation\n\nIf you are running **Linux-based** OS (tested on Ubuntu 20.04) you can download the official\nPyPI **pycubool** python package, which includes compiled library source code\nwith Cuda and Sequential computations support. Installation process \nrequires only `python3` to be installed on your machine. Python can be installed \nas follows [link](https://phoenixnap.com/kb/how-to-install-python-3-ubuntu).\n\nIf all requirements are satisfied, run the following command to install PyPI package:\n\n```shell script\n$ python3 -m pip install pycubool\n``` \n\n### Documentation\n\nThe following links give a brief start guide for new users:\n\n- [C API example](https://github.com/JetBrains-Research/cuBool/blob/master/docs/examples/transitive_closure_cpp.md) - complete C++ application to compute transitive closure of an example graph\n- [Python API usage](https://github.com/JetBrains-Research/cuBool/blob/master/docs/examples/python_examples.md) - complete and detailed set of the python API usage examples for all lib features  \n\n## Getting started\n\nThis section gives instructions to build the library from sources.\nThese steps are required if you want to build library for your specific platform with custom build settings.\n\n### Requirements\n\n- Linux-based OS (tested on Ubuntu 20.04)\n- CMake Version 3.15 or higher\n- CUDA Compatible GPU device (to run Cuda computations)\n- GCC Compiler \n- NVIDIA CUDA toolkit (to build Cuda backend)\n- Python 3 (for `pycubool` library)\n- Git (to get source code)\n\n### Cuda \u0026 compiler setup\n\n\u003e Skip this section if you want to build library with only sequential backend\n\u003e without cuda backend support.\n\nBefore the CUDA setup process, validate your system NVIDIA driver with `nvidia-smi`\ncommand. Install required driver via `ubuntu-drivers devices` and \n`apt install \u003cdriver\u003e` commands respectively.\n\nThe following commands grubs the required GCC compilers for the CC and CXX compiling \nrespectively. CUDA toolkit, shipped in the default Ubuntu package manager, has version \nnumber 10 and supports only GCC of the version 8.4 or less.  \n\n```shell script\n$ sudo apt update\n$ sudo apt install gcc-8 g++-8\n$ sudo apt install nvidia-cuda-toolkit\n$ sudo apt install nvidia-cuda-dev \n$ nvcc --version\n```\n\nIf everything successfully installed, the last version command will output \nsomething like this:\n\n```shell script\n$ nvcc: NVIDIA (R) Cuda compiler driver\n$ Copyright (c) 2005-2019 NVIDIA Corporation\n$ Built on Sun_Jul_28_19:07:16_PDT_2019\n$ Cuda compilation tools, release 10.1, V10.1.243\n```\n\n**Bonus Step:** In order to have CUDA support in the CLion IDE, you will have to\noverwrite global alias for the `gcc` and `g++` compilers:\n\n```shell script\n$ sudo rm /usr/bin/gcc\n$ sudo rm /usr/bin/g++\n$ sudo ln -s /usr/bin/gcc-8 /usr/bin/gcc\n$ sudo ln -s /usr/bin/g++-8 /usr/bin/g++\n```\n\nThis step can be easily undone by removing old aliases and creating new one \nfor the desired gcc version on your machine. Also you can safely omit this step\nif you want to build library from the command line only. \n\n**Useful links:**\n- [NVIDIA Drivers installation Ubuntu](https://linuxconfig.org/how-to-install-the-nvidia-drivers-on-ubuntu-20-04-focal-fossa-linux)\n- [CUDA Linux installation guide](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html)\n- [CUDA Hello world program](https://developer.nvidia.com/blog/easy-introduction-cuda-c-and-c/)\n- [CUDA CMake tutorial](https://developer.nvidia.com/blog/building-cuda-applications-cmake/)\n\n### Get the source code and run\n\nRun the following commands in the command shell to download the repository,\nmake `build` directory, configure `cmake build` and run compilation process.\nFirst of all, get the source code and project dependencies:\n\n```shell script\n$ git clone https://github.com/JetBrains-Research/cuBool.git\n$ cd cuBool\n$ git submodule update --init --recursive\n```\n\nMake the build directory and go into it:\n\n```shell script\n$ mkdir build\n$ cd build\n```\n\nConfigure build in Release mode with tests and run actual compilation process:\n\n```shell script\n$ cmake .. -DCMAKE_BUILD_TYPE=Release -DCUBOOL_BUILD_TESTS=ON\n$ cmake --build . --target all -j `nproc`\n$ bash ./scripts/run_tests_all.sh\n```\n\nBy default, the following cmake options will be automatically enabled:\n\n- `CUBOOL_WITH_CUDA` - build library with actual cuda backend\n- `CUBOOL_WITH_SEQUENTIAL` - build library with cpu based backend\n- `CUBOOL_WITH_TESTS` - build library unit-tests collection\n\n\u003e Note: in order to provide correct GCC version for CUDA sources compiling,\n\u003e you will have to provide custom paths to the CC and CXX compilers before \n\u003e the actual compilation process as follows:\n\u003e\n\u003e ```shell script\n\u003e $ export CC=/usr/bin/gcc-8\n\u003e $ export CXX=/usr/bin/g++-8\n\u003e $ export CUDAHOSTCXX=/usr/bin/g++-8\n\u003e ```\n\n### Python wrapper\n\n**Export** env variable `PYTHONPATH=\"/build_dir_path/python/:$PYTHONPATH\"` if\nyou want to use `pycubool` without installation into default python packages dir.\nThis variable will help python find package if you import it as `import pycubool` in your python scripts.\n\n**To run regression tests** within your build directory, open folder `/build_dir_path/python` and\nrun the following command:\n\n```shell script\n$ export PYTHONPATH=\"`pwd`:$PYTHONPATH\"\n$ cd tests\n$ python3 -m unittest discover -v\n```\n\n**Note:** after the build process, the shared library object will be placed\ninside the build directory in the folder with python wrapper `python/pycubool/`. \nSo, the wrapper will be able to automatically locate required lib file.\n\n### Python package runtime config\n\n**Pycubool** Python-package can be configured before import by the following environment variables: \n\n- `CUBOOL_PATH` - custom path to compiled cubool library object. \nWithout that variable by default the package will try to find library in the package folder.\n\n- `CUBOOL_BACKEND` - allows to select backend for execution. \nBy default library selects cuda if present. Pass value `cpu` to force cpu computations,\neven if cuda backend is presented and supported for selection.\n\n- `CUBOOL_MEM` - type of the memory to use if run computations in cuda backend.\nBy default library uses device memory. If pass in the variable value `managed`, then\nbackend will be configured to use cuda managed memory for resources allocation.\n\n## Usage \n\nThe following C++ code snipped demonstrates, how library functions and\nprimitives can be used for the transitive closure evaluation of the directed\ngraph, represented as an adjacency matrix with boolean values. The transitive\nclosure provides info about reachable vertices in the graph:\n\n```c++\n/**\n * Performs transitive closure for directed graph\n *\n * @param A Adjacency matrix of the graph\n * @param T Reference to the handle where to allocate and store result\n *\n * @return Status on this operation\n */\ncuBool_Status TransitiveClosure(cuBool_Matrix A, cuBool_Matrix* T) {\n    cuBool_Matrix_Duplicate(A, T);                       /* Duplicate A to result T */\n\n    cuBool_Index total = 0;\n    cuBool_Index current;\n\n    cuBool_Matrix_Nvals(*T, \u0026current);                   /* Query current nvals value */\n\n    while (current != total) {                           /* Iterate, while new values are added */\n        total = current;\n        cuBool_MxM(*T, *T, *T, CUBOOL_HINT_ACCUMULATE);  /* T += T x T */\n        cuBool_Matrix_Nvals(*T, \u0026current);\n    }\n\n    return CUBOOL_STATUS_SUCCESS;\n}\n```\n\nThe following Python code snippet demonstrates, how the library python\nwrapper can be used to compute the same transitive closure problem for the\ndirected graph within python environment:\n\n```python\nimport pycubool as cb\n\ndef transitive_closure(a: cb.Matrix):\n    \"\"\"\n    Evaluates transitive closure for the provided\n    adjacency matrix of the graph.\n\n    :param a: Adjacency matrix of the graph\n    :return: The transitive closure adjacency matrix\n    \"\"\"\n\n    t = a.dup()                           # Duplicate matrix where to store result\n    total = 0                             # Current number of values\n\n    while total != t.nvals:\n        total = t.nvals\n        t.mxm(t, out=t, accumulate=True)  # t += t * t\n\n    return t\n```\n\n## Directory structure\n\n```\ncuBool\n├── .github - GitHub Actions CI setup \n├── docs - documents, text files and various helpful stuff\n├── scripts - short utility programs \n├── cubool - library core source code\n│   ├── include - library public C API \n│   ├── sources - source-code for implementation\n│   │   ├── core - library core and state management\n│   │   ├── io - logging and i/o stuff\n│   │   ├── utils - auxilary class shared among modules\n│   │   ├── backend - common interfaces\n│   │   ├── cuda - cuda backend\n│   │   └── sequential - fallback cpu backend\n│   ├── utils - testing utilities\n│   └── tests - gtest-based unit-tests collection\n├── python - pycubool related sources\n│   ├── pycubool - cubool library wrapper for python (similar to pygraphblas)\n│   ├── tests - regression tests for python wrapper\n│   ├── examples - short script files with python api usage examples\n│   └── data - generate data for pycubool regression tests\n├── deps - project dependencies\n│   ├── cub - cuda utility, required for nsparse\n│   ├── gtest - google test framework for unit testing\n│   ├── naive - GEMM implementation for squared dense boolean matrices\n│   ├── nsparse - SpGEMM implementation for csr matrices\n│   └── nsparse-um - SpGEMM implementation for csr matrices with unified memory (configurable)\n└── CMakeLists.txt - library cmake config, add this as sub-directory to your project\n```\n\n## Contributors\n\n- Egor Orachyov (Github: [EgorOrachyov](https://github.com/EgorOrachyov))\n- Pavel Alimov (Github : [Krekep](https://github.com/Krekep))\n- Semyon Grigorev (Github: [gsvgit](https://github.com/gsvgit))\n\n## Citation \n\n```ignorelang\n@MISC{cuBool,\n  author = {Orachyov, Egor and Alimov, Pavel and Grigorev, Semyon},\n  title = {cuBool: sparse Boolean linear algebra for Nvidia Cuda},\n  year = 2021,\n  url = {https://github.com/JetBrains-Research/cuBool},\n  note = {Version 1.2.0}\n}\n```\n\n## Algorithms\n\nIn this section listed all the related papers, which were used as an algorithmic foundation for \nimplementation of sparse linear boolean algebra operations (sparse matrix-matrix multiplication, \nsparse matrix-vector multiplication, sparse vector-matrix multiplication, matrix-matrix element-wise addition and etc.):\n\n- High-performance and Memory-saving Sparse General Matrix-Matrix Multiplication for NVIDIA Pascal GPU, \nYusuke Nagasaka, Akira Nukada, Satoshi Matsuoka\n- GPU Merge Path - A GPU Merging Algorithm, \nOded Green, Robert McColl, David A. Bader\n- Efficient Sparse Matrix-Vector Multiplication on GPUs using the CSR Storage Format, \nJoseph L. Greathouse, Mayank Daga\n- Atomic Reduction Based Sparse Matrix-Transpose Vector Multiplication on GPUs, \nYuan Tao, Yangdong Deng, Shuai Mu, Mingfa Zhu, Limin Xiao, Li Ruan, Zhibin Huang\n\n## License\n\nThis project is licensed under MIT License. License text can be found in the \n[license file](https://github.com/JetBrains-Research/cuBool/blob/master/LICENSE.md).\n\n## Acknowledgments\n\nThis is a research project of the Programming Languages and Tools Laboratory\nat JetBrains-Research. Laboratory website [link](https://research.jetbrains.org/groups/plt_lab/).\n\n## Also\n\nThe name of the library is formed by a combination of words *Cuda* and *Boolean*,\nwhat literally means *Cuda with Boolean* and sounds very similar to the name of \nthe programming language *COBOL*.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparselinearalgebra%2Fcubool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsparselinearalgebra%2Fcubool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsparselinearalgebra%2Fcubool/lists"}