Installer l'API C de Qiskit

Ce guide décrit comment installer et utiliser l'API C de Qiskit. Pour savoir comment étendre ton workflow Python Qiskit avec du C, consulte Étendre Python avec l'API C de Qiskit.

L'exemple suivant construit un observable avec 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 et systèmes similaires

Cette section fournit les instructions de compilation pour les systèmes de type UNIX.

Prérequis

La compilation nécessite les outils suivants :

• Un compilateur Rust : consulte par exemple le guide d'installation de Qiskit depuis les sources
• Un compilateur C : par exemple, GCC sur Linux et Clang sur MacOS. L'API C de Qiskit est compatible avec un compilateur conforme à la norme C11.
• cbindgen : un outil pour créer l'en-tête C, que tu peux installer avec cargo install cbindgen Note que l'exécution de l'outil depuis la ligne de commande doit être activée, ce qui peut nécessiter d'exporter ta variable PATH pour inclure /path/to/.cargo/bin
• Bibliothèque Python installée (Python 3.9+) : la bibliothèque Python est requise lors de l'édition de liens dynamique. Note que Python n'est pas utilisé à l'exécution et que l'interpréteur n'est jamais initialisé ; seuls certains symboles de libpython doivent être définis. Consulte ce ticket pour plus de détails
• (GNU) Make : optionnel mais recommandé pour utiliser les processus d'installation automatisés.

Ce code vérifie que tout a bien été installé :

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

Compilation

Pour compiler l'en-tête C et la bibliothèque, tu peux exécuter la commande Make suivante¹ à la racine de Qiskit,

make c

ce qui fournira la bibliothèque partagée compilée dans dist/c/lib et l'en-tête qiskit.h avec toutes les déclarations de fonctions dans dist/c/include. Note que le nom précis de la bibliothèque dépend de la plateforme ; par exemple, libqiskit.so sur UNIX et libqiskit.dylib sur MacOS. (Note que cette étape émet actuellement beaucoup d'avertissements, ce qui est attendu et ne constitue pas un motif d'inquiétude. Les versions futures supprimeront ces avertissements.)

Tu peux ensuite compiler un programme C en utilisant l'en-tête et la bibliothèque C de Qiskit :

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

Pour s'assurer que la bibliothèque Qiskit est trouvée lors de l'édition de liens, configure le chemin de la bibliothèque d'exécution pour inclure /path/to/dist/c/lib. Si la bibliothèque Python n'est pas disponible par défaut lors de l'édition de liens dynamique, elle doit également être ajoutée. Ces commandes dépendent de la plateforme. Sur 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

Sur MacOS :

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

Alternativement, tu peux définir le chemin de la bibliothèque d'exécution lors de la compilation en ajoutant

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

aux options du compilateur. De plus, la bibliothèque Python doit être disponible lors de l'édition de liens dynamique. Dans les environnements Linux, c'est généralement le cas par défaut.

Tu peux maintenant exécuter le binaire :

./example.o

ce qui, si tu utilises l'exemple de code présenté précédemment, devrait afficher

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

Cette section fournit les instructions de compilation pour les systèmes Windows.

Prérequis

La compilation nécessite les outils suivants :

• Un compilateur Rust : consulte par exemple le guide d'installation de Qiskit depuis les sources
• Un compilateur C : par exemple, MSVC et l'invite de commandes native proposant la commande cl
• Une installation Python, avec accès à la fois à python3.lib et python3.dll
• cbindgen : un outil pour créer l'en-tête C, que tu peux installer avec cargo install cbindgen Note que l'exécution de l'outil depuis la ligne de commande doit être activée, ce qui peut nécessiter de mettre à jour ta variable PATH pour inclure le chemin cargo.

Compilation

D'abord, compile la bibliothèque dynamique qiskit_cext en exécutant ce qui suit à la racine de Qiskit

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

Cela générera la bibliothèque dynamique .dll et le fichier .dll.lib associé dans target/release. Ensuite, génère l'en-tête avec

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

Cela écrira l'en-tête compatible MSVC dans dist\c\include.

Tu peux maintenant utiliser cl pour compiler le programme C. Pour s'assurer que le compilateur trouve la bibliothèque qiskit, on inclut target\release dans la variable PATH.

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

Avant d'exécuter, tu dois inclure le chemin vers ta python3.dll.

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

devrait alors afficher

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. Si tu n'as pas installé Make, consulte le Makefile à la racine de Qiskit pour les commandes requises — ou installe simplement Make ; il n'est pas trop tard.) ↩