# sisl.physics.electron.EigenstateElectron

class sisl.physics.electron.EigenstateElectron(state, c, parent=None, **info)[source]

Bases: StateCElectron

Eigen states of electrons with eigenvectors and eigenvalues.

This holds routines that enable the calculation of (projected) density of states, spin moments (spin texture).

Methods

 COHP(E, *args, **kwargs) Calculate COHP for provided energies, E. COOP(E, *args, **kwargs) Calculate COOP for provided energies, E. COP(E, M, *args, **kwargs) Calculate COP for provided energies, E using matrix M DOS(E[, distribution]) Calculate DOS for provided energies, E. PDOS(E[, distribution]) Calculate PDOS for provided energies, E. Sk([format, spin]) Retrieve the overlap matrix corresponding to the originating parent structure. align_norm(other[, ret_index, inplace]) Align self with the site-norms of other, a copy may optionally be returned align_phase(other[, ret_index, inplace]) Align self with the phases for other, a copy may be returned berry_curvature(*args, **kwargs) Calculate Berry curvature for the states change_gauge(gauge[, offset]) In-place change of the gauge of the state coefficients Return a copy (only the coefficients and states are copied), parent and info are passed by reference degenerate(eps) Find degenerate coefficients with a specified precision derivative([order, degenerate, ...]) Calculate the derivative with respect to $$\mathbf k$$ for a set of states up to a given order effective_mass(*args, **kwargs) Calculate effective mass tensor for the states inner([ket, matrix, diag]) Calculate the inner product as $$\mathbf A_{ij} = \langle\psi_i|\mathbf M|\psi'_j\rangle$$ ipr([q]) Calculate the inverse participation ratio (IPR) for arbitrary q values iter([asarray]) An iterator looping over the states in this system Return a vector with the Euclidean norm of each state $$\sqrt{\langle\psi|\psi\rangle}$$ norm2([sum]) Return a vector with the norm of each state $$\langle\psi|\mathbf S|\psi\rangle$$ Return a normalized state where each state has $$|\psi|^2=1$$ occupation([distribution]) Calculate the occupations for the states according to a distribution function outer([ket, matrix]) Return the outer product by $$\sum_i|\psi_i\rangle\langle\psi'_i|$$ phase([method, ret_index]) Calculate the Euler angle (phase) for the elements of the state, in the range $$]-\pi;\pi]$$ remove(idx[, inplace]) Return a new state without the specified indices rotate([phi, individual]) Rotate all states (in-place) to rotate the largest component to be along the angle phi sort([ascending]) Sort and return a new StateC by sorting the coefficients (default to ascending) spin_moment([project]) Calculate spin moment from the states sub(idx[, inplace]) Return a new state with only the specified states tile(reps, axis[, normalize, offset]) Tile the state vectors for a new supercell translate(isc) Translate the vectors to a new unit-cell position velocity(*args, **kwargs) Calculate velocity for the states wavefunction(grid[, spinor, eta]) Expand the coefficients as the wavefunction on grid as-is c dkind The data-type of the state (in str) dtype Data-type for the state eig Eigenvalues for each state info parent shape Returns the shape of the state state
COHP(E, *args, **kwargs)[source]

Calculate COHP for provided energies, E.

This routine calls COP with appropriate arguments.

COOP(E, *args, **kwargs)[source]

Calculate COOP for provided energies, E.

This routine calls COP with appropriate arguments.

COP(E, M, *args, **kwargs)[source]

Calculate COP for provided energies, E using matrix M

This routine calls COP with appropriate arguments.

DOS(E, distribution='gaussian')[source]

Calculate DOS for provided energies, E.

This routine calls sisl.physics.electron.DOS with appropriate arguments and returns the DOS.

See DOS for argument details.

PDOS(E, distribution='gaussian')[source]

Calculate PDOS for provided energies, E.

This routine calls PDOS with appropriate arguments and returns the PDOS.

See PDOS for argument details.

Sk(format=None, spin=None)

Retrieve the overlap matrix corresponding to the originating parent structure.

When self.parent is a Hamiltonian this will return $$\mathbf S(k)$$ for the $$k$$-point these eigenstates originate from

Parameters
• format (str, optional) – the returned format of the overlap matrix. This only takes effect for non-orthogonal parents.

• spin (Spin, optional) – for non-colinear spin configurations the fake overlap matrix returned will have halve the size of the input matrix. If you want the full overlap matrix, simply do not specify the spin argument.

__init__(state, c, parent=None, **info)

Define a state container with a given set of states and coefficients for the states

align_norm(other, ret_index=False, inplace=False)

Align self with the site-norms of other, a copy may optionally be returned

To determine the new ordering of self first calculate the residual norm of the site-norms.

