---
title: Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz
canonical_url: "https://www.modelscope.cn/datasets/nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz"
md_url: "https://www.modelscope.cn/datasets/nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz.md"
repository: nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz
last_updated: 2026-07-14
license: mit
downloads: 54
stars: 0
---

# Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz

> Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz - nbalexis 在 ModelScope 开源的数据集。This repository contains the simulations and manuscript for a comparison of four 16-qubit parameterized quantum circuits. See readme.md for detail.

nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz 是 ModelScope 魔搭社区上的数据集，采用 mit 许可。

- **Repository**: nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz
- **License**: mit
- **Downloads**: 54
- **Stars**: 0
- **Last updated**: 2026-07-14

Source: https://www.modelscope.cn/datasets/nbalexis/Expressibility_and_Trainability_Data_for_2D_Pairwise_Ansatz

---

# Ansatz2D: expressibility and trainability of 2D pairwise quantum ansatze

This repository contains the simulation data and source code for a comparison of six
16-qubit parameterized quantum circuits built from a common $R_y$–$R_z$ rotation
layer plus CNOT entangling blocks (parameters: $2N(L+1)$, $N=16$, $L$ entangling
blocks):

- **1D pairwise** (`1D Dense` in the code): even and odd nearest-neighbor CNOT sweeps on a ring.
- **Circular**: an ordered nearest-neighbor CNOT chain with periodic closure.
- **SCA**: the Circular chain with its starting position shifted between layers.
- **2D pairwise** (`2D Dense Static` in the code): four directional nearest-neighbor CNOT sweeps on a $4\times4$ grid.
- **2D Max-Matching**: four analytically selected perfect matchings of the $4\times4$ grid, eight CNOTs per sublayer.
- **2D Max-Matching v2 (mixed orientation)**: the same matchings with reversed CNOT orientation on revisited edges, preventing CNOT cancellation under compilation.

The study compares the circuits using:

1. Structural resources: compiled CNOT count and two-qubit depth per block.
2. KL divergence from the Haar-random fidelity distribution (10,000 pairs, 50 quantile bins).
3. The state $t=2$ frame potential (2,000 states, delete-one jackknife).
4. The variance of the global-parity-cost gradient for one fixed, homologous parameter, plus a broader gradient survey (3 observables x 3 parameter locations).
5. An ideal four-class variational quantum classifier (VQC) comparison at $L=2$ with a global even/odd-parity readout (10 paired initializations x 5000 SPSA iterations), with a noisy evaluation at the fixed ideal optima retained for provenance.

The manuscript source and compiled figures are not included here; only the
numerical data and the scripts that produced it are retained.

## Repository layout

```text
Ansatz2D/
├── ansatz.py                     Six circuit builders and entangling schedules
├── simulate.py                   KL / frame-potential / gradient-variance estimators
├── workstation_study.py          Formal baseline study: resources, expressibility,
│                                 trainability, gradient survey (five-ansatz baseline)
├── workstation_l2_vqc_vqe.py     Mixed-orientation v2 study: expressibility,
│                                 trainability, and the L=2 global-parity VQC
├── tests.py                      Structural and estimator regression tests
├── plot_results.py               Regenerates all six manuscript figures from the data
├── run_workstation.bat           Windows launcher for workstation_study.py
├── run_workstation_l2_vqc_vqe.bat Windows launcher for workstation_l2_vqc_vqe.py
├── build_data_manifest.py        Regenerates data_manifest.json checksums
├── requirements.txt              Pinned Python package versions
├── data_manifest.json            Sizes, statistics, and SHA-256 checksums of raw arrays
└── raw_data/
    ├── FORMAL_RESULTS.md         Provenance notes for the formal result sets
    ├── formal_workstation_results/        Baseline five-ansatz study (2026-07-23.2)
    └── final_v2_l2_workstation_results/   Mixed v2 + L=2 VQC study (2026-08-05)
```

## Environment setup

The committed results were produced with Python 3.13 and the versions in
`requirements.txt`:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Verify the installation before a long simulation:

```powershell
python tests.py
```

## Reproduction commands

Both study scripts checkpoint after every unit of work, so interrupted runs resume
without discarding completed results. On Windows, the batch launchers create a
dedicated virtual environment with the pinned dependencies and then run the study:

