Installare la C API di Qiskit

Questa guida descrive come installare e utilizzare la C API di Qiskit. Dopo aver completato l'installazione, leggi Estendere Python con la C API di Qiskit.

Il seguente esempio costruisce un observable in 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;
}

Sistemi UNIX-like

Questa sezione fornisce le istruzioni di compilazione per i sistemi UNIX-like.

Requisiti

La compilazione richiede i seguenti strumenti:

• Un compilatore Rust: consulta ad esempio la guida all'installazione di Qiskit dal sorgente
• Un compilatore C: ad esempio GCC su Linux e Clang su MacOS. La C API di Qiskit è compatibile con un compilatore conforme allo standard C11.
• cbindgen: uno strumento per generare l'header C, installabile con cargo install cbindgen L'esecuzione dello strumento dalla riga di comando deve essere abilitata, il che potrebbe richiedere di esportare la variabile PATH per includere /path/to/.cargo/bin.
• Libreria Python installata (Python 3.9+): la libreria Python è necessaria durante il collegamento dinamico. Tieni presente che Python non viene utilizzato a runtime e l'interprete non viene mai inizializzato; è sufficiente che alcuni simboli di libpython siano definiti. Consulta questa issue per ulteriori dettagli.
• (GNU) Make: opzionale, ma consigliato per automatizzare il processo di installazione.

Questo codice verifica che tutto sia stato installato correttamente:

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

Compilazione

Per compilare l'header C e la libreria, puoi eseguire il seguente comando Make¹ nella root di Qiskit:

make c

che fornirà la libreria condivisa compilata in dist/c/lib e l'header qiskit.h con tutte le dichiarazioni delle funzioni in dist/c/include. Tieni presente che il nome esatto della libreria dipende dalla piattaforma; ad esempio libqiskit.so su UNIX e libqiskit.dylib su MacOS. (Nota che questo passaggio attualmente emette molti warning, il che è previsto e non è motivo di preoccupazione. Le versioni future rimuoveranno i warning.)

Puoi quindi compilare un programma C utilizzando l'header e la libreria C di Qiskit:

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

Per assicurarti che la libreria Qiskit venga trovata durante il collegamento, imposta il percorso della libreria a runtime in modo che includa /path/to/dist/c/lib. Se la libreria Python non è disponibile di default durante il collegamento dinamico, anche questa deve essere aggiunta. I comandi dipendono dalla piattaforma. Su 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

Su MacOS:

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

In alternativa, puoi impostare il percorso della libreria a runtime durante la compilazione aggiungendo

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

ai flag del compilatore. Inoltre, la libreria Python deve essere disponibile durante il collegamento dinamico. Negli ambienti Linux questo è tipicamente il comportamento predefinito.

Ora puoi eseguire il binario:

./example.o

che, usando il frammento di esempio mostrato in precedenza, dovrebbe stampare

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

Questa sezione fornisce le istruzioni di compilazione per i sistemi Windows.

Esistono due modi indipendenti per usare la C API su Windows:

• Costruire moduli di estensione Python che usano la C API di Qiskit. Segui i passi 1-5. Questo percorso usa gli header C forniti con il pacchetto Python qiskit e non richiede Rust o cbindgen.

• Costruire la libreria C standalone da collegare a un programma C puro, come avviene nella sezione UNIX-like. Completa il passo 1, poi salta a Build the standalone library, che elenca i suoi requisiti aggiuntivi.

Requisiti

• Sono richiesti i diritti di amministratore per alcuni passi.

• 5-8 GB di spazio libero su disco.

• Un compilatore C: Microsoft Visual C++ (MSVC), installato al passo 1.

• Un'installazione Python a 64 bit (3.10 o successiva), installata al Passaggio 1.

Prima di iniziare

Crea il tuo workspace. Dovrebbe essere un percorso breve su un'unità locale. Non usare cartelle sincronizzate con OneDrive (come Documenti o Desktop), unità di rete o percorsi con spazi o caratteri non ASCII. Se il tuo nome utente contiene caratteri non inglesi, non metterlo sotto la tua cartella utente.

Esempi di percorsi di workspace validi: C:\workspace, D:\workspace, C:\Users\john\workspace

Passaggio 1. Installa i prerequisiti

MSVC Build Tools (compilatore C) — installa questo per primo

