BasisPair

Class Methods

`__init__`(system_atoms[, m, ...])	Create a basis for a pair of atoms.
`canonicalized`()	Return the canonical basis with identity coefficients.
`from_ket_atoms`(cls, ket_atom_tuples, ...[, ...])
`from_kets`(kets, system_atoms[, delta_m, ...])	Create a BasisPair from one or more pairs of kets with optional energy/m windows.
`get_amplitudes`(other)
`get_coefficients`()	Return the coefficients of the basis as a sparse matrix.
`get_corresponding_ket`(state)
`get_corresponding_ket_index`(state)
`get_corresponding_state`(ket)
`get_corresponding_state_index`(ket)
`get_ket`(index)	Return the ket at the given index.
`get_matrix_elements`(other, operators, qs[, unit])
`get_overlaps`(other)
`get_state`(index)	Return the state at the given index.

Class Attributes and Properties

`kets`	Return a list containing the kets of the basis.
`number_of_kets`	Return the number of kets in the basis.
`number_of_states`	Return the number of states in the basis.
`states`	Return a list containing the states of the basis.
`system_atoms`	The two SystemAtom objects, from which the BasisPair is build.

class BasisPair[source]

Basis for a pair of atoms.

Add all product states of the eigenstates of two given SystemAtom objects to the basis, which pair energy is within the given energy range. You can also specify which total magnetic quantum number m the pair should have (if it is conserved) and which parities under inversion and permutation should be used for symmetrization. Due to the possible restrictions of the basis states, the BasisPair coefficients matrix will in general not be square but (n x d), where n is the number of all involved kets (typically basis1.number_of_kets * basis2.number_of_kets) and d is the number of basis states (after applying the restrictions).

Examples

>>> import pairinteraction as pi
>>> ket = pi.KetAtom("Rb", n=60, l=0, m=0.5)
>>> basis = pi.BasisAtom("Rb", n=(58, 63), l=(0, 3))
>>> system = pi.SystemAtom(basis).set_magnetic_field([0, 0, 1], unit="G").diagonalize()
>>> pair_energy = 2 * system.get_corresponding_energy(ket, unit="GHz")
>>> pair_basis = pi.BasisPair(
...     [system, system],
...     energy=(pair_energy - 3, pair_energy + 3),
...     energy_unit="GHz",
... )
>>> print(pair_basis)
BasisPair(|Rb:59,S_1/2,-1/2; Rb:61,S_1/2,-1/2⟩ ... |Rb:58,F_7/2,7/2; Rb:59,S_1/2,1/2⟩)

__init__(system_atoms, m=None, parity_under_inversion=None, parity_under_permutation=None, energy=None, energy_unit=None)[source]

Create a basis for a pair of atoms.

Parameters:

system_atoms (Sequence[SystemAtom]) – tuple of two SystemAtom objects, which define the two atoms, from which the BasisPair is build Both system_atoms have to be diagonalized before creating the BasisPair.
m (tuple[float, float] | None) – tuple of (min, max) values for the total magnetic quantum number m of the pair state. Default None, i.e. no restriction.
parity_under_inversion (Parity | None) – Restrict to pair states with this parity under inversion. Default None, i.e. do not apply inversion symmetrization.
parity_under_permutation (Parity | None) – Restrict to pair states with this parity under permutation. Default None, i.e. do not apply permutation symmetrization.
energy (tuple[float, float] | tuple[PintFloat, PintFloat] | None) – tuple of (min, max) value for the pair energy. Default None, i.e. add all available states.
energy_unit (str | None) – In which unit the energy values are given, e.g. “GHz”. Default None, i.e. energy is provided as pint object.

Return type:

None

system_atoms: tuple[SystemAtom, SystemAtom]: The two SystemAtom objects, from which the BasisPair is build.

classmethod from_kets(kets, system_atoms, delta_m=None, parity_under_inversion=None, parity_under_permutation=None, delta_energy=None, delta_energy_unit=None, number_of_kets=None, *, warn_number_of_kets=True)[source]

Create a BasisPair from one or more pairs of kets with optional energy/m windows.

Currently a single big basis including all kets for the quantum numbers from min_value - delta to max_value + delta is returned. In the future this might change to return a basis including all states around the given kets +/- delta, but not necessarily all states between the given kets.

You can either give a delta_energy to restrict the basis size in energy, or give an (approximate) number_of_kets, which is used to construct a basis centered around the provided ket pairs with approximately that many kets. If there are multiple states with the same energy, the actual number of kets may be a bit higher than the specified number.

Parameters:

