PQLS: Parallel Quantum Liouvillian Solver

PQLS is a high-performance, JAX-accelerated open quantum system solver specifically architected for Rydberg atomic physics and quantum sensing.

By mapping Lindblad master equation steady-states to compiler-optimized tensor operations, PQLS allows researchers to perform massive, multi-dimensional parameter sweeps (e.g., laser detunings, RF field amplitudes) in a fraction of a second.

Why PQLS?

• Hardware-Accelerated & Batched: Uses jax.vmap and XLA compilation to solve thousands of steady states simultaneously.
• Domain-Specific: Fully integrated with the Alkali Rydberg Calculator (ARC), automatically handling energy levels, decay rates, and dipole moments.
• Differentiable: Built entirely in pure JAX, making the physics fully compatible with automatic differentiation.
• Lightweight: Does not rely on heavy generalized frameworks for the core solver, keeping the dependency tree clean and fast.

---

Table of Contents

• Installation
• Quickstart
• Examples
• Testing & Benchmarking
• Documentation
• Acknowledgments

---

Installation

PQLS requires Python 3.12+. We highly recommend installing the package inside a virtual environment to prevent dependency conflicts.

Standard Installation (For Users)

Install PQLS directly from PyPI:

# Set up and activate the virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate

# Upgrade pip and install PQLS
pip install --upgrade pip
pip install pqls

Developer Installation (For Contributors)

If you plan to edit the source code, run benchmarks, or contribute to the project, install the package in "editable" mode along with the [dev] dependency group (which includes pytest, qutip, matplotlib, and our linter ruff):

# Install with all developer, testing, and documentation tools
pip install -e ".[dev]"

---

Quickstart

Simulating an N-level atomic system is as simple as defining the states and providing the driving fields. PQLS automatically queries ARC for the physical atomic properties and constructs the Lindbladian.

The Quickstart example also requires Matplotlib:

pip install matplotlib

import matplotlib.pyplot as plt
import numpy as np

from pqls import Driver, QuantumLadder, QuantumState, solve_quantum_ladder

# Define 4-level atomic ladder
ladder = QuantumLadder(
    "Rb85",
    [
        QuantumState(n=5, l=0, j=0.5, mj=0.5),    # |5S_1/2>
        QuantumState(n=5, l=1, j=1.5, mj=1.5),    # |5P_3/2>
        QuantumState(n=50, l=2, j=2.5, mj=2.5),   # |50D_5/2>
        QuantumState(n=51, l=1, j=1.5, mj=1.5),   # |51P_3/2>
    ],
)

# Set field amplitudes (Probe, Coupling, RF in V/m) and detuning sweep
drivers = [Driver(1.0), Driver(8.0e4), Driver(2.0)]
delta_c = np.linspace(-60e6, 60e6, 400)

# Solve steady state across coupling detuning in a single batched call
# The detunings list is aligned with the driver order: [Probe, Coupling, RF]
coherences = solve_quantum_ladder(ladder, drivers, detunings=[0.0, delta_c, 0.0])

# Plot transmission
plt.plot(delta_c / 1e6, np.exp(250.0 * coherences))
plt.xlabel("Coupling Detuning (MHz)")
plt.ylabel("Probe Transmission (a.u.)")
plt.title(r"$^{85}\mathrm{Rb}$ Rydberg Electrometry: Autler-Townes Splitting")
plt.grid(True)
plt.show()

---

Examples

In the examples/ directory, we provide examples that demonstrate both the functionality of PQLS and its performance.

• 01a_quickstart_ats.py: The minimal 4-level ladder simulation shown above using the high-level API.
• 01b_quickstart_ats_low_level.py: The same ATS system built from scratch using the lowest-level matrix API.
• 02_custom_network.py: Demonstrates modeling arbitrary topologies (e.g., $\Lambda$-systems with branching decays and Coherent Population Trapping) using the mid-level API.
• 03_heatmap.py: A highly-optimized, fully vectorized 2D parameter sweep (10,000+ points) producing interference heatmaps.
• 04_benchmark_qutip.py: A direct performance and accuracy benchmark of PQLS against QuTiP and QuTiP-JAX.
• 05_benchmark_scalability.py: A log-log scalability benchmark evaluating PQLS execution times (CPU/GPU) against Rydiqule.

Run any example directly from your terminal:

python examples/03_heatmap.py

---

Testing & Benchmarking

PQLS includes a rigorous test suite. Rather than just checking code execution, the test suite dynamically generates random Hamiltonians and verifies the JAX backend against QuTiP's standard steadystate solver.

Furthermore, the test suite enforces strict quantum mechanical invariants across all batched dimensions:

1. Unit Trace: $\text{Tr}(\rho) = 1$
2. Hermiticity: $\rho = \rho^\dagger$
3. Positive Semi-Definiteness: All eigenvalues $\ge 0$

Running the Tests

To run the test suite from a cloned PQLS repository, install the [test] or [dev] dependencies first:

python -m pip install -e ".[test]"

Then run the tests:

# Standard test run
pytest

# Detailed view (shows individual parametrized test cases and batch sizes)
pytest -v

# Extra verbose (prints standard output and shows exact numerical diffs if a test fails)
pytest -vv -s

---

Documentation

To generate and view the API documentation locally (requires the [docs] or [dev] dependencies):

# Build the HTML documentation
cd docs
make html       # On Linux / macOS
# make.bat html # On Windows

# Open the generated site in your browser
# On macOS:   open build/html/index.html
# On Linux:   xdg-open build/html/index.html
# On Windows: explorer.exe build\html\index.html

---

Acknowledgments

This project was developed by Evan Simanovskis under the supervision of Javane Rostampoor and Raviraj Adve at the University of Toronto.

The physical parameters, Rydberg transitions, and 2D parameter space provided in the heatmap example are adapted from their work on interference-resilient quantum receivers:

J. Rostampoor and R. Adve, "Interference resilient quantum receivers with Rydberg atoms," in Proc. IEEE GLOBECOM Workshops, 2025.

License

PQLS is licensed under the GPL-3.0 License. See the LICENSE file for more details.

Citing PQLS

If you use PQLS in your research, please click the "Cite this repository" button on the GitHub sidebar to generate the appropriate citation.