Fixes #13145

Summary

This PR introduces and integrates several key modules for a Rust-based quantum computing framework, laying the foundation for exporting circuits in QASM 3.0 format. The modules added are:
1. printer.rs:
• Implements functionality for formatted output generation of AST or other hierarchical structures.
2. symbols.rs:
• Manages a symbol table used for mapping variable names to their corresponding entities.
• Provides helper methods for creating, binding, and looking up symbols with robust error handling.
• Note: This file is directly copied from Qiskit’s OpenQASM 3 parser, as this symbol table is used when loading QASM 3.0 and converting it to quantum circuits. However, this architecture might be overly complex for the current task of QASM 3.0 exporting, and its necessity should be revisited in future iterations.
3. ast.rs:
• Defines the AST structure for representing quantum programs.
• Contains data structures such as nodes, expressions, and declarations that model the core components of quantum circuit descriptions.
4. exporter.rs:
• Implements a builder for generating QASM 3.0 programs.
• Integrates with Python-based tools (via pyo3) to extract circuit data and parameters.

Details and comments

Current Limitations

The current implementation has limited QASM 3.0 output functionality and relies on partial Python integration. The following features are not yet supported:
• Control Flow Constructs: While QASM 3.0 supports control flow, such as loops and conditionals, these are not yet implemented.
• Classical Variables: Handling classical variables is not included in the current architecture.
• Not standard Gates: Generating QASM for not standard gates and mapping them to Qiskit’s standard gates is pending.

These tasks require further discussion to determine whether they should be included in the scope of Qiskit Issue #13145. My recommendation is to address these features after Qiskit PR #13278 is merged, potentially targeting them for the 2.1 release and beyond.

What is Pending

1. Support for:
• Control flow constructs like loops, conditionals, and subroutines.
• Advanced QASM 3.0 features, including classical variable handling and parameterized gates.
• Handling edge cases for non-standard instructions or unique circuit data.
2. Architecture Alignment:
• Finalizing the architecture based on team feedback to ensure long-term scalability.
• Deciding whether the symbol table from symbols.rs should remain part of the architecture or be replaced with a more streamlined solution.

Discussion Points

1. Scope of Qiskit Issue #13145:
• Should the above pending features (control flow, classical variables, custom gates) be addressed as part of this issue, or deferred to subsequent iterations?
• My suggestion is to revisit these features post-merge of Qiskit PR #13278, targeting them for the 2.1 release or later.
2. Testing and Architecture Validation:
• Before implementing test cases, I would like to confirm agreement on the overall architecture and the scope of tasks to ensure alignment with the team’s priorities.

import numpy as np
import warnings

from qiskit import qasm3
from qiskit.exceptions import ExperimentalWarning
from qiskit.circuit.library import RealAmplitudes

warnings.filterwarnings("ignore", category=ExperimentalWarning)

# This is a little more than 5k gates.
base = RealAmplitudes(27, reps=100, flatten=True)
base = base.assign_parameters(np.random.rand(base.num_parameters))

print("Current OpenQASM 3 time")
%timeit qasm3.dumps(base)
print("New OpenQASM 3 time")
%timeit qasm3.dumps_experimental(base)

Current OpenQASM 3 time
75.7 ms ± 870 μs per loop (mean ± std. dev. of 7 runs, 10 loops each)

New OpenQASM 3 time
15.2 ms ± 782 μs per loop (mean ± std. dev. of 7 runs, 100 loops each)

I expect new qasm3.dumps() will become faster if it can be independent completely from python.