From 161633d7a01564167bbaa458da9029994ebf29ac Mon Sep 17 00:00:00 2001 From: Egor Orachev Date: Fri, 14 Oct 2022 12:02:12 +0300 Subject: [PATCH] gh-167: add essential docs for pyspla primitives --- python/pyspla/__init__.py | 49 +++++++++++++++++++------- python/pyspla/matrix.py | 45 ++++++++++++++---------- python/pyspla/object.py | 53 ++++++++++++++++++++++++++++ python/pyspla/scalar.py | 73 +++++++++++++++++++++++++++++++++++++++ python/pyspla/vector.py | 59 +++++++++++++++++++++++++++++++ src/type.cpp | 8 ++--- 6 files changed, 253 insertions(+), 34 deletions(-) create mode 100644 python/pyspla/object.py create mode 100644 python/pyspla/scalar.py diff --git a/python/pyspla/__init__.py b/python/pyspla/__init__.py index 527ee4185..32266beec 100644 --- a/python/pyspla/__init__.py +++ b/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 * diff --git a/python/pyspla/matrix.py b/python/pyspla/matrix.py index fda4d71f3..73e22919d 100644 --- a/python/pyspla/matrix.py +++ b/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 ------- diff --git a/python/pyspla/object.py b/python/pyspla/object.py new file mode 100644 index 000000000..8f3e8fe02 --- /dev/null +++ b/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 diff --git a/python/pyspla/scalar.py b/python/pyspla/scalar.py new file mode 100644 index 000000000..7ac904f76 --- /dev/null +++ b/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 diff --git a/python/pyspla/vector.py b/python/pyspla/vector.py index 2a6354b1a..93b4faa49 100644 --- a/python/pyspla/vector.py +++ b/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 diff --git a/src/type.cpp b/src/type.cpp index 768d7a400..999608cb0 100644 --- a/src/type.cpp +++ b/src/type.cpp @@ -29,9 +29,9 @@ namespace spla { - ref_ptr BYTE = TType::make_type("BYTE", "B", "char", "signed 1 byte integral type", 1); - ref_ptr INT = TType::make_type("INT", "I", "int", "signed 4 byte integral type", 2); - ref_ptr UINT = TType::make_type("UINT", "U", "uint", "unsigned 4 byte integral type", 3); - ref_ptr FLOAT = TType::make_type("FLOAT", "F", "float", "4 byte floating point type", 4); + ref_ptr BYTE = TType::make_type("BYTE", "B", "char", "signed 1 byte integral type", 1); + ref_ptr INT = TType::make_type("INT", "I", "int", "signed 4 byte integral type", 2); + ref_ptr UINT = TType::make_type("UINT", "U", "uint", "unsigned 4 byte integral type", 3); + ref_ptr FLOAT = TType::make_type("FLOAT", "F", "float", "4 byte floating point type", 4); }// namespace spla \ No newline at end of file