Installer l'API C de Qiskit

Ce guide décrit comment installer et utiliser l'API C de Qiskit. Une fois l'installation terminée, consulte Extend Python with the Qiskit C API.

L'exemple suivant construit un observable avec 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 et systèmes similaires

Cette section fournit les instructions de compilation pour les systèmes de type UNIX.

Prérequis

La compilation nécessite les outils suivants :

• Un compilateur Rust : consulte par exemple le guide d'installation de Qiskit depuis les sources
• Un compilateur C : par exemple, GCC sur Linux et Clang sur MacOS. L'API C de Qiskit est compatible avec un compilateur conforme à la norme C11.
• cbindgen : un outil pour créer l'en-tête C, que tu peux installer avec cargo install cbindgen L'exécution de l'outil depuis la ligne de commande doit être activée, ce qui peut nécessiter d'exporter ta variable PATH pour inclure /path/to/.cargo/bin.
• Bibliothèque Python installée (Python 3.9+) : la bibliothèque Python est requise lors de l'édition de liens dynamique. Note que Python n'est pas utilisé à l'exécution et que l'interpréteur n'est jamais initialisé ; seuls certains symboles de libpython doivent être définis. Consulte ce ticket pour plus de détails.
• (GNU) Make : optionnel mais recommandé pour utiliser les processus d'installation automatisés.

Ce code vérifie que tout a bien été installé :

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

Compilation

Pour compiler l'en-tête C et la bibliothèque, tu peux exécuter la commande Make suivante¹ à la racine de Qiskit,

make c

ce qui fournira la bibliothèque partagée compilée dans dist/c/lib et l'en-tête qiskit.h avec toutes les déclarations de fonctions dans dist/c/include. Note que le nom précis de la bibliothèque dépend de la plateforme ; par exemple, libqiskit.so sur UNIX et libqiskit.dylib sur MacOS. (Note que cette étape émet actuellement beaucoup d'avertissements, ce qui est attendu et ne constitue pas un motif d'inquiétude. Les versions futures supprimeront ces avertissements.)

Tu peux ensuite compiler un programme C en utilisant l'en-tête et la bibliothèque C de Qiskit :

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

Pour t'assurer que la bibliothèque Qiskit est trouvée lors de l'édition de liens, configure le chemin de la bibliothèque d'exécution pour inclure /path/to/dist/c/lib. Si la bibliothèque Python n'est pas disponible par défaut lors de l'édition de liens dynamique, elle doit également être ajoutée. Ces commandes dépendent de la plateforme. Sur 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

Sur MacOS :

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

Alternativement, tu peux définir le chemin de la bibliothèque d'exécution lors de la compilation en ajoutant

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

aux options du compilateur. De plus, la bibliothèque Python doit être disponible lors de l'édition de liens dynamique. Dans les environnements Linux, c'est généralement le cas par défaut.

Tu peux maintenant exécuter le binaire :

./example.o

ce qui, si tu utilises l'exemple de code présenté précédemment, devrait afficher

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

Cette section fournit les instructions de compilation pour les systèmes Windows.

Il existe deux façons indépendantes d'utiliser l'API C sous Windows :

• Créer des modules d'extension Python qui utilisent l'API C de Qiskit. Suis les étapes 1 à 5. Ce chemin utilise les en-têtes C fournis avec le package Python qiskit et ne nécessite pas Rust ni cbindgen.

• Créer la bibliothèque C autonome à lier depuis un programme en C pur, comme cela est fait dans la section de type UNIX. Termine l'étape 1, puis passe directement à Build the standalone library, qui liste ses exigences supplémentaires.

Prérequis

• Des droits d'administrateur sont requis pour certaines étapes.

• 5 à 8 Go d'espace disque libre.

• Un compilateur C : Microsoft Visual C++ (MSVC), installé à l'étape 1.

• Une installation Python 64 bits (3.10 ou ultérieure), installée à l'étape 1.

Avant de commencer

Crée ton espace de travail. Il doit s'agir d'un chemin court sur un lecteur local. N'utilise pas de dossiers synchronisés avec OneDrive (comme Documents ou Bureau), de lecteurs réseau, ou de chemins contenant des espaces ou des caractères non-ASCII. Si ton nom d'utilisateur contient des caractères non anglais, ne le place pas sous ton dossier utilisateur.

Exemples de bons chemins d'espace de travail : C:\workspace, D:\workspace, C:\Users\john\workspace

Étape 1. Installer les prérequis

MSVC Build Tools (compilateur C) — installer ceci en premier

