Instalacja Qiskit C API

Ten przewodnik opisuje, jak zainstalować i używać Qiskit C API. Po zakończeniu instalacji przeczytaj Rozszerzanie Pythona za pomocą Qiskit C API.

Poniższy przykład buduje obserwabla w 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;
}

Systemy uniksopodobne

Ta sekcja zawiera instrukcje budowania dla systemów typu UNIX.

Wymagania

Kompilacja wymaga następujących narzędzi:

• Kompilator Rust: zapoznaj się na przykład z przewodnikiem instalacji Qiskit ze źródeł
• Kompilator C: na przykład GCC na Linuksie i Clang na MacOS. Qiskit C API jest zgodne z kompilatorem spełniającym standard C11.
• cbindgen: narzędzie do tworzenia nagłówka C, które możesz zainstalować poleceniem cargo install cbindgen Uruchamianie narzędzia z wiersza poleceń musi być włączone, co może wymagać wyeksportowania zmiennej PATH tak, aby zawierała /path/to/.cargo/bin.
• Zainstalowana biblioteka Pythona (Python 3.9+): biblioteka Pythona jest wymagana podczas dynamicznego linkowania. Zauważ, że Python nie jest używany w trakcie działania programu, a interpreter nigdy nie jest inicjalizowany; zdefiniowane muszą być jedynie niektóre symbole z libpython. Więcej szczegółów znajdziesz w tym zgłoszeniu.
• (GNU) Make: jest opcjonalne, ale zalecane do korzystania z automatycznych procesów instalacji.

Ten kod weryfikuje, czy wszystko zostało zainstalowane:

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

Budowanie

Aby zbudować nagłówek C i bibliotekę, możesz uruchomić następujące polecenie Make¹ w katalogu głównym Qiskit,

make c

co dostarczy skompilowaną bibliotekę współdzieloną w dist/c/lib oraz nagłówek qiskit.h ze wszystkimi deklaracjami funkcji w dist/c/include. Pamiętaj, że dokładna nazwa biblioteki zależy od platformy; na przykład libqiskit.so na UNIX i libqiskit.dylib na MacOS. (Zauważ, że ten krok aktualnie generuje wiele ostrzeżeń, co jest oczekiwane i nie stanowi powodu do niepokoju. Przyszłe wersje usuną te ostrzeżenia.)

Następnie możesz skompilować program w C używając nagłówka i biblioteki Qiskit C:

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

Aby upewnić się, że biblioteka Qiskit zostanie znaleziona podczas linkowania, ustaw ścieżkę biblioteki czasu wykonania tak, aby zawierała /path/to/dist/c/lib. Jeśli biblioteka Pythona nie jest domyślnie dostępna podczas dynamicznego linkowania, również należy ją dodać. Polecenia te zależą od platformy. Na Linuksie:

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

Alternatywnie możesz ustawić ścieżkę biblioteki czasu wykonania podczas kompilacji, dodając

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

do flag kompilatora. Dodatkowo, biblioteka Pythona musi być dostępna podczas dynamicznego linkowania. W środowiskach Linuksowych jest to zazwyczaj wartość domyślna.

Teraz możesz uruchomić plik binarny:

./example.o

co, jeśli używasz przykładowego fragmentu kodu pokazanego wcześniej, powinno wydrukować

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

Ta sekcja zawiera instrukcje budowania dla systemów Windows.

Istnieją dwa niezależne sposoby korzystania z C API w systemie Windows:

• Twórz moduły rozszerzeń Python, które korzystają z Qiskit C API. Wykonaj kroki 1-5. Ta ścieżka wykorzystuje nagłówki C dostarczane z pakietem Python qiskit i nie wymaga Rust ani cbindgen.

• Zbuduj samodzielną bibliotekę C, aby dołączyć ją do czystego programu w C, tak jak zostało to zrobione w sekcji UNIX-like. Wykonaj krok 1, a następnie przejdź do Build the standalone library, gdzie wymienione są jego dodatkowe wymagania.

