45class Type:
 46    """
 47    Spla base Type for storage parametrization.
 48
 49    List of built-in Unary operations
 50    ---------------------------------
 51
 52    | Name      | Type     | Meaning        |
 53    |:----------|:---------|:---------------|
 54    |`IDENTITY` | unary(x) | r = x          |
 55    |`AINV`     | unary(x) | r = -x         |
 56    |`MINV`     | unary(x) | r = 1/x        |
 57    |`LNOT`     | unary(x) | r = !(x!=0)    |
 58    |`UONE`     | unary(x) | r = 1          |
 59    |`ABS`      | unary(x) | r = abs(x)     |
 60    |`BNOT`     | unary(x) | r = ~x         |
 61    |`SQRT`     | unary(x) | r = sqrt(x)    |
 62    |`LOG`      | unary(x) | r = log(x)     |
 63    |`EXP`      | unary(x) | r = exp(x)     |
 64    |`SIN`      | unary(x) | r = sin(x)     |
 65    |`COS`      | unary(x) | r = cos(x)     |
 66    |`TAN`      | unary(x) | r = tan(x)     |
 67    |`ASIN`     | unary(x) | r = asin(x)    |
 68    |`ACOS`     | unary(x) | r = acos(x)    |
 69    |`ATAN`     | unary(x) | r = atan(x)    |
 70    |`CEIL`     | unary(x) | r = ceil(x)    |
 71    |`FLOOR`    | unary(x) | r = floor(x)   |
 72    |`ROUND`    | unary(x) | r = round(x)   |
 73    |`TRUNC`    | unary(x) | r = trunc(x)   |
 74
 75    List of built-in Binary operations
 76    ----------------------------------
 77
 78    | Name    | Type        | Meaning        |
 79    |:--------|:------------|:---------------|
 80    |`PLUS`   | binary(x,y) | r = x + y      |
 81    |`MINUS`  | binary(x,y) | r = x - y      |
 82    |`MULT`   | binary(x,y) | r = x * y      |
 83    |`DIV`    | binary(x,y) | r = x / y      |
 84    |`FIRST`  | binary(x,y) | r = x          |
 85    |`SECOND` | binary(x,y) | r = y          |
 86    |`BONE`   | binary(x,y) | r = 1          |
 87    |`MIN`    | binary(x,y) | r = min(x, y)  |
 88    |`MAX`    | binary(x,y) | r = max(x, y)  |
 89    |`LOR`    | binary(x,y) | r = x lor y    |
 90    |`LAND`   | binary(x,y) | r = x && y     |
 91    |`BOR`    | binary(x,y) | r = x bor y    |
 92    |`BAND`   | binary(x,y) | r = x & y      |
 93    |`BXOR`   | binary(x,y) | r = x ^ y      |
 94
 95    List of built-in Select operations
 96    ----------------------------------
 97
 98    | Name    | Type        | Meaning        |
 99    |:--------|:------------|:---------------|
100    |`EQZERO` | select(x)   | x == 0         |
101    |`NQZERO` | select(x)   | x != 0         |
102    |`GTZERO` | select(x)   | x > 0          |
103    |`GEZERO` | select(x)   | x >= 0         |
104    |`LTZERO` | select(x)   | x < 0          |
105    |`LEZERO` | select(x)   | x <= 0         |
106    |`ALWAYS` | select(x)   | true           |
107    |`NEVER`  | select(x)   | false          |
108
109    """
110
111    _c_type = None
112    _c_type_p = None
113    _code = ''
114    _scalar_get = None
115    _scalar_set = None
116    _array_get = None
117    _array_set = None
118    _vector_get = None
119    _vector_set = None
120    _matrix_get = None
121    _matrix_set = None
122    _hnd = None
123
124    IDENTITY: OpUnary
125    AINV: OpUnary
126    MINV: OpUnary
127    LNOT: OpUnary
128    UONE: OpUnary
129    ABS: OpUnary
130    BNOT: OpUnary
131    SQRT: OpUnary
132    LOG: OpUnary
133    EXP: OpUnary
134    SIN: OpUnary
135    COS: OpUnary
136    TAN: OpUnary
137    ASIN: OpUnary
138    ACOS: OpUnary
139    ATAN: OpUnary
140    CEIL: OpUnary
141    FLOOR: OpUnary
142    ROUND: OpUnary
143    TRUNC: OpUnary
144
145    PLUS: OpBinary
146    MINUS: OpBinary
147    MULT: OpBinary
148    DIV: OpBinary
149    MINUS_POW2: OpBinary
150    FIRST: OpBinary
151    SECOND: OpBinary
152    BONE: OpBinary
153    MIN: OpBinary
154    MAX: OpBinary
155    LOR: OpBinary
156    LAND: OpBinary
157    BOR: OpBinary
158    BAND: OpBinary
159    BXOR: OpBinary
160
161    EQZERO: OpSelect
162    NQZERO: OpSelect
163    GTZERO: OpSelect
164    GEZERO: OpSelect
165    LTZERO: OpSelect
166    LEZERO: OpSelect
167    ALWAYS: OpSelect
168    NEVER: OpSelect
169
170    @classmethod
171    def get_code(cls):
172        """
173        Literal code of the type in numpy style.
174        """
175        return cls._code
176
177    @classmethod
178    def cast_value(cls, value):
179        """
180        Transforms native C value into python value.
181
182        :param value: any.
183            Ctypes value to unpack to python value.
184
185        :return: Transformed value.
186        """
187        pass
188
189    @classmethod
190    def format_value(cls, value, width=2, precision=2):
191        """
192        Format value of this type for a pretty printing.
193
194        :param value: any.
195            Value to format by this type.
196
197        :param width: optional: int. default: 2.
198            Formatted string integral part width.
199
200        :param precision:
201            Formatted string fractional part width.
202
203        :return: Formatted value.
204        """
205        f = "{:>%s}" % width
206        if not isinstance(value, bool):
207            return f.format(value)
208        return f.format("t") if value is True else f.format("f")
209
210    @classmethod
211    def _setup_op_unary(cls):
212        b = backend()
213        type_name = cls.__name__
214
215        def load_op(name):
216            f = f"spla_OpUnary_{name}_{type_name}"
217            func = getattr(b, f) if hasattr(b, f) else None
218            return OpUnary(hnd=func(), name=name, dtype_res=cls, dtype_arg0=cls) if func else None
219
220        cls.IDENTITY = load_op('IDENTITY')
221        cls.AINV = load_op('AINV')
222        cls.MINV = load_op('MINV')
223        cls.LNOT = load_op('LNOT')
224        cls.UONE = load_op('UONE')
225        cls.ABS = load_op('ABS')
226        cls.BNOT = load_op('BNOT')
227        cls.SQRT = load_op('SQRT')
228        cls.LOG = load_op('LOG')
229        cls.EXP = load_op('EXP')
230        cls.SIN = load_op('SIN')
231        cls.COS = load_op('COS')
232        cls.TAN = load_op('TAN')
233        cls.ASIN = load_op('ASIN')
234        cls.ACOS = load_op('ACOS')
235        cls.ATAN = load_op('ATAN')
236        cls.CEIL = load_op('CEIL')
237        cls.FLOOR = load_op('FLOOR')
238        cls.ROUND = load_op('ROUND')
239        cls.TRUNC = load_op('TRUNC')
240
241    @classmethod
242    def _setup_op_binary(cls):
243        b = backend()
244        type_name = cls.__name__
245
246        def load_op(name):
247            f = f"spla_OpBinary_{name}_{type_name}"
248            func = getattr(b, f) if hasattr(b, f) else None
249            return OpBinary(hnd=func(), name=name, dtype_res=cls, dtype_arg0=cls, dtype_arg1=cls) if func else None
250
251        cls.PLUS = load_op('PLUS')
252        cls.MINUS = load_op('MINUS')
253        cls.MULT = load_op('MULT')
254        cls.DIV = load_op('DIV')
255        cls.MINUS_POW2 = load_op('MINUS_POW2')
256        cls.FIRST = load_op('FIRST')
257        cls.SECOND = load_op('SECOND')
258        cls.BONE = load_op('BONE')
259        cls.MIN = load_op('MIN')
260        cls.MAX = load_op('MAX')
261        cls.LOR = load_op('LOR')
262        cls.LAND = load_op('LAND')
263        cls.BOR = load_op('BOR')
264        cls.BAND = load_op('BAND')
265        cls.BXOR = load_op('BXOR')
266
267    @classmethod
268    def _setup_op_select(cls):
269        b = backend()
270        type_name = cls.__name__
271
272        def load_op(name):
273            f = f"spla_OpSelect_{name}_{type_name}"
274            func = getattr(b, f) if hasattr(b, f) else None
275            return OpSelect(hnd=func(), name=name, dtype_arg0=cls) if func else None
276
277        cls.EQZERO = load_op('EQZERO')
278        cls.NQZERO = load_op('NQZERO')
279        cls.GTZERO = load_op('GTZERO')
280        cls.GEZERO = load_op('GEZERO')
281        cls.LTZERO = load_op('LTZERO')
282        cls.LEZERO = load_op('LEZERO')
283        cls.ALWAYS = load_op('ALWAYS')
284        cls.NEVER = load_op('NEVER')
285
286    @classmethod
287    def _setup(cls):
288        b = backend()
289        type_name = cls.__name__
290        type_name_lower = type_name.lower()
291
292        if not b:
293            return
294
295        cls._scalar_get = getattr(b, f"spla_Scalar_get_{type_name_lower}")
296        cls._scalar_set = getattr(b, f"spla_Scalar_set_{type_name_lower}")
297        cls._array_get = getattr(b, f"spla_Array_get_{type_name_lower}")
298        cls._array_set = getattr(b, f"spla_Array_set_{type_name_lower}")
299        cls._vector_get = getattr(b, f"spla_Vector_get_{type_name_lower}")
300        cls._vector_set = getattr(b, f"spla_Vector_set_{type_name_lower}")
301        cls._matrix_get = getattr(b, f"spla_Matrix_get_{type_name_lower}")
302        cls._matrix_set = getattr(b, f"spla_Matrix_set_{type_name_lower}")
303        cls._hnd = getattr(b, f"spla_Type_{type_name}")()
304
305        cls._setup_op_unary()
306        cls._setup_op_binary()
307        cls._setup_op_select()

