התקנת ה-C API של Qiskit

מדריך זה מסביר כיצד להתקין ולהשתמש ב-C API של Qiskit. לאחר השלמת ההתקנה, קרא את הרחבת Python עם ה-C API של Qiskit.

הדוגמה הבאה בונה 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 שלך כך שיכלול את /path/to/.cargo/bin.
• ספריית Python מותקנת (Python 3.9+): ספריית Python נדרשת במהלך קישור דינמי. שים לב ש-Python אינו בשימוש בזמן ריצה והמתרגם לעולם אינו מאותחל; רק כמה סמלים מ-libpython צריכים להיות מוגדרים. ראה בעיה זו לפרטים נוספים.
• (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.

יש שתי דרכים עצמאיות להשתמש ב-C API ב-Windows:

• בנה מודולי הרחבה של Python שמשתמשים ב-C API של Qiskit. עקוב אחר שלבים 1-5. הנתיב הזה משתמש בכותרות C (headers) שמסופקות עם חבילת ה-Python qiskit ואינו דורש Rust או cbindgen.

• בנה את ספריית ה-C העצמאית כדי לקשר אליה מתוכנית C טהורה, כפי שנעשה בסעיף דמוי-UNIX. השלם את שלב 1, ואז דלג לבניית הספרייה העצמאית, שמפרט את הדרישות הנוספות שלה.

דרישות

• נדרשות הרשאות מנהל עבור חלק מהשלבים.

• 5-8 GB שטח דיסק פנוי.

• קומפיילר C: Microsoft Visual C++‏ (MSVC), מותקן בשלב 1.

• התקנת Python בת 64-סיביות (3.10 ומעלה), מותקנת בשלב 1.

לפני שמתחילים

צור את סביבת העבודה שלך. זה צריך להיות נתיב קצר בכונן מקומי. אל תשתמש בתיקיות מסונכרנות עם OneDrive (כמו Documents או Desktop), כוננים ברשת, או נתיבים עם רווחים או תווים שאינם ASCII. אם שם המשתמש שלך מכיל תווים שאינם באנגלית, אל תמקם את סביבת העבודה תחת תיקיית המשתמש שלך.

דוגמאות לנתיבי סביבת עבודה תקינים: C:\workspace, D:\workspace, C:\Users\john\workspace

שלב 1. התקנת הדרישות המקדימות

MSVC Build Tools (מהדר C) — התקן קודם

זוהי הורדה גדולה (2-5 GB, 10-30 דקות). התקן אותה קודם כדי לדעת מיד אם המחשב שלך תואם.

הערה

Requires administrator rights.

אפשרות A — winget פתח מסוף PowerShell והרץ את הפקודה הבאה:

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

נראה שהמסוף קפא בזמן שהמתקין רץ. זה תקין ויכול לקחת 10-30 דקות. בדוק בשורת המשימות אם מופיע חלון "Visual Studio Installer".

אם winget לא מזוהה, עדכן את App Installer דרך חנות Microsoft, או השתמש באפשרות B.

אפשרות B — הורדה ידנית פתח את אתר Visual Studio Build Tools for C++ ולחץ על Download Build Tools. הרץ את קובץ ההפעלה כדי להתחיל בהתקנה.

כשנפתח חלון Installing Visual Studio, בלשונית Workloads, בחר "Desktop development with C++". ראה את העמוד Install C and C++ support in Visual Studio לפרטים נוספים.

VS Code

הורד את VS Code מהאתר Visual Studio Code, או הרץ winget install Microsoft.VisualStudio.Code. הרץ את קובץ ההפעלה שהורדת כדי להתקין את VS Code.

אחרי ההתקנה, המשך עם השלבים הבאים:

1. פתח את VS Code
2. לחץ על File → Open Folder, ואז בחר את סביבת העבודה שלך (למשל, C:\workspace).
3. לחץ על Terminal → New terminal כדי לפתוח מסוף PowerShell.
4. לחץ על סמל ה-Extensions בצד שמאל או הקש Ctrl+Shift+X. בחלון ה-Extensions, חפש והתקן את ms-python.python, ms-toolsai.jupyter, ו-ms-vscode.cpptools.

הרץ את שאר הפקודות במדריך הזה במסוף VS Code, אלא אם צוין אחרת. מסוף VS Code ברירת המחדל שלו הוא PowerShell, מה שמונע בלבול עם חלון הפקודה המובנה של Windows.

הגדר את משתנה סביבת העבודה. לדוגמה, אם סביבת העבודה שלך נקראת workspace, הרץ את הפקודה הבאה:

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

Python 3.12 (הגרסה המומלצת)

Python 3.12 מומלצת מכיוון שיש לה את זמינות ה-wheel הטובה ביותר עבור qiskit-aer ותלויות אחרות. 3.10 ו-3.11 גם עובדות, אבל 3.13 ומעלה עלולות שלא לכלול wheels בנויים מראש עבור חלק מהחבילות.

פתח את מסוף VS Code והרץ את הקוד הבא כדי לזהות גרסה מתאימה של 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'" }

אם ההורדה לא עבדה, או שאתה מעדיף הורדה ידנית, הפוך להערה את שורות הקוד שמתקינות את Python 3.12, ואז הורד את Python 3.12 מאתר Python. הרץ את קובץ ההפעלה כדי להתקין את Python. בחר "Add Python to PATH" במהלך ההתקנה, ואז הרץ מחדש את הקטע הקודם כדי לוודא שהוא נמצא.

הערות

• אל תשתמש ב-Python של חנות Microsoft כי חסרים בו קובצי C headers. אם python פותח את חנות Microsoft, השבת את ה-alias דרך Windows Settings → Apps → Advanced app settings → App execution aliases.

• למשתמשי Anaconda: הרץ conda deactivate עד שהקידומת (base) נעלמת. אם היא לא נעלמת, פתח מסוף חדש ב-VS Code.

Git (אופציונלי)

נדרש רק אם אתה משכפל מאגרי lab. הרץ winget install Git.Git.

שלב 2 - הגדרת סביבה וירטואלית של Python עם Qiskit

איפוס מסוף VS Code

פתח את מסוף VS Code ואפס אותו:

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

יצירה והפעלה של סביבה וירטואלית

אפשר הרצת סקריפטים (פעם אחת לכל משתמש), ואז צור את הסביבה הווירטואלית:

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

אם ההפעלה מציגה שגיאה אדומה על "scripts disabled", השורה Set-ExecutionPolicy לא הורצה. הרץ אותה ידנית, ואז נסה שוב.

ה-prompt שלך אמור כעת להציג (workspace).

Verify:

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

התקנת חבילות

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 מונע קומפילציה של qiskit-aer מהקוד המקור. אם qiskit-aer עדיין נכשל, נסה pip install qiskit-aer --only-binary=:all: או דלג עליו. qiskit-aer הוא אופציונלי ונדרש רק לסימולציה מקומית.

הערה

אל תריץ pip install --upgrade qiskit לאחר ההתקנה. שדרוג לגרסת משנה חדשה שובר הרחבות C שנבנו מול הגרסה הישנה.

שלב 3 - טעינת סביבת MSVC

הרץ את הקוד הבא בכל הפעלת Python חדשה (למשל, בכל פעם שאתה מפעיל מחדש kernel של Jupyter). הוא מאתר וטוען אוטומטית את סביבת המפתח של MSVC כדי שלא תזדקק לשורת הפקודה המובנית x64.

הדוגמה במסמך הזה בונה מודולי הרחבת C באמצעות setuptools עם MSVC. באופן כללי, אתה מגדיר QISKIT_PYTHON_EXTENSION, כולל את qiskit.h, וקורא ל-qk_import() בפונקציית ה-init שלך. רק הכותרות (headers) מ-qiskit.capi.get_include() נדרשות בזמן הבנייה — אין קישור (linking) של ספרייה. ראה Extend Qiskit in Python with C לפרטים.

טעינת סביבת 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)

