sisl.sparse module

Sparsity pattern used to express matrices in concise manners.

class sisl.sparse.SparseCSR(arg1, dim=1, dtype=None, nnzpr=20, nnz=None, **kwargs)

Bases: object

A compressed sparse row matrix, slightly different than scipy.sparse.csr_matrix.

This class holds all required information regarding the CSR matrix format.

Note that this sparse matrix of data does not retain the number of columns in the matrix, i.e. it has no way of determining whether the input is correct.

Attributes

data	Return data contained in the sparse matrix
dim	Return extra dimensionality of the sparse matrix
dtype	Return the data-type in the sparse matrix
finalized	Whether the contained data is finalized and non-used elements have been removed
nnz	Return number of non-zero elements in the sparsity pattern
shape	Return shape of the sparse matrix

Methods

copy([dims, dtype])	Returns an exact copy of the sparse matrix
empty([keep])	Delete all sparse information from the sparsity pattern
finalize([sort])	Finalizes the sparse matrix by removing all non-set elements
iter_nnz([row])	Iterations of the non-zero elements, returns a tuple of row and column with non-zero elements
register_math(var[, routines])	Register math operators on the cls class using var as attribute getattr(cls, var)
spalign(other)	Aligns this sparse matrix with the sparse elements of the other sparse matrix
spsame(other)	Check whether two sparse matrices have the same non-zero elements
tocsr([dim])	Return the data in scipy.sparse.csr_matrix format

Initialize a new sparse CSR matrix

This sparse matrix class tries to resemble the scipy.sparse.csr_matrix as much as possible with the difference of this class being multi-dimensional.

Creating a new sparse matrix is much similar to the scipy equivalent.

nzs is only used if nzs > nr * nzsr.

This class may be instantiated by verious means.

• SparseCSR(S) where S is a scipy.sparse matrix
• SparseCSR((M,N)[, dtype]) the shape of the sparse matrix (equivalent to SparseCSR((M,N,K)[, dtype]).
• SparseCSR((M,N,K)[, dtype]) creating a sparse matrix with M rows, N columns and K elements per sparse element.

Additionally these parameters control the creation of the sparse matrix

Parameters:

nnzpr : int, 20

initial number of non-zero elements per row. Only used if nnz is not supplied

nnz : int

initial total number of non-zero elements This quantity has precedence over nnzpr

dim : int, 1

number of elements stored per sparse element, only used if (M,N) is passed

dtype : numpy data type, numpy.float64

data type of the matrix

Attributes

ncol: int-array, self.shape[0]	number of entries per row
ptr: int-array, self.shape[0]+1	pointer index in the 1D column indices of the corresponding row
col: int-array,	column indices of the sparse elements
data:	the data in the sparse matrix
dim: int	the extra dimension of the sparse matrix
nnz: int	number of contained sparse elements
shape: tuple, 3*(,)	size of contained matrix, M, N, K
finalized: boolean	whether the sparse matrix is finalized and non-set elements are removed

Methods

copy([dims, dtype])	Returns an exact copy of the sparse matrix
empty([keep])	Delete all sparse information from the sparsity pattern
finalize([sort])	Finalizes the sparse matrix by removing all non-set elements
iter_nnz([row])	Iterations of the non-zero elements, returns a tuple of row and column with non-zero elements
register_math(var[, routines])	Register math operators on the cls class using var as attribute getattr(cls, var)
spalign(other)	Aligns this sparse matrix with the sparse elements of the other sparse matrix
spsame(other)	Check whether two sparse matrices have the same non-zero elements
tocsr([dim])	Return the data in scipy.sparse.csr_matrix format

copy(dims=None, dtype=None)

Returns an exact copy of the sparse matrix

Parameters:

dims: array-like, (all)

which dimensions to store in the copy

dtype : numpy.dtype

this defaults to the dtype of the object, but one may change it if supplied.

data

Return data contained in the sparse matrix

dim

Return extra dimensionality of the sparse matrix

dtype

Return the data-type in the sparse matrix

empty(keep=False)

Delete all sparse information from the sparsity pattern

Essentially this deletes all entries.

Parameters:

keep: boolean, False

if True it will keep the sparse elements _as is_. I.e. it will merely set the stored sparse elements as zero. This may be advantagegous when re-constructing a new sparse matrix from an old sparse matrix

finalize(sort=True)

Finalizes the sparse matrix by removing all non-set elements

One may still interact with the sparse matrix as one would previously.

NOTE: This is mainly an internal used routine to ensure data structure when converting to scipy.sparse.csr_matrix

Parameters:

sort: bool, True

sort the column indices for each row

finalized

Whether the contained data is finalized and non-used elements have been removed

iter_nnz(row=None)

Iterations of the non-zero elements, returns a tuple of row and column with non-zero elements

An iterator returning the current row index and the corresponding column index.

>>> for r, c in self:

In the above case r and c are rows and columns such that

>>> self[r, c] 

returns the non-zero element of the sparse matrix.

Parameters:

row : int=, array_like

only loop on the given row(s) default to all rows

nnz

Return number of non-zero elements in the sparsity pattern

classmethod register_math(var, routines=None)

Register math operators on the cls class using var as attribute getattr(cls, var)

Parameters:

cls : class

class which gets registered overloaded math operators

var : str

name of attribute that is SparseCSR object in cls

routines : list of str

names of routines that gets overloaded, defaults to:

[‘__sub__’, ‘__add__’, ‘__mul__’, ‘__div__’,

‘__truediv__’, ‘__pow__’]

shape

Return shape of the sparse matrix

spalign(other)

Aligns this sparse matrix with the sparse elements of the other sparse matrix

Routine for ensuring that all non-zero elements in other are also in this object.

I.e. this will, possibly, change the sparse elements in-place.

A ValueError will be raised if the shapes are not mergeable.

Parameters:

other : SparseCSR

the other sparse matrix to align.

spsame(other)

Check whether two sparse matrices have the same non-zero elements

Parameters:

other : SparseCSR

Returns:

bool :

True if the same non-zero elements are in the matrices.

tocsr(dim=0, **kwargs)

Return the data in scipy.sparse.csr_matrix format

Parameters:

dim: int

the dimension of the data to create the sparse matrix

**kwargs:

arguments passed to the scipy.sparse.csr_matrix routine

sisl.sparse.ispmatrix(matrix, map_row=None, map_col=None)

Iterator for iterating rows and columns for non-zero elements in a scipy.sparse.*_matrix (or SparseCSR)

If either map_row or map_col are not None the generator will only yield the unique values.

Parameters:

matrix : scipy.sparse.sp_matrix

the sparse matrix to iterate non-zero elements

map_row : func, optional

map each row entry through the function map_row, defaults to None which is equivalent to no mapping.

map_col : func, optional

map each column entry through the function map_col, defaults to None which is equivalent to no mapping.

Yields:

int, int

the row, column indices of the non-zero elements

sisl.sparse.ispmatrixd(matrix, map_row=None, map_col=None)

Iterator for iterating rows, columns and data for non-zero elements in a scipy.sparse.*_matrix (or SparseCSR)

Parameters:

matrix : scipy.sparse.sp_matrix

the sparse matrix to iterate non-zero elements

map_row : func, optional

map each row entry through the function map_row, defaults to None which is equivalent to no mapping.

map_col : func, optional

map each column entry through the function map_col, defaults to None which is equivalent to no mapping.

Yields:

int, int, <>

the row, column and data of the non-zero elements