sisl.physics.electron.StateCElectron¶
- class sisl.physics.electron.StateCElectron(state, c, parent=None, **info)[source]¶
Bases:
sisl.physics.electron._electron_State
,sisl.physics.StateC
A state describing a physical quantity related to electrons, with associated coefficients of the state
Methods
Sk
([format, spin])Retrieve the overlap matrix corresponding to the originating parent structure.
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
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
andinfo
are passed by referencedegenerate
(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\)
Return a normalized state where each state has \(|\psi|^2=1\)
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
([project])Calculate spin moment from the states
sub
(idx)Return a new state with only the specified states
velocity
([eps, project])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
The data-type of the state (in str)
Data-type for the state
Returns the shape of the 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, c, parent=None, **info)¶
Define a state container with a given set of states and coefficients for the states
- 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
- 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_phase
rotate states such that their phases align
- align_phase(other, copy=False)¶
Align other.state with the phases for this state, a copy of other is returned with rotated elements
States will be rotated by \(\pi\) provided the phase difference between the states are above \(|\Delta\theta| > \pi/2\).
- Parameters
See also
align_norm
re-order states such that site-norms have a smaller residual
- asCoefficient()¶
- asState()¶
- berry_curvature(complex=False, eps=0.0001)[source]¶
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\) and \(\tilde C_j\) belongs to the
r
andR
gauge, respectively.- Parameters
gauge ({'R', 'r'}) – specify the new gauge for the state coefficients
- copy()¶
Return a copy (only the coefficients and states are copied),
parent
andinfo
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
- 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
- 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
- inv_eff_mass_tensor(as_matrix=False, eps=0.001)[source]¶
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.
- 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
- 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
- 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
- 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
- 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.
- 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(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)¶
Return a new state with only the specified states
- velocity(eps=0.0001, project=False)[source]¶
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
See also
PDOS
for an explanation of the projections in case of project being True
- velocity_matrix(eps=0.0001)[source]¶
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.