ElecSus: Modeling Alkali Vapor Susceptibility

• ElecSus is an open-source Python package that models the complex electric susceptibility in alkali-metal vapors using Hamiltonian diagonalization.
• It supports both axial and arbitrary magneto-optic geometries, incorporating buffer-gas effects and dual-temperature control for accurate spectral predictions.
• The toolkit is validated in applications such as Faraday filter design, optical metrology, and vector magnetometry, featuring efficient fitting routines.

Searching arXiv for ElecSus papers and related applications. ElecSus is an open-source Python package and underlying model for calculating the complex electric susceptibility $\chi(\omega)$ of an alkali-metal vapour in the weak-probe approximation. It uses a matrix representation of the atomic Hamiltonian in the completely uncoupled basis to calculate transition frequencies and strengths, and from these predicts absorption, dispersion, polarization rotation, refractive indices, Stokes parameters, and related spectra for optical fields propagating through thermal vapours in magnetic fields. In its original formulation it targeted axial-field spectroscopy and device design for Faraday rotators, Faraday filters, optical isolators, and circular polarisation filters, while also providing fitting routines for optical metrology (Zentile et al., 2014).

1. Origins, scope, and development

The original ElecSus release presented a computer program to calculate the electric susceptibility of a gas, with a specific focus on alkali-metal vapours. Its central domain was weak-probe spectroscopy in thermal vapours of Na, K, Rb, and Cs, with line selection on the D$_1$ and D$_2$ transitions and an applied axial magnetic field. The program calculated various spectra for a weak-probe laser beam in an atomic medium and exposed both forward modelling and fitting routines for experiment comparison (Zentile et al., 2014).

A major subsequent update extended ElecSus to arbitrary geometry magneto-optics. The most important change was support for non-axial magnetic fields, which required a more general treatment of light propagation in anisotropic media. That release also introduced a graphical user interface front-end and improved several aspects of the program structure (Keaveney et al., 2017).

Later work documented further extension of the code base rather than a fixed static model. One line of development incorporated buffer-gas broadening and pressure shifts into potassium D$_1$ modelling, including dual-temperature handling for cell body and stem temperatures (Alqarni et al., 10 Apr 2025). Another added a lithium-specific subpackage so that both D-lines in both stable isotopes, $^6$Li and $^7$Li, could be treated simultaneously in hot-vapour Faraday-filter calculations (Luka et al., 13 Oct 2025). This progression suggests a transition from an axial weak-probe spectroscopy code to a broader magneto-optic toolkit spanning arbitrary geometry, buffer-gas environments, and additional atomic species.

2. Microscopic model of susceptibility

In ElecSus, the optical response is expressed through the complex refractive index $\hat n(\omega)=n(\omega)+i\beta(\omega)$ and the complex susceptibility $\chi(\omega)$, with

$$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$

for $|\chi|\ll1$. The real part $_1$0 gives dispersive phase shifts, while the imaginary part $_1$1 gives absorption; in a dilute atomic vapour the intensity decays as

$_1$2

where $_1$3 (Zentile et al., 2014).

The atomic structure calculation is based on a Hamiltonian assembled in the completely uncoupled basis. In the axial-field formulation this is written as

$_1$4

while the arbitrary-geometry treatment uses

$_1$5

The fine, hyperfine, and Zeeman interactions are assembled term by term and the resulting matrix is diagonalized numerically. Transition frequencies follow from the eigenenergies of the ground and excited manifolds, and line strengths are obtained from the corresponding eigenvectors using reduced dipole matrix elements and angular-momentum algebra (Zentile et al., 2014).

For a collection of independent resonances labelled by $_1$6, the susceptibility can be written as

$_1$7

Thermal motion broadens each transition through convolution with the one-dimensional Maxwell–Boltzmann distribution, producing a Voigt profile. In ElecSus this is evaluated through the Faddeeva function $_1$8, so that the Doppler-broadened line shape is generated efficiently and reused across transitions shifted by their respective resonance frequencies and weighted by their line strengths (Zentile et al., 2014).

In the presence of an axial magnetic field, the $_1$9 and $_2$0 components acquire different susceptibilities, $_2$1 and $_2$2. The relative phase then gives Faraday rotation,

$_2$3

where $_2$4 is the cell length. From the same susceptibility, ElecSus derives transmission, refractive index, group index, analyzer spectra, and Stokes parameters for arbitrary incident polarization states (Zentile et al., 2014).

3. Magneto-optic propagation and geometry handling

The arbitrary-geometry extension reformulated ElecSus as an anisotropic propagation problem. In that treatment one defines the partial susceptibilities $_2$5, $_2$6, and $_2$7 associated with $_2$8, $_2$9, and $_1$0 transitions. In a laboratory basis with light propagating along $_1$1 and the magnetic field in the $_1$2–$_1$3 plane, the dielectric tensor is expressed through

$_1$4

with off-diagonal magneto-optic terms $_1$5 (Keaveney et al., 2017).

Light propagation is then obtained by solving Maxwell’s wave equation in the medium,

