Install the Qiskit C API

This guide describes how to install and use the Qiskit C API. To see how to extend your Qiskit Python workflow with C, read Extend Python with the Qiskit C API.

The following example builds an observable with C:

// file: example.c
#include <stdio.h>
#include <stdint.h>
#include <complex.h>
#include <qiskit.h>
 
int main(int argc, char* argv[]) {
    // build a 100-qubit empty observable
    u_int32_t num_qubits = 100;
    QkObs *obs = qk_obs_zero(num_qubits);
 
    // add the term 2 * (X0 Y1 Z2) to the observable
    complex double coeff = 2;  // on MSVC use: _Dcomplex coeff = {2, 0}
    QkBitTerm bit_terms[3] = {QkBitTerm_X, QkBitTerm_Y, QkBitTerm_Z};  // bit terms: X Y Z
    uint32_t indices[3] = {0, 1, 2};  // indices: 0 1 2
    QkObsTerm term = {coeff, 3, bit_terms, indices, num_qubits};
    qk_obs_add_term(obs, &term);  // append the term
 
    // print some properties and the observable itself
    printf("num_qubits: %i\n", qk_obs_num_qubits(obs));
    printf("num_terms: %lu\n", qk_obs_num_terms(obs));
    printf("observable: %s\n", qk_obs_str(obs));
 
    // free the memory allocated for the observable
    qk_obs_free(obs);
 
    return 0;
}

UNIX-like

This section provides build instructions for UNIX-like systems.

Requirements

Compilation requires the following tools:

• A Rust compiler: see for example the guide on installing Qiskit from source
• A C compiler: for example, GCC on Linux and Clang on MacOS. Qiskit's C API is compatible with a compiler conforming to the C11 standard.
• cbindgen: a tool to create the C header, which you can install with cargo install cbindgen Note that running the tool from the command line should be enabled, which might require exporting your PATH variable to include /path/to/.cargo/bin
• (GNU) Make: this is optional but is recommended to use automated install processes

This code verifies that everything has been installed:

rustc --version
gcc --version
cbindgen --version
make --version  # optional, but recommended

Build

To build the C header and library, you can run the following Make command¹ in Qiskit root,

make c

which will provide the compiled shared library in dist/c/lib and the qiskit.h header with all function declarations in dist/c/include. Note that the precise library name depends on the platform; for example,libqiskit.so on UNIX and libqiskit.dylib on MacOS. (Note that this step currently emits a lot of warnings, which is expected, and is no cause for alarm. Future versions will remove the warnings.)

You can then compile a C program using the Qiskit C header and library:

gcc example.c -o example.o -I /path/to/dist/c/include -L /path/to/dist/c/lib -lqiskit

To ensure the library is found during execution, set the runtime library path to include /path/to/dist/c/lib. This depends on the platform. On Linux:

export LD_LIBRARY_PATH=/path/to/dist/c/lib:$LD_LIBRARY_PATH

On MacOS:

export DYLD_LIBRARY_PATH=/path/to/dist/c/lib:$DYLD_LIBRARY_PATH

Alternatively, you can set the runtime library path during compilation by adding

-Wl,-rpath,/path/to/dist/c/lib

to the compiler flags.

Now you can execute the binary:

./example.o

which, if using the example snippet shown previously, should print

num_qubits: 100
num_terms: 1
observable: SparseObservable { num_qubits: 100, coeffs: [Complex { re: 2.0, im: 0.0 }], bit_terms: [X, Y, Z], indices: [0, 1, 2], boundaries: [0, 3] }

Windows

This section provides build instructions for Windows systems.

Requirements

Compilation requires the following tools:

• A Rust compiler: see for example the guide on installing Qiskit from source
• A C compiler: for example, MSVC and the native command prompt offering the cl command
• A Python installation, with access to both python3.lib and python3.dll
• cbindgen: a tool to create the C header, which you can install with cargo install cbindgen Note that running the tool from the command line should be enabled, which might require updating your PATH variable to include the cargo path.

Build

First, compile the qiskit_cext dynamic library, by running the following in Qiskit root

set PATH="\path\to\pythonlib";%PATH%
cargo rustc --release --crate-type cdylib -p qiskit-cext

This will generate the .dll dynamic library and associated .dll.lib file in target/release. Next, generate the header with

cbindgen --crate qiskit-cext --output dist\c\include\qiskit.h

This will write the MSVC-compatible header in dist\c\include.

Now you can use cl to compile the C program. To ensure the compiler finds the qiskit library, we include target\release in the PATH variable.

set PATH="\path\to\target\release";%PATH%
cl example.c qiskit_cext.dll.lib -I\path\to\dist\c\include

Before running, you have to include the path to your python3.dll.

set PATH="\path\to\python3-dll";%PATH%
.\example.exe

should then print

num_qubits: 100
num_terms: 1
observable: SparseObservable { num_qubits: 100, coeffs: [Complex { re: 2.0, im: 0.0 }], bit_terms: [X, Y, Z], indices: [0, 1, 2], boundaries: [0, 3] }