sisl.physics.electron.EigenstateElectron

class sisl.physics.electron.EigenstateElectron

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).

Plotting

plot	Plotting functions for the EigenstateElectron class.
plot.wavefunction(*[, i, ...])	Creates a EigenstateData object and then plots a WavefunctionPlot from it.

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])	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
asCoefficient()
asState()
berry_curvature([sum, distribution, ...])	Calculate the Berry curvature matrix for a set of states (Kubo)
change_gauge(gauge[, offset])	In-place change of the gauge of the state coefficients
copy()	Return a copy (only the coefficients and states are copied), parent and info are passed by reference
degenerate(atol)	Find degenerate coefficients with a specified precision
derivative([order, matrix, axes, operator])	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, units are (ps/Ang)^2
inner([ket, matrix, projection])	Calculate the inner product as ${\mathbf{A}}_{ij}=⟨{\psi }_i|\mathbf{M}|{\psi }_j^{\prime }⟩$
ipr([q])	Calculate the inverse participation ratio (IPR) for arbitrary q values
iter([asarray])	An iterator looping over the states in this system
norm()	Return a vector with the Euclidean norm of each state $\sqrt{⟨\psi |\psi ⟩}$
norm2([projection])	Return a vector with the norm of each state $⟨\psi |\mathbf{S}|\psi ⟩$
normalize()	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 _{\alpha }|{\psi }_{\alpha }⟩⟨{\psi }_{\alpha }^{\prime }|$
phase([method, ret_index])	Calculate the Euler angle (phase) for the elements of the state, in the range $]-\pi ;\pi ]$
remove(index[, inplace])	Return a new state without the specified indices
rotate([phi, individual, inplace])	Rotate all states 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_berry_curvature([sigma, sum, ...])	Calculate the spin Berry curvature
spin_moment([projection])	Calculate spin moment from the states
sub(index[, 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

Attributes

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)

Calculate COHP for provided energies, E.

This routine calls COP with appropriate arguments.

COOP(E, *args, **kwargs)

Calculate COOP for provided energies, E.

This routine calls COP with appropriate arguments.

COP(E, M, *args, **kwargs)

Calculate COP for provided energies, E using matrix M

This routine calls COP with appropriate arguments.

DOS(E, distribution='gaussian')

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.

Parameters:

distribution (Literal['gaussian', 'lorentzian', 'fermi', 'bose-einstein', 'cold', 'step-function', 'heaviside'] | ~typing.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~numpy.ndarray])

PDOS(E, distribution='gaussian')

Calculate PDOS for provided energies, E.

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

See PDOS for argument details.

Parameters:

distribution (Literal['gaussian', 'lorentzian', 'fermi', 'bose-einstein', 'cold', 'step-function', 'heaviside'] | ~typing.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~numpy.ndarray])

Sk(format=None)

Retrieve the overlap matrix corresponding to the originating parent structure.

When self.parent is a Hamiltonian this will return $\mathbf{S}(\mathbf{k})$ for the $\mathbf{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.

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(⟨{\psi }_i^{\alpha }|{\psi }_i^{\alpha }⟩-⟨{\psi }_i^{\beta }|{\psi }_i^{\beta }⟩{)}^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 }^{\prime }$ where $\delta N_{\alpha \beta }$ is smallest.

Parameters:

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

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

• inplace (bool) – 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.

See also

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 $|\mathrm{\Delta }\theta |>\pi /2$.

Parameters:

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

• ret_index (bool) – return which indices got swapped

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

See also

align_norm

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

asCoefficient()

asState()

berry_curvature(sum=True, *, distribution=None, derivative_kwargs={}, operator=lambda M, d: ..., eta=0.0)

Calculate the Berry curvature matrix for a set of states (Kubo)

The Berry curvature is calculated using the following expression ($\alpha$, $\beta$ corresponding to Cartesian directions):

$${\mathbf{\Omega }}_{i,\alpha \beta }=2i{\hslash }^2\sum _{j\ne i}\frac{v_{ij}^{\alpha }{v}_{ji}^{\beta }}{[{ϵ}_i-{ϵ}_j{]}^2+i{\eta }^2}$$

For details on the Berry curvature, see Eq. (11) in [14] or Eq. (2.59) in [1].

The operator argument can be used to define the Berry curvature in other quantities. E.g. the spin Berry curvature is defined by replacing $v^{\alpha }$ by the spin current operator. see spin_berry_curvature for details.

