sisl.physics.electron.EigenvectorElectron

class sisl.physics.electron.EigenvectorElectron

Bases: StateElectron

Eigenvectors of electronic states, no eigenvalues retained

This holds routines that enable the calculation of spin moments.

Methods

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
change_gauge(gauge[, offset])	In-place change of the gauge of the state coefficients
copy()	Return a copy (only the state is copied).
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$
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 vectors
rotate([phi, individual, inplace])	Rotate all states to rotate the largest component to be along the angle phi
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
wavefunction(grid[, spinor, eta])	Expand the coefficients as the wavefunction on grid as-is

Attributes

dkind	The data-type of the state (in str)
dtype	Data-type for the state
info
parent
shape	Returns the shape of the state
state

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

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 state is copied). parent and info are passed by reference

Parameters:

state (State)

Return type:

State

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 = State(np.arange(10))
>>> n = state.norm()
>>> norm_state = State(state.state / n.reshape(-1, 1))

Notes

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

Returns:

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

Return type:

State

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'

remove(index, inplace=False)

Return a new state without the specified vectors

Parameters:

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

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

• state (State)

Returns:

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

Return type:

State

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

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

• state (State)

Returns:

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

Return type:

State

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

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.

property dkind

The data-type of the state (in str)

property dtype

Data-type for the state

info

parent

property shape

Returns the shape of the state

state