[Python] Add docs for new matrix/vector classes methods with examples

Author: EgorOrachyov

python/features.py

@@ -111,6 +111,24 @@ def gen_matrix(size, seed):
 print(vals)
 print(a.equals(a))
 
+a = pycubool.Matrix.empty(shape=(4, 4))
+print(a.marker)
+a.set_marker("meow")
+print(a.marker)
+
+matrix = pycubool.Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+vector = pycubool.Vector.from_list(4, [0, 1, 2])
+print(matrix.mxv(vector))
+
+matrix = pycubool.Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+print(matrix.reduce_vector(), matrix.reduce_vector(transpose=True), sep="")
+
+matrix = pycubool.Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+print(matrix.extract_row(1))
+
+matrix = pycubool.Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+print(matrix.extract_col(1))
+
 matrix = pycubool.Matrix.generate(shape=(5, 4), density=0.5)
 print(matrix, matrix.extract_row(1), matrix.extract_col(2), sep="\n")
 
@@ -125,6 +143,58 @@ def gen_matrix(size, seed):
 matrix = pycubool.Matrix.generate(shape=(10, 6), density=0.2)
 print(matrix, matrix.reduce_vector(transpose=False), matrix.reduce_vector(transpose=True), sep="\n")
 
+vector = pycubool.Vector.from_list(4, [0, 1, 3], is_sorted=True, no_duplicates=True)
+print(vector)
+
+vector = pycubool.Vector.generate(nrows=4, density=0.5)
+print(vector)
+
+vector = pycubool.Vector.empty(4)
+vector.build([0, 1, 3], is_sorted=True, no_duplicates=True)
+print(vector)
+
+a = pycubool.Vector.from_list(4, [0, 1, 3], is_sorted=True, no_duplicates=True)
+b = a.dup()
+b[2] = True
+print(a, b, sep="")
+
+a = pycubool.Vector.empty(nrows=4)
+print(a.marker)
+a.set_marker("meow")
+print(a.marker)
+
+a = pycubool.Vector.empty(nrows=4)
+a[0] = True
+a[2] = True
+a[3] = True
+rows = a.to_list()
+print(list(rows))
+
+vector = pycubool.Vector.from_list(4, [0, 1, 3], is_sorted=True, no_duplicates=True)
+print(vector)
+
+vector = pycubool.Vector.from_list(5, [0, 1, 3])
+print(vector.extract_vector(1, nrows=3))
+
+matrix = pycubool.Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+vector = pycubool.Vector.from_list(5, [2, 3, 4])
+print(vector.vxm(matrix))
+
+a = pycubool.Vector.from_list(4, [0, 1, 3])
+b = pycubool.Vector.from_list(4, [1, 2, 3])
+print(a.ewiseadd(b))
+
+vector = pycubool.Vector.from_list(5, [2, 3, 4])
+print(vector.reduce())
 
+vector = pycubool.Vector.from_list(5, [1, 3, 4])
+print(list(iter(vector)))
 
+vector = pycubool.Vector.from_list(5, [1, 3, 4])
+print(vector[0:3], vector[2:], sep="")
 
+vector = pycubool.Vector.empty(4)
+vector[0] = True
+vector[2] = True
+vector[3] = True
+print(vector)

python/pycubool/matrix.py

@@ -77,7 +77,7 @@ def empty(cls, shape):
     @classmethod
     def from_lists(cls, shape, rows, cols, is_sorted=False, no_duplicates=False):
         """
-        Build matrix from provided `shape` and non-zero values data.
+        Create matrix from provided `shape` and non-zero values data.
 
         >>> matrix = Matrix.from_lists((4, 4), [0, 1, 2, 3], [0, 1, 2, 0], is_sorted=True, no_duplicates=True)
         >>> print(matrix)
@@ -260,7 +260,7 @@ def set_marker(self, marker: str):
         'meow (0x1a767b0)'
 
         :param marker: String marker to set
-        :return: None
+        :return:
         """
 
         assert marker is not None
@@ -492,6 +492,23 @@ def extract_matrix(self, i, j, shape, out=None, time_check=False):
         return out
 
     def extract_row(self, i, out=None):
+        """
+        Extract specified `self` matrix row as sparse vector.
+
+        >>> matrix = Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+        >>> print(matrix.extract_row(1))
+        '
+          0 |   . |   0
+          1 |   1 |   1
+          2 |   . |   2
+          3 |   . |   3
+        '
+
+        :param i: Row index to extract
+        :param out: Optional out vector to store result
+        :return: Return extracted row
+        """
+
         if out is None:
             out = vector.Vector.empty(self.ncols)
 
