Add initial C API for circuit construction #14006

mtreinish · 2025-03-12T16:05:17Z

Summary

Building off the infrastructure for the sparse observable added in
PR #13445 this commit adds a C FFI for building Quantum Circuits. Right
now there is a function to create an empty circuit with n qubits and m
clbits and then a function to add standard gates to a circuit and then
also get the op counts out of a circuit. This is a start of the
functionality for a C API around interacting with circuits, later PRs
will expand this so we can have a more fully featured C API in the
future.

Details and comments

Part of #13276

This PR is based on top of #13986 and will need to rebased after that merges. To see the contents of just this PR you can look at: mtreinish/qiskit-core@no-py-token-constructor-path...mtreinish:qiskit-core:c-api-circuit-rebased

TODO:

Add release notes

qiskit-bot · 2025-03-12T16:05:23Z

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

@Qiskit/terra-core
@levbishop

Cryoris

This looks really cool! I left some comments below 🙂

crates/cext/src/circuit.rs

test/c/test_circuit.c

crates/cext/src/circuit.rs

test/c/test_circuit.c

coveralls · 2025-03-12T20:18:58Z

Pull Request Test Coverage Report for Build 14192218180

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

14 of 270 (5.19%) changed or added relevant lines in 5 files are covered.
4 unchanged lines in 1 file lost coverage.
Overall coverage decreased (-0.2%) to 87.819%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/cext/src/pointers.rs	0	19	0.0%
crates/cext/src/circuit.rs	0	237	0.0%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	4	92.48%

Totals
Change from base Build 14175885620:	-0.2%
Covered Lines:	72818
Relevant Lines:	82918

💛 - Coveralls

Building off the infrastructure for the sparse observable added in PR Qiskit#13445 this commit adds a C FFI for building Quantum Circuits. Right now there is a function to create an empty circuit with n qubits and m clbits and then a function to add standard gates to a circuit and then also get the op counts out of a circuit. This is a start of the functionality for a C API around interacting with circuits, later PRs will expand this so we can have a more fully featured C API in the future. Part of Qiskit#13276

Co-authored-by: Julien Gacon <[email protected]>

This also updates the test logic to make sure we always free even in case of a failure.

Cryoris · 2025-03-18T09:45:16Z

crates/cext/src/circuit.rs

