Symmetry-Oriented Testing Framework (SOT Framework)

• DOI: 10.5281/zenodo.21405151
• Latest release: https://github.com/FujitsuResearch/SOT-Framework

Overview

This repository contains the official implementation of the Symmetry-Oriented Testing Framework for Variational Quantum Algorithms (SOT Framework).

It includes both the reusable Python library for symmetry-oriented diagnostics in variational quantum algorithms and the experimental notebooks used to produce the results reported in the companion paper.

Citation

This repository accompanies the following paper, accepted at IEEE Quantum Week 2026 (QCE26), Quantum Software Systems (QSYS) track:

Masaomi Yamaguchi and Fuyuki Ishikawa, "Symmetry-Oriented Testing Framework for Variational Quantum Algorithms." 2026 IEEE International Conference on Quantum Computing and Engineering (QCE), Toronto, ON, Canada, 2026.

Repository Structure

The repository is organized into four main parts:

• src/sot/: The core Python library implementing the SOT Framework.
  • workflow.py: End-to-end VQA workflow execution and step tracking.
  • problem.py: Problem specification helpers and exact-diagonalization utilities.
  • oracles.py: Health-check and acceptance-check oracle logic.
  • estimator.py and estimators/: Estimator backends used by the workflow.
  • experiment_runner.py: Helpers for multi-start experiment orchestration.
  • trace_enrichment.py: Post-processing helpers for HC/AC trace analysis.
• Experiment/: The experimental suite used to evaluate the framework and generate the results reported in the paper.
  • fault_detection/noiseless_HE/: RQ1 notebooks for noiseless fault detection on H2 hardware-efficient ansatze.
  • correlation_analysis/: RQ2 perturbation-scan notebooks for H2, LiH, BeH2, H2O, and Z2 lattice gauge theory.
  • screening_analysis/: RQ3 notebooks for threshold-based screening.
  • fault_detection/insert_noise/: RQ4 replay notebooks for inserted-noise analysis.
• examples/: Lightweight notebooks for understanding the framework without running the full paper pipeline.
• tests/: Automated tests for the library and experiment-support code.

Installation

1. Install Python 3.12. https://www.python.org/downloads/

2. Clone this repository.

3. Install the runtime dependencies. Using a virtual environment is recommended.

   python -m venv .venv      # recommended
   source .venv/bin/activate # recommended
   pip install --upgrade pip # recommended
   pip install -r requirements.txt
   pip install dist/sot-*.whl

Development

Development tooling is managed with Poetry. If you want to run tests, edit the project, or build distribution artifacts locally, Poetry is required.

Poetry: https://python-poetry.org/

pip install poetry
poetry install
poetry build

Usage

As a Library

You can use the sot library to run symmetry-oriented diagnostics in your own VQA workflows.

Please see:

• examples/

Reproducing Experiments

The experiments from the paper can be reproduced from the notebook tree under Experiment/.

Please see:

• Experiment/README.md
• Experiment/fault_detection/noiseless_HE/README.md
• Experiment/fault_detection/insert_noise/README.md
• Experiment/correlation_analysis/README.md
• Experiment/screening_analysis/README.md

Most experiment notebooks write a JSON artifact next to the notebook. Those artifacts are the stable inputs consumed by downstream reporting and figure generation.

Running Tests

Run the test suite from the Poetry-managed development environment:

poetry run pytest