SparseAtom¶
-
class
sisl.
SparseAtom
(geometry, dim=1, dtype=None, nnzpr=None, **kwargs)[source]¶ 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
Rij
([dtype])Create a sparse matrix with the vectors between atoms __init__
(geometry[, dim, dtype, nnzpr])Create sparse object with element between orbitals 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. edges
(atom[, exclude])Retrieve edges (connections) of a given atom
or list ofatom
’seliminate_zeros
([atol])Removes all zero elements from the sparse matrix empty
([keep_nnz])See empty
for detailsfinalize
()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 make_hermitian
()Ensures the matrix is Hermitian by doing an in-place symmetrization nonzero
([atom, only_col])Indices row and column indices where non-zero elements exists remove
(atom)Create a subset of this sparse matrix by removing the atoms corresponding to atom
repeat
(reps, axis)Create a repeated sparse atom object, equivalent to Geometry.repeat
reset
([dim, dtype, nnzpr])The sparsity pattern has all elements removed and everything is reset. rij
([dtype])Create a sparse matrix with the distance between atoms set_nsc
(*args, **kwargs)Reset the number of allowed supercells in the sparse atom spalign
(other)See align
for detailsspsame
(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
swap
(a, b)Swaps atoms in the sparse geometry to obtain a new order of atoms 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-
Rij
(dtype=<class 'numpy.float64'>)[source]¶ Create a sparse matrix with the vectors between atoms
Parameters: - dtype : numpy.dtype, optional
the data-type of the sparse matrix.
Notes
The returned sparse matrix with vectors are taken from the current sparse pattern. I.e. a subsequent addition of sparse elements will make them inequivalent. It is thus important to only create the sparse vector matrix when the sparse structure is completed.
-
construct
(func, na_iR=1000, method='rand', eta=False)¶ Automatically construct the sparse model based on a function that does the setting up of the elements
This may be called in two variants.
- Pass a function (
func
), see e.g.create_construct
which does the setting up. - Pass a tuple/list in
func
which consists of two elements, one isR
the radii parameters for the corresponding parameters. The second is the parameters corresponding to theR[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.geometry.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}
method used in
Geometry.iter_block
, see there for details- eta: bool, optional
whether an ETA will be printed
See also
create_construct
- a generic function used to create a generic function which this routine requires
tile
- tiling after construct is much faster for very large systems
repeat
- repeating after construct is much faster for very large systems
- Pass a function (
-
copy
(dtype=None)¶ 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)¶ 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.geometry.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 withR[0]/100
- param : array_like
coupling constants corresponding to the
R
ranges.param[0,:]
are the elements for the all atoms withinR[0]
of each atom.
See also
construct
- routine to create the sparse matrix from a generic function (as returned from
create_construct
)
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.
-
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
number of times the structure will be cut
- axis : int
the axis that will be cut
-
dim
¶ Number of components per element
-
dkind
¶ Data type of sparse elements (in str)
-
dtype
¶ Data type of sparse elements
-
edges
(atom, exclude=None)¶ Retrieve edges (connections) of a given
atom
or list ofatom
’sThe returned edges are unique and sorted (see
numpy.unique
) and are returned in supercell indices (i.e.0 <= edge < self.geometry.na_s
).Parameters: - atom : int or list of int
the edges are returned only for the given atom
- exclude : int or list of int, optional
remove edges which are in the exclude list. Default to
atom
.
See also
SparseCSR.edges
- the underlying routine used for extracting the edges
-
eliminate_zeros
(atol=0.0)¶ Removes all zero elements from the sparse matrix
This is an in-place operation.
Parameters: - atol : float, optional
absolute tolerance below this value will be considered 0.
-
empty
(keep_nnz=False)¶ See
empty
for details
-
finalize
()¶ 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 a 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)¶ Returns a sparse model from a preset Geometry and a list of sparse matrices
-
geom
¶ Associated geometry
-
geometry
¶ Associated geometry
-
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
-
make_hermitian
()¶ Ensures the matrix is Hermitian by doing an in-place symmetrization
-
nnz
¶ Number of non-zero elements
-
nonzero
(atom=None, only_col=False)[source]¶ Indices row and column indices where non-zero elements exists
Parameters: - atom : int or array_like of int, optional
only return the tuples for the requested atoms, default is all atoms
- only_col : bool, optional
only return then non-zero columns
See also
SparseCSR.nonzero
- the equivalent function call
-
remove
(atom)¶ Create a subset of this sparse matrix by removing the atoms corresponding to
atom
Negative indices are wrapped and thus works.
Parameters: - atom : array_like of int
indices of removed atoms
See also
Geometry.remove
- equivalent to the resulting
Geometry
from this routine Geometry.sub
- the negative of
Geometry.remove
sub
- the opposite of
remove
, i.e. retain a subset of 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
See also
Geometry.repeat
- the same ordering as the final geometry
Geometry.tile
- a different ordering of the final geometry
tile
- a different ordering of the final geometry
-
reset
(dim=None, dtype=<class 'numpy.float64'>, nnzpr=None)¶ The sparsity pattern has all elements removed and everything 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, default to the current number of elements per matrix element.
- dtype: numpy.dtype, optional
the datatype of the sparse elements
- nnzpr: int, optional
number of non-zero elements per row
-
rij
(dtype=<class 'numpy.float64'>)[source]¶ Create a sparse matrix with the distance between atoms
Parameters: - dtype : numpy.dtype, optional
the data-type of the sparse matrix.
Notes
The returned sparse matrix with distances are taken from the current sparse pattern. I.e. a subsequent addition of sparse elements will make them inequivalent. It is thus important to only create the sparse distance when the sparse structure is completed.
-
set_nsc
(*args, **kwargs)[source]¶ Reset the number of allowed supercells in the sparse atom
If one reduces the number of supercells any sparse element that references the supercell will be deleted.
See
SuperCell.set_nsc
for allowed parameters.See also
SuperCell.set_nsc
- the underlying called method
-
shape
¶ Shape of sparse matrix
-
spalign
(other)¶ See
align
for details
-
spsame
(other)¶ Compare two sparse objects and check whether they have the same entries.
This does not necessarily mean that the elements are the same
-
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
See also
Geometry.remove
- the negative of
Geometry.sub
Geometry.sub
- equivalent to the resulting
Geometry
from this routine remove
- the negative of
sub
, i.e. remove a subset of atoms
-
swap
(a, b)¶ Swaps atoms in the sparse geometry to obtain a new order of atoms
This can be used to reorder elements of a geometry.
Parameters: - a : array_like
the first list of atomic coordinates
- b : array_like
the second list of atomic coordinates
-
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
See also
Geometry.tile
- the same ordering as the final geometry
Geometry.repeat
- a different ordering of the final geometry
repeat
- a different ordering of the final geometry
Notes
Calling this routine will automatically
finalize
theSparseAtom
. This is required to greatly increase performance.
-
tocsr
(index, isc=None, **kwargs)¶ Return a
scipy.sparse.csr_matrix
of the specified indexParameters: - 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
)
-