README

Quantum Metropolis–Hastings via Penalised Qubitized Walks:

This repository contains the simulation code accompanying the paper

“Quantum Metropolis–Hastings via Penalised Qubitized Walks: Circuit Implementation and Spectral Filtering.”

The code implements the qubitized quantum walk construction of Metropolis–Hastings Markov chains together with the spectral filtering procedure used to recover samples from the stationary distribution.

In particular, the code reproduces the numerical experiments for two model systems studied in the paper:

• a bidimensional double well energy landscape
• a one-dimensional Ising chain

---

Implemented Quantum Framework

This repository implements the full qubitization pipeline following the Claudon–Montanaro–et al. formalism, together with the modifications required to efficiently sample the target distribution. It includes:

• Construction of the Box isometry ($\boxtimes$)
• Projected Unitary Encodings (PUE / PUE*)
• Qubitized walk operator ( $\mathcal{W}$ )
• Penalized qubitized walk operator ($\mathcal{V}$)
• Quantum Phase Estimation (QPE)
• Dual to vertex decoding transformation
• Extraction of the final $X$-register distribution
• Tools for validating correctness and debugging intermediate states

---

Repository Structure

The repository contains two main implementations of the quantum Metropolis–Hastings pipeline:

• Double_well/ – the original implementation for the bidimensional double-well energy landscape.
• Ising/ – the more recent implementation for the one-dimensional Ising model, with a more modular oracle structure.

These two directories do not share exactly the same internal organization.

• In Double_well/, the quantum circuit components are grouped under qk/, in a model-specific implementation.
• In Ising/, the code is reorganized into general_qk/ and oracles/, separating reusable quantum-walk machinery from model-dependent oracle definitions.

This reflects the evolution of the codebase from an initial tailor-made implementation to a more modular and reusable structure.

---

Double_well/

This directory contains the original implementation of the algorithm used for the two-dimensional double-well energy landscape experiments.

The code in this folder was developed first and is tailored specifically to the double-well model. It contains the full end-to-end pipeline together with the corresponding tests and analysis scripts.

Contents

• main5.py
  Main simulation script for the double well workflow.

• analyze_results.py
  Loads saved outputs and produces diagnostic plots in results/.

• qk/
  Model-specific quantum circuit components for the double-well implementation.

• tests/
  Unit and consistency tests for the circuit components.

• results/
  Output plots and saved analysis products.

---

Ising/

This directory contains the implementation used for the one-dimensional Ising model.

Compared with Double_well/, this version adopts a more modular structure. In particular, the quantum-walk machinery is separated from the model-dependent oracle layer.

Contents

• main_Ising_semiclassical_chuncks.py
  Main simulation entry point for the Ising workflow.

• analyze_plot_energy_mass_grid.py
  Analysis and visualization script for energy/mass-grid outputs.

• analyze_plot_fidelity_beta_m.py
  Analysis script for fidelity as well as other observables as a function of inverse temperature and QPE precision.

• classical_spectral_gaps.py
  Classical spectral-gap computations and related diagnostics.

• general_qk/
  General quantum circuit machinery, written in a reusable form rather than tailored to a single model.

• oracles/
  Model-dependent oracle definitions used by the Ising implementation.

• tests/
  Tests for the Ising implementation.

• results/
  Output plots and saved analysis products.

---

Implementation Notes

The repository reflects two stages in the development of the project:

• Double_well/ contains the original, model-specific implementation used to validate the full pipeline.
• Ising/ reorganizes the code into a more modular structure, separating general quantum-circuit components from problem-specific oracle definitions.

This makes the Ising codebase closer to a reusable implementation of the framework, while the double-well code remains the original reference version for the first numerical experiments.

Running the Main Pipelines

The repository contains two independent implementations (Double_well and Ising), each with its own execution pipeline.

---

Double_well: Full QPE + Prop.13 run

From the repository root:

python3 Double_well/main5.py --m-phase 4

This generates simulation outputs saved as .npz files, for example:

qpe_prop13_sv_m4_shots20000_main5_penalised.npz

These files contain the saved statevector diagnostics and measurement statistics.

The results can then be analyzed using the scripts in Double_well/, such as:

python3 Double_well/analyze_results.py Double_well/qpe_prop13_sv_m4_shots20000_main5_penalised.npz

These analysis scripts generate visualizations and diagnostics in the Double_well/results/ directory.

---

Ising: semiclassical chunked simulation

The Ising implementation uses a more modular pipeline and supports checkpointing.

Example run:

python3 -m Ising.main_Ising_semiclassical_chuncks \
  --m-phase 8 --proposal L1 --beta 3.0 --shots 20000 \
  --penalty-impl flag --varphi 1.0472 --side left \
  --checkpoint ckpt_epoch_m8_beta3.0.npz

This command runs the Ising model simulation using the semiclassical chunking strategy and stores intermediate results in checkpoint files.

Analysis of the results can be performed using the analysis scripts located in the Ising/ directory.

Note The two implementations use different variants of Quantum Phase Estimation.

• The Double_well implementation uses the standard (fully coherent) QPE circuit, where all phase-estimation qubits are present simultaneously.
• The Ising implementation instead uses the semiclassical QPE approach, where the phase register is measured sequentially and classically fed forward.

This semiclassical strategy allows us to trade precision qubits for circuit depth, reducing the number of qubits required to achieve a given phase resolution at the cost of a longer circuit.

What the Algorithm Does

1. Construct the oracle operators, PUEs and the modified walk operator $\mathcal{V}$
2. Prepares a seed state via the isometry $\boxtimes$
3. Applies QPE on $\mathcal{V}$ with $m$ phase register ancillas
4. Postselects the phase=0 component
5. Apply the dual to vertex decoding transformation
6. Measure the first register to sample from the obtained distribution

If all components are correct and there are enough precision phase ancillas, the output distribution should converge to π.

---

Citation & Theory

This codebase follows and modifies the quantum Metropolis–Hastings / qubitization formalism of:

Claudon et al., Quantum Circuits for the Metropolis–Hastings Algorithm, 2025.

---

Author

Miguel Carrasco Arango Quantum Markov Chains & Qubitization Research