Document electronic transitions

[hartytp]

Currently we don't properly document how we define electric dipole / quadrupole matrix elements and how scattering rates / Rabi frequencies should be calculated from them.

This has been discussed in a few places, opening a single issue here to track the discussion:

• Epole matrix element #19
• Expose matrix element calculation #27
• Added physics documentation #10

One thing to think about here is what level of documentation we want. My aim is explicitly not to write a text book on atomic physics; just to have enough documentation for the conventions / definitions to be clear to someone with a good understanding of (text book on) atomic physics.

In particular, I want to avoid the kind of explanations that one often finds in atomic physics which go "detail...detail...detail...wave hands...detail...detail". I don't think that is a useful thing for us to have. As such, I think we probably just need a much condensed version of #10 , which summarizes the results, but without as much of the workings.

NB there are a few FIXMEs which have crept in in places where I think we're doing something slightly odd in our electric multipole calculations. We should resolve these while tidying up the docs here.

[Xuhui-Yao]

I am trying to use atom_physics (version 2.0.1) to calculate some transitions of barium ions. Regarding the method cal_electric_multipoles(), I think there are two problems:

1. The program use np.linalg.eig() to find the energy eigenstates in (M_J,M_I) basis, but it doesn't ensure that in the low field limit, the sign of eigenstates (F,m_F) agree with Condon-Shortley phase. This will lead to an error in the sign of electric multipole matrix element in the low field limit; (this can be seen in the formula (55) of Ryan's notes Added physics documentation #10). I tried writing a small piece of code in the end of the __post_init_() method of class Atom to fix this issue：

            # Now we can assign the Condon-Shortley phase to the state vectors
            # to make sure consistent with wigner 3j symbol in low field limit
            phase = np.ones(state_vectors.shape)
            for i in range(I_dim * J_dim):
                for j in range(I_dim *  #J_dim):
                    mJ = -level.J + j // I_dim
                    mI = -self.nuclear_spin + j % I_dim
                    phase[j, i] = np.sign(wigner3j(
                        level.J, self.nuclear_spin, self.F[level_slice][i],
                        mJ, mI, -self.M[level_slice][i]
                    ))
                    phase[j,i] = (-1)**(level.J - self.nuclear_spin + self.M[level_slice][i]) * phase[j,i]

            self.state_vectors[level_slice, level_slice]  = np.abs(state_vectors) * phase

2. The matrix self._electric_multipoles is a lower triangular matrix, and since the eigenstates are arranged in descending order of energy, we may interpret the (i,j) element of the matrix (ignoring the nuclear spin) to be:

where I have use the definition of electric dipole operator in chapter 7.5 of Daniel A. Steck, Quantum and Atom Optics. Note that sign before wigner 3j symbol and the q = M_g - M_e is different from what was originally defined in the program. I didn't figure out the physical meaning of the original definition, while I think this new definition is clearer. It can be directly used to calculate the multipoles matrix element between hyperfine states, consistent with the result calculated using Wigner 6j symbol.

[hartytp]

The matrix self._electric_multipoles is a lower triangular matrix, and since the eigenstates are arranged in descending order of energy, we may interpret the (i,j) element of the matrix (ignoring the nuclear spin) to be:

Yes, this part of the code needs an overhaul. The first step here is updating the definitions and conventions part of the manual to include electronic transitions and be clear about what we're actually doing (I have a half-finished PR for this, which I'm hoping to get to in the next couple of weeks). Once that's done, we can update the code so that it actually returns a matrix of Rabi frequencies, rather than some amplitudes which are loosely related to the Rabi frequencies.