Instal Qiskit C API

Panduan ini menjelaskan cara menginstal dan menggunakan Qiskit C API. Setelah instalasi selesai, baca Extend Python with the Qiskit C API.

Contoh berikut membangun sebuah observable dengan 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;
}

Mirip UNIX

Bagian ini menyediakan instruksi build untuk sistem Mirip UNIX.

Persyaratan

Kompilasi membutuhkan alat-alat berikut:

• Compiler Rust: lihat misalnya panduan menginstal Qiskit dari source
• Compiler C: misalnya, GCC di Linux dan Clang di MacOS. C API Qiskit kompatibel dengan compiler yang memenuhi standar C11.
• cbindgen: alat untuk membuat C header, yang bisa kamu instal dengan cargo install cbindgen Menjalankan alat ini dari command line harus diaktifkan, yang mungkin memerlukan ekspor variabel PATH untuk menyertakan /path/to/.cargo/bin.
• Library Python terinstal (Python 3.9+): Library Python diperlukan selama dynamic linking. Perlu diperhatikan bahwa Python tidak digunakan saat runtime dan interpreter tidak pernah diinisialisasi; hanya beberapa simbol dari libpython yang perlu didefinisikan. Lihat issue ini untuk detail lebih lanjut.
• (GNU) Make: ini opsional tapi direkomendasikan untuk menggunakan proses instalasi otomatis.

Kode ini memverifikasi bahwa semua sudah terinstal:

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

Build

Untuk membangun C header dan library, kamu bisa menjalankan perintah Make berikut¹ di root Qiskit,

make c

yang akan menghasilkan shared library yang telah dikompilasi di dist/c/lib dan header qiskit.h dengan semua deklarasi fungsi di dist/c/include. Perhatikan bahwa nama library yang tepat tergantung pada platform; misalnya, libqiskit.so di UNIX dan libqiskit.dylib di MacOS. (Perlu dicatat bahwa langkah ini saat ini menghasilkan banyak peringatan, yang memang diharapkan, dan bukan hal yang perlu dikhawatirkan. Versi mendatang akan menghapus peringatan tersebut.)

Kamu kemudian bisa mengompilasi program C menggunakan Qiskit C header dan library:

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

Untuk memastikan library Qiskit ditemukan selama linking, atur runtime library path untuk menyertakan /path/to/dist/c/lib. Jika library Python tidak tersedia secara default selama dynamic linking, ini juga perlu ditambahkan. Perintah-perintah ini tergantung 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

Atau, kamu bisa mengatur runtime library path selama kompilasi dengan menambahkan

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

ke flag compiler. Selain itu, library Python perlu tersedia selama dynamic linking. Di lingkungan Linux ini biasanya sudah menjadi default.

Sekarang kamu bisa menjalankan binary:

./example.o

yang, jika menggunakan contoh snippet yang ditunjukkan sebelumnya, akan 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

Bagian ini menyediakan instruksi build untuk sistem Windows.

Ada dua cara independen untuk menggunakan C API di Windows:

• Bangun modul ekstensi Python yang menggunakan Qiskit C API. Ikuti Langkah 1-5. Cara ini menggunakan header C yang disertakan dengan paket Python qiskit dan tidak memerlukan Rust atau cbindgen.

• Bangun library C standalone untuk di-link dari program C murni, seperti yang dilakukan pada bagian Mirip UNIX. Selesaikan Langkah 1, lalu lanjut ke Build the standalone library, yang mencantumkan persyaratan tambahannya.

Persyaratan

• Hak administrator diperlukan untuk beberapa langkah.

• Ruang disk kosong 5-8 GB.

• Kompiler C: Microsoft Visual C++ (MSVC), diinstal di Langkah 1.

• Instalasi Python 64-bit (3.10 atau yang lebih baru), diinstal di Langkah 1.

Sebelum kamu mulai

Buat workspace kamu. Ini sebaiknya berupa path pendek pada drive lokal. Jangan gunakan folder yang disinkronkan dengan OneDrive (seperti Documents atau Desktop), drive jaringan, atau path dengan spasi atau karakter non-ASCII. Jika nama pengguna kamu mengandung karakter non-Inggris, jangan letakkan di dalam folder pengguna kamu.

