Environment

• Qiskit version: 1.2
• Python version: 3.11
• Operating system: Sonoma 14.6.1 (23G93) aarch64

What is happening?

When custom includes are passed into the qiskit/qasm3/exporter::Exporter.__init__ function, the export of QASM will always throw an error when the dump function is called via the QASM3Builder. The docs say:

includes: the filenames that should be emitted as includes.  These files will be parsed
    for gates, and any objects dumped from this exporter will use those definitions
    where possible.

This worked fine in Qiskit 1.1.x but 1.2 changed the behavior such that any includes passed in that aren't exactly stdgates.inc will raise QASM3ExporterError. This also removed the GlobalNamespace type breaking consumers.

In 1.1.x the definitions from the custom includes were treated as opaque assuming any missing definitions would have been provided in the basis gates passed into the Exporter.

How can we reproduce the issue?

from qiskit import QuantumCircuit
from qiskit.qasm3 import Exporter, QASM3ExporterError

try:
    qc = QuantumCircuit(1, 1)
    includes = ("stdgates.inc", "custom_gates.inc")
    Exporter(includes=includes).dumps(qc)
except QASM3ExporterError as ex:
    print(ex)

"Unknown OpenQASM 3 include file: 'custom_gates.inc'"

What should happen?

The documentation indicates that the includes will be parsed for gate definitions. The docs have not changed since 1.1.x so the docs have never matched the implementation. I think there are two primary paths which can be taken:

• Restore the old functionality and update the documentation. This would allow custom gate definitions in QASM files.
  • The basis_gates can be used to define opaque gate names which would be found in the external QASM files.
• Update the Exporter/QASM3Builder to match the docs. This will require updating the crates/qasm3/build.rs as it currently noops gate definitions when parsing the ASG.
  • How would this reconcile parsed definitions vs the basis_gates parameter?

These solutions would not include any files included from the supplied includes list. Instead, the supplied includes are listed at the top of the generated QASM file as was done in 1.1.x.

Any suggestions?

No response