For additional details on the spin Berry curvature, see Eq. (1) in [9] and Eq. (2) in [4].

Notes

There exists reports on some terms missing in the above formula, for details see [3].

Parameters:

• state (StateCElectron) – the state describing the electronic states we wish to calculate the Berry curvature of.

• sum (bool) – only return the summed Berry curvature (over all states).

• distribution (Literal['gaussian', 'lorentzian', 'fermi', 'bose-einstein', 'cold', 'step-function', 'heaviside'] | ~typing.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~numpy.ndarray] | None) – An optional distribution enabling one to automatically sum states across occupied/unoccupied states. This is useful when calculating AHC/SHC contributions since it can improve numerical accuracy. If this is None, it will do the above equation exactly.

• derivative_kwargs (dict) – arguments passed to derivative. Since operator is defined here, one cannot have operator in derivative_kwargs.

• operator (Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]] | tuple[~collections.abc.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes], ~typing.Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~collections.abc.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes], ~typing.Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]]]) – the operator to use for changing the dPk matrices. Note, that this may change the resulting units, and it will be up to the user to adapt the units accordingly.

• eta (float) – direct imaginary part broadening of the Lorentzian.

Return type:

ndarray

See also

derivative

method for calculating the exact derivatives

spin_berry_curvature

calculate the spin Berry curvature

ahc

anomalous Hall conductivity

shc

spin Hall conductivity

Returns:

If sum is False, it will be at least a 3D array with the 3rd dimension having the contribution from state i. If one passes axes to the derivative_kwargs argument one will get dimensions according to the number of axes requested, by default all axes will be used (even if they are non-periodic). The dtype will be imaginary. The unit is ${\mathrm{Ang}}^2$.

Return type:

bc

Parameters:

• state (StateCElectron)

• sum (bool)

• distribution (Literal['gaussian', 'lorentzian', 'fermi', 'bose-einstein', 'cold', 'step-function', 'heaviside'] | ~typing.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~numpy.ndarray] | None)

• derivative_kwargs (dict)

• operator (Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]] | tuple[~collections.abc.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes], ~typing.Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~collections.abc.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes], ~typing.Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]]])

• eta (float)

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}}_{\alpha }=e^{i\mathbf{k}{\mathbf{r}}_{\alpha }}{C}_{\alpha }$$

where $C_{\alpha }$ and ${\tilde{C}}_{\alpha }$ belongs to the atomic and lattice gauge, respectively.

Parameters:

• gauge (Literal['lattice', 'atomic']) – specify the new gauge for the mode coefficients

• offset (ndarray, 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

Parameters:

statec (StateC)

Return type:

StateC

degenerate(atol)

Find degenerate coefficients with a specified precision

Parameters:

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

Returns:

a list of indices

Return type:

list of numpy.ndarray

derivative(order=1, matrix=False, axes='xyz', operator=lambda M, d=None: ...)

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}=⟨{\psi }_i|\frac{\partial }{\partial {\mathbf{k}}_{\alpha }}\mathbf{H}(\mathbf{k})|{\psi }_j⟩$$

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

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

$${\mathbf{d}}_{\alpha \beta ij}^2=⟨{\psi }_i|\frac{{\partial }^2}{\partial {\mathbf{k}}_{\alpha }\partial {\mathbf{k}}_{\beta }}\mathbf{H}(\mathbf{k})|{\psi }_j⟩-\frac{1}{2}\frac{{\mathbf{d}}_{\alpha ij}{\mathbf{d}}_{\beta ij}}{{ϵ}_i-{ϵ}_j}$$

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 $\mathrm{\Gamma }$ point you may get warnings about casting complex numbers to reals. In these cases you should force the state at the $\mathrm{\Gamma }$ point to be calculated in complex numbers to enable the correct decoupling.

Parameters:

• order (Literal[1, 2]) – an integer specifying which order of the derivative is being calculated.

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

• axes (Literal[0, 1, 2] | ~typing.Literal['x', 'y', 'z'] | ~collections.abc.Sequence[~typing.Literal[0, 1, 2, 'x', 'y', 'z']]) – NOTE: this argument may change in future versions. only calculate the derivative(s) along specified Cartesian directions. The axes argument will be sorted internally, so the order will always be xyz. For the higher order derivatives all those involving only the provided axes will be used.

• operator (Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]]) – an operator that translates the $\delta$ matrices to another operator. The same operator will be applied to both P and S matrices.