$_1$6

which yields the refractive indices $_1$7 and the associated normal-mode polarizations. ElecSus packages this in a generalized Jones matrix,

$_1$8

so that absorption, phase shifts, and polarization rotation are handled within a single propagation formalism (Keaveney et al., 2017).

This framework recovers the standard special cases. In Faraday geometry, with $_1$9, the normal modes are left- and right-circular and the familiar circular birefringence picture is recovered. In Voigt geometry, with $^6$0, one mode is linearly polarized along the magnetic field and drives only $^6$1 transitions, while the orthogonal mode is an equal superposition of $^6$2 and $^6$3 and gives linear dichroism and the Voigt effect (Keaveney et al., 2017).

The Voigt-geometry spectroscopy studies give the operational form of this decomposition. With $^6$4 and $^6$5, a linearly polarised probe with polarization angle $^6$6 decomposes into an $^6$7 component that couples only to $^6$8 transitions and an $^6$9 component that couples only to $^7$0 transitions. The transmitted intensity becomes

$^7$1

which makes explicit how the polarization angle tunes between $^7$2- and $^7$3-dominated absorption (Keaveney et al., 2018).

4. Software organization, interfaces, and fitting routines

In the original release, ElecSus was described as a Python 2.x program organized around a small set of core modules. The main driver elecsus.py reads the run-card, calls the spectrum routines, and handles fitting and I/O; spectrum.py builds and diagonalizes Hamiltonians and computes $^7$4 and derived spectra; eigensystem.py provides the low-level eigenproblem interface; and fitting/*.py contains Marquardt–Levenberg, Random-Restart, and Simulated-Annealing routines. The numerical stack relies on NumPy, SciPy, and matplotlib (Zentile et al., 2014).

User input in that version is managed through a run-card specifying the atomic species, D-line, vapour-pressure temperature, Doppler-broadening temperature, cell length, axial magnetic field, detuning range, incident polarization, spectra to compute, and optional fit parameters. Command-line execution is performed with python elecsus.py myruncard.py, while output includes theory spectra, residual files, and best-fit parameters when fitting is enabled (Zentile et al., 2014).

Published workflows also show other interfaces. In a Faraday-filter modelling example, ElecSus is configured through a plain-text file containing species, isotope abundances, line selection, cell length, temperature, magnetic field, input polarization, and scan range, and can then be invoked either from the shell or directly from Python via calculate (Zentile et al., 2015). The arbitrary-geometry release added a graphical user interface front-end, and later examples used object-based APIs for susceptibility and filter classes in specialized extensions such as lithium modelling (Keaveney et al., 2017).

Fitting is a central feature rather than an auxiliary one. The original package included Marquardt–Levenberg as a fast local least-squares method, Random-Restart as repeated local fitting from random initial guesses, and Simulated-Annealing as a global minimization strategy (Zentile et al., 2014). In later arbitrary-geometry work, nonlinear least-squares fitting used lmfit, and the implementation emphasized vectorized operations, precomputation and caching of eigensystems, and multi-core fitting support (Keaveney et al., 2017).

5. Filter design, optimization, and metrological use

A prominent ElecSus application is the design of atomic Faraday filters. For a cesium D$^7$5-line Faraday filter, ElecSus was used to find optimal experimental parameters and identified a configuration with a magnetic field of 45.3 gauss and a temperature of 68.0$^7$6C in a 75 mm cell. In that operating point the filter simultaneously achieved a peak transmission of 77%, a passband of 310 MHz, and an equivalent noise bandwidth of 0.96 GHz, and experiment and theory showed excellent agreement (Zentile et al., 2015).

The relevant performance metrics are expressed explicitly in the ElecSus-based filter literature. One workflow defines

$^7$7

with $^7$8 in practice, and then uses $^7$9 as the optimization target (Zentile et al., 2015). A related Faraday-filter study defines

$\hat n(\omega)=n(\omega)+i\beta(\omega)$0

and uses a global-minimization meta-algorithm consisting of random-restart hill-climbing combined with Nelder–Mead downhill simplex to optimize magnetic field and temperature for a chosen cell length (Zentile et al., 2015).

That same study established an important limitation of simplified filter models: homogeneous line broadening drastically affects performance, self-broadening is particularly important for short vapour cells and for wing-type filters, and additional homogeneous broadening from background buffer gas may be required for accurate fits. In a 1 mm$\hat n(\omega)=n(\omega)+i\beta(\omega)$1, 99% $\hat n(\omega)=n(\omega)+i\beta(\omega)$2Rb micro-fabricated cell with a small 1% $\hat n(\omega)=n(\omega)+i\beta(\omega)$3Rb impurity and a trace of unknown buffer gas, omitting the extra $\hat n(\omega)=n(\omega)+i\beta(\omega)$4 produced a simulated wing-type filter peak of approximately 0.8, whereas the experiment showed approximately 0.55. Adding $\hat n(\omega)=n(\omega)+i\beta(\omega)$5 MHz brought theory into excellent agreement, with RMS residual $\hat n(\omega)=n(\omega)+i\beta(\omega)$6; removing self-broadening again overestimated the transmission (Zentile et al., 2015). The same work explicitly advises against simply rescaling $\hat n(\omega)=n(\omega)+i\beta(\omega)$7, because both Doppler and self-broadening shift the optimum profile.

Beyond filter design, ElecSus has been used as an optical metrology tool. On the potassium D lines, weak-probe transmission spectra measured across a wide temperature range agreed with ElecSus with rms errors of approximately $\hat n(\omega)=n(\omega)+i\beta(\omega)$8 to $\hat n(\omega)=n(\omega)+i\beta(\omega)$9, providing the first experimental test of ElecSus on an atom whose ground-state hyperfine splitting is smaller than the Doppler width (Hanley et al., 2015). In that study, fitting the 4S$\chi(\omega)$04P D-line transmission returned the cell temperature with a precision of $\chi(\omega)$1C, and a proposed two-beam method for 4S$\chi(\omega)$25P spectroscopy was predicted to measure transition decay rates with precision $\chi(\omega)$3 kHz (Hanley et al., 2015).

6. Experimental validation and later extensions

ElecSus has been validated quantitatively in non-axial geometries. In a detailed study of thermal $\chi(\omega)$4Rb vapour in the Voigt geometry for DC magnetic fields up to 0.4 T, fits to transmission spectra yielded RMS errors of $\chi(\omega)$5 and extracted the magnetic field strength and the angle between the light polarization and the magnetic field to within $\chi(\omega)$6 of a commercial Hall probe and to $\chi(\omega)$7 rad, respectively (Keaveney et al., 2018). At still higher field, a 1.5 T Voigt-geometry study fitted all Stokes parameters with RMS errors of $\chi(\omega)$8 on $\chi(\omega)$9 and $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$0 on $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$1, extracted $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$2 T, and showed that including birefringent entrance and exit cell windows significantly reduced residuals, especially in $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$3 (Ponciano-Ojeda et al., 2020).

Buffer-gas modelling has become an explicit extension of the ElecSus formalism. For potassium D$$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$4 spectroscopy in neon-filled sealed cells, the susceptibility denominator was modified from $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$5 to $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$6, so that pressure shifts and pressure broadening enter directly into the Voigt profile (Alqarni et al., 10 Apr 2025). In that work, dual-temperature control was built into ElecSus by assigning the Doppler width to the cell-body temperature $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$7 and the number density to the stem temperature $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$8. At 100 Torr of neon, fits returned $$\hat n(\omega)=\sqrt{1+\chi(\omega)}\approx 1+\chi(\omega)/2$$9 MHz and $|\chi|\ll1$0 MHz; across pressures the best-fit slopes were $|\chi|\ll1$1 MHz/Torr for broadening and $|\chi|\ll1$2 MHz/Torr for shift, with weighted-residual rms error below 0.5% across a 16 GHz scan (Alqarni et al., 10 Apr 2025).

A related Stokes-polarimetry study on potassium D$|\chi|\ll1$3 with 60 Torr neon used ElecSus in the Faraday geometry for magnetic fields up to 1.2 kG. Measurements at five stem temperatures and three magnetic fields showed excellent agreement for $|\chi|\ll1$4 and $|\chi|\ll1$5 absorptive features and accurate reproduction of the rapid dispersive oscillations in $|\chi|\ll1$6 and $|\chi|\ll1$7, with RMS residuals below 1% in one set of measurements and below 1.5% in another (Alqarni et al., 24 Jul 2025). That work identified pressure broadening, pressure shift, and damping of $|\chi|\ll1$8 and $|\chi|\ll1$9 zero-crossings as buffer-gas signatures that are reproduced only when collisional broadening is included.

The lithium extension further broadened the atomic scope of ElecSus. Because the $_1$00Li D$_1$01 line overlaps the $_1$02Li D$_1$03 line by only approximately 10 GHz, the extended model sums over both D-lines in both stable isotopes and introduces a dedicated elecsus.lithium subpackage with routines for the Hamiltonian, transition strengths, Voigt profiles, susceptibility calculation, and Faraday-filter transmission (Luka et al., 13 Oct 2025). A three-dimensional grid scan over temperature, magnetic field, and path length found an optimum near $_1$04C, $_1$05 G, and $_1$06 mm, where ElecSus forecast peak transmission $_1$07, $_1$08 GHz, and $_1$09 GHz$_1$10; experiment measured a peak of 82%, ENBW $_1$11 GHz, residuals below $_1$12, and identical wing structure over $_1$13 GHz detuning (Luka et al., 13 Oct 2025).

Taken together, these studies document ElecSus as a first-principles spectroscopy and magneto-optics framework built around Hamiltonian diagonalization, Voigt-profile susceptibility synthesis, and Jones-matrix propagation, with demonstrated use in filter optimization, thermometry, decay-rate inference, vector magnetometry, buffer-gas spectroscopy, and multi-isotope extensions across several alkali species.