Render zero-operand instructions (e.g. GlobalPhaseGate) in circuit drawers

[KevesDev]

What does this PR do?

Zero-operand instructions — most commonly a stand-alone GlobalPhaseGate appended via circuit.append(GlobalPhaseGate(angle)) — were being silently dropped by every circuit drawer. circ.draw('text'), circ.draw('mpl'), and circ.draw('latex_source') would all just omit the instruction entirely, with no error and no visual trace that it had ever been there.

This PR makes all three drawers render such instructions as a box spanning every qubit wire, with no per-wire operand index (since there's no specific operand to index), positioned in the circuit's original instruction order — the rendering behavior suggested in the issue itself.

Before:

     ┌───┐┌───┐
q_0: ┤ H ├┤ X ├
     └───┘└───┘
q_1: ──────────
     ┌───┐
q_2: ┤ X ├─────
     └─┬─┘
q_3: ──■───────

q_4: ──────────

(both GlobalPhaseGate(pi) and GlobalPhaseGate(5*pi) calls are simply missing — no trace of them anywhere in the output)

After:

     ┌───┐┌─────────────────┐┌──────────────────┐┌───┐
q_0: ┤ H ├┤                 ├┤                  ├┤ X ├
     └───┘│                 ││                  │└───┘
q_1: ─────┤                 ├┤                  ├─────
     ┌───┐│                 ││                  │
q_2: ┤ X ├┤ Global_phase(π) ├┤ Global_phase(5π) ├─────
     └─┬─┘│                 ││                  │
q_3: ──■──┤                 ├┤                  ├─────
          │                 ││                  │
q_4: ─────┤                 ├┤                  ├─────
          └─────────────────┘└──────────────────┘

Why was this PR needed?

The root cause is upstream of all three drawers, in shared layering code: _get_layered_instructions (qiskit/visualization/circuit/_utils.py) builds its layers from dag.layers(), which only ever visits DAG nodes reachable by walking the DAG's wires. An instruction with no qargs and no cargs has no wires, so dag.layers() never visits it, and it's dropped before any drawer-specific rendering code ever runs.

Fix:

• _get_layered_instructions now separately walks dag.op_nodes() for zero-operand nodes (excluding directives, see below) and re-inserts each one into its own dedicated layer, positioned immediately after the layer of the last real instruction that precedes it in original circuit order. DAGOpNode identity/equality isn't stable across separate dag.layers()/dag.op_nodes() calls (confirmed empirically: the same logical node gets a different _node_id, and even a different id(node.op), depending on which traversal returns it), so matching is done via each instruction's (qargs, cargs) instead, which is stable.
• text.py, matplotlib.py, and latex.py each extend their existing multi-qubit box-drawing code (set_qu_multibox, _multiqubit_gate, _build_multi_gate) with a skip_wire_labels/equivalent option, rather than adding new, parallel drawing functions that duplicate that logic.
• Directives (e.g. a classical Store on a Var, which also has no qargs/cargs) are explicitly excluded from the layering fix — they've never had any rendering for the zero-operand case, and inserting one into its own layer would just produce a visibly empty column. Discovered this while testing against Var-based control-flow circuits; text.py's barrier-handling branch also had a latent crash (min() on an empty qargs) for this case, fixed defensively in case a zero-qarg directive reaches it via another path (e.g. justify="none", which bypasses the layering fix entirely).
• Also fixes an unrelated latent bug in text.py's _set_multibox: its single-bit path always forwarded top_connect (default None) straight into the box constructor, silently overriding that class's own sensible default and breaking a later .center() call. No existing caller hit this combination before; the new zero-operand path does, on any single-qubit circuit.

I also checked a previous attempt at this issue (#12922, stalled in draft). Its _LayerSpooler patch walked dag.topological_op_nodes() and inserted every zero-operand node at the very start of the circuit, since topological sort has no ordering for nodes with no dependency edges — multiple GlobalPhaseGates would all land in column 0 regardless of where they were declared. This PR instead places each one in true original-circuit-order. That PR also had no implemented tests and an author-acknowledged "hack" for the matplotlib portion.

What are the relevant issue numbers?

Fixes #9962

Screenshots / Recordings

Text drawer output is included inline above. For the matplotlib drawer, the same circuit renders as a box spanning all 5 qubits for each GlobalPhaseGate, with no per-wire numbers — happy to attach a rendered PNG in review if it's helpful. I did not add a matplotlib snapshot/reference-image test to test/visual/mpl/circuit/test_circuit_matplotlib_drawer.py, since generating a correctly-matched reference image requires this project's mybinder snapshot-testing notebook (per CONTRIBUTING.md) to match CI's exact rendering environment, which I can't do from a local clone — flagging this explicitly as a follow-up rather than skipping it silently. I did add a non-snapshot regression test (test_mpl_zero_operand_gate_does_not_raise) covering the same code path.

Does this PR meet the acceptance criteria?

• Tests added for new/changed behavior — 8 new unit tests across test_utils.py, test_circuit_text_drawer.py, test_circuit_drawer.py, and test_circuit_latex.py (the latter using the project's existing assertEqualToReference text-diff mechanism, with committed reference .tex files).
• All tests passing — full local run of all four touched test modules (245 tests) is green.
• Follows project style guide — black and ruff both pass clean on every modified file.
• No breaking changes introduced — change is additive; previously-dropped instructions now render, nothing previously-rendered changes.
• Documentation updated — n/a beyond the added release note (no public API changed).

Also added a reno release note (releasenotes/notes/fix-zero-operand-drawers-5b92cd1d081d2aeb.yaml).

AI/LLM disclosure

• I didn't use LLM tooling, or only used it privately.
• I used the following tool to help write this PR description: Claude Code (Claude Sonnet 4.6)
• I used the following tool to generate or modify code: Claude Code (Claude Sonnet 4.6)

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the following people are relevant to this code:

• @enavarro51
• @Qiskit/terra-core

[CLAassistant]

All committers have signed the CLA.

[KevesDev]

Hi @enavarro51 — this is my first contribution to Qiskit. I've fixed #9962 (zero-operand instructions like GlobalPhaseGate being silently dropped by the text, matplotlib, and LaTeX circuit drawers) by reworking the shared layering logic in _get_layered_instructions and extending each drawer's existing multi-qubit box-drawing code to render them. I picked you as a reviewer since you're by far the most frequent contributor to these exact files in the git history. Tests and lint are passing locally; details are in the PR description. Would appreciate a review when you have time — thank you!

[KevesDev]

Pushed a follow-up commit (1870092) before any review: while double-checking the directive-exclusion fix against a clean build of unmodified main, I found that my fix to the qubit-pruning filter at the end of _get_layered_instructions was itself causing a classical Store (on a Var) to reach each drawer's directive-handling code and crash it -- a regression I'd introduced, not a pre-existing issue as I'd assumed in an earlier commit message. Fixed by extracting a single shared predicate (_is_zero_operand_gate) used consistently by both the insertion and pruning logic, so a real zero-operand gate and a zero-operand directive can't be treated inconsistently between the two again. Verified against a from-scratch build of unmodified upstream main in an isolated worktree to confirm the before/after behavior precisely. Tests and lint still passing (245/245 locally).