Contoh path workspace yang baik: C:\workspace, D:\workspace, C:\Users\john\workspace

Langkah 1. Instal prasyarat

MSVC Build Tools (Kompiler C) — instal ini terlebih dahulu

Ini adalah unduhan berukuran besar (2-5 GB, 10-30 menit). Instal ini terlebih dahulu agar kamu langsung tahu apakah komputermu kompatibel.

catatan

Requires administrator rights.

Opsi 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 akan terlihat seperti macet saat installer berjalan. Ini normal dan akan memakan waktu 10-30 menit. Periksa taskbar kamu untuk jendela "Visual Studio Installer".

Jika winget tidak dikenali, perbarui App Installer dari Microsoft Store, atau gunakan Opsi B.

Opsi B — unduhan manual Buka situs Visual Studio Build Tools for C++ dan klik Download Build Tools. Jalankan file eksekusi untuk memulai instalasi.

Ketika jendela Installing Visual Studio terbuka, pada tab Workloads, pilih "Desktop development with C++". Lihat halaman Install C and C++ support in Visual Studio untuk detail lebih lanjut.

VS Code

Unduh VS Code dari situs Visual Studio Code, atau jalankan winget install Microsoft.VisualStudio.Code. Jalankan file eksekusi yang diunduh untuk menginstal VS Code.

Setelah terinstal, lanjutkan dengan langkah berikut:

1. Buka VS Code
2. Klik File → Open Folder, lalu pilih workspace kamu (misalnya, C:\workspace).
3. Klik Terminal → New terminal untuk membuka terminal PowerShell.
4. Klik ikon Extensions di sebelah kiri atau tekan Ctrl+Shift+X. Di jendela Extensions, cari dan instal ms-python.python, ms-toolsai.jupyter, dan ms-vscode.cpptools.

Jalankan perintah lainnya dalam panduan ini di terminal VS Code, kecuali diinstruksikan lain. Terminal VS Code menggunakan PowerShell secara default, sehingga mencegah kebingungan dengan command window bawaan Windows.

Atur variabel workspace. Misalnya, jika workspace kamu bernama workspace, jalankan yang berikut:

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

Python 3.12 (versi yang direkomendasikan)

Python 3.12 direkomendasikan karena memiliki ketersediaan wheel terbaik untuk qiskit-aer dan dependensi lainnya. 3.10 dan 3.11 juga berfungsi, tetapi 3.13 atau yang lebih baru mungkin tidak memiliki wheel pre-built untuk beberapa paket.

Buka terminal VS Code dan jalankan kode berikut untuk mendeteksi 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 unduhan tidak berhasil, atau kamu lebih suka mengunduh secara manual, beri komentar pada baris kode yang menginstal Python 3.12, lalu unduh Python 3.12 dari situs Python. Jalankan file eksekusi untuk menginstal Python. Pilih "Add Python to PATH" selama instalasi, lalu jalankan ulang cuplikan kode di atas untuk memastikan Python terdeteksi.

Catatan

• JANGAN gunakan Python dari Microsoft Store karena tidak memiliki header C. Jika python membuka Microsoft Store, nonaktifkan alias tersebut dengan membuka Windows Settings → Apps → Advanced app settings → App execution aliases.

• Pengguna Anaconda: jalankan conda deactivate sampai prefix (base) menghilang. Jika tidak juga hilang, buka terminal baru di VS Code.

Git (opsional)

Hanya diperlukan jika kamu meng-clone repositori lab. Jalankan winget install Git.Git.

Langkah 2 - Siapkan virtual environment Python dengan Qiskit

Reset terminal VS Code

Buka terminal VS Code dan reset:

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

Buat dan aktifkan virtual environment

Izinkan eksekusi skrip (sekali per pengguna), lalu buat virtual environment:

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

Jika aktivasi menampilkan error merah tentang "scripts disabled", berarti baris Set-ExecutionPolicy belum dijalankan. Jalankan secara manual, lalu coba lagi.

Prompt kamu sekarang seharusnya menampilkan (workspace).

Verify:

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

