Instalace Qiskit C API

Tento průvodce popisuje, jak nainstalovat a používat Qiskit C API. Po dokončení instalace si přečti 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;
}

Podobné Unixu

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 Spouštění nástroje z příkazové řádky by mělo být povoleno, 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 by 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.

Existují dva nezávislé způsoby, jak používat C API na Windows:

• Sestavit rozšiřující moduly Pythonu, které používají Qiskit C API. Postupuj podle kroků 1-5. Tato cesta používá C hlavičky dodávané s Python balíčkem qiskit a nevyžaduje Rust ani cbindgen.

• Sestavit samostatnou C knihovnu pro linkování z čistě C programu, tak jak je to popsáno v sekci UNIX-like. Dokonči krok 1 a poté přeskoč na Sestavení samostatné knihovny, kde jsou uvedeny její dodatečné požadavky.

Požadavky

• Pro některé kroky jsou vyžadována administrátorská práva.

• 5-8 GB volného místa na disku.

• C kompilátor: Microsoft Visual C++ (MSVC), instalovaný v kroku 1.

• 64bitová instalace Pythonu (3.10 nebo novější), instalovaná v kroku 1.

Než začneš

Vytvoř svůj pracovní prostor. Měla by to být krátká cesta na lokálním disku. Nepoužívej složky synchronizované přes OneDrive (jako Documents nebo Desktop), síťové disky ani cesty s mezerami nebo znaky mimo ASCII. Pokud tvé uživatelské jméno obsahuje neanglické znaky, neumísťuj ho pod svou uživatelskou složku.

Příklady dobrých cest k pracovnímu prostoru: C:\workspace, D:\workspace, C:\Users\john\workspace

Krok 1. Instalace předpokladů

MSVC Build Tools (C kompilátor) — nainstaluj toto jako první

Jedná se o velké stažení (2-5 GB, 10-30 min). Nainstaluj ho jako první, abys hned věděl, zda je tvůj počítač kompatibilní.

poznámka

Requires administrator rights.

Možnost A — winget Otevři terminál PowerShell a spusť následující:

winget install Microsoft.VisualStudio.2022.BuildTools --override "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended --passive --wait"

Terminál se zdá zamrzlý, zatímco instalátor běží. To je normální a bude to trvat 10-30 minut. Zkontroluj svůj hlavní panel pro okno "Visual Studio Installer".

Pokud winget není rozpoznán, aktualizuj App Installer z Microsoft Store, nebo použij Možnost B.

Možnost B — manuální stažení Otevři web Visual Studio Build Tools for C++ a klikni na Download Build Tools. Spusť spustitelný soubor pro zahájení instalace.

Když se otevře okno Installing Visual Studio, na kartě Workloads zvol "Desktop development with C++". Podrobnosti najdeš na stránce Install C and C++ support in Visual Studio.

VS Code

Stáhni si VS Code z webu Visual Studio Code, nebo spusť winget install Microsoft.VisualStudio.Code. Spusť stažený spustitelný soubor pro instalaci VS Code.

Po instalaci pokračuj těmito kroky:

1. Otevři VS Code
2. Klikni na File → Open Folder a poté vyber svůj pracovní prostor (například C:\workspace).
3. Klikni na Terminal → New terminal pro otevření terminálu PowerShell.
4. Klikni na ikonu Extensions vlevo nebo stiskni Ctrl+Shift+X. V okně Extensions vyhledej a nainstaluj ms-python.python, ms-toolsai.jupyter a ms-vscode.cpptools.

Zbytek příkazů v tomto průvodci spouštěj v terminálu VS Code, pokud není uvedeno jinak. Terminál VS Code je ve výchozím nastavení PowerShell, což zabraňuje záměně se zabudovaným příkazovým oknem Windows.

Nastav proměnnou pracovního prostoru. Pokud se například tvůj pracovní prostor jmenuje workspace, spusť následující:

$WORKSPACE = "C:\workspace"   # change to your workspace path
mkdir $WORKSPACE -Force
cd $WORKSPACE

Python 3.12 (doporučená verze)

Python 3.12 je doporučen, protože má nejlepší dostupnost wheelů pro qiskit-aer a další závislosti. 3.10 a 3.11 také fungují, ale 3.13 nebo novější může postrádat předsestavené wheely pro některé balíčky.

Otevři terminál VS Code a spusť následující kód pro detekci vhodné verze Pythonu:

