Qiskit C++ Issue #146: Only Add OpenQASM 3 export support in qiskit-cpp

[GoiBasia]

Summary

This PR version implements OpenQASM 3 export support entirely within qiskit-cpp. It adds a dedicated Qiskit::qasm3::dumps(...) exporter, keeps QuantumCircuit::to_qasm3() as a compatibility wrapper, and reuses the existing parameter serialization path to support parameter-aware QASM3 output.

No changes to the upstream Qiskit library or its C API are required for this implementation.

Details and comments

Fix

src/qasm3/qasm3_exporter.hpp

Adds the dedicated QASM 3 exporter and public Qiskit::qasm3::dumps(...) API. It adds RAII wrappers for C API resources such as QkOpCounts, QkCircuitInstruction, and qk_param_str() strings, and emits parameter declarations before registers and operations.

src/circuit/quantumcircuit_def.hpp

Removes inline QASM text generation from QuantumCircuit::to_qasm3() and delegates to the new exporter. It also records parameter-symbol metadata when parameterized gates are added, appended, composed, copied, or recovered through operator[].

src/circuit/quantumcircuit.hpp

Includes the new QASM 3 exporter header so the compatibility to_qasm3() path can delegate cleanly.

src/circuit/parameter.hpp

Tracks local parameter-symbol metadata on C++ Parameter objects. Symbol names are preserved across copies and parameter operations, including arithmetic and common unary functions, so expressions retain the names needed for QASM declarations.

test/test_circuit.cpp

Adds coverage for parameter-aware QASM export, including direct symbolic parameters, expressions, numeric-only parameters, uppercase U(...), explicit parameter names, invalid explicit names, parameterized compose(...), append(src[0]), and the fail-closed path when default names cannot be recovered.

Example Result

A parameterized circuit now exports self-contained OpenQASM 3:

OPENQASM 3.0;
include "stdgates.inc";
input float[64] theta;
qubit[1] q;
bit[1] c;
rx(theta) q[0];

Numeric-only parameters do not emit unnecessary input declarations:

OPENQASM 3.0;
include "stdgates.inc";
qubit[1] q;
bit[1] c;
rx(0.25) q[0];

Coverage

The qiskit-cpp tests cover:

• existing non-parameterized QASM output
• single parameter declarations
• multiple parameter declarations in wrapper metadata order
• parameter expressions
• numeric-only parameterized gates
• uppercase U(...) output
• Qiskit::qasm3::dumps(circuit, names) happy path
• wrong parameter count, empty name, and duplicate-name validation
• compatibility through QuantumCircuit::to_qasm3()
• parameter metadata through compose(...)
• parameter metadata through append(src[0])
• fail-closed default export when wrapper-side names are unavailable

Verification

The qiskit-cpp fix was verified with:

cmake --build test/build
ctest -V -C Debug --test-dir test/build
git diff --check

The qiskit-cpp test suite passed 3/3.

• [ √] I have added the tests to cover my changes.
• [√ ] I have updated the documentation accordingly.
• [√ ] I have read the CONTRIBUTING document.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}