Instalar a API C do Qiskit

Este guia descreve como instalar e utilizar a API C do Qiskit. Após a conclusão da instalação, leia “Ampliando o Python com a API C do Qiskit ”.

O exemplo a seguir cria um observável com 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;
}

semelhante ao UNIX

Esta seção fornece instruções de compilação para sistemas do tipo UNIX.

Requisitos

A compilação requer as seguintes ferramentas:

• Um compilador Rust: consulte, por exemplo, o guia sobre como instalar o Qiskit a partir da fonte
• Um compilador C: por exemplo, GCC em Linux e Clang em MacOS. A API C do Qiskit é compatível com um compilador em conformidade com o padrão C11 padrão.
• cbindgen: uma ferramenta para criar o cabeçalho C, que você pode instalar com cargo install cbindgen A execução da ferramenta na linha de comando deve estar habilitada, o que pode exigir a exportação da PATH variável para incluir /path/to/.cargo/bin.
• Python Biblioteca instalada ( Python 3.9 +): A biblioteca Python é necessária durante a vinculação dinâmica. Observe que Python não é usado em tempo de execução e que o interpretador nunca é inicializado; apenas alguns símbolos de libpython precisam ser definidos. Consulte esta edição para obter mais detalhes.
• (GNU) Make: isso é opcional, mas é recomendado para usar processos de instalação automatizados.

Esse código verifica se tudo foi instalado:

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

Construir

Para criar o cabeçalho e a biblioteca C, você pode executar o seguinte comando Make¹ na raiz do Qiskit,

make c

que fornecerá a biblioteca compartilhada compilada em dist/c/lib e o cabeçalho qiskit.h com todas as declarações de função em dist/c/include. Observe que o nome exato da biblioteca depende da plataforma; por exemplo,libqiskit.so no UNIX e libqiskit.dylib em MacOS. (Observe que essa etapa atualmente emite muitos avisos, o que é esperado e não é motivo para alarme. As versões futuras removerão os avisos)

Em seguida, você pode compilar um programa em C usando o cabeçalho e a biblioteca do Qiskit C:

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

Para garantir que a biblioteca Qiskit seja encontrada durante a vinculação, defina o caminho da biblioteca de tempo de execução como include /path/to/dist/c/lib. Se a biblioteca Python não estiver disponível por padrão durante a vinculação dinâmica, ela também precisará ser adicionada. Esses comandos dependem da plataforma. No 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

No MacOS:

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

Como alternativa, você pode definir o caminho da biblioteca de tempo de execução durante a compilação, adicionando

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

para os sinalizadores do compilador. Além disso, a biblioteca Python precisa estar disponível durante a vinculação dinâmica. Em ambientes Linux esse é normalmente o padrão.

Agora você pode executar o binário:

./example.o

que, se estiver usando o snippet de exemplo mostrado anteriormente, deverá imprimir

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

Esta seção fornece instruções de compilação para sistemas Windows.

Existem duas maneiras independentes de usar a API C no Windows:

• Crie módulos de extensão para o Python que utilizem a API C do Qiskit. Siga as etapas 1 a 5. Essa abordagem utiliza os cabeçalhos C fornecidos com o pacote qiskitPython e não requer o Rust nem o cbindgen.
• Compile a biblioteca C independente para ser vinculada a um programa em C puro, conforme feito na seção “Sistemas do tipo UNIX ”. Conclua a Etapa 1 e, em seguida, pule para a seção “Compilar a biblioteca independente ”, que lista os requisitos adicionais.

Requisitos

• São necessários direitos de administrador para algumas etapas.
• 5 a 8 GB de espaço livre em disco.
• Um compilador C: Microsoft Visual C++ (MSVC), instalado na Etapa 1.
• Uma instalação do Python de 64 bits ( 3.10 ou posterior), instalada na Etapa 1.

Antes de iniciar

Crie seu espaço de trabalho. Esse deve ser um caminho curto em uma unidade local. Não utilize pastas d OneDrive-synced (como “Documentos” ou “Área de Trabalho”), unidades de rede ou caminhos que contenham espaços ou caracteres não ASCII. Se o seu nome de usuário contiver caracteres que não sejam do alfabeto inglês, não o coloque na sua pasta de usuário.

Exemplos de caminhos adequados para o espaço de trabalho: C:\workspace, D:\workspace, C:\Users\john\workspace

Etapa 1. Instalar os pré-requisitos