Questo è un download di grandi dimensioni (2-5 GB, 10-30 min). Installalo per primo così saprai subito se il tuo computer è compatibile.

nota

Requires administrator rights.

Opzione A — winget Apri un terminale PowerShell ed esegui quanto segue:

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

Il terminale sembra bloccato mentre l'installer è in esecuzione. Questo è normale e richiederà 10-30 minuti. Controlla la barra delle applicazioni per una finestra "Visual Studio Installer".

Se winget non viene riconosciuto, aggiorna App Installer dal Microsoft Store, oppure usa l'Opzione B.

Opzione B — download manuale Apri il sito Visual Studio Build Tools for C++ e fai clic su Download Build Tools. Esegui l'eseguibile per avviare l'installazione.

Quando si apre la finestra Installing Visual Studio, nella scheda Workloads, scegli "Desktop development with C++". Consulta la pagina Install C and C++ support in Visual Studio per ulteriori dettagli.

VS Code

Scarica VS Code dal sito Visual Studio Code, oppure esegui winget install Microsoft.VisualStudio.Code. Esegui il file eseguibile scaricato per installare VS Code.

Dopo l'installazione, continua con questi passaggi:

1. Apri VS Code
2. Fai clic su File → Open Folder, poi seleziona il tuo workspace (per esempio, C:\workspace).
3. Fai clic su Terminal → New terminal per aprire un terminale PowerShell.
4. Fai clic sull'icona Extensions a sinistra o premi Ctrl+Shift+X. Nella finestra Extensions, cerca e installa ms-python.python, ms-toolsai.jupyter e ms-vscode.cpptools.

Esegui il resto dei comandi in questa guida nel terminale di VS Code, salvo diversa indicazione. Il terminale di VS Code utilizza PowerShell per impostazione predefinita, evitando confusione con il prompt dei comandi integrato di Windows.

Imposta la variabile workspace. Per esempio, se il tuo workspace si chiama workspace, esegui quanto segue:

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

Python 3.12 (versione consigliata)

Python 3.12 è consigliato perché ha la migliore disponibilità di wheel per qiskit-aer e altre dipendenze. Anche 3.10 e 3.11 funzionano, ma 3.13 o successive potrebbero non avere wheel precompilati per alcuni pacchetti.

Apri il terminale di VS Code ed esegui il seguente codice per rilevare una versione adatta di 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'" }

Se il download non ha funzionato, o preferisci il download manuale, commenta le righe di codice che installano Python 3.12, poi scarica Python 3.12 dal sito Python. Esegui l'eseguibile per installare Python. Seleziona "Add Python to PATH" durante l'installazione, poi riesegui lo snippet sopra per assicurarti che venga trovato.

Note

• NON usare il Python del Microsoft Store perché manca delle intestazioni C. Se python apre il Microsoft Store, disabilita l'alias andando su Impostazioni di Windows → App → Impostazioni avanzate app → Alias di esecuzione delle app.

• Utenti Anaconda: esegui conda deactivate finché il prefisso (base) non scompare. Se non scompare, apri un nuovo terminale in VS Code.

Git (opzionale)

Necessario solo se cloni repository di laboratorio. Esegui winget install Git.Git.

Passaggio 2 - Configura l'ambiente virtuale Python con Qiskit

Reimposta il terminale di VS Code

Apri il terminale di VS Code e reimpostalo:

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

Crea e attiva un ambiente virtuale

Consenti l'esecuzione di script (una volta per utente), poi crea l'ambiente virtuale:

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

Se l'attivazione mostra un errore rosso su "scripts disabled", la riga Set-ExecutionPolicy non è stata eseguita. Eseguila manualmente, poi riprova.

Il tuo prompt ora dovrebbe mostrare (workspace).

Verify:

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

Installa i pacchetti

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 evita di compilare qiskit-aer dal sorgente. Se qiskit-aer continua a fallire, prova pip install qiskit-aer --only-binary=:all: oppure saltalo. qiskit-aer è opzionale ed è necessario solo per la simulazione locale.

nota

NON eseguire pip install --upgrade qiskit dopo la configurazione. L'aggiornamento a una nuova versione minore rende inutilizzabili le estensioni C compilate per la versione precedente.

Passaggio 3 - Carica l'ambiente MSVC

