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	Data contained in the sparse matrix (numpy array of elements)
dim	The extra dimensionality of the sparse matrix
dkind	The data-type in the sparse matrix (in str)
dtype	The data-type in the sparse matrix
finalized	Whether the contained data is finalized and non-used elements have been removed
nnz	Number of non-zero elements in the sparse matrix
shape	Return shape of the sparse matrix

Methods

align(other)	Aligns this sparse matrix with the sparse elements of the other sparse matrix
copy([dims, dtype])	Returns an exact copy of the sparse matrix
diags(diagonals[, offsets, shape, dtype])	Create a SparseCSR with diagonal elements
eliminate_zeros()	Remove all zero elememts from 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)
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,1)[, dtype]).
• SparseCSR((M,N), dim=K, [, 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:

dim : int, optional

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

dtype : numpy.dtype, optional

data type of the matrix, defaults to numpy.float64

nnzpr : int, optional

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

nnz : int, optional

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

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

align(other)	Aligns this sparse matrix with the sparse elements of the other sparse matrix
copy([dims, dtype])	Returns an exact copy of the sparse matrix
diags(diagonals[, offsets, shape, dtype])	Create a SparseCSR with diagonal elements
eliminate_zeros()	Remove all zero elememts from 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)
spsame(other)	Check whether two sparse matrices have the same non-zero elements
tocsr([dim])	Return the data in scipy.sparse.csr_matrix format

align(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.

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

Data contained in the sparse matrix (numpy array of elements)

classmethod diags(diagonals, offsets=0, shape=None, dtype=None)

Create a SparseCSR with diagonal elements

Parameters:

diagonals : scalar or array_like

the diagonal values, if scalar the shape must be present.

offsets : scalar or array_like

the offsets from the diagonal for each of the components (defaults to the diagonal)

shape : tuple or list of int

matrix dimensions, if un-specified the size will be a square matrix with size len(diagonals)

dtype : numpy.dtype, optional

the data-type to create (default to numpy.float64)

dim

The extra dimensionality of the sparse matrix

dkind

The data-type in the sparse matrix (in str)

dtype

The data-type in the sparse matrix

eliminate_zeros()

Remove all zero elememts from the sparse matrix

This is an in-place operation

empty(keep=False)

Delete all sparse information from the sparsity pattern

Essentially this deletes all entries.

Parameters:

keep: boolean, optional

if True keeps the sparse elements _as is_. I.e. it will merely set the stored sparse elements to 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, optional

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 or array_like of int

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

nnz

Number of non-zero elements in the sparse matrix

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

spsame(other)

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

Parameters:other : SparseCSR Returns:True if the same non-zero elements are in the matrices (but not necessarily the same values)

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