$\delta N_{\alpha\beta} = \sum_i \big(\langle \psi^\alpha_i | \psi^\alpha_i\rangle - \langle \psi^\beta_i | \psi^\beta_i\rangle\big)^2$

where $$\alpha$$ and $$\beta$$ correspond to state indices in self and other, respectively. The new states (from self) returned is then ordered such that the index $$\alpha \equiv \beta'$$ where $$\delta N_{\alpha\beta}$$ is smallest.

Parameters
• other (State) – the other state to align against

• ret_index (bool, optional) – also return indices for the swapped indices

• inplace (bool, optional) – swap states in-place

Returns

• self_swap (State) – A swapped instance of self, only if inplace is False

• index (array of int) – the indices that swaps self to be self_swap, i.e. self_swap = self.sub(index) Only if inplace is False and ret_index is True

Notes

The input state and output state have the same number of states, but their ordering is not necessarily the same.

align_phase

rotate states such that their phases align

align_phase(other, ret_index=False, inplace=False)

Align self with the phases for other, a copy may be returned

States will be rotated by $$\pi$$ provided the phase difference between the states are above $$|\Delta\theta| > \pi/2$$.

Parameters
• other (State) – the other state to align onto this state

• ret_index (bool, optional) – return which indices got swapped

• inplace (bool, optional) – rotate the states in-place

align_norm

re-order states such that site-norms have a smaller residual

asCoefficient()
asState()
berry_curvature(*args, **kwargs)

Calculate Berry curvature for the states

This routine calls derivative(1, *args, **kwargs, matrix=True) and returns the Berry curvature for the states.

Note that the coefficients associated with the StateCElectron must correspond to the energies of the states.

derivative

for details of the velocity matrix calculation implementation

sisl.physics.electron.berry_curvature

for details of the Berry curvature implementation

c
change_gauge(gauge, offset=(0, 0, 0))

In-place change of the gauge of the state coefficients

The two gauges are related through:

$\tilde C_j = e^{i\mathbf k\mathbf r_j} C_j$

where $$C_j$$ and $$\tilde C_j$$ belongs to the r and R gauge, respectively.

Parameters
• gauge ({'R', 'r'}) – specify the new gauge for the mode coefficients

• offset (array_like, optional) – whether the coordinates should be offset by another phase-factor

copy()

Return a copy (only the coefficients and states are copied), parent and info are passed by reference

degenerate(eps)

Find degenerate coefficients with a specified precision

Parameters

eps (float) – the precision above which coefficients are not considered degenerate

Returns

a list of indices

Return type
derivative(order=1, degenerate=1e-05, degenerate_dir=(1, 1, 1), matrix=False)

Calculate the derivative with respect to $$\mathbf k$$ for a set of states up to a given order

These are calculated using the analytic expression ($$\alpha$$ corresponding to the Cartesian directions), here only shown for the 1st order derivative:

$\mathbf{d}_{\alpha ij} = \langle \psi_j | \frac{\partial}{\partial\mathbf k_\alpha} \mathbf H(\mathbf k) | \psi_i \rangle$

In case of non-orthogonal basis the equations substitutes $$\mathbf H(\mathbf k)$$ by $$\mathbf H(\mathbf k) - \epsilon_i\mathbf S(\mathbf k)$$.

The 2nd order derivatives are calculated with the Berry curvature correction:

$\mathbf d^2_{\alpha \beta ij} = \langle\psi_j| \frac{\partial^2}{\partial\mathbf k_\alpha\partial\mathbf k_\beta} \mathbf H(\mathbf k) | \psi_i\rangle - \frac12\frac{\mathbf{d}_{\alpha ij}\mathbf{d}_{\beta ij}} {\epsilon_j - \epsilon_i}$

Notes

When requesting 2nd derivatives it will not be advisable to use a sub before calculating the derivatives since the 1st order perturbation uses the energy differences (Berry contribution) and the 1st derivative matrix for correcting the curvature.

For states at the $$\Gamma$$ point you may get warnings about casting complex numbers to reals. In these cases you should force the state at the $$\Gamma$$ point to be calculated in complex numbers to enable the correct decoupling.

Parameters
• order ({1, 2}) – an integer specifying which order of the derivative is being calculated.

• degenerate (float or list of array_like, optional) – If a float is passed it is regarded as the degeneracy tolerance used to calculate the degeneracy levels. Defaults to 1e-5 eV. If a list, it contains the indices of degenerate states. In that case a prior diagonalization is required to decouple them. See degenerate_dir for the sum of directions.

• degenerate_dir ((3,), optional) – a direction used for degenerate decoupling. The decoupling based on the velocity along this direction

• matrix (bool, optional) – whether the full matrix or only the diagonal components are returned

SparseOrbitalBZ.dPk

function for generating the matrix derivatives

SparseOrbitalBZ.dSk

function for generating the matrix derivatives in non-orthogonal basis

Returns

