Add `qk_circuit_draw` function to the C API by eliarbel · Pull Request #15361 · Qiskit/qiskit

eliarbel · 2025-11-20T22:45:57Z

This PR adds support for circuit text drawing through the C API. ~~It is based and blocked on #15357. See commit fefdd03 for the changes of this PR only.~~

qiskit-bot · 2025-11-20T22:46:01Z

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

@Eric-Arellano
@abbycross
@beckykd
@Qiskit/terra-core

coveralls · 2025-11-20T23:33:00Z

Pull Request Test Coverage Report for Build 19696786623

Details

15 of 788 (1.9%) changed or added relevant lines in 3 files are covered.
36 unchanged lines in 2 files lost coverage.
Overall coverage decreased (-0.6%) to 87.604%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/cext/src/circuit.rs	14	16	87.5%
crates/circuit/src/circuit_drawer.rs	0	771	0.0%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	6	91.52%
crates/qasm2/src/parse.rs	30	95.68%

Totals
Change from base Build 19684338744:	-0.6%
Covered Lines:	94408
Relevant Lines:	107767

💛 - Coveralls

ShellyGarion · 2026-03-19T09:25:49Z

+
+    uint32_t qubits[10] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+    double params[3] = {1.41, 2.71, 3.14};
+    for (uint8_t gate = 0; gate <= QkGate_RC3X; ++gate) {


is there a simpler way to loop over all standard gates?
also, there is a gate that needs 4 parametrs (CUGate), and here only 3 are given.
should we also add reset to the test?
what about the new gates like PPM and PPR ?

This is merely a smoke test type of thing, just to have evidence that it's working. Thanks to Matthew we now have more rigor Rust test now for the Rust text drawer.

Good catch about the 4-param gate and the missing reset instruction. Addressed in c2ce88c.

Regarding PPR/PPM: not all gates are supported yet by the Rust drawer. We'll add more as we go.

jakelishman

If this is still intended to merge for the 2.4 cycle, can you give the new C functions export slots somewhere suitable in qiskit-cext-vtable?

eliarbel · 2026-03-19T15:55:29Z

This is now rebased on top of main.

eliarbel · 2026-03-19T16:00:38Z

If this is still intended to merge for the 2.4 cycle, can you give the new C functions export slots somewhere suitable in qiskit-cext-vtable?

Good idea. Done in 11e02ad

alexanderivrii

Thanks Eli! I experimented with this PR earlier, drawing circuits using the C interface, and all the gates appear correct.

jakelishman

I think there was a slightly mistaken merge-conflict resolution

jakelishman · 2026-03-19T16:12:49Z

+/// The configuration options for the ``qk_circuit_draw`` function.
+#[repr(C)]
+pub struct CCircuitDrawerConfig {
+    /// If `true`, bundles classical registers into single wires.
+    bundle_cregs: bool,
+    /// If `true`, merges the bottom and top lines of adjacent wires.
+    merge_wires: bool,
+    /// Sets the line length for wrapping the rendered text. Use 0
+    /// to auto-detect console width.
+    fold: usize,
+}


It's too late to change now for the release, but given this configuration may well expand in the future, we might be in a bit of an awkward position with API stability and require a breaking change - having the struct members all be visible to C makes it harder for us to modify it in the future without an API break.

We can revisit in the future if/when we need to change it, and we're explicitly not API stable yet in the C API, so no worries.

Fwiw (and this is really minor) - when in repr(C), the order of the struct members is guaranteed to be in declaration order, but then to satisfy alignment concerns this means that there's going to be padding bytes between merge_wires and fold.

having the struct members all be visible to C makes it harder for us to modify it in the future without an API break.

I didn't want to add more functions to the API for this (i.e. getter and setters for the options if this is opaque), so I thought maybe ABI stability should be enough (since it's passed by address). Anyway, Ok, I'd be happy to have it more API-stability friendly.

Thanks about the repr(c).

It's passed by address, but given the access pattern is meant to be (judging by the test) that the caller allocates one on the stack themselves, then the trouble will be that if we extend the struct in a later version of the C API, code compiled against Qiskit 2.4 will have only allocated the 16 bytes needed for this struct, but Qiskit 2.5 might then try to read more than 16 bytes through the pointer it's given, which is an overread error, and it'll get random stack data instead.

jakelishman

Thanks for this, Eli. I think given more time I might have wanted to think about the configuration API more, but given we're explicitly unstable in the C API, I'd rather get this out like this than not at all.

jakelishman · 2026-03-19T16:20:00Z

+    for (uint8_t gate = 0; gate <= QkGate_RC3X; ++gate) {
+        qk_circuit_gate(circuit, gate, &qubits[gate % 8], params);
+    }


hahaha oh wow, that's quite the strategy

It's C after all, right? 😉

