Add `qiskit.capi` module by jakelishman · Pull Request #15711 · Qiskit/qiskit

jakelishman · 2026-02-22T15:16:18Z

This adds a basic qiskit.capi module for Python-space interaction with the C API. The two initial functions included are get_include and get_lib, to get the package include directory and shared-object library containing the C-API exported symbols, respectively.

Note that while the included header files are complete information to build against the C API, the file returned from get_lib is not generally useful as part of a build system, but can be used to interact with the C API live through a Python session.

I hope to follow this patch with two more:

provide a second "mode" for the packaged header files that allows building safe Python extension modules against the C API. This would mean that all the C API function names will be #define'd to function pointers looked up in a static table stored inside a PyCapsule that is initialised as part of _accelerate's initialisation.
generate a ctypes wrapper file for the C API as part of the _accelerate (pyext) build script, which would expose all of the C API functions directly to Python space, potentially allowing them to be jitted through Numba, or allowing direct tests of C API functionality (without the manually-written file currently in our test suite).

Summary

Details and comments

Close #15609.

Currently built on ~~#15679 and~~ a PR to setuptools-rust (PyO3/setuptools-rust#574).

qiskit-bot · 2026-02-22T15:16:23Z

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

@abbycross
@beckykd
@Qiskit/terra-core

mrossinek

At a cursory glance this all makes sense to me thus far 👍

Will give a more thorough look next week!

mrossinek

I just reviewed 843b4bf to isolate the changes made by this PR from the current base.

This all seems great, I'm just adding some minor suggestions/questions.

I assume this is blocked by a working solution to get merged and released into setuptools-rust?

crates/bindgen/src/lib.rs

releasenotes/notes/header-file-include-aad5efd67ace6bad.yaml

.gitignore

jakelishman · 2026-02-23T13:06:25Z

I assume this is blocked by a working solution to get merged and released into setuptools-rust?

Yeah, basically. It's not 100% hard blocked on that because we could release using the build dependency on my branch of setuptools-rust, or I could release a forked version to PyPI with it. But that's hugely undesirable and an absolute last resort - I'd first see if there was a hackier way I could do it manually from within our setup.py before doing something like that.

