sisl.sparse_geometry module

A generic sparse matrix which is based on a hosting Geometry.

The sparse matrix can in this case represent _any_ data and should be sub-classed for specific uses.

class sisl.sparse_geometry.SparseGeometry(geom, dim=1, dtype=None, nnzpr=None, **kwargs)[source]

Bases: object

Sparse object containing sparse elements for a given geometry.

This is a base class intended to be sub-classed because the sparsity information needs to be extracted from the _size attribute.

The sub-classed object _must_ implement the _size attribute. The sub-classed object may re-implement the _cls_kwargs routine to pass down keyword arguments when a new class is instantiated.

This object contains information regarding the
  • geometry

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz() Iterations of the non-zero elements
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index

Create sparse object with element between orbitals

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz() Iterations of the non-zero elements
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index
align(other)[source]

See SparseCSR.align for details

construct(func, na_iR=1000, method='rand', eta=False)[source]

Automatically construct the sparse model based on a function that does the setting up of the elements

This may be called in two variants.

  1. Pass a function (func), see e.g. create_construct which does the setting up.
  2. Pass a tuple/list in func which consists of two elements, one is R the radii parameters for the corresponding parameters. The second is the parameters corresponding to the R[i] elements. In this second case all atoms must only have one orbital.
Parameters:

func: callable or array_like

this function must take 4 arguments. 1. Is this object (self) 2. Is the currently examined atom (ia) 3. Is the currently bounded indices (idxs) 4. Is the currently bounded indices atomic coordinates (idxs_xyz) An example func could be:

>>> def func(self, ia, idxs, idxs_xyz=None):
...     idx = self.geom.close(ia, R=[0.1, 1.44], idx=idxs, idx_xyz=idxs_xyz)
...     self[ia, idx[0]] = 0
...     self[ia, idx[1]] = -2.7

na_iR : int, optional

number of atoms within the sphere for speeding up the iter_block loop.

