SparseCSR

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

A compressed sparse row matrix, slightly different than 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.

This sparse matrix class tries to resemble the 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.

nnz is only used if nnz > nr * nnzpr.

This class may be instantiated by verious means.

• SparseCSR(S) where S is a :module:`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

arg1tuple

various initialization methods as described above

dimint, optional

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

dtypenumpy.dtype, optional

data type of the matrix, defaults to numpy.float64

nnzprint, optional

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

nnzint, optional

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

Attributes

ncolint-array, self.shape[0]

number of entries per row

ptrint-array, self.shape[0]+1

pointer index in the 1D column indices of the corresponding row

colint-array

column indices of the sparse elements

data:

the data in the sparse matrix

dimint

The extra dimensionality of the sparse matrix (elements per matrix element)

nnzint

Number of non-zero elements in the sparse matrix

shapetuple, 3*(,)

The shape of the sparse matrix

finalizedboolean

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

Attributes

data	Data contained in the sparse matrix (numpy array of elements)
dim	The extra dimensionality of the sparse matrix (elements per matrix element)
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	The shape of the sparse matrix

Methods

__init__(self, arg1[, dim, dtype, nnzpr, nnz])	Initialize a new sparse CSR matrix
align(self, other)	Aligns this sparse matrix with the sparse elements of the other sparse matrix
copy(self[, dims, dtype])	A deepcopy of the sparse matrix
delete_columns(self, columns[, keep_shape])	Delete all columns in columns
diags(self, diagonals[, offsets, dim, dtype])	Create a SparseCSR with diagonal elements with the same shape as the routine
edges(self, row[, exclude])	Retrieve edges (connections) of a given row or list of row’s
eliminate_zeros(self[, atol])	Remove all zero elememts from the sparse matrix
empty(self[, keep_nnz])	Delete all sparse information from the sparsity pattern
finalize(self[, sort])	Finalizes the sparse matrix by removing all non-set elements
iter_nnz(self[, row])	Iterations of the non-zero elements, returns a tuple of row and column with non-zero elements
nonzero(self[, row, only_col])	Row and column indices where non-zero elements exists
remove(self, indices)	Return a new sparse CSR matrix with all the indices removed
spsame(self, other)	Check whether two sparse matrices have the same non-zero elements
sub(self, indices)	Create a new sparse CSR matrix with the data only for the given rows and columns
sum(self[, axis])	Calculate the sum, if axis is None the sum of all elements are returned, else a new sparse matrix is returned
tocsr(self[, dim])	Convert dimension dim into a csr_matrix format
translate_columns(self, old, new[, clean])	Takes all old columns and translates them to new.

align(self, 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

otherSparseCSR

the other sparse matrix to align.

copy(self, dims=None, dtype=None)

A deepcopy of the sparse matrix

Parameters

dimsarray-like, optional

which dimensions to store in the copy, defaults to all.

dtypenumpy.dtype

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

property data

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

delete_columns(self, columns, keep_shape=False)

Delete all columns in columns

Parameters

columnsint or array_like

columns to delete from the sparse pattern

keep_shapebool, optional

whether the shape of the object should be retained, if True all higher columns will be shifted according to the number of columns deleted below, if False, only the elements will be deleted.

diags(self, diagonals, offsets=0, dim=None, dtype=None)

Create a SparseCSR with diagonal elements with the same shape as the routine

Parameters

diagonalsscalar or array_like

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

offsetsscalar or array_like

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

dimint, optional

the extra dimension of the new diagonal matrix (default to the current extra dimension)

dtypenumpy.dtype, optional

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

property dim

The extra dimensionality of the sparse matrix (elements per matrix element)

property dkind

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

property dtype

The data-type in the sparse matrix

edges(self, row, exclude=None)

Retrieve edges (connections) of a given row or list of row’s

The returned edges are unique and sorted (see numpy.unique).

Parameters

rowint or list of int

the edges are returned only for the given row

excludeint or list of int, optional

remove edges which are in the exclude list. Default to row.

eliminate_zeros(self, atol=0.0)

Remove all zero elememts from the sparse matrix

This is an in-place operation

Parameters

atolfloat, optional

absolute tolerance below this value will be considered 0.

empty(self, keep_nnz=False)

Delete all sparse information from the sparsity pattern

Essentially this deletes all entries.

Parameters

keep_nnzboolean, 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(self, 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 csr_matrix

Parameters

sortbool, optional

sort the column indices for each row

property finalized

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

iter_nnz(self, 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

rowint or array_like of int

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

property nnz

Number of non-zero elements in the sparse matrix

nonzero(self, row=None, only_col=False)

Row and column indices where non-zero elements exists

Parameters

rowint or array_like of int, optional

only return the tuples for the requested rows, default is all rows

only_colbool, optional

only return then non-zero columns

remove(self, indices)

Return a new sparse CSR matrix with all the indices removed

Parameters

indicesarray_like

the indices of the rows and columns that are removed in the sparse pattern

property shape

The shape of the sparse matrix

spsame(self, other)

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

Parameters

otherSparseCSR

Returns

bool

true if the same non-zero elements are in the matrices (but not necessarily the same values)

sub(self, indices)

Create a new sparse CSR matrix with the data only for the given rows and columns

All rows and columns in indices are retained, everything else is removed.

Parameters

indicesarray_like

the indices of the rows and columns that are retained in the sparse pattern

sum(self, axis=None)

Calculate the sum, if axis is None the sum of all elements are returned, else a new sparse matrix is returned

Parameters

axisint, optional

which axis to perform the sum of. If None the element sum is returned, if either 0 or 1 is passed a vector is returned, and for 2 it returns a new sparse matrix with the last dimension reduced to 1 (summed).

Raises

NotImplementedErrorwhen axis = 1

tocsr(self, dim=0, **kwargs)

Convert dimension dim into a csr_matrix format

Parameters

dimint, optional

dimension of the data returned in a scipy sparse matrix format

**kwargs:

arguments passed to the csr_matrix routine

translate_columns(self, old, new, clean=True)

Takes all old columns and translates them to new.

Parameters

oldint or array_like

old column indices

newint or array_like

new column indices

cleanbool, optional

whether the new translated columns, outside the shape, should be deleted or not (default delete)