Instal paket

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 menghindari kompilasi qiskit-aer dari sumber. Jika qiskit-aer masih gagal, coba pip install qiskit-aer --only-binary=:all: atau lewati saja. qiskit-aer bersifat opsional dan hanya diperlukan untuk simulasi lokal.

catatan

JANGAN jalankan pip install --upgrade qiskit setelah setup. Meng-upgrade ke minor version baru akan merusak C extension yang dibangun berdasarkan versi lama.

Langkah 3 - Muat environment MSVC

Jalankan kode berikut di setiap sesi Python baru (misalnya, setiap kali kamu me-restart kernel Jupyter). Kode ini mencari dan memuat environment developer MSVC secara otomatis sehingga kamu tidak memerlukan command prompt bawaan x64.

Contoh dalam dokumentasi ini membangun modul ekstensi C dengan menggunakan setuptools bersama MSVC. Umumnya, kamu mendefinisikan QISKIT_PYTHON_EXTENSION, menyertakan qiskit.h, dan memanggil qk_import() di fungsi init kamu. Hanya header dari qiskit.capi.get_include() yang diperlukan saat build time — tidak ada library yang di-link. Lihat Extend Qiskit in Python with C untuk detailnya.

Muat environment 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)

Verifikasi penyiapan

Verifikasi bahwa penyiapan berhasil:

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 - Smoke test: Bangun ekstensi C

Jalankan kode berikut. Kode ini menulis file sumber ke _smoke_pkg/, membangun ekstensi C terhadap Qiskit C API, dan mengimpor hasilnya. Jika mencetak "SMOKE TEST PASSED", toolchain kamu sudah siap.

Paket ini mengikuti proses Extend Qiskit in Python with C dan menggunakan fungsi dari referensi Qiskit C API.

Kode smoke test

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 — Konfigurasi VS Code (opsional)

Untuk kemudahan penggunaan, kamu bisa mengikuti proses ini untuk menyiapkan IntelliSense untuk file C dan memilih interpreter Python secara otomatis.

Buat direktori .vscode

Di terminal VS Code, jalankan kode berikut:

mkdir $WORKSPACE\.vscode -Force

Buat file settings

Buat .vscode/settings.json di workspace kamu dengan menjalankan kode ini:

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

Buat file properties

Kode berikut mencetak JSON yang perlu kamu tempel ke .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 file ekstensi VS Code

Di VS Code, buat .vscode/extensions.json dengan konten ini:

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

Bangun library standalone

Bagian ini membangun library C standalone, yang hanya diperlukan jika kamu ingin mengkompilasi dan menautkan program C murni, seperti dijelaskan di bagian Mirip UNIX. Selain prasyarat Langkah 1, ini membutuhkan alat berikut:

• Compiler Rust: lihat misalnya panduan menginstal Qiskit dari sumber

• cbindgen: alat untuk membuat header C, yang bisa kamu instal dengan cargo install cbindgen. Menjalankan alat ini dari command line harus diaktifkan, yang mungkin memerlukan pembaruan variabel PATH kamu agar mencakup path cargo.

• Instalasi Python dengan akses ke python3.lib dan python3.dll

• Clone dari repositori Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Bangun library standalone

Pertama, kompilasi library dinamis qiskit_cext, dengan menjalankan perintah berikut di 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 menghasilkan library dinamis .dll dan file .dll.lib terkait di target/release. Selanjutnya, buat header dengan

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

Ini menulis header yang kompatibel dengan MSVC di dist\c\include.

Sekarang kamu bisa menggunakan cl untuk mengompilasi program C. Untuk memastikan compiler menemukan library qiskit, sertakan target\release di variabel 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 path ke python3.dll.

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

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

Pemecahan masalah

winget tidak dikenali

Perbarui App Installer dari Microsoft Store, atau gunakan link unduhan manual yang relevan

cl tidak dikenali

Jalankan ulang cell pemuatan MSVC (Langkah 3), atau gunakan x64 Native Tools Command Prompt

python membuka Microsoft Store

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

.ps1 cannot be loaded / skrip dinonaktifkan

Jalankan Set-ExecutionPolicy -Scope CurrentUser RemoteSigned lalu coba lagi

cannot open file 'qiskit.h'

Jalankan python -c "import qiskit.capi; print(qiskit.capi.get_include())" dan pastikan path-nya ada