```powershell
.\run_workstation.bat            REM baseline five-ansatz formal study
.\run_workstation_l2_vqc_vqe.bat REM mixed-orientation v2 + L=2 VQC study
```

Or invoke the scripts directly (both support `--workers`, `--quick` smoke tests,
and `--force` recomputation):

```powershell
python workstation_study.py --workers 6
python workstation_l2_vqc_vqe.py --workers 4
```

The full formal studies are computationally expensive. Use `--quick` for a small
end-to-end validation run first.

### Regenerating the manuscript figures

All six result figures of the manuscript are regenerated from the committed data
alone (numpy + matplotlib only, no Qiskit needed):

```powershell
python plot_results.py            REM writes the six PDFs to figures/
python plot_results.py --output-dir figures --data-root raw_data
```

This produces `kl_divergence.pdf`, `frame_potential.pdf`,
`gradient_variance.pdf`, `gradient_survey.pdf`, `vqc_ideal_training.pdf`, and
`vqc_dataset.pdf`, and prints the plotted values for comparison against the
manuscript tables.

## Numerical data

### `raw_data/formal_workstation_results/`

Baseline formal study for 1D pairwise, Circular, SCA, 2D pairwise, and the
original 2D Max-Matching ansatz. Contents:

- `protocol.json` — fixed sampling/estimator protocol (seeds, sample counts).
- `summary.json` — merged results: calibration, expressibility, gradients,
  resources, structural selection, ideal/noisy VQE provenance.
- `tables/` — manuscript tables (`expressibility.csv`, `gradient_survey.csv`,
  `resources.csv`, `kl_calibration.csv`, `manuscript_values.tex`, ...).
- `raw/` — per-metric raw arrays (`expressibility/`, `gradients/`, `noise/`,
  `vqe/`, `kl_calibration.npy`).
- `checkpoints/` — resumable per-task checkpoints.
- `figures/`, `run.log`.

### `raw_data/final_v2_l2_workstation_results/formal/`

Final mixed-orientation Max-Matching v2 study
(`2026-08-05.final-mixed-v2-exptrain-l2-vqc-vqe-v1`). Contents:

- `protocol.json`, `summary.json` — v2 expressibility/trainability plus the
  complete ideal L=2 global-parity VQC comparison across all six ansatze.
- `vqc_noise_summary.json` — noisy VQC evaluation at the fixed ideal optima.
- `tables/` — VQC accuracy and resource tables (CSV) and manuscript values.
- `checkpoints/` — paired-initialization VQC checkpoints, compiled-resource
  records, and the exact `make_blobs` task dataset (seed 42).
- `raw/`, `figures/`, `run.log`, `conclusions.txt`.

Earlier ideal L=2 Z2 lattice-gauge VQE results are retained in the same
directory for provenance; the VQE comparison is not part of the current
manuscript.

### Data formats

All numerical content is stored as JSON, CSV, NumPy `.npy`, or NumPy `.npz`
files. Ansatz naming differs slightly by location: the baseline study uses
display names (`1D pairwise`, `Circular`, `SCA`, `2D pairwise`,
`2D Max-Matching`), the v2 study adds the key
`2D Max-Matching v2 (mixed orientation)`, and raw-array filenames use
snake_case prefixes (`1d_dense`, `2d_dense_static`, `2d_max-matching`, ...).

`summary.json` (both studies) — merged machine-readable results:

- Baseline: `calibration` (finite-sample Haar KL floor: `asymptotic_bias`,
  `empirical_mean`, `interval_95`, `standard_deviation`), `expressibility`
  (per ansatz/depth KL and frame potential with standard errors),
  `gradients` (fixed-parameter variance plus the 3x3 survey),
  `resources` (logical/compiled CNOT and two-qubit depth),
  `structural_selection` (36 perfect matchings -> 1536 admissible -> 4 optimal,
  lexicographic min-reachability ranking), `vqe_ideal`/`vqe_noise` (provenance).
- v2: `expressibility` (six entries, KL + frame potential),
  `trainability` (54 entries: 6 depths x 3 observables x 3 parameter
  locations), `vqc.summary` (six ansatze, mean +/- standard error over the 10
  paired initializations), `structure` (matching/orientation definitions),
  `vqe` (gauge-VQE provenance).

