sisl.physics.State
- class sisl.physics.State(state, parent=None, **info)
Bases:
ParentContainer
An object handling a set of vectors describing a given state
- Parameters:
state (array_like) – state vectors
state[i, :]
containing the i’th state vectorparent (obj, optional) – a parent object that defines the origin of the state.
**info (dict, optional) – an info dictionary that turns into an attribute on the object. This
info
may contain anything that may be relevant for the state.
Notes
This class should be subclassed!
Methods
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|\psi\rangle\)
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
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
The data-type of the state (in str)
Data-type for the state
Returns the shape of the state
- align_norm(other, ret_index=False, inplace=False)[source]
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:
- 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)[source]
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:
See also
align_norm
re-order states such that site-norms have a smaller residual
- change_gauge(gauge, offset=(0, 0, 0))[source]
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 mode coefficients
offset (array_like, optional) – whether the coordinates should be offset by another phase-factor
- 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)[source]
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:
- ipr(q=2)[source]
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)[source]
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()[source]
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)[source]
Return a vector with the norm of each state \(\langle\psi|\psi\rangle\)
- 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()[source]
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:
- outer(ket=None, matrix=None)[source]
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:
- parent
- phase(method='max', ret_index=False)[source]
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'
- rotate(phi=0.0, individual=False)[source]
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
- state
- tile(reps, axis, normalize=False, offset=0)[source]
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:
See also
Geometry.tile
- translate(isc)[source]
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