ติดตั้ง Qiskit C API

คู่มือนี้อธิบายวิธีติดตั้งและใช้งาน Qiskit C API ถ้าอยากรู้วิธีขยาย Qiskit Python workflow ด้วย C ให้อ่าน ขยาย Python ด้วย Qiskit C API

ตัวอย่างต่อไปนี้สร้าง observable ด้วย 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

ส่วนนี้ให้คำแนะนำการ build สำหรับระบบแบบ UNIX

ข้อกำหนดเบื้องต้น

การ compile ต้องใช้เครื่องมือต่อไปนี้:

• Rust compiler: ดูตัวอย่างได้ที่ คู่มือการติดตั้ง Qiskit จากซอร์ส
• C compiler: เช่น GCC บน Linux และ Clang บน MacOS Qiskit C API รองรับ compiler ที่สอดคล้องกับมาตรฐาน C11
• cbindgen: เครื่องมือสร้าง C header ซึ่งติดตั้งได้ด้วย cargo install cbindgen โปรดตรวจสอบว่าสามารถรันคำสั่งจาก command line ได้ อาจต้องเพิ่ม /path/to/.cargo/bin ลงใน PATH
• Python library ที่ติดตั้งแล้ว (Python 3.9+): จำเป็นต้องมีในระหว่าง dynamic linking โปรดทราบว่า Python ไม่ได้ถูกใช้งานตอน runtime และ interpreter ไม่เคยถูกเริ่มต้น — ต้องการเพียงบาง symbol จาก libpython เท่านั้น ดูรายละเอียดเพิ่มเติมได้ที่ issue นี้
• (GNU) Make: ไม่จำเป็น แต่แนะนำให้ใช้สำหรับกระบวนการติดตั้งแบบอัตโนมัติ

โค้ดนี้ตรวจสอบว่าติดตั้งทุกอย่างเรียบร้อยแล้ว:

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

Build

เพื่อ build C header และ library รันคำสั่ง Make ต่อไปนี้¹ ใน Qiskit root:

make c

ซึ่งจะให้ shared library ที่ compile แล้วใน dist/c/lib และ header qiskit.h พร้อม function declaration ทั้งหมดใน dist/c/include ชื่อไฟล์ library ที่แน่นอนขึ้นอยู่กับ platform เช่น libqiskit.so บน UNIX และ libqiskit.dylib บน MacOS (หมายเหตุ: ขั้นตอนนี้จะแสดง warning จำนวนมาก ซึ่งเป็นเรื่องปกติและไม่ต้องกังวล เวอร์ชันในอนาคตจะลบ warning เหล่านี้ออก)

จากนั้น compile โปรแกรม C โดยใช้ Qiskit C header และ library:

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

เพื่อให้แน่ใจว่า Qiskit library ถูกพบในระหว่าง linking ให้กำหนด runtime library path ให้รวม /path/to/dist/c/lib ถ้า Python library ไม่พร้อมใช้งานโดยค่าเริ่มต้นในระหว่าง dynamic linking จะต้องเพิ่มเข้าไปด้วย คำสั่งเหล่านี้แตกต่างกันตาม platform บน 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

บน MacOS:

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

หรือกำหนด runtime library path ในระหว่าง compilation โดยเพิ่ม

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

เข้าใน compiler flags นอกจากนี้ Python library ต้องพร้อมใช้งานในระหว่าง dynamic linking ซึ่งโดยทั่วไปเป็นค่าเริ่มต้นในสภาพแวดล้อม Linux

ตอนนี้รัน binary ได้เลย:

./example.o

ถ้าใช้ตัวอย่างโค้ดข้างต้น จะได้ผลลัพธ์ดังนี้:

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

ส่วนนี้ให้คำแนะนำการ build สำหรับระบบ Windows

ข้อกำหนดเบื้องต้น

การ compile ต้องใช้เครื่องมือต่อไปนี้:

• Rust compiler: ดูตัวอย่างได้ที่ คู่มือการติดตั้ง Qiskit จากซอร์ส
• C compiler: เช่น MSVC และ native command prompt ที่ให้คำสั่ง cl
• Python ที่ติดตั้งแล้ว พร้อมสิทธิ์เข้าถึงทั้ง python3.lib และ python3.dll
• cbindgen: เครื่องมือสร้าง C header ซึ่งติดตั้งได้ด้วย cargo install cbindgen โปรดตรวจสอบว่าสามารถรันคำสั่งจาก command line ได้ อาจต้องอัปเดต PATH ให้รวม cargo path

Build

ก่อนอื่น compile qiskit_cext dynamic library โดยรันคำสั่งต่อไปนี้ใน Qiskit root:

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

คำสั่งนี้จะสร้าง .dll dynamic library และไฟล์ .dll.lib ที่เกี่ยวข้องใน target/release จากนั้นสร้าง header ด้วย:

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

คำสั่งนี้จะเขียน MSVC-compatible header ใน dist\c\include

ตอนนี้ใช้ cl เพื่อ compile โปรแกรม C ได้แล้ว เพื่อให้ compiler พบ qiskit library เราเพิ่ม target\release ไว้ใน PATH:

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

ก่อนรัน ต้องเพิ่ม path ของ python3.dll:

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

จะได้ผลลัพธ์:

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. ถ้าไม่ได้ติดตั้ง Make ให้ดูไฟล์ Makefile ใน Qiskit root เพื่อดูคำสั่งที่ต้องใช้ — หรือจะติดตั้ง Make ก็ยังไม่สาย ↩