[FEATURE] Qubit Register Consolidation

[TheGupta2012]

Feature Description

• Introduce a device_qubits parameter to PyQASM’s unroll method that consolidates all declared qubit and qreg registers in a QASM program into a single, uniquely named register: qubit[N] __PYQASM_QUBITS__, where N is the total number of qubits specified by the user.
• When device_qubits is specified, __PYQASM_QUBITS__ becomes a special reserved keyword and cannot be used elsewhere in the user’s code. All gate and measurement operations referencing original registers are remapped to this consolidated register. If the total number of required qubits exceeds the specified device size, an error is raised.

The order in which qubit registers appear in the original QASM program defines their mapping in the consolidated register: the first declared register occupies the lowest indices, followed by the next, and so on. This ensures deterministic and predictable assignment of qubit IDs within __PYQASM_QUBITS__.

Motivation

• Hardware Compatibility: Many quantum devices require flat, contiguous qubit addressing.
• Simplified Compilation: Automates the tedious and error-prone process of remapping multiple logical registers to a single hardware register.
• Error Prevention: Validates that the user’s program does not exceed the available device qubits, preventing invalid execution.
• Consistent Register Management: Maintaining a single, reserved register (__PYQASM_QUBITS__) throughout the program simplifies code generation, post-processing, and downstream analysis.
• Facilitates Routing: Consolidating all qubits into one register makes routing and mapping phases more straightforward.

Implementation

• Input Handling:
  • Add device_qubits: int as an optional parameter to unroll().
  • Compute the total number of qubits required by summing all register and qubit declarations.
• Validation:
  • Raise an error if the total required qubits exceed device_qubits.
  • Raise an error if the original QASM program declares a register named __PYQASM_QUBITS__ when device_qubits is specified.
• Consolidation:
  • Remove and replace all qubit and qreg declarations with qubit[device_qubits] __PYQASM_QUBITS__;.
  • Rewrite all gate and measurement operands to reference __PYQASM_QUBITS__[i], where i is the offset determined by the order of appearance of each register in the original code.
• Edge Cases:
  • Ensure no overlap in qubit indexing and preserve original program semantics.

---

Example Workflow

from pyqasm import loads

qasm_code = """
OPENQASM 3.0;
qubit[4] data;
qubit[2] ancilla;
cx data[0], ancilla[1];
"""

module = loads(qasm_code)

# User specifies a 6-qubit device
module.unroll(device_qubits = 6)

print(module)

# Output:
# OPENQASM 3.0;
# qubit[6] __PYQASM_QUBITS__;
# cx __PYQASM_QUBITS__[0], __PYQASM_QUBITS__[5];

In this example, the data register (4 qubits) appears first and is mapped to __PYQASM_QUBITS__[0-3], while the ancilla register (2 qubits) appears next and is mapped to __PYQASM_QUBITS__[4-5].

NOTE: When device_qubits is specified, __PYQASM_QUBITS__ is a reserved keyword. Any attempt to declare or use __PYQASM_QUBITS__ as a register name in the original QASM program will result in an error. The mapping of original registers to the consolidated register strictly follows their order of appearance in the source code.