# ── Pre-checks ───────────────────────────────────────────────────────────────
if ($env:CONDA_DEFAULT_ENV -or $env:CONDA_PREFIX) {
    Write-Warning "Conda is active. Run 'conda deactivate' first, or open a new terminal."
    return
}
if ($env:VIRTUAL_ENV) {
    Write-Warning "A virtual environment is active: $env:VIRTUAL_ENV — run 'deactivate' first."
    return
}

# ── Detect Python ────────────────────────────────────────────────────────────
$PYTHON_EXE = $null
try {
    $ver  = (py -3 --version 2>&1) -replace "Python ", ""
    $bits = py -3 -c "import platform; print(platform.architecture()[0])"
    $path = py -3 -c "import sys; print(sys.executable)"
    if ($path -match "(?i)(anaconda|miniconda|miniforge|mambaforge|[/\\]conda[/\\]|[/\\]envs[/\\])") {
        Write-Host "Skipping conda-managed Python at: $path"
    } elseif ([version]$ver -ge [version]"3.10" -and $bits -eq "64bit") {
        $PYTHON_EXE = $path
        Write-Host "Python $ver (64-bit) found: $PYTHON_EXE"
    } else {
        Write-Host "Skipping ($ver, $bits) — need 3.10+ 64-bit"
    }
} catch {}
if (-not $PYTHON_EXE) {
    try {
        $ver  = (python --version 2>&1) -replace "Python ", ""
        $bits = python -c "import platform; print(platform.architecture()[0])"
        $path = python -c "import sys; print(sys.executable)"
        if ($path -match "(?i)(anaconda|miniconda|miniforge|mambaforge|[/\\]conda[/\\]|[/\\]envs[/\\])") {
            Write-Host "Skipping conda-managed Python at: $path"
        } elseif ([version]$ver -ge [version]"3.10" -and $bits -eq "64bit") {
            $PYTHON_EXE = $path
            Write-Host "Python $ver (64-bit) found: $PYTHON_EXE"
        } else {
            Write-Host "Skipping ($ver, $bits) — need 3.10+ 64-bit"
        }
    } catch {}
}

# Install Python 3.12 if it wasn't found.
if (-not $PYTHON_EXE) {
    Write-Host "Not found. Installing Python 3.12..."
    winget install Python.Python.3.12
    Write-Host "Close and reopen the terminal, then rerun this snippet."
}
if ($PYTHON_EXE -and ($PYTHON_EXE -match '[^\x20-\x7E]')) {
    Write-Warning "Python path has non-ASCII characters. Keep your workspace on an ASCII path."
}
if ($PYTHON_EXE) { Write-Host "`$PYTHON_EXE = '$PYTHON_EXE'" }

Pokud stažení nefungovalo, nebo preferuješ manuální stažení, zakomentuj řádky kódu, které instalují Python 3.12, poté si stáhni Python 3.12 z webu Python. Spusť spustitelný soubor pro instalaci Pythonu. Během instalace zvol "Add Python to PATH" a poté znovu spusť výše uvedený úryvek, aby ses ujistil, že je nalezen.

Poznámky

• NEPOUŽÍVEJ Python z Microsoft Store, protože mu chybí C hlavičky. Pokud python otevře Microsoft Store, zakaž tento alias přechodem na Windows Settings → Apps → Advanced app settings → App execution aliases.

• Uživatelé Anacondy: spusť conda deactivate, dokud nezmizí předpona (base). Pokud nezmizí, otevři v VS Code nový terminál.

Git (volitelné)

Potřebné pouze pokud klonuješ repozitáře laboratoří. Spusť winget install Git.Git.

Krok 2 - Nastavení virtuálního prostředí Pythonu s Qiskit

Resetuj terminál VS Code

Otevři terminál VS Code a resetuj ho:

$WORKSPACE = "C:\workspace"   # change to your workspace path
if (-not $PYTHON_EXE) {
    if (Get-Command py -ErrorAction SilentlyContinue) { $PYTHON_EXE = py -3 -c "import sys; print(sys.executable)" }
    elseif (Get-Command python -ErrorAction SilentlyContinue) { $PYTHON_EXE = python -c "import sys; print(sys.executable)" }
    else { Write-Host "Python not found — complete Step 1.3 first." ; return }
    Write-Host "`$PYTHON_EXE = '$PYTHON_EXE'"
}

Vytvoření a aktivace virtuálního prostředí

Povol spouštění skriptů (jednou na uživatele) a poté vytvoř virtuální prostředí:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
cd $WORKSPACE
& $PYTHON_EXE -m venv .venv --prompt workspace
.\.venv\Scripts\Activate.ps1

