התקנת ה-C API של Qiskit

מדריך זה מסביר כיצד להתקין ולהשתמש ב-C API של Qiskit. כדי לראות כיצד להרחיב את תהליך העבודה שלך ב-Python עם C, קרא את הרחבת Python עם ה-C API של Qiskit.

הדוגמה הבאה בונה 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

סעיף זה מספק הוראות בנייה עבור מערכות דמויות UNIX.

דרישות

הקומפילציה דורשת את הכלים הבאים:

• קומפיילר Rust: ראה לדוגמה את המדריך להתקנת Qiskit מקוד מקור
• קומפיילר C: לדוגמה, GCC על Linux ו-Clang על MacOS. ה-C API של Qiskit תואם לקומפיילר שמציית לתקן C11.
• cbindgen: כלי ליצירת כותרת ה-C, שאותו ניתן להתקין עם cargo install cbindgen שים לב שיש לאפשר הפעלת הכלי משורת הפקודה, מה שעשוי לדרוש ייצוא משתנה ה-PATH שלך כך שיכלול את /path/to/.cargo/bin
• ספריית Python מותקנת (Python 3.9+): ספריית Python נדרשת במהלך קישור דינמי. שים לב ש-Python אינו בשימוש בזמן ריצה והמתרגם לעולם אינו מאותחל; רק כמה סמלים מ-libpython צריכים להיות מוגדרים. ראה בעיה זו לפרטים נוספים
• (GNU) Make: זה אופציונלי אך מומלץ לשימוש בתהליכי התקנה אוטומטיים.

קוד זה מאמת שהכל הותקן כראוי:

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

בנייה

כדי לבנות את כותרת ה-C והספרייה, תוכל להריץ את פקודת Make הבאה¹ בשורש Qiskit,

make c

אשר יספק את הספרייה המשותפת המקומפלת ב-dist/c/lib ואת כותרת qiskit.h עם כל הצהרות הפונקציות ב-dist/c/include. שים לב שהשם המדויק של הספרייה תלוי בפלטפורמה; לדוגמה, libqiskit.so על UNIX ו-libqiskit.dylib על MacOS. (שים לב שצעד זה פולט כרגע הרבה אזהרות, וזה צפוי ואין סיבה לדאגה. גרסאות עתידיות יסירו את האזהרות.)

לאחר מכן תוכל לקמפל תוכנית C תוך שימוש בכותרת ובספרייה של Qiskit:

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

כדי לוודא שספריית Qiskit נמצאת במהלך הקישור, הגדר את נתיב ספריית זמן הריצה כך שיכלול את /path/to/dist/c/lib. אם ספריית Python אינה זמינה כברירת מחדל במהלך קישור דינמי, גם היא צריכה להיות מוגדרת. פקודות אלה תלויות בפלטפורמה. על 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

לחלופין, תוכל להגדיר את נתיב ספריית זמן הריצה במהלך הקומפילציה על ידי הוספת

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

לדגלי הקומפיילר. בנוסף, ספריית Python צריכה להיות זמינה במהלך קישור דינמי. בסביבות Linux זה בדרך כלל ברירת המחדל.

כעת תוכל להפעיל את הקובץ הבינארי:

./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

סעיף זה מספק הוראות בנייה עבור מערכות Windows.

דרישות

הקומפילציה דורשת את הכלים הבאים:

• קומפיילר Rust: ראה לדוגמה את המדריך להתקנת Qiskit מקוד מקור
• קומפיילר C: לדוגמה, MSVC ושורת הפקודה המקומית המציעה את הפקודה cl
• התקנת Python, עם גישה הן ל-python3.lib והן ל-python3.dll
• cbindgen: כלי ליצירת כותרת ה-C, שאותו ניתן להתקין עם cargo install cbindgen שים לב שיש לאפשר הפעלת הכלי משורת הפקודה, מה שעשוי לדרוש עדכון משתנה ה-PATH שלך כך שיכלול את נתיב cargo.

בנייה

ראשית, קמפל את הספרייה הדינמית qiskit_cext על ידי הרצת הפקודות הבאות בשורש Qiskit

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

פעולה זו תיצור את הספרייה הדינמית .dll ואת קובץ .dll.lib המשויך ב-target/release. לאחר מכן, צור את הכותרת עם

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

פעולה זו תכתוב את הכותרת התואמת ל-MSVC ב-dist\c\include.

כעת תוכל להשתמש ב-cl לקמפול תוכנית ה-C. כדי לוודא שהקומפיילר מוצא את ספריית qiskit, נכלול את target\release במשתנה PATH.

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

לפני הרצה, עליך לכלול את הנתיב ל-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 לאיתור הפקודות הנדרשות — או פשוט התקן את Make; עדיין לא מאוחר.) ↩