Arrays#

class sigmaepsilon.math.linalg.meta.Array(shape=None, dtype=<class 'float'>, buffer=None, offset=0, strides=None, order=None, frame=None)[source]#

Base backend class for array-like classes. Although you don’t really need to directly create instances of this class, you can use it like if it was a numpy.ndarray instance.

The class has a safe metaclass, which means that there is a safety mechanism that prevents you from unintentionally crashing the internal behaviour of the class upon subclassing. This practically means, that you will see an error if you try to shadow a definition in any of the base classes of the class. For this reason it is safer to subclass this class rather than to directly subclass NumPy’s ndarray class.

See also

ndarray, ABC_Safe

property frame: FrameLike#: Returns the frame of the vector.

class sigmaepsilon.math.linalg.meta.ArrayWrapper(*args, cls_params=None, contiguous: bool = True, **kwargs)[source]#

Base frontend class for array-like classes. Use it like if it was a numpy.ndarray instance.

chop(tol: float = 1e-12) → ArrayWrapper[source]#

Sets very small values (in an absolute sense) to zero.

Added in version 1.0.5.

Parameters:: tol (float, Optional) – The values whose absolute value is less than this limit are set to zero. Default is 1e-12.
Returns:: The object the call was made upon.
Return type:: ArrayWrapper`

property dim: int#: Returns the dimension of the array.

property minmax: Tuple[float]#: Returns the minimum and maximum values of the array.

to_numpy() → ndarray[source]#: Returns the data as a pure NumPy array.

class sigmaepsilon.math.linalg.sparse.JaggedArray(data: Iterable = None, *, cuts: Iterable = None, force_numpy: bool = True, **kwargs)[source]#

A NumPy-compliant class that handles 2d matrices with a variable number of columns per row.

The class is actually an interface to awkward.Array, with some additional features, specific to 2d jagged arrays.

At the moment a JaggedArray can be constructed from * a flattened 2d jagged array with ‘cuts’ through unflatteing (we use Awkward here) * a list of 1d lists * a list of 2d NumPy arrays

Parameters:

data (Iterable) – A 2d numpy array or a list of them.
cuts (Iterable, Optional) – An iterable that tells how to unflatten an 1d array into a 2d jagged shape. Only if ‘data’ is an 1d array. Default is None.
force_numpy (bool, Optional) – Forces dense inputs to be NumPy arrays in the background. Default is True.

Examples

The following defines a dense matrix from a flattened shape:

>>> import numpy as np
>>> from sigmaepsilon.math.linalg import JaggedArray
>>> data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> JaggedArray(data, cuts=[3, 3, 3])
array([[1, 2, 3],
       [4, 5, 6],
       [7, 8, 9]])

Since we use the Awkward library to deflatten arrays, if we provide the argument force_numpy=False, which is the default behaviour, the data is stored as an Awkward array:

>>> JaggedArray(data, cuts=[3, 3, 3], force_numpy=False)
JaggedArray([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

The next example defines a jagged array. In this case the data is inevitably stored as an Awkward array.

>>> data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
>>> JaggedArray(data, cuts=[3, 3, 4])
JaggedArray([[1, 2, 3], [4, 5, 6], [7, 8, 9, 10]])

>>> JaggedArray([[1, 2], [3, 4, 5]])
JaggedArray([[1, 2], [3, 4, 5]])

>>> JaggedArray([np.eye(2), np.eye(3)])
JaggedArray([[[1, 0], [0, 1]], [[1, 0, 0], [0, 1, 0], [0, 0, 1]]])

See also

csr_matrix, awkward.Array

flatten(return_cuts: bool = False)[source]#: Returns the flattened equivalent of the array.

is_jagged() → bool[source]#: Returns True if the topology is jagged, False otherwise.

property shape#: Returns the shape of the data as a tuple. If the topology is jagged, the second item is an iterable.

Added in version 0.0.8.

property size: int#: Number of elements in the array.

to_ak() → Array[source]#: Returns underlying data as an Awkward array.

See also

awkward.Array

to_array() → Array | ndarray[source]#: Returns the underlying data, which either an Awkward or a NumPy array.

to_csr() → csr_matrix[source]#: Returns the topology as a csr_matrix.

See also

csr_matrix

to_list()[source]#: Returns underlying data as lists.

Added in version 0.0.8.

to_numpy() → ndarray[source]#: Returns underlying data as a NumPy array. This is only possible for regular topologies.

to_scipy() → csr_matrix[source]#: Returns the array as a sparse SciPy CSR matrix.

See also

scipy.sparse.csr_matrix

unique(*args, **kwargs)[source]#: Returns unique elements, by generalizing the functionality provided by numpy.unique(), see its documentation for the details.

widths() → ndarray[source]#: Returns the number of columns for each row.

class sigmaepsilon.math.linalg.sparse.csr_matrix(data: spmatrix | ndarray | Array, indices: ndarray = None, indptr: ndarray = None, shape: tuple = None)[source]#

Numba-jittable Python class for a sparse matrices in CSR format. The meaning of the input variables is the same as in SciPy, and object creation follows the same pattern.

Parameters:

data (SparseLike) – Contains the non-zero values of the matrix, in the order in which they would be encountered if we walked along the rows left to right and top to bottom. If this is a CSC matrix, the walk happens along the columns. From version 0.0.8, Awkward arrays are also accepted. .. versionmodified:: 0.0.8
indices (numpy.ndarray, Optional) – The indices of the columns (rows) during the walk. Default is None.
indptr (numpy.ndarray, Optional) – Stores row (column) boundaries. Default is None.
shape (Tuple, Optional) – Default is None.

Note

1) At the moment, this class does not support NumPy’s array protocoll. If you want this to be the argument to a numpy function, use the to_scipy() method of this class. 2) The attributed ‘data’, ‘indices’, ‘indptr’ and ‘shape’ are all accessible inside Numba-jitted functions.

Examples

Create from a JaggedArray

>>> import numpy as np
>>> from sigmaepsilon.math.linalg import JaggedArray, csr_matrix
>>> data = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
>>> csr = JaggedArray(data, cuts=[3, 3, 4]).to_csr()
>>> csr
3x4 CSR matrix of 10 values.

You can watch it as a NumPy array

>>> csr.to_numpy()
array([[ 1.,  2.,  3.,  0.],
       [ 4.,  5.,  6.,  0.],
       [ 7.,  8.,  9., 10.]])

Create from a SciPy sparse matrix

>>> from scipy.sparse import csr_matrix as csr_scipy
>>> scipy_matrix = csr_scipy((3, 4), dtype=np.int8).toarray()
>>> csr_matrix(scipy_matrix)
3x4 CSR matrix of 12 values.

To create the 10 by 10 identity matrix, do this:

>>> csr_matrix.eye(10)
10x10 CSR matrix of 10 values.

You can access rows and row indices of a CSR matrix in Numba jitted code, even in ‘nopython’ mode:

>>> from numba import jit
>>> @jit(nopython=True)
... def numba_nopython(csr: csr_matrix, i: int):
...     return csr.row(i), csr.irow(i)
>>> row = np.array([0, 0, 1, 2, 2, 2])
>>> col = np.array([0, 2, 2, 0, 1, 2])
>>> data = np.array([1, 2, 3, 4, 5, 6])
>>> matrix = csr_scipy((data, (row, col)), shape=(3, 3))
>>> matrix.toarray()
array([[1, 0, 2],
       [0, 0, 3],
       [4, 5, 6]])
>>> csr = csr_matrix(matrix)
>>> numba_nopython(csr, 0)  
(array([1., 2.]), array([0, 2]))