Pokud aktivace zobrazí červenou chybu o "scripts disabled", řádek Set-ExecutionPolicy nebyl spuštěn. Spusť ho ručně a poté to zkus znovu.

Tvůj prompt by nyní měl zobrazovat (workspace).

Verify:

Get-Command python | Select-Object -First 1 -ExpandProperty Source
# → workspace\.venv\Scripts\python.exe

Instalace balíčků

python -m pip install --upgrade pip setuptools wheel
pip install "qiskit[visualization]>=2.4.2"
pip install --prefer-binary qiskit-ibm-runtime qiskit-aer
pip install notebook ipykernel ipywidgets  # optional: run the following Python steps in Jupyter

--prefer-binary zabraňuje kompilaci qiskit-aer ze zdrojového kódu. Pokud qiskit-aer stále selhává, zkus pip install qiskit-aer --only-binary=:all: nebo ho přeskoč. qiskit-aer je volitelný a je potřebný pouze pro lokální simulaci.

poznámka

Po nastavení NESPOUŠTĚJ pip install --upgrade qiskit. Upgrade na novou minor verzi rozbije C rozšíření sestavená proti té staré.

Krok 3 - Načtení prostředí MSVC

Spusť následující kód v každé nové Python session (například pokaždé, když restartuješ Jupyter kernel). Automaticky vyhledá a načte vývojářské prostředí MSVC, takže nepotřebuješ zabudovaný x64 příkazový řádek.

Příklad v této dokumentaci sestavuje rozšiřující moduly C pomocí setuptools s MSVC. Obecně definuješ QISKIT_PYTHON_EXTENSION, zahrneš qiskit.h a zavoláš qk_import() ve své init funkci. V době sestavení jsou potřeba pouze hlavičky z qiskit.capi.get_include() — žádná knihovna se nelinkuje. Podrobnosti najdeš v Rozšíření Qiskit v Pythonu pomocí C.

Načtení prostředí MSVC

import os, sys, subprocess, glob, shutil

def load_msvc_env():
    if os.name != "nt":
        return "Not Windows — the system C compiler is used as-is."
    if shutil.which("cl"):
        return "cl.exe is already available in this kernel."

    pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
    pf = os.environ.get("ProgramFiles", r"C:\Program Files")
    vcvars = None

    vswhere = os.path.join(pf86, "Microsoft Visual Studio", "Installer", "vswhere.exe")
    if os.path.isfile(vswhere):
        # vswhere outputs UTF-8 regardless of system locale
        inst = subprocess.run(
            [vswhere, "-latest", "-products", "*",
             "-requires", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
             "-property", "installationPath"],
            capture_output=True, text=True, encoding="utf-8").stdout.strip()
        if inst:
            cand = os.path.join(inst, "VC", "Auxiliary", "Build", "vcvars64.bat")
            if os.path.isfile(cand):
                vcvars = cand

    if not vcvars:
        pat = os.path.join("Microsoft Visual Studio", "*", "*",
                           "VC", "Auxiliary", "Build", "vcvars64.bat")
        hits = glob.glob(os.path.join(pf86, pat)) + glob.glob(os.path.join(pf, pat))
        if hits:
            vcvars = sorted(hits)[-1]

    if not vcvars:
        return ("Could not find vcvars64.bat. Install MSVC Build Tools (Step 1.3), "
                "or launch Jupyter from the x64 Native Tools Command Prompt.")

    # cmd.exe outputs in the OEM codepage (cp437/cp850/etc.), not the ANSI codepage
    out = subprocess.run(f'"{vcvars}" >nul 2>&1 && set',
                         capture_output=True, text=True, encoding="oem", shell=True).stdout
    for line in out.splitlines():
        if "=" in line:
            k, _, v = line.partition("=")
            os.environ[k] = v

    return ("Loaded MSVC from:\n  " + vcvars) if shutil.which("cl") \
        else "Ran vcvars64.bat but cl.exe is still not found — check your MSVC install."

print(load_msvc_env())
print("cl.exe on PATH:", shutil.which("cl") is not None)

Ověření nastavení

Ověř, že nastavení fungovalo:

import importlib.util, shutil

checks = {
    "setuptools": importlib.util.find_spec("setuptools") is not None,
    "wheel":      importlib.util.find_spec("wheel") is not None,
    "cl.exe":     shutil.which("cl") is not None,
}
for name, ok in checks.items():
    print(f"  [{'PASS' if ok else 'FAIL':>4}] {name}")

