Instalează Qiskit C API

Acest ghid descrie cum să instalezi și să folosești Qiskit C API. După ce instalarea este completă, citește Extinde Python cu Qiskit C API.

Următorul exemplu construiește un observabil cu 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

Această secțiune oferă instrucțiuni de compilare pentru sisteme de tip UNIX.

Cerințe

Compilarea necesită următoarele instrumente:

• Un compilator Rust: vezi de exemplu ghidul de instalare a Qiskit din sursă
• Un compilator C: de exemplu, GCC pe Linux și Clang pe MacOS. C API din Qiskit este compatibil cu un compilator conform standardului C11.
• cbindgen: un instrument pentru a crea header-ul C, pe care îl poți instala cu cargo install cbindgen Rularea instrumentului din linia de comandă trebuie să fie activată, ceea ce poate necesita exportarea variabilei PATH pentru a include /path/to/.cargo/bin.
• Bibliotecă Python instalată (Python 3.9+): Biblioteca Python este necesară în timpul legării dinamice. Reține că Python nu este utilizat la rulare și interpretorul nu este niciodată inițializat; doar unele simboluri din libpython trebuie definite. Vezi această problemă pentru mai multe detalii.
• (GNU) Make: acesta este opțional, dar este recomandat pentru a folosi procese de instalare automatizate.

Acest cod verifică dacă totul a fost instalat:

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

Compilare

Pentru a compila header-ul C și biblioteca, poți rula următoarea comandă Make¹ în rădăcina Qiskit,

make c

care va furniza biblioteca partajată compilată în dist/c/lib și header-ul qiskit.h cu toate declarațiile de funcții în dist/c/include. Reține că numele exact al bibliotecii depinde de platformă; de exemplu, libqiskit.so pe UNIX și libqiskit.dylib pe MacOS. (Reține că în prezent acest pas emite multe avertismente, ceea ce este de așteptat și nu este un motiv de îngrijorare. Versiunile viitoare vor elimina avertismentele.)

Poți apoi compila un program C folosind header-ul și biblioteca Qiskit C:

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

Pentru a te asigura că biblioteca Qiskit este găsită în timpul legării, setează calea bibliotecii de rulare să includă /path/to/dist/c/lib. Dacă biblioteca Python nu este disponibilă implicit în timpul legării dinamice, aceasta trebuie adăugată și ea. Aceste comenzi depind de platformă. Pe 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

Pe MacOS:

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

Alternativ, poți seta calea bibliotecii de rulare în timpul compilării adăugând

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

la opțiunile compilatorului. În plus, biblioteca Python trebuie să fie disponibilă în timpul legării dinamice. În mediile Linux acesta este de obicei comportamentul implicit.

Acum poți executa binarul:

./example.o

care, dacă se folosește fragmentul de exemplu prezentat anterior, ar trebui să afișeze

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

Această secțiune oferă instrucțiuni de compilare pentru sisteme Windows.

Există două moduri independente de a folosi C API pe Windows:

• Construiește module de extensie Python care folosesc Qiskit C API. Urmează Pașii 1-5. Această cale folosește antetele C livrate împreună cu pachetul Python qiskit și nu necesită Rust sau cbindgen.

• Construiește biblioteca C independentă pentru a o lega dintr-un program pur C, așa cum se face în secțiunea UNIX-like. Finalizează Pasul 1, apoi sari la Construiește biblioteca independentă, care listează cerințele sale suplimentare.

Cerințe

• Drepturile de administrator sunt necesare pentru unii pași.

• 5-8 GB spațiu liber pe disc.

• Un compilator C: Microsoft Visual C++ (MSVC), instalat la Pasul 1.

• O instalare Python pe 64 de biți (3.10 sau mai recentă), instalată la Pasul 1.

Înainte să începi

Creează-ți spațiul de lucru. Acesta ar trebui să fie o cale scurtă pe o unitate locală. Nu folosi foldere sincronizate prin OneDrive (precum Documents sau Desktop), unități de rețea sau căi cu spații sau caractere non-ASCII. Dacă numele tău de utilizator conține caractere non-englezești, nu îl pune sub folderul tău de utilizator.

Exemple de căi bune pentru spațiul de lucru: C:\workspace, D:\workspace, C:\Users\john\workspace

Pasul 1. Instalează cerințele preliminare

MSVC Build Tools (compilator C) — instalează asta mai întâi

