⚛️ quantum physics

qiskit-qudits: A Qiskit Extension for Simulating Qudit Circuits

This paper introduces **qiskit-qudits**, a Qiskit extension that simulates arbitrary d-level qudits by encoding them into qubits with identity-padding to handle non-power-of-two dimensions, offering both standard gate decompositions and exact dense unitary synthesis for dimensions up to 16, while validating its implementation through numerical verification of the quantum Fourier transform and gate decompositions.

Original authors: Francesco Pudda

Published 2026-08-25

📖 6 min read🧠 Deep dive

CC BY 4.0

Original authors: Francesco Pudda

Original paper licensed under CC BY 4.0 (http://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

In the world of quantum computing, the standard building block is the qubit, a tiny system that can exist in two states at once, often described as zero and one. But nature is not limited to just two options. Many physical systems, such as certain atoms or ions, naturally possess three, four, or even more distinct energy levels. Scientists call these multi-level systems qudits. While qubits are the foundation of current quantum computers, qudits offer a richer landscape for computation, potentially allowing for more efficient algorithms and better use of physical hardware. However, a significant hurdle has remained: the most popular software tools for designing quantum programs were built exclusively for two-level qubits. This meant that researchers wanting to experiment with qudits had to either write their own complex software from scratch or abandon the powerful tools that the broader community had developed.

Francesco Pudda has bridged this gap with a new software extension called qiskit-qudits. This tool allows scientists to design quantum circuits using multi-level qudits while still using the standard Qiskit software suite, which is widely used for building and testing quantum programs. The core achievement of this work is a clever translation method. Since the underlying hardware and the standard software both think in terms of two-level qubits, the new system encodes every multi-level qudit into a small group of qubits. For example, a three-level system is represented by two qubits, and a five-level system by three. This approach creates a slight inefficiency because the group of qubits can represent more states than the qudit actually uses, but the software is designed to ignore these extra, unused states. By treating these unused states as if they do nothing, the system ensures that the complex logic of the qudit works perfectly within the familiar language of qubits.

The researchers did not just build a theoretical idea; they created a fully functional library that integrates seamlessly with existing quantum workflows. The software defines a new set of instructions, or gates, that act on these multi-level systems. These gates can perform standard operations like shifting levels or creating complex superpositions. A key feature of the design is its ability to handle different sizes of qudits simultaneously. A single circuit can contain a three-level system, a four-level system, and a five-level system all working together, and the software manages the translation for each one automatically. When the number of levels is a power of two, the software breaks the operation down into a series of standard qubit steps that the computer's optimization tools can easily process. When the number of levels is not a power of two, the software uses a different method, calculating the exact mathematical transformation for the entire group of qubits at once. This ensures that the system works correctly for any size up to sixteen levels, a range that covers many practical physical systems.

To prove that their translation method was accurate, the team ran rigorous numerical tests. They compared the behavior of their software against the known mathematical rules for a specific type of quantum operation called the quantum Fourier transform, which is a fundamental tool in many quantum algorithms. They tested this across various sizes, including those that do not fit neatly into powers of two. The results showed that the software's output matched the theoretical expectations with extreme precision, with errors so small they were effectively zero for practical purposes. They also verified that every single type of gate they created behaved exactly as intended, whether it was a simple shift or a complex multi-level interaction. The tests confirmed that the software correctly handles the "unused" parts of the encoded space, ensuring that no information leaks out or gets corrupted during the process.

The paper also highlights the trade-offs involved in this approach. Because the system uses extra qubits to represent each qudit, it requires more memory to simulate on a classical computer than a native qudit simulator would. For very large systems, this overhead becomes significant, and the researchers note that for pure simulation of massive systems, a tool built specifically for qudits might still be more efficient. However, for the vast majority of current use cases, the benefit of using the standard Qiskit ecosystem outweighs this cost. The software allows researchers to draw circuits at the qudit level, run them through standard optimization passes, and prepare them for execution on real quantum hardware or simulators without needing to manually rewrite the code.

One of the most practical aspects of this work is how it handles measurement. When a quantum system is measured, the result must be converted back from the raw qubit data into the meaningful levels of the qudit. The new software includes a decoding layer that performs this translation automatically. It also includes a safety mechanism to detect "leakage," a situation where a system accidentally ends up in a state that does not correspond to any valid level of the qudit. In a perfect simulation, this should never happen, but on real hardware or when noise is introduced, it can occur. The software allows users to choose how to handle these rare events, either by discarding the bad data or by flagging it for review, making the simulation results more reliable and transparent.

The work represents a significant step forward in making quantum computing more accessible and versatile. By turning the theoretical concepts of multi-level quantum systems into a working, translatable software layer, it removes a major barrier for researchers. The team verified that their method works for dimensions ranging from two up to sixteen, covering the needs of many current experimental platforms. While the software relies on a specific encoding strategy that adds a layer of complexity, the author demonstrates that this complexity is managed effectively, allowing the standard tools of the quantum community to operate on a much broader range of physical systems. The result is a tool that lets scientists explore the full potential of multi-level quantum mechanics without having to abandon the powerful, established infrastructure they already rely on.

Technical Summary: QISKIT-QUDITS

Problem Statement

Qudits, which generalize two-level qubits to $d$ computational levels, offer potential advantages in quantum information processing. However, the Qiskit framework lacks native support for qudits, treating them as a known third-party extension gap. Existing toolchains face a dichotomy: native qudit simulators (e.g., Cirq, QuTiP) cannot leverage Qiskit's extensive compilation stack, transpiler passes, and hardware backends, while qubit-targeted tools often lack a programming surface for qudit-level operations. Users currently must manually implement encoding schemes, gate matrices, decompositions, and classical decoding, a process prone to errors regarding the treatment of unphysical state space and measurement decoding.

Methodology

The paper introduces qiskit-qudits, a Qiskit extension that simulates $d$ -level qudits by encoding each into $m = \lceil \log_2 d \rceil$ qubits. The software is built upon Qiskit's public Instruction, Gate, and ControlledGate classes, ensuring compatibility with the existing ecosystem.

Core Design Decisions

Encoding and Identity Padding:
Since $d$ is not necessarily a power of two, the encoded Hilbert space ( $D = 2^N$ ) is generally larger than the logical subspace ( $L = \prod d_i$ ). The library adopts the identity-padding convention: every gate acts as the identity on the orthogonal complement of the logical subspace. Formally, for a logical gate $G$ , the encoded unitary is $U = E G E^\dagger + (I - \Pi)$ , where $E$ is the encoding isometry and $\Pi$ is the projector onto the logical subspace. This choice prevents leakage during noiseless simulation and preserves permutation properties.
Gate Hierarchy and Decomposition:
The library defines three base classes: QuditGate (single qudit), QuditControlledGate (multi-control), and QuditMultiGate.
- Power-of-Two Path: When all operand dimensions are powers of two, gates decompose into fixed cascades of standard Qiskit qubit gates (e.g., mcx, cp, synth_qft_full). This allows the Qiskit transpiler to optimize the circuit.
- Dense-Synthesis Fallback: For non-power-of-two dimensions, gates fall back to exact dense unitary synthesis. The library generates the full $D \times D$ unitary matrix (via NumPy's __array__ protocol) and embeds it as a single opaque unitary instruction, which the UnitarySynthesis pass then decomposes.
Circuit Model and Measurement:
The QuditQuantumCircuit maintains two synchronized views: a qudit-level instruction log (.data) and an encoded qubit-level circuit (.circuit). Measurement is handled via QuditMeasure, which maps encoding qubits to classical bits (ClByte). A dedicated decoding layer translates backend counts back to qudit levels, explicitly detecting "leakage" (outcomes $\ge d$ ) which can be handled via configurable policies (keep, drop, raise).

Key Contributions

Implementation of a Transpilable Qudit Layer: The work converts the theoretical gate definitions from prior work [1] into a working, transpilable Qiskit extension. It supports dimensions $2 \le d \le 16$ and mixed-dimensional registers.
Exact Simulation for Non-Power-of-Two Dimensions: Unlike previous qubit-simulation approaches limited to $d=2^m$ , this library supports exact synthesis for arbitrary $d$ within the supported range using dense unitary fallbacks.
Verification of Theory and Implementation:
- Check A: Verified that the dense unitary matrices reproduce the Discrete Fourier Transform (DFT) on the logical subspace for both power-of-two and non-power-of-two dimensions, extending the verification of [1].
- Check B: Validated that the decomposed circuits (both cascade and dense paths) match the dense unitary definitions across 138 gate instances, with deviations within machine precision ( $\approx 10^{-15}$ ).
- Padding Invariant: Confirmed that the identity-padding invariant holds exactly, ensuring no mixing between valid and invalid subspaces.
Leakage Detection: Provides an explicit mechanism to detect and handle leakage events in simulations, distinguishing between ideal behavior and noise-induced errors.

Results

Numerical verification confirms the implementation's correctness:

QFT vs. DFT: The QFT implementation matches the theoretical DFT matrix to within $10^{-15}$ for dimensions $d \in \{2, 3, 4, 5, 8\}$ .
Gate Decomposition: All gates, including SUMX, SUMP, SWAP, and QFT, produce decompositions consistent with their dense unitary definitions.
Resource Analysis:
- Power-of-Two: Decompositions are efficient and transpiler-friendly. For example, a 3-qutrit QFT ( $d=3$ ) requires 1,783 CX gates, whereas a 3-ququart QFT ( $d=4$ ) requires only 56 CX gates.
- Non-Power-of-Two: The dense fallback incurs significant overhead. A 3-qutrit QFT ( $d=3$ ) synthesizes to 1,783 CX gates, while a 3-ququint ( $d=5$ ) QFT requires 119,383 CX gates. This highlights the cost of dense synthesis for larger non-power-of-two dimensions.
- Memory Constraints: The dense path is limited by memory; a gate on eight 16-level qudits ( $N=32$ ) would require $\approx 256$ EiB of memory, making the practical limit $N \approx 13\text{--}14$ on commodity hardware.

Significance and Limitations

The paper positions qiskit-qudits as a bridge allowing users to write qudit algorithms at the logical level while retaining full access to Qiskit's compilation stack, backends, and primitives. It explicitly addresses the "unphysical part" of the encoded space and measurement decoding, which are often error-prone in manual implementations.

Limitations and Trade-offs:

Dimension Cap: The library enforces $2 \le d \le 16$ and a maximum of 8 qudits per gate. These are nominal caps; the practical limit is determined by the memory required for dense unitary synthesis ( $N \lesssim 13\text{--}14$ ).
Leakage Semantics: The identity-padding convention freezes leaked amplitude rather than modeling physical leakage. It does not commute with tensoring, meaning circuit equivalence must be checked on the projected subspace ( $\Pi U \Pi$ ).
Optimization: The current implementation does not exploit "don't-care" rows/columns in the transpiler, and the dense fallback for non-power-of-two dimensions is computationally expensive compared to native qudit simulators or optimized reversible logic synthesis.

The work concludes that while the dense fallback enables exact simulation for non-power-of-two dimensions, future improvements should focus on dimension-agnostic reversible logic synthesis and exposing the unphysical subspace to the transpiler to reduce resource overhead.