kets (KetPairLike | Sequence[KetPairLike]) – A single ket pair (given either as tuple (ket1, ket2) of KetAtom objects or as a KetPair object) or a list of ket pairs. Must not be empty.
system_atoms (Sequence[SystemAtom]) – A collection of exactly two diagonalized SystemAtom objects, one per atom.
delta_m (float | None) – Half-width of the total magnetic quantum number window m = m1 + m2. Default None means no m restriction.
parity_under_inversion (Parity | None) – Restrict to pair states with this parity under inversion. Default None means no inversion symmetrization.
parity_under_permutation (Parity | None) – Restrict to pair states with this parity under permutation. Default None means no permutation symmetrization.
delta_energy (float | PintFloat | None) – Half-width of the energy window. Mutually exclusive with number_of_kets. Default None means no energy restriction.
delta_energy_unit (str | None) – Unit for delta_energy and the pair energies (e.g. "GHz"). Default None means pint quantities are used.
number_of_kets (int | None) – Target number of pair kets to include. The method keeps the number_of_kets states closest in energy to the reference ket pairs. Mutually exclusive with delta_energy. Default None means no count restriction.
warn_number_of_kets (bool) – Don’t warn about the possible issues with using number_of_kets.

Return type:

Self

Returns:

A new BasisPair whose energy (and optionally m) range is determined by the provided ket pairs and the chosen restrictions.

Examples

>>> import pairinteraction as pi
>>> ket = pi.KetAtom("Rb", n=60, l=0, m=0.5)
>>> basis_atom = pi.BasisAtom("Rb", n=(58, 62), l=(0, 2))
>>> system = pi.SystemAtom(basis_atom).diagonalize()
>>> pair_basis = pi.BasisPair.from_kets(
...     (ket, ket), [system, system], delta_energy=3, delta_energy_unit="GHz"
... )

classmethod from_ket_atoms(cls, ket_atom_tuples, system_atoms, delta_m=None, parity_under_inversion=None, parity_under_permutation=None, delta_energy=None, delta_energy_unit=None, number_of_kets=None)[source]

Return type:

Self

Parameters:

ket_atom_tuples (KetAtomTuple | Sequence[KetAtomTuple])
system_atoms (Sequence[SystemAtom])
delta_m (float | None)
parity_under_inversion (Parity | None)
parity_under_permutation (Parity | None)
delta_energy (float | PintFloat | None)
delta_energy_unit (str | None)
number_of_kets (int | None)

get_corresponding_state(ket)[source]

Return type:: StatePair
Parameters:: ket (KetPairLike)

get_corresponding_state_index(ket)[source]

Return type:: int
Parameters:: ket (KetPairLike)

get_amplitudes(other)[source]

Overloads:

self, other (KetPairLike | StatePairLike) → NDArray
self, other (BasisPairLike) → csr_matrix

Parameters:

other (KetPairLike | StatePairLike | BasisPairLike)

Return type:

NDArray | csr_matrix

canonicalized()

Return the canonical basis with identity coefficients.

Return type:: Self
Parameters:: self (Self)

get_coefficients()

Return the coefficients of the basis as a sparse matrix.

The coefficients are stored in a sparse matrix with shape (number_of_kets, number_of_states), where the first index correspond to the kets and the second index correspond to the states. For example basis.get_coefficients()[i, j] is the i-th coefficient (i.e. the coefficient corresponding to the i-th ket) of the j-th state.

The coefficients are normalized, i.e. the sum of the absolute values of the coefficients in each row is equal to 1.

Return type:: csr_matrix

get_corresponding_ket(state)

Return type:

TypeVar(KetType, bound= KetBase)

Parameters:

self (Self)
state (StateType)

get_corresponding_ket_index(state)

Return type:: int
Parameters:: state (StateType)

get_ket(index)

Return the ket at the given index.

Return type:: TypeVar(KetType, bound= KetBase)
Parameters:: index (int)

get_state(index)

Return the state at the given index.

Return type:: TypeVar(StateType, bound= StateBase[Any])
Parameters:: index (int)

property kets: list[KetType]: Return a list containing the kets of the basis.

property number_of_kets: int: Return the number of kets in the basis.

property number_of_states: int: Return the number of states in the basis.

property states: list[StateType]: Return a list containing the states of the basis.

get_overlaps(other)[source]

Overloads:

self, other (KetPairLike | StatePairLike) → NDArray
self, other (BasisPairLike) → csr_matrix

Parameters:

other (KetPairLike | StatePairLike | BasisPairLike)

Return type:

NDArray | csr_matrix

get_matrix_elements(other, operators, qs, unit=None)[source]

Overloads:

self, other (KetPairLike | StatePairLike), operators (tuple[OperatorType, OperatorType]), qs (tuple[int, int]), unit (None) → PintArray
self, other (KetPairLike | StatePairLike), operators (tuple[OperatorType, OperatorType]), qs (tuple[int, int]), unit (str) → NDArray
self, other (BasisPairLike), operators (tuple[OperatorType, OperatorType]), qs (tuple[int, int]), unit (None) → PintSparse
self, other (BasisPairLike), operators (tuple[OperatorType, OperatorType]), qs (tuple[int, int]), unit (str) → csr_matrix

Parameters:

other (KetPairLike | StatePairLike | BasisPairLike)
operators (tuple[OperatorType, OperatorType])
qs (tuple[int, int])
unit (str | None)

Return type:

NDArray | PintArray | csr_matrix | PintSparse