DAGCircuit is missing adequate documentation

[sbrandhsn]

URL to the relevant documentation

A DAGCircuit (https://docs.quantum.ibm.com/api/qiskit/qiskit.dagcircuit.DAGCircuit) is an essential part of the transpilation backbone. Formerly, we had the tutorial at https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/circuits_advanced/04_transpiler_passes_and_passmanager.ipynb to describe how to work with a DAGCircuit but nowadays there is no information on that except what is included in the API docs at https://docs.quantum.ibm.com/api/qiskit/qiskit.dagcircuit.DAGCircuit

Specifically, https://docs.quantum.ibm.com/transpile/custom-transpiler-pass points to https://www.rustworkx.org/tutorial/dags.html which is not as useful as the previously available tutorial for users that want to develop their own passes.

Select all that apply

• [ ] typo
• [ ] code bug
• [ ] out-of-date content
• [ ] broken link
• [ ] other

Describe the fix.

Insert a subset of the content at https://github.com/Qiskit/qiskit-tutorials/blob/master/tutorials/circuits_advanced/04_transpiler_passes_and_passmanager.ipynb into the docs or add a new section that describes how to work with the DAGCircuit to users that want to develop their own passes.

[abbycross]

Hi @sbrandhsn, thanks for opening the issue. Does the unitary synthesis plugin example in the the "Create a transpiler plugin" page help at all? It's the only other place where I see DAGCircuit mentioned in the docs.

Marking this as needs discussion so our team can assess next steps.

[abbycross]

@sbrandhsn can you specify the material from the tutorial you'd like to see added into the docs?

[sbrandhsn]

I believe sections 'Introducing the DAG' and 'Implementing a BasicMapper Pass' would be helpful. Longterm, I think 'Introducing the DAG' can be extended heavily to highlight any new functionality in DAGCircuit since 10+ months ago and maybe also include some information on its (asymptotic) performance.

[javabster]

I agree, I think the content we currently have on DAG stuff could be expanded into it's own page.

[JGeipel]

Interested in trying this one for unitaryHACK.

[AbdullahKazi500]

Hi @Eric-Arellano and @sbrandhsn made a PR addressing the issue with the latest version of qiskit 2.0

[SecludedPerson700]

I am interested in the issue as well I Created a PR

[kaelynj]

Hi @JGeipel, @AbdullahKazi500, @SecludedPerson700 . Thanks for you interest in working on this for the Unitary Hack! I'll go through and review each of these PRs in submission order.

[AbdullahKazi500]

Hi @JGeipel, @AbdullahKazi500, @SecludedPerson700 . Thanks for you interest in working on this for the Unitary Hack! I'll go through and review each of these PRs in submission order.

Thanks

[1ucian0]

👋 This issue is part of UnitaryHack 2025. For the duration of the event, it follows a few special rules and considerations:

• No need to be assigned to start working on it, just go ahead! This holds until the end of UnitaryHack.
• If multiple PRs are submitted to close this issue, maintainers may select one at the end of the event and award the bounty accordingly.
• If more than one person works on a single PR, please note that the bounty cannot be split.
• In some cases, a not-fully-complete but close-enough PR might receive a partial bounty.
• If you have any questions or need clarification, feel free to ask in the comments here. Please note that while maintainers do their best to reply, responses might take longer than you expect.

Happy hacking! 🧑‍💻✨