if not checks["cl.exe"]:
    print("\n  cl.exe is not on PATH. rerun the cell above to load the MSVC environment.")
elif all(checks.values()):
    print("\n  Toolchain ready. Continue to the smoke test.")

Krok 4 - Smoke test: Sestavení rozšíření C

Spusť následující kód. Zapíše zdrojové soubory do _smoke_pkg/, sestaví rozšíření C oproti Qiskit C API a importuje výsledek. Pokud vypíše "SMOKE TEST PASSED", tvůj toolchain je připraven.

Balíček se řídí procesem Rozšíření Qiskit v Pythonu pomocí C a používá funkce z referenční dokumentace Qiskit C API.

Kód smoke testu

import sys, subprocess, pathlib, importlib

root = pathlib.Path("_smoke_pkg")
pkg = root / "src" / "qgss_smoke"
pkg.mkdir(parents=True, exist_ok=True)

(root / "pyworkspace.toml").write_text("""
[build-system]
requires = ["setuptools", "qiskit>=2.4.2"]
build-backend = "setuptools.build_meta"

[workspace]
name = "qgss_smoke"
version = "0.0.1"
dependencies = ["qiskit>=2.4.2"]

[tool.setuptools]
package-dir = {"" = "src"}
""".lstrip())

(root / "setup.py").write_text("""
import qiskit
from setuptools import setup, Extension

core_ext = Extension(
    name="qgss_smoke._core",
    sources=["src/qgss_smoke/_coremodule.c"],
    include_dirs=[qiskit.capi.get_include()],
)
setup(ext_modules=[core_ext])
""".lstrip())

(pkg / "__init__.py").write_text("from . import _core\nbuild_demo = _core.build_demo\n")

(pkg / "_coremodule.c").write_text("""
#define QISKIT_PYTHON_EXTENSION
#include <Python.h>
#include <qiskit.h>
#include <stdint.h>

static PyObject *build_demo(PyObject *self, PyObject *args) {
    QkCircuit *qc = qk_circuit_new(2, 0);
    uint32_t q0[1] = {0};
    qk_circuit_gate(qc, QkGate_H, q0, NULL);
    uint32_t q1[1] = {1};
    qk_circuit_gate(qc, QkGate_X, q1, NULL);
    return qk_circuit_to_python_full(qc);
}

static PyMethodDef core_methods[] = {
    {"build_demo", build_demo, METH_NOARGS, "Build a 2-qubit demo circuit in C."},
    {NULL, NULL, 0, NULL},
};
static struct PyModuleDef core_module = {
    .m_base = PyModuleDef_HEAD_INIT,
    .m_name = "_core",
    .m_methods = core_methods,
};
PyMODINIT_FUNC PyInit__core(void) {
    if (qk_import() < 0) {
        return NULL;
    }
    return PyModuleDef_Init(&core_module);
}
""".lstrip())

# On Windows, an imported .pyd is file-locked by the OS. Drop the module from
# sys.modules BEFORE pip install --force-reinstall, otherwise pip fails with
# WinError 32 ("file in use") trying to overwrite the locked .pyd.
if "qgss_smoke._core" in sys.modules:
    del sys.modules["qgss_smoke._core"]
if "qgss_smoke" in sys.modules:
    del sys.modules["qgss_smoke"]

r = subprocess.run(
    [sys.executable, "-m", "pip", "install", "--no-build-isolation",
     "--force-reinstall", "--quiet", str(root.resolve())],
    capture_output=True, text=True,
)
if r.returncode != 0:
    output = (r.stderr + r.stdout).strip()
    print("BUILD FAILED:\n")
    print(output)
    if "WinError 32" in output or "being used by another process" in output:
        print("\n--- TIP ---")
        print("The .pyd file is locked because it was previously imported in this kernel.")
        print("Restart the kernel (Ctrl+Shift+P → 'Jupyter: Restart Kernel'), then rerun")
        print("the Step 3 MSVC cell first, then this cell again.")
    elif "cl.exe" in output.lower() or "vcvars" in output.lower() or "cannot find" in output.lower():
        print("\n--- TIP ---")
        print("The compiler was not found. rerun the Step 3 cell to load the MSVC environment.")