Wymagania

• Do niektórych kroków wymagane są uprawnienia administratora.

• 5-8 GB wolnego miejsca na dysku.

• Kompilator C: Microsoft Visual C++ (MSVC), zainstalowany w kroku 1.

• 64-bitowa instalacja Pythona (3.10 lub nowszy), zainstalowana w kroku 1.

Zanim zaczniesz

Utwórz swoje środowisko robocze. Powinna to być krótka ścieżka na dysku lokalnym. Nie używaj folderów synchronizowanych przez OneDrive (takich jak Documents czy Desktop), dysków sieciowych ani ścieżek ze spacjami lub znakami spoza ASCII. Jeśli Twoja nazwa użytkownika zawiera znaki spoza alfabetu angielskiego, nie umieszczaj tego pod swoim folderem użytkownika.

Przykłady dobrych ścieżek środowiska roboczego: C:\workspace, D:\workspace, C:\Users\john\workspace

Krok 1. Instalacja wymagań wstępnych

MSVC Build Tools (kompilator C) — zainstaluj to najpierw

Jest to duże pobieranie (2-5 GB, 10-30 min). Zainstaluj to najpierw, aby od razu wiedzieć, czy Twój komputer jest kompatybilny.

uwaga

Requires administrator rights.

Opcja A — winget Otwórz terminal PowerShell i uruchom:

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

Terminal wygląda na zamrożony podczas działania instalatora. Jest to normalne i potrwa 10-30 minut. Sprawdź pasek zadań w poszukiwaniu okna „Visual Studio Installer”.

Jeśli winget nie jest rozpoznawany, zaktualizuj App Installer ze sklepu Microsoft Store lub użyj Opcji B.

Opcja B — ręczne pobieranie Otwórz stronę Visual Studio Build Tools for C++ i kliknij Download Build Tools. Uruchom plik wykonywalny, aby rozpocząć instalację.

Gdy otworzy się okno Installing Visual Studio, na karcie Workloads wybierz „Desktop development with C++”. Zobacz stronę Install C and C++ support in Visual Studio, aby uzyskać więcej szczegółów.

VS Code

Pobierz VS Code ze strony Visual Studio Code lub uruchom winget install Microsoft.VisualStudio.Code. Uruchom pobrany plik wykonywalny, aby zainstalować VS Code.

Po zainstalowaniu kontynuuj wykonując te kroki:

1. Otwórz VS Code
2. Kliknij File → Open Folder, a następnie wybierz swoje środowisko robocze (na przykład C:\workspace).
3. Kliknij Terminal → New terminal, aby otworzyć terminal PowerShell.
4. Kliknij ikonę Extensions po lewej stronie lub naciśnij Ctrl+Shift+X. W oknie Extensions wyszukaj i zainstaluj ms-python.python, ms-toolsai.jupyter oraz ms-vscode.cpptools.

Uruchamiaj pozostałe polecenia z tego przewodnika w terminalu VS Code, chyba że podano inaczej. Terminal VS Code domyślnie używa PowerShell, co zapobiega pomyłkom z wbudowanym oknem poleceń systemu Windows.

Ustaw zmienną workspace. Na przykład, jeśli Twoje środowisko robocze nazywa się workspace, uruchom:

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

Python 3.12 (zalecana wersja)

Zalecany jest Python 3.12, ponieważ ma najlepszą dostępność pakietów wheel dla qiskit-aer i innych zależności. 3.10 i 3.11 również działają, ale 3.13 lub nowsze mogą nie mieć wstępnie zbudowanych pakietów wheel dla niektórych pakietów.

Otwórz terminal VS Code i uruchom poniższy kod, aby wykryć odpowiednią wersję Pythona:

# ── 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'" }

Jeśli pobieranie nie zadziałało lub wolisz pobrać ręcznie, zakomentuj linie kodu instalujące Python 3.12, a następnie pobierz Python 3.12 ze strony Python. Uruchom plik wykonywalny, aby zainstalować Python. Podczas instalacji zaznacz „Add Python to PATH”, a następnie ponownie uruchom powyższy fragment kodu, aby upewnić się, że jest wykrywany.