See also

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

Parameters:

• order (Literal[1, 2])

• matrix (bool)

• axes (Literal[0, 1, 2] | ~typing.Literal['x', 'y', 'z'] | ~collections.abc.Sequence[~typing.Literal[0, 1, 2, 'x', 'y', 'z']])

• operator (Callable[[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], Literal['x', 'y', 'z', 'xx', 'yy', 'zz', 'yz', 'xz', 'xy'] | None], ~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]])

effective_mass(*args, **kwargs)

Calculate effective mass tensor for the states, units are (ps/Ang)^2

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 $\mathrm{\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.

See also

derivative

for details of the implementation

inner(ket=None, matrix=None, projection='diagonal')

Calculate the inner product as ${\mathbf{A}}_{ij}=⟨{\psi }_i|\mathbf{M}|{\psi }_j^{\prime }⟩$

Inner product calculation allows for a variety of things.

• for matrix it will compute off-diagonal elements as well

  $${\mathbf{A}}_{\alpha \beta }=⟨{\psi }_{\alpha }|\mathbf{M}|{\psi }_{\beta }^{\prime }⟩$$

• for diag only the diagonal components will be returned

  $${\mathbf{a}}_{\alpha }=⟨{\psi }_{\alpha }|\mathbf{M}|{\psi }_{\alpha }⟩$$

• for basis, only do inner products for individual states, but return them basis-resolved

  $${\mathbf{A}}_{\alpha \beta }={\psi }_{\alpha ,\beta }^{\ast }\mathbf{M}|{\psi }_{\alpha }{⟩}_{\beta }$$

• for atoms, only do inner products for individual states, but return them atom-resolved

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 $⟨{\psi }_i|$

• matrix (ndarray, 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.

• projection (Union[ProjectionType, ProjectionTypeHadamard, ProjectionTypeHadamardAtoms]) –

  how to perform the final projection. This can be used to sum specific sub-elements, return the diagonal, or the full matrix.

  • diagonal only return the diagonal of the inner product (‘ii’ elements)

  • matrix a matrix with diagonals and the off-diagonals (‘ij’ elements)

  • hadamard only do element wise products for the states (equivalent to basis resolved inner-products)

  • atoms only do inner products for individual states, but return them atom-resolved

Notes

This does not take into account a possible overlap matrix when non-orthogonal basis sets are used. One have to add the overlap matrix in the matrix argument, if needed.

Raises:

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

• RuntimeError – if the matrix shapes are incompatible with an atomic resolution conversion

Returns:

a matrix with the sum of inner state products

Return type:

numpy.ndarray

Parameters:

projection (Union[ProjectionType, ProjectionTypeHadamard, ProjectionTypeHadamardAtoms])

ipr(q=2)

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

The inverse participation ratio is defined as

$$I_{q,\alpha }=\frac{\sum _i|{\psi }_{\alpha ,i}{|}^{2q}}{[\sum _i|{\psi }_{\alpha ,i}{|}^2{]}^q}$$

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

$$\begin{array}{r}\underset{L\to \mathrm{\infty }}{lim}{I}_{2,\alpha }=\{\begin{array}{rl}1/L^d& \text{extended state}\\ \text{const.}& \text{localized state}\end{array}\end{array}$$

For further details see [7]. Note that for eigenstates the IPR reduces to:

$$I_{q,\alpha }=\sum _i|{\psi }_{\alpha ,i}{|}^{2q}$$

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

Parameters:

q (int) – order parameter for the IPR

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{⟨\psi |\psi ⟩}$

Returns:

the Euclidean norm for each state

Return type:

numpy.ndarray

norm2(projection='diagonal')

Return a vector with the norm of each state $⟨\psi |\mathbf{S}|\psi ⟩$

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

Parameters:

projection (Literal['matrix', 'ij', 'diagonal', 'diag', 'ii', 'trace', 'sum', 'hadamard', 'basis', 'hadamard:atoms', 'atoms']) – whether to compute the norm per state as a single number or as orbital-/atom-resolved quantity

See also

inner

used method for calculating the squared norm.

Returns:

the squared norm for each state

Return type:

numpy.ndarray

Parameters:

projection (Literal['matrix', 'ij', 'diagonal', 'diag', 'ii', 'trace', 'sum', 'hadamard', 'basis', 'hadamard:atoms', 'atoms'])

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')

Calculate the occupations for the states according to a distribution function

Parameters:

distribution (Literal['gaussian', 'lorentzian', 'fermi', 'bose-einstein', 'cold', 'step-function', 'heaviside'] | ~typing.Callable[[~collections.abc.Buffer | ~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]] | ~numpy._typing._nested_sequence._NestedSequence[~numpy._typing._array_like._SupportsArray[~numpy.dtype[~typing.Any]]] | bool | int | float | complex | str | bytes | ~numpy._typing._nested_sequence._NestedSequence[bool | int | float | complex | str | bytes]], ~numpy.ndarray]) – 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 _{\alpha }|{\psi }_{\alpha }⟩⟨{\psi }_{\alpha }^{\prime }|$

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 }_{\alpha }⟩$

