KetAtom

Class Methods

__init__(species[, n, nu, nui, l, s, j, ...])	Create a single-atom canonical basis state, which is defined by its species and quantum numbers.
get_black_body_transition_rates(temperature)	Calculate the black body transition rates of the KetAtom.
get_energy([unit])	Get the energy of the ket in the given unit.
get_label([fmt])	Label representing the ket.
get_lifetime([temperature, ...])	Calculate the lifetime of the KetAtom.
get_matrix_element(ket, operator, q[, unit])	Get the matrix element between two atomic basis states from the database.
get_quantum_number(name)	Return the quantum number with the given name.
get_quantum_number_std(name)	Return the standard deviation of the quantum number with the given name.
get_spontaneous_transition_rates([unit])	Calculate the spontaneous transition rates for the KetAtom.
to_state()	Create a canonical state representing the single ket.

Class Attributes and Properties

database	The database from which the KetAtom was loaded.
f	The total momentum quantum number f (int or half-int).
f_core	The expectation value of the total momentum quantum number f_{core} of the ionic core.
f_core_std	The standard deviation of the total momentum quantum number f_{core} of the ionic core.
i_core	The expectation value of the nuclear spin quantum number i_{core} of the ionic core.
i_core_std	The standard deviation of the nuclear spin quantum number i_{core} of the ionic core.
is_j_total_momentum	Whether j is the total momentum quantum number, otherwise f is the total momentum quantum number.
j	The expectation value of the total angular quantum number j of all valence electrons.
j_core	The expectation value of the total angular quantum number j_{core} of the core electron.
j_core_std	The standard deviation of the total angular quantum number j_{core} of the core electron.
j_ryd	The expectation value of the total angular quantum number j_{Ryd} of the Rydberg electron.
j_ryd_std	The standard deviation of the total angular quantum number j_{Ryd} of the Rydberg electron.
j_std	The standard deviation of the total angular quantum number j of all valence electrons.
l	The expectation value of the orbital quantum number l of all valence electrons.
l_core	The expectation value of the orbital quantum number l_{core} of the core electron.
l_core_std	The standard deviation of the orbital quantum number l_{core} of the core electron.
l_ryd	The expectation value of the orbital quantum number l_{Ryd} of the Rydberg electron.
l_ryd_std	The standard deviation of the orbital quantum number l_{Ryd} of the Rydberg electron.
l_std	The standard deviation of the orbital quantum number l of all valence electrons.
m	The magnetic quantum number m (int or half-int).
n	The principal quantum number n.
nu	The effective principal quantum number nu.
nui	The expectation value of the effective principal quantum numbers nu_i of the channels.
nui_std	The standard deviation of the effective principal quantum numbers nu_i of the channels.
parity	The parity of the ket.
s	The expectation value of the total spin quantum number s of all valence electrons.
s_core	The expectation value of the spin quantum number s_{core} of the core electron.
s_core_std	The standard deviation of the spin quantum number s_{core} of the core electron.
s_ryd	The expectation value of the spin quantum number s_{Ryd} of the Rydberg electron.
s_ryd_std	The standard deviation of the spin quantum number s_{Ryd} of the Rydberg electron.
s_std	The standard deviation of the total spin quantum number s of all valence electrons.
species	The atomic species.
underspecified_channel_contribution	The contribution of channels whose quantum numbers are not exactly known.

class KetAtom

Ket for an atomic basis state.

Each KetAtom object uniquely represents a single-atom basis state (and therefore all KetAtom objects are orthogonal). When initializing a KetAtom you have to provide the species of the atom and a combination of quantum numbers, which uniquely define a single-atom basis state (this always includes providing a magnetic quantum number m).

SQDT (Single Channel Quantum Defect Theory) for one valence electron (alkali atoms):

The quantum numbers n (int), l (int), j (half-int) and m (half-int) should be used to define the desired atomic basis state. All other quantum numbers are trivially derived from these: s = 1/2, f = j (we neglect hyperfine interaction for SQDT), nu = n - delta, l_ryd = l, j_ryd = j.

SQDT (Single Channel Quantum Defect Theory) for two valence electrons (divalent atoms):

The quantum numbers n (int), l_ryd (int), s (0 or 1), j (int) and m (int) should be used to define the desired atomic basis state. For divalent atoms the spin quantum number s selects the singlet (s=0) or the triplet (s=1) sector, which are both contained in the same database (e.g. “Sr88_sqdt”). Again we neglect hyperfine interaction, thus f = j. And nu = n - delta. All other quantum numbers are not necessarily eigenvalues anymore and are given as expectation values.

