gh-167: add examples in api docs

python/example.py

@@ -1,27 +1 @@
 from pyspla import *
-
-a = Array.from_list(dtype=INT, values=[-1, 0, 1])
-print(a)
-
-b = Array.generate(dtype=INT, shape=10, dist=(-10, 10))
-print(b)
-
-s = Scalar(value=10, dtype=INT)
-print(s)
-
-m = Vector.from_lists([0, 2, 5], [-1, 1, 1], shape=10, dtype=INT)
-t = Vector(shape=10, dtype=INT)
-t.assign(m, Scalar(INT, 10), INT.SECOND, INT.GEZERO)
-print(t.to_list())
-
-M = Matrix.generate((4, 4), INT, density=0.3, dist=[0, 10])
-print(M)
-
-M = Matrix.from_lists([1, 2, 3], [1, 2, 3], [-1, 5, 10], (4, 4), INT)
-print(M)
-
-v = Vector.generate(shape=4, dtype=INT, density=0.5, dist=[1, 10])
-print(v)
-
-v = Vector.from_lists([0, 1, 3], [-1, 7, 5], 4, INT)
-print(v)

python/pyspla/matrix.py

@@ -76,6 +76,17 @@ def __init__(self, shape, dtype=INT, hnd=None, label=None):
         """
         Creates new matrix of specified type and shape.
 
+        >>> M = Matrix((4, 5), INT)
+        >>> print(M)
+        '
+            0 1 2 3 4
+         0| . . . . .|  0
+         1| . . . . .|  1
+         2| . . . . .|  2
+         3| . . . . .|  3
+            0 1 2 3 4
+        '
+
         :param dtype: Type.
             Type parametrization of a storage.
 
@@ -112,27 +123,51 @@ def __init__(self, shape, dtype=INT, hnd=None, label=None):
     def dtype(self):
         """
         Type used for storage parametrization of this container.
+
+        >>> M = Matrix((4, 5), INT)
+        >>> print(M.dtype)
+        '
+            <class 'pyspla.type.INT'>
+        '
         """
         return self._dtype
 
     @property
     def n_rows(self):
         """
         Number of rows in the matrix.
+
+        >>> M = Matrix((4, 5), INT)
+        >>> print(M.n_rows)
+        '
+            4
+        '
         """
         return self._shape[0]
 
     @property
     def n_cols(self):
         """
         Number of cols in the matrix.
+
+        >>> M = Matrix((4, 5), INT)
+        >>> print(M.n_cols)
+        '
+            5
+        '
         """
         return self._shape[1]
 
     @property
     def shape(self):
         """
         2-Tuple with shape of matrix.
+
+        >>> M = Matrix((4, 5), INT)
+        >>> print(M.shape)
+        '
+            (4, 5)
+        '
         """
 
         return self._shape
@@ -155,6 +190,20 @@ def set(self, i, j, v):
         """
         Set value at specified index
 
+        >>> M = Matrix((4, 4), INT)
+        >>> M.set(0, 0, -1)
+        >>> M.set(1, 2, 4)
+        >>> M.set(3, 1, 10)
+        >>> print(M)
+        '
+            0 1 2 3
+         0|-1 . . .|  0
+         1| . . 4 .|  1
+         2| . . . .|  2
+         3| .10 . .|  3
+            0 1 2 3
+        '
+
         :param i: uint.
             Row index to set.
 
@@ -171,6 +220,18 @@ def get(self, i, j):
         """
         Get value at specified index.
 
+        >>> M = Matrix.from_lists([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2], (4, 4), INT)
+        >>> print(M.get(1, 0))
+        '
+            -1
+        '
+
+        >>> M = Matrix.from_lists([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2], (4, 4), INT)
+        >>> print(M.get(1, 3))
+        '
+            0
+        '
+
         :param i: uint.
             Row index of value to get.
 
@@ -226,6 +287,12 @@ def to_lists(self):
         """
         Read matrix data as a python lists of I, J and V.
 
+        >>> M = Matrix.from_lists([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2], (4, 4), INT)
+        >>> print(M.to_lists())
+        '
+            ([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2])
+        '
+
         :return: Tuple (List, List, List) with the matrix keys and matrix values.
         """
 
@@ -256,6 +323,12 @@ def to_list(self):
         """
         Read matrix data as a python lists of tuples where key and value stored together.
 
+        >>> M = Matrix.from_lists([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2], (4, 4), INT)
+        >>> print(M.to_list())
+        '
+            [(1, 0, -1), (2, 1, -4), (3, 0, 4), (3, 3, 2)]
+        '
+
         :return: List of matrix entries as (I, J, V).
         """
 
@@ -428,6 +501,12 @@ def reduce(self, op_reduce, out=None, init=None, desc=None):
         """
         Reduce matrix elements.
 
+        >>> M = Matrix.from_lists([1, 2, 3, 3], [0, 1, 0, 3], [-1, -4, 4, 2], (4, 4), INT)
+        >>> print(M.reduce(op_reduce=INT.MULT, init=Scalar(INT, 1)))
+        '
+            32
+        '
+
         :param op_reduce: OpBinary.
             Binary operation to apply for reduction of matrix elements.
 

