pairinteraction 2.5.1

A Rydberg Interaction Calculator

PairInteraction - A Rydberg Interaction Calculator

Note: This is a completely new version of the PairInteraction software that is not backward compatible to versions below v1.0.

The PairInteraction software calculates properties of Rydberg atoms. The software consists of a Python library and a graphical user interface for obtaining single-atom properties and calculating pair potentials, making use of a high-performance C++ backend. For a more detailed description of the software that is written to be accessible also to non-specialists, see the About page of the project. The software can be installed via pip (requires Python >= 3.10, for tips see our extended installation instructions):

pip install pairinteraction

You can use the PairInteraction software as a Python library, see our quick start guide to get started in 5 minutes, or you can launch its graphical user interface from the command line:

pairinteraction

Highlights

• For calculating Rydberg pair potentials, the software uses a similar approach to the old version of PairInteraction, the Alkali.ne Rydberg Calculator, and the rydcalc library. We optimized the construction and diagonalization of Hamiltonians, typically achieving a speedup of 5-20x compared to other implementations.

  

  Figure: Benchmarking the construction and diagonalization of a Hamiltonian of a pair of Rb 60S atoms for 100 different internuclear distances on an AMD Ryzen 7 5700G CPU using Windows 11. The Hilbert space comprises pair states that differ at most by 4 in n, l and 25GHz in energy. When supported, symmetries were used to reduce the Hilbert space size. See the benchmarking tool.

• The software uses single-channel quantum defect theory (SQDT) and also multi-channel quantum defect theory (MQDT) for the accurate description of atoms.

  The construction of Hamiltonians is accelerated by using pre-calculated matrix elements, which are stored in database tables. These tables are automatically downloaded from GitHub [1,2] and cached locally when needed.

• Electric and magnetic fields in arbitrary directions can be included in the calculations. Diamagnetism is supported.

How to Cite

If you use PairInteraction in your research, please cite our paper:

Johannes Mögerle, Frederic Hummel, Alicia Keil, Tangi Legrand, Eduard J. Braun, Henri Menke, Jonathan King, Beatriz Olmos, Sebastian Hofferberth, Hans Peter Büchler, Sebastian Weber, Accurate Modeling of Rydberg Atoms and Their Interactions: Theory and Implementation in PairInteraction, arXiv:2605.14993

If you would like to read more about the underlying theory and methods, we also refer to the original tutorial paper:

Sebastian Weber, Christoph Tresp, Henri Menke, Alban Urvoy, Ofer Firstenberg, Hans Peter Büchler, Sebastian Hofferberth, Tutorial: Calculation of Rydberg interaction potentials, J. Phys. B: At. Mol. Opt. Phys. 50, 133001 (2017), arXiv:1612.08053

Quantum Defects

PairInteraction relies on quantum defects provided by the community. We encourage users to cite the relevant publications for their atomic species alongside PairInteraction.

Click to expand for quantum defect references

Element	Model	Identifier	References
H	SQDT	H	Schrödinger equation for hydrogen
Li	SQDT	Li	10.1017/CBO9780511524530 (1994) 10.1103/PhysRevA.34.2889 (1986)
Na	SQDT	Na	10.1088/0953-4075/30/10/009 (1997) 10.1070/QE1995v025n09ABEH000501 (1995) 10.1103/PhysRevA.45.4720 (1992)
K	SQDT	K	10.1088/0031-8949/27/4/012 (1983) 10.1016/0030-4018(81)90225-X (1981)
Rb	SQDT	Rb	10.1103/PhysRevA.83.052515 (2011) 10.1103/PhysRevA.74.054502 (2006) 10.1103/PhysRevA.74.062712 (2006) 10.1103/PhysRevA.67.052502 (2003)
Cs	SQDT	Cs	10.1103/PhysRevA.93.013424 (2016) 10.1103/PhysRevA.35.4650 (1987) 10.1103/PhysRevA.26.2733 (1982)
Sr88	SQDT, singlet sector	Sr88_singlet	10.1103/PhysRevA.108.022815 (2023) 10.17169/refubium-34581 (2022)
Sr88	SQDT, triplet sector	Sr88_triplet	10.1016/j.cpc.2020.107814 (2021)
Sr87	MQDT	Sr87_mqdt	10.1088/1361-6455/ab4c22 (2019)
Sr88	MQDT	Sr88_mqdt	10.1088/1361-6455/ab4c22 (2019)
Yb171	MQDT	Yb171_mqdt	10.1103/PhysRevX.15.011009 (2025) 10.1103/mzsv-rckx (2025)
Yb173	MQDT	Yb173_mqdt	MQDT model formulated by us
Yb174	MQDT	Yb174_mqdt	10.1103/PhysRevX.15.011009 (2025) 10.1103/mzsv-rckx (2025)

The identifier can be used to specify an atomic species in the PairInteraction software.

Documentation

User Guide

• Installation - Whether you prefer an installation via pip or compiling from source, we've got all the information you need.

• Tutorials - Covering both the graphical user interface and the Python library, these tutorials enable you to leverage PairInteraction for your projects.

• API Reference - Documentation of classes and functions of PairInteraction's Python library.

• Publications - Find out more about the theory behind PairInteraction and how to cite it and the quantum defects you use.

• FAQs - Frequently asked questions.

Contributor Guide

• Getting Started as a Contributor - Discover the many ways you can help improve PairInteraction, from contributing to the repository to providing quantum defects.

• Overview of PairInteraction's Architecture - Find out how PairInteraction is structured.

• Style Guide - Learn about the coding style used in PairInteraction.

• Database Format - Explore the database for storing atomic states and matrix elements.

Utility Tools [External Links]

• MQDT.jl - Learn how to calculate states and matrix elements using multi-channel quantum defect theory with our tool written in Julia.

• RydState - Learn how to calculate Rydberg states and matrix elements using single quantum defect theory with our tool written in Python.

Contributors

The software is currently maintained by:

• Sebastian Weber
• Johannes Mögerle

In addition, the following people contributed significantly to the current and/or previous versions of the software (ordered by date of first contribution):

• Henri Menke - Former co-maintainer, Numerov integrator, contributions to the Python interface, continuous integration, packaging and binary builds
• Johannes Block - Calculation of Rydberg pair potentials near surfaces via static Green tensor
• Alexander Papageorge - Julia interface in legacy PairInteraction
• Patrick Mischke - GUI button for fitting c3/c6 coefficients, archlinux package
• Nicolas Zuber - Tutorial on Rydberg-ion interaction
• Simon Hollerith - Documentation of the graphical user interface (not yet in new version)
• Frederic Hummel - Julia package for multi-channel quantum defect theory, matrix elements
• Eduard J. Braun - Perturbative calculations, installation instructions for Windows
• Alicia Keil - Enhanced and redesigned calculation of Rydberg pair potentials near surfaces

We warmly welcome new contributions! Please see our contributor guide for more information!

The development of the PairInteraction software has been supported by the Institute for Theoretical Physics III of the University of Stuttgart, the Federal Ministry of Education and Research under the Grants QRydDemo and MUNIQC-Atoms, and the company Atom Computing. The development of the original version of the software started at the 5th Institute of Physics of the University of Stuttgart.

License

The PairInteraction software is licensed under LGPL v3. For more information, see LICENSE.txt.