Metadata-Version: 2.5
Name: dbac
Version: 0.1.0
Summary: Double-Bracket Algorithmic Cooling: simulation, DME, HBAC baseline and plotting code.
Project-URL: Homepage, https://github.com/khanhuyengiang/dbac
Project-URL: Paper, https://arxiv.org/abs/2510.00302
Author-email: Khanh Uyen Giang <khanh.giang@tu-darmstadt.de>
Keywords: QITE,algorithmic cooling,density matrix exponentiation,double-bracket flow,quantum
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.9
Requires-Dist: numpy>=1.26
Requires-Dist: qibo>=0.3
Requires-Dist: qutip>=5.0
Requires-Dist: scipy>=1.11
Provides-Extra: docs
Requires-Dist: furo; extra == 'docs'
Requires-Dist: myst-nb>=1.0; extra == 'docs'
Requires-Dist: sphinx>=7.3; extra == 'docs'
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.1; extra == 'notebooks'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# Double-Bracket Algorithmic Cooling (dbac) package

Code accompanying the paper **[Double-Bracket Algorithmic Cooling](https://arxiv.org/abs/2510.00302)**
(M. Alghadeer, K. U. Giang, S. Cao, S. D. Fasciati, M. Piscitelli, N. Ng, P. J. Leek,
M. Gluza, M. Bakr).

## Background

Algorithmic cooling lowers the entropy of a qubit using only local operations and a
"colder" ancilla, and is the basis of established techniques like heat-bath algorithmic
cooling (HBAC). This paper introduces **double-bracket algorithmic cooling (DBAC)**, which
instead removes *coherence* from an already-pure qubit state, extending algorithmic
cooling from a thermodynamic (entropy) notion of cooling to a genuinely quantum one.

DBAC simulates quantum imaginary-time evolution (QITE) by recursively synthesizing
unitaries that implement Riemannian steepest-descent ("double-bracket") flows towards the
ground state, one small step at a time. Each step needs an extra copy of the current state
to act as a **quantum instruction**: that copy is consumed via **density matrix
exponentiation (DME)**, a protocol that uses repeated partial SWAPs to approximate the
unitary $e^{-it\rho}$ generated by a state $\rho$, without ever synthesizing $\rho$ as a
gate. Because the resulting circuit does not depend on the input state and needs no
measurements or feedback, cooling performance is governed entirely by *how many* quantum
instructions (copies of the state) are available -- a trade-off the paper relates to the
Nernst principle ("cooling to absolute zero costs infinite resources").

## Repository layout

```
src/dbac/          Physics and numerics: DME, DB-QITE/GCI recursion, HBAC, state utilities.
src/dbac/plotting/ All plotting code, factored out of the physics and shared across scripts/notebooks.
scripts/           The three DBAC scripts (computation + plotting), runnable standalone.
notebooks/ Narrated walkthroughs that call scripts/ and dbac.plotting and explain the physics.
figures/           All generated figures (PDF).
docs/              Sphinx documentation (`pip install -e ".[docs]" && make -C docs html`).
```

### `src/dbac/` -- physics and numerics (no plotting)

| File | Contents |
|---|---|
| `dme.py` | Density matrix exponentiation: exact (`dme_expm`), SWAP+numpy (`dme_channel`), analytical equivalent (`dme_channel_equivalent`), and qibo-circuit (`dme_qibo`) implementations. |
| `dbqite.py` | A single-qubit DB-QITE step built on top of Trotterized DME (`QITE_GCI_dme`) or on the exact unitary (`ideal_DME`). |
| `gci.py` | `GCI`: runs and tracks a DB-QITE/"group commutator iteration" recursion (energy, fidelity, states) for a fixed number of steps or by greedily picking the best step size at each round. |
| `hbac.py` | Heat-bath algorithmic cooling (reset + compress), the classical baseline DBAC is compared against. |
| `utils.py` | Shared helpers: fidelity with the ground state, depolarizing noise, thermal states, the $R_X(\theta)$ initial-state sweep used throughout. |

### `src/dbac/plotting/` -- all plotting

| File | Contents |
|---|---|
| `style.py` | Shared journal figure sizes and matplotlib `rcParams`. |
| `bloch.py` | Bloch-sphere rendering of single-qubit states and DB-QITE recursion trajectories. |
| `ptm.py` | Pauli-transfer-matrix heatmaps and a hue/size process-matrix plot. |
| `gci.py` | Energy/fidelity vs. evolution-duration plots for `GCI.execute_gci` output. |
| `cooling.py` | The cooling-performance figures: fidelity-fidelity plots, energy-vs-$\theta$ plots, grid layouts, and the ideal-DME summary figure. |
| `dme.py` | DME-channel-implementation benchmark plots. |

### `scripts/` -- one script per result, runnable from the command line

The three DBAC scripts do the computation (calling into `dbac`), calls `dbac.plotting` to
plot it, and saves the resulting figures to `figures/`:

```bash
pip install -e .
python scripts/sup_figure_S2.py      # DME channel implementation benchmark
python scripts/sup_figure_S4.py       # DBAC with ideal (M -> infinity) DME, sweep over k
python scripts/figure_4.py           # Main result: cooling vs. number of quantum instructions (Fig. 4)
python scripts/sup_figure_S5.py       # Bloch-sphere illustration of the DBAC recursion
```

### `notebooks/` -- narrated walkthroughs

| Notebook | Figure(s) | What it shows |
|---|---|---|
| [`dme_ptm_plot.ipynb`](notebooks/dme_ptm_plot.ipynb) | `ptm_*.pdf` | Pauli-transfer-matrix view of the ideal $ZZ$ interaction, the DME unitary, and the two hardware circuits (A, B). |
| [`hbac.ipynb`](notebooks/hbac.ipynb) | `hbac_3_qubits.pdf` | Heat-bath algorithmic cooling baseline on a 3-qubit chain, pure vs. depolarized input. |
| [`sup_figure_S4.ipynb`](notebooks/sup_figure_S4.ipynb) | `S4_QITE_ideal_DME_merged.pdf` (Fig. 7) | DBAC in the ideal-DME limit, sweeping the recursion depth $k$. |
| [`docs/index.ipynb`](docs/index.ipynb) | `F4_*.pdf` (Fig. 4) | **Main result** (also the front page of the docs): Trotterized-DME DBAC cooling performance vs. number of quantum instructions, compared to hardware experiment data. |

`notebooks/not_in_use/` holds earlier exploratory notebooks kept for reference;
they are not part of the maintained code path.

## Setup

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[notebooks]"
jupyter notebook notebooks/
```

Figures that use LaTeX-rendered labels require a local LaTeX installation (`matplotlib`'s
`text.usetex`); without one, either install `texlive` or disable it via
`dbac.plotting.use_paper_style(use_tex=False)`.

## Citation

If you use this code, please cite:

```bibtex
@article{alghadeer2025dbac,
  title   = {Double-Bracket Algorithmic Cooling},
  author  = {Alghadeer, Mohammed and Giang, Khanh Uyen and Cao, Shuxiang and
             Fasciati, Simone D. and Piscitelli, Michele and Ng, Nelly and
             Leek, Peter J. and Gluza, Marek and Bakr, Mustafa},
  journal = {arXiv preprint arXiv:2510.00302},
  year    = {2025}
}
```

Notebooks only save their plots when `SAVE_PLOTS = True` in [`notebooks/config.py`](notebooks/config.py) (off by default); PDFs then go to `figures/`.