`tables/*.csv` — manuscript tables in long format, one row per
ansatz/depth(/observable/parameter):

- `expressibility.csv`: `ansatz, depth, kl(_divergence), kl_standard_error,
  frame_potential, frame_potential_standard_error, haar_frame_potential`.
- `gradient_survey.csv` / `trainability_gradient_variance.csv`:
  `ansatz, depth, observable, parameter, parameter_index, variance
  (gradient_variance), standard_error_200, standard_error_1000,
  mean_gradient`. The manuscript error bars use `standard_error_200` for the
  fixed-parameter table and `standard_error_1000` for the survey.
- `resources.csv`: logical and compiled CNOT count / two-qubit depth.
- `vqc_summary.csv`: per-ansatz mean +/- standard error of train/test loss and
  accuracy (ideal parity readout, local diagnostic readout, and noisy
  evaluation). `vqc_ideal_initializations.csv` /
  `vqc_noisy_initializations.csv`: the same quantities per initialization,
  plus compiled resources and a path to the raw `.npz`.
- `kl_calibration.csv`: the 5,000 Haar-reference KL replicates.
- `manuscript_values.tex`: the exact numbers inserted into the manuscript.

Raw arrays (`raw/`):

- `raw/expressibility/<ansatz>__L<L>__fidelities.npy` — 10,000 sampled
  fidelities per ansatz/depth (KL input); `<...>__fp_row_sums.npy` — 2,000
  row sums of the off-diagonal overlap block (jackknife-ready frame-potential
  input). `raw/kl_calibration.npy` — 5,000 Haar-reference KL estimates.
  The four baseline ansatze carried over from the first-generation pipeline
  (`1d_dense`, `circular`, `sca`, `2d_dense_static`) were converted from the
  legacy `results.json` fidelity lists and overlap arrays into this same
  format; each converted array reproduces the committed summary value and
  standard error exactly.
- `raw/gradients/<ansatz>__L<L>.npy` — 10,000 parameter-shift gradients of
  the fixed homologous parameter per ansatz/depth.
- `raw/vqc_parity_ideal/<ansatz>__I<0..9>.npz` — per-initialization VQC run:
  `trace` (101 x 5: iteration, train loss, train accuracy, test loss, test
  accuracy), `optimized_parameters`, and final test probabilities.
- `raw/vqc_parity_noise/<ansatz>__I<k>.npz` — noisy evaluation at the fixed
  ideal optima, including the compiled-circuit resource records.
- `raw/datasets/task_seed_42.npz` — the exact four-class task:
  `raw_features` (256 x 32), `labels`, `train_indices` / `test_indices`
  (128 each), the standardized `train_angles` / `test_angles`, and the
  z-score `scaler_mean` / `scaler_scale`.
- `raw/vqe_ideal/`, `raw/noise/`, `raw/vqe/` — VQE and noise provenance
  arrays.

`checkpoints/` — one small JSON per completed task; deleting a checkpoint
forces recomputation of only that task on the next run.

### Checksums and provenance

`raw_data/FORMAL_RESULTS.md` records the study IDs and provenance of each formal
result set. Regenerate the array-level checksum inventory after any data change:

```powershell
python build_data_manifest.py
```

`data_manifest.json` records the path, per-array key, byte size, SHA-256
checksum, dtype, shape, mean, and variance of every `.npy` array and every
array inside each `.npz` archive in the two formal result sets (staging
`*.partial.npz` files excluded).

## Testing

```powershell
python tests.py
```

The tests verify 2D grid indexing, checkerboard parity, boundary neighbors,
CNOT/parameter counts for all six ansatze, agreement between declared and actual
Qiskit parameter counts, the fixed-parameter gradient-variance estimator, the
noisy energy estimators, and best-checkpoint selection.

## Notes

- The first-generation pipeline used for the initial release of this dataset
  (sequential KL/FP runner, parallel GV runner, `results.json`, and the legacy
  per-ansatz `.npy` archives) is superseded by the formal workstation studies
  above and was removed from the working tree; it remains recoverable from the
  git history of this repository.
- Superseded exploration studies (earlier local-readout VQC, TFIM VQE,
  Z2 gauge VQE, and first-pass Max-Matching v2 direction experiments) are not
  included; the retained noisy VQC and gauge-VQE records exist for provenance
  only.