310class BOOL(Type):
311    """Spla logical BOOL-32 type."""
312
313    _c_type = ctypes.c_bool
314    _c_type_p = ctypes.POINTER(ctypes.c_bool)
315    _code = 'B'
316
317    @classmethod
318    def cast_value(cls, value):
319        return bool(value.value)

322class INT(Type):
323    """Spla integral INT-32 type."""
324
325    _c_type = ctypes.c_int
326    _c_type_p = ctypes.POINTER(ctypes.c_int)
327    _code = 'I'
328
329    @classmethod
330    def cast_value(cls, value):
331        return int(value.value)

334class UINT(Type):
335    """Spla integral UINT-32 type."""
336
337    _c_type = ctypes.c_uint
338    _c_type_p = ctypes.POINTER(ctypes.c_uint)
339    _code = 'U'
340
341    @classmethod
342    def cast_value(cls, value):
343        return int(value.value)

346class FLOAT(Type):
347    """Spla floating-point FLOAT-32 type."""
348
349    _c_type = ctypes.c_float
350    _c_type_p = ctypes.POINTER(ctypes.c_float)
351    _code = 'F'
352
353    @classmethod
354    def cast_value(cls, value):
355        return float(value.value)
356
357    @classmethod
358    def format_value(cls, value, width=2, precision=2):
359        return f"{value:>{width}.{precision}}"

