EigenstateElectron¶

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

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

`c`
`dkind`	The data-type of the state (in str)
`dtype`	Data-type for the state
`eig`
`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.
`__init__`(state, c[, parent])	Define a state container with a given set of states and coefficients for the states
`asCoefficient`()
`asState`()
`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
`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 norm of each state \(\sqrt{\langle\psi\|\psi\rangle}\)
`norm2`([sum])	Return a vector with the norm of each state \(\langle\psi\|\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\|\)
`psi`(grid[, spinor, eta])	Expand the coefficients as the wavefunction on grid as-is
`sort`([ascending])	Sort and return a new `StateC` by sorting the coefficients (default to ascending)
`spin_moment`()	Calculate spin moment 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-collinear 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.

asCoefficient()¶

asState()¶

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

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

dtype¶: Data-type for the state

eig¶

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:	expectation : a vector if diag is true, otherwise the expectation matrix

info¶

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.

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.

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.

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 norm of each state \(\sqrt{\langle\psi|\psi\rangle}\)

Returns:	numpy.ndarray the normalization for each state

norm2(sum=True)¶

Return a vector with the norm of each state \(\langle\psi|\psi\rangle\)

Parameters:	sum : bool, optional if true the summed orbital square is returned (a vector). For false a matrix with normalization squared per orbital is returned.
Returns:	numpy.ndarray the normalization on each orbital for each state

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:	state : a new state with all states normalized, otherwise equal to this

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:	numpy.ndarray : len(self) with occupation values

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:	numpy.ndarray : a matrix with the sum of outer state products

parent¶

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

Expand the coefficients as the wavefunction on grid as-is

See wavefunction for argument details.

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.

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:	StateC : a new object with a subset of the states

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.