Il s'agit d'un téléchargement volumineux (2 à 5 Go, 10 à 30 min). Installe-le en premier pour savoir immédiatement si ton ordinateur est compatible.

remarque

Requires administrator rights.

Option A — winget Ouvre un terminal PowerShell et exécute ce qui suit :

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

Le terminal semble figé pendant l'exécution du programme d'installation. Ceci est normal et prendra 10 à 30 minutes. Vérifie ta barre des tâches pour une fenêtre « Visual Studio Installer ».

Si winget n'est pas reconnu, mets à jour App Installer depuis le Microsoft Store, ou utilise l'Option B.

Option B — téléchargement manuel Ouvre le site Visual Studio Build Tools for C++ et clique sur Download Build Tools. Exécute le fichier exécutable pour démarrer l'installation.

Lorsque la fenêtre Installing Visual Studio s'ouvre, dans l'onglet Workloads, choisis « Desktop development with C++ ». Consulte la page Install C and C++ support in Visual Studio pour plus de détails.

VS Code

Télécharge VS Code depuis le site Visual Studio Code, ou exécute winget install Microsoft.VisualStudio.Code. Exécute le fichier exécutable téléchargé pour installer VS Code.

Une fois l'installation terminée, poursuis avec ces étapes :

1. Ouvre VS Code
2. Clique sur File → Open Folder, puis sélectionne ton espace de travail (par exemple, C:\workspace).
3. Clique sur Terminal → New terminal pour ouvrir un terminal PowerShell.
4. Clique sur l'icône Extensions à gauche ou appuie sur Ctrl+Shift+X. Dans la fenêtre Extensions, recherche et installe ms-python.python, ms-toolsai.jupyter, et ms-vscode.cpptools.

Exécute le reste des commandes de ce guide dans le terminal VS Code, sauf indication contraire. Le terminal VS Code utilise PowerShell par défaut, ce qui évite les confusions avec la fenêtre de commande intégrée de Windows.

Définis la variable d'espace de travail. Par exemple, si ton espace de travail s'appelle workspace, exécute ce qui suit :

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

Python 3.12 (version recommandée)

Python 3.12 est recommandé car il offre la meilleure disponibilité de wheels pour qiskit-aer et d'autres dépendances. 3.10 et 3.11 fonctionnent également, mais 3.13 ou une version ultérieure pourrait manquer de wheels précompilées pour certains packages.

Ouvre le terminal VS Code et exécute le code suivant pour détecter une version appropriée de 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'" }

Si le téléchargement n'a pas fonctionné, ou si tu préfères un téléchargement manuel, mets en commentaire les lignes de code qui installent Python 3.12, puis télécharge Python 3.12 depuis le site Python. Exécute l'exécutable pour installer Python. Sélectionne « Add Python to PATH » pendant l'installation, puis réexécute l'extrait ci-dessus pour t'assurer qu'il est bien détecté.

Remarques

• N'utilise PAS le Python du Microsoft Store car il ne contient pas les en-têtes C. Si python ouvre le Microsoft Store, désactive l'alias en allant dans Windows Settings → Apps → Advanced app settings → App execution aliases.

• Utilisateurs d'Anaconda : exécute conda deactivate jusqu'à ce que le préfixe (base) disparaisse. S'il ne disparaît pas, ouvre un nouveau terminal dans VS Code.

Git (facultatif)

Nécessaire uniquement si tu clones des dépôts de labo. Exécute winget install Git.Git.

Étape 2 - Configurer l'environnement virtuel Python avec Qiskit

Réinitialiser le terminal VS Code

Ouvre le terminal VS Code et réinitialise-le :

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

Créer et activer un environnement virtuel

Autorise l'exécution de scripts (une fois par utilisateur), puis crée l'environnement virtuel :

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

Si l'activation affiche une erreur rouge concernant des « scripts désactivés », la ligne Set-ExecutionPolicy n'a pas été exécutée. Exécute-la manuellement, puis réessaie.

Ton invite devrait maintenant afficher (workspace).

Verify:

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

Installer les 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 évite de compiler qiskit-aer depuis les sources. Si qiskit-aer échoue toujours, essaie pip install qiskit-aer --only-binary=:all: ou ignore-le. qiskit-aer est optionnel et n'est nécessaire que pour la simulation locale.

remarque

Ne lance PAS pip install --upgrade qiskit après l'installation. Passer à une nouvelle version mineure casse les extensions C construites avec l'ancienne.

