💻 computer science

QUAMET: Structural and Semantic Metric Analysis for Quantum Code Smell Detection

This paper introduces QUAMET, a novel approach that combines structural and semantic analysis to establish software metrics and detect six types of code smells in quantum programs, validated on a refined dataset of 4,102 real-world Qiskit projects.

Original authors: Ruchika Malhotra, Bhawna Jain, Marouane Kessentini

Published 2026-07-06

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Ruchika Malhotra, Bhawna Jain, Marouane Kessentini

Original paper licensed under CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

Imagine you are building a house, but instead of wood and bricks, you are building with quantum bits (qubits). These aren't normal bits that are just "on" or "off"; they are like spinning coins that can be heads, tails, or both at the same time. Because this technology is so new and complex, the "blueprints" (code) people write for these quantum computers often have hidden flaws.

In the software world, we call these hidden flaws "code smells." Think of a code smell like a bad odor in a kitchen. It doesn't mean the food is poisoned (the program might still run), but it tells you something is wrong, messy, or inefficient that could lead to a disaster later.

This paper, titled QUAMET, is like a new, high-tech smell-o-vision designed specifically for quantum computer code. Here is how it works, broken down simply:

1. The Problem: Quantum Code is Messy

Just like a messy room makes it hard to find your keys, messy quantum code makes it hard for the computer to do its job efficiently. Because quantum programming is so new, developers often make mistakes that don't happen in regular computers. The researchers wanted to find a way to automatically sniff out these bad smells before they cause big problems.

2. The Solution: Two Types of "Noses"

The researchers built a system called QUAMET that uses two different ways to smell the code:

The Structural Nose (Looking at the Shape): This looks at the physical layout of the code. It counts things like:
- How many "gates" (logic switches) are there?
- How deep is the circuit (how many steps does the data have to travel)?
- How many qubits are being used?
- Analogy: Imagine looking at a house and counting how many rooms it has, how long the hallways are, and how many doors there are. If the house is a maze with 500 doors, it's probably poorly designed.
The Semantic Nose (Understanding the Meaning): This looks at what the code is actually trying to do. It analyzes the logic and the flow.
- Analogy: Imagine walking into that house and realizing the kitchen is in the basement, the bedroom is on the roof, and the front door opens into the backyard. The structure might look okay on a blueprint, but the meaning of the layout is broken.

The paper claims that using both noses together is much better than using just one.

3. The Six "Bad Smells" They Found

The researchers identified six specific types of "stink" that are unique to quantum code. They named them based on what they smell like:

Long Circuit (LC): The code is too long and winding. It's like a road trip that takes 100 miles to go 1 mile. This makes the computer slow and prone to errors.
Excessive Measurement (EM): The code checks the results too many times. In quantum physics, "checking" (measuring) collapses the magic state of the qubit. Doing it too often ruins the calculation. It's like checking if your cake is done every 5 seconds; you'll never let it bake properly.
Unconnected Circuit (UC): The parts of the code aren't talking to each other. Quantum computers need their parts to be "entangled" (linked) to work. If they aren't linked, the computer is just doing simple math, not "quantum" math.
Inconsistent Bits (IB): The number of quantum bits doesn't match the number of classical bits needed to read the results. It's like having 5 keys but only 3 keyholes. It creates confusion and errors.
Low Quantum Volume (LQV): The code is too weak or simple to do complex tasks. It's like trying to run a supercomputer game on a calculator.
Insufficient Depth per Qubit (IDQ): The individual parts of the code aren't being used enough. It's like having a Ferrari engine but only driving it at 5 mph. You aren't getting the power you paid for.

4. The Experiment: Training a Detective

To test their idea, the researchers took a huge pile of real-world quantum code (about 4,100 projects) and taught a computer to be a detective.

The Dataset: They cleaned up a massive collection of code snippets (like organizing a messy library).
The Training: They fed this data into 14 different types of "detectives" (Machine Learning algorithms).
The Result: They found that one detective, called Random Forest, was the best at sniffing out the bad smells. It was almost perfect at identifying the problems.

5. The Big Takeaway

The most important finding of the paper is that you need both the Structural and Semantic noses to get it right.

If you only look at the shape (Structure), you miss the logic errors.
If you only look at the meaning (Semantics), you miss the physical inefficiencies.
When you combine them, the accuracy jumps up significantly. It's like having a detective who can see the blueprint and understand the owner's intent.

Summary

The paper presents a new tool (QUAMET) that helps developers clean up their quantum code. By measuring specific structural and semantic features, it can automatically flag six common types of bad code. The study proves that combining these two types of analysis makes the detection much more accurate than looking at just one type. This helps ensure that the quantum computers of the future run smoothly and efficiently.

Technical Summary: QUAMET – Structural and Semantic Metric Analysis for Quantum Code Smell Detection

Problem Statement

The rapid advancement of Quantum Computing (QC) has led to the proliferation of quantum programs (QPs) developed using frameworks like Qiskit, Cirq, and Q#. However, this growth has introduced significant challenges in software maintenance. Similar to classical software, quantum programs are susceptible to "code smells"—suboptimal design patterns that hinder maintainability, performance, and reliability. While code smell detection is well-established in classical software engineering, it remains underexplored in the quantum domain. Existing research has largely focused on bug detection or limited metric analysis, lacking a comprehensive approach that combines structural and semantic features to identify quantum-specific code smells. Furthermore, there is a scarcity of large-scale, labeled datasets of real-world quantum projects necessary to train robust detection models.

Methodology