I was also surprized that there was no API like
for gate in StandardGateList
or similar...

I mean, this basically is the way of doing it in C, but yeah, we don't have it in Rust.

Yeah we do :p for gate in (0..STANDARD_GATE_SIZE).map(|x| unsafe { std::mem::transmute(x) }) (probably missing a type hint, but I'm on my phone)

mtreinish · 2026-03-19T16:38:23Z

+    merge_wires: bool,
+    /// Sets the line length for wrapping the rendered text. Use 0
+    /// to auto-detect console width.
+    fold: usize,


Do we not have an option for no folding in the api? In python we set this to -1 to not fold. I guess usize::max is fine as an equivalent. But maybe we should document that.

I haven't really thought about this use case initially, but I can see now how this could be useful e.g. for saving the output to a file. The Rust drawer itself uses usize for the wrapping length, so using -1 as a sentinel value seems maybe too intrusive change for this, since usize::MAX practically provides this behavior. I'll update the documentation during the RC period.

eliarbel added this to the 2.3.0 milestone Nov 20, 2025

eliarbel requested a review from a team as a code owner November 20, 2025 22:45

eliarbel added the Changelog: Added Add an "Added" entry in the GitHub Release changelog. label Nov 20, 2025

eliarbel added this to Qiskit 2.3 Nov 20, 2025

eliarbel added the C API Related to the C API label Nov 20, 2025

github-project-automation Bot moved this to Ready in Qiskit 2.3 Nov 20, 2025

eliarbel added the on hold Can not fix yet label Nov 20, 2025

jakelishman assigned mtreinish Nov 25, 2025

Cryoris modified the milestones: 2.3.0, 2.4.0 Dec 9, 2025

github-project-automation Bot added this to Qiskit 2.4 Dec 9, 2025

github-project-automation Bot moved this to Ready in Qiskit 2.4 Dec 9, 2025

Cryoris removed this from Qiskit 2.3 Dec 9, 2025

eliarbel mentioned this pull request Mar 10, 2026

Text circuit drawer #15357

Merged

alexanderivrii moved this from Ready to Blocked in Qiskit 2.4 Mar 18, 2026

ShellyGarion reviewed Mar 19, 2026

View reviewed changes

jakelishman reviewed Mar 19, 2026

View reviewed changes

jakelishman mentioned this pull request Mar 19, 2026

Add cext slots added since last update #15838

Merged

alexanderivrii moved this from Blocked to In review in Qiskit 2.4 Mar 19, 2026

eliarbel added 4 commits March 19, 2026 17:49

Add qk_circuit_draw to the C API

9ba12b7

Fix clang-format issue

7076154

Address the review comments on the C test

c2ce88c

Add qk_circuit_draw to the vtable

11e02ad

eliarbel force-pushed the c-api-circuit-drawer branch from afc2312 to 11e02ad Compare March 19, 2026 15:54

Clean up

bcb2123

alexanderivrii reviewed Mar 19, 2026

View reviewed changes

jakelishman reviewed Mar 19, 2026

View reviewed changes

Comment thread crates/cext/cbindgen.toml Outdated

Comment thread crates/cext/src/circuit.rs Outdated

One more cleanup

52d8c70

jakelishman reviewed Mar 19, 2026

View reviewed changes

eliarbel removed the on hold Can not fix yet label Mar 19, 2026

jakelishman approved these changes Mar 19, 2026

View reviewed changes

jakelishman enabled auto-merge March 19, 2026 16:21

mtreinish reviewed Mar 19, 2026

View reviewed changes

jakelishman added this pull request to the merge queue Mar 19, 2026

Merged via the queue into Qiskit:main with commit f0d87ec Mar 19, 2026
25 checks passed

github-project-automation Bot moved this from In review to Done in Qiskit 2.4 Mar 19, 2026

eliarbel mentioned this pull request Mar 22, 2026

Improve docs for the fold field in CircuitDrawerConfig #15850

Merged

mergify Bot mentioned this pull request Mar 22, 2026

Improve docs for the fold field in CircuitDrawerConfig (backport #15850) #15852

Merged

Conversation

eliarbel commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qiskit-bot commented Nov 20, 2025

Uh oh!

coveralls commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19696786623

Details

💛 - Coveralls

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eliarbel Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakelishman left a comment

Choose a reason for hiding this comment

Uh oh!

eliarbel commented Mar 19, 2026

Uh oh!

eliarbel commented Mar 19, 2026

Uh oh!

alexanderivrii left a comment

Choose a reason for hiding this comment

Uh oh!

jakelishman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jakelishman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

eliarbel commented Nov 20, 2025 •

edited

Loading

coveralls commented Nov 20, 2025 •

edited

Loading

eliarbel Mar 19, 2026 •

edited

Loading