Uwagi

• NIE używaj Pythona ze sklepu Microsoft Store, ponieważ brakuje mu nagłówków C. Jeśli python otwiera Microsoft Store, wyłącz alias, przechodząc do Windows Settings → Apps → Advanced app settings → App execution aliases.

• Użytkownicy Anacondy: uruchom conda deactivate, aż prefiks (base) zniknie. Jeśli nie chce zniknąć, otwórz nowy terminal w VS Code.

Git (opcjonalnie)

Potrzebne tylko, jeśli klonujesz repozytoria laboratoryjne. Uruchom winget install Git.Git.

Krok 2 - Konfiguracja wirtualnego środowiska Python z Qiskit

Zresetuj terminal VS Code

Otwórz terminal VS Code i zresetuj go:

$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'"
}

Utwórz i aktywuj wirtualne środowisko

Zezwól na wykonywanie skryptów (raz na użytkownika), a następnie utwórz wirtualne środowisko:

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

Jeśli aktywacja pokazuje czerwony błąd o „scripts disabled”, linia Set-ExecutionPolicy nie została uruchomiona. Uruchom ją ręcznie, a następnie spróbuj ponownie.

Twój prompt powinien teraz pokazywać (workspace).

Verify:

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

Zainstaluj pakiety

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 unika kompilowania qiskit-aer ze źródeł. Jeśli qiskit-aer nadal się nie udaje, spróbuj pip install qiskit-aer --only-binary=:all: lub pomiń go. qiskit-aer jest opcjonalny i jest potrzebny tylko do lokalnej symulacji.

uwaga

NIE uruchamiaj polecenia pip install --upgrade qiskit po konfiguracji. Aktualizacja do nowej wersji pomniejszej powoduje uszkodzenie rozszerzeń C zbudowanych względem starej wersji.

Krok 3 - Wczytanie środowiska MSVC

Uruchamiaj poniższy kod w każdej nowej sesji Pythona (na przykład za każdym razem, gdy restartujesz jądro Jupyter). Automatycznie lokalizuje i wczytuje środowisko deweloperskie MSVC, dzięki czemu nie potrzebujesz wbudowanego wiersza poleceń x64.

Przykład w tej dokumentacji buduje moduły rozszerzeń C, używając setuptools z MSVC. Ogólnie definiujesz QISKIT_PYTHON_EXTENSION, dołączasz qiskit.h i wywołujesz qk_import() w swojej funkcji init. W czasie kompilacji potrzebne są tylko nagłówki z qiskit.capi.get_include() — żadna biblioteka nie jest linkowana. Zobacz Extend Qiskit in Python with C, aby uzyskać szczegóły.

Wczytaj środowisko 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)

Zweryfikuj konfigurację

Zweryfikuj, że konfiguracja zadziałała:

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 — Test dymny: Zbuduj rozszerzenie C

Uruchom poniższy kod. Zapisuje on pliki źródłowe do _smoke_pkg/, buduje rozszerzenie C względem Qiskit C API i importuje wynik. Jeśli wyświetli się "SMOKE TEST PASSED", twój toolchain jest gotowy.

Pakiet jest zgodny z procesem Rozszerzanie Qiskit w Pythonie za pomocą C i wykorzystuje funkcje z dokumentacji referencyjnej Qiskit C API.

Kod testu dymnego

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 — Skonfiguruj VS Code (opcjonalnie)

Dla wygody możesz wykonać ten proces, aby skonfigurować IntelliSense dla plików C i automatycznie wybrać interpreter Pythona.

Utwórz katalog .vscode

W terminalu VS Code uruchom poniższy kod:

mkdir $WORKSPACE\.vscode -Force

Utwórz plik ustawień

Utwórz .vscode/settings.json w swoim workspace, uruchamiając ten kod:

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

Utwórz plik właściwości