• matrix (ndarray, 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

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) – return indices for the elements used when method=='max'

plot.wavefunction(*, i=0, geometry=None, grid_prec=0.2, grid=None, axes=['z'], represent='real', transforms=(), reduce_method='average', boundary_mode='grid-wrap', nsc=(1, 1, 1), interp=(1, 1, 1), isos=[], smooth=False, colorscale=None, crange=None, cmid=None, show_cell='box', cell_style={}, x_range=None, y_range=None, z_range=None, plot_geom=False, geom_kwargs={}, backend='plotly')

Creates a EigenstateData object and then plots a WavefunctionPlot from it.

Parameters:

• i (int) – The index of the eigenstate to plot.

• geometry (Optional[Geometry]) – Geometry to use to project the eigenstate to real space. If None, the geometry associated with the eigenstate is used.

• grid_prec (float) – The precision of the grid where the wavefunction is projected.

• grid (Optional[Grid]) – The grid to plot.

• axes (Axes) – The axes to project the grid to.

• represent (Literal['real', 'imag', 'mod', 'phase', 'deg_phase', 'rad_phase']) – The representation of the grid to plot.

• transforms (Sequence[Union[str, Callable]]) – List of transforms to apply to the grid before plotting.

• reduce_method (Literal['average', 'sum']) – The method used to reduce the grid axes that are not displayed.

• boundary_mode (str) – 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 (tuple[int, int, int]) – The number of unit cells to display in each direction.

• interp (tuple[int, int, int]) – The interpolation factor to use for each axis to make the grid smoother.

• isos (Sequence[dict]) – List of isosurfaces or isocontours to plot. See the showcase notebooks for examples.

• smooth (bool) – Whether to ask the plotting backend to make an attempt at smoothing the grid display.

• colorscale (Optional[Colorscale]) – Colorscale to use for the grid display in the 2D representation. If None, the default colorscale is used for each backend.

• crange (Optional[tuple[float, float]]) – Min and max values for the colorscale.

• cmid (Optional[float]) – The value at which the colorscale is centered.

• show_cell (Literal['box', 'axes', False]) – Method used to display the unit cell. If False, the cell is not displayed.

• cell_style (dict) – Style specification for the cell. See the showcase notebooks for examples.

• x_range (Optional[Sequence[float]]) – 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 (Optional[Sequence[float]]) – 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 (Optional[Sequence[float]]) – 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 (bool) – Whether to plot the associated geometry (if any).

• geom_kwargs (dict) – Keyword arguments to pass to the geometry plot of the associated geometry.

• backend (str) – The backend to use to generate the figure.

Return type:

WavefunctionPlot

See also

WavefunctionPlot

The plot class used to generate the plot.

EigenstateData

The class to which data is converted.

remove(index, inplace=False)

Return a new state without the specified indices

Parameters:

• index (int | Sequence[int] | Sequence[bool]) – indices that are removed in the returned object

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

• statec (StateC)

Returns:

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

Return type:

StateC

rotate(phi=0.0, individual=False, inplace=False)

Rotate all states to rotate the largest component to be along the angle phi

The states will be rotated according to:

$${\mathbf{S}}^{\prime }=\mathbf{S}/{\mathbf{S}}_{\varphi -\max }^{†}\exp (i\varphi ),$$

where ${\mathbf{S}}_{\varphi -\max }^{†}$ is the phase of the component with the largest amplitude and $\varphi$ 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.

• inplace (bool) – whether to do the rotation on the object it-self (True), or return a copy with the rotated states (False).

• state (State)

Return type:

State | None

sort(ascending=True)

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

Parameters:

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