Étape 3 - Charger l'environnement MSVC

Exécute le code suivant dans chaque nouvelle session Python (par exemple, chaque fois que tu redémarres un kernel Jupyter). Il localise et charge automatiquement l'environnement de développement MSVC afin que tu n'aies pas besoin de l'invite de commandes intégrée x64.

L'exemple de cette documentation construit des modules d'extension C en utilisant setuptools avec MSVC. En général, tu définis QISKIT_PYTHON_EXTENSION, tu inclus qiskit.h, et tu appelles qk_import() dans ta fonction d'initialisation. Seuls les en-têtes de qiskit.capi.get_include() sont nécessaires au moment de la construction — aucune bibliothèque n'est liée. Consulte Étendre Qiskit en Python avec C pour plus de détails.

Charger l'environnement 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)

Vérifier la configuration

Vérifie que la configuration a fonctionné :

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

Étape 4 - Test de fumée : construire une extension C

Exécute le code suivant. Il écrit des fichiers sources dans _smoke_pkg/, construit une extension C qui s'appuie sur l'API C de Qiskit, et importe le résultat. S'il affiche « SMOKE TEST PASSED », ta chaîne d'outils est prête.

Le package suit le processus Étendre Qiskit en Python avec C et utilise des fonctions de la référence de l'API C de Qiskit.

Code du test de fumée

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

Étape 5 — Configurer VS Code (optionnel)

Pour plus de facilité, tu peux suivre ce processus pour configurer IntelliSense pour les fichiers C et sélectionner automatiquement l'interpréteur Python.

Créer le répertoire .vscode

Dans le terminal VS Code, exécute le code suivant :

mkdir $WORKSPACE\.vscode -Force

Créer le fichier de paramètres

Crée .vscode/settings.json dans ton espace de travail en exécutant ce code :

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

Créer le fichier de propriétés

Le code suivant affiche le JSON que tu dois coller dans .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('}')

Créer le fichier des extensions VS Code

Dans VS Code, crée .vscode/extensions.json avec ce contenu :

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

Construire la bibliothèque autonome

Cette section construit la bibliothèque C autonome, qui n'est nécessaire que si tu veux compiler et lier des programmes C purs, comme décrit dans la section de type UNIX. En plus des prérequis de l'étape 1, cela nécessite les outils suivants :

• Un compilateur Rust : voir par exemple le guide d'installation de Qiskit depuis les sources

• cbindgen : un outil pour créer l'en-tête C, que tu peux installer avec cargo install cbindgen. L'exécution de l'outil depuis la ligne de commande doit être activée, ce qui peut nécessiter de mettre à jour ta variable PATH pour inclure le chemin de cargo.

• Une installation Python avec accès à la fois à python3.lib et python3.dll