Aceasta este o descărcare mare (2-5 GB, 10-30 min). Instalează-o mai întâi, ca să știi imediat dacă computerul tău este compatibil.

notă

Requires administrator rights.

Opțiunea A — winget Deschide un terminal PowerShell și rulează următoarele:

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

Terminalul pare blocat în timp ce rulează instalatorul. Acest lucru este normal și va dura 10-30 de minute. Verifică bara de activități pentru o fereastră "Visual Studio Installer".

Dacă winget nu este recunoscut, actualizează App Installer din Microsoft Store, sau folosește Opțiunea B.

Opțiunea B — descărcare manuală Deschide site-ul Visual Studio Build Tools for C++ și fă clic pe Download Build Tools. Rulează executabilul pentru a începe instalarea.

Când se deschide fereastra Installing Visual Studio, în fila Workloads, alege "Desktop development with C++". Consultă pagina Install C and C++ support in Visual Studio pentru mai multe detalii.

VS Code

Descarcă VS Code de pe site-ul Visual Studio Code, sau rulează winget install Microsoft.VisualStudio.Code. Rulează fișierul executabil descărcat pentru a instala VS Code.

După ce este instalat, continuă cu acești pași:

1. Deschide VS Code
2. Fă clic pe File → Open Folder, apoi selectează spațiul tău de lucru (de exemplu, C:\workspace).
3. Fă clic pe Terminal → New terminal pentru a deschide un terminal PowerShell.
4. Fă clic pe pictograma Extensions din stânga sau apasă Ctrl+Shift+X. În fereastra Extensions, caută și instalează ms-python.python, ms-toolsai.jupyter și ms-vscode.cpptools.

Rulează restul comenzilor din acest ghid în terminalul VS Code, dacă nu se indică altfel. Terminalul VS Code este implicit PowerShell, prevenind confuziile cu fereastra de comandă integrată în Windows.

Setează variabila spațiului de lucru. De exemplu, dacă spațiul tău de lucru se numește workspace, rulează următoarele:

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

Python 3.12 (versiunea recomandată)

Python 3.12 este recomandat deoarece are cea mai bună disponibilitate de wheel-uri pentru qiskit-aer și alte dependențe. 3.10 și 3.11 funcționează de asemenea, dar 3.13 sau mai recente ar putea să nu aibă wheel-uri precompilate pentru unele pachete.

Deschide terminalul VS Code și rulează următorul cod pentru a detecta o versiune potrivită de Python:

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

Dacă descărcarea nu a funcționat, sau preferi descărcarea manuală, comentează liniile de cod care instalează Python 3.12, apoi descarcă Python 3.12 de pe site-ul Python. Rulează executabilul pentru a instala Python. Selectează "Add Python to PATH" în timpul instalării, apoi rulează din nou fragmentul de mai sus pentru a te asigura că este găsit.

Note

• NU folosi Python din Microsoft Store deoarece îi lipsesc antetele C. Dacă python deschide Microsoft Store, dezactivează alias-ul mergând la Windows Settings → Apps → Advanced app settings → App execution aliases.

• Utilizatorii Anaconda: rulează conda deactivate până când prefixul (base) dispare. Dacă nu dispare, deschide un terminal nou în VS Code.

Git (opțional)

Necesar doar dacă clonezi repository-uri de laborator. Rulează winget install Git.Git.

Pasul 2 - Configurează mediul virtual Python cu Qiskit

Resetează terminalul VS Code

Deschide terminalul VS Code și resetează-l:

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

Creează și activează un mediu virtual

Permite execuția scripturilor (o dată per utilizator), apoi creează mediul virtual:

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

Dacă activarea afișează o eroare roșie despre "scripts disabled", linia Set-ExecutionPolicy nu a fost rulată. Rulează-o manual, apoi încearcă din nou.

Promptul tău ar trebui să afișeze acum (workspace).

Verify:

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

Instalează pachetele

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 evită compilarea qiskit-aer din sursă. Dacă qiskit-aer tot eșuează, încearcă pip install qiskit-aer --only-binary=:all: sau sari peste el. qiskit-aer este opțional și este necesar doar pentru simularea locală.

notă

NU rula pip install --upgrade qiskit după instalare. Actualizarea la o versiune minoră nouă rupe extensiile C construite pentru cea veche.

Pasul 3 - Încarcă mediul MSVC