102class FormatMatrix(enum.Enum):
103    """
104    Mapping for spla supported matrix storage formats enumeration.
105
106    | Name     | Memory type   | Description                                                       |
107    |:---------|--------------:|:------------------------------------------------------------------|
108    |`CPU_LIL` | RAM (host)    | List of lists, storing adjacency lists per vertex                 |
109    |`CPU_DOK` | RAM (host)    | Dictionary of keys, effectively hash map of row,column to value   |
110    |`CPU_COO` | RAM (host)    | Lists of coordinates, storing rows, columns and values separately |
111    |`CPU_CSR` | RAM (host)    | Compressed sparse rows format                                     |
112    |`CPU_CSC` | RAM (host)    | Compressed sparse columns format                                  |
113    |`ACC_COO` | VRAM (device) | List of coordinates, but implemented for GPU/ACC usage            |
114    |`ACC_CSR` | VRAM (device) | CSR, but implemented for GPU/ACC usage                            |
115    |`ACC_CSC` | VRAM (device) | CSC, but implemented for GPU/ACC usage                            |
116
117    """
118
119    CPU_LIL = 0
120    CPU_DOK = 1
121    CPU_COO = 2
122    CPU_CSR = 3
123    CPU_CSC = 4
124    ACC_COO = 5
125    ACC_CSR = 6
126    ACC_CSC = 7
127    COUNT = 8