qiskit.capi tidak ditemukan

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

Build qiskit-aer gagal

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

Build berhasil tapi impor gagal dengan error versi

Ekstensi C Qiskit yang dibangun dan versi Qiskit yang terinstal harus memiliki versi yang sama. Instal ulang Qiskit dengan pip install "qiskit~=2.4.2"

Saya membangun ulang C tapi circuit tidak berubah

Ekstensi C tidak bisa diimpor ulang secara langsung. Restart kernel, jalankan ulang perintah MSVC (Langkah 3), lalu bangun ulang

Skrip PowerShell diblokir

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Error panjang path

Gunakan path root pendek di C:\ (misalnya, C:\workspace, atau path yang kamu tetapkan di langkah setup), atau aktifkan Long Paths: Settings → System → For developers → Long Paths

Conda aktif (prompt menampilkan (base)) atau build berperilaku aneh setelah menggunakan Anaconda

Jalankan conda deactivate sampai CONDA_DEFAULT_ENV dan CONDA_PREFIX keduanya hilang dari environment. Periksa dengan $env:CONDA_PREFIX. Jika masih ada, buka PowerShell baru (bukan prompt Anaconda) dan coba lagi dari Langkah 2.

Virtual environment dibuat dari Python yang dikelola conda (periksa baris home = di .venv\pyvenv.cfg)

Virtual environment ini mewarisi C runtime dari conda dan tidak bisa diperbaiki di tempat. Hapus, unduh Python 3.12 dari website Python, dan bangun ulang. Jalankan Remove-Item -Recurse -Force .venv, lalu jalankan ulang snippet deteksi Python di Langkah 1 untuk menetapkan $PYTHON_EXE, lalu buat ulang virtual environment (Langkah 2).

DLL load failed saat impor

Conda kemungkinan bocor ke virtual environment. Periksa kedua masalah tepat di atas ini. Pastikan juga Python berupa 64-bit: python -c "import platform; print(platform.architecture())"

Build gagal dengan path yang kacau atau C1083

Nama pengguna atau path workspace kamu mengandung karakter non-ASCII. Pindahkan workspace ke path pendek yang hanya berisi ASCII (misalnya, C:\workspace)

Build atau impor gagal secara acak, berhasil saat dicoba ulang

Folder workspace disinkronkan oleh OneDrive. Pindahkan ke path lokal seperti C:\workspace

Build terganggu di tengah jalan (misalnya, ada pemadaman listrik)

Hapus folder _smoke_pkg di workspace kamu, jalankan ulang cell pemuatan MSVC, lalu jalankan ulang cell smoke test

pip install gagal dengan error sertifikat SSL

Jaringan kamu menggunakan proxy yang mencegat HTTPS. Coba jalankan pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit atau minta sertifikat CA proxy dari administrator jaringan kamu

Windows Defender mengkarantina file .pyd

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

VS Build Tools tidak bisa diinstal (tidak ada hak admin)

Akses administrator diperlukan. Minta akses dari departemen IT kamu

WinError 32 / file sedang digunakan saat build ulang

File .pyd terkunci oleh kernel yang sedang berjalan. Restart kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), jalankan ulang Langkah 3, lalu bangun ulang

Perintah diam-diam tidak melakukan apa pun (tidak ada error, tidak ada output)

Kamu mungkin berada di cmd.exe, bukan PowerShell. Periksa prompt kamu: PowerShell menampilkan PS C:\>, cmd menampilkan C:\>. Buka PowerShell dari Start Menu atau Win+X

Instalasi MSVC tampak macet

Flag --passive --wait memblokir PowerShell selagi installer berjalan di latar belakang. Periksa taskbar kamu untuk jendela "Visual Studio Installer". Instalasi bisa memakan waktu 10-30 menit.

Langkah selanjutnya

Rekomendasi

• Pelajari cara memperluas Python dengan Qiskit C API.
• Instal Qiskit.
• Jelajahi referensi Qiskit C API.

Footnotes

1. Jika kamu tidak menginstal Make, cek Makefile di root Qiskit untuk perintah yang diperlukan - atau cukup instal Make; belum terlambat.) ↩