Встановлення Qiskit C API

Цей посібник описує, як встановити та використовувати Qiskit C API. Після завершення встановлення прочитай Розширення Python за допомогою Qiskit C API.

Наступний приклад будує спостережувану величину (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/to/.cargo/bin до змінної середовища PATH.
• Встановлена бібліотека Python (Python 3.9+): бібліотека Python потрібна під час динамічного компонування. Зверни увагу, що Python не використовується під час виконання і інтерпретатор ніколи не ініціалізується — лише деякі символи з libpython мають бути визначені. Дивись це issue для деталей.
• (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, що використовують Qiskit C API. Виконай кроки 1-5. Цей шлях використовує заголовки C, які постачаються з пакетом Python qiskit, і не потребує Rust або cbindgen.

• Створи автономну бібліотеку C для компонування з чистою програмою на C, як це зроблено в розділі UNIX-like. Виконай крок 1, а потім перейди до Build the standalone library, де перелічені додаткові вимоги.

Вимоги

• Для деяких кроків потрібні права адміністратора.

• 5-8 ГБ вільного місця на диску.

• Компілятор C: Microsoft Visual C++ (MSVC), встановлений на кроці 1.

• 64-бітна інсталяція Python (3.10 або новіша), встановлена на кроці 1.

Перш ніж почати

Створи свій робочий простір. Це має бути короткий шлях на локальному диску. Не використовуй папки, синхронізовані з OneDrive (такі як Documents або Desktop), мережеві диски або шляхи з пробілами чи символами, що не входять до ASCII. Якщо твоє ім'я користувача містить символи, що не входять до англійського алфавіту, не створюй робочий простір у своїй папці користувача.

Приклади гарних шляхів робочого простору: C:\workspace, D:\workspace, C:\Users\john\workspace

Крок 1. Встановлення передумов

MSVC Build Tools (компілятор C) — встанови це першим

Це великий файл для завантаження (2-5 ГБ, 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 Store, або скористайся варіантом 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 або новіші версії можуть не мати попередньо зібраних 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 Store, оскільки в ньому відсутні заголовки C. Якщо python відкриває Microsoft Store, вимкни псевдонім, перейшовши до Windows Settings → Apps → Advanced app settings → App execution aliases.

• Користувачі Anaconda: виконуй conda deactivate, поки не зникне префікс (base). Якщо він не зникає, відкрий новий термінал у VS Code.

Git (необов'язково)

Потрібно лише якщо ти клонуєш репозиторії лабораторних робіт. Виконай 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

Встановлення пакетів

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() у своїй функції ініціалізації. Під час збірки потрібні лише заголовки з 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)

Перевір налаштування

Переконайся, що налаштування спрацювало:

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 - Smoke-тест: Побудова C-розширення

Виконай наведений нижче код. Він записує вихідні файли в _smoke_pkg/, збирає C-розширення з використанням Qiskit C API і імпортує результат. Якщо виводиться "SMOKE TEST PASSED", твій набір інструментів готовий.

Пакет слідує процесу Extend Qiskit in Python with C і використовує функції з Qiskit C API reference.

Код smoke-тесту

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 Store або скористайся відповідними посиланнями для ручного завантаження

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, який є необов'язковим

Збірка проходить, але імпорт не вдається з помилкою версії

Зібране C-розширення Qiskit і встановлена версія 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 prompt) і повтори спробу з Кроку 2.

Віртуальне середовище було створено з керованого conda Python (перевір рядок 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, потім повторно виконай комірку smoke-тесту

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 не вдається встановити (немає прав адміністратора)

Потрібен доступ адміністратора. Звернись до свого IT-відділу за доступом

WinError 32 / файл використовується під час перезбирання

.pyd заблокований запущеним ядром. Перезапусти ядро (Ctrl+Shift+P → Jupyter: Restart Kernel), повторно виконай Крок 3, потім перезбери

Команди мовчки нічого не роблять (без помилки, без виводу)

Можливо, ти перебуваєш у cmd.exe замість PowerShell. Перевір своє запрошення: PowerShell показує PS C:\>, cmd показує C:\>. Відкрий PowerShell з меню Пуск або 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; ще не пізно. ↩