• dv – the 1st derivative, has shape (3, state.shape[0]) for matrix=False, else has shape (3, state.shape[0], state.shape[0]) Also returned for order >= 2 since it is used in the higher order derivatives

• ddv – the 2nd derivative, has shape (6, state.shape[0]) for matrix=False, else has shape (6, state.shape[0], state.shape[0]), the first dimension is in the Voigt representation Only returned for order >= 2

property dkind

The data-type of the state (in str)

property dtype

Data-type for the state

effective_mass(*args, **kwargs)

Calculate effective mass tensor for the states

This routine calls derivative(2, *args, **kwargs) and returns the effective mass for all states.

Note that the coefficients associated with the StateCElectron must correspond to the energies of the states.

Notes

Since some directions may not be periodic there will be zeros. This routine will invert elements where the values are different from 0.

It is not advisable to use a sub before calculating the effective mass since the 1st order perturbation uses the energy differences and the 1st derivative matrix for correcting the curvature.

The returned effective mass is given in the Voigt notation.

For $$\Gamma$$ point calculations it may be beneficial to pass dtype=np.complex128 to the eigenstate argument to ensure their complex values. This is necessary for the degeneracy decoupling.

derivative

for details of the implementation

property eig

Eigenvalues for each state

info
inner(ket=None, matrix=None, diag=True)

Calculate the inner product as $$\mathbf A_{ij} = \langle\psi_i|\mathbf M|\psi'_j\rangle$$

Parameters
• ket (State, optional) – the ket object to calculate the inner product with, if not passed it will do the inner product with itself. The object itself will always be the bra $$\langle\psi_i|$$

• matrix (array_like, optional) – whether a matrix is sandwiched between the bra and ket, defaults to the identity matrix. 1D arrays will be treated as a diagonal matrix.

• diag (bool, optional) – only return the diagonal matrix $$\mathbf A_{ii}$$.

Notes

This does not take into account a possible overlap matrix when non-orthogonal basis sets are used.

Raises

ValueError – if the number of state coefficients are different for the bra and ket

Returns

a matrix with the sum of inner state products

Return type

numpy.ndarray

ipr(q=2)

Calculate the inverse participation ratio (IPR) for arbitrary q values

The inverse participation ratio is defined as

$I_{q,i} = \frac{\sum_\nu |\psi_{i\nu}|^{2q}}{ \big[\sum_\nu |\psi_{i\nu}|^2\big]^q}$

where $$i$$ is the band index and $$\nu$$ is the orbital. The order of the IPR is defaulted to $$q=2$$, see (1) for details. The IPR may be used to distinguish Anderson localization and extended states:

\begin{align} \lim_{L\to\infty} I_{2,i} = \left\{\begin{aligned} 1/L^d & \text{extended state} \\ const. & \text{localized state} \end{aligned} \end{align}

For further details see [1]_. Note that for eigen states the IPR reduces to:

$I_{q,i} = \sum_\nu |\psi_{i\nu}|^{2q}$

since the denominator is $$1^{q} = 1$$.

Parameters

q (int, optional) – order parameter for the IPR

References

1

N. C. Murphy *et.al.*, “Generalized inverse participation ratio as a possible measure of localization for interacting systems”, PRB **83**, 184206 (2011)

iter(asarray=False)

An iterator looping over the states in this system

Parameters

asarray (bool, optional) – if true the yielded values are the state vectors, i.e. a numpy array. Otherwise an equivalent object is yielded.

Yields
• state (State) – a state only containing individual elements, if asarray is false

• state (numpy.ndarray) – a state only containing individual elements, if asarray is true

norm()

Return a vector with the Euclidean norm of each state $$\sqrt{\langle\psi|\psi\rangle}$$

Returns

the Euclidean norm for each state

Return type

numpy.ndarray

norm2(sum=True)

Return a vector with the norm of each state $$\langle\psi|\mathbf S|\psi\rangle$$

$$\mathbf S$$ is the overlap matrix (or basis), for orthogonal basis $$\mathbf S \equiv \mathbf I$$.

Parameters

sum (bool, optional) – for true only a single number per state will be returned, otherwise the norm per basis element will be returned.

Returns

the squared norm for each state

Return type

numpy.ndarray

normalize()

Return a normalized state where each state has $$|\psi|^2=1$$

This is roughly equivalent to:

>>> state = StateC(np.arange(10), 1)
>>> n = state.norm()
>>> norm_state = StateC(state.state / n.reshape(-1, 1), state.c.copy())
>>> norm_state.c[0] == 1

Returns

a new state with all states normalized, otherwise equal to this

Return type

State

occupation(distribution='fermi_dirac')[source]

Calculate the occupations for the states according to a distribution function

Parameters

distribution (str or func, optional) – distribution used to find occupations

Returns

len(self) with occupation values

Return type

numpy.ndarray

outer(ket=None, matrix=None)

Return the outer product by $$\sum_i|\psi_i\rangle\langle\psi'_i|$$

Parameters
• ket (State, optional) – the ket object to calculate the outer product of, if not passed it will do the outer product with itself. The object itself will always be the bra $$|\psi_i\rangle$$

• matrix (array_like, optional) – whether a matrix is sandwiched between the ket and bra, defaults to the identity matrix. 1D arrays will be treated as a diagonal matrix.

Notes

This does not take into account a possible overlap matrix when non-orthogonal basis sets are used.

Returns

a matrix with the sum of outer state products

Return type

numpy.ndarray

parent
phase(method='max', ret_index=False)

Calculate the Euler angle (phase) for the elements of the state, in the range $$]-\pi;\pi]$$

