Instal Qiskit C API

Panduan ini menjelaskan cara menginstal dan menggunakan Qiskit C API. Untuk mengetahui cara memperluas workflow Python Qiskit dengan C, baca Extend Python with the Qiskit C API.

Contoh berikut membangun sebuah observable dengan 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

Bagian ini menyediakan instruksi build untuk sistem UNIX-like.

Persyaratan

Kompilasi membutuhkan alat-alat berikut:

• Compiler Rust: lihat misalnya panduan menginstal Qiskit dari source
• Compiler C: misalnya, GCC di Linux dan Clang di MacOS. C API Qiskit kompatibel dengan compiler yang memenuhi standar C11.
• cbindgen: alat untuk membuat C header, yang bisa kamu instal dengan cargo install cbindgen Perhatikan bahwa menjalankan alat ini dari command line harus diaktifkan, yang mungkin memerlukan ekspor variabel PATH untuk menyertakan /path/to/.cargo/bin
• Library Python terinstal (Python 3.9+): Library Python diperlukan selama dynamic linking. Perlu diperhatikan bahwa Python tidak digunakan saat runtime dan interpreter tidak pernah diinisialisasi; hanya beberapa simbol dari libpython yang perlu didefinisikan. Lihat issue ini untuk detail lebih lanjut
• (GNU) Make: ini opsional tapi direkomendasikan untuk menggunakan proses instalasi otomatis.

Kode ini memverifikasi bahwa semua sudah terinstal:

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

Build

Untuk membangun C header dan library, kamu bisa menjalankan perintah Make berikut¹ di root Qiskit,

make c

yang akan menghasilkan shared library yang telah dikompilasi di dist/c/lib dan header qiskit.h dengan semua deklarasi fungsi di dist/c/include. Perhatikan bahwa nama library yang tepat tergantung pada platform; misalnya, libqiskit.so di UNIX dan libqiskit.dylib di MacOS. (Perlu dicatat bahwa langkah ini saat ini menghasilkan banyak peringatan, yang memang diharapkan, dan bukan hal yang perlu dikhawatirkan. Versi mendatang akan menghapus peringatan tersebut.)

Kamu kemudian bisa mengompilasi program C menggunakan Qiskit C header dan library:

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

Untuk memastikan library Qiskit ditemukan selama linking, atur runtime library path untuk menyertakan /path/to/dist/c/lib. Jika library Python tidak tersedia secara default selama dynamic linking, ini juga perlu ditambahkan. Perintah-perintah ini tergantung pada platform. Di 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

Di MacOS:

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

Atau, kamu bisa mengatur runtime library path selama kompilasi dengan menambahkan

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

ke flag compiler. Selain itu, library Python perlu tersedia selama dynamic linking. Di lingkungan Linux ini biasanya sudah menjadi default.

Sekarang kamu bisa menjalankan binary:

./example.o

yang, jika menggunakan contoh snippet yang ditunjukkan sebelumnya, akan mencetak

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

Bagian ini menyediakan instruksi build untuk sistem Windows.

Persyaratan

Kompilasi membutuhkan alat-alat berikut:

• Compiler Rust: lihat misalnya panduan menginstal Qiskit dari source
• Compiler C: misalnya, MSVC dan command prompt native yang menyediakan perintah cl
• Instalasi Python, dengan akses ke python3.lib dan python3.dll
• cbindgen: alat untuk membuat C header, yang bisa kamu instal dengan cargo install cbindgen Perhatikan bahwa menjalankan alat ini dari command line harus diaktifkan, yang mungkin memerlukan pembaruan variabel PATH untuk menyertakan path cargo.

Build

Pertama, kompilasi library dinamis qiskit_cext, dengan menjalankan perintah berikut di root Qiskit

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

Ini akan menghasilkan library dinamis .dll dan file .dll.lib terkait di target/release. Selanjutnya, buat header dengan

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

Ini akan menulis header yang kompatibel dengan MSVC di dist\c\include.

Sekarang kamu bisa menggunakan cl untuk mengompilasi program C. Untuk memastikan compiler menemukan library qiskit, kita sertakan target\release di variabel PATH.

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

Sebelum menjalankan, kamu harus menyertakan path ke python3.dll.

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

seharusnya kemudian mencetak

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. Jika kamu tidak menginstal Make, cek Makefile di root Qiskit untuk perintah yang diperlukan - atau cukup instal Make; belum terlambat.) ↩