EigenstateElectron¶

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

Bases: sisl.physics.electron.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).

Attributes

`__doc__`
`__module__`
`__slots__`
`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`

Methods

`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.
`__delattr__`	Implement delattr(self, name).
`__dir__`	Default dir() implementation.
`__eq__`	Return self==value.
`__format__`	Default object formatter.
`__ge__`	Return self>=value.
`__getattribute__`	Return getattr(self, name).
`__getitem__`(key)	Return a new state with only one associated state
`__gt__`	Return self>value.
`__hash__`	Return hash(self).
`__init__`(state, c[, parent])	Define a state container with a given set of states and coefficients for the states
`__init_subclass__`	This method is called when a class is subclassed.
`__iter__`([asarray])	An iterator looping over the states in this system
`__le__`	Return self<=value.
`__len__`()	Number of states
`__lt__`	Return self<value.
`__ne__`	Return self!=value.
`__new__`	Create and return a new object.
`__reduce__`	Helper for pickle.
`__reduce_ex__`	Helper for pickle.
`__repr__`	Return repr(self).
`__setattr__`	Implement setattr(self, name, value).
`__sizeof__`	Size of object in memory, in bytes.
`__str__`()	The string representation of this object
`__subclasshook__`	Abstract classes can override this to customize issubclass().
`_electron_State__is_nc`()	Internal routine to check whether this is a non-colinear calculation
`_sanitize_index`(idx)	Ensure indices are transferred to acceptable integers
`align_norm`(other[, ret_index])	Align other.state with the site-norms for this state, a copy of other is returned with re-ordered states
`align_phase`(other[, copy])	Align other.state with the phases for this state, a copy of other is returned with rotated elements
`asCoefficient`()
`asState`()
`berry_curvature`([complex, eps])	Calculate Berry curvature for the states
`change_gauge`(gauge)	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`(eps)	Find degenerate coefficients with a specified precision
`expectation`(A[, diag])	Calculate the expectation value of matrix A
`inner`([right, diagonal, align])	Return the inner product by \(\mathbf M_{ij} = \langle\psi_i\|\psi'_j\rangle\)
`inv_eff_mass_tensor`([as_matrix, eps])	Calculate inverse effective mass tensor for the states
`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\)
`occupation`([distribution])	Calculate the occupations for the states according to a distribution function
`outer`([idx])	Return the outer product for the indices idx (or all if `None`) by \(\sum_i\|\psi_i\rangle c_i\langle\psi_i\|\)
`phase`([method, return_indices])	Calculate the Euler angle (phase) for the elements of the state, in the range \(]-\pi;\pi]\)
`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`()	Calculate spin moment from the states
`spin_orbital_moment`()	Calculate spin moment per orbital from the states
`sub`(idx)	Return a new state with only the specified states
`velocity`([eps])	Calculate velocity for the states
`velocity_matrix`([eps])	Calculate velocity matrix for the states
`wavefunction`(grid[, spinor, eta])	Expand the coefficients as the wavefunction on grid as-is

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='csr', 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.

align_norm(other, ret_index=False)¶

Align other.state with the site-norms for this state, a copy of other is returned with re-ordered states

To determine the new ordering of other we 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 other) 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 onto this state
ret_index (bool, optional) – also return indices for the swapped indices

Returns

other_swap (State) – A swapped instance of other
index (array of int) – the indices that swaps other to be other_swap, i.e. other_swap = other.sub(index)

Notes

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

See also

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

asCoefficient()¶

asState()¶

berry_curvature(complex=False, eps=0.0001)¶

Calculate Berry curvature for the states

This routine calls berry_curvature with appropriate arguments and returns the Berry curvature for the states.

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

See berry_curvature for details.

Parameters

complex (logical, optional) – whether the returned quantity is complex valued
eps (float, optional) – precision used to find degenerate states.

c¶

change_gauge(gauge)¶

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\) belongs to the gauge R and \(\tilde C_j\) is in the gauge r.

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

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: list of numpy.ndarray

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

property dtype¶: Data-type for the state

property eig¶: Eigenvalues for each state

expectation(A, diag=True)¶

Calculate the expectation value of matrix A

The expectation matrix is calculated as:

\[A_{ij} = \langle \psi_i | \mathbf A | \psi_j \rangle\]

If diag is true, only the diagonal elements are returned.

Parameters

A (array_like) – a vector or matrix that expresses the operator A
diag (bool, optional) – whether only the diagonal elements are calculated or if the full expectation matrix is calculated

Returns

a vector if diag is true, otherwise a matrix with expectation values

Return type

numpy.ndarray

info¶

inner(right=None, diagonal=True, align=False)¶

Return the inner product by \(\mathbf M_{ij} = \langle\psi_i|\psi'_j\rangle\)

Parameters

right (State, optional) – the right object to calculate the inner product with, if not passed it will do the inner product with itself. This object will always be the left \(\langle\psi_i|\).
diagonal (bool, optional) – only return the diagonal matrix \(\mathbf M_{ii}\).
align (bool, optional) – first align right with the angles for this state (see align)

:raises ValueError : in case where right is not None and self and right has differing overlap matrix.:

Returns: a matrix with the sum of inner state products
Return type: numpy.ndarray

inv_eff_mass_tensor(as_matrix=False, eps=0.001)¶

Calculate inverse effective mass tensor for the states

This routine calls inv_eff_mass with appropriate arguments and returns the state inverse effective mass tensor. I.e. for non-orthogonal basis the overlap matrix and energy values are also passed.

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

See inv_eff_mass_tensor for details.

Notes

The reason for not inverting the mass-tensor is that for systems with limited periodicities some of the diagonal elements of the inverse mass tensor matrix will be 0, in which case the matrix is singular and non-invertible. Therefore it is the users responsibility to remove any of the non-periodic elements from the matrix.

Parameters

as_matrix (bool, optional) – if true the returned tensor will be a symmetric matrix, otherwise the Voigt tensor is returned.
eps (float, optional) – precision used to find degenerate states.

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(idx=None)¶

Return the outer product for the indices idx (or all if None) by \(\sum_i|\psi_i\rangle c_i\langle\psi_i|\)

Parameters: idx (int or array_like, optional) – only perform an outer product of the specified indices, otherwise all states are used
Returns: a matrix with the sum of outer state products
Return type: numpy.ndarray

parent¶

phase(method='max', return_indices=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
return_indices (bool, optional) – return indices for the elements used when method=='max'

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()¶

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.

spin_orbital_moment()¶

Calculate spin moment per orbital from the states

This routine calls spin_orbital_moment with appropriate arguments and returns the spin moment for each orbital on the states.

See spin_orbital_moment for details.

state¶

sub(idx)¶

Return a new state with only the specified states

Parameters: idx (int or array_like) – indices that are retained in the returned object
Returns: a new object with a subset of the states
Return type: StateC

velocity(eps=0.0001)¶

Calculate velocity for the states

This routine calls velocity with appropriate arguments and returns the velocity for the states. I.e. for non-orthogonal basis the overlap matrix and energy values are also passed.

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

See velocity for details.

Parameters: eps (float, optional) – precision used to find degenerate states.

velocity_matrix(eps=0.0001)¶

Calculate velocity matrix for the states

This routine calls velocity_matrix with appropriate arguments and returns the velocity for the states. I.e. for non-orthogonal basis the overlap matrix and energy values are also passed.

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

See velocity_matrix for details.

Parameters: eps (float, optional) – precision used to find degenerate states.

wavefunction(grid, spinor=0, eta=False)¶

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.