Poniższy kod wyświetla JSON, który musisz wkleić 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('}')

Utwórz plik rozszerzeń VS Code

W VS Code utwórz .vscode/extensions.json z tą zawartością:

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

Zbuduj samodzielną bibliotekę

Ta sekcja buduje samodzielną bibliotekę C, która jest potrzebna tylko wtedy, gdy chcesz kompilować i linkować czyste programy C, zgodnie z opisem w sekcji UNIX-like. Oprócz wymagań wstępnych z Kroku 1, jest to wymagane dla następujących narzędzi:

• Kompilator Rust: zobacz na przykład przewodnik po instalacji Qiskit ze źródła

• cbindgen: narzędzie do tworzenia nagłówka C, które możesz zainstalować za pomocą cargo install cbindgen. Uruchamianie narzędzia z wiersza poleceń powinno być włączone, co może wymagać zaktualizowania zmiennej PATH, aby zawierała ścieżkę cargo.

• Instalacja Pythona z dostępem zarówno do python3.lib, jak i python3.dll

• Klon repozytorium Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Zbuduj samodzielną bibliotekę

Najpierw skompiluj dynamiczną bibliotekę qiskit_cext, uruchamiając poniższe polecenie w terminalu VS Code (PowerShell) w katalogu głównym Qiskit:

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

Spowoduje to wygenerowanie biblioteki dynamicznej .dll i powiązanego pliku .dll.lib w target/release. Następnie wygeneruj nagłówek poleceniem

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

Spowoduje to zapisanie nagłówka zgodnego z MSVC w dist\c\include.

Teraz możesz użyć cl do skompilowania programu w C. Aby upewnić się, że kompilator znajdzie bibliotekę qiskit, dołączamy target\release do zmiennej PATH.

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

Przed uruchomieniem dołącz ścieżkę do python3.dll.

$env:PATH = "\path\to\python3-dll;" + $env:PATH
.\example.exe

powinno następnie wydrukować

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] }

Rozwiązywanie problemów

winget nie jest rozpoznawane

Zaktualizuj App Installer ze Sklepu Microsoft Store lub użyj odpowiednich linków do ręcznego pobrania

cl nie jest rozpoznawane

Uruchom ponownie komórkę ładowania MSVC (Krok 3) lub użyj x64 Native Tools Command Prompt

python otwiera Microsoft Store

Przejdź do Ustawienia → Aplikacje → Zaawansowane ustawienia aplikacji → Aliasy wykonywania aplikacji i wyłącz python.exe

.ps1 cannot be loaded / skrypty wyłączone

Uruchom Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, a następnie spróbuj ponownie

cannot open file 'qiskit.h'

Uruchom python -c "import qiskit.capi; print(qiskit.capi.get_include())" i potwierdź, że ścieżka istnieje

qiskit.capi nie znaleziono

Uruchom pip install "qiskit[visualization]~=2.4.2"

Budowanie qiskit-aer kończy się niepowodzeniem

Uruchom pip install qiskit-aer --only-binary=:all:. Jeśli to również się nie powiedzie, użyj Pythona 3.12 lub pomiń aer, który jest opcjonalny

Budowanie działa, ale import kończy się błędem wersji

Zbudowane rozszerzenie Qiskit C i zainstalowana wersja Qiskit muszą mieć tę samą wersję. Zainstaluj ponownie Qiskit za pomocą pip install "qiskit~=2.4.2"

Przebudowałem C, ale Circuit się nie zmienił

Rozszerzenia C nie można ponownie zaimportować na żywo. Uruchom ponownie kernel, uruchom ponownie polecenia MSVC (Krok 3), a następnie zbuduj ponownie

Skrypt PowerShell został zablokowany

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Błędy długości ścieżki

Użyj krótkiej ścieżki głównej na C:\ (na przykład C:\workspace lub ścieżki ustawionej w kroku konfiguracji) albo włącz Długie ścieżki: Ustawienia → System → Dla programistów → Długie ścieżki