+/// Behavior is undefined ``circuit`` is not a valid, non-null pointer to a ``QkCircuit``.
+#[no_mangle]
+#[cfg(feature = "cbinding")]
+pub unsafe extern "C" fn qk_circuit_append_measure(


Should we just call this qk_circuit_measure (same for the other directives)? The append doesn't really add any information, or what do you think?

I can drop append if you prefer. I named it this way because of the gate function I used append.

crates/cext/src/circuit.rs

Cryoris · 2025-03-18T09:49:09Z

crates/cext/src/circuit.rs

+    circuit: *mut CircuitData,
+    qubit: u32,
+) -> ExitCode {
+    let circuit = unsafe { mut_ptr_as_ref(circuit) };


I'm surprised cargo doesn't complain (maybe because of unsafe?) but the circuit should be declared mut if we push onto it, no? The same holds for the other methods 🙂

crates/cext/src/circuit.rs

Cryoris · 2025-03-18T10:07:13Z

crates/cext/src/circuit.rs

+/// Behavior is undefined if ``inst`` is not an object returned by ``qk_circuit_get_instruction``.
+#[no_mangle]
+#[cfg(feature = "cbinding")]
+pub unsafe extern "C" fn qk_free_circuit_instruction(inst: CInstruction) {


This should be qk_circuit_instruction_free for consistency -- and should it take a pointer to a CInstruction otherwise the struct would get passed by value? Same question actually below for OpCounts 🙂

It does take it by value, but that's because we're freeing the pointers that are contained in the struct not the struct itself. Each CInstruction has 4 pointers to a heap allocated arrays that we need to free. If we just drop the instruction those would be leaked. We can take a pointer to CInstruction but it functionally doesn't matter in this case because the struct itself isn't what we're freeing.

But don't we also need to free the struct if it was allocated by qk_circuit_get_instruction? 🤔

It's a directly returned stack allocated struct so we don't have to worry about freeing it, the memory will be reclaimed automatically like any local variable (unless the caller puts it on the heap but then it's their responsibility).

Ah right because we don't Box::free anything we don't have to consume it again -- like the 1:1 mapping of malloc and free in C

Co-authored-by: Julien Gacon <[email protected]>

… function

Locally I was using clang-format-19 while in CI we run with clang-format-14. Version 14 was flagging this difference while version 19 was happy. This commit makes the change to make version 14 happy in CI.

raynelfss

I gave a quick review to what you've worked on so far. I feel like it makes sense to me even if the API is still very limited. I would suggest adding any additional support for other operations within the circuit in subsequent PRs.

Most of the observations here are just docstring comments :)

crates/cext/src/circuit.rs

raynelfss · 2025-03-20T19:40:34Z

releasenotes/notes/c-api-circuit-3ecb43d396425bed.yaml

+    The C API for Qiskit has been extended with support for building and
+    interacting with quantum circuits.


Maybe we should mention that the support of this API is limited ?

Suggested change

The C API for Qiskit has been extended with support for building and

interacting with quantum circuits.

The C API for Qiskit has been extended with limited support for building and

interacting with quantum circuits.

I'm not actually sure what limited would mean here. The API lets you build and interact with a quantum circuit. It's not the same as the python API but there will be continued incremental improvements to the API over time. We're also 3 months out from the final 2.1.0 release so it's hard to say how limited the API will be when we finish.

raynelfss · 2025-03-20T19:52:42Z

test/c/test_circuit.c

+int test_gate_num_qubits() {
+    for (uint8_t i = 0; i < 52; i++) {
+        if (i == 0) {
+            if (qk_gate_num_qubits(i) != 0) {
+
+                return EqualityError;
+            }
+        } else if (i < 21) {
+            if (qk_gate_num_qubits(i) != 1) {
+                return EqualityError;
+            }
+        } else if (i <= 44) {
+            if (qk_gate_num_qubits(i) != 2) {
+                return EqualityError;
+            }
+        } else if (i <= 48) {
+            if (qk_gate_num_qubits(i) != 3) {
+                return EqualityError;
+            }
+        } else {
+            if (qk_gate_num_qubits(i) != 4) {
+                return EqualityError;
+            }
+        }
+    }
+    return Ok;
+}


Would it be possible for us to iterate through the values of the Enum itself? AFAIK we could do something like:

for (QkGate gate = X; i < RC3X; i++) { ... }

But then again there's no perfect way of knowing the end value of an enum unless added explicitly. But in case we were to hypothetically add a new standard gate, we wouldn't necessarily have to update this test manually.

I can change the integers to use the gate enum variants, but in practice I think trying to make this robust against future gates won't really be feasible. It would depend on semantics being applied to the enum ordering which isn't a guarantee, we have a convention now. But if we add gates that definitely won't hold because we're unlikely to ever change the existing order of gates in the future because it would require very large refactoring, more than just these tests.

raynelfss · 2025-03-20T19:57:50Z

test/c/test_circuit.c

+    return Ok;
+}
+
+int test_get_gate_counts_bv_no_measure() {


Someone really likes Bernstein-Vazirani :)

test/c/CMakeLists.txt

Co-authored-by: Julien Gacon <[email protected]>

test/c/CMakeLists.txt

mtreinish added Changelog: New Feature Include in the "Added" section of the changelog Rust This PR or issue is related to Rust code in the repository mod: circuit Related to the core of the `QuantumCircuit` class or the circuit library C API Related to the C API labels Mar 12, 2025

mtreinish added this to the 2.1.0 milestone Mar 12, 2025

mtreinish requested a review from a team as a code owner March 12, 2025 16:05

mtreinish force-pushed the c-api-circuit-rebased branch from d3d226a to 590e7a8 Compare March 12, 2025 16:49

Cryoris reviewed Mar 12, 2025

View reviewed changes

mtreinish force-pushed the c-api-circuit-rebased branch from 2e02dc1 to bbde5e5 Compare March 12, 2025 19:50

mtreinish added the priority: high label Mar 12, 2025

Cryoris mentioned this pull request Mar 14, 2025

Concise StandardGate::<ID> enums in Rust space #14026

Merged

mtreinish and others added 6 commits March 14, 2025 17:25

Add functions for standard instructions (except delay)

1b9b884

Apply suggestions from code review

7ec4361

Co-authored-by: Julien Gacon <[email protected]>

Rename qk_circuit_free_count_ops() to qk_opcounts_free()

c4425e2

This also updates the test logic to make sure we always free even in case of a failure.

Add release note

ccaa499

Add function to get instruction details

669695a

mtreinish force-pushed the c-api-circuit-rebased branch from 3e62ec6 to 669695a Compare March 15, 2025 18:22

mtreinish changed the title ~~[WIP] Add initial C API for circuit construction~~ Add initial C API for circuit construction Mar 15, 2025

mtreinish added 2 commits March 17, 2025 15:54

Merge remote-tracking branch 'origin/main' into c-api-circuit-rebased

2dd8940

Rename QkStandardGate -> QkGate

66a989c