Parameters
• method ({'max', 'all'}) – for max, the phase for the element which has the largest absolute magnitude is returned, for all, all phases are calculated

• ret_index (bool, optional) – return indices for the elements used when method=='max'

plot

Handles all plotting possibilities for a class

remove(idx, inplace=False)

Return a new state without the specified indices

Parameters
• idx (int or array_like) – indices that are removed in the returned object

• inplace (bool, optional) – whether the values will be removed inplace

Returns

a new state without containing the requested elements, only if inplace is false

Return type

StateC

rotate(phi=0.0, individual=False)

Rotate all states (in-place) to rotate the largest component to be along the angle phi

The states will be rotated according to:

$S' = S / S^\dagger_{\phi-\mathrm{max}} \exp (i \phi),$

where $$S^\dagger_{\phi-\mathrm{max}}$$ is the phase of the component with the largest amplitude and $$\phi$$ is the angle to align on.

Parameters
• phi (float, optional) – angle to align the state at (in radians), 0 is the positive real axis

• individual (bool, optional) – whether the rotation is per state, or a single maximum component is chosen.

property shape

Returns the shape of the state

sort(ascending=True)

Sort and return a new StateC by sorting the coefficients (default to ascending)

Parameters

ascending (bool, optional) – sort the contained elements ascending, else they will be sorted descending

spin_moment(project=False)

Calculate spin moment from the states

This routine calls spin_moment with appropriate arguments and returns the spin moment for the states.

See spin_moment for details.

Parameters

project (bool, optional) – whether the moments are orbitally resolved or not

state
sub(idx, inplace=False)

Return a new state with only the specified states

Parameters
• idx (int or array_like) – indices that are retained in the returned object

• inplace (bool, optional) – whether the values will be retained inplace

Returns

a new object with a subset of the states, only if inplace is false

Return type

StateC

tile(reps, axis, normalize=False, offset=0)

Tile the state vectors for a new supercell

Tiling a state vector makes use of the Bloch factors for a state by utilizing

$\psi_{\mathbf k}(\mathbf r + \mathbf T) \propto e^{i\mathbf k\cdot \mathbf T}$

where $$\mathbf T = i\mathbf a_0 + j\mathbf a_1 + l\mathbf a_2$$. Note that axis selects which of the $$\mathbf a_i$$ vectors that are translated and reps corresponds to the $$i$$, $$j$$ and $$l$$ variables. The offset moves the individual states by said amount, i.e. $$i\to i+\mathrm{offset}$$.

Parameters
• reps (int) – number of repetitions along a specific lattice vector

• axis (int) – lattice vector to tile along

• normalize (bool, optional) – whether the states are normalized upon return, may be useful for eigenstates

• offset (float, optional) – the offset for the phase factors

Geometry.tile

translate(isc)

Translate the vectors to a new unit-cell position

The method is thoroughly explained in tile while this one only selects the corresponding state vector

Parameters

isc ((3,)) – number of offsets for the statevector

tile

equivalent method for generating more cells simultaneously

velocity(*args, **kwargs)

Calculate velocity for the states

This routine calls derivative(1, *args, **kwargs) and returns the velocity for the states.

Note that the coefficients associated with the StateCElectron must correspond to the energies of the states.

Notes

The states and energies for the states may have changed after calling this routine. This is because of the velocity un-folding for degenerate modes. I.e. calling PDOS after this method may change the result.

Notes

The velocities are calculated without the Berry curvature contribution see Eq. (2) in [1]_. The missing contribution may be added in later editions, for completeness sake, it is:

$\delta \mathbf v = - \mathbf k\times \Omega_i(\mathbf k)$

where $$\Omega_i$$ is the Berry curvature for state $$i$$.

References

1

X. Wang, J. R. Yates, I. Souza, D. Vanderbilt, “Ab initio calculation of the anomalous Hall conductivity by Wannier interpolation”, PRB **74**, 195118 (2006)

derivative
See wavefunction for argument details, the arguments not present in this method are automatically passed from this object.