Metadata-Version: 2.4
Name: pqls
Version: 0.1.2
Summary: Parallel Quantum Liouvillian Solver: High-performance JAX-accelerated Lindblad solvers for quantum atomic systems.
Author: Evan Simanovskis, Javane Rostampoor, Raviraj Adve
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)
Install PQLS directly from PyPI:

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

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

The Quickstart example also requires Matplotlib:

```bash
pip install matplotlib
```

```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 from a cloned PQLS repository, install the `[test]` or `[dev]` dependencies first:

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

Then run the tests:

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