번역 미완료

이 페이지는 아직 한국어로 번역되지 않았습니다. 영어 원본을 보고 있습니다.

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 <qiskit.h>

int main(int argc, char *argv[]) {
    // build a 100-qubit empty observable
    uint32_t num_qubits = 100;
    QkObs *obs = qk_obs_zero(num_qubits);

    // add the term 2 * (X0 Y1 Z2) to the observable
    QkComplex64 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
• Python library installed (Python 3.9+): The Python library is required during dynamic linking. Notice that Python is not used at runtime and the interpreter is never initialized; only some symbols from libpython need to be defined. See this issue for more details
• (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 Qiskit library is found during linking, set the runtime library path to include /path/to/dist/c/lib. If the Python library is not available per default during dynamic linking, this also needs to be added. These commands depend on the platform. On Linux:

export LD_LIBRARY_PATH=/path/to/dist/c/lib:$LD_LIBRARY_PATH
# on Linux, the Python library is typically included in the dynamic library path per default
export LD_LIBRARY_PATH=/path/to/python/lib:$LD_LIBRARY_PATH

On MacOS:

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

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

-Wl,-rpath,/path/to/dist/c/lib
# same for Python

to the compiler flags. In addition, the Python library needs to be available during dynamic linking. In Linux environments this is typically the default.

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] }

Footnotes

1. If you did not install Make, check the Makefile in Qiskit root for the required commands - or simply install Make; it's not too late.) ↩