Esegui il seguente codice in ogni nuova sessione Python (per esempio, ogni volta che riavvii un kernel Jupyter). Individua e carica automaticamente l'ambiente per sviluppatori MSVC così non hai bisogno del prompt dei comandi integrato x64.

L'esempio in questa documentazione compila moduli di estensione C usando setuptools con MSVC. In generale, definisci QISKIT_PYTHON_EXTENSION, includi qiskit.h e chiami qk_import() nella tua funzione init. Al momento della compilazione sono necessarie solo le intestazioni da qiskit.capi.get_include() — non viene collegata alcuna libreria. Consulta Extend Qiskit in Python with C per i dettagli.

Carica l'ambiente 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)

Verifica la configurazione

Verifica che la configurazione abbia funzionato:

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

Passaggio 4 - Smoke test: compila un'estensione C

Esegui il seguente codice. Scrive file sorgente in _smoke_pkg/, compila un'estensione C rispetto all'API C di Qiskit e importa il risultato. Se stampa "SMOKE TEST PASSED", la tua toolchain è pronta.

Il pacchetto segue il processo Extend Qiskit in Python with C e utilizza funzioni dal riferimento API C di Qiskit.

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

Passaggio 5 — Configura VS Code (opzionale)

Per facilità d'uso, puoi seguire questo processo per configurare IntelliSense per i file C e selezionare automaticamente l'interprete Python.

Crea la directory .vscode

Nel terminale di VS Code, esegui il seguente codice:

mkdir $WORKSPACE\.vscode -Force

Crea il file delle impostazioni

Crea .vscode/settings.json nel tuo workspace eseguendo questo codice:

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

Crea il file delle proprietà

Il seguente codice stampa il JSON che devi incollare in .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('}')

Crea il file delle estensioni di VS Code

In VS Code, crea .vscode/extensions.json con questo contenuto:

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

Compila la libreria standalone

Questa sezione compila la libreria C standalone, necessaria solo se vuoi compilare e collegare programmi C puri, come descritto nella sezione UNIX-like. Oltre ai prerequisiti del Passaggio 1, sono necessari i seguenti strumenti:

• Un compilatore Rust: vedi per esempio la guida sull'installazione di Qiskit dal sorgente

• cbindgen: uno strumento per creare l'intestazione C, che puoi installare con cargo install cbindgen. L'esecuzione dello strumento dalla riga di comando dovrebbe essere abilitata, il che potrebbe richiedere l'aggiornamento della variabile PATH per includere il percorso di cargo.

• Un'installazione Python con accesso sia a python3.lib che a python3.dll

• Un clone del repository Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Compila la libreria standalone

Innanzitutto, compila la libreria dinamica qiskit_cext, eseguendo quanto segue nel terminale VS Code (PowerShell) nella root di Qiskit:

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

Questo genererà la libreria dinamica .dll e il file .dll.lib associato in target/release. Successivamente, genera l'header con:

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

Questo scrive l'header compatibile con MSVC in dist\c\include.

Ora puoi usare cl per compilare il programma C. Per assicurarti che il compilatore trovi la libreria qiskit, includi target\release nella variabile PATH.

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

Prima di eseguire il programma, includi il percorso del tuo python3.dll.

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

che dovrebbe stampare

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

Risoluzione dei problemi

winget non viene riconosciuto

Aggiorna App Installer dal Microsoft Store, oppure usa i link di download manuale pertinenti

cl non viene riconosciuto

Riesegui la cella di caricamento MSVC (Passaggio 3), oppure usa l'x64 Native Tools Command Prompt

python apre il Microsoft Store

Vai su Impostazioni → App → Impostazioni avanzate app → Alias di esecuzione delle app e disattiva python.exe

.ps1 cannot be loaded / script disabilitati

Esegui Set-ExecutionPolicy -Scope CurrentUser RemoteSigned poi riprova

cannot open file 'qiskit.h'

Esegui python -c "import qiskit.capi; print(qiskit.capi.get_include())" e conferma che il percorso esista

qiskit.capi non trovato

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

La compilazione di qiskit-aer fallisce

Esegui pip install qiskit-aer --only-binary=:all:. Se anche questo fallisce, usa Python 3.12 oppure salta aer, che è opzionale

La compilazione riesce ma l'importazione fallisce con un errore di versione

