Встановлення Qiskit C API

Цей посібник описує, як встановити та використовувати Qiskit C API. Щоб дізнатися, як розширити свій робочий процес Qiskit Python за допомогою 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-подібні системи

Цей розділ містить інструкції зі збірки для UNIX-подібних систем.

Вимоги

Для компіляції потрібні такі інструменти:

• Компілятор Rust: дивись, наприклад, посібник зі встановлення Qiskit із вихідного коду
• Компілятор C: наприклад, GCC на Linux або Clang на MacOS. C API Qiskit сумісний із компіляторами, що відповідають стандарту C11.
• cbindgen: інструмент для генерації заголовкового файлу C — встановлюється командою cargo install cbindgen Зверни увагу, що запуск інструменту з командного рядка має бути увімкнений; для цього може знадобитися додати /path/to/.cargo/bin до змінної середовища PATH
• Встановлена бібліотека Python (Python 3.9+): бібліотека Python потрібна під час динамічного компонування. Зверни увагу, що Python не використовується під час виконання і інтерпретатор ніколи не ініціалізується — лише деякі символи з libpython мають бути визначені. Дивись це issue для деталей
• (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 by 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; ще не пізно. ↩