Rulează următorul cod în fiecare sesiune Python nouă (de exemplu, de fiecare dată când repornești un kernel Jupyter). Acesta localizează și încarcă automat mediul de dezvoltare MSVC, astfel încât nu ai nevoie de linia de comandă încorporată x64.

Exemplul din această documentație construiește module de extensie C folosind setuptools cu MSVC. În general, definești QISKIT_PYTHON_EXTENSION, incluzi qiskit.h și apelezi qk_import() în funcția ta init. La momentul construirii sunt necesare doar antetele din qiskit.capi.get_include() — nu este legată nicio bibliotecă. Vezi Extinde Qiskit în Python cu C pentru detalii.

Încarcă mediul 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)

Verifică configurarea

Verifică dacă configurarea a funcționat:

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.")

Pasul 4 - Test rapid: construiește o extensie C

Rulează următorul cod. Acesta scrie fișierele sursă în _smoke_pkg/, construiește o extensie C folosind API-ul C Qiskit și importă rezultatul. Dacă afișează „SMOKE TEST PASSED”, lanțul tău de instrumente este pregătit.

Pachetul urmează procesul Extinde Qiskit în Python cu C și folosește funcții din referința API C Qiskit.

Cod pentru testul rapid

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.")

Pasul 5 — Configurează VS Code (opțional)

Pentru ușurință în utilizare, poți urma acest proces pentru a configura IntelliSense pentru fișiere C și a selecta automat interpretorul Python.

Creează directorul .vscode

În terminalul VS Code, rulează următorul cod:

mkdir $WORKSPACE\.vscode -Force

Creează fișierul de setări

Creează .vscode/settings.json în spațiul tău de lucru rulând acest cod:

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

Creează fișierul de proprietăți

Următorul cod afișează JSON-ul pe care trebuie să-l lipești în .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('}')

Creează fișierul de extensii VS Code

În VS Code, creează .vscode/extensions.json cu acest conținut:

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

Construiește biblioteca de sine stătătoare

Această secțiune construiește biblioteca C de sine stătătoare, care este necesară doar dacă vrei să compilezi și să legi programe C pure, așa cum este descris în secțiunea tip UNIX. Pe lângă cerințele preliminare din Pasul 1, aceasta necesită următoarele instrumente:

• Un compilator Rust: vezi de exemplu ghidul de instalare a Qiskit din sursă

• cbindgen: un instrument pentru a crea antetul C, pe care îl poți instala cu cargo install cbindgen. Rularea instrumentului din linia de comandă ar trebui să fie activată, ceea ce ar putea necesita actualizarea variabilei PATH pentru a include calea cargo.

• O instalare Python cu acces atât la python3.lib, cât și la python3.dll

• O clonă a depozitului Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Construiește biblioteca de sine stătătoare

Întâi, compilează biblioteca dinamică qiskit_cext, rulând următoarele în terminalul VS Code (PowerShell) în rădăcina Qiskit:

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

Aceasta va genera biblioteca dinamică .dll și fișierul asociat .dll.lib în target/release. Apoi, generează header-ul cu

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

Aceasta scrie header-ul compatibil MSVC în dist\c\include.

Acum poți folosi cl pentru a compila programul C. Pentru a te asigura că compilatorul găsește biblioteca qiskit, includem target\release în variabila PATH.

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

Înainte de rulare, include calea către python3.dll.

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

ar trebui apoi să afișeze

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

Depanare

winget nu este recunoscut

Actualizează App Installer din Microsoft Store, sau folosește linkurile relevante de descărcare manuală

cl nu este recunoscut

Rerulează celula de încărcare MSVC (Pasul 3), sau folosește x64 Native Tools Command Prompt

python deschide Microsoft Store

Mergi la Settings → Apps → Advanced app settings → App execution aliases și dezactivează python.exe

.ps1 cannot be loaded / scripturi dezactivate

Rulează Set-ExecutionPolicy -Scope CurrentUser RemoteSigned apoi reîncearcă

cannot open file 'qiskit.h'

Rulează python -c "import qiskit.capi; print(qiskit.capi.get_include())" și confirmă că această cale există

qiskit.capi nu este găsit

Rulează pip install "qiskit[visualization]~=2.4.2"

construirea qiskit-aer eșuează

Rulează pip install qiskit-aer --only-binary=:all:. Dacă și asta eșuează, folosește Python 3.12 sau omite aer, care este opțional

