تثبيت واجهة برمجة التطبيقات C الخاصة بـ Qiskit

يصف هذا الدليل كيفية تثبيت واجهة برمجة التطبيقات C الخاصة بـ Qiskit واستخدامها. بعد اكتمال التثبيت، اقرأ توسيع Python بواجهة برمجة التطبيقات C لـ 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 لـ 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 C:

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 على Windows:

• بناء وحدات امتداد Python التي تستخدم واجهة برمجة التطبيقات C الخاصة بـ Qiskit. اتبع الخطوات من 1 إلى 5. يستخدم هذا المسار ملفات ترويسة C المرفقة مع حزمة Python الخاصة بـ qiskit ولا يتطلب Rust أو cbindgen.

• بناء مكتبة C المستقلة للربط بها من برنامج C خالص، كما يتم في القسم الشبيه بـ UNIX. أكمل الخطوة 1، ثم انتقل إلى بناء المكتبة المستقلة، التي تسرد متطلباتها الإضافية.

المتطلبات

• مطلوبة صلاحيات المسؤول لبعض الخطوات.

• مساحة قرص فارغة من 5 إلى 8 غيغابايت.

• مُصرِّف C: Microsoft Visual C++‏ (MSVC)، مثبَّت في الخطوة 1.

• تثبيت Python 64-بت (3.10 أو أحدث)، تم تثبيته في الخطوة 1.

قبل أن تبدأ

أنشئ مساحة العمل الخاصة بك. يجب أن يكون هذا مساراً قصيراً على محرك أقراص محلي. لا تستخدم المجلدات المتزامنة مع OneDrive (مثل المستندات أو سطح المكتب)، أو محركات الأقراص الشبكية، أو المسارات التي تحتوي على مسافات أو أحرف غير ASCII. إذا كان اسم المستخدم الخاص بك يحتوي على أحرف غير إنجليزية، فلا تضعه ضمن مجلد المستخدم الخاص بك.

أمثلة على مسارات مساحة عمل جيدة: C:\workspace، D:\workspace، C:\Users\john\workspace

الخطوة 1. تثبيت المتطلبات الأساسية

MSVC Build Tools (مترجم C) — ثبِّته أولاً

هذا تنزيل كبير (2-5 GB، 10-30 دقيقة). ثبِّته أولاً حتى تعرف على الفور ما إذا كان جهازك متوافقاً.

ملاحظة

Requires administrator rights.

الخيار أ — 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، أو استخدم الخيار ب.

الخيار ب — التنزيل اليدوي افتح موقع Visual Studio Build Tools for C++ وانقر على تنزيل 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 أو الأحدث إلى ملفات wheel جاهزة لبعض الحزم.

افتح طرفية 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" أثناء التثبيت، ثم أعد تشغيل المقتطف أعلاه للتأكد من العثور عليه.

Notes

• لا تستخدم Python من متجر Microsoft لأنه يفتقر إلى ملفات الترويسة C. إذا فتح python متجر Microsoft، عطِّل الاسم المستعار بالانتقال إلى Windows Settings ← Apps ← Advanced app settings ← App execution aliases.

• مستخدمو Anaconda: شغِّل conda deactivate حتى تختفي البادئة (base). إذا لم تختفِ، افتح طرفية جديدة في VS Code.

Git (optional)

مطلوب فقط إذا كنت تستنسخ مستودعات المختبر. شغِّل 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 لم يتم تشغيله. شغِّله يدوياً، ثم أعد المحاولة.

يجب أن يظهر موجه الأوامر الخاص بك الآن (workspace).

Verify:

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

Install packages

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 جديدة (على سبيل المثال، في كل مرة تعيد فيها تشغيل نواة Jupyter). يعثر على بيئة تطوير MSVC ويحمِّلها تلقائياً حتى لا تحتاج إلى موجه الأوامر المدمج x64.

يبني المثال في هذه الوثائق وحدات امتداد C باستخدام setuptools مع MSVC. بشكل عام، تعرِّف QISKIT_PYTHON_EXTENSION، وتضمِّن qiskit.h، وتستدعي qk_import() في دالة init الخاصة بك. تحتاج فقط إلى ترويسات من qiskit.capi.get_include() وقت البناء — لا يتم ربط أي مكتبة. راجع 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)

Verify the setup

