Metadata-Version: 2.4
Name: pqls
Version: 0.1.0
Summary: Parallel Quantum Liouvillian Solver: High-performance JAX-accelerated Lindblad solvers for quantum atomic systems.
Author-email: Evan Simanovskis <evan.simanovskis@mail.utoronto.ca>, Javane Rostampoor <javane.rostampoor@utoronto.ca>, Raviraj Adve <rsadve@ece.utoronto.ca>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Semyazi/pqls
Project-URL: Repository, https://github.com/Semyazi/pqls.git
Project-URL: Issues, https://github.com/Semyazi/pqls/issues
Keywords: quantum,physics,jax,lindblad,rydberg,amo,steady-state
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ARC-Alkali-Rydberg-Calculator>=3.10.2
Requires-Dist: jax>=0.4.30
Requires-Dist: scipy>=1.17.1
Requires-Dist: numpy>=2.4.6
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: qutip>=5.0.0; extra == "test"
Requires-Dist: matplotlib>=3.8.0; extra == "test"
Requires-Dist: rydiqule>=2.1.3; extra == "test"
Requires-Dist: qutip-jax>=0.1.1; extra == "test"
Provides-Extra: dev
Requires-Dist: pqls[docs,test]; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

# 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)](https://arc-alkali-rydberg-calculator.readthedocs.io/), 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](#installation)
- [Quickstart](#quickstart)
- [Examples](#examples)
- [Testing & Benchmarking](#testing--benchmarking)
- [Documentation](#documentation)
- [Acknowledgments](#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)
Clone the repository, create a virtual environment, and install the base package:

```bash
# Clone the repository
git clone https://github.com/Semyazi/pqls.git
cd pqls

# 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 the package
pip install --upgrade pip
pip install .
```

### 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`):

```bash
# 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.

```python
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()
```

![Quickstart](assets/01a_quickstart_ats.png)

---

## 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:
```bash
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, ensure you have installed the `[dev]` or `[test]` dependencies, then run:

```bash
# 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):

```bash
# 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.
