Gibbs State Preparation

This repository contains an implementation of an Gibbs state preparation (GSP) hybrid quantum-classical algorithm for NISQ devices. A complete description of the algorithm can be found in the paper associated with this project: arxiv:2603.03801.

Table of Contents

• Introduction
• Structure
• Usage
• License

Introduction

From the abstract of the paper:

We implement a variational quantum algorithm for Gibbs state preparation of a transverse-field Ising model on IonQ quantum computers for systems involving 2-4 qubits. We train the variational parameters via classical simulation, and perform state tomography on the quantum devices to evaluate the fidelity of the prepared Gibbs state. We find that fidelity decreases (non-monotonically) as a function of the inverse temperature $\beta$ of the system. Fidelity also decreases as a function of the size of the system. We find that a Gibbs state prepared for a specified $\beta$ is a better representative of a Gibbs state prepared for a lower $\beta$; or in other words, thermal fluctuations in the quantum hardware increase the temperature of the prepared Gibbs state above what was intended.

Structure

The repository structure is as follows:

GibbsStatePreparation/
├── APIs/                               # A directory containing API keys (untracked)
│   ├── IBM.txt                           # The API key for IBM simulations and hardware jobs
│   ├── IonQ.txt                          # The API key for IonQ simulations
│   └── IonQ_Full.txt                     # The API key for IonQ hardware jobs
├── archive/                            # A directory containing archived content
│   ├── data/                             # Archived data files
│   ├── figures/                          # Archived images
│   └── src/                              # Archived scripts
├── circuits/                           # A directory containing circuit images for paper
├── data/                               # A directory containing all experimental data, including:
│   ├── circuits/                         # Circuit complexity across hardware devices
│   ├── densityMatrices/                  # Reconstructed density matrices from experiments
│   ├── expectations/                     # Expectation values of observables from experiments
│   ├── jobs/                             # Ids for all jobs submitted to hardware
│   ├── params/                           # Optimized parameters for each experiment
│   ├── plots/                            # Plots of reconstructed density matrices (untracked)
│   ├── results/                          # Raw measurement results from experiments
│   ├── simFidelities/                    # GSP cost history data from noiseless simulator
│   ├── simTraining/                      # GSP cost history data from quantum hardware
│   └── costHistory.csv                   # Cost information for all jobs submitted on hardware
├── figures/                            # A directory containing all figures in the paper
├── src/                                # A directory of script files, including:
│   ├── betaExplorationExperiment.ipynb   # Analysis of change in beta observed in experiments
│   ├── betaExplorationTraining.ipynb     # Training protocol for betaExplorationExperiment
│   ├── circuitComparison.ipynb           # Comparison of circuit complexity between IonQ and IBM
│   ├── costCalculation.ipynb             # Computation of total cost of experiments
│   ├── methods.py                        # Python source file containing all major functions
│   ├── parityCheck.ipynb                 # Parity check validation routine
│   ├── plotting.ipynb                    # Script to generate all item of figures/ directory
│   ├── runGSP.ipynb                      # Script to execute the GSP routine
│   ├── simulateGSP.ipynb                 # Script to simulate the GSP routine
│   └── trainGSP.ipynb                    # Script to train the GSP routine
├── .gitignore                          # Git ignore file (e.g., system files)
├── LICENSE                             # License file
└── README.md                           # Project description and instructions

Of these files, those in the source directory are the most important. In particular, trainGSP.ipynb is used to classically train optimal parameters for given combinations of $n$, $h$, $\beta$, and selected hardware. Following this, runGSP.ipynb is used to execute the experiments on the real hardware devices with the identified optimal parameters. Finally, plotting.ipynb visualizes the results. The relevant functions for all of these scripts are stored in methods.py.

Usage

To use this code, first ensure that Conda is installed on your machine. Next, clone the GitHub repository, and open a terminal in the main project directory. Run conda env create -f environment.yml to create a conda environment called gibbs-state, which can be used to run the files in the src\ folder.

To replicate the results presented in the paper, run the runGSP.ipynb file and then the plotting.ipynb file, in that order. To rerun the experiments with the saved optimal parameters, set EXECUTE_JOBS=True in rusGSP.ipynb before executing that file. To reconduct the experiment, begin with the trainGSP.ipynb file, then repeat the other two files (again with EXECUTE_JOBS=True in runGSP.ipynb).

License

This project is licensed under the MIT License — see the LICENSE file for details.