Conda jest aktywna (prompt pokazuje (base)) lub budowania zachowują się dziwnie po użyciu Anacondy

Uruchom conda deactivate, aż CONDA_DEFAULT_ENV i CONDA_PREFIX znikną ze środowiska. Sprawdź za pomocą $env:CONDA_PREFIX. Jeśli się utrzymują, otwórz nowy PowerShell (nie prompt Anacondy) i spróbuj ponownie od Kroku 2.

Środowisko wirtualne zostało utworzone z Pythona zarządzanego przez condę (sprawdź linię home = w .venv\pyvenv.cfg)

Środowisko wirtualne odziedziczyło środowisko wykonawcze C condy i nie można tego naprawić w miejscu. Usuń je, pobierz Pythona 3.12 ze strony Python i zbuduj ponownie. Uruchom Remove-Item -Recurse -Force .venv, a następnie uruchom ponownie fragment kodu wykrywania Pythona z Kroku 1, aby ustawić $PYTHON_EXE, a następnie utwórz środowisko wirtualne ponownie (Krok 2).

DLL load failed przy imporcie

Conda prawdopodobnie przecieka do środowiska wirtualnego. Sprawdź oba problemy bezpośrednio powyżej. Zweryfikuj również, że Python jest 64-bitowy: python -c "import platform; print(platform.architecture())"

Budowanie kończy się niepowodzeniem z zniekształconymi ścieżkami lub C1083

Twoja nazwa użytkownika lub ścieżka workspace zawiera znaki spoza ASCII. Przenieś workspace do krótkiej ścieżki zawierającej tylko ASCII (na przykład C:\workspace)

Budowanie lub import losowo się nie udaje, działa po ponownej próbie

Folder workspace jest synchronizowany przez OneDrive. Przenieś go do lokalnej ścieżki, takiej jak C:\workspace

Budowanie zostało przerwane w trakcie (na przykład wystąpiła awaria zasilania)

Usuń folder _smoke_pkg w swoim workspace, uruchom ponownie komórkę ładowania MSVC, a następnie uruchom ponownie komórkę testu dymnego

pip install kończy się niepowodzeniem z błędem certyfikatu SSL

Twoja sieć używa proxy, które przechwytuje HTTPS. Spróbuj uruchomić pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit lub poproś administratora sieci o certyfikat CA proxy

Windows Defender poddaje kwarantannie plik .pyd

Dodaj foldery .venv i _smoke_pkg swojego workspace do wykluczeń Defendera, przechodząc do Windows Security → Ochrona przed wirusami i zagrożeniami → Zarządzaj ustawieniami → Wykluczenia

Nie można zainstalować VS Build Tools (brak uprawnień administratora)

Wymagany jest dostęp administratora. Poproś dział IT o dostęp

WinError 32 / plik w użyciu podczas przebudowy

.pyd jest zablokowany przez uruchomiony kernel. Uruchom ponownie kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), uruchom ponownie Krok 3, a następnie zbuduj ponownie

Polecenia po cichu nic nie robią (brak błędu, brak wyjścia)

Możesz być w cmd.exe zamiast w PowerShell. Sprawdź swój prompt: PowerShell pokazuje PS C:\>, cmd pokazuje C:\>. Otwórz PowerShell z Menu Start lub Win+X

Instalacja MSVC wydaje się zawieszona

Flagi --passive --wait blokują PowerShell, podczas gdy instalator działa w tle. Sprawdź pasek zadań pod kątem okna "Visual Studio Installer". Instalacja może potrwać 10-30 minut

Następne kroki

Zalecenia

• Dowiedz się, jak rozszerzyć Pythona za pomocą Qiskit C API.
• Zainstaluj Qiskit.
• Zapoznaj się z dokumentacją referencyjną Qiskit C API.

Footnotes

1. Jeśli nie zainstalowałeś Make, sprawdź Makefile w katalogu głównym Qiskit, aby poznać wymagane polecenia — lub po prostu zainstaluj Make; to nie jest jeszcze za późno.) ↩