sisl.physics.Hamiltonian
- class sisl.physics.Hamiltonian(geometry, dim=1, dtype=None, nnzpr=None, **kwargs)
Bases:
SparseOrbitalBZSpin
Sparse Hamiltonian matrix object
Assigning or changing Hamiltonian elements is as easy as with standard
numpy
assignments:>>> ham = Hamiltonian(...) >>> ham.H[1, 2] = 0.1
which assigns 0.1 as the coupling constant between orbital 2 and 3. (remember that Python is 0-based elements).
For spin matrices the elements are defined with an extra dimension.
For a polarized matrix:
>>> M = Hamiltonian(..., spin="polarized") >>> M[0, 0, 0] = # onsite spin up >>> M[0, 0, 1] = # onsite spin down
For non-colinear the indices are a bit more tricky:
>>> M = Hamiltonian(..., spin="non-colinear") >>> M[0, 0, M.M11] = # Re(up-up) >>> M[0, 0, M.M22] = # Re(down-down) >>> M[0, 0, M.M12r] = # Re(up-down) >>> M[0, 0, M.M12i] = # Im(up-down)
For spin-orbit it looks like this:
>>> M = Hamiltonian(..., spin="spin-orbit") >>> M[0, 0, M.M11r] = # Re(up-up) >>> M[0, 0, M.M11i] = # Im(up-up) >>> M[0, 0, M.M22r] = # Re(down-down) >>> M[0, 0, M.M22i] = # Im(down-down) >>> M[0, 0, M.M12r] = # Re(up-down) >>> M[0, 0, M.M12i] = # Im(up-down) >>> M[0, 0, M.M21r] = # Re(down-up) >>> M[0, 0, M.M21i] = # Im(down-up)
Thus the number of orbitals is unchanged but a sub-block exists for the spin-block.
When transferring the matrix to a k-point the spin-box is local to each orbital, meaning that the spin-box for orbital i will be:
>>> Hk = ham.Hk() >>> Hk[i*2:(i+1)*2, i*2:(i+1)*2]
- Parameters:
geometry (
Geometry
) – parent geometry to create a Hamiltonian from. The Hamiltonian will have size equivalent to the number of orbitals in the geometrydim (
int
orSpin
, optional) – number of components per element, may be aSpin
objectdtype (
np.dtype
, optional) – data type contained in the matrix. See details ofSpin
for default values.nnzpr (
int
, optional) – number of initially allocated memory per orbital in the matrix. For increased performance this should be larger than the actual number of entries per orbital.spin (
Spin
, optional) – equivalent todim
argument. This keyword-only argument has precedence overdim
.orthogonal (
bool
, optional) – whether the matrix corresponds to a non-orthogonal basis. In this case the dimensionality of the matrix is one more thandim
. This is a keyword-only argument.
Plotting
Plotting functions for the
Hamiltonian
class.plot.atomicmatrix
([dim, isc, ...])Builds a
AtomicMatrixPlot
by setting the value of "matrix" to the current object.plot.pdos
([kgrid, kgrid_displ, ...])Creates a
PDOSData
object and then plots aPdosPlot
from it.plot.wavefunction
([k, spin, i, ...])Creates a
EigenstateData
object and then plots aWavefunctionPlot
from it.Methods
Hk
([k, dtype, gauge, format])Setup the Hamiltonian for a given k-point
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
add
(other[, axis, offset])Add two sparse matrices by adding the parameters to one set.
append
(other, axis[, atol, scale])Append other along axis to construct a new connected sparse matrix
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.dHk
([k, dtype, gauge, format])Setup the Hamiltonian derivative for a given k-point
dSk
([k, dtype, gauge, format])Setup the \(\mathbf k\)-derivatie of the overlap matrix for a given k-point
ddHk
([k, dtype, gauge, format])Setup the Hamiltonian double derivative for a given k-point
ddSk
([k, dtype, gauge, format])Setup the double \(\mathbf k\)-derivatie of the overlap matrix for a given k-point
edges
([atoms, exclude, orbitals])Retrieve edges (connections) for all atoms
eig
([k, gauge, eigvals_only])Returns the eigenvalues of the physical quantity (using the non-Hermitian solver)
eigenstate
([k, gauge])Calculate the eigenstates at k and return an
EigenstateElectron
object containing all eigenstateseigenvalue
([k, gauge])Calculate the eigenvalues at k and return an
EigenvalueElectron
object containing all eigenvalues for a given keigh
([k, gauge, eigvals_only])Returns the eigenvalues of the physical quantity
eigsh
([k, n, gauge, eigvals_only])Calculates a subset of eigenvalues of the physical quantity using sparse matrices
eliminate_zeros
(*args, **kwargs)Removes all zero elements from the sparse matrix
empty
([keep_nnz])See
empty
for detailsfermi_level
([bz, q, distribution, q_tol, ...])Calculate the Fermi-level using a Brillouinzone sampling and a target charge
finalize
()Finalizes the model
fromsp
(geometry, P[, S])Create a sparse model from a preset Geometry and a list of sparse matrices
iter_nnz
([atoms, orbitals])Iterations of the non-zero elements
iter_orbitals
([atoms, local])Iterations of the orbital space in the geometry, two indices from loop
nonzero
([atoms, only_cols])Indices row and column indices where non-zero elements exists
prepend
(other, axis[, atol, scale])See
append
for detailsread
(sile, *args, **kwargs)Reads Hamiltonian from Sile using read_hamiltonian.
remove
(atoms)Create a subset of this sparse matrix by removing the atoms corresponding to atoms
remove_orbital
(atoms, orbitals)Remove a subset of orbitals on atoms according to orbitals
repeat
(reps, axis)Create a repeated sparse orbital object, equivalent to Geometry.repeat
replace
(atoms, other[, other_atoms, atol, scale])Replace atoms in self with other_atoms in other and retain couplings between them
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
shift
(E)Shift the electronic structure by a constant energy
spalign
(other)See
align
for detailsspsame
(other)Compare two sparse objects and check whether they have the same entries.
sub
(atoms)Create a subset of this sparse matrix by only retaining the atoms corresponding to atoms
sub_orbital
(atoms, orbitals)Retain only a subset of the orbitals on atoms according to orbitals
swap
(atoms_a, atoms_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
toSparseAtom
([dim, dtype])Convert the sparse object (without data) to a new sparse object with equivalent but reduced sparse pattern
tocsr
([dim, isc])Return a
csr_matrix
for the specified dimensiontransform
([matrix, dtype, spin, orthogonal])Transform the matrix by either a matrix or new spin configuration
translate2uc
([atoms, axes])Translates all primary atoms to the unit cell.
transpose
([hermitian, spin, sort])A transpose copy of this object, possibly apply the Hermitian conjugate as well
trs
()Create a new matrix with applied time-reversal-symmetry
unrepeat
(reps, axis[, segment, sym])Unrepeats the sparse model into different parts (retaining couplings)
untile
(reps, axis[, segment, sym])Untiles the sparse model into different parts (retaining couplings)
write
(sile, *args, **kwargs)Writes a Hamiltonian to the Sile as implemented in the
Sile.write_hamiltonian
methodAttributes
Access the Hamiltonian elements
Access the overlap elements associated with the sparse matrix
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
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
- Hk(k=(0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format='csr', *args, **kwargs)[source]
Setup the Hamiltonian for a given k-point
Creation and return of the Hamiltonian for a given k-point (default to Gamma).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\mathbf H(\mathbf k) = \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices.
Another possible gauge is the atomic distance which can be written as
\[\mathbf H(\mathbf k) = \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the orbitals.
- Parameters:
k (
array_like
) – the k-point to setup the Hamiltonian atdtype (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 – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{'csr', 'array', 'dense', 'coo', ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(‘array’/’dense’/’matrix’). Prefixing with ‘sc:’, or simply ‘sc’ returns the matrix in supercell format with phases. This is useful for e.g. bond-current calculations where individual hopping + phases are required.spin (
int
, optional) – if the Hamiltonian is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the Hamiltonian is notSpin.POLARIZED
this keyword is ignored.
See also
- Returns:
matrix (
numpy.ndarray
orscipy.sparse.*_matrix
) – the Hamiltonian matrix at \(\mathbf k\). The returned object depends on format.
- Rij(what: str = 'orbital', dtype=np.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.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.
- Sk(k: sisl.typing.KPoint = (0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format: str = '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).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\mathbf S(\mathbf k) = \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices.
Another possible gauge is the atomic distance which can be written as
\[\mathbf S(\mathbf k) = \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the orbitals.
- 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 isnumpy.complex128
gauge – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{"csr", "array", "matrix", "coo", ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(“array”/”dense”/”matrix”). Prefixing with “sc:”, or simply “sc” returns the matrix in supercell format with phases. This is useful for e.g. bond-current calculations where individual hopping + phases are required.
See also
- Returns:
matrix (
numpy.ndarray
orscipy.sparse.*_matrix
) – the overlap matrix at \(\mathbf k\). The returned object depends on format.
- add(other, axis: int | None = None, offset: sisl.typing.Coord = (0, 0, 0))
Add two sparse matrices by adding the parameters to one set. The final matrix will have no couplings between self and other
The final sparse matrix will not have any couplings between self and other. Not even if they have commensurate overlapping regions. If you want to create couplings you have to use
append
but that requires the structures are commensurate in the coupling region.- Parameters:
other (
SparseGeometry
) – the other sparse matrix to be added, all atoms will be appendedaxis – whether a specific axis of the cell will be added to the final geometry. For
None
the final cell will be that of self, otherwise the lattice vector corresponding to axis will be appended.offset – offset in geometry of other when adding the atoms.
- append(other, axis: int, atol: float = 0.005, scale: sisl.typing.SeqOrScalarFloat = 1)
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.01 Ang, a warning will be issued. If this difference is above atol 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.
Examples
>>> sporb = SparseOrbital(....) >>> sporb2 = sporb.append(sporb, 0) >>> sporbt = sporb.tile(2, 0) >>> sporb2.spsame(sporbt) True
To retain couplings only from the left sparse matrix, do:
>>> sporb = left.append(right, 0, scale=(2, 0)) >>> sporb = (sporb + sporb.transpose()) / 2
To retain couplings only from the right sparse matrix, do:
>>> sporb = left.append(right, 0, scale=(0, 2.)) >>> sporb = (sporb + sporb.transpose()) / 2
Notes
The current implementation does not preserve the hermiticity of the matrix. If you want to preserve hermiticity of the matrix you have to do the following:
>>> sm = (sm + sm.transpose()) / 2
- Parameters:
other (
object
) – must be an object of the same type as selfaxis – axis to append the two sparse geometries along
atol – 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 tolerance is used as a baseline, see above.
scale (
float
orarray_like
, optional) – the scale used for the overlapping region. For scalar values it corresponds to passing:(scale, scale)
. For array-like inputscale[0]
refers to the scale of the matrix elements coupling from self, whilescale[1]
is the scale of the matrix elements in other.
See also
prepend
equivalent scheme as this method
add
merge two matrices without considering overlap or commensurability
transpose
ensure hermiticity by using this routine
replace
replace a sub-set of atoms with another sparse matrix
Geometry.append
,Geometry.prepend
SparseCSR.scale_columns
method used to scale the two matrix elements values
- Raises:
ValueError – if the two geometries are not compatible for either coordinate, orbital or supercell errors
- Returns:
object
– a new instance with two sparse matrices joined and appended together
- construct(func, na_iR: int = 1000, method: str = 'rand', eta=None)
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:
func (
callable
orarray_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, atoms, atoms_xyz=None): ... idx = self.geometry.close(ia, R=[0.1, 1.44], atoms=atoms, atoms_xyz=atoms_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 detailseta (
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
- copy(dtype=None) _SparseGeometry
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 useself.dtype
- create_construct(R, param)
Create a simple function for passing to the
construct
function.This is to relieve the creation of simplistic functions needed for setting up sparse elements.
For simple matrices this returns a function:
>>> def func(self, ia, atoms, atoms_xyz=None): ... idx = self.geometry.close(ia, R=R, atoms=atoms, atoms_xyz=atoms_xyz) ... for ix, p in zip(idx, param): ... self[ia, ix] = p
In the non-colinear case the matrix element \(\mathbf M_{ij}\) will be set to input values param if \(i \le j\) and the Hermitian conjugated values for \(j < i\).
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.
This method issues warnings if the on-site terms are not Hermitian for spin-orbit systems. Do note that it still creates the matrices based on the input.
- 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
)
- dHk(k=(0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format='csr', *args, **kwargs)[source]
Setup the Hamiltonian derivative for a given k-point
Creation and return of the Hamiltonian derivative for a given k-point (default to Gamma).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_{\mathbf k} \mathbf H_\alpha(\mathbf k) = i \mathbf R_\alpha \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices. And \(\alpha\) is one of the Cartesian directions.
Another possible gauge is the atomic distance which can be written as
\[\nabla_{\mathbf k} \mathbf H_\alpha(\mathbf k) = i \mathbf r_\alpha \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the atoms (for atom centered orbitals).
- Parameters:
k (
array_like
) – the k-point to setup the Hamiltonian atdtype (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 – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{'csr', 'array', 'dense', 'coo', ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(‘array’/’dense’/’matrix’).spin (
int
, optional) – if the Hamiltonian is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the Hamiltonian is notSpin.POLARIZED
this keyword is ignored.
- Returns:
tuple
– for each of the Cartesian directions a \(\partial \mathbf H(\mathbf k)/\partial \mathbf k_\alpha\) is returned.
- dSk(k: sisl.typing.KPoint = (0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format: str = 'csr', *args, **kwargs)
Setup the \(\mathbf 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).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_{\mathbf k} \mathbf S_\alpha(\mathbf k) = i \mathbf R_\alpha \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices. And \(\alpha\) is one of the Cartesian directions.
Another possible gauge is the atomic distance which can be written as
\[\nabla_{\mathbf k} \mathbf S_\alpha(\mathbf k) = i \mathbf r_\alpha \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the orbitals.
- 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 isnumpy.complex128
gauge – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{"csr", "array", "matrix", "coo", ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(“array”/”dense”/”matrix”).
- Returns:
tuple
– for each of the Cartesian directions a \(\partial \mathbf S(\mathbf k)/\partial\mathbf k\) is returned.
- ddHk(k=(0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format='csr', *args, **kwargs)[source]
Setup the Hamiltonian double derivative for a given k-point
Creation and return of the Hamiltonian double derivative for a given k-point (default to Gamma).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_{\mathbf k^2} \mathbf H_{\alpha\beta}(\mathbf k) = - \mathbf R_\alpha \mathbf R_\beta \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices. And \(\alpha\) and \(\beta\) are one of the Cartesian directions.
Another possible gauge is the atomic distance which can be written as
\[\nabla_{\mathbf k^2} \mathbf H_{\alpha\beta}(\mathbf k) = -\mathbf r_\alpha\mathbf r_\beta \mathbf H_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the atoms.
- Parameters:
k (
array_like
) – the k-point to setup the Hamiltonian atdtype (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 – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{'csr', 'array', 'dense', 'coo', ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(‘array’/’dense’/’matrix’).spin (
int
, optional) – if the Hamiltonian is a spin polarized one can extract the specific spin direction matrix by passing an integer (0 or 1). If the Hamiltonian is notSpin.POLARIZED
this keyword is ignored.
- Returns:
list
ofmatrices
– for each of the Cartesian directions (in Voigt representation); xx, yy, zz, zy, xz, xy
- ddSk(k: sisl.typing.KPoint = (0, 0, 0), dtype=None, gauge: sisl.typing.GaugeType = 'cell', format: str = 'csr', *args, **kwargs)
Setup the double \(\mathbf 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).
Notes
Currently the implemented gauge for the k-point is the cell vector gauge:
\[\nabla_{\mathbf k^2} \mathbf S_{\alpha\beta}(\mathbf k) = - \mathbf R_\alpha \mathbf R_\beta \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf R}\]where \(\mathbf R\) is an integer times the cell vector and \(i\), \(j\) are orbital indices. And \(\alpha\) and \(\beta\) are one of the Cartesian directions.
Another possible gauge is the atomic distance which can be written as
\[\nabla_{\mathbf k^2} \mathbf S_{\alpha\beta}(\mathbf k) = - \mathbf r_\alpha \mathbf r_\beta \mathbf S_{ij} e^{i\mathbf k\cdot\mathbf r}\]where \(\mathbf r\) is the distance between the orbitals.
- 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 isnumpy.complex128
gauge – the chosen gauge,
cell
for cell vector gauge, andatom
for atomic distance gauge.format (
{"csr", "array", "matrix", "coo", ...}
) – the returned format of the matrix, defaulting to thescipy.sparse.csr_matrix
, however if one always requires operations on dense matrices, one can always return innumpy.ndarray
(“array”/”dense”/”matrix”).
- Returns:
list
ofmatrices
– for each of the Cartesian directions (in Voigt representation); xx, yy, zz, zy, xz, xy
- edges(atoms: sisl.typing.AtomsIndex = None, exclude: sisl.typing.AtomsIndex = None, orbitals=None)
Retrieve edges (connections) for all atoms
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:
atoms – 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 – remove edges which are in the exclude list, this list refers to orbitals.
orbitals (
int
orlist
ofint
) – 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(k: sisl.typing.KPoint = (0, 0, 0), gauge: sisl.typing.GaugeType = 'cell', eigvals_only: bool = 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:
spin (
int
, optional) – the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid forSpin.POLARIZED
matrices.
- eigenstate(k=(0, 0, 0), gauge: sisl.typing.GaugeType = 'cell', **kwargs)[source]
Calculate the eigenstates at k and return an
EigenstateElectron
object containing all eigenstates- Parameters:
k (
array_like*3
, optional) – the k-point at which to evaluate the eigenstates atgauge – the gauge used for calculating the eigenstates
sparse (
bool
, optional) – ifTrue
,eigsh
will be called, elseeigh
will be called (default).format (
str
, optional) – seeeigh
for details, this will be passed to the EigenstateElectron instance to be used in subsequent calls, may speed up post-processing.**kwargs (
dict
, optional) – passed arguments to the eigenvalue calculator routine
- Returns:
EigenstateElectron
- eigenvalue(k=(0, 0, 0), gauge: sisl.typing.GaugeType = 'cell', **kwargs)[source]
Calculate the eigenvalues at k and return an
EigenvalueElectron
object containing all eigenvalues for a given k- Parameters:
k (
array_like*3
, optional) – the k-point at which to evaluate the eigenvalues atgauge – the gauge used for calculating the eigenvalues
sparse (
bool
, optional) – ifTrue
,eigsh
will be called, elseeigh
will be called (default).format (
str
, optional) – seeeigh
for details, this will be passed to the EigenstateElectron instance to be used in subsequent calls, may speed up post-processing.**kwargs (
dict
, optional) – passed arguments to the eigenvalue calculator routine
- Returns:
EigenvalueElectron
- eigh(k: sisl.typing.KPoint = (0, 0, 0), gauge: sisl.typing.GaugeType = 'cell', eigvals_only: bool = 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:
spin (
int
, optional) – the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid forSpin.POLARIZED
matrices.
- eigsh(k: sisl.typing.KPoint = (0, 0, 0), n: int = 1, gauge: sisl.typing.GaugeType = 'cell', eigvals_only: bool = True, **kwargs)
Calculates a subset of eigenvalues of the physical quantity using sparse matrices
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.sparse.linalg.eigsh
.- Parameters:
n – number of eigenvalues to calculate Defaults to the n smallest magnitude eigevalues.
spin (
int
, optional) – the spin-component to calculate the eigenvalue spectrum of, note that this parameter is only valid forSpin.POLARIZED
matrices.**kwargs – arguments passed directly to
scipy.sparse.linalg.eigsh
.
Notes
The performance and accuracy of this method depends heavily on kwargs. Playing around with a small test example before doing large scale calculations is adviced!
- eliminate_zeros(*args, **kwargs)
Removes all zero elements from the sparse matrix
This is an in-place operation.
See also
SparseCSR.eliminate_zeros
method called, see there for parameters
- fermi_level(bz=None, q=None, distribution='fermi_dirac', q_tol: float = 1e-10, *, apply_kwargs=None)[source]
Calculate the Fermi-level using a Brillouinzone sampling and a target charge
The Fermi-level will be calculated using an iterative approach by first calculating all eigenvalues and subsequently fitting the Fermi level to the final charge (q).
- Parameters:
bz (
Brillouinzone
, optional) – sampled k-points and weights, thebz.parent
will be equal to this object upon return default to Gamma-pointq (
float
,list
offloat
, optional) – seeked charge, if not set will be equal toself.geometry.q0
. If a list of two is passed there will be calculated a Fermi-level per spin-channel. If the Hamiltonian is not spin-polarized the sum of the list will be used and only a single fermi-level will be returned.distribution (
str
,func
, optional) – used distribution, must accept the keywordmu
as parameter for the Fermi-levelq_tol (
float
, optional) – tolerance of charge for finding the Fermi-levelapply_kwargs (
dict
, optional) – keyword arguments passed directly tobz.apply(**apply_kwargs)
.
- Returns:
float
orarray_like
– the Fermi-level of the system (or two if two different charges are passed)
- 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.
- classmethod fromsp(geometry: Geometry, P, S=None, **kwargs)
Create a sparse model from a preset Geometry and a list of sparse matrices
The passed sparse matrices are in one of
scipy.sparse
formats.- Parameters:
geometry (
Geometry
) – geometry to describe the new sparse geometryP (
list
ofscipy.sparse
orscipy.sparse
) – the new sparse matrices that are to be populated in the sparse matrixS (
scipy.sparse
, optional) – if provided this refers to the overlap matrix and will force the returned sparse matrix to be non-orthogonal**kwargs (optional) – any arguments that are directly passed to the
__init__
method of the class.
- Returns:
SparseGeometry
– a new sparse matrix that holds the passed geometry and the elements of P and optionally being non-orthogonal ifS
is not none
- iter_nnz(atoms: sisl.typing.AtomsIndex = None, orbitals=None)
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
- Parameters:
atoms – only loop on the non-zero elements coinciding with the orbitals on these atoms (not compatible with the orbitals keyword)
orbitals (
int
orarray_like
) – only loop on the non-zero elements coinciding with the orbital (not compatible with the atoms keyword)
- iter_orbitals(atoms: sisl.typing.AtomsIndex = None, local: bool = 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.iter_orbitals():
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:
- Yields:
ia
– atomic indexio
– orbital index
See also
Geometry.iter_orbitals
method used to iterate orbitals
- nonzero(atoms: sisl.typing.AtomsIndex = None, only_cols: bool = False)
Indices row and column indices where non-zero elements exists
- Parameters:
atoms – only return the tuples for the requested atoms, default is all atoms But for all orbitals.
only_cols – only return then non-zero columns
See also
SparseCSR.nonzero
the equivalent function call
- plot.atomicmatrix(dim: int = 0, isc: int | None = None, fill_value: float | None = None, geometry: Geometry | None = None, atom_lines: bool | dict = False, orbital_lines: bool | dict = False, sc_lines: bool | dict = False, color_pixels: bool = True, colorscale: Colorscale | None = 'RdBu', crange: tuple[float, float] | None = None, cmid: float | None = None, text: str | None = None, textfont: dict | None = {}, set_labels: bool = False, constrain_axes: bool = True, arrows: list[dict] = [], backend: str = 'plotly') AtomicMatrixPlot
Builds a
AtomicMatrixPlot
by setting the value of “matrix” to the current object.Plots a (possibly sparse) matrix where rows and columns are either orbitals or atoms.
- Parameters:
dim – If the matrix has a third dimension (e.g. spin), which index to plot in that third dimension.
isc – If the matrix contains data for an auxiliary supercell, the index of the cell to plot. If None, the whole matrix is plotted.
fill_value – If the matrix is sparse, the value to use for the missing entries.
geometry – Only needed if the matrix does not contain a geometry (e.g. it is a numpy array) and separator lines or labels are requested.
atom_lines – If a boolean, whether to draw lines separating atom blocks, using default styles. If a dict, draws the lines with the specified plotly line styles.
orbital_lines – If a boolean, whether to draw lines separating blocks of orbital sets, using default styles. If a dict, draws the lines with the specified plotly line styles.
sc_lines – If a boolean, whether to draw lines separating the supercells, using default styles. If a dict, draws the lines with the specified plotly line styles.
color_pixels – Whether to color the pixels of the matrix according to the colorscale.
colorscale – The colorscale to use to color the pixels.
crange – The minimum and maximum values of the colorscale.
cmid – The midpoint of the colorscale. If
crange
is provided, this is ignored.If None and crange is also None, the midpoint is set to 0 if the data contains both positive and negative values.
text – If provided, show text of pixel value with the specified format. E.g. text=”.3f” shows the value with three decimal places.
textfont – The font to use for the text. This is a dictionary that may contain the keys “family”, “size”, “color”.
set_labels – Whether to set the axes labels to the atom/orbital that each row and column corresponds to. For orbitals the labels will be of the form “Atom: (l, m)”, where Atom is the index of the atom and l and m are the quantum numbers of the orbital.
constrain_axes – Whether to set the ranges of the axes to exactly fit the matrix.
backend – The backend to use for plotting.
- plot.pdos(kgrid: ~typing.Tuple[int, int, int] = None, kgrid_displ: ~typing.Tuple[float, float, float] = (0, 0, 0), data_Erange: ~typing.Tuple[float, float] = (-2, 2), E0: float = 0, nE: int = 100, distribution=functools.partial(<function gaussian>, sigma=0.1, x0=0.0), *, groups: Sequence[OrbitalStyleQuery] = [{'name': 'DOS'}], Erange: tuple[float, float] = (-2, 2), E_axis: Literal['x', 'y'] = 'x', line_mode: Literal['line', 'scatter', 'area_line'] = 'line', line_scale: float = 1.0, backend: str = 'plotly') PdosPlot
Creates a
PDOSData
object and then plots aPdosPlot
from it.- Parameters:
kgrid – Number of kpoints in each reciprocal space direction. A Monkhorst-pack grid will be generated from this specification. The PDOS will be averaged over the whole k-grid.
kgrid_displ – Displacement of the Monkhorst-Pack grid.
data_Erange – Energy range (min and max) for the PDOS calculation.
E0 – Energy shift for the PDOS calculation.
nE – Number of energy points for the PDOS calculation.
distribution – The distribution to use for smoothing the PDOS along the energy axis. Each state will be broadened by this distribution.
groups – List of orbital specifications to filter and accumulate the PDOS. The contribution of each group will be displayed in a different line. See showcase notebook for examples.
Erange – The energy range to plot.
E_axis – Axis to project the energies.
line_mode – Mode used to draw the PDOS lines.
line_scale – Scaling factor for the width of all lines.
backend – The backend to generate the figure.
See also
PdosPlot
The plot class used to generate the plot.
PDOSData
The class to which data is converted.
- plot.wavefunction(k: tuple[float, float, float] = (0, 0, 0), spin: int = 0, *, i: int = 0, geometry: Geometry | None = None, grid_prec: float = 0.2, grid: Grid | None = None, axes: Axes = ['z'], represent: Literal['real', 'imag', 'mod', 'phase', 'deg_phase', 'rad_phase'] = 'real', transforms: Sequence[str | Callable] = (), reduce_method: Literal['average', 'sum'] = 'average', boundary_mode: str = 'grid-wrap', nsc: tuple[int, int, int] = (1, 1, 1), interp: tuple[int, int, int] = (1, 1, 1), isos: Sequence[dict] = [], smooth: bool = False, colorscale: Colorscale | None = None, crange: tuple[float, float] | None = None, cmid: float | None = None, show_cell: Literal['box', 'axes', False] = 'box', cell_style: dict = {}, x_range: Sequence[float] | None = None, y_range: Sequence[float] | None = None, z_range: Sequence[float] | None = None, plot_geom: bool = False, geom_kwargs: dict = {}, backend: str = 'plotly') WavefunctionPlot
Creates a
EigenstateData
object and then plots aWavefunctionPlot
from it.- Parameters:
k – The k-point for which the eigenstate coefficients are desired.
spin – The spin for which the eigenstate coefficients are desired.
i – The index of the eigenstate to plot.
geometry – Geometry to use to project the eigenstate to real space. If None, the geometry associated with the eigenstate is used.
grid_prec – The precision of the grid where the wavefunction is projected.
grid – The grid to plot.
axes – The axes to project the grid to.
represent – The representation of the grid to plot.
transforms – List of transforms to apply to the grid before plotting.
reduce_method – The method used to reduce the grid axes that are not displayed.
boundary_mode – The method used to deal with the boundary conditions. Only used if the grid is to be orthogonalized. See scipy docs for more info on the possible values.
nsc – The number of unit cells to display in each direction.
interp – The interpolation factor to use for each axis to make the grid smoother.
isos – List of isosurfaces or isocontours to plot. See the showcase notebooks for examples.
smooth – Whether to ask the plotting backend to make an attempt at smoothing the grid display.
colorscale – Colorscale to use for the grid display in the 2D representation. If None, the default colorscale is used for each backend.
crange – Min and max values for the colorscale.
cmid – The value at which the colorscale is centered.
show_cell – Method used to display the unit cell. If False, the cell is not displayed.
cell_style – Style specification for the cell. See the showcase notebooks for examples.
x_range – The range of the x axis to take into account. Even if the X axis is not displayed! This is important because the reducing operation will only be applied on this range.
y_range – The range of the y axis to take into account. Even if the Y axis is not displayed! This is important because the reducing operation will only be applied on this range.
z_range – The range of the z axis to take into account. Even if the Z axis is not displayed! This is important because the reducing operation will only be applied on this range.
plot_geom – Whether to plot the associated geometry (if any).
geom_kwargs – Keyword arguments to pass to the geometry plot of the associated geometry.
backend – The backend to use to generate the figure.
See also
WavefunctionPlot
The plot class used to generate the plot.
EigenstateData
The class to which data is converted.
- prepend(other, axis: int, atol: float = 0.005, scale: sisl.typing.SeqOrScalarFloat = 1)
See
append
for detailsThis is currently equivalent to:
>>> other.append(self, axis, atol, scale)
- static read(sile, *args, **kwargs)[source]
Reads Hamiltonian from Sile using read_hamiltonian.
- Parameters:
sile (
Sile
,str
orpathlib.Path
) – a Sile object which will be used to read the Hamiltonian and the overlap matrix (if any) if it is a string it will create a new sile using get_sile.* (
args passed directly
toread_hamiltonian(,**)
)
- remove(atoms: sisl.typing.AtomsIndex) _SparseGeometry
Create a subset of this sparse matrix by removing the atoms corresponding to atoms
Negative indices are wrapped and thus works.
- Parameters:
atoms – indices of removed atoms
- remove_orbital(atoms: sisl.typing.AtomsIndex, orbitals)
Remove a subset of orbitals on atoms according to orbitals
For more detailed examples, please see the equivalent (but opposite) method
sub_orbital
.- Parameters:
atoms – indices of atoms or Atom that will be reduced in size according to orbitals
orbitals (
array_like
ofint
orOrbital
) – indices of the orbitals on atoms that are removed from the sparse matrix.
See also
sub_orbital
retaining a set of orbitals (see here for examples)
- repeat(reps: int, axis: int) SparseOrbital
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 – number of repetitions along cell-vector axis
axis – 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
SparseOrbital.tile
a different ordering of the final geometry
- replace(atoms: sisl.typing.AtomsIndex, other, other_atoms: sisl.typing.AtomsIndex = None, atol: float = 0.005, scale: sisl.typing.SeqOrScalarFloat = 1.0)
Replace atoms in self with other_atoms in other and retain couplings between them
This method replaces a subset of atoms in self with another sparse geometry retaining any couplings between them. The algorithm checks whether the coupling atoms have the same number of orbitals. Meaning that atoms in the overlapping region should have the same connections and number of orbitals per atom. It will _not_ check whether the orbitals or atoms _are_ the same, nor the order of the orbitals.
The replacement algorithm takes the couplings from
self -> other
on atoms belonging toself
andother -> self
fromother
. This will in some cases mean that the matrix becomes non-symmetric. See in Notes for details on symmetrizing the matrices.Examples
>>> minimal = SparseOrbital(....) >>> big = minimal.tile(2, 0) >>> big2 = big.replace(np.arange(big.na), minimal) >>> big.spsame(big2) True
To ensure hermiticity and using the average of the couplings from
big
andminimal
one can do:>>> big2 = big.replace(np.arange(big.na), minimal) >>> big2 = (big2 + big2.transpose()) / 2
To retain couplings only from the
big
sparse matrix, one should do the following (note the subsequent transposing which ensures hermiticy and is effectively copying couplings frombig
to the replaced region.>>> big2 = big.replace(np.arange(big.na), minimal, scale=(2, 0)) >>> big2 = (big2 + big2.transpose()) / 2
To only retain couplings from the
minimal
sparse matrix:>>> big2 = big.replace(np.arange(big.na), minimal, scale=(0, 2)) >>> big2 = (big2 + big2.transpose()) / 2
Notes
The current implementation does not preserve the hermiticity of the matrix. If you want to preserve hermiticity of the matrix you have to do the following:
>>> sm = (sm + sm.transpose()) / 2
Also note that the ordering of the atoms will be
range(atoms.min()), range(len(other_atoms)), <rest>
.Algorithms that utilizes atomic indices should be careful.
When the tolerance atol is high, the elements may be more prone to differences in the symmetry elements. A good idea would be to check the difference between the couplings. The below variable
diff
will contain the difference(self -> other) - (other -> self)
>>> diff = sm - sm.transpose()
- Parameters:
atoms – which atoms in self that are removed and replaced with
other.sub(other_atoms)
other (
object
) – must be an object of the same type as self, a subset is taken from this sparse matrix and combined with self to create a new sparse matrixother_atoms – to select a subset of atoms in other that are taken out. Defaults to all atoms in other.
atol – coordinate tolerance for allowing replacement. It is important that this value is at least smaller than half the distance between the two closests atoms such that there is no ambiguity in selecting equivalent atoms.
scale – the scale used for the overlapping region. For scalar values it corresponds to passing:
(scale, scale)
. For array-like inputscale[0]
refers to the scale of the matrix elements coupling from self, whilescale[1]
is the scale of the matrix elements in other.
See also
prepend
prepend two sparse matrices, see
append
for detailsadd
merge two matrices without considering overlap or commensurability
transpose
may be used to ensure hermiticity (symmetrization of the matrix elements)
append
append two sparse matrices
Geometry.append
,Geometry.prepend
SparseCSR.scale_columns
method used to scale the two matrix elements values
- Raises:
ValueError – if the two geometries are not compatible for either coordinate, orbital or supercell errors
AssertionError – if the two geometries are not compatible for either coordinate, orbital or supercell errors
- Warns:
SislWarning – in case the overlapping atoms are not comprising the same atomic specie. In some cases this may not be a problem. However, care must be taken by the user if this warning is issued.
- Returns:
object
– a new instance with two sparse matrices merged together by replacing some atoms
- reset(dim: int | None = None, dtype=np.float64, nnzpr: int | None = 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 – number of dimensions per element, default to the current number of elements per matrix element.
dtype (
numpy.dtype
, optional) – the datatype of the sparse elementsnnzpr – number of non-zero elements per row
- rij(what: str = 'orbital', dtype=np.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.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 Lattice.set_nsc for allowed parameters.
See also
Lattice.set_nsc
the underlying called method
- shift(E)[source]
Shift the electronic structure by a constant energy
This is equal to performing this operation:
\[\mathbf H_\sigma = \mathbf H_\sigma + E \mathbf S\]where \(\mathbf H_\sigma\) correspond to the spin diagonal components of the Hamiltonian.
- Parameters:
E (
float
or(2,)
) – the energy (in eV) to shift the electronic structure, if two values are passed the two first spin-components get shifted individually.
- 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(atoms: sisl.typing.AtomsIndex) SparseOrbital
Create a subset of this sparse matrix by only retaining the atoms corresponding to atoms
Negative indices are wrapped and thus works, supercell atoms are also wrapped to the unit-cell.
- Parameters:
atoms – indices of retained atoms or Atom for retaining only that atom
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
See also
Geometry.remove
the negative of Geometry.sub
Geometry.sub
equivalent to the resulting Geometry from this routine
SparseOrbital.remove
the negative of
sub
, i.e. remove a subset of atoms
- sub_orbital(atoms: sisl.typing.AtomsIndex, orbitals)
Retain only a subset of the orbitals on atoms according to orbitals
This allows one to retain only a given subset of the sparse matrix elements.
- Parameters:
atoms – indices of atoms or Atom that will be reduced in size according to orbitals
orbitals (
array_like
ofint
orOrbital
) – indices of the orbitals on atoms 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.
When using this method the internal species list will be populated by another species that is named after the orbitals removed. This is to distinguish different atoms.
Examples
>>> # a Carbon atom with 2 orbitals >>> C = sisl.Atom('C', [1., 2.]) >>> # an oxygen atom with 3 orbitals >>> O = sisl.Atom('O', [1., 2., 2.4]) >>> geometry = sisl.Geometry([[0] * 3, [1] * 3]], 2, [C, O]) >>> obj = SparseOrbital(geometry).tile(3, 0) >>> # fill in obj data...
Now
obj
is a sparse geometry with 2 different species and 6 atoms (3 of each). They are ordered[C, O, C, O, C, O]
. In the following we will note species that are different from the original by a'
in the list.Retain 2nd orbital on the 2nd atom:
[C, O', C, O, C, O]
>>> new_obj = obj.sub_orbital(1, 1)
Retain 2nd orbital on 1st and 2nd atom:
[C', O', C, O, C, O]
>>> new_obj = obj.sub_orbital([0, 1], 1)
Retain 2nd orbital on the 1st atom and 3rd orbital on 4th atom:
[C', O, C, O', C, O]
>>> new_obj = obj.sub_orbital(0, 1).sub_orbital(3, 2)
Retain 2nd orbital on all atoms equivalent to the first atom:
[C', O, C', O, C', O]
>>> new_obj = obj.sub_orbital(obj.geometry.atoms[0], 1)
Retain 1st orbital on 1st atom, and 2nd orbital on 3rd and 5th atom:
[C', O, C'', O, C'', O]
>>> new_obj = obj.sub_orbital(0, 0).sub_orbital([2, 4], 1)
See also
remove_orbital
removing a set of orbitals (opposite of this)
- swap(atoms_a: sisl.typing.AtomsIndex, atoms_b: sisl.typing.AtomsIndex) _SparseGeometry
Swaps atoms in the sparse geometry to obtain a new order of atoms
This can be used to reorder elements of a geometry.
- Parameters:
atoms_a – the first list of atomic coordinates
atoms_b – the second list of atomic coordinates
- tile(reps: int, axis: int) SparseOrbital
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 – number of repetitions along cell-vector axis
axis – 0, 1, 2 according to the cell-direction
See also
SparseOrbital.repeat
a different ordering of the final geometry
SparseOrbital.untile
opposite of this method
Geometry.tile
the same ordering as the final geometry
Geometry.repeat
a different ordering of the final geometry
- toSparseAtom(dim: int = 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:
dim – number of dimensions allocated in the SparseAtom object, default to the same
dtype (
numpy.dtype
, optional) – used data-type for the sparse object. Defaults to the same.
- tocsr(dim: int = 0, isc=None, **kwargs)
Return a
csr_matrix
for the specified dimension- Parameters:
dim – the dimension in the sparse matrix (for non-orthogonal cases the last dimension is the overlap matrix)
isc (
int
, optional) – the supercell index, or all (ifisc=None
)
- transform(matrix=None, dtype=None, spin=None, orthogonal=None)
Transform the matrix by either a matrix or new spin configuration
1. General transformation: * If matrix is provided, a linear transformation \(\mathbf R^n \rightarrow \mathbf R^m\) is applied to the \(n\)-dimensional elements of the original sparse matrix. The
spin
andorthogonal
flags are optional but need to be consistent with the creation of an m-dimensional matrix.This method will copy over the overlap matrix in case the matrix argument only acts on the non-overlap matrix elements and both input and output matrices are non-orthogonal.
2. Spin conversion: If
spin
is provided (without matrix), the spin class is changed according to the following conversions:Upscaling * unpolarized -> (polarized, non-colinear, spinorbit): Copy unpolarized value to both up and down components * polarized -> (non-colinear, spinorbit): Copy up and down components * non-colinear -> spinorbit: Copy first four spin components * all other new spin components are set to zero
Downscaling * (polarized, non-colinear, spinorbit) -> unpolarized: Set unpolarized value to a mix 0.5*up + 0.5*down * (non-colinear, spinorbit) -> polarized: Keep up and down spin components * spinorbit -> non-colinear: Keep first four spin components * all other spin components are dropped
3. Orthogonality: If the
orthogonal
flag is provided, the overlap matrix is either dropped or explicitly introduced as the identity matrix.Notes
The transformation matrix does not act on the rows and columns, only on the final dimension of the matrix.
- Parameters:
matrix (
array_like
, optional) – transformation matrix of shape \(m \times n\). Default is no transformation.dtype (
numpy.dtype
, optional) – data type contained in the matrix. Defaults to the input type.spin (
str
,sisl.Spin
, optional) – spin class of created matrix. Defaults to the input type.orthogonal (
bool
, optional) – flag to control if the new matrix includes overlaps. Defaults to the input type.
- translate2uc(atoms: sisl.typing.AtomsIndex = None, axes: sisl.typing.CellAxes | None = None)
Translates all primary atoms to the unit cell.
With this, the coordinates of the geometry are translated to the unit cell and the supercell connections in the matrix are updated accordingly.
- Parameters:
atoms – only translate the specified atoms. If not specified, all atoms will be translated.
axes – only translate certain lattice directions, None specifies only the periodic directions
- Returns:
SparseOrbital
orSparseAtom
– A new sparse matrix with the updated connections and a new associated geometry.
- transpose(hermitian: bool = False, spin: bool = True, sort: bool = True)
A transpose copy of this object, possibly apply the Hermitian conjugate as well
- Parameters:
hermitian – if true, also apply a spin-box Hermitian operator to ensure TRS, otherwise only return the transpose values.
spin – whether the spin-box is also transposed if this is false, and hermitian is true, then only imaginary values will change sign.
sort – the returned columns for the transposed structure will be sorted if this is true, default
- trs()
Create a new matrix with applied time-reversal-symmetry
Time reversal symmetry is applied using the following equality:
\[2\mathbf M^{\mathrm{TRS}} = \mathbf M + \boldsymbol\sigma_y \mathbf M^* \boldsymbol\sigma_y\]where \(*\) is the conjugation operator.
- unrepeat(reps: int, axis: int, segment: int = 0, *args, sym: bool = True, **kwargs)
Unrepeats the sparse model into different parts (retaining couplings)
Please see
untile
for details, the algorithm and arguments are the same however, this is the opposite ofrepeat
.
- untile(reps: int, axis: int, segment: int = 0, *args, sym: bool = True, **kwargs)
Untiles the sparse model into different parts (retaining couplings)
Recreates a new sparse object with only the cutted atoms in the structure. This will preserve matrix elements in the supercell.
- Parameters:
reps – number of repetitions the tiling function created (opposite meaning as in
untile
)axis – which axis to untile along
segment – which segment to retain. Generally each segment should be equivalent, however requesting individiual segments can help uncover inconsistencies in the sparse matrix
*args – arguments passed directly to Geometry.untile
sym – if True, the algorithm will ensure the returned matrix is symmetrized (i.e. return
(M + M.transpose())/2
, else return data as is. False should generally only be used for debugging precision of the matrix elements, or if one wishes to check the warnings.**kwargs – keyword arguments passed directly to Geometry.untile
Notes
Untiling structures with
nsc == 1
along axis are assumed to have periodic boundary conditions.When untiling structures with
nsc == 1
along axis it is important to untile as much as possible. This is because otherwise the algorithm cannot determine the correct couplings. Therefore to create a geometry of 3 times a unit-cell, one should untile to the unit-cell, and subsequently tile 3 times.Consider for example a system of 4 atoms, each atom connects to its 2 neighbors. Due to the PBC atom 0 will connect to 1 and 3. Untiling this structure in 2 will group couplings of atoms 0 and 1. As it will only see one coupling to the right it will halve the coupling and use the same coupling to the left, which is clearly wrong.
In the following the latter is the correct way to do it.
>>> SPM.untile(2, 0) != SPM.untile(4, 0).tile(2, 0)
- Raises:
ValueError : – in case the matrix elements are not conseuctive when determining the new supercell structure. This may often happen if untiling a matrix too few times, and then untiling it again.
See also
tile
opposite of this method
Geometry.untile
same as this method, see details about parameters here
- write(sile: sisl.typing.SileLike, *args, **kwargs) None
Writes a Hamiltonian to the Sile as implemented in the
Sile.write_hamiltonian
method
- property H
Access the Hamiltonian elements
- property S
Access the overlap elements associated with the sparse matrix
- property dim
Number of components per element
- property dkind
Data type of sparse elements (in str)
- property dtype
Data type of sparse elements
- property finalized
Whether the contained data is finalized and non-used elements have been removed
- property geometry
Associated geometry
- property nnz
Number of non-zero elements
- property non_orthogonal
True if the object is using a non-orthogonal basis
- property orthogonal
True if the object is using an orthogonal basis
- plot
Plotting functions for the
Hamiltonian
class.
- property shape
Shape of sparse matrix
- property spin
Associated spin class