MQDT (Multi Channel Quantum Defect Theory) for two valence electrons (divalent atoms):

The quantum numbers nu (float), f (int or half-int) and m (int or half-int) are still good quantum numbers. All other quantum numbers (like l, s, j, l_ryd, j_ryd) are not necessarily eigenvalues anymore. You can still provide them to specify the atomic basis state, whose expectation value is closest to the provided value.

All the quantum numbers of the three coupling schemes are available as attributes:

General angular quantum numbers: l_ryd, s_ryd, l_core, s_core and i_core. LS coupling of all valence electrons: l, s, j. JJ coupling of the electrons: j_ryd, j_core. FJ coupling of the hyperfine structure of the ionic core: f_core. Each of these has a companion attribute with a “_std” suffix holding its standard deviation, which is zero for quantum numbers that are exact.

Examples

>>> import pairinteraction as pi
>>> ket_s = pi.KetAtom("Rb", n=60, l=0, m=0.5)
>>> (ket_s.species, ket_s.n, ket_s.l, ket_s.j, ket_s.m, ket_s.s)
('Rb', 60, 0.0, 0.5, 0.5, 0.5)
>>> print(ket_s)
|Rb:60,S_1/2,1/2⟩
>>> print(ket_s.to_state())
1.00 |Rb:60,S_1/2,1/2⟩
>>> ket_p = pi.KetAtom("Rb", n=60, l=1, j=0.5, m=0.5)
>>> print((2 * ket_p - ket_s).normalize())
0.89 |Rb:60,P_1/2,1/2⟩ - 0.45 |Rb:60,S_1/2,1/2⟩
>>> ket_mqdt = pi.KetAtom("Yb174_mqdt", nu=60, l=1, f=1, m=1)
>>> (ket_mqdt.species, round(ket_mqdt.nu, 3), ket_mqdt.f, ket_mqdt.m)
('Yb174_mqdt', 60.049, 1.0, 1.0)
>>> print(ket_mqdt)
|Yb174:S=0.0,nu=60.0,L=1.0,J=1,1⟩

__init__(species, n=None, nu=None, nui=None, l=None, s=None, j=None, l_ryd=None, j_ryd=None, l_core=None, j_core=None, f_core=None, f=None, m=None, energy=None, energy_unit=None, parity=None, database=None)

Create a single-atom canonical basis state, which is defined by its species and quantum numbers.

Parameters:

• species (str) – See attribute.

• n (int | None) – See attribute. Default None, i.e. load from the database.

• nu (float | None) – See attribute. Default None, i.e. load from the database.

• nui (float | None) – See attribute. Default None, i.e. load from the database.

• l (float | None) – See attribute. Default None, i.e. load from the database.

• s (float | None) – See attribute. Default None, i.e. load from the database.

• j (float | None) – See attribute. Default None, i.e. load from the database.

• l_ryd (float | None) – See attribute. Default None, i.e. load from the database.

• j_ryd (float | None) – See attribute. Default None, i.e. load from the database.

• l_core (float | None) – See attribute. Default None, i.e. load from the database.

• j_core (float | None) – See attribute. Default None, i.e. load from the database.

• f_core (float | None) – See attribute. Default None, i.e. load from the database.

• f (float | None) – See attribute. Default None, i.e. load from the database.

• m (float | None) – See attribute. This should always be provided.

• energy (float | pairinteraction.units.PintFloat | None) – See attribute. Default None, i.e. load from the database.

• energy_unit (str | None) – In which unit the energy is given, e.g. “GHz”. Default None, i.e. energy is provided as pint object.

• parity (Literal['even', 'odd'] | None) – See attribute. Default None, i.e. load from the database.

• database (Database | None) – Which database to use. Default None, i.e. use the global database instance.

Return type:

None

property database: Database

The database from which the KetAtom was loaded.

get_quantum_number(name)

Return the quantum number with the given name.

Parameters:

name (str) – The name of the quantum number, e.g. “n”, “s”, “l_ryd”, “j_core”.

Return type:

float

Returns:

The value of the quantum number.

get_quantum_number_std(name)

Return the standard deviation of the quantum number with the given name.

Quantum numbers that are exact (i.e. that the database does not store a standard deviation for) have a standard deviation of zero.

Parameters:

name (str) – The name of the quantum number, e.g. “n”, “s”, “l_ryd”, “j_core”.

Return type:

float

Returns:

The standard deviation of the quantum number.

property m: float

The magnetic quantum number m (int or half-int).

property f: float

The total momentum quantum number f (int or half-int).

property parity: Literal['even', 'odd']

The parity of the ket.

property species: str

The atomic species.

property n: int

The principal quantum number n.

property nu: float

The effective principal quantum number nu.

property nui: float

The expectation value of the effective principal quantum numbers nu_i of the channels.

property l: float

The expectation value of the orbital quantum number l of all valence electrons.

property s: float

The expectation value of the total spin quantum number s of all valence electrons.

property j: float

The expectation value of the total angular quantum number j of all valence electrons.

property l_ryd: float

The expectation value of the orbital quantum number l_{Ryd} of the Rydberg electron.

property s_ryd: float

The expectation value of the spin quantum number s_{Ryd} of the Rydberg electron.

property j_ryd: float

The expectation value of the total angular quantum number j_{Ryd} of the Rydberg electron.

property l_core: float

The expectation value of the orbital quantum number l_{core} of the core electron.

property s_core: float

The expectation value of the spin quantum number s_{core} of the core electron.

property j_core: float

The expectation value of the total angular quantum number j_{core} of the core electron.

property i_core: float

The expectation value of the nuclear spin quantum number i_{core} of the ionic core.

property f_core: float

The expectation value of the total momentum quantum number f_{core} of the ionic core.

property nui_std: float

The standard deviation of the effective principal quantum numbers nu_i of the channels.

property l_std: float

The standard deviation of the orbital quantum number l of all valence electrons.

property s_std: float

The standard deviation of the total spin quantum number s of all valence electrons.

property j_std: float

The standard deviation of the total angular quantum number j of all valence electrons.

property l_ryd_std: float

The standard deviation of the orbital quantum number l_{Ryd} of the Rydberg electron.

property s_ryd_std: float

The standard deviation of the spin quantum number s_{Ryd} of the Rydberg electron.

property j_ryd_std: float

The standard deviation of the total angular quantum number j_{Ryd} of the Rydberg electron.

property l_core_std: float

The standard deviation of the orbital quantum number l_{core} of the core electron.

property s_core_std: float

The standard deviation of the spin quantum number s_{core} of the core electron.

property j_core_std: float

The standard deviation of the total angular quantum number j_{core} of the core electron.

property i_core_std: float

The standard deviation of the nuclear spin quantum number i_{core} of the ionic core.

property f_core_std: float

The standard deviation of the total momentum quantum number f_{core} of the ionic core.

property is_j_total_momentum: bool

Whether j is the total momentum quantum number, otherwise f is the total momentum quantum number.

Without a nuclear spin there is no hyperfine coupling, thus f = j and j is the total momentum quantum number.

property underspecified_channel_contribution: float

The contribution of channels whose quantum numbers are not exactly known.

to_state()

Create a canonical state representing the single ket.

The returned state has a minimal basis consisting only of this ket and a single coefficient equal to one.

Return type:

StateAtom

Returns:

A state object representing the ket.

get_matrix_element(ket, operator, q, unit=None)

Get the matrix element between two atomic basis states from the database.

Overloads:

• ket (Self | StateAtom), operator (Literal['zero', 'energy', 'electric_monopole', 'electric_dipole', 'electric_quadrupole', 'electric_quadrupole_zero', 'electric_octupole', 'magnetic_dipole', 'identity', 'arbitrary']), q (int), unit (None) = None → pairinteraction.units.PintFloat | pairinteraction.units.PintComplex

• ket (Self | StateAtom), operator (Literal['zero', 'energy', 'electric_monopole', 'electric_dipole', 'electric_quadrupole', 'electric_quadrupole_zero', 'electric_octupole', 'magnetic_dipole', 'identity', 'arbitrary']), q (int), unit (str) → float | complex

Parameters:

• ket (Self | StateAtom) – The second atomic basis state to calculate the matrix element with.

• operator (Literal['zero', 'energy', 'electric_monopole', 'electric_dipole', 'electric_quadrupole', 'electric_quadrupole_zero', 'electric_octupole', 'magnetic_dipole', 'identity', 'arbitrary']) – The operator, for which to calculate the matrix element.

• q (int) – The index for the matrix element.

• unit (str | None) – The unit to return the matrix element in. Default None will return a pint.Quantity.