L'estensione C di Qiskit compilata e la versione di Qiskit installata devono avere la stessa versione. Reinstalla Qiskit con pip install "qiskit~=2.4.2"

Ho ricompilato il C ma il circuito non è cambiato

Un'estensione C non può essere reimportata a runtime. Riavvia il kernel, riesegui i comandi MSVC (Passaggio 3), poi ricompila

Lo script PowerShell è stato bloccato

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Errori di lunghezza del percorso

Usa un percorso radice breve su C:\ (per esempio, C:\workspace, o il percorso impostato nel passaggio di configurazione), oppure abilita i percorsi lunghi: Impostazioni → Sistema → Per sviluppatori → Percorsi lunghi

Conda è attivo (il prompt mostra (base)) oppure le compilazioni si comportano in modo strano dopo aver usato Anaconda

Esegui conda deactivate finché CONDA_DEFAULT_ENV e CONDA_PREFIX non scompaiono entrambi dall'ambiente. Controlla con $env:CONDA_PREFIX. Se persistono, apri un nuovo PowerShell (non un prompt Anaconda) e riprova dal Passaggio 2.

L'ambiente virtuale è stato creato da un Python gestito da conda (controlla la riga home = in .venv\pyvenv.cfg)

L'ambiente virtuale ha ereditato il runtime C di conda e non può essere corretto sul posto. Eliminalo, scarica Python 3.12 dal sito Python e ricompila. Esegui Remove-Item -Recurse -Force .venv, poi riesegui lo snippet di rilevamento Python nel Passaggio 1 per impostare $PYTHON_EXE, poi ricrea l'ambiente virtuale (Passaggio 2).

DLL load failed durante l'importazione

È probabile che Conda stia interferendo con l'ambiente virtuale. Controlla entrambi i problemi appena sopra. Verifica anche che Python sia a 64 bit: python -c "import platform; print(platform.architecture())"

La compilazione fallisce con percorsi corrotti o C1083

Il tuo nome utente o percorso del workspace contiene caratteri non ASCII. Sposta il workspace in un percorso breve solo ASCII (per esempio, C:\workspace)

La compilazione o l'importazione falliscono in modo casuale, ma funzionano al nuovo tentativo

La cartella del workspace è sincronizzata da OneDrive. Spostala in un percorso locale come C:\workspace

Compilazione interrotta a metà (per esempio, c'è stata un'interruzione di corrente)

Elimina la cartella _smoke_pkg nel tuo workspace, riesegui la cella di caricamento MSVC, poi riesegui la cella dello smoke test

pip install fallisce con un errore di certificato SSL

La tua rete usa un proxy che intercetta HTTPS. Prova a eseguire pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit oppure chiedi al tuo amministratore di rete il certificato CA del proxy

Windows Defender mette in quarantena il file .pyd

Aggiungi le cartelle .venv e _smoke_pkg del tuo workspace alle esclusioni di Defender andando su Sicurezza di Windows → Protezione da virus e minacce → Gestisci impostazioni → Esclusioni

Impossibile installare VS Build Tools (nessun diritto di amministratore)

È richiesto l'accesso come amministratore. Chiedi accesso al tuo reparto IT

WinError 32 / file in uso durante la ricompilazione

Il .pyd è bloccato dal kernel in esecuzione. Riavvia il kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), riesegui il Passaggio 3, poi ricompila

I comandi non fanno silenziosamente nulla (nessun errore, nessun output)

Potresti trovarti in cmd.exe invece che in PowerShell. Controlla il tuo prompt: PowerShell mostra PS C:\>, cmd mostra C:\>. Apri PowerShell dal menu Start o con Win+X

L'installazione MSVC sembra bloccata

I flag --passive --wait bloccano PowerShell mentre l'installer viene eseguito in background. Controlla la barra delle applicazioni per una finestra "Visual Studio Installer". L'installazione può richiedere 10-30 minuti

Prossimi passaggi

Raccomandazioni

• Impara come estendere Python con l'API C di Qiskit.
• Installa Qiskit.
• Esplora il riferimento API C di Qiskit.

Footnotes

1. Se non hai installato Make, controlla il Makefile nella root di Qiskit per i comandi necessari — oppure installa semplicemente Make: non è mai troppo tardi. ↩