SparseOrbitalBZSpin¶
-
class
sisl.physics.
SparseOrbitalBZSpin
(geom, dim=1, dtype=None, nnzpr=None, **kwargs)[source]¶ Sparse object containing the orbital connections in a Brillouin zone with possible spin-components
It contains an intrinsic sparse matrix of the physical elements.
Assigning or changing elements is as easy as with standard
numpy
assignments:>>> S = SparseOrbitalBZSpin(...) >>> S[1,2] = 0.1
which assigns 0.1 as the element between orbital 2 and 3. (remember that Python is 0-based elements).
Attributes
S
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 non_orthogonal
True if the object is using a non-orthogonal basis orthogonal
True if the object is using an orthogonal basis shape
Shape of sparse matrix spin
Associated spin class Methods
Rij
([what, dtype])Create a sparse matrix with the vectors between atoms/orbitals Sk
([k, dtype, gauge, format])Setup the overlap matrix for a given k-point __init__
(geom[, dim, dtype, nnzpr])Create SparseOrbitalBZSpin model from geometry 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. edges
([atom, exclude, orbital])Retrieve edges (connections) of a given atom or list of atom‘s eigh
([k, atoms, gauge, eigvals_only])Returns the eigenvalues of the physical quantity eigsh
([k, n, atoms, gauge, eigvals_only])Calculates a subset of eigenvalues of the physical quantity (default 10) eliminate_zeros
()Removes all zero elements from the sparse matrix empty
([keep_nnz])See SparseCSR.empty for details finalize
()Finalizes the model fromsp
(geom, P[, S])Read and return the object with possible overlap iter
([local])Iterations of the orbital space in the geometry, two indices from loop iter_nnz
([atom, orbital])Iterations of the non-zero elements 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 orbital object, equivalent to Geometry.repeat reset
([dim, dtype, nnzpr])The sparsity pattern has all elements removed and everything is reset. rij
([what, dtype])Create a sparse matrix with the distance between atoms/orbitals set_nsc
(*args, **kwargs)Reset the number of allowed supercells in the sparse orbital spalign
(other)See SparseCSR.align for details 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 atoms corresponding to atom swap
(a, b)Swaps atoms in the sparse geometry to obtain a new order of atoms 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-
Rij
(what=None, dtype=<type 'numpy.float64'>)¶ Create a sparse matrix with the vectors between atoms/orbitals
Parameters: what : {None, ‘atom’, ‘orbital’}
which kind of sparse vector matrix to return, either an atomic vector matrix or an orbital vector matrix. The orbital matrix is equivalent to the atomic one with the same vectors repeated for the same atomic orbitals. The default is the same type as the parent class.
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.
-
S
¶
-
Sk
(k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)¶ Setup the overlap matrix for a given k-point
Creation and return of the overlap matrix for a given k-point (default to Gamma).
Parameters: k : array_like, optional
the k-point to setup the overlap at (default Gamma point)
dtype : numpy.dtype, optional
the data type of the returned matrix. Do NOT request non-complex data-type for non-Gamma k. The default data-type is
numpy.complex128
gauge : {‘R’, ‘r’}
the chosen gauge, R for cell vector gauge, and r for orbital distance gauge.
format : {‘csr’, ‘array’, ‘dense’, ‘coo’, ...}
the returned format of the matrix, defaulting to the
scipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(‘array’) ornumpy.matrix
(‘dense’).Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[S(k) = S_{ij} e^{i k R}\]where \(R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices.
Another possible gauge is the orbital distance which can be written as
\[S(k) = S_{ij} e^{i k r}\]where \(r\) is the distance between the orbitals \(i\) and \(j\). Currently the second gauge is not implemented (yet).
-
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.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}
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.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 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)¶ 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
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=None, exclude=None, orbital=None)¶ Retrieve edges (connections) of a given atom or list of atom‘s
The returned edges are unique and sorted (see
numpy.unique
) and are returned in supercell indices (i.e.0 <= edge < self.geom.no_s
).Parameters: atom : int or list of int
the edges are returned only for the given atom (but by using all orbitals of the requested atom). The returned edges are also atoms.
exclude : int or list of int, optional
remove edges which are in the exclude list. Default to atom.
orbital : int or list of int
the edges are returned only for the given orbital. The returned edges are orbitals.
See also
SparseCSR.edges
- the underlying routine used for extracting the edges
-
eigh
(k=(0, 0, 0), atoms=None, gauge='R', eigvals_only=True, **kwargs)[source]¶ Returns the eigenvalues of the physical quantity
Setup the system and overlap matrix with respect to the given k-point, then reduce the space to the specified atoms and calculate the eigenvalues.
All subsequent arguments gets passed directly to
scipy.linalg.eigh
-
eigsh
(k=(0, 0, 0), n=10, atoms=None, gauge='R', eigvals_only=True, **kwargs)[source]¶ Calculates a subset of eigenvalues of the physical quantity (default 10)
Setup the quantity and overlap matrix with respect to the given k-point, then reduce the space to the specified atoms and calculate a subset of the eigenvalues using the sparse algorithms.
All subsequent arguments gets passed directly to
scipy.linalg.eigsh
-
eliminate_zeros
()¶ Removes all zero elements from the sparse matrix
This is an in-place operation.
-
empty
(keep_nnz=False)¶ See SparseCSR.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
-
fromsp
(geom, P, S=None)¶ Read and return the object with possible overlap
-
geom
¶ Associated geometry
-
geometry
¶ Associated geometry
-
iter
(local=False)¶ Iterations of the orbital space in the geometry, two indices from loop
An iterator returning the current atomic index and the corresponding orbital index.
>>> for ia, io in self:
In the above case
io
always belongs to atom ia and ia may be repeated according to the number of orbitals associated with the atom ia.Parameters: local : bool, optional
whether the orbital index is the global index, or the local index relative to the atom it resides on.
-
iter_nnz
(atom=None, orbital=None)¶ 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
-
nnz
¶ Number of non-zero elements
-
non_orthogonal
¶ True if the object is using a non-orthogonal basis
-
nonzero
(atom=None, only_col=False)¶ 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 But for all orbitals.
only_col : bool, optional
only return then non-zero columns
See also
SparseCSR.nonzero
- the equivalent function call
-
orthogonal
¶ True if the object is using an orthogonal basis
-
remove
(atom)¶ Create a subset of this sparse matrix by removing the atoms 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)¶ 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
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=<type '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
(what=None, dtype=<type 'numpy.float64'>)¶ Create a sparse matrix with the distance between atoms/orbitals
Parameters: what : {None, ‘atom’, ‘orbital’}
which kind of sparse distance matrix to return, either an atomic distance matrix or an orbital distance matrix. The orbital matrix is equivalent to the atomic one with the same distance repeated for the same atomic orbitals. The default is the same type as the parent class.
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)¶ Reset the number of allowed supercells in the sparse orbital
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 SparseCSR.align for details
-
spin
¶ Associated spin class
-
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)¶ Create a subset of this sparse matrix by only retaining the atoms corresponding to atom
Indices passed MUST be unique.
Negative indices are wrapped and thus works.
Parameters: atom : array_like of int
indices of retained 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)¶ 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
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
-
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
)
-