Instalace Qiskit C API

Tento průvodce popisuje, jak nainstalovat a používat Qiskit C API. Pokud chceš zjistit, jak rozšířit svůj Qiskit Python workflow pomocí C, přečti si Rozšíření Pythonu pomocí Qiskit C API.

Následující příklad sestavuje observable v 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

Tato sekce obsahuje pokyny pro sestavení na systémech podobných UNIXu.

Požadavky

Kompilace vyžaduje následující nástroje:

• Kompilátor Rust: viz například průvodce instalací Qiskitu ze zdrojového kódu
• Kompilátor C: například GCC na Linuxu a Clang na MacOS. Qiskit C API je kompatibilní s kompilátorem splňujícím standard C11.
• cbindgen: nástroj pro vytvoření hlavičkového souboru C, který lze nainstalovat pomocí cargo install cbindgen Upozorňujeme, že je třeba umožnit spouštění nástroje z příkazové řádky, což může vyžadovat přidání /path/to/.cargo/bin do proměnné PATH
• Nainstalovaná Python knihovna (Python 3.9+): Python knihovna je vyžadována při dynamickém linkování. Vezmi na vědomí, že Python není používán za běhu a interpret není nikdy inicializován; je potřeba definovat pouze některé symboly z libpython. Více informací najdeš v tomto issue
• (GNU) Make: tento nástroj je volitelný, ale doporučujeme ho používat pro automatizované instalační procesy.

Tento kód ověří, že vše bylo správně nainstalováno:

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

Sestavení

Pro sestavení hlavičkového souboru C a knihovny můžeš spustit následující příkaz Make¹ v kořenovém adresáři Qiskitu,

make c

což poskytne zkompilovanou sdílenou knihovnu v dist/c/lib a hlavičkový soubor qiskit.h se všemi deklaracemi funkcí v dist/c/include. Vezmi na vědomí, že přesný název knihovny závisí na platformě; například libqiskit.so na UNIXu a libqiskit.dylib na MacOS. (Upozorňujeme, že tento krok v současné době generuje velké množství varování, což je očekávané a není důvod k obavám. Budoucí verze tato varování odstraní.)

Poté můžeš zkompilovat program v C pomocí hlavičkového souboru a knihovny Qiskit:

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

Aby bylo zajištěno, že knihovna Qiskit bude nalezena při linkování, nastav cestu ke knihovně za běhu tak, aby zahrnovala /path/to/dist/c/lib. Pokud Python knihovna není ve výchozím nastavení dostupná při dynamickém linkování, je třeba ji přidat také. Tyto příkazy závisí na platformě. Na Linuxu:

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

Na MacOS:

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

Případně můžeš nastavit cestu ke knihovně za běhu během kompilace přidáním

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

do příznaků kompilátoru. Navíc musí být Python knihovna dostupná při dynamickém linkování. V prostředích Linux je to obvykle výchozí nastavení.

Nyní můžeš spustit binární soubor:

./example.o

což by při použití výše uvedeného ukázkového fragmentu kódu mělo vypsat

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

Tato sekce obsahuje pokyny pro sestavení na systémech Windows.

Požadavky

Kompilace vyžaduje následující nástroje:

• Kompilátor Rust: viz například průvodce instalací Qiskitu ze zdrojového kódu
• Kompilátor C: například MSVC a nativní příkazový řádek nabízející příkaz cl
• Instalace Pythonu s přístupem k python3.lib i python3.dll
• cbindgen: nástroj pro vytvoření hlavičkového souboru C, který lze nainstalovat pomocí cargo install cbindgen Upozorňujeme, že je třeba umožnit spouštění nástroje z příkazové řádky, což může vyžadovat aktualizaci proměnné PATH tak, aby zahrnovala cestu ke cargo.

Sestavení

Nejprve zkompiluj dynamickou knihovnu qiskit_cext spuštěním následujícího příkazu v kořenovém adresáři Qiskitu

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

Tím se vygeneruje dynamická knihovna .dll a přidružený soubor .dll.lib v target/release. Dále vygeneruj hlavičkový soubor pomocí

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

Tím se zapíše hlavičkový soubor kompatibilní s MSVC do dist\c\include.

Nyní můžeš použít cl ke kompilaci programu v C. Aby kompilátor našel knihovnu qiskit, zahrneme target\release do proměnné PATH.

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

Před spuštěním musíš zahrnout cestu k python3.dll.

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

by pak mělo vypsat

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. Pokud jsi nenainstaloval/a Make, podívej se do souboru Makefile v kořenovém adresáři Qiskitu pro potřebné příkazy – nebo prostě Make nainstaluj; není pozdě.) ↩