تحقق من أن الإعداد نجح:

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 مرتبطاً بواجهة برمجة التطبيقات C الخاصة بـ Qiskit، ويستورد النتيجة. إذا طُبع "SMOKE TEST PASSED"، فسلسلة أدواتك جاهزة.

تتبع الحزمة عملية Extend Qiskit in Python with C وتستخدم دوال من مرجع Qiskit C API.

Smoke test code

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، يمكنك تثبيتها باستخدام cargo install cbindgen. يجب تفعيل تشغيل الأداة من سطر الأوامر، وهو ما قد يتطلب تحديث متغير PATH الخاص بك ليشمل مسار cargo.

• تثبيت Python مع إمكانية الوصول إلى كل من python3.lib وpython3.dll

• استنساخ مستودع Qiskit (git clone https://github.com/Qiskit/qiskit.git)

بناء المكتبة المستقلة

أولاً، جمِّع مكتبة 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 Store

اذهب إلى 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، وهو اختياري

يعمل البناء لكن الاستيراد يفشل بخطأ في الإصدار

يجب أن يكون امتداد Qiskit C المبني وإصدار Qiskit المثبت بنفس الإصدار. أعد تثبيت Qiskit باستخدام pip install "qiskit~=2.4.2"

أعدت بناء C لكن الدائرة لم تتغير

لا يمكن إعادة استيراد امتداد C أثناء التشغيل. أعد تشغيل النواة، وأعد تشغيل أوامر MSVC (الخطوة 3)، ثم أعد البناء

تم حظر برنامج PowerShell النصي

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

أخطاء طول المسار

استخدم مساراً جذرياً قصيراً على C:\ (على سبيل المثال، C:\workspace، أو المسار الذي حددته في خطوة الإعداد)، أو فعِّل Long Paths: Settings ← System ← For developers ← Long Paths

Conda نشطة (يظهر في الموجه (base)) أو تتصرف عمليات البناء بغرابة بعد استخدام Anaconda

شغِّل conda deactivate حتى تختفي كل من CONDA_DEFAULT_ENV وCONDA_PREFIX من البيئة. تحقق باستخدام $env:CONDA_PREFIX. إذا استمرت، افتح PowerShell جديدة (وليست موجه Anaconda) وأعد المحاولة من الخطوة 2.

أُنشئت البيئة الافتراضية من Python تديره conda (تحقق من السطر home = في .venv\pyvenv.cfg)

ورثت البيئة الافتراضية بيئة تشغيل 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

تستخدم شبكتك وكيلاً يعترض HTTPS. جرِّب تشغيل pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit أو اطلب من مسؤول الشبكة شهادة CA الخاصة بالوكيل

يضع Windows Defender ملف .pyd في الحجر الصحي

أضف مجلدي .venv و_smoke_pkg في مساحة العمل الخاصة بك إلى استثناءات Defender بالانتقال إلى Windows Security ← Virus & threat protection ← Manage settings ← Exclusions

لا يمكن تثبيت VS Build Tools (لا توجد صلاحيات مسؤول)

مطلوب وصول المسؤول. اطلب من قسم تقنية المعلومات لديك الوصول

WinError 32 / الملف قيد الاستخدام أثناء إعادة البناء

ملف .pyd مقفل من قبل النواة قيد التشغيل. أعد تشغيل النواة (Ctrl+Shift+P ← Jupyter: Restart Kernel)، وأعد تشغيل الخطوة 3، ثم أعد البناء

الأوامر لا تفعل شيئاً بصمت (لا خطأ ولا مخرجات)

قد تكون في cmd.exe بدلاً من PowerShell. تحقق من موجه الأوامر الخاص بك: يظهر PowerShell PS C:\>، ويظهر cmd C:\>. افتح PowerShell من قائمة Start أو Win+X

يبدو أن تثبيت MSVC متوقف

تحجب علامتا --passive --wait PowerShell أثناء تشغيل المثبِّت في الخلفية. تحقق من شريط المهام الخاص بك بحثاً عن نافذة "Visual Studio Installer". قد يستغرق التثبيت 10-30 دقيقة

الخطوات التالية

Recommendations

• تعرَّف على كيفية توسيع Python باستخدام Qiskit C API.
• تثبيت Qiskit.
• استكشف مرجع Qiskit C API.

Footnotes

1. إن لم تثبت Make، اطلع على ملف Makefile في المجلد الجذر لـ Qiskit للاطلاع على الأوامر المطلوبة - أو ثبِّت Make ببساطة؛ لم يفت الأوان بعد. ↩