sisl.physics.electron.StateElectron

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

Bases: _electron_State, State

A state describing a physical quantity related to electrons

Methods

`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
`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, 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
`norm`()	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\)
`normalize`()	Return a normalized state where each state has \(\|\psi\|^2=1\)
`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 vectors
`rotate`([phi, individual])	Rotate all states (in-place) to rotate the largest component to be along the angle phi
`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
`wavefunction`(grid[, spinor, eta])	Expand the coefficients as the wavefunction on grid as-is
`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, 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, parent=None, **info): Define a state container with a given set of 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.

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 \(|\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

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

property dkind: The data-type of the state (in str)

property dtype: Data-type for the 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 &\quad \text{extended state} \\ \text{const.} &\quad \text{localized state} \end{aligned}\right. \end{align}

For further details see [5]. 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

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 = 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_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'

remove(idx, inplace=False)

Return a new state without the specified vectors

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

State

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

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 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, optional) – whether the states are normalized upon return, may be useful for eigenstates
offset (float, optional) – the offset for the phase factors

See also

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

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.