BasisPair

Class Methods

`__init__`(systems[, m, product_of_parities, ...])	Create a basis for a pair of atoms.
`from_ket_atoms`(ket_atom_tuples, system_atoms)	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_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 the product of the parities of the two atoms. 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__(systems, m=None, product_of_parities=None, energy=None, energy_unit=None)[source]

Create a basis for a pair of atoms.

Parameters:

systems (Sequence[SystemAtom]) – tuple of two SystemAtom objects, which define the two atoms, from which the BasisPair is build. Both systems 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.
product_of_parities (Literal['even', 'odd', 'unknown'] | None) – The product parity of the states to consider. Default None, i.e. add all available states.
energy (tuple[float, float] | tuple[pairinteraction.units.PintFloat, pairinteraction.units.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_ket_atoms(ket_atom_tuples, system_atoms, delta_m=None, product_of_parities=None, delta_energy=None, delta_energy_unit=None, number_of_kets=None)[source]

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

Each element of ket_atom_tuples is a pair (ket1, ket2) of KetAtom objects.

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:

ket_atom_tuples (pairinteraction.ket.ket_pair.KetAtomTuple | Sequence[pairinteraction.ket.ket_pair.KetAtomTuple]) – A single pair (ket1, ket2) of KetAtom objects, or a list of such 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.
product_of_parities (Literal['even', 'odd', 'unknown'] | None) – Restrict to pair states with this product of single-atom parities. Default None means no parity restriction.
delta_energy (float | pairinteraction.units.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.

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_ket_atoms(
...     (ket, ket), [system, system], delta_energy=3, delta_energy_unit="GHz"
... )

get_amplitudes(other)[source]

Overloads:

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

Parameters:

other (TypeAliasForwardRef('pairinteraction.ket.ket_pair.KetPairLike') | BasisPair | tuple[BasisAtom, BasisAtom] | Sequence[BasisAtom])

Return type:

TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | csr_matrix

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_corresponding_state(ket)

Return type:: TypeVar(StateType, bound= StateBase[Any])
Parameters:: ket (KetBase)

get_corresponding_state_index(ket)

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

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) → NDArray
self, other (BasisPairLike) → csr_matrix

Parameters:

other (TypeAliasForwardRef('pairinteraction.ket.ket_pair.KetPairLike') | BasisPair | tuple[BasisAtom, BasisAtom] | Sequence[BasisAtom])

Return type:

TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | csr_matrix

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

Overloads:

self, other (KetPairLike), operators (tuple[OperatorType, OperatorType]), qs (tuple[int, int]), unit (None) → PintArray
self, other (KetPairLike), 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 (TypeAliasForwardRef('pairinteraction.ket.ket_pair.KetPairLike') | BasisPair | tuple[BasisAtom, BasisAtom] | Sequence[BasisAtom])
operators (tuple[Literal['zero', 'energy', 'electric_dipole', 'electric_quadrupole', 'electric_quadrupole_zero', 'electric_octupole', 'magnetic_dipole', 'identity', 'arbitrary'], ~typing.Literal['zero', 'energy', 'electric_dipole', 'electric_quadrupole', 'electric_quadrupole_zero', 'electric_octupole', 'magnetic_dipole', 'identity', 'arbitrary']])
qs (tuple[int, int])
unit (str | None)

Return type:

TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | TypeAliasForwardRef(‘pairinteraction.units.PintArray’) | csr_matrix | TypeAliasForwardRef(‘pairinteraction.units.PintSparse’)