Installare la C API di Qiskit
Questa guida descrive come installare e utilizzare la C API di Qiskit. Per scoprire come estendere il tuo flusso di lavoro Python con Qiskit in C, leggi Estendere Python con la C API di Qiskit.
Il seguente esempio costruisce un observable in 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;
}
Sistemi UNIX-like​
Questa sezione fornisce le istruzioni di compilazione per i sistemi UNIX-like.
Requisiti​
La compilazione richiede i seguenti strumenti:
- Un compilatore Rust: consulta ad esempio la guida all'installazione di Qiskit dal sorgente
- Un compilatore C: ad esempio GCC su Linux e Clang su MacOS. La C API di Qiskit è compatibile con un compilatore conforme allo standard C11.
cbindgen: uno strumento per generare l'header C, installabile concargo install cbindgenNota che il tool deve essere eseguibile dalla riga di comando; potrebbe essere necessario esportare la variabilePATHper includere/path/to/.cargo/bin- Libreria Python installata (Python 3.9+): la libreria Python è necessaria durante il collegamento dinamico. Tieni presente che Python non viene utilizzato a runtime e l'interprete non viene mai inizializzato; è sufficiente che alcuni simboli di
libpythonsiano definiti. Consulta questa issue per maggiori dettagli - (GNU) Make: opzionale, ma consigliato per automatizzare il processo di installazione.
Questo codice verifica che tutto sia stato installato correttamente:
rustc --version
gcc --version
cbindgen --version
make --version # optional, but recommended
Compilazione​
Per compilare l'header C e la libreria, puoi eseguire il seguente comando Make1 nella root di Qiskit:
make c
che fornirà la libreria condivisa compilata in dist/c/lib e l'header qiskit.h con tutte le dichiarazioni delle funzioni in dist/c/include. Tieni presente che il nome esatto della libreria dipende dalla piattaforma; ad esempio libqiskit.so su UNIX e libqiskit.dylib su MacOS.
(Nota che questo passaggio attualmente emette molti warning, il che è previsto e non è motivo di preoccupazione. Le versioni future rimuoveranno i warning.)
Puoi quindi compilare un programma C utilizzando l'header e la libreria C di Qiskit:
gcc example.c -o example.o -I /path/to/dist/c/include -L /path/to/dist/c/lib -lqiskit
Per assicurarti che la libreria Qiskit venga trovata durante il collegamento, imposta il percorso della libreria a runtime in modo che includa /path/to/dist/c/lib. Se la libreria Python non è disponibile di default durante il collegamento dinamico, anche questa deve essere aggiunta. I comandi dipendono dalla piattaforma. Su 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
Su MacOS:
export DYLD_LIBRARY_PATH=/path/to/dist/c/lib:$DYLD_LIBRARY_PATH
export DYLD_LIBRARY_PATH=/path/to/python/lib:$DYLD_LIBRARY_PATH
In alternativa, puoi impostare il percorso della libreria a runtime durante la compilazione aggiungendo
-Wl,-rpath,/path/to/dist/c/lib
# same for Python
ai flag del compilatore. Inoltre, la libreria Python deve essere disponibile durante il collegamento dinamico. Negli ambienti Linux questo è tipicamente il comportamento predefinito.
Ora puoi eseguire il binario:
./example.o
che, usando il frammento di esempio mostrato in precedenza, dovrebbe stampare
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​
Questa sezione fornisce le istruzioni di compilazione per i sistemi Windows.
Requisiti​
La compilazione richiede i seguenti strumenti:
- Un compilatore Rust: consulta ad esempio la guida all'installazione di Qiskit dal sorgente
- Un compilatore C: ad esempio MSVC e il prompt dei comandi nativo che mette a disposizione il comando
cl - Un'installazione Python, con accesso sia a
python3.libche apython3.dll cbindgen: uno strumento per generare l'header C, installabile concargo install cbindgenNota che il tool deve essere eseguibile dalla riga di comando; potrebbe essere necessario aggiornare la variabilePATHper includere il percorso di cargo.
Compilazione​
Per prima cosa, compila la libreria dinamica qiskit_cext eseguendo quanto segue nella root di Qiskit:
set PATH="\path\to\pythonlib";%PATH%
cargo rustc --release --crate-type cdylib -p qiskit-cext
Questo genererà la libreria dinamica .dll e il file .dll.lib associato in target/release.
Successivamente, genera l'header con:
cbindgen --crate qiskit-cext --output dist\c\include\qiskit.h
Questo scriverà l'header compatibile con MSVC in dist\c\include.
Ora puoi usare cl per compilare il programma C. Per assicurarti che il compilatore trovi la libreria qiskit, includiamo target\release nella variabile PATH:
set PATH="\path\to\target\release";%PATH%
cl example.c qiskit_cext.dll.lib -I\path\to\dist\c\include
Prima di eseguire il programma, devi includere il percorso del tuo python3.dll:
set PATH="\path\to\python3-dll";%PATH%
.\example.exe
che dovrebbe stampare
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] }