130class FormatVector(enum.Enum):
131    """
132    Mapping for spla supported vector storage formats enumeration.
133
134    | Name       | Memory type   | Description                                                    |
135    |:-----------|--------------:|:---------------------------------------------------------------|
136    |`CPU_DOK`   | RAM (host)    | Dictionary of keys, hash map of index to value                 |
137    |`CPU_DENSE` | RAM (host)    | Dense array of values with direct indexing                     |
138    |`CPU_COO`   | RAM (host)    | List of coordinates, storing rows and values separately        |
139    |`ACC_DENSE` | VRAM (device) | Dense array, but implemented for GPU/ACC usage                 |
140    |`ACC_COO`   | VRAM (device) | List of coordinates, but implemented for GPU/ACC usage         |
141    """
142
143    CPU_DOK = 0
144    CPU_DENSE = 1
145    CPU_COO = 2
146    ACC_DENSE = 3
147    ACC_COO = 4
148    COUNT = 5

36class Descriptor(Object):
37    """
38    Wrapper for a descriptor object from a library.
39    """
40
41    def __init__(self, label=None, hnd=None):
42        """
43        Creates a new descriptor from existing hnd or making new for a buffer resource.
44
45        :param label: optional: str. default: None.
46            MemView name for debugging.
47
48        :param hnd: optional: ctypes.c_void_p. default: None.
49            MemView native void* handle to a C counterpart.
50        """
51
52        super().__init__(label, hnd)

40class Op(Object):
41    """
42    Wrapper for a spla Op (operation) object.
43
44    Notes
45    -----
46
47    Operation represents some callable function with a return value.
48    This function may be used for mathematical calculations with
49    library primitives such as scalars, vectors and matrices.
50    """
51
52    __slots__ = ["_name", "_dtype_res"]
53
54    def __init__(self, hnd, name, dtype_res, label=None):
55        """
56        Creates new operation from a native C api object handle.
57
58        :param  hnd: ctypes.c_void_p.
59            Mandatory handle to native C object.
60
61        :param name: str.
62            Mandatory name of the operation.
63
64        :param dtype_res: Type.
65            Type of the return value of the operation.
66
67        :param label: optional: str. default: None.
68            Optional debug label to set for the object.
69        """
70
71        assert hnd
72        assert name
73        assert dtype_res
74
75        super().__init__(label, hnd)
76
77        self._name = name
78        self._dtype_res = dtype_res
79
80    @property
81    def name(self):
82        """
83        Name of operation.
84        """
85        return self._name
86
87    @property
88    def dtype_res(self):
89        """
90        Data type of the return value of the operation.
91        """
92        return self._dtype_res

 95class OpUnary(Op):
 96    """
 97    Wrapper for a spla OpUnary (unary operation) object.
 98
 99    Notes
100    -----
101
102    Unary operation is a callable function with a signature `T0 -> R`.
103    This function may be used in transformation and apply operations.
104    """
105
106    __slots__ = ["_dtype_arg0"]
107
108    def __init__(self, hnd, name, dtype_res, dtype_arg0, label=None):
109        """
110        Creates new unary operation from a native C api object handle.
111
112        :param hnd: ctypes.c_void_p.
113            Mandatory handle to native C object.
114
115        :param name: str.
116            Mandatory name of the operation.
117
118        :param dtype_res: Type.
119            Type of the return value of the operation.
120
121        :param dtype_arg0: Type.
122            Type of the first operation argument.
123
124        :param label: optional: str. default: None.
125            Optional debug label to set for the object.
126        """
127
128        super().__init__(hnd=hnd, name=name, dtype_res=dtype_res, label=label)
129
130        self._dtype_arg0 = dtype_arg0
131
132    @property
133    def dtype_arg0(self):
134        """
135        Data type of the first argument of the unary operation.
136        """
137        return self._dtype_arg0

140class OpBinary(Op):
141    """
142    Wrapper for a spla OpBinary (binary operation) object.
143
144    Notes
145    -----
146
147    Binary operation is a callable function with signature `T0 x T1 -> R`.
148    It is commonly used in math matrix vector products, reductions, etc.
149    """
150
151    __slots__ = ["_dtype_arg0", "_dtype_arg1"]
152
153    def __init__(self, hnd, name, dtype_res, dtype_arg0, dtype_arg1, label=None):
154        """
155        Creates new binary operation from a native C api object handle.
156
157        :param hnd: ctypes.c_void_p.
158            Mandatory handle to native C object.
159
160        :param name: str.
161            Mandatory name of the operation.
162
163        :param dtype_res: Type.
164            Type of the return value of the operation.
165
166        :param dtype_arg0: Type.
167            Type of the first operation argument.
168
169        :param dtype_arg1: Type.
170            Type of the second operation argument.
171
172        :param  label: optional: str. default: None.
173            Optional debug label to set for the object.
174        """
175
176        super().__init__(hnd=hnd, name=name, dtype_res=dtype_res, label=label)
177
178        self._dtype_arg0 = dtype_arg0
179        self._dtype_arg1 = dtype_arg1
180
181    @property
182    def dtype_arg0(self):
183        """
184        Data type of the first argument of the binary operation.
185        """
186        return self._dtype_arg0
187
188    @property
189    def dtype_arg1(self):
190        """
191        Data type of the second argument of the binary operation.
192        """
193        return self._dtype_arg1

