C API interface from Python
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.
Build-system interaction
The Python package 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 get_include() and get_lib() respectively.
You typically should not link directly against the output of 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.
get_include
qiskit.capi.get_include()
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:
qiskit_include=$(python -c 'import qiskit.capi; print(qiskit.capi.get_include())')
gcc -I "$qiskit_include" my_bin.c -o my_binThe 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 type
get_lib
qiskit.capi.get_lib()
Get the path to a shared-object library that contains all the C-API exported symbols.
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 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 type
Native bindings to the C API
Additionally, this module contains ctypes bindings to all Qiskit C API types and functions. These are available as module attributes on qiskit.capi with the same name as they have in the C API. For example, qiskit.capi.qk_circuit_new corresponds to qk_circuit_new().
qiskit.capi.LIB
Type: ctypes.PyDLL
A ctypes wrapper around the library containing the Qiskit C API.
This is provided for completeness, though you can access all the functions, structs and enumerations directly from the qiskit.capi module object.
Structs
Concrete struct types used in the C API are declared as corresponding ctypes.Structure types with a complete _fields_ attribute. These can be instantiated and inspected directly.
Opaque pointers are represented by a ctypes.Structure type with no _fields_ attribute set, and cannot be instantiated. They are typically returned from functions wrapped in a ctypes.POINTER type wrapper.
Enums
In places where the C API has an enumeration, this module declares a Python enum.Enum whose values are a corresponding ctypes primitive integer type. The Python-space Enum type object is still a wrapping Python object, so ctypes functions that return an enumeration will return the raw numeric value, not the value in the Enum. The Python-space Enum objects are declared for convenience in constructing calls.
Functions
All the public library functions in the Qiskit C API are fully typed, and re-exported in the module root with the same name as they have in C. You can also access the functions from LIB, if you prefer.
Note that header-only functions, such as qk_import(), are not exported because they are not part of the C API library object.