gh-167: add essential docs for pyspla primitives

python/pyspla/__init__.py

@@ -2,9 +2,9 @@
 Python wrapper for spla library
 ===============================
 
-Cross-platforms generalized sparse linear algebra framework for efficient mathematical
+Cross-platform generalized sparse linear algebra framework for efficient mathematical
 computations over sparse matrices and vectors with vendor-agnostic GPUs
-accelerations to speed-up processing of large and complex data.
+acceleration to speed-up processing of large and complex data.
 Library core witten using C++ with optional C-compatible interface.
 
 Links:
@@ -26,7 +26,7 @@
 - **Bug report**:
   [https://github.com/JetBrains-Research/spla/issues](https://github.com/JetBrains-Research/spla/issues)
 
-We are welcome for contribution. Join project development on [GitHub](https://github.com/JetBrains-Research/spla)!
+We are welcome for contributions. Join project development on [GitHub](https://github.com/JetBrains-Research/spla)!
 
 Installation
 ------------
@@ -48,8 +48,8 @@
 
 Generalized sparse liner algebra python package with GPUs accelerated
 computations. Library provides a set of linear algebra primitives such as
-`matrix` and `vector` for mathematical computations parametrized using
-on of built-in `type`. It allows to define sequence of execution tasks
+`matrix`, `vector` and `scalar` for mathematical computations parametrized using
+one of built-in `type`. It allows to define sequence of execution tasks
 using `schedule` API. Desired behavior of math operations can be customized
 using on of element operations in `op` module.
 
@@ -70,8 +70,9 @@
 managed by container internally. All required format conversion done
 in the context of particular primitive usage.
 
-- `Matrix` - Generalized sparse storage-invariant matrix primitive.
-- `Vector` - Generalized sparse storage-invariant vector primitive.
+- `Matrix` - Generalized statically-typed sparse storage-invariant matrix primitive.
+- `Vector` - Generalized statically-typed sparse storage-invariant vector primitive.
+- `Scalar` - Generalized statically-typed scalar primitive.
 
 Schedule
 --------
@@ -86,12 +87,35 @@
 Types
 -----
 
-TBD.
+Library provides a set of standard and common built-in data types. Library value types
+differ a bit from a classic type definition. In spla library type is essentially is a
+storage characteristic, which defines count and layout of bytes per element. User
+can interpret stored data as her/she wants. Spla types set is limited due to the nature
+of GPUs accelerations, where arbitrary layout of data causes significant performance penalties.
+
+- `BYTE`  - 1-byte-sized signed integral value
+- `INT`   - 4-byte-sized signed integral value
+- `UINT`  - 4-byte-sized unsigned integral value
+- `FLOAT` - 4-byte-sized single-precision floating point value
 
 Op
 --
 
-TBD.
+Library provides a set of unary, binary and select ops for values data manipulation inside
+matrix and vector containers.
+
+- `PLUS`   - binary(x,y): r = x + y
+- `MINUS`  - binary(x,y): r = x - y
+- `MULT`   - binary(x,y): r = x * y
+- `DIV`    - binary(x,y): r = x / y
+- `FIRST`  - binary(x,y): r = x
+- `SECOND` - binary(x,y): r = y
+- `ONE`    - binary(x,y): r = 1
+- `MIN`    - binary(x,y): r = min(x, y)
+- `MAX`    - binary(x,y): r = max(x, y)
+- `BOR`    - binary(x,y): r = x | y, for integral only
+- `BAND`   - binary(x,y): r = x & y, for integral only
+- `BXOR`   - binary(x,y): r = x ^ y, for integral only
 
 Usage information
 -----------------
@@ -101,9 +125,8 @@
 Details
 -------
 
-Spla C backend compiled library is automatically loaded and
-initialized on package import. State of the library managed
-by internal `bridge` module. All resources are unloaded automatically
+Spla C/C++ backend compiled library is automatically loaded and initialized on package import.
+State of the library managed by internal `bridge` module. All resources are unloaded automatically
 on package exit. Library state finalized automatically.
 """
 
@@ -133,10 +156,12 @@
 
 from .library import *
 from .op import *
+from .object import *
 from .schedule import *
 from .type import *
 from .matrix import *
 from .vector import *
+from .scalar import *
 from .version import *
 from .bridge import *
 

python/pyspla/matrix.py

@@ -31,14 +31,13 @@
 
 class Matrix:
     """
-    Generalized sparse storage-invariant matrix primitive.
+    Generalized statically-typed sparse storage-invariant matrix primitive.
 
     Attributes
     ----------
 
     - type : `type` type of stored matrix elements
     - shape : `2-tuple` shape of the matrix in form of two integers tuple
-    - hnd: `p_void`  handle to the native matrix object in spla C API
 
     Notes
     -----
@@ -47,28 +46,38 @@ class Matrix:
 
     - incremental creation
     - build from values
-    - transposition
-    - triangular lower
-    - triangular upper
-    - element-wise addition
-    - element-wise subtraction
+    - read-back by value
+    - (tbd) transposition
+    - (tbd) triangular lower
+    - (tbd) triangular upper
+    - (tbd) element-wise addition
+    - (tbd) element-wise subtraction
     - matrix-vector product
-    - matrix-matrix product
-    - matrix-matrix kronecker product
+    - (tbd) matrix-matrix product
+    - (tbd) matrix-matrix kronecker product
 
-    Matrix best performance:
+    Matrix supports storage schemas:
 
-    - Prepare matrix data
-    - Ensure matrix format
-    - Execute math operations
-    - Avoiding unnecessary data reads and mixing of incremental updates from python
+    - cpu lil (list of lists, for incremental build)
+    - cpu dok (dictionary of keys, for incremental build and per-value reed back)
+    - cpu coo (coordinate matrix format)
+    - cpu csr (compressed sparse rows)
+    - cpu csc (compressed sparse columns)
+    - acc coo (opencl)
+    - acc csr (opencl)
+    - acc csc (opencl)
 
     Matrix typical usage:
 
-    - Instantiate matrix primitive
-    - Build incrementally from yours data source
-    - Matrix usage in a sequence of math operations
-    - Read-back matrix data to python to analyse results
+    - (1) Instantiate matrix primitive
+    - (2) Build incrementally from yours data source
+    - (3) Matrix usage in a sequence of math operations
+    - (4) Read-back matrix data to python to analyse results
+
+    Steps (2) and (4) requires internal format transformations and possible transfer of data
+    from acc (GPU) side if acceleration was employed in computations. These steps may be very
+    intensive, so you have to avoid them in critical parts of computations. If you need faster
+    data reads, prefer usage of batched reads, where all content of storage read at once.
 
     Details
     -------

python/pyspla/object.py

@@ -0,0 +1,53 @@
+"""
+Wrapped native (spla C API) object primitive implementation.
+"""
+
+__copyright__ = "Copyright (c) 2021-2022 JetBrains-Research"
+
+__license__ = """
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import ctypes
+
+
+class Object:
+    """
+    Base class for any spla library object.
+
+    Attributes
+    ----------
+
+    - label : `str` user provided text label for object for debugging
+    - hnd : `ctypes.p_void` hnd to native object in spla C API
+
+    Details
+    -------
+
+    Object class support all spla C API matrix functions.
+    It provides bind functionality as well as new functions/methods for better python user experience.
+
+    Object class used for runtime-introspection of spla primitives, as well as for safe ref-count
+    of native spla C/C++ instances, created inside imported native shared spla (.dll/.so/.dylib) library.
+    """
+
+    def __init__(self):
+        pass

python/pyspla/scalar.py

@@ -0,0 +1,73 @@
+"""
+Wrapped native (spla C API) scalar primitive implementation.
+"""
+
+__copyright__ = "Copyright (c) 2021-2022 JetBrains-Research"
+
+__license__ = """
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+import ctypes
+
+
+class Scalar:
+    """
+    Generalized statically-typed scalar primitive.
+
+    Attributes
+    ----------
+
+    - type : `type` type of stored matrix elements
+    - shape : `2-tuple` shape of the scalar in form of two integers tuple (always 1x1)
+
+    Notes
+    -----
+
+    Scalar provides features for:
+
+    - pack native value
+    - unpack native value
+    - pass value as a param to some operation
+    - get scalar as an operation result
+
+    Scalar typical usage:
+
+    - (1) Create scalar from python value
+    - (2) Pass scalar as argument to matrix/vector operation
+    - (3) Get scalar as a return value of some operation
+    - (4) Unpack value on python side
+
+    Avoid intensive creation of scalar values. Prefer python native types.
+    Use scalars only if you want to parametrise matrix/vector operations.
+
+    Details
+    -------
+
+    Scalar class support all spla C API scalar functions.
+    It provides bind functionality as well as new functions/methods for better python user experience.
+
+    Scalar internally stored in the native format of the type it has.
+    Meta-data additionally stored with each scalar value.
+    """
+
+    def __init__(self):
+        pass

python/pyspla/vector.py

@@ -25,3 +25,62 @@
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
+
+import ctypes
+
+
+class Vector:
+    """
+    Generalized statically-typed sparse storage-invariant vector primitive.
+
+    Attributes
+    ----------
+
+    - type : `type` type of stored vector elements
+    - shape : `2-tuple` shape of the vector in form of two integers tuple (second dim is 1)
+
+    Notes
+    -----
+
+    Vector provides features for:
+
+    - incremental creation
+    - build from values
+    - read-back by value
+    - reduction to scalar
+    - (tbd) element-wise addition
+    - (tbd) element-wise subtraction
+    - matrix-vector product
+
+    Vector supports storage schemas:
+
+    - cpu dense
+    - acc dense (opencl)
+
+    Vector typical usage:
+
+    - (1) Instantiate vector primitive
+    - (2) Build incrementally from yours data source
+    - (3) Vector usage in a sequence of math operations
+    - (4) Read-back vector data to python to analyse results
+
+    Steps (2) and (4) requires internal format transformations and possible transfer of data
+    from acc (GPU) side if acceleration was employed in computations. These steps may be very
+    intensive, so you have to avoid them in critical parts of computations. If you need faster
+    data reads, prefer usage of batched reads, where all content of storage read at once.
+
+    Details
+    -------
+
+    Vector class support all spla C API vector functions.
+    It provides bind functionality as well as new functions/methods for better python user experience.
+
+    Vector internally manages optimal format of stored data. Use hints to
+    force vector state and format changes.
+
+    Vector optional uses dedicated/integrated GPU to speedup computations
+    using one of built-in OpenCL or CUDA accelerators.
+    """
+
+    def __init__(self):
+        pass

src/type.cpp

@@ -29,9 +29,9 @@
 
 namespace spla {
 
-    ref_ptr<Type> BYTE  = TType<std::int8_t>::make_type("BYTE", "B", "char", "signed 1 byte integral type", 1);
-    ref_ptr<Type> INT   = TType<std::int32_t>::make_type("INT", "I", "int", "signed 4 byte integral type", 2);
-    ref_ptr<Type> UINT  = TType<std::uint32_t>::make_type("UINT", "U", "uint", "unsigned 4 byte integral type", 3);
-    ref_ptr<Type> FLOAT = TType<float>::make_type("FLOAT", "F", "float", "4 byte floating point type", 4);
+    ref_ptr<Type> BYTE  = TType<T_BYTE>::make_type("BYTE", "B", "char", "signed 1 byte integral type", 1);
+    ref_ptr<Type> INT   = TType<T_INT>::make_type("INT", "I", "int", "signed 4 byte integral type", 2);
+    ref_ptr<Type> UINT  = TType<T_UINT>::make_type("UINT", "U", "uint", "unsigned 4 byte integral type", 3);
+    ref_ptr<Type> FLOAT = TType<T_FLOAT>::make_type("FLOAT", "F", "float", "4 byte floating point type", 4);
 
 }// namespace spla