method : {‘rand’, str, ‘rand’

method used in Geometry.iter_block, see there for details

eta: bool, False

whether an ETA will be printed
copy(dtype=None)[source]

A copy of this object

Parameters:

dtype : numpy.dtype, optional

it is possible to convert the data to a different data-type If not specified, it will use self.dtype
create_construct(R, param)[source]

Create a simple function for passing to the construct function.

This is simply to leviate the creation of simplistic functions needed for setting up the sparse elements.

Basically this returns a function:

>>> def func(self, ia, idxs, idxs_xyz=None):
>>>     idx = self.geom.close(ia, R=R, idx=idxs)
>>>     for ix, p in zip(idx, param):
>>>         self[ia, ix] = p
Parameters:

R : array_like

radii parameters for different shells. Must have same length as param or one less. If one less it will be extended with R[0]/100

param : array_like

coupling constants corresponding to the R ranges. param[0,:] are the elements for the all atoms within R[0] of each atom.

Notes

This function only works for geometry sparse matrices (i.e. one element per atom). If you have more than one element per atom you have to implement the function your-self.

dim

Number of components per element

dkind

Data type of sparse elements (in str)

dtype

Data type of sparse elements

eliminate_zeros()[source]

Removes all zero elements from the sparse matrix

This is an in-place operation

empty(keep=False)[source]

See SparseCSR.empty for details

finalize()[source]

Finalizes the model

Finalizes the model so that all non-used elements are removed. I.e. this simply reduces the memory requirement for the sparse matrix.

Note that adding more elements to the sparse matrix is more time-consuming than for an non-finalized sparse matrix due to the internal data-representation.

finalized

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

classmethod fromsp(geom, sp)[source]

Returns a sparse model from a preset Geometry and a list of sparse matrices

geom

Associated geometry

geometry

Associated geometry

iter_nnz()[source]

Iterations of the non-zero elements

An iterator on the sparse matrix with, row and column

Examples

>>> for i, j in self.iter_nnz():
...    self[i, j] # is then the non-zero value
nnz

Number of non-zero elements

reset(dim=1, dtype=<type 'numpy.float64'>, nnzpr=None)[source]

The sparsity pattern is cleaned and every thing is reset.

The object will be the same as if it had been initialized with the same geometry as it were created with.

Parameters:

dim: int, optional

number of dimensions per element

dtype: numpy.dtype, optional

the datatype of the sparse elements

nnzpr: int, optional

number of non-zero elements per row
shape

Shape of sparse matrix

spsame(other)[source]

Compare two sparse objects and check whether they have the same entries.

This does not necessarily mean that the elements are the same

tocsr(index, isc=None)[source]

Return a scipy.sparse.csr_matrix of the specified index

Parameters:

index : int

the index in the sparse matrix (for non-orthogonal cases the last dimension is the overlap matrix)

isc : int, optional

the supercell index, or all (if isc=None)
class sisl.sparse_geometry.SparseAtom(geom, dim=1, dtype=None, nnzpr=None, **kwargs)[source]

Bases: sisl.sparse_geometry.SparseGeometry

Sparse object with number of rows equal to the total number of atoms in the Geometry

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
cut(seps, axis, *args, **kwargs) Cuts the sparse atom model into different parts.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz([atom]) Iterations of the non-zero elements
remove(atom) Create a subset of this sparse matrix by removing the elements corresponding to atom
repeat(reps, axis) Create a repeated sparse atom object, equivalent to Geometry.repeat
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
sub(atom) Create a subset of this sparse matrix by only retaining the elements corresponding to the atom
tile(reps, axis) Create a tiled sparse atom object, equivalent to Geometry.tile
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index

Create sparse object with element between orbitals

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
cut(seps, axis, *args, **kwargs) Cuts the sparse atom model into different parts.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz([atom]) Iterations of the non-zero elements
remove(atom) Create a subset of this sparse matrix by removing the elements corresponding to atom
repeat(reps, axis) Create a repeated sparse atom object, equivalent to Geometry.repeat
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
sub(atom) Create a subset of this sparse matrix by only retaining the elements corresponding to the atom
tile(reps, axis) Create a tiled sparse atom object, equivalent to Geometry.tile
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index
cut(seps, axis, *args, **kwargs)[source]

Cuts the sparse atom model into different parts.

Recreates a new sparse atom object with only the cutted atoms in the structure.

Cutting is the opposite of tiling.

Parameters:

seps : int, optional

number of times the structure will be cut

axis : int

the axis that will be cut
iter_nnz(atom=None)[source]

Iterations of the non-zero elements

An iterator on the sparse matrix with, row and column

Parameters:

atom : int or array_like

only loop on the non-zero elements coinciding with the atoms

Examples

>>> for i, j in self.iter_nnz():
...    self[i, j] # is then the non-zero value
remove(atom)[source]

Create a subset of this sparse matrix by removing the elements corresponding to atom

Indices passed MUST be unique.

Negative indices are wrapped and thus works.

Parameters:

atom : array_like of int

indices of removed atoms
repeat(reps, axis)[source]

Create a repeated sparse atom object, equivalent to Geometry.repeat

The already existing sparse elements are extrapolated to the new supercell by repeating them in blocks like the coordinates.

Parameters:

reps : int

number of repetitions along cell-vector axis

axis : int

0, 1, 2 according to the cell-direction
sub(atom)[source]

Create a subset of this sparse matrix by only retaining the elements corresponding to the atom

Indices passed MUST be unique.

Negative indices are wrapped and thus works.

Parameters:

atom : array_like of int

indices of retained atoms
tile(reps, axis)[source]

Create a tiled sparse atom object, equivalent to Geometry.tile

The already existing sparse elements are extrapolated to the new supercell by repeating them in blocks like the coordinates.

Parameters:

reps : int

number of repetitions along cell-vector axis

axis : int

0, 1, 2 according to the cell-direction
class sisl.sparse_geometry.SparseOrbital(geom, dim=1, dtype=None, nnzpr=None, **kwargs)[source]

Bases: sisl.sparse_geometry.SparseGeometry

Sparse object with number of rows equal to the total number of orbitals in the Geometry

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
cut(seps, axis, *args, **kwargs) Cuts the sparse orbital model into different parts.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz([atom, orbital]) Iterations of the non-zero elements
repeat(reps, axis) Create a repeated sparse orbital object, equivalent to Geometry.repeat
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
sub(atom) Create a subset of this sparse matrix by only retaining the elements corresponding to the atom
tile(reps, axis) Create a tiled sparse orbital object, equivalent to Geometry.tile
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index

Create sparse object with element between orbitals

Attributes

dim Number of components per element
dkind Data type of sparse elements (in str)
dtype Data type of sparse elements
finalized Whether the contained data is finalized and non-used elements have been removed
geom Associated geometry
geometry Associated geometry
nnz Number of non-zero elements
shape Shape of sparse matrix

Methods

align(other) See SparseCSR.align for details
construct(func[, na_iR, method, eta]) Automatically construct the sparse model based on a function that does the setting up of the elements
copy([dtype]) A copy of this object
create_construct(R, param) Create a simple function for passing to the construct function.
cut(seps, axis, *args, **kwargs) Cuts the sparse orbital model into different parts.
eliminate_zeros() Removes all zero elements from the sparse matrix
empty([keep]) See SparseCSR.empty for details
finalize() Finalizes the model
fromsp(geom, sp) Returns a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz([atom, orbital]) Iterations of the non-zero elements
repeat(reps, axis) Create a repeated sparse orbital object, equivalent to Geometry.repeat
reset([dim, dtype, nnzpr]) The sparsity pattern is cleaned and every thing is reset.
spsame(other) Compare two sparse objects and check whether they have the same entries.
sub(atom) Create a subset of this sparse matrix by only retaining the elements corresponding to the atom
tile(reps, axis) Create a tiled sparse orbital object, equivalent to Geometry.tile
tocsr(index[, isc]) Return a scipy.sparse.csr_matrix of the specified index
cut(seps, axis, *args, **kwargs)[source]

Cuts the sparse orbital model into different parts.

Recreates a new sparse orbital object with only the cutted atoms in the structure.

Cutting is the opposite of tiling.

Parameters:

seps : int, optional

number of times the structure will be cut

axis : int

the axis that will be cut
iter_nnz(atom=None, orbital=None)[source]

Iterations of the non-zero elements

An iterator on the sparse matrix with, row and column

Parameters:

atom : int or array_like

only loop on the non-zero elements coinciding with the orbitals on these atoms (not compatible with the orbital keyword)

orbital : int or array_like

only loop on the non-zero elements coinciding with the orbital (not compatible with the atom keyword)

Examples

>>> for i, j in self.iter_nnz():
...    self[i, j] # is then the non-zero value
repeat(reps, axis)[source]

Create a repeated sparse orbital object, equivalent to Geometry.repeat

The already existing sparse elements are extrapolated to the new supercell by repeating them in blocks like the coordinates.

Parameters:

reps : int

number of repetitions along cell-vector axis

axis : int

0, 1, 2 according to the cell-direction
sub(atom)[source]

Create a subset of this sparse matrix by only retaining the elements corresponding to the atom

Indices passed MUST be unique.

Negative indices are wrapped and thus works.

Parameters:

atom : array_like of int

indices of retained atoms
tile(reps, axis)[source]

Create a tiled sparse orbital object, equivalent to Geometry.tile

The already existing sparse elements are extrapolated to the new supercell by repeating them in blocks like the coordinates.

Parameters:

reps : int

number of repetitions along cell-vector axis

axis : int

0, 1, 2 according to the cell-direction