• Ferramentas de compilação do MSVC (compilador C) — instale isso primeiro

  Este é um arquivo grande para baixar (2 a 5 GB, 10 a 30 minutos). Instale-o primeiro para saber imediatamente se o seu computador é compatível.

  Note

  Requer direitos de administrador.

  Opção A — winget Abra um terminal do PowerShell e execute o seguinte:

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

  O terminal parece estar travado enquanto o instalador está em execução. Isso é normal e levará de 10 a 30 minutos. Verifique se há uma janela chamada “Visual Studio Installer” na sua barra de tarefas.

  Se winget o aplicativo não for reconhecido, atualize o App Installer na Microsoft Store ou utilize a Opção B.

  Opção B — download manual Acesse o site do Visual Studio Build Tools for C++ e clique em “Baixar as ferramentas de compilação”. Execute o arquivo executável para iniciar a instalação.

  Quando a janela “Instalando o Visual Studio” for aberta, na guia “Cargas de trabalho”, selecione “Desenvolvimento para desktop com C++”. Consulte a página “Instalar suporte a C e C++ no Visual Studio ” para obter mais detalhes.

• VS Code

  Baixe o VS Code no site Visual Studio Code ou execute winget install Microsoft.VisualStudio.Code. Execute o arquivo executável baixado para instalar o VS Code.

  Após a instalação, siga estas etapas:

  1. Abrir o VS Code
  2. Clique em Arquivo → Abrir pasta e, em seguida, selecione sua área de trabalho (por exemplo, C:\workspace).
  3. Clique em Terminal → Novo terminal para abrir um terminal do PowerShell.
  4. Clique no ícone “Extensões” à esquerda ou pressione Ctrl+Shift+X. Na janela “Extensões”, procure e instale ms-python.python, ms-toolsai.jupyter, e ms-vscode.cpptools.

  Execute os demais comandos deste guia no terminal do VS Code, a menos que seja indicado o contrário. O terminal do VS Code é configurado por padrão como “ PowerShell, ”, o que evita confusões com a janela de comando integrada do Windows.

  Defina a variável do espaço de trabalho. Por exemplo, se o seu espaço de trabalho se chamar workspace, execute o seguinte:

  $WORKSPACE = "C:\workspace"   # change to your workspace path
  mkdir $WORKSPACE -Force
  cd $WORKSPACE
• Python 3.12 (versão recomendada)

  Python 3.12 é recomendado porque oferece a melhor disponibilidade de rodas para qiskit-aer e outras dependências. 3.10 e 3.11 também funcionam, mas 3.13 ou versões posteriores podem não ter pacotes pré-compilados para alguns pacotes.

  Abra o terminal do VS Code e execute o código a seguir para detectar uma versão adequada do 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 o download não tiver funcionado, ou se você preferir fazer o download manualmente, comente as linhas de código que instalam Python 3.12 e, em seguida, baixe Python 3.12 do site Python. Execute o arquivo executável para instalar o Python. Selecione “Adicionar Python ao PATH” durante a instalação e, em seguida, execute novamente o trecho de código acima para verificar se ele está sendo encontrado.

  Notas

  • NÃO utilize a versão da Microsoft Store Python, pois ela não contém os cabeçalhos C. Se python isso abrir a Microsoft Store, desative o alias acessando Configurações do Windows → Aplicativos → Configurações avançadas de aplicativos → Aliases de execução de aplicativos.

  • Usuários do Anaconda: executem o comando conda deactivate até que o prefixo (base) desapareça. Se o problema persistir, abra um novo terminal no VS Code.

• Git (opcional)

  Isso só é necessário se você clonar repositórios do laboratório. Execute o winget install Git.Git.

Etapa 2 - Configurar o ambiente virtual “ Python ” com o Qiskit

• Reiniciar o terminal do VS Code

  Abra o terminal do VS Code e reinicie-o:

  $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'"
  }
• Criar e ativar um ambiente virtual

  Permita a execução do script (uma vez por usuário) e, em seguida, crie o ambiente virtual:

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

  Se, durante a ativação, aparecer uma mensagem de erro em vermelho informando que “os scripts estão desativados”, isso significa que a Set-ExecutionPolicy linha não foi executada. Execute manualmente e tente novamente.

  (workspace)Sua linha de comando deve estar exibindo agora.

  Verifique:

  Get-Command python | Select-Object -First 1 -ExpandProperty Source
  # → workspace\.venv\Scripts\python.exe
• Pacotes de Instalação

  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 a compilação qiskit-aer a partir do código-fonte. Se qiskit-aer ainda assim não funcionar, tente pip install qiskit-aer --only-binary=:all: ou pule essa etapa. qiskit-aer é opcional e só é necessário para simulação local.

  Note

  NÃO execute pip install --upgrade qiskit o programa após a instalação. A atualização para uma nova versão secundária causa incompatibilidade com as extensões C compiladas com base na versão anterior.