Returns:

The matrix element between the two states in the given unit or as a pint.Quantity.

Return type:

PintFloat | PintComplex | float | complex

get_energy(unit=None)

Get the energy of the ket in the given unit.

Overloads:

• unit (None) = None → pairinteraction.units.PintFloat

• unit (str) → float

Parameters:

unit (str | None) – The unit to which to convert the energy to. Default None will return a pint.Quantity.

Returns:

The energy as float if a unit was given, otherwise a pint.Quantity.

Return type:

float | TypeAliasForwardRef(‘pairinteraction.units.PintFloat’)

get_label(fmt='raw')

Label representing the ket.

Parameters:

fmt (Literal['raw', 'ket', 'bra']) – The format of the label, i.e. whether to return the raw label, or the label in ket or bra notation.

Return type:

str

Returns:

The label of the ket in the given format.

get_spontaneous_transition_rates(unit=None)

Calculate the spontaneous transition rates for the KetAtom.

Overloads:

• unit (None) = None → tuple[list[KetAtom], pairinteraction.units.PintArray]

• unit (str) → tuple[list[KetAtom], pairinteraction.units.NDArray]

Parameters:

unit (str | None)

Return type:

tuple[list[KetAtom], TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | TypeAliasForwardRef(‘pairinteraction.units.PintArray’)]

The spontaneous transition rates are given by the Einstein A coefficients.

Parameters:

unit (str | None) – The unit to which to convert the result. Default None will return a pint.Quantity.

Returns:

The relevant states and the transition rates.

Return type:

tuple[list[KetAtom], TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | TypeAliasForwardRef(‘pairinteraction.units.PintArray’)]

get_black_body_transition_rates(temperature, temperature_unit=None, unit=None)

Calculate the black body transition rates of the KetAtom.

Overloads:

• temperature (float | pairinteraction.units.PintFloat), temperature_unit (str | None) = None, unit (None) = None → tuple[list[KetAtom], pairinteraction.units.PintArray]

• temperature (pairinteraction.units.PintFloat), *, unit (str) → tuple[list[KetAtom], pairinteraction.units.NDArray]

• temperature (float), temperature_unit (str), unit (str) → tuple[list[KetAtom], pairinteraction.units.NDArray]

Parameters:

• temperature (float | TypeAliasForwardRef('pairinteraction.units.PintFloat'))

• temperature_unit (str | None)

• unit (str | None)

Return type:

tuple[list[KetAtom], TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | TypeAliasForwardRef(‘pairinteraction.units.PintArray’)]

The black body transition rates are given by the Einstein B coefficients, with a weight factor given by Planck’s law.

Parameters:

• temperature (float | pairinteraction.units.PintFloat) – The temperature, for which to calculate the black body transition rates.

• temperature_unit (str | None) – The unit of the temperature. Default None will assume the temperature is given as pint.Quantity.

• unit (str | None) – The unit to which to convert the result. Default None will return a pint.Quantity.

Returns:

The relevant states and the transition rates.

Return type:

tuple[list[KetAtom], TypeAliasForwardRef(‘pairinteraction.units.NDArray’) | TypeAliasForwardRef(‘pairinteraction.units.PintArray’)]

get_lifetime(temperature=None, temperature_unit=None, unit=None)

Calculate the lifetime of the KetAtom.

Overloads:

• temperature (float | pairinteraction.units.PintFloat | None) = None, temperature_unit (str | None) = None, unit (None) = None → pairinteraction.units.PintFloat

• *, unit (str) → float

• temperature (pairinteraction.units.PintFloat), *, unit (str) → float

• temperature (float), temperature_unit (str), unit (str) → float

Parameters:

• temperature (float | TypeAliasForwardRef('pairinteraction.units.PintFloat') | None)

• temperature_unit (str | None)

• unit (str | None)

Return type:

float | TypeAliasForwardRef(‘pairinteraction.units.PintFloat’)

The lifetime is the inverse of the sum of all transition rates.

Parameters:

• temperature (float | pairinteraction.units.PintFloat | None) – The temperature, for which to calculate the black body transition rates. Default None will not include black body transitions.

• temperature_unit (str | None) – The unit of the temperature. Default None will assume the temperature is given as pint.Quantity.

• unit (str | None) – The unit to which to convert the result. Default None will return a pint.Quantity.

Returns:

The lifetime of the state.

Return type:

float | TypeAliasForwardRef(‘pairinteraction.units.PintFloat’)