אימות ההגדרה

וודא שההגדרה עבדה:

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

שלב 4 - בדיקת עשן: בניית הרחבת C

הרץ את הקוד הבא. הוא כותב קבצי מקור אל _smoke_pkg/, בונה הרחבת C מול Qiskit C API, ומייבא את התוצאה. אם הוא מדפיס "SMOKE TEST PASSED", ערכת הכלים שלך מוכנה.

החבילה עוקבת אחרי התהליך של Extend Qiskit in Python with C ומשתמשת בפונקציות מתוך Qiskit C API reference.

קוד בדיקת עשן

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

שלב 5 — הגדרת VS Code (אופציונלי)

לנוחות השימוש, אתה יכול לעקוב אחרי התהליך הזה כדי להגדיר IntelliSense עבור קובצי C ובחירה אוטומטית של פרשן ה-Python.

יצירת הספרייה .vscode

במסוף VS Code, הרץ את הקוד הבא:

mkdir $WORKSPACE\.vscode -Force

יצירת קובץ ההגדרות

צור את .vscode/settings.json בסביבת העבודה שלך על ידי הרצת הקוד הזה:

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

יצירת קובץ המאפיינים

הקוד הבא מדפיס את ה-JSON שאתה צריך להדביק ל-.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('}')

יצירת קובץ ההרחבות של VS Code