The paper proposes QUAMET, a novel framework designed to detect quantum code smells through a dual-analysis approach: structural and semantic metric analysis. The methodology proceeds through the following stages:

1. Dataset Curation and Pre-processing

The study utilized the LintQ dataset, a publicly available repository containing raw code snippets from 7,568 real-world quantum projects.

Filtering: The dataset was refined by selecting only Python and Jupyter files, converting Jupyter notebooks to Python scripts, and executing circuits using the Qiskit library to ensure validity.
Cleaning: Files lacking quantum circuits or containing only import statements were removed. The dataset was updated to align with the latest library versions.
Final Corpus: The pre-processing resulted in a refined dataset of 4,102 real-world quantum projects.

2. Metric Extraction

QUAMET extracts two categories of metrics to characterize the quantum code:

Structural Metrics (9 metrics): These quantify the physical and logical architecture of the quantum circuits. Key metrics include:
- Depth: Maximum path length from input to output.
- Width: Total number of qubits and classical bits.
- Gate Count: Total number of gate operations.
- Entangling Gates: Count of gates creating quantum entanglement.
- Average Gate Depth per Qubit: Workload distribution across qubits.
Semantic Metrics (3 metrics): These analyze the meaning and functional behavior of the code using Abstract Syntax Trees (AST) and circuit analysis:
- Code Comprehension: Ratio of AST nodes to lines of code, indicating complexity and readability.
- Circuit Connectivity: Number of non-overlapping connected components.
- Quantum Volume: A performance metric combining qubit count, connectivity, and error rates ( $2^{\min(\text{gates}, \text{depth})}$ ).

3. Definition of Quantum Code Smells

Based on the metrics, the study defines and validates six specific quantum code smells:

Long Circuit (LC): Circuits with excessive depth or width relative to their ratio, leading to high error rates and decoherence.
Excessive Measurement (EM): Imbalanced usage of measurement operations relative to total bits, causing resource inefficiency.
Unconnected Circuit (UC): Circuits with low connectivity and zero entangling gates, failing to exploit quantum parallelism.
Inconsistent Bits (IB): A discrepancy where the number of qubits does not match the number of classical bits, risking data overwriting.
Low Quantum Volume (LQV): Circuits with low quantum volume and poor code comprehension, indicating limited computational power.
Insufficient Depth per Qubit (IDQ): Circuits where the average gate depth per qubit is below a threshold, indicating underutilization of quantum components.

4. Machine Learning Classification

The labeled dataset (smelly vs. non-smelly for each of the six categories) was used to train and evaluate 14 Machine Learning classifiers, including Decision Trees, Random Forest (RF), Support Vector Machines (SVM), Neural Networks (MLP), and Naive Bayes variants.

Validation: The models were evaluated using Accuracy, Precision, Recall, and F1-score.
Statistical Testing: The Wilcoxon signed-rank test was employed to determine if performance differences between classifiers were statistically significant, with Bonferroni correction applied for multiple comparisons.

Key Contributions

Large-Scale Labeled Dataset: The creation of a curated dataset of 4,102 real-world quantum projects, labeled with six distinct types of quantum code smells, addressing the scarcity of training data in this domain.
Hybrid Metric Analysis: A pioneering approach that integrates both structural (circuit architecture) and semantic (code meaning/AST) metrics to detect code smells, moving beyond traditional size-based metrics.
Definition of Quantum-Specific Smells: The identification and expert validation of six code smells unique to the quantum programming paradigm, providing a taxonomy for future research.
Empirical Evaluation: A comprehensive benchmark of 14 ML classifiers, identifying the most effective models for quantum code smell detection.

Results

Feature Integration: Experiments demonstrated that models trained on both structural and semantic features significantly outperformed those trained on either feature set alone. For instance, combining features improved the F1-score for Long Circuit detection by approximately 26.78% compared to using only semantic features.
Classifier Performance: The Random Forest (RF) classifier consistently achieved the best performance across all six code smells, with near-perfect scores in accuracy, precision, recall, and F1-score. Multilayer Perceptron (MLP) and K-Nearest Neighbor (KNN) also showed strong performance. Conversely, models like Stochastic Gradient Descent (SGD) and various SVM kernels (Poly, Sigmoid, RBF) performed poorly, particularly in recall.
Statistical Significance: The Wilcoxon test confirmed that RF and MLP were statistically superior to most other classifiers. RF emerged as the most robust model with 0 losses in pairwise comparisons, while MLP achieved the highest win percentage (97.44%).
Comparison with State-of-the-Art: The proposed methodology outperformed existing metric-based tools (e.g., QSmell) and recent LLM-based approaches (e.g., LintQ-LLM) in detecting specific code smells, achieving accuracy increases of up to 15% for validated smells.

Significance and Claims

The paper claims that the QUAMET framework represents a significant advancement in quantum software engineering by bridging the gap between code smell detection and quantum-specific constraints. Its primary significance lies in:

Enhanced Detection Accuracy: Demonstrating that a holistic view combining structural and semantic analysis is essential for accurately identifying quantum code smells, which single-dimension approaches miss.
Practical Utility: Providing a validated, data-driven methodology that can be used to build automated tools for improving the maintainability and performance of quantum software.
Expert Validation: The defined smells and metrics were rigorously reviewed by industry experts and academic researchers, ensuring their relevance to real-world quantum development challenges.

The authors conclude that while challenges remain regarding the evolving nature of quantum libraries and the generalizability of the models, the proposed structural and semantic analysis offers a scalable and effective foundation for future quantum code quality assurance tools.