Add qiskit.capi module (#15711)

* Add `qiskit.capi` module

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>

* Vendor `generated-files` handling from `setuptools-rust`

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`.

* Remove pylint suppressions

* Fix typos

* Comment on hard-pin of `setuptools-rust`

---------

Co-authored-by: Max Rossmannek <max@rossmannek.de>

Author: jakelishman

.gitignore

@@ -18,6 +18,8 @@ __pycache__/
 
 # C extensions
 *.so
+# Generated C header files included in package.
+/qiskit/capi/include
 
 # Distribution / packaging
 .Python

Cargo.lock

@@ -19,6 +19,20 @@ pub static GENERATED_FILE: &str = "qiskit.h";
 pub static PYTHON_BINDING_FEATURE: &str = "python_binding";
 pub static PYTHON_BINDING_DEFINE: &str = "QISKIT_C_PYTHON_INTERFACE";
 
+pub static COPYRIGHT: &str = "\
+// This code is part of Qiskit.
+//
+// (C) Copyright IBM 2026
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE.txt file in the root directory
+// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+";
+
 pub static INCLUDE_GUARD: &str = "QISKIT_H";
 /// Crates that contain definitions of objects that are exposed through the C API.
 pub static QISKIT_PUBLIC_API_CRATES: &[&str] =
@@ -100,6 +114,14 @@ fn manual_include_files() -> anyhow::Result<Vec<PathBuf>> {
 
 /// Get the Qiskit configuration
 fn get_config() -> anyhow::Result<cbindgen::Config> {
+    // `Python.h` is required to be the first file included because it reserves the right to define
+    // preprocessor macros that affect standard-library includes.  This causes it to be ahead of our
+    // include guard, but `Python.h` has its own, so we should be fine.
+    let header = Some(format!(
+        "{}\n{}",
+        COPYRIGHT,
+        guarded_python_import(PYTHON_BINDING_DEFINE)
+    ));
     let enumeration = cbindgen::EnumConfig {
         prefix_with_name: true,
         ..Default::default()
@@ -158,10 +180,7 @@ fn get_config() -> anyhow::Result<cbindgen::Config> {
         })
         .collect::<Result<Vec<_>, _>>()?;
     Ok(cbindgen::Config {
-        // `Python.h` is required to be the first file included because it reserves the right to
-        // define preprocessor macros that affect standard-library includes.  This causes it to be
-        // ahead of our include guard, but `Python.h` has its own, so we should be fine.
-        header: Some(guarded_python_import(PYTHON_BINDING_DEFINE)),
+        header,
         language: cbindgen::Language::C,
         include_version: true,
         include_guard: Some(INCLUDE_GUARD.into()),

crates/bindgen/src/lib.rs

@@ -4,6 +4,7 @@ version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true
+build = "build.rs"
 
 [lib]
 name = "qiskit_pyext"
@@ -22,6 +23,10 @@ workspace = true
 default = ["pyo3/extension-module"]
 cache_pygates = ["pyo3/extension-module", "qiskit-circuit/cache_pygates", "qiskit-accelerate/cache_pygates", "qiskit-transpiler/cache_pygates", "qiskit-cext/cache_pygates", "qiskit-qpy/cache_pygates"]
 
+[build-dependencies]
+anyhow.workspace = true
+qiskit-bindgen.workspace = true
+
 [dependencies]
 pyo3.workspace = true
 qiskit-accelerate.workspace = true

crates/pyext/Cargo.toml

@@ -0,0 +1,41 @@
+// This code is part of Qiskit.
+//
+// (C) Copyright IBM 2026
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE.txt file in the root directory
+// of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+use anyhow::anyhow;
+use std::path::Path;
+
+#[allow(clippy::print_stdout)] // We're a build script - we're _supposed_ to print to stdout.
+fn main() -> anyhow::Result<()> {
+    let cext_path = {
+        let mut path = Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf();
+        path.pop();
+        path.push("cext");
+        path
+    };
+    println!(
+        "cargo::rerun-if-changed={}",
+        cext_path
+            .to_str()
+            .ok_or_else(|| anyhow!("cext path isn't unicode"))?
+    );
+    let out_path = {
+        let out_dir = std::env::var("OUT_DIR").expect("cargo should set this for build scripts");
+        let mut path = Path::new(&out_dir).to_path_buf();
+        path.push("include");
+        path
+    };
+    let bindings = qiskit_bindgen::generate_bindings(&cext_path)?;
+    // We install the headers into our `OUT_DIR`, then we configure `setuptools-rust` to pick them
+    // up from there and put them into the Python package.
+    qiskit_bindgen::install_c_headers(&bindings, &out_path)?;
+    Ok(())
+}

crates/pyext/build.rs

@@ -0,0 +1,6 @@
+.. _qiskit-capi:
+
+.. automodule:: qiskit.capi
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/apidoc/capi.rst

@@ -75,6 +75,7 @@ Other:
 .. toctree::
    :maxdepth: 1
 
+   capi
    compiler
    exceptions
    root

docs/apidoc/index.rst

@@ -2,7 +2,10 @@
 # This is duplicated as `dependency-groups.build` for convenience.
 requires = [
     "setuptools>=77.0",
-    "setuptools-rust",
+    # This is hard-pinned to permit the awful monkeypatching in `setup.py`.
+    # It should be removed when we can use a released version of
+    # https://github.com/PyO3/setuptools-rust/pull/574
+    "setuptools-rust==1.12.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -184,7 +187,7 @@ default = "qiskit.transpiler.preset_passmanagers.builtin_plugins:DefaultScheduli
 # process.  If you intended that, use `project.optional-dependencies` instead.
 [dependency-groups]
 # Sync with `build-system.requires`.
-build = ["setuptools>=77.0", "setuptools-rust"]
+build = ["setuptools>=77.0", "setuptools-rust==1.12.0"]
 # We use quite tight pins on pylint and astroid because they have a habit of adding new
 # on-by-default lints that are harder to deal with.
 lint = [

pyproject.toml

@@ -142,6 +142,7 @@
 
 
 from qiskit.exceptions import QiskitError, MissingOptionalLibraryError
+import qiskit.capi
 
 # The main qiskit operators
 from qiskit.circuit import ClassicalRegister

qiskit/__init__.py

@@ -0,0 +1,90 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2026.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at https://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+r"""
+================================================
+C API interface from Python (:mod:`qiskit.capi`)
+================================================
+
+.. currentmodule:: qiskit.capi
+
+This module provides Python-space interactions with Qiskit's public C API.
+
+For documentation on the C API itself, see `Qiskit C API
+<https://quantum.cloud.ibm.com/docs/api/qiskit-c/>`__.
+
+Build-system interaction
+========================
+
+The Python package :mod:`qiskit` contains all of the Qiskit C API header files, and a compiled
+shared-object library that includes all of the C-API functions.  You can access the locations of
+these two objects with the functions :func:`get_include` and :func:`get_lib` respectively.
+
+.. warning::
+    You typically *should not* link directly against the output of :func:`get_lib`, unless you know
+    what you are doing.  In particular, directly linking against this object is not a safe way to
+    build a distributable Python extension module that uses Qiskit's C API.
+
+    However, if you understand all the caveats of direct linking, you can use the function to get
+    the location of the library.
+
+.. autofunction:: get_include
+.. autofunction:: get_lib
+"""
+
+__all__ = ["get_include", "get_lib"]
+
+from pathlib import Path
+
+import qiskit._accelerate
+
+
+def get_include() -> str:
+    """Get the directory containing the ``qiskit.h`` C header file and the internal
+    ``qiskit/*.h`` auxiliary files.
+
+    When using Qiskit as a build dependency, you typically want to include this directory on the
+    include search path of your compiler, such as:
+
+    .. code-block:: bash
+
+        qiskit_include=$(python -c 'import qiskit.capi; print(qiskit.capi.get_include())')
+        gcc -I "$qiskit_include" my_bin.c -o my_bin
+
+    The location of this directory within the Qiskit package data is not fixed, and may change
+    between Qiskit versions.  You should always use this function to retrieve the directory.
+
+    Returns:
+        an absolute path to the package include-files directory.
+    """
+    return str(Path(__file__).parent.absolute() / "include")
+
+
+def get_lib() -> str:
+    """Get the path to a shared-object library that contains all the C-API exported symbols.
+
+    .. warning::
+        You typically *should not* link directly against this object.  In particular, directly
+        linking against this object is not a safe way to build a Python extension module that uses
+        Qiskit's C API.
+
+    You can, if you choose, use :mod:`ctypes` to access the C API symbols contained in this object,
+    though beware that the C-API types declared in the header file are not interchangeable with the
+    Python objects that correspond to them.
+
+    The location and name of this file within the Qiskit package data is not fixed, and may change
+    between Qiskit versions.
+
+    Returns:
+        an absolute path to the shared-object library containing the C-API exported symbols.
+    """
+    return str(Path(qiskit._accelerate.__file__).absolute())