ב-VS Code, צור את .vscode/extensions.json עם התוכן הבא:

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

בניית הספרייה העצמאית

הסעיף הזה בונה את ספריית ה-C העצמאית, שנדרשת רק אם אתה רוצה להדר ולקשר תוכניות C טהורות, כמתואר בסעיף UNIX-like. בנוסף לדרישות המקדימות של שלב 1, זה מצריך את הכלים הבאים:

• מהדר Rust: ראה לדוגמה את המדריך להתקנת Qiskit מהקוד המקור

• cbindgen: כלי ליצירת קובץ ה-C header, שאותו אפשר להתקין עם cargo install cbindgen. יש לאפשר הרצת הכלי משורת הפקודה, מה שעשוי לדרוש עדכון של משתנה ה-PATH שלך כך שיכלול את נתיב ה-cargo.

• התקנת Python עם גישה גם ל-python3.lib וגם ל-python3.dll

• שכפול של מאגר ה-Qiskit (git clone https://github.com/Qiskit/qiskit.git)

בניית הספרייה העצמאית

ראשית, קמפל את ספריית ה-dynamic library qiskit_cext, על ידי הרצת הפקודה הבאה במסוף VS Code (PowerShell) בתוך שורש Qiskit:

$env:PATH = "\path\to\pythonlib;" + $env: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.

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

לפני ההרצה, כלול את הנתיב ל-python3.dll שלך.

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

פתרון בעיות

winget לא מזוהה

עדכן את App Installer דרך חנות Microsoft, או השתמש בקישורי ההורדה הידנית הרלוונטיים

cl לא מזוהה

הרץ מחדש את תא טעינת MSVC (שלב 3), או השתמש ב-x64 Native Tools Command Prompt

python פותח את חנות Microsoft

עבור אל Settings → Apps → Advanced app settings → App execution aliases וכבה את python.exe

.ps1 cannot be loaded / הרצת סקריפטים מושבתת

הרץ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned ואז נסה שוב

cannot open file 'qiskit.h'

הרץ python -c "import qiskit.capi; print(qiskit.capi.get_include())" ואשר שהנתיב קיים

qiskit.capi לא נמצא

הרץ pip install "qiskit[visualization]~=2.4.2"

בניית qiskit-aer נכשלת

הרץ pip install qiskit-aer --only-binary=:all:. אם גם זה נכשל, השתמש ב-Python 3.12 או דלג על aer, שהוא אופציונלי

הבנייה מצליחה אבל הייבוא נכשל עם שגיאת גרסה

הרחבת ה-C של Qiskit שנבנתה וגרסת ה-Qiskit המותקנת חייבות להיות באותה גרסה. התקן מחדש את Qiskit עם pip install "qiskit~=2.4.2"

בניתי מחדש את ה-C אבל המעגל לא השתנה

לא ניתן לייבא מחדש הרחבת C בזמן ריצה. הפעל מחדש את ה-kernel, הרץ מחדש את פקודות MSVC (שלב 3), ואז בנה מחדש

סקריפט PowerShell נחסם

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

שגיאות אורך נתיב

השתמש בנתיב שורש קצר ב-C:\ (למשל, C:\workspace, או הנתיב שקבעת בשלב ההגדרה), או הפעל Long Paths: Settings → System → For developers → Long Paths

Conda פעיל (ה-prompt מציג (base)) או שהבנייה מתנהגת בצורה משונה אחרי שימוש ב-Anaconda

הרץ conda deactivate עד ש-CONDA_DEFAULT_ENV וגם CONDA_PREFIX נעלמים לגמרי מהסביבה. בדוק עם $env:CONDA_PREFIX. אם הם ממשיכים להופיע, פתח PowerShell חדש (לא Anaconda prompt) ונסה שוב משלב 2.

הסביבה הווירטואלית נוצרה מ-Python שמנוהל על ידי conda (בדוק את השורה home = ב-.venv\pyvenv.cfg)

הסביבה הווירטואלית ירשה את סביבת ה-runtime של C מ-conda, ולא ניתן לתקן אותה כפי שהיא. מחק אותה, הורד את Python 3.12 מאתר Python, ובנה מחדש. הרץ Remove-Item -Recurse -Force .venv, ואז הרץ מחדש את קטע זיהוי ה-Python בשלב 1 כדי להגדיר את $PYTHON_EXE, ואז צור מחדש את הסביבה הווירטואלית (שלב 2).

DLL load failed בייבוא

כנראה ש-conda מדליף לתוך הסביבה הווירטואלית. בדוק את שתי הבעיות שמעל. גם ודא ש-Python הוא 64-ביט: python -c "import platform; print(platform.architecture())"

הבנייה נכשלת עם נתיבים מעוותים או C1083

שם המשתמש שלך או נתיב סביבת העבודה מכיל תווים שאינם ASCII. העבר את סביבת העבודה לנתיב קצר וב-ASCII בלבד (למשל, C:\workspace)

הבנייה או הייבוא נכשלים באופן אקראי, עובד בניסיון חוזר

תיקיית סביבת העבודה מסונכרנת על ידי OneDrive. העבר אותה לנתיב מקומי כמו C:\workspace

הבנייה הופרעה באמצע (למשל, הייתה הפסקת חשמל)

מחק את התיקייה _smoke_pkg בסביבת העבודה שלך, הרץ מחדש את תא טעינת MSVC, ואז הרץ מחדש את תא בדיקת העשן

pip install נכשל עם שגיאת אישור SSL

הרשת שלך משתמשת ב-proxy שמיירט HTTPS. נסה להרץ pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit או בקש ממנהל הרשת שלך את אישור ה-CA של ה-proxy

Windows Defender שם בהסגר את קובץ ה-.pyd

הוסף את התיקיות .venv ו-_smoke_pkg של סביבת העבודה שלך לרשימת החריגים של Defender דרך Windows Security → Virus & threat protection → Manage settings → Exclusions

לא ניתן להתקין את VS Build Tools (אין הרשאות מנהל)

נדרשת גישת מנהל מערכת. בקש גישה ממחלקת ה-IT שלך

WinError 32 / קובץ בשימוש בזמן בנייה מחדש

ה-.pyd נעול על ידי ה-kernel הפעיל. הפעל מחדש את ה-kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), הרץ מחדש את שלב 3, ואז בנה מחדש

הפקודות לא עושות כלום בשקט (בלי שגיאה, בלי פלט)

אולי אתה נמצא ב-cmd.exe במקום ב-PowerShell. בדוק את ה-prompt שלך: PowerShell מציג PS C:\>, cmd מציג C:\>. פתח PowerShell מתפריט Start או Win+X

התקנת MSVC נראית תקועה

הדגלים --passive --wait חוסמים את PowerShell בזמן שהמתקין רץ ברקע. בדוק בשורת המשימות אם מופיע חלון "Visual Studio Installer". ההתקנה יכולה לקחת 10-30 דקות

צעדים הבאים

המלצות

• למד איך להרחיב את Python עם ה-Qiskit C API.
• התקן את Qiskit.
• חקור את Qiskit C API reference.

Footnotes

1. אם לא התקנת את Make, בדוק את ה-Makefile בשורש Qiskit לאיתור הפקודות הנדרשות — או פשוט התקן את Make; עדיין לא מאוחר.) ↩