python/pyspla/vector.py

@@ -76,6 +76,16 @@ def __init__(self, shape, dtype=INT, hnd=None, label=None):
         """
         Creates new vector of specified type and shape.
 
+        >>> v = Vector(5, INT)
+        >>> print(v)
+        '
+         0| .
+         1| .
+         2| .
+         3| .
+         4| .
+        '
+
         :param dtype: Type.
             Type parametrization of a storage.
 
@@ -109,20 +119,38 @@ def __init__(self, shape, dtype=INT, hnd=None, label=None):
     def dtype(self):
         """
         Type used for storage parametrization of this container.
+
+        >>> v = Vector(5, INT)
+        >>> print(v.dtype)
+        '
+            <class 'pyspla.type.INT'>
+        '
         """
         return self._dtype
 
     @property
     def n_rows(self):
         """
         Number of rows in the vector.
+
+        >>> v = Vector(5, INT)
+        >>> print(v.n_rows)
+        '
+            5
+        '
         """
         return self._shape[0]
 
     @property
     def shape(self):
         """
         2-Tuple with shape of vector where second value is always 1.
+
+        >>> v = Vector(5, INT)
+        >>> print(v.shape)
+        '
+            (5, 1)
+        '
         """
 
         return self._shape
@@ -145,6 +173,19 @@ def set(self, i, v):
         """
         Set value at specified index
 
+        >>> v = Vector(5, INT)
+        >>> v.set(1, 10)
+        >>> v.set(2, -1)
+        >>> v.set(4, 15)
+        >>> print(v)
+        '
+         0| .
+         1|10
+         2|-1
+         3| .
+         4|15
+        '
+
         :param i: uint.
             Row index to set.
 
@@ -158,6 +199,18 @@ def get(self, i):
         """
         Get value at specified index.
 
+        >>> v = Vector.from_lists([0, 1], [-2, -3], 5, INT)
+        >>> print(v.get(0))
+        '
+            -2
+        '
+
+        >>> v = Vector.from_lists([0, 1], [-2, -3], 5, INT)
+        >>> print(v.get(4))
+        '
+            0
+        '
+
         :param i: uint.
             Row index of value to get.
 
@@ -207,6 +260,12 @@ def to_lists(self):
         """
         Read vector data as a python lists of keys and values.
 
+        >>> v = Vector.from_lists([0, 1, 4], [-2, -3, 10], 5, INT)
+        >>> print(v.to_lists())
+        '
+            ([0, 1, 4], [-2, -3, 10])
+        '
+
         :return: Tuple (List, List) with the vector keys and vector values.
         """
 
@@ -225,6 +284,12 @@ def to_list(self):
         """
         Read vector data as a python lists of tuples where key and value stored together.
 
+        >>> v = Vector.from_lists([0, 1, 4], [-2, -3, 10], 5, INT)
+        >>> print(v.to_list())
+        '
+            [(0, -2), (1, -3), (4, 10)]
+        '
+
         :return: List of vector entries.
         """
 
@@ -375,6 +440,16 @@ def eadd(self, op_add, v, out=None, desc=None):
         """
         Element-wise add one vector to another and return result.
 
+        >>> u = Vector.from_lists([0, 1], [10, 20], 4, INT)
+        >>> v = Vector.from_lists([1, 3], [-5, 12], 4, INT)
+        >>> print(u.eadd(INT.PLUS, v))
+        '
+         0|10
+         1|15
+         2| .
+         3|12
+        '
+
         :param op_add: OpBinary.
             Binary operation to sum values.
 
@@ -409,6 +484,18 @@ def assign(self, mask, value, op_assign, op_select, desc=None):
         """
         Assign scalar value to a vector by mask.
 
+        >>> v = Vector(4, INT)
+        >>> m = Vector.from_lists([0, 1, 3], [1, 0, 1], 4, INT)
+        >>> s = Scalar(INT, 4)
+        >>> v.assign(mask=m, value=s, op_assign=INT.SECOND, op_select=INT.GTZERO)
+        >>> print(v)
+        '
+         0| 4
+         1| .
+         2| .
+         3| 4
+        '
+
         :param mask: Vector.
             Mask vector which structure will be used to select entries for assignment.
 
@@ -442,6 +529,18 @@ def reduce(self, op_reduce, out=None, init=None, desc=None):
         """
         Reduce vector elements.
 
+        >>> v = Vector.from_lists([0, 1, 2], [-1, 2, 5], 4, INT)
+        >>> print(v.reduce(op_reduce=INT.PLUS))
+        '
+            6
+        '
+
+        >>> v = Vector.from_lists([0, 1, 2], [-0.5, 4.0, 12.3], 4, FLOAT)
+        >>> print(v.reduce(op_reduce=FLOAT.MAX))
+        '
+            12.3
+        '
+
         :param op_reduce: OpBinary.
             Binary operation to apply for reduction of vector elements.