spin_berry_curvature(sigma='z', sum=True, *, distribution=None, J_axes='xyz', **berry_kwargs)

Calculate the spin Berry curvature

This is equivalent to calling berry_curvature with the spin current operator and the regular velocity operator instead of $v^{\alpha }$:

def noop(M, d): return M
def Jz(M, d):
    if d in J_axes:
        return (M @ sigma_z + sigma_z @ M) * 0.5
    return M

state.berry_curvature(..., operator=(Jz, noop))

I.e. the left velocity operator being swapped with the spin current operator:

$$J^{\gamma \alpha }=\frac{1}{2}\{v^{\alpha },{\hat{\sigma }}^{\gamma }\}$$

where $\{\}$ means the anticommutator.

When calling it like this, the spin Berry curvature is found in the index corresponding to the axes the spin operator is acting on. The regular spin Berry curvature is found in all indices (J_axes).

E.g. if J_axes = 'xy', sigma = 'z', then shc[[0, 1]] will be the spin Berry curvature using the Pauli matrix ${\hat{\sigma }}^z$ (not the spin-operator ${\hat{s}}^z={\displaystyle \frac{\hslash }{2}}{\hat{\sigma }}^z$), and shc[2] will be the normal Berry curvature (since only the left velocity operator will be changed for J_axes).

Notes

For performance reasons, it can be very benificial to extract the above methods and call berry_curvature directly. This is because the $\sigma$ operator gets created on every call of this method.

This, repeated matrix creation, might change in the future.

Parameters:

• sigma (Union[CartesianAxisStrLiteral, npt.ArrayLike]) – which Pauli matrix is used, alternatively one can pass a custom spin matrix, or the full sigma.

• J_axes (Union[CartesianAxisStrLiteral, Sequence[CartesianAxisStrLiteral]]) – the direction(s) where the $J^{\sigma }$ operator will be applied, defaults to all.

• **kwargs – see berry_curvature for the remaining arguments.

• state (StateCElectron)

• sum (bool)

• distribution (Optional[DistributionType])

Return type:

np.ndarray

See also

berry_curvature

calculate the Berry curvature (internally called)

derivative

method for calculating the exact derivatives

ahc

anomalous Hall conductivity

shc

spin Hall conductivity

Returns:

Spin Berry curvature + (possibly Berry curvature) returned in certain dimensions. If one passes axes to the derivative_kwargs argument one will get dimensions according to the number of axes requested, by default all axes will be used (even if they are non-periodic). The dtype will be imaginary. The unit is ${\mathrm{Ang}}^2$.

Return type:

bc

Parameters:

• state (StateCElectron)

• sigma (Union[CartesianAxisStrLiteral, npt.ArrayLike])

• sum (bool)

• distribution (Optional[DistributionType])

• J_axes (Union[CartesianAxisStrLiteral, Sequence[CartesianAxisStrLiteral]])

spin_moment(projection='diagonal')

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:

projection – whether the moments are orbitally resolved or not

sub(index, inplace=False)

Return a new state with only the specified states

Parameters:

• index (int | Sequence[int] | Sequence[bool]) – indices that are retained in the returned object

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

• statec (StateC)

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) – whether the states are normalized upon return, may be useful for eigenstates, equivalent to state.tile().normalize()

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

• state (State)

Return type:

State

See also

Geometry.tile, Grid.tile, Lattice.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

See also

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.

The unit is Ang/ps.

Notes

The velocities are calculated without the Berry curvature contribution see Eq. (2) in [14]. It is thus typically denoted as the effective velocity operater (see Ref. 21 in [14]. The missing contribution may be added in later editions, for completeness sake, it is:

$$\delta \mathbf{v}=-\mathbf{k}\times {\mathrm{\Omega }}_i(\mathbf{k})$$

where ${\mathrm{\Omega }}_i$ is the Berry curvature for state $i$.

Parameters:

• *args – arguments passed directly to derivative, see that method for argument details.

• **kwargs – arguments passed directly to derivative, see that method for argument details.

• state (StateCElectron)

See also

derivative

for details of the implementation

wavefunction(grid, spinor=0, eta=None)

Expand the coefficients as the wavefunction on grid as-is

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

c

property dkind

The data-type of the state (in str)

property dtype

Data-type for the state

property eig

Eigenvalues for each state

info

parent

plot

Plotting functions for the EigenstateElectron class.

property shape

Returns the shape of the state

state