(I think there is - I could patch the build_rust command from a known version of setuptools-rust to basically vendor in my PyO3/setuptools-rust#574 PR with some extra hacky logic to search for the target directory.)

This adds a basic `qiskit.capi` module for Python-space interaction with the C API. The two initial functions included are `get_include` and `get_lib`, to get the package include directory and shared-object library containing the C-API exported symbols, respectively. Note that while the included header files _are_ complete information to build against the C API, the file returned from `get_lib` is not generally useful as part of a _build_ system, but can be used to interact with the C API live through a Python session. I hope to follow this patch with two more: * provide a second "mode" for the packaged header files that allows building safe Python extension modules against the C API. This would mean that all the C API function names will be `#define`'d to function pointers looked up in a static table stored inside a `PyCapsule` that is initialised as part of `_accelerate`'s initialisation. * generate a `ctypes` wrapper file for the C API as part of the `_accelerate` (`pyext`) build script, which would expose all of the C API functions directly to Python space, potentially allowing them to be jitted through Numba, or allowing direct tests of C API functionality (without the manually-written file currently in our test suite). Co-authored-by: Max Rossmannek <max@rossmannek.de>

jakelishman · 2026-03-05T18:51:16Z

I think I'll have to revisit this and put in temporary infrastructure to do a git submodule and an in-tree build-system build of setuptools-rust, or something like that, because I don't think we can depend on a full release of setuptools-rust with my patch in time.

That's ok, I think - we can work around it.

We need PyO3/setuptools-rust#574 (or something akin to it) to handle the movement of the generated files from the build script to the output. This is not yet ready for merge, and is highly unlikely to be ready in time for the Qiskit 2.4.0 release (or at least 2.4.0rc1), so to avoid blocking ourselves, we vendor in a monkey-patching reimplementation of the code temporarily. The allowed range of `setuptools-rust` is _probably_ larger than the hard pin, but the monkey-patch is so invasive and v1.12.0 is sufficiently old (August 2025) that it's not worth the risk. There are no meaningful licensing concerns since the vendored code here was entirely written by me both here and in the `setuptools-rust` patch; there is no cross-contamination from that repository and no code inclusion from it. This commit should be reverted as soon as we can swap to a safe released version of `setuptools-rust`.

jakelishman · 2026-03-10T14:27:17Z

It's unlikely that PyO3/setuptools-rust#574 will merge in time, so I've updated this PR to make a horrendous but self-contained monkeypatch to a known-good version of setuptools-rust as a temporary build system, until we can revert d3d2e54 and swap to a proper installed version of setuptools-rust.

Doing that unblocks this chain of work - if the setuptools-rust PR merges (and releases) before our 2.4.0rc1 we can swap back later, but there's no need to wait.

Cryoris

Essentially LGTM, I left some small comments below

qiskit/capi/__init__.py

crates/bindgen/src/lib.rs

crates/pyext/build.rs

Cryoris · 2026-03-10T17:26:39Z

test/python/capi/ffi.py


-LIB_PATH = qiskit._accelerate.__file__
-LIB = ctypes.PyDLL(LIB_PATH)
+LIB = ctypes.PyDLL(qiskit.capi.get_lib())


Nice - we should remember to update the guides with this

Well not really - you basically should never be doing this. I do have to update the guide, but with how to build an actually safe C extension, and that doesn't involve qiskit.capi.get_lib() at all.

(Using ctypes is like the one exception where it makes sense to use the _accelerate object loaded live.)

-> which is what the guide is doing: https://quantum.cloud.ibm.com/docs/en/guides/c-extension-for-python 🙂

No it isn't, at least not related to get_lib() - the guide is describing how to make a ctypes binding to you own correctly-exposed module. It's the "Build" section below that one that discusses _accelerate, where this method would be relevant, but that's the place that's wildly unsafe and needs to be completely rewritten.

test/python/capi/test_capi.py

pyproject.toml

setup.py

qiskit/capi/__init__.py

jakelishman · 2026-03-10T18:48:16Z

The wheel-build failures are unrelated and should be fixed by #15791.

mrossinek

Nice, Julien caught a lot more typos than I did 😅

Do you already want to open an issue to track the removal of the horrendous monkeypatch in setup.py once the setuptools-rust feature lands?

jakelishman · 2026-03-11T09:12:53Z

Max: the "messsages" typo was only introduced after you reviewed haha.

I can open an issue after this merges, assuming it merges in this form. I'm not likely to forget, though - it's already my PR I'm waiting on, and I wrote it specifically for this purpose!

Cryoris

LGTM thanks for the explanations, too!

This new module was added in Qiskit/qiskit#15711

jakelishman added this to the 2.4.0 milestone Feb 22, 2026

jakelishman added the Changelog: Added Add an "Added" entry in the GitHub Release changelog. label Feb 22, 2026

jakelishman requested a review from a team as a code owner February 22, 2026 15:16

jakelishman added ci: test wheels Run the wheel-build scripts as an additional CI run for this PR Changelog: Build Add a "Build System" entry in the GitHub Release changelog. labels Feb 22, 2026

github-project-automation bot added this to Qiskit 2.4 Feb 22, 2026

github-project-automation bot moved this to Ready in Qiskit 2.4 Feb 22, 2026

jakelishman added on hold Can not fix yet C API Related to the C API labels Feb 22, 2026

jakelishman requested a review from mrossinek February 22, 2026 15:16

jakelishman force-pushed the c/include-file branch 3 times, most recently from 4b0dea6 to 1f1e4cd Compare February 22, 2026 15:59

jakelishman mentioned this pull request Feb 22, 2026

Add installation of data-files build artifacts into Python package PyO3/setuptools-rust#574

Open

mrossinek reviewed Feb 22, 2026

View reviewed changes

mrossinek reviewed Feb 23, 2026

View reviewed changes

crates/bindgen/src/lib.rs Show resolved Hide resolved

releasenotes/notes/header-file-include-aad5efd67ace6bad.yaml Outdated Show resolved Hide resolved

.gitignore Show resolved Hide resolved

jakelishman force-pushed the c/include-file branch from 6bab43a to c484a13 Compare February 23, 2026 12:39

jakelishman force-pushed the c/include-file branch from c484a13 to 0f3ebb5 Compare March 5, 2026 10:31

This was referenced Mar 5, 2026

Separate type/constant declarations from functions in C headers #15760

Merged

Add C API vtable to pyext #15761

Merged

Add safe Python-extension module C API headers #15762

Merged

Provide a safe way for Python extension modules to use the C API #15572

Closed

jakelishman force-pushed the c/include-file branch from 0f3ebb5 to d3d2e54 Compare March 10, 2026 14:25

jakelishman removed the on hold Can not fix yet label Mar 10, 2026

Cryoris self-assigned this Mar 10, 2026

Cryoris reviewed Mar 10, 2026

View reviewed changes

jakelishman added 3 commits March 10, 2026 18:09

Remove pylint suppressions

e526d30

Fix typos

0c1645d

Comment on hard-pin of setuptools-rust

b66bce6

mrossinek approved these changes Mar 11, 2026

View reviewed changes

Cryoris approved these changes Mar 11, 2026

View reviewed changes

Cryoris added this pull request to the merge queue Mar 11, 2026

Merged via the queue into Qiskit:main with commit 676863e Mar 11, 2026
27 of 30 checks passed

github-project-automation bot moved this from Ready to Done in Qiskit 2.4 Mar 11, 2026

jakelishman deleted the c/include-file branch March 11, 2026 14:43

frankharkins mentioned this pull request Mar 13, 2026

Add qiskit.capi to the TOC grouping Qiskit/documentation#4810

Merged

github-merge-queue bot pushed a commit to Qiskit/documentation that referenced this pull request Mar 16, 2026

Add qiskit.capi to the TOC grouping (#4810)

98e5bec

This new module was added in Qiskit/qiskit#15711

frankharkins added a commit to Qiskit/documentation that referenced this pull request Mar 16, 2026

Add qiskit.capi to the TOC grouping (#4810)

5f29817

This new module was added in Qiskit/qiskit#15711

Conversation

jakelishman commented Feb 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details and comments

Uh oh!

qiskit-bot commented Feb 22, 2026

Uh oh!

mrossinek left a comment

Choose a reason for hiding this comment

Uh oh!

mrossinek left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakelishman commented Feb 23, 2026

Uh oh!

jakelishman commented Mar 5, 2026

Uh oh!

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

Uh oh!

Uh oh!

Cryoris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Cryoris Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

jakelishman Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

jakelishman Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Cryoris Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

jakelishman Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jakelishman commented Mar 10, 2026

Uh oh!

mrossinek left a comment

Choose a reason for hiding this comment

Uh oh!

jakelishman commented Mar 11, 2026

Uh oh!

Cryoris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jakelishman commented Feb 22, 2026 •

edited

Loading

jakelishman commented Mar 10, 2026 •

edited

Loading