StateC¶

class sisl.physics.StateC(state, c, parent=None, **info)¶

Bases: sisl.physics.State

An object handling a set of vectors describing a given state with associated coefficients c

c¶

coefficients assigned to each state

Type: numpy.ndarray

state¶

state coefficients

Type: numpy.ndarray

info¶

information regarding the creation of the states

Type: dict

parent¶

object from where the states has been calculated, in one way or the other

Type: obj

Parameters

state (array_like) – state vectors state[i, :] containing the i’th state vector
c (array_like) – coefficients for the states c[i] containing the i’th coefficient
parent (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!

Attributes

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

Methods

`__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().
`_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`()
`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
`inner`([right, diagonal, align])	Return the inner product as \(\mathbf M_{ij} = \langle\psi_i\|\psi'_j\rangle\)
`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\)
`normalize`()	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)
`sub`(idx)	Return a new state with only the specified 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

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()[source]¶

asState()[source]¶

c¶

copy()[source]¶: Return a copy (only the coefficients and states are copied), parent and info are passed by reference

degenerate(eps)[source]¶

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

info¶

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

Return the inner product as \(\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)

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 inner state products
Return type: numpy.ndarray

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

normalize()[source]¶

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

outer(idx=None)[source]¶

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)[source]¶

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

state¶

sub(idx)[source]¶

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