Etapa 3 - Carregar o ambiente MSVC

Execute o código a seguir em cada nova sessão do Python (por exemplo, sempre que você reiniciar um kernel do Jupyter). Ele localiza e carrega o ambiente de desenvolvimento do MSVC automaticamente, de modo que você não precisa usar o prompt de comando integrado do x64.

O exemplo nesta documentação compila módulos de extensão em C utilizando setuptools o MSVC. QISKIT_PYTHON_EXTENSIONGeralmente, você define, inclui qiskit.he chama qk_import() na sua função de inicialização. Apenas os arquivos de cabeçalho de qiskit.capi.get_include() são necessários na compilação — nenhuma biblioteca é vinculada. Consulte “Extend Qiskit in Python with C” para obter mais detalhes.

• Carregar o ambiente do 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)
• Verifique a configuração

  Verifique se a configuração funcionou:

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

Etapa 4 – Teste de funcionamento: Compilar uma extensão em C

Execute o código a seguir. Ele grava os arquivos-fonte em _smoke_pkg/, compila uma extensão em C com base na API C do Qiskit e importa o resultado. Se for exibido “SMOKE TEST PASSED”, sua cadeia de ferramentas está pronta.

O pacote segue o processo “Extend Qiskit in Python with C” e utiliza funções da referência da API do Qiskit em C.

• Código de teste de fumaça

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

Etapa 5 — Configurar o VS Code (opcional)

Para facilitar o uso, você pode seguir este procedimento para configurar o IntelliSense para arquivos C e selecionar automaticamente o interpretador Python.

• Crie o diretório.vscode

  No terminal do VS Code, execute o código a seguir:

  mkdir $WORKSPACE\.vscode -Force
• Crie o arquivo de configurações

  Crie .vscode/settings.json em sua área de trabalho executando este código:

  {
      "python.defaultInterpreterPath": "${workspaceFolder}/.venv/Scripts/python.exe",
      "python.terminal.activateEnvironment": true,
      "jupyter.notebookFileRoot": "${workspaceFolder}"
  }
• Crie o arquivo de propriedades

  .vscode/c_cpp_properties.jsonO código a seguir exibe o JSON que você precisa colar em:

  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('}')
• Crie o arquivo de extensões do VS Code

  No VS Code, crie .vscode/extensions.json um arquivo com este conteúdo:

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

Compilar a biblioteca autônoma

Esta seção compila a biblioteca C independente, necessária apenas se você quiser compilar e vincular programas em C puro, conforme descrito na seção sobre sistemas do tipo UNIX. Além dos pré-requisitos da Etapa 1, são necessárias as seguintes ferramentas:

• Um compilador Rust: consulte, por exemplo, o guia sobre como instalar o Qiskit a partir da fonte
• cbindgen: uma ferramenta para criar o arquivo de cabeçalho em C, que você pode instalar com cargo install cbindgen. A execução da ferramenta a partir da linha de comando deve estar habilitada, o que pode exigir a atualização da sua PATH variável para incluir o caminho do cargo.
• Uma instalação do Python com acesso tanto python3.lib a quanto python3.dll
• Um clone do repositório do Qiskit (git clone https://github.com/Qiskit/qiskit.git)

• Compilar a biblioteca autônoma

  Primeiro, compile a qiskit_cext biblioteca dinâmica executando o seguinte comando no terminal do VS Code ( PowerShell ) na raiz do Qiskit:

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

  Isso gerará a biblioteca dinâmica .dll e o arquivo .dll.lib associado em target/release. Em seguida, gere o cabeçalho com

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

  Isso grava o cabeçalho compatível com o MSVC em dist\c\include.

  Agora você pode usar cl para compilar o programa em C. Para garantir que o compilador encontre a biblioteca qiskit, inclua-a target\release na PATH variável.

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

  Antes de executar, inclua o caminho para o seu python3.dll.

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

  deve então imprimir

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

Resolução de problemas

• winget não é reconhecido

  Atualize o App Installer pela Microsoft Store ou use os links de download manual correspondentes

• cl não é reconhecido

  Execute novamente a célula de carga do MSVC (Etapa 3) ou utilize o Prompt de Comando do Native Tools do x64

• python abre a Microsoft Store

  Vá para Configurações → Aplicativos → Configurações avançadas de aplicativos → Aliases de execução de aplicativos e desative python.exe

• .ps1 cannot be loaded / scripts desativados

  Execute Set-ExecutionPolicy -Scope CurrentUser RemoteSigned e, em seguida, tente novamente

• cannot open file 'qiskit.h'

  Execute python -c "import qiskit.capi; print(qiskit.capi.get_include())" e verifique se o caminho existe

• qiskit.capi não encontrado

  Executar o pip install "qiskit[visualization]~=2.4.2"

• qiskit-aer construção falha

  Execute o pip install qiskit-aer --only-binary=:all:. Se isso também não funcionar, use Python 3.12 ou ignore o aer, que é opcional

• A compilação é executada, mas a importação falha devido a um erro de versão

  A extensão C do Qiskit compilada e a versão instalada do Qiskit devem ser da mesma versão. Reinstale o Qiskit com pip install "qiskit~=2.4.2"

• Eu reconstruí o C, mas o circuito não mudou

  Uma extensão C não pode ser reimportada em tempo real. Reinicie o kernel, execute novamente os comandos do MSVC (Etapa 3) e, em seguida, recompile

• PowerShell o script foi bloqueado

  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

• Erros de comprimento do caminho

  Use um caminho raiz curto em C:\ (por exemplo, C:\workspace, ou o caminho que você definiu na etapa de configuração), ou habilite Caminhos Longos: Configurações → Sistema → Para desenvolvedores → Caminhos Longos

• O Conda está ativo (o prompt exibe (base)) ou as compilações apresentam comportamento anômalo após o uso do Anaconda

  Execute conda deactivate até que CONDA_DEFAULT_ENV e CONDA_PREFIX tenham sido removidos do ambiente. Verifique com $env:CONDA_PREFIX. Se o problema persistir, abra um novo prompt do PowerShell (não o prompt do Anaconda) e tente novamente a partir da Etapa 2.

• O ambiente virtual foi criado a partir de um Python gerenciado pelo conda (verifique a home = linha em .venv\pyvenv.cfg)

  O ambiente virtual herdou o runtime C do conda e não pode ser fixado no local. Exclua-o, baixe o arquivo “ Python ” 3.12 do site Python e recompile. Execute Remove-Item -Recurse -Force .venve, em seguida, execute novamente o trecho de código de detecção do Python da Etapa 1 para definir as configurações $PYTHON_EXEe, depois, recrie o ambiente virtual (Etapa 2).

• DLL load failed na importação

  É provável que o Conda esteja causando vazamentos no ambiente virtual. Verifique os dois assuntos mencionados imediatamente acima deste. Verifique também se o Python é de 64 bits: python -c "import platform; print(platform.architecture())"

• A compilação falha devido a caminhos incorretos ou C1083

  Seu nome de usuário ou caminho do espaço de trabalho contém caracteres não ASCII. Mude o espaço de trabalho para um caminho curto que contenha apenas caracteres ASCII (por exemplo, C:\workspace)

• A compilação ou importação falha aleatoriamente, mas funciona ao tentar novamente

  A pasta do espaço de trabalho é sincronizada pelo OneDrive. Mova-o para um caminho local, como C:\workspace

• Compilação interrompida no meio do processo (por exemplo, houve uma queda de energia)

  Exclua a _smoke_pkg pasta do seu espaço de trabalho, execute novamente a célula de carga do MSVC e, em seguida, execute novamente a célula de teste de fumaça

• pip install falha com um erro de certificado do tipo “ SSL ”

  Sua rede utiliza um proxy que intercepta o endereço HTTPS. Tente executar pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org qiskit o comando ou peça ao seu administrador de rede o certificado da CA do proxy

• O Windows Defender coloca o .pyd arquivo em quarentena

  Adicione as pastas e _smoke_pkg do .venv seu espaço de trabalho às exclusões do Defender acessando Segurança do Windows → Proteção contra vírus e ameaças → Gerenciar configurações → Exclusões

• Não é possível instalar o VS Build Tools (falta de direitos de administrador)

  É necessário ter acesso de Administrador. Peça acesso ao seu departamento de TI

• WinError 32 / arquivo em uso durante a recompilação

  O arquivo.pyd está bloqueado pelo kernel em execução. Reinicie o kernel (Ctrl+Shift+P → Jupyter: Reiniciar Kernel), execute novamente a Etapa 3 e, em seguida, recompile

• Os comandos simplesmente não fazem nada (sem erro, sem saída)

  Talvez você esteja no site cmd.exe em vez de PowerShell. Verifique o que aparece no prompt: o PowerShell mostra PS C:\>, e o cmd mostra C:\>. Abra o “ PowerShell ” pelo Menu Iniciar ou com Win+X

• A instalação do MSVC parece ter travado

  As --passive --wait opções de linha de comando PowerShell, enquanto o instalador é executado em segundo plano. Verifique se há uma janela chamada “Visual Studio Installer” na sua barra de tarefas. A instalação pode levar de 10 a 30 minutos

Próximas etapas