@@ -506,6 +523,24 @@ def extract_row(self, i, out=None):
         return out
 
     def extract_col(self, j, out=None):
+        """
+        Extract specified `self` matrix column as sparse vector.
+
+        >>> matrix = Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+        >>> print(matrix.extract_col(1))
+        '
+          0 |   . |   0
+          1 |   1 |   1
+          2 |   1 |   2
+          3 |   . |   3
+          4 |   . |   4
+        '
+
+        :param j: Column index to extract
+        :param out: Optional out vector to store result
+        :return: Return extracted column
+        """
+
         if out is None:
             out = vector.Vector.empty(self.nrows)
 
@@ -562,6 +597,29 @@ def mxm(self, other, out=None, accumulate=False, time_check=False):
         return out
 
     def mxv(self, other, out=None, time_check=False):
+        """
+        Matrix-vector multiply.
+
+        Multiply `this` matrix by column `other` vector `on the right`.
+        For row vector-matrix multiplication "on the left" see `Vector.vxm`.
+
+        >>> matrix = Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+        >>> vector = Vector.from_list(4, [0, 1, 2])
+        >>> print(matrix.mxv(vector))
+        '
+          0 |   1 |   0
+          1 |   1 |   1
+          2 |   1 |   2
+          3 |   . |   3
+          4 |   . |   4
+        '
+
+        :param other: Input matrix for multiplication
+        :param out: Optional out vector to store result
+        :param time_check: Pass True to measure and log elapsed time of the operation
+        :return: Vector-matrix multiplication result
+        """
+
         if out is None:
             out = vector.Vector.empty(self.nrows)
 
@@ -654,9 +712,9 @@ def ewiseadd(self, other, out=None, time_check=False):
         bridge.check(status)
         return out
 
-    def reduce(self, time_check=False):
+    def reduce(self, out=None, time_check=False):
         """
-        Reduce matrix to vector with boolean "+ = or" operation.
+        Reduce matrix to column matrix with boolean "+ = or" operation.
         Return `self` reduced matrix.
 
         >>> matrix = Matrix.from_lists((4, 4), [0, 1, 2, 2], [0, 1, 0, 2])
@@ -670,12 +728,14 @@ def reduce(self, time_check=False):
                   0
         '
 
+        :param out: Optional out matrix to store result
         :param time_check: Pass True to measure and log elapsed time of the operation
         :return: Reduced matrix (matrix with M x 1 shape)
         """
 
-        shape = (self.nrows, 1)
-        out = Matrix.empty(shape)
+        if out is None:
+            shape = (self.nrows, 1)
+            out = Matrix.empty(shape)
 
         status = wrapper.loaded_dll.cuBool_Matrix_Reduce2(
             out.hnd,
@@ -687,6 +747,31 @@ def reduce(self, time_check=False):
         return out
 
     def reduce_vector(self, out=None, transpose=False, time_check=False):
+        """
+        Reduce matrix to column vector with boolean "+ = or" operation.
+        Return `self` reduced matrix.
+
+        >>> matrix = Matrix.from_lists((5, 4), [0, 1, 2, 4], [0, 1, 1, 3])
+        >>> print(matrix.reduce_vector(), matrix.reduce_vector(transpose=True), sep="")
+        '
+          0 |   1 |   0
+          1 |   1 |   1
+          2 |   1 |   2
+          3 |   . |   3
+          4 |   1 |   4
+
+          0 |   1 |   0
+          1 |   1 |   1
+          2 |   . |   2
+          3 |   1 |   3
+        '
+
+        :param out: Optional out matrix to store result
+        :param transpose: Pass True to reduce matrix to row vector
+        :param time_check: Pass True to measure and log elapsed time of the operation
+        :return: Reduced matrix (matrix with M x 1 shape)
+        """
+
         if out is None:
             nrows = self.ncols if transpose else self.nrows
             out = vector.Vector.empty(nrows)
@@ -795,7 +880,7 @@ def __getitem__(self, item):
 
     def __setitem__(self, key, value):
         """
-        Sets Sets specified `key` = (i, j) value of the matrix to True.
+        Sets specified `key` = (i, j) value of the matrix to True.
 
         >>> matrix = Matrix.empty(shape=(4, 4))
         >>> matrix[0, 0] = True