196class OpSelect(Op):
197    """
198    Wrapper for a spla OpSelect (select operation) object.
199
200    Notes
201    -----
202
203    Selection operation is a special kind of callable function with signature `T0 -> BOOL`.
204    This type of `unary predicate` usually used for masking and filtering operations.
205    """
206
207    __slots__ = ["_dtype_arg0"]
208
209    def __init__(self, hnd, name, dtype_arg0, label=None):
210        """
211        Creates new select operation from a native C api object handle.
212
213        :param hnd: ctypes.c_void_p.
214            Mandatory handle to native C object.
215
216        :param name: str.
217            Mandatory name of the operation.
218
219        :param dtype_arg0: Type.
220            Type of the first operation argument.
221
222        :param label: optional: str. default: None.
223            Optional debug label to set for the object.
224        """
225
226        from .type import BOOL
227
228        super().__init__(hnd=hnd, name=name, dtype_res=BOOL, label=label)
229
230        self._dtype_arg0 = dtype_arg0
231
232    @property
233    def dtype_arg0(self):
234        """
235        Data type of the first argument of the select operation.
236        """
237        return self._dtype_arg0

 36class MemView(Object):
 37    """
 38    Wrapper for a memory view object from a library.
 39
 40    Details
 41    -------
 42
 43    Memory view is a wrapper for a raw memory resource. It allows to inspect
 44    spla library containers data without an extra overhead on copy operations
 45    and without explicit memory lifetime control.
 46    """
 47
 48    __slots__ = ["_buffer", "_owner"]
 49
 50    def __init__(self, label=None, hnd=None, buffer=None, size=None, mutable=None, owner=None):
 51        """
 52        Creates a new memory view from existing hnd or making new for a buffer resource.
 53
 54        :param label: optional: str. default: None.
 55            MemView name for debugging.
 56
 57        :param hnd: optional: ctypes.c_void_p. default: None.
 58            MemView native void* handle to a C counterpart.
 59
 60        :param buffer: optional: ctypes.c_void_p. default: None.
 61            Optional buffer in case making new view.
 62
 63        :param size: optional: int. default: None.
 64            Optional size, must be provided if buffer provided.
 65
 66        :param mutable: optional: bool. default: None.
 67            Optional flag if buffer content is mutable.
 68
 69        :param owner: optional: Object. default: None.
 70            Optional owner of a given memory view.
 71        """
 72
 73        super().__init__(None, None)
 74
 75        self._buffer = buffer
 76        self._owner = owner
 77
 78        if hnd is None:
 79            assert buffer
 80            assert size
 81
 82            if mutable is None:
 83                mutable = 0
 84
 85            hnd = ctypes.c_void_p(0)
 86            check(backend().spla_MemView_make(ctypes.byref(hnd), buffer, ctypes.c_size_t(size), ctypes.c_int(mutable)))
 87
 88        super().__init__(label, hnd)
 89
 90    @property
 91    def buffer(self):
 92        """
 93        Pointer to a native C-buffer viewed by this view.
 94        """
 95        c_buffer = ctypes.c_void_p(0)
 96        check(backend().spla_MemView_get_buffer(self._hnd, ctypes.byref(c_buffer)))
 97        return c_buffer
 98
 99    @property
100    def size(self):
101        """
102        Size of viewed memory buffer in bytes.
103        """
104
105        c_size = ctypes.c_size_t(0)
106        check(backend().spla_MemView_get_size(self._hnd, ctypes.byref(c_size)))
107        return int(c_size.value)
108
109    @property
110    def is_mutable(self):
111        """
112        True if the content of viewed memory buffer can be modified.
113        """
114
115        c_is_mutable = ctypes.c_int(0)
116        check(backend().spla_MemView_get_buffer(self._hnd, ctypes.byref(c_is_mutable)))
117        return bool(c_is_mutable.value)