DensityMatrix¶
-
class
sisl.physics.
DensityMatrix
(geometry, dim=1, dtype=None, nnzpr=None, **kwargs)[source]¶ Sparse density matrix object
Assigning or changing elements is as easy as with standard
numpy
assignments:>>> DM = DensityMatrix(...) >>> DM.D[1,2] = 0.1
which assigns 0.1 as the density element between orbital 2 and 3. (remember that Python is 0-based elements).
- Parameters
- geometryGeometry
parent geometry to create a density matrix from. The density matrix will have size equivalent to the number of orbitals in the geometry
- dimint or Spin, optional
number of components per element, may be a
Spin
object- dtypenp.dtype, optional
data type contained in the density matrix. See details of
Spin
for default values.- nnzprint, optional
number of initially allocated memory per orbital in the density matrix. For increased performance this should be larger than the actual number of entries per orbital.
- spinSpin, optional
equivalent to
dim
argument. This keyword-only argument has precedence overdim
.- orthogonalbool, optional
whether the density matrix corresponds to a non-orthogonal basis. In this case the dimensionality of the density matrix is one more than
dim
. This is a keyword-only argument.
Attributes
Access elements to the sparse density matrix
Access elements to the sparse overlap
Number of components per element
Data type of sparse elements (in str)
Data type of sparse elements
Whether the contained data is finalized and non-used elements have been removed
Associated geometry
Associated geometry
Number of non-zero elements
True if the object is using a non-orthogonal basis
True if the object is using an orthogonal basis
Shape of sparse matrix
Associated spin class
Methods
Dk
(self[, k, dtype, gauge, format])Setup the density matrix for a given k-point
Rij
(self[, what, dtype])Create a sparse matrix with the vectors between atoms/orbitals
Sk
(self[, k, dtype, gauge, format])Setup the overlap matrix for a given k-point
__init__
(self, geometry[, dim, dtype, nnzpr])Initialize density matrix
append
(self, other, axis[, eps])Append other along axis to construct a new connected sparse matrix
charge
(self[, method])Calculate orbital charges based on the density matrix
construct
(self, func[, na_iR, method, eta])Automatically construct the sparse model based on a function that does the setting up of the elements
copy
(self[, dtype])A copy of this object
create_construct
(self, R, param)Create a simple function for passing to the
construct
function.cut
(self, seps, axis, \*args, \*\*kwargs)Cuts the sparse orbital model into different parts.
dDk
(self[, k, dtype, gauge, format])Setup the density matrix derivative for a given k-point
dSk
(self[, k, dtype, gauge, format])Setup the \(k\)-derivatie of the overlap matrix for a given k-point
ddDk
(self[, k, dtype, gauge, format])Setup the density matrix double derivative for a given k-point
ddSk
(self[, k, dtype, gauge, format])Setup the double \(k\)-derivatie of the overlap matrix for a given k-point
density
(self, grid[, spinor, tol, eta])Expand the density matrix to the charge density on a grid
edges
(self[, atom, exclude, orbital])Retrieve edges (connections) of a given atom or list of atom’s
eig
(self[, k, gauge, eigvals_only])Returns the eigenvalues of the physical quantity (using the non-Hermitian solver)
eigh
(self[, k, gauge, eigvals_only])Returns the eigenvalues of the physical quantity
eigsh
(self[, k, n, gauge, eigvals_only])Calculates a subset of eigenvalues of the physical quantity (default 10)
eliminate_zeros
(self[, atol])Removes all zero elements from the sparse matrix
empty
(self[, keep_nnz])See
empty
for detailsfinalize
(self)Finalizes the model
fromsp
(geometry, P[, S])Read and return the object with possible overlap
iter
(self[, local])Iterations of the orbital space in the geometry, two indices from loop
iter_nnz
(self[, atom, orbital])Iterations of the non-zero elements
nonzero
(self[, atom, only_col])Indices row and column indices where non-zero elements exists
prepend
(self, other, axis[, eps])See
append
for detailsread
(sile, \*args, \*\*kwargs)Reads density matrix from Sile using read_density_matrix.
remove
(self, atom[, orb_index])Remove a subset of this sparse matrix by only retaining the atoms corresponding to atom
remove_orbital
(self, atom, orbital)Remove a subset of orbitals on atom according to orbital
repeat
(self, reps, axis)Create a repeated sparse orbital object, equivalent to Geometry.repeat
reset
(self[, dim, dtype, nnzpr])The sparsity pattern has all elements removed and everything is reset.
rij
(self[, what, dtype])Create a sparse matrix with the distance between atoms/orbitals
set_nsc
(self, \*args, \*\*kwargs)Reset the number of allowed supercells in the sparse orbital
spalign
(self, other)See
align
for detailsspsame
(self, other)Compare two sparse objects and check whether they have the same entries.
sub
(self, atom)Create a subset of this sparse matrix by only retaining the atoms corresponding to atom
sub_orbital
(self, atom, orbital)Retain only a subset of the orbitals on atom according to orbital
swap
(self, a, b)Swaps atoms in the sparse geometry to obtain a new order of atoms
tile
(self, reps, axis)Create a tiled sparse orbital object, equivalent to Geometry.tile
toSparseAtom
(self[, dim, dtype])Convert the sparse object (without data) to a new sparse object with equivalent but reduced sparse pattern
tocsr
(self[, dim, isc])Return a
csr_matrix
for the specified dimensiontranspose
(self)Create the transposed sparse geometry by interchanging supercell indices
write
(self, sile, \*args, \*\*kwargs)Writes a density matrix to the Sile as implemented in the
Sile.write_density_matrix
method-
property
D
¶ Access elements to the sparse density matrix
-
Dk
(self, k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)[source]¶ Setup the density matrix for a given k-point
Creation and return of the density matrix for a given k-point (default to Gamma).
- Parameters
- karray_like
the k-point to setup the density matrix at
- dtypenumpy.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’/’dense’/’matrix’).- spinint, optional
if the density matrix is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the density matrix is not
Spin.POLARIZED
this keyword is ignored.
- Returns
- objectthe density matrix at \(k\). The returned object depends on format.
See also
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\mathbf D(k) = \mathbf D_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices.
Another possible gauge is the orbital distance which can be written as
\[\mathbf D(k) = \mathbf D_{\nu\mu} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
Rij
(self, what='orbital', dtype=<class 'numpy.float64'>)¶ Create a sparse matrix with the vectors between atoms/orbitals
- Parameters
- what{‘orbital’, ‘atom’}
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.
- dtypenumpy.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.
-
property
S
¶ Access elements to the sparse overlap
-
Sk
(self, 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
- karray_like, optional
the k-point to setup the overlap at (default Gamma point)
- dtypenumpy.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’, ‘matrix’, ‘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’/’dense’/’matrix’).
- Returns
- objectthe overlap matrix for the \(k\)-point, format determines the object type.
See also
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\mathbf S(k) = \mathbf S_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices.
Another possible gauge is the orbital distance which can be written as
\[\mathbf S(k) = \mathbf S_{\nu\mu} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
append
(self, other, axis, eps=0.01)¶ Append other along axis to construct a new connected sparse matrix
This method tries to append two sparse geometry objects together by the following these steps:
Create the new extended geometry
Use neighbor cell couplings from self as the couplings to other This may cause problems if the coupling atoms are not exactly equi-positioned. If the coupling coordinates and the coordinates in other differ by more than 0.001 Ang, a warning will be issued. If this difference is above eps the couplings will be removed.
When appending sparse matrices made up of atoms, this method assumes that the orbitals on the overlapping atoms have the same orbitals, as well as the same orbital ordering.
- Parameters
- otherobject
must be an object of the same type as self
- axisint
axis to append the two sparse geometries along
- epsfloat, optional
tolerance that all coordinates must be within to allow an append. It is important that this value is smaller than half the distance between the two closests atoms such that there is no ambiguity in selecting equivalent atoms. An internal stricter eps is used as a baseline, see above.
- Returns
- object
a new instance with two sparse matrices joined and appended together
- Raises
- ValueError if atomic coordinates does not overlap within eps
See also
Notes
This routine and how it is functioning may change in future releases. There are many design choices in how to assign the matrix elements when combining two models and it is not clear what is the best procedure.
The current implentation does not preserve the hermiticity of the matrix.
Examples
>>> sporb = SparseOrbital(....) >>> forced_hermitian = (sporb + sporb.transpose()) * 0.5
-
charge
(self, method='mulliken')[source]¶ Calculate orbital charges based on the density matrix
This returns CSR-matrices with each spin-components charges.
- Parameters
- methodstr, optional
choice of method to calculate the charges, currently only Mulliken is allowed
- Returns
- chargecsr_matrix of charges
-
construct
(self, 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 is
R
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
- funccallable 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_iRint, 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
- etabool, 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
-
copy
(self, dtype=None)¶ A copy of this object
- Parameters
- dtypenumpy.dtype, optional
it is possible to convert the data to a different data-type If not specified, it will use
self.dtype
-
create_construct
(self, 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
- Rarray_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
- paramarray_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
(self, 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
- sepsint
number of times the structure will be cut
- axisint
the axis that will be cut
-
dDk
(self, k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)[source]¶ Setup the density matrix derivative for a given k-point
Creation and return of the density matrix derivative for a given k-point (default to Gamma).
- Parameters
- karray_like
the k-point to setup the density matrix at
- dtypenumpy.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’/’dense’/’matrix’).- spinint, optional
if the density matrix is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the density matrix is not
Spin.POLARIZED
this keyword is ignored.
- Returns
- tuplefor each of the Cartesian directions a \(\partial \mathbf D(k)/\partial k\) is returned.
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_k \mathbf D_\alpha(k) = i R_\alpha \mathbf D_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices. And \(\alpha\) is one of the Cartesian directions.
Another possible gauge is the orbital distance which can be written as
\[\nabla_k \mathbf D_\alpha(k) = i r_\alpha \mathbf D_{\nu\mu} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
dSk
(self, k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)¶ Setup the \(k\)-derivatie of the overlap matrix for a given k-point
Creation and return of the derivative of the overlap matrix for a given k-point (default to Gamma).
- Parameters
- karray_like, optional
the k-point to setup the overlap at (default Gamma point)
- dtypenumpy.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’, ‘matrix’, ‘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’/’dense’/’matrix’).
- Returns
- tuplefor each of the Cartesian directions a \(\partial \mathbf S(k)/\partial k\) is returned.
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_k \mathbf S_\alpha(k) = i R_\alpha \mathbf S_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices. And \(\alpha\) is one of the Cartesian directions.
Another possible gauge is the orbital distance which can be written as
\[\nabla_k \mathbf S_\alpha(k) = i r_\alpha \mathbf S_{ij} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
ddDk
(self, k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)[source]¶ Setup the density matrix double derivative for a given k-point
Creation and return of the density matrix double derivative for a given k-point (default to Gamma).
- Parameters
- karray_like
the k-point to setup the density matrix at
- dtypenumpy.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’/’dense’/’matrix’).- spinint, optional
if the density matrix is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the density matrix is not
Spin.POLARIZED
this keyword is ignored.
- Returns
- tuple of tuplesfor each of the Cartesian directions
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_k^2 \mathbf D_{\alpha\beta}(k) = - R_\alpha R_\beta \mathbf D_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices. And \(\alpha\) and \(\beta\) are one of the Cartesian directions.
Another possible gauge is the orbital distance which can be written as
\[\nabla_k^2 \mathbf D_{\alpha\beta}(k) = - r_\alpha r_\beta \mathbf D_{\nu\mu} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
ddSk
(self, k=(0, 0, 0), dtype=None, gauge='R', format='csr', *args, **kwargs)¶ Setup the double \(k\)-derivatie of the overlap matrix for a given k-point
Creation and return of the double derivative of the overlap matrix for a given k-point (default to Gamma).
- Parameters
- karray_like, optional
the k-point to setup the overlap at (default Gamma point)
- dtypenumpy.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’, ‘matrix’, ‘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’/’dense’/’matrix’).
- Returns
- tuple of tuplesfor each of the Cartesian directions
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_k^2 \mathbf S_{\alpha\beta}(k) = - R_\alpha R_\beta \mathbf S_{\nu\mu} e^{i k R}\]where \(R\) is an integer times the cell vector and \(\nu\), \(\mu\) are orbital indices. And \(\alpha\) and \(\beta\) are one of the Cartesian directions.
Another possible gauge is the orbital distance which can be written as
\[\nabla_k^2 \mathbf S_{\alpha\beta}(k) = - r_\alpha r_\beta \mathbf S_{ij} e^{i k r}\]where \(r\) is the distance between the orbitals.
-
density
(self, grid, spinor=None, tol=1e-07, eta=False)¶ Expand the density matrix to the charge density on a grid
This routine calculates the real-space density components on a specified grid.
This is an in-place operation that adds to the current values in the grid.
Note: To calculate \(\rho(\mathbf r)\) in a unit-cell different from the originating geometry, simply pass a grid with a unit-cell different than the originating supercell.
The real-space density is calculated as:
\[\rho(\mathbf r) = \sum_{\nu\mu}\phi_\nu(\mathbf r)\phi_\mu(\mathbf r) D_{\nu\mu}\]While for non-collinear/spin-orbit calculations the density is determined from the spinor component (spinor) by
\[\rho_{\boldsymbol\sigma}(\mathbf r) = \sum_{\nu\mu}\phi_\nu(\mathbf r)\phi_\mu(\mathbf r) \sum_\alpha [\boldsymbol\sigma \mathbf \rho_{\nu\mu}]_{\alpha\alpha}\]Here \(\boldsymbol\sigma\) corresponds to a spinor operator to extract relevant quantities. By passing the identity matrix the total charge is added. By using the Pauli matrix \(\boldsymbol\sigma_x\) only the \(x\) component of the density is added to the grid (see
Spin.X
).- Parameters
- gridGrid
the grid on which to add the density (the density is in
e/Ang^3
)- spinor(2,) or (2, 2), optional
the spinor matrix to obtain the diagonal components of the density. For un-polarized density matrices this keyword has no influence. For spin-polarized it has to be either 1 integer or a vector of length 2 (defaults to total density). For non-collinear/spin-orbit density matrices it has to be a 2x2 matrix (defaults to total density).
- tolfloat, optional
DM tolerance for accepted values. For all density matrix elements with absolute values below the tolerance, they will be treated as strictly zeros.
- etabool, optional
show a progressbar on stdout
-
property
dim
¶ Number of components per element
-
property
dkind
¶ Data type of sparse elements (in str)
-
property
dtype
¶ Data type of sparse elements
-
edges
(self, 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.geometry.no_s
).- Parameters
- atomint 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.
- excludeint or list of int, optional
remove edges which are in the exclude list. Default to atom.
- orbitalint 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
-
eig
(self, k=(0, 0, 0), gauge='R', eigvals_only=True, **kwargs)¶ Returns the eigenvalues of the physical quantity (using the non-Hermitian solver)
Setup the system and overlap matrix with respect to the given k-point and calculate the eigenvalues.
All subsequent arguments gets passed directly to
scipy.linalg.eig
- Parameters
- spinint, optional
the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid for
Spin.POLARIZED
matrices.
-
eigh
(self, k=(0, 0, 0), gauge='R', eigvals_only=True, **kwargs)¶ Returns the eigenvalues of the physical quantity
Setup the system and overlap matrix with respect to the given k-point and calculate the eigenvalues.
All subsequent arguments gets passed directly to
scipy.linalg.eigh
- Parameters
- spinint, optional
the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid for
Spin.POLARIZED
matrices.
-
eigsh
(self, k=(0, 0, 0), n=10, gauge='R', eigvals_only=True, **kwargs)¶ Calculates a subset of eigenvalues of the physical quantity (default 10)
Setup the quantity and overlap matrix with respect to the given k-point and calculate a subset of the eigenvalues using the sparse algorithms.
All subsequent arguments gets passed directly to
scipy.linalg.eigsh
- Parameters
- spinint, optional
the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid for
Spin.POLARIZED
matrices.
-
eliminate_zeros
(self, atol=0.0)¶ Removes all zero elements from the sparse matrix
This is an in-place operation.
- Parameters
- atolfloat, optional
absolute tolerance equal or below this value will be considered 0.
-
empty
(self, keep_nnz=False)¶ See
empty
for details
-
finalize
(self)¶ 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.
-
property
finalized
¶ Whether the contained data is finalized and non-used elements have been removed
-
classmethod
fromsp
(geometry, P, S=None)¶ Read and return the object with possible overlap
-
property
geom
¶ Associated geometry
-
property
geometry
¶ Associated geometry
-
iter
(self, 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
- localbool, optional
whether the orbital index is the global index, or the local index relative to the atom it resides on.
-
iter_nnz
(self, atom=None, orbital=None)¶ Iterations of the non-zero elements
An iterator on the sparse matrix with, row and column
- Parameters
- atomint or array_like
only loop on the non-zero elements coinciding with the orbitals on these atoms (not compatible with the
orbital
keyword)- orbitalint 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
-
property
nnz
¶ Number of non-zero elements
-
property
non_orthogonal
¶ True if the object is using a non-orthogonal basis
-
nonzero
(self, atom=None, only_col=False)¶ Indices row and column indices where non-zero elements exists
- Parameters
- atomint or array_like of int, optional
only return the tuples for the requested atoms, default is all atoms But for all orbitals.
- only_colbool, optional
only return then non-zero columns
See also
SparseCSR.nonzero
the equivalent function call
-
property
orthogonal
¶ True if the object is using an orthogonal basis
-
prepend
(self, other, axis, eps=0.01)¶ See
append
for detailsThis is currently equivalent to:
>>> other.append(self, axis, eps)
-
static
read
(sile, *args, **kwargs)[source]¶ Reads density matrix from Sile using read_density_matrix.
- Parameters
- sileSile, str or pathlib.Path
a Sile object which will be used to read the density matrix and the overlap matrix (if any) if it is a string it will create a new sile using get_sile.
- *args passed directly to
read_density_matrix(,**)
-
remove
(self, atom, orb_index=None)¶ Remove a subset of this sparse matrix by only retaining the atoms corresponding to atom
- Parameters
- atomarray_like of int or Atom
indices of removed atoms or Atom for direct removal of all atoms
-
remove_orbital
(self, atom, orbital)¶ Remove a subset of orbitals on atom according to orbital
- Parameters
- atomarray_like of int or Atom
indices of atoms or Atom that will be reduced in size according to orbital
- orbitalarray_like of int or Orbital
indices of the orbitals on atom that are removed from the sparse matrix.
Examples
>>> obj = SparseOrbital(...) >>> # remove the second orbital on the 2nd atom >>> # all other orbitals are retained >>> obj.remove_orbital(1, 1)
-
repeat
(self, 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
- repsint
number of repetitions along cell-vector axis
- axisint
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
(self, 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
- dimint, optional
number of dimensions per element, default to the current number of elements per matrix element.
- dtypenumpy.dtype, optional
the datatype of the sparse elements
- nnzprint, optional
number of non-zero elements per row
-
rij
(self, what='orbital', dtype=<class 'numpy.float64'>)¶ Create a sparse matrix with the distance between atoms/orbitals
- Parameters
- what{‘orbital’, ‘atom’}
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.
- dtypenumpy.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
(self, *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
-
property
shape
¶ Shape of sparse matrix
-
spalign
(self, other)¶ See
align
for details
-
property
spin
¶ Associated spin class
-
spsame
(self, 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
(self, atom)¶ Create a subset of this sparse matrix by only retaining the atoms corresponding to atom
Negative indices are wrapped and thus works, supercell atoms are also wrapped to the unit-cell.
- Parameters
- atomarray_like of int or Atom
indices of retained atoms or Atom for retaining only that atom
See also
Examples
>>> obj = SparseOrbital(...) >>> obj.sub(1) # only retain the second atom in the SparseGeometry >>> obj.sub(obj.atoms.atom[0]) # retain all atoms which is equivalent to >>> # the first atomic specie
-
sub_orbital
(self, atom, orbital)¶ Retain only a subset of the orbitals on atom according to orbital
This allows one to retain only a given subset of the sparse matrix elements.
- Parameters
- atomarray_like of int or Atom
indices of atoms or Atom that will be reduced in size according to orbital
- orbitalarray_like of int or Orbital
indices of the orbitals on atom that are retained in the sparse matrix, the list of orbitals will be sorted. One cannot re-arrange matrix elements currently.
Notes
Future implementations may allow one to re-arange orbitals using this method.
Examples
>>> obj = SparseOrbital(...) >>> # only retain the second orbital on the 2nd atom >>> # all other orbitals are retained >>> obj.sub_orbital(1, 1)
-
swap
(self, 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
- aarray_like
the first list of atomic coordinates
- barray_like
the second list of atomic coordinates
-
tile
(self, 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
- repsint
number of repetitions along cell-vector axis
- axisint
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
-
toSparseAtom
(self, dim=None, dtype=None)¶ Convert the sparse object (without data) to a new sparse object with equivalent but reduced sparse pattern
This converts the orbital sparse pattern to an atomic sparse pattern.
- Parameters
- dimint, optional
number of dimensions allocated in the SparseAtom object, default to the same
- dtypenumpy.dtype, optional
used data-type for the sparse object. Defaults to the same.
-
tocsr
(self, dim=0, isc=None, **kwargs)¶ Return a
csr_matrix
for the specified dimension- Parameters
- dimint, optional
the dimension in the sparse matrix (for non-orthogonal cases the last dimension is the overlap matrix)
- iscint, optional
the supercell index, or all (if
isc=None
)
-
transpose
(self)¶ Create the transposed sparse geometry by interchanging supercell indices
Sparse geometries are (typically) relying on symmetry in the supercell picture. Thus when one transposes a sparse geometry one should ideally get the same matrix. This is true for the Hamiltonian, density matrix, etc.
This routine transposes all rows and columns such that any interaction between row, r, and column c in a given supercell (i,j,k) will be transposed into row c, column r in the supercell (-i,-j,-k).
- Returns
- object
an equivalent sparse geometry with transposed matrix elements
Notes
For Hamiltonians with non-collinear or spin-orbit there is no transposing of the sub-spin matrix box. This needs to be done manually.
Examples
Force a sparse geometry to be Hermitian:
>>> sp = SparseOrbital(...) >>> sp = (sp + sp.transpose()) * 0.5