Pasang Qiskit C API

Panduan ini menerangkan cara memasang dan menggunakan Qiskit C API. Selepas pemasangan selesai, baca Extend Python with the Qiskit C API.

Contoh berikut membina observable menggunakan 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;
}

Seperti UNIX

Bahagian ini menyediakan arahan binaan untuk sistem UNIX-like.

Keperluan

Penyusunan memerlukan alat-alat berikut:

• Pengkompil Rust: lihat contohnya panduan memasang Qiskit dari sumber
• Pengkompil C: contohnya, GCC di Linux dan Clang di MacOS. C API Qiskit serasi dengan pengkompil yang mematuhi piawaian C11.
• cbindgen: alat untuk mencipta pengepala C, yang boleh anda pasang dengan cargo install cbindgen Menjalankan alat dari baris perintah perlu diaktifkan, yang mungkin memerlukan mengeksport pemboleh ubah PATH anda untuk menyertakan /path/to/.cargo/bin.
• Pustaka Python dipasang (Python 3.9+): Pustaka Python diperlukan semasa penghubungan dinamik. Perlu diingat bahawa Python tidak digunakan semasa runtime dan penterjemah tidak pernah dimulakan; hanya beberapa simbol dari libpython perlu ditakrifkan. Lihat isu ini untuk maklumat lanjut.
• (GNU) Make: ini pilihan tetapi disyorkan untuk menggunakan proses pemasangan automatik.

Kod ini mengesahkan bahawa semua telah dipasang:

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

Binaan

Untuk membina pengepala C dan pustaka, anda boleh menjalankan arahan Make berikut¹ di direktori akar Qiskit,

make c

yang akan menyediakan pustaka kongsi yang telah dikompil di dist/c/lib dan pengepala qiskit.h dengan semua deklarasi fungsi di dist/c/include. Perhatikan bahawa nama pustaka yang tepat bergantung pada platform; contohnya, libqiskit.so di UNIX dan libqiskit.dylib di MacOS. (Perhatikan bahawa langkah ini pada masa ini mengeluarkan banyak amaran, yang dijangka, dan tidak perlu dibimbangkan. Versi masa depan akan menghapuskan amaran tersebut.)

Anda kemudian boleh mengkompil program C menggunakan pengepala dan pustaka C Qiskit:

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

Untuk memastikan pustaka Qiskit dijumpai semasa penghubungan, tetapkan laluan pustaka runtime untuk menyertakan /path/to/dist/c/lib. Jika pustaka Python tidak tersedia secara lalai semasa penghubungan dinamik, ini juga perlu ditambah. Arahan ini bergantung pada platform. Di 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

Di MacOS:

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

Sebagai alternatif, anda boleh menetapkan laluan pustaka runtime semasa penyusunan dengan menambah

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

pada bendera pengkompil. Selain itu, pustaka Python perlu tersedia semasa penghubungan dinamik. Di persekitaran Linux ini biasanya sudah menjadi lalai.

Sekarang anda boleh melaksanakan binari:

./example.o

yang, jika menggunakan petikan contoh yang ditunjukkan sebelum ini, sepatutnya mencetak

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

Bahagian ini menyediakan arahan binaan untuk sistem Windows.

Terdapat dua cara bebas untuk menggunakan C API pada Windows:

• Bina modul sambungan Python yang menggunakan Qiskit C API. Ikuti Langkah 1-5. Laluan ini menggunakan header C yang disertakan bersama pakej Python qiskit dan tidak memerlukan Rust atau cbindgen.

• Bina pustaka C tersendiri untuk dipautkan daripada program C tulen, seperti yang dilakukan dalam bahagian UNIX-like. Lengkapkan Langkah 1, kemudian langkau ke Build the standalone library, yang menyenaraikan keperluan tambahannya.

Keperluan

• Hak pentadbir diperlukan untuk sesetengah langkah.

• 5-8 GB ruang cakera bebas.

• Pengkompil C: Microsoft Visual C++ (MSVC), dipasang dalam Langkah 1.

• Pemasangan Python 64-bit (3.10 atau lebih baharu), dipasang dalam Langkah 1.

Sebelum anda bermula

Buat ruang kerja anda. Ini sepatutnya laluan pendek pada pemacu tempatan. Jangan gunakan folder yang disegerakkan OneDrive (seperti Documents atau Desktop), pemacu rangkaian, atau laluan dengan ruang atau aksara bukan-ASCII. Jika nama pengguna anda mengandungi aksara bukan-Inggeris, jangan letakkannya di bawah folder pengguna anda.