• Un clone du dépôt Qiskit (git clone https://github.com/Qiskit/qiskit.git)

Construire la bibliothèque autonome

Tout d'abord, compile la bibliothèque dynamique qiskit_cext, en exécutant ce qui suit dans le terminal VS Code (PowerShell) à la racine de Qiskit :

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

Cela générera la bibliothèque dynamique .dll et le fichier .dll.lib associé dans target/release. Ensuite, génère l'en-tête avec

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

Cela écrit l'en-tête compatible MSVC dans dist\c\include.

Tu peux maintenant utiliser cl pour compiler le programme C. Pour t'assurer que le compilateur trouve la bibliothèque qiskit, inclus target\release dans la variable PATH.

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

Avant d'exécuter, inclus le chemin vers ta python3.dll.

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

devrait alors afficher

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

Dépannage

winget n'est pas reconnu

Mets à jour l'App Installer depuis le Microsoft Store, ou utilise les liens de téléchargement manuel appropriés

cl n'est pas reconnu

Réexécute la cellule de chargement MSVC (étape 3), ou utilise l'invite de commandes x64 Native Tools

python ouvre le Microsoft Store

Va dans Paramètres → Applications → Paramètres avancés des applications → Alias d'exécution d'application et désactive python.exe

.ps1 cannot be loaded / scripts désactivés

Exécute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned puis réessaie

cannot open file 'qiskit.h'

Exécute python -c "import qiskit.capi; print(qiskit.capi.get_include())" et confirme que le chemin existe

qiskit.capi introuvable

Exécute pip install "qiskit[visualization]~=2.4.2"

La construction de qiskit-aer échoue

Exécute pip install qiskit-aer --only-binary=:all:. Si cela échoue aussi, utilise Python 3.12 ou ignore aer, qui est optionnel

La construction fonctionne mais l'import échoue avec une erreur de version

L'extension C de Qiskit construite et la version de Qiskit installée doivent avoir la même version. Réinstalle Qiskit avec pip install "qiskit~=2.4.2"

J'ai reconstruit le C mais le circuit n'a pas changé

Une extension C ne peut pas être réimportée à chaud. Redémarre le kernel, réexécute les commandes MSVC (étape 3), puis reconstruis

Le script PowerShell a été bloqué

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Erreurs de longueur de chemin

Utilise un chemin racine court sur C:\ (par exemple, C:\workspace, ou le chemin que tu as défini à l'étape de configuration), ou active les chemins longs : Paramètres → Système → Pour les développeurs → Chemins longs

Conda est actif (l'invite affiche (base)) ou les constructions se comportent bizarrement après l'utilisation d'Anaconda

Exécute conda deactivate jusqu'à ce que CONDA_DEFAULT_ENV et CONDA_PREFIX aient tous deux disparu de l'environnement. Vérifie avec $env:CONDA_PREFIX. S'ils persistent, ouvre un nouveau PowerShell (pas une invite Anaconda) et réessaie depuis l'étape 2.

L'environnement virtuel a été créé à partir d'un Python géré par conda (vérifie la ligne home = dans .venv\pyvenv.cfg)

L'environnement virtuel a hérité du runtime C de conda et ne peut pas être corrigé en place. Supprime-le, télécharge Python 3.12 depuis le site Python, et reconstruis. Exécute Remove-Item -Recurse -Force .venv, puis réexécute l'extrait de détection Python de l'étape 1 pour définir $PYTHON_EXE, puis recrée l'environnement virtuel (étape 2).

DLL load failed à l'import

Conda s'infiltre probablement dans l'environnement virtuel. Vérifie les deux problèmes juste au-dessus. Vérifie aussi que Python est en 64 bits : python -c "import platform; print(platform.architecture())"

La construction échoue avec des chemins corrompus ou C1083

Ton nom d'utilisateur ou le chemin de ton espace de travail contient des caractères non-ASCII. Déplace l'espace de travail vers un chemin court, uniquement en ASCII (par exemple, C:\workspace)

La construction ou l'import échoue de façon aléatoire, fonctionne en réessayant

Le dossier de l'espace de travail est synchronisé par OneDrive. Déplace-le vers un chemin local comme C:\workspace

La construction a été interrompue en cours (par exemple, à cause d'une coupure de courant)

Supprime le dossier _smoke_pkg dans ton espace de travail, réexécute la cellule de chargement MSVC, puis réexécute la cellule de test de fumée

pip install échoue avec une erreur de certificat SSL

Ton réseau utilise un proxy qui intercepte le trafic HTTPS. Essaie d'exécuter pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit ou demande à ton administrateur réseau le certificat CA du proxy

Windows Defender met en quarantaine le fichier .pyd

Ajoute les dossiers .venv et _smoke_pkg de ton espace de travail aux exclusions de Defender en allant dans Sécurité Windows → Protection contre les virus et menaces → Gérer les paramètres → Exclusions

VS Build Tools ne peut pas être installé (pas de droits administrateur)

L'accès administrateur est requis. Demande l'accès à ton service informatique

WinError 32 / fichier en cours d'utilisation pendant la reconstruction

Le .pyd est verrouillé par le kernel en cours d'exécution. Redémarre le kernel (Ctrl+Shift+P → Jupyter: Restart Kernel), réexécute l'étape 3, puis reconstruis

Les commandes ne font silencieusement rien (aucune erreur, aucune sortie)

Tu es peut-être dans cmd.exe au lieu de PowerShell. Vérifie ton invite : PowerShell affiche PS C:\>, cmd affiche C:\>. Ouvre PowerShell depuis le menu Démarrer ou Win+X

L'installation de MSVC semble bloquée

Les options --passive --wait bloquent PowerShell pendant que l'installateur s'exécute en arrière-plan. Vérifie ta barre des tâches pour une fenêtre « Visual Studio Installer ». Cela peut prendre 10 à 30 minutes à installer

Étapes suivantes

Recommandations

• Découvre comment étendre Python avec l'API C de Qiskit.
• Installer Qiskit.
• Explore la référence de l'API C de Qiskit.

Footnotes

1. Si tu n'as pas installé Make, consulte le Makefile à la racine de Qiskit pour les commandes requises — ou installe simplement Make ; il n'est pas trop tard. ↩