Construirea rulează, dar importul eșuează cu o eroare de versiune

Extensia C Qiskit construită și versiunea Qiskit instalată trebuie să aibă aceeași versiune. Reinstalează Qiskit cu pip install "qiskit~=2.4.2"

Am reconstruit C-ul, dar circuitul nu s-a schimbat

O extensie C nu poate fi reimportată în timp real. Repornește kernel-ul, rerulează comenzile MSVC (Pasul 3), apoi reconstruiește

Scriptul PowerShell a fost blocat

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Erori de lungime a căii

Folosește o cale rădăcină scurtă pe C:\ (de exemplu, C:\workspace, sau calea pe care ai setat-o în pasul de configurare), sau activează Long Paths: Settings → System → For developers → Long Paths

Conda este activă (promptul afișează (base)) sau construirile se comportă ciudat după utilizarea Anaconda

Rulează conda deactivate până când CONDA_DEFAULT_ENV și CONDA_PREFIX dispar amândouă din mediu. Verifică cu $env:CONDA_PREFIX. Dacă persistă, deschide un PowerShell nou (nu un prompt Anaconda) și reîncearcă de la Pasul 2.

Mediul virtual a fost creat dintr-un Python gestionat de conda (verifică linia home = din .venv\pyvenv.cfg)

Mediul virtual a moștenit mediul de rulare C al conda și nu poate fi reparat pe loc. Șterge-l, descarcă Python 3.12 de pe site-ul Python și reconstruiește. Rulează Remove-Item -Recurse -Force .venv, apoi rerulează fragmentul de detectare Python din Pasul 1 pentru a seta $PYTHON_EXE, apoi recreează mediul virtual (Pasul 2).

DLL load failed la import

Este posibil ca conda să se infiltreze în mediul virtual. Verifică ambele probleme imediat de mai sus. De asemenea, verifică dacă Python este pe 64 de biți: python -c "import platform; print(platform.architecture())"

Construirea eșuează cu căi corupte sau C1083

Numele tău de utilizator sau calea spațiului de lucru conține caractere non-ASCII. Mută spațiul de lucru într-o cale scurtă, doar ASCII (de exemplu, C:\workspace)

Construirea sau importul eșuează aleatoriu, funcționează la reîncercare

Dosarul spațiului de lucru este sincronizat de OneDrive. Mută-l într-o cale locală precum C:\workspace

Construirea a fost întreruptă pe parcurs (de exemplu, a existat o pană de curent)

Șterge dosarul _smoke_pkg din spațiul tău de lucru, rerulează celula de încărcare MSVC, apoi rerulează celula de test rapid

pip install eșuează cu o eroare de certificat SSL

Rețeaua ta folosește un proxy care interceptează HTTPS. Încearcă să rulezi pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit sau cere administratorului de rețea certificatul CA al proxy-ului

Windows Defender pune în carantină fișierul .pyd

Adaugă dosarele .venv și _smoke_pkg din spațiul tău de lucru la excluderile Defender mergând la Windows Security → Virus & threat protection → Manage settings → Exclusions

VS Build Tools nu poate fi instalat (fără drepturi de administrator)

Este necesar acces de administrator. Cere departamentului tău IT acces

WinError 32 / fișier în uz în timpul reconstruirii

Fișierul .pyd este blocat de kernel-ul care rulează. Repornește kernel-ul (Ctrl+Shift+P → Jupyter: Restart Kernel), rerulează Pasul 3, apoi reconstruiește

Comenzile nu fac nimic în mod silențios (fără eroare, fără ieșire)

Este posibil să fii în cmd.exe în loc de PowerShell. Verifică promptul tău: PowerShell afișează PS C:\>, cmd afișează C:\>. Deschide PowerShell din Start Menu sau Win+X

Instalarea MSVC pare blocată

Steagurile --passive --wait blochează PowerShell în timp ce instalatorul rulează în fundal. Verifică bara de sarcini pentru o fereastră „Visual Studio Installer”. Poate dura 10-30 de minute pentru instalare

Pașii următori

Recomandări

• Află cum să extinzi Python cu API-ul C Qiskit.
• Instalează Qiskit.
• Explorează referința API C Qiskit.

Footnotes

1. Dacă nu ai instalat Make, verifică fișierul Makefile din rădăcina Qiskit pentru comenzile necesare - sau pur și simplu instalează Make; nu e prea târziu.) ↩