else:
    importlib.invalidate_caches()
    import qgss_smoke
    from qiskit import QuantumCircuit

    qc = qgss_smoke.build_demo()
    ops = dict(qc.count_ops())
    ok = isinstance(qc, QuantumCircuit) and ops.get("h") == 1 and ops.get("x") == 1

    print("Returned object is a QuantumCircuit:", isinstance(qc, QuantumCircuit))
    print("Gates built in C:", ops)
    print("\nSMOKE TEST PASSED — your Windows toolchain can build Qiskit C extensions."
          if ok else "\nSomething is off — check the gates above.")

Krok 5 — Konfigurace VS Code (volitelné)

Pro snadnější použití můžeš postupovat podle tohoto procesu, abys nastavil IntelliSense pro C soubory a automatický výběr interpretu Pythonu.

Vytvoření adresáře .vscode

V terminálu VS Code spusť následující kód:

mkdir $WORKSPACE\.vscode -Force

Vytvoření souboru nastavení

Vytvoř .vscode/settings.json ve svém pracovním prostoru spuštěním tohoto kódu:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
    "python.terminal.activateEnvironment": true,
    "jupyter.notebookFileRoot": "${workspaceFolder}"
}

Vytvoření souboru vlastností

Následující kód vypíše JSON, který musíš vložit do .vscode/c_cpp_properties.json:

import qiskit.capi

inc = qiskit.capi.get_include().replace("\\", "/")
print(".vscode/c_cpp_properties.json — create this file with the content below:\n")
print('{')
print('    "version": 4,')
print('    "configurations": [')
print('        {')
print('            "name": "Win32",')
print(f'            "includePath": ["{inc}"],')
print('            "defines": ["QISKIT_PYTHON_EXTENSION"],')
print('            "compilerPath": "cl.exe",')
print('            "cStandard": "c11",')
print('            "intelliSenseMode": "windows-msvc-x64"')
print('        }')
print('    ]')
print('}')

Vytvoření souboru rozšíření VS Code

Ve VS Code vytvoř .vscode/extensions.json s tímto obsahem:

{
    "recommendations": ["ms-python.python", "ms-toolsai.jupyter", "ms-vscode.cpptools"]
}

Sestavení samostatné knihovny

Tato sekce sestavuje samostatnou C knihovnu, která je potřebná pouze pokud chceš kompilovat a linkovat čisté C programy, jak je popsáno v sekci UNIX-like. Kromě předpokladů z kroku 1 to vyžaduje následující nástroje:

• Rust kompilátor: viz například průvodce instalací Qiskit ze zdrojového kódu

• cbindgen: nástroj pro vytvoření C hlavičkového souboru, který můžeš nainstalovat pomocí cargo install cbindgen. Spouštění nástroje z příkazové řádky by mělo být povoleno, což může vyžadovat aktualizaci proměnné PATH tak, aby zahrnovala cestu k cargo.

• Instalace Pythonu s přístupem k python3.lib i python3.dll

• Klon repozitáře Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Sestavení samostatné knihovny

Nejprve zkompiluj dynamickou knihovnu qiskit_cext spuštěním následujícího příkazu v terminálu VS Code (PowerShell) v kořenovém adresáři Qiskit:

$env:PATH = "\path\to\pythonlib;" + $env:PATH
cargo rustc --release --crate-type cdylib -p qiskit-cext

Tím se vygeneruje dynamická knihovna .dll a související 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 C programu. Aby kompilátor našel knihovnu qiskit, zahrň target\release do proměnné PATH.

$env:PATH = "\path\to\target\release;" + $env:PATH
cl example.c qiskit_cext.dll.lib -I\path\to\dist\c\include

Před spuštěním zahrň cestu ke svému souboru python3.dll.

$env:PATH = "\path\to\python3-dll;" + $env: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] }

Řešení problémů

winget není rozpoznán

Aktualizuj App Installer z Microsoft Store, nebo použij příslušné odkazy pro ruční stažení

cl není rozpoznán

Znovu spusť buňku pro načtení MSVC (Krok 3), nebo použij x64 Native Tools Command Prompt

python otevírá Microsoft Store

Přejdi do Nastavení → Aplikace → Pokročilá nastavení aplikací → Aliasy pro spouštění aplikací a vypni python.exe

.ps1 cannot be loaded / skripty zakázány

Spusť Set-ExecutionPolicy -Scope CurrentUser RemoteSigned a zkus to znovu

cannot open file 'qiskit.h'

Spusť python -c "import qiskit.capi; print(qiskit.capi.get_include())" a ověř, že cesta existuje

qiskit.capi nenalezen

Spusť pip install "qiskit[visualization]~=2.4.2"

Sestavení qiskit-aer selže

Spusť pip install qiskit-aer --only-binary=:all:. Pokud to také selže, použij Python 3.12 nebo přeskoč aer, který je volitelný

Sestavení proběhne, ale import selže s chybou verze

Sestavené C rozšíření Qiskit a nainstalovaná verze Qiskit musí mít stejnou verzi. Přeinstaluj Qiskit pomocí pip install "qiskit~=2.4.2"

Přesestavil jsem C, ale obvod se nezměnil

C rozšíření nelze znovu importovat za běhu. Restartuj kernel, znovu spusť příkazy MSVC (Krok 3) a poté znovu sestav

Skript PowerShellu byl zablokován

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Chyby délky cesty

Použij krátkou kořenovou cestu na C:\ (například C:\workspace, nebo cestu, kterou jsi nastavil v kroku nastavení), nebo povol dlouhé cesty: Nastavení → Systém → Pro vývojáře → Dlouhé cesty

Conda je aktivní (příkazový řádek zobrazuje (base)) nebo se sestavení chová podivně po použití Anacondy

Spusť conda deactivate, dokud CONDA_DEFAULT_ENV a CONDA_PREFIX nezmizí z prostředí. Ověř to pomocí $env:CONDA_PREFIX. Pokud přetrvávají, otevři nový PowerShell (ne příkazový řádek Anacondy) a zkus to znovu od Kroku 2.

Virtuální prostředí bylo vytvořeno z Pythonu spravovaného condou (zkontroluj řádek home = v souboru .venv\pyvenv.cfg)

Virtuální prostředí zdědilo C runtime condy a nelze ho opravit na místě. Smaž ho, stáhni Python 3.12 z webu Python a znovu sestav. Spusť Remove-Item -Recurse -Force .venv, poté znovu spusť úryvek pro detekci Pythonu z Kroku 1 pro nastavení $PYTHON_EXE a následně znovu vytvoř virtuální prostředí (Krok 2).

DLL load failed při importu

Conda pravděpodobně proniká do virtuálního prostředí. Zkontroluj oba problémy uvedené bezprostředně výše. Také ověř, že Python je 64bitový: python -c "import platform; print(platform.architecture())"

Sestavení selže s poškozenými cestami nebo C1083

Tvé uživatelské jméno nebo cesta k pracovnímu prostoru obsahuje jiné než ASCII znaky. Přesuň pracovní prostor na krátkou cestu obsahující pouze ASCII znaky (například C:\workspace)

Sestavení nebo import náhodně selže, při opakování funguje

Složka pracovního prostoru je synchronizována pomocí OneDrive. Přesuň ji na lokální cestu, jako je C:\workspace

Sestavení přerušeno v polovině (například kvůli výpadku napájení)

Smaž složku _smoke_pkg ve svém pracovním prostoru, znovu spusť buňku pro načtení MSVC a poté znovu spusť buňku s testem

pip install selže s chybou SSL certifikátu

Tvá síť používá proxy, která zachytává HTTPS. Zkus spustit pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit nebo požádej svého správce sítě o CA certifikát proxy

Windows Defender umístí soubor .pyd do karantény

Přidej složky .venv a _smoke_pkg svého pracovního prostoru do výjimek Defenderu tak, že přejdeš do Windows Security → Ochrana před viry a hrozbami → Spravovat nastavení → Výjimky

VS Build Tools nelze nainstalovat (chybí administrátorská práva)

Je vyžadován přístup administrátora. Požádej své IT oddělení o přístup

WinError 32 / soubor je používán během přesestavení

Soubor .pyd je uzamčen běžícím kernelem. Restartuj kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), znovu spusť Krok 3, a poté znovu sestav

Příkazy tiše nic nedělají (žádná chyba, žádný výstup)

Možná jsi v cmd.exe místo v PowerShellu. Zkontroluj svůj příkazový řádek: PowerShell zobrazuje PS C:\>, cmd zobrazuje C:\>. Otevři PowerShell z nabídky Start nebo pomocí Win+X

Zdá se, že instalace MSVC uvízla

Příznaky --passive --wait blokují PowerShell, zatímco instalátor běží na pozadí. Zkontroluj na hlavním panelu okno "Visual Studio Installer". Instalace může trvat 10-30 minut

Další kroky

Doporučení

• Nauč se, jak rozšířit Python pomocí Qiskit C API.
• Nainstaluj Qiskit.
• Prozkoumej referenční dokumentaci Qiskit C API.

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ě.) ↩