[Project/Code] Graph Viz:

- Bug fixes for python gviz
- Add gviz matrices export function
- Update readme/python readme
- Add more pycubool examples

Author: EgorOrachyov

CMakeLists.txt

@@ -2,7 +2,7 @@
 # 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)

README.md

@@ -45,27 +45,48 @@ 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
+- [X] Code examples
 - [ ] User guide
 - [X] Unit Tests collection
-- [ ] Publish built artifacts and shared libs
+- [X] Publish built artifacts and shared libs
 - [ ] 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
 ``` 
@@ -77,11 +98,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 +258,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 +317,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,

docs/pictures/gviz_example.png

@@ -29,43 +29,139 @@ 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.   
 
-## Sparse Boolean Matrix Features
+## Features
 
 - Matrix creation (empty, from data, with random data)
 - Matrix-matrix operations (multiplication, element-wise addition, kronecker product)
 - Matrix operations (equality, transpose, reduce to vector, extract sub-matrix)
 - Matrix data extraction (as lists, as list of pairs)
 - Matrix syntax sugar (pretty string printing, slicing, iterating through non-zero values)
 - IO (import/export matrix from/to `.mtx` file format)
+- GraphViz (export single matrix or set of matrices as a graph with custom color and label settings)
 - Debug (matrix string debug markers, logging)
 
-## Example
+## Simple example
 
-The following Python code snippet demonstrates, how the **pycubool**
-wrapper can be used to compute the transitive closure problem for the
-directed graph within python environment:
+Create sparse matrices, compute matrix-matrix product and print the result to the output:
 
 ```python
-import pycubool
+import pycubool as cb
 
-def transitive_closure(a: pycubool.Matrix):
-    """
-    Evaluates transitive closure for the provided
-    adjacency matrix of the graph.
+a = cb.Matrix.empty(shape=(2, 3))
+a[0, 0] = True
+a[1, 2] = True
 
-    :param a: Adjacency matrix of the graph
-    :return: The transitive closure adjacency matrix
-    """
+b = cb.Matrix.empty(shape=(3, 4))
+b[0, 1] = True
+b[0, 2] = True
+b[1, 3] = True
+b[2, 1] = True
 
-    t = a.dup()                           # Duplicate matrix where to store result
-    total = 0                             # Current number of values
+print(a, b, a.mxm(b), sep="\n")
+```
+
+Output:
+
+```
+        0   1   2 
+  0 |   1   .   . |   0
+  1 |   .   .   1 |   1
+        0   1   2 
+
+        0   1   2   3 
+  0 |   .   1   1   . |   0
+  1 |   .   .   .   1 |   1
+  2 |   .   1   .   . |   2
+        0   1   2   3 
+
+        0   1   2   3 
+  0 |   .   1   1   . |   0
+  1 |   .   1   .   . |   1
+        0   1   2   3
+```
+
+## Transitive closure example
+
+Compute the transitive closure problem for the directed graph and print the result:
+
+```python
+import pycubool as cb
+
+a = cb.Matrix.empty(shape=(4, 4))
+a[0, 1] = True
+a[1, 2] = True
+a[2, 0] = True
+a[2, 3] = True
+a[3, 2] = True
+
+t = a.dup()                             # Duplicate matrix where to store result
+total = 0                               # Current number of values
+
+while total != t.nvals:
+    total = t.nvals
+    t.mxm(t, out=t, accumulate=True)    # t += t * t
 
-    while total != t.nvals:
-        total = t.nvals
-        t.mxm(t, out=t, accumulate=True)  # t += t * t
+print(a, t, sep="\n")
+```
+
+Output:
 
-    return t
 ```
+        0   1   2   3 
+  0 |   .   1   .   . |   0
+  1 |   .   .   1   . |   1
+  2 |   1   .   .   1 |   2
+  3 |   .   .   1   . |   3
+        0   1   2   3 
+
+        0   1   2   3 
+  0 |   1   1   1   1 |   0
+  1 |   1   1   1   1 |   1
+  2 |   1   1   1   1 |   2
+  3 |   1   1   1   1 |   3
+        0   1   2   3
+```
+
+## GraphViz example
+
+Generate GraphViz graph script for a graph stored as a set of adjacency matrices:
+
+```python
+import pycubool as cb
+
+name = "Test"                           # Displayed graph name   
+shape = (4, 4)                          # Adjacency matrices shape
+colors = {"a": "red", "b": "green"}     # Colors per label
+
+a = cb.Matrix.empty(shape=shape)        # Edges labeled as 'a'
+a[0, 1] = True
+a[1, 2] = True
+a[2, 0] = True
+
+b = cb.Matrix.empty(shape=shape)        # Edges labeled as 'b'
+b[2, 3] = True
+b[3, 2] = True
+
+print(cb.matrices_to_gviz(matrices={"a": a, "b": b}, graph_name=name, edge_colors=colors))
+```
+
+Output:
+
+```
+digraph G {
+    graph [label=Test];
+    node [color=black];
+    0 -> 1 [label=a,color=red];
+    1 -> 2 [label=a,color=red];
+    2 -> 0 [label=a,color=red];
+    2 -> 3 [label=b,color=green];
+    3 -> 2 [label=b,color=green];
+}
+```
+
+As an image:
+
+![gviz-example](https://raw.githubusercontent.com/JetBrains-Research/cuBool/master/docs/pictures/gviz_example.png)
 
 ## Contributors
 

python/README.md

@@ -0,0 +1,59 @@
+import pycubool as cb
+
+#
+# Basic setup example
+#
+
+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")
+
+#
+# Transitive closure example
+#
+
+a = cb.Matrix.empty(shape=(4, 4))
+a[0, 1] = True
+a[1, 2] = True
+a[2, 0] = True
+a[2, 3] = True
+a[3, 2] = True
+
+t = a.dup()                             # Duplicate matrix where to store result
+total = 0                               # Current number of values
+
+while total != t.nvals:
+    total = t.nvals
+    t.mxm(t, out=t, accumulate=True)    # t += t * t
+
+print(a, t, sep="\n")
+
+#
+# Export matrices set to graph viz graph
+#
+
+name = "Test"                           # Displayed graph name
+shape = (4, 4)                          # Adjacency matrices shape
+colors = {"a": "red", "b": "green"}     # Colors per label
+
+a = cb.Matrix.empty(shape=shape)        # Edges labeled as 'a'
+a[0, 1] = True
+a[1, 2] = True
+a[2, 0] = True
+
+b = cb.Matrix.empty(shape=shape)        # Edges labeled as 'b'
+b[2, 3] = True
+b[3, 2] = True
+
+print(cb.matrices_to_gviz(matrices={"a": a, "b": b}, graph_name=name, edge_colors=colors))
+
+
+