Contoh laluan ruang kerja yang baik: C:\workspace, D:\workspace, C:\Users\john\workspace

Langkah 1. Pasang prasyarat

MSVC Build Tools (C compiler) — install this first

Ini adalah muat turun yang besar (2-5 GB, 10-30 minit). Pasang ini dahulu supaya anda tahu serta-merta sama ada komputer anda serasi.

nota

Requires administrator rights.

Pilihan A — winget Buka terminal PowerShell dan jalankan yang berikut:

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

Terminal kelihatan seperti terhenti semasa pemasang berjalan. Ini adalah normal dan akan mengambil masa 10-30 minit. Semak bar tugas anda untuk tetingkap "Visual Studio Installer".

Jika winget tidak dikenali, kemas kini App Installer daripada Microsoft Store, atau gunakan Pilihan B.

Pilihan B — muat turun secara manual Buka laman Visual Studio Build Tools for C++ dan klik Download Build Tools. Jalankan fail boleh laku untuk memulakan pemasangan.

Apabila tetingkap Installing Visual Studio dibuka, pada tab Workloads, pilih "Desktop development with C++". Lihat halaman Install C and C++ support in Visual Studio untuk butiran lanjut.

VS Code

Muat turun VS Code daripada laman Visual Studio Code, atau jalankan winget install Microsoft.VisualStudio.Code. Jalankan fail boleh laku yang dimuat turun untuk memasang VS Code.

Selepas ia dipasang, teruskan dengan langkah-langkah berikut:

1. Buka VS Code
2. Klik File → Open Folder, kemudian pilih ruang kerja anda (contohnya, C:\workspace).
3. Klik Terminal → New terminal untuk membuka terminal PowerShell.
4. Klik ikon Extensions di sebelah kiri atau tekan Ctrl+Shift+X. Dalam tetingkap Extensions, cari dan pasang ms-python.python, ms-toolsai.jupyter, dan ms-vscode.cpptools.

Jalankan baki arahan dalam panduan ini dalam terminal VS Code, melainkan diarahkan sebaliknya. Terminal VS Code menggunakan PowerShell secara lalai, mengelakkan kekeliruan dengan tetingkap arahan terbina dalam Windows.

Tetapkan pembolehubah ruang kerja. Contohnya, jika ruang kerja anda dinamakan workspace, jalankan yang berikut:

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

Python 3.12 (recommended version)

Python 3.12 disyorkan kerana ia mempunyai ketersediaan wheel terbaik untuk qiskit-aer dan kebergantungan lain. 3.10 dan 3.11 juga berfungsi, tetapi 3.13 atau lebih baharu mungkin tidak mempunyai wheel pra-binaan untuk sesetengah pakej.

Buka terminal VS Code dan jalankan kod berikut untuk mengesan versi Python yang sesuai:

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

Jika muat turun tidak berjaya, atau anda lebih suka muat turun secara manual, komen baris kod yang memasang Python 3.12, kemudian muat turun Python 3.12 daripada laman Python. Jalankan fail boleh laku untuk memasang Python. Pilih "Add Python to PATH" semasa pemasangan, kemudian jalankan semula petikan di atas untuk memastikan ia dijumpai.

Notes

• JANGAN gunakan Python Microsoft Store kerana ia tidak mempunyai header C. Jika python membuka Microsoft Store, matikan alias dengan pergi ke Windows Settings → Apps → Advanced app settings → App execution aliases.

• Pengguna Anaconda: jalankan conda deactivate sehingga awalan (base) hilang. Jika ia tidak hilang, buka terminal baharu dalam VS Code.

Git (optional)

Hanya diperlukan jika anda mengklon repositori makmal. Jalankan winget install Git.Git.

Langkah 2 - Sediakan persekitaran maya Python dengan Qiskit

Reset the VS Code terminal

Buka terminal VS Code dan tetapkan semula:

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

Create and activate a virtual environment

Benarkan pelaksanaan skrip (sekali sahaja bagi setiap pengguna), kemudian buat persekitaran maya:

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

Jika pengaktifan menunjukkan ralat merah tentang "scripts disabled", baris Set-ExecutionPolicy tidak dijalankan. Jalankannya secara manual, kemudian cuba semula.

Prompt anda sepatutnya kini menunjukkan (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 mengelakkan pengkompilan qiskit-aer daripada sumber. Jika qiskit-aer masih gagal, cuba pip install qiskit-aer --only-binary=:all: atau langkau ia. qiskit-aer adalah pilihan dan hanya diperlukan untuk simulasi tempatan.

nota

JANGAN jalankan pip install --upgrade qiskit selepas persediaan. Menaik taraf kepada versi minor baharu akan merosakkan sambungan C yang dibina berdasarkan versi lama.

Langkah 3 - Muatkan persekitaran MSVC

Jalankan kod berikut dalam setiap sesi Python baharu (contohnya, setiap kali anda memulakan semula kernel Jupyter). Ia mengesan dan memuatkan persekitaran pembangun MSVC secara automatik supaya anda tidak memerlukan prompt arahan terbina dalam x64.

Contoh dalam dokumentasi ini membina modul sambungan C dengan menggunakan setuptools dengan MSVC. Secara umumnya, anda mentakrifkan QISKIT_PYTHON_EXTENSION, sertakan qiskit.h, dan panggil qk_import() dalam fungsi init anda. Hanya header daripada qiskit.capi.get_include() diperlukan semasa masa binaan — tiada pustaka dipautkan. Lihat Extend Qiskit in Python with C untuk butiran.

Load the MSVC environment

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

Sahkan bahawa persediaan berfungsi:

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

Langkah 4 - Ujian asap: Bina sambungan C

Jalankan kod berikut. Ia menulis fail sumber ke _smoke_pkg/, membina sambungan C terhadap Qiskit C API, dan mengimport hasilnya. Jika ia mencetak "SMOKE TEST PASSED", rantaian alat anda sudah sedia.

Pakej ini mengikuti proses Extend Qiskit in Python with C dan menggunakan fungsi daripada Qiskit C API reference.

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

Langkah 5 — Konfigurasikan VS Code (pilihan)

Untuk kemudahan penggunaan, kamu boleh ikut proses ini untuk menyediakan IntelliSense untuk fail C dan memilih secara automatik interpreter Python.

Buat direktori .vscode

Dalam terminal VS Code, jalankan kod berikut:

mkdir $WORKSPACE\.vscode -Force

Buat fail settings

Cipta .vscode/settings.json dalam workspace kamu dengan menjalankan kod ini:

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

Buat fail properties

Kod berikut mencetak JSON yang kamu perlu tampal ke dalam .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('}')

Buat fail sambungan VS Code

Dalam VS Code, cipta .vscode/extensions.json dengan kandungan ini:

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

Bina pustaka standalone

Bahagian ini membina pustaka C standalone, yang hanya diperlukan jika kamu mahu mengkompil dan memaut program C tulen, seperti yang diterangkan dalam bahagian UNIX-like. Selain prasyarat Langkah 1, ini memerlukan alatan berikut:

• Kompiler Rust: lihat contohnya panduan memasang Qiskit dari sumber

• cbindgen: alat untuk mencipta header C, yang boleh kamu pasang dengan cargo install cbindgen. Menjalankan alat ini dari command line perlu didayakan, yang mungkin memerlukan kamu mengemaskini pembolehubah PATH untuk memasukkan laluan cargo.

• Pemasangan Python dengan akses kepada kedua-dua python3.lib dan python3.dll

• Satu klon repositori Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Bina pustaka standalone

Pertama, kompil pustaka dinamik qiskit_cext, dengan menjalankan yang berikut dalam terminal VS Code (PowerShell) di root Qiskit:

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

Ini akan menjana pustaka dinamik .dll dan fail .dll.lib yang berkaitan di target/release. Seterusnya, jana pengepala dengan

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

Ini menulis pengepala yang serasi dengan MSVC di dist\c\include.

Sekarang anda boleh menggunakan cl untuk mengkompil program C. Untuk memastikan pengkompil menjumpai pustaka qiskit, sertakan target\release dalam pemboleh ubah PATH.

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

Sebelum menjalankan, sertakan laluan ke python3.dll anda.

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

sepatutnya mencetak

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

Penyelesaian masalah

winget is not recognized

Kemaskini App Installer dari Microsoft Store, atau gunakan pautan muat turun manual yang berkaitan

cl is not recognized

Jalankan semula sel muat MSVC (Langkah 3), atau gunakan x64 Native Tools Command Prompt

python opens Microsoft Store

Pergi ke Settings → Apps → Advanced app settings → App execution aliases dan matikan python.exe

.ps1 cannot be loaded / scripts disabled

Jalankan Set-ExecutionPolicy -Scope CurrentUser RemoteSigned kemudian cuba lagi

cannot open file 'qiskit.h'

Jalankan python -c "import qiskit.capi; print(qiskit.capi.get_include())" dan sahkan laluan itu wujud

qiskit.capi not found

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

qiskit-aer build fails

Jalankan pip install qiskit-aer --only-binary=:all:. Jika itu juga gagal, gunakan Python 3.12 atau langkau aer, yang bersifat pilihan

Build runs but import fails with a version error

Sambungan C Qiskit yang dibina dan versi Qiskit yang dipasang mesti mempunyai versi yang sama. Pasang semula Qiskit dengan pip install "qiskit~=2.4.2"

I rebuilt the C but the circuit did not change

Sambungan C tidak boleh diimport semula secara langsung. Mulakan semula kernel, jalankan semula arahan MSVC (Langkah 3), kemudian bina semula

PowerShell script was blocked

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Path length errors

Gunakan laluan root yang pendek pada C:\ (contohnya, C:\workspace, atau laluan yang kamu tetapkan dalam langkah persediaan), atau dayakan Long Paths: Settings → System → For developers → Long Paths

Conda is active (the prompt shows (base)) or builds behave oddly after using Anaconda

Jalankan conda deactivate sehingga CONDA_DEFAULT_ENV dan CONDA_PREFIX kedua-duanya hilang daripada persekitaran. Semak dengan $env:CONDA_PREFIX. Jika ia berterusan, buka PowerShell baharu (bukan Anaconda prompt) dan cuba semula dari Langkah 2.

The virtual environment was created from a conda-managed Python (check the home = line in .venv\pyvenv.cfg)

Persekitaran maya telah mewarisi runtime C conda dan tidak boleh dibetulkan di tempatnya. Padamkannya, muat turun Python 3.12 dari laman web Python, dan bina semula. Jalankan Remove-Item -Recurse -Force .venv, kemudian jalankan semula snippet pengesanan Python dalam Langkah 1 untuk menetapkan $PYTHON_EXE, kemudian cipta semula persekitaran maya (Langkah 2).

DLL load failed on import

Conda berkemungkinan bocor ke dalam persekitaran maya. Semak kedua-dua isu tepat di atas ini. Sahkan juga bahawa Python adalah 64-bit: python -c "import platform; print(platform.architecture())"

Build fails with garbled paths or C1083

Nama pengguna atau laluan workspace kamu mengandungi aksara bukan-ASCII. Pindahkan workspace ke laluan pendek ASCII sahaja (contohnya, C:\workspace)

Build or import randomly fails, works on retry

Folder workspace disegerakkan oleh OneDrive. Pindahkannya ke laluan tempatan seperti C:\workspace

Build interrupted midway (for example, there was a power loss)

Padamkan folder _smoke_pkg dalam workspace kamu, jalankan semula sel muat MSVC, kemudian jalankan semula sel ujian smoke

pip install fails with SSL certificate error

Rangkaian kamu menggunakan proxy yang memintas HTTPS. Cuba jalankan pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit atau minta pentadbir rangkaian kamu untuk sijil CA proxy

Windows Defender quarantines the .pyd file

Tambahkan folder .venv dan _smoke_pkg workspace kamu ke pengecualian Defender dengan pergi ke Windows Security → Virus & threat protection → Manage settings → Exclusions

VS Build Tools cannot be installed (no admin rights)

Akses pentadbir diperlukan. Minta jabatan IT kamu untuk akses

WinError 32 / file in use during rebuild

Fail .pyd dikunci oleh kernel yang sedang berjalan. Mulakan semula kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), jalankan semula Langkah 3, kemudian bina semula

Commands silently do nothing (no error, no output)

Kamu mungkin berada dalam cmd.exe bukannya PowerShell. Semak prompt kamu: PowerShell menunjukkan PS C:\>, cmd menunjukkan C:\>. Buka PowerShell dari Start Menu atau Win+X

MSVC install appears stuck

Bendera --passive --wait menyekat PowerShell semasa pemasang berjalan di latar belakang. Semak taskbar kamu untuk tetingkap "Visual Studio Installer". Ia boleh mengambil masa 10-30 minit untuk dipasang.

Langkah seterusnya

Recommendations

• Ketahui cara melanjutkan Python dengan Qiskit C API.
• Pasang Qiskit.
• Terokai rujukan Qiskit C API.

Footnotes

1. Jika anda tidak memasang Make, semak Makefile di direktori akar Qiskit untuk arahan yang diperlukan - atau pasang sahaja Make; masih belum terlambat.) ↩