Pular para o conteúdo principal

Especificar opções do Sampler

Versões dos pacotes

O código desta página foi desenvolvido com os seguintes requisitos. Recomendamos usar essas versões ou versões mais recentes.

qiskit[all]~=2.5.2
qiskit-ibm-runtime~=0.47.0

Você pode usar opções para personalizar a primitiva Sampler. Esta seção foca em como especificar as opções da primitiva IBM Quantum. Embora a interface do método run() das primitivas seja comum a todas as implementações, suas opções não são. Consulte as referências de API correspondentes para obter informações sobre as opções de qiskit.primitives.BackendSamplerV2 e qiskit_aer.primitives.SamplerV2.

Definir opções do Sampler​

Você pode definir opções ao inicializar o Sampler, após inicializá-lo, ou atualizar as opções depois que o Sampler foi inicializado. Para instruções sobre como usar essas técnicas, consulte o tópico Introdução às opções.

Além disso, você pode definir o valor shots no método run(), conforme descrito na seção a seguir.

Método Run()​

Os únicos valores que você pode passar para run() são os definidos na interface, ou seja, shots. Isso substitui qualquer valor definido para default_shots na execução atual.

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-runtime
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

circuit1 = random_iqp(3)
circuit1.measure_all()
circuit2 = random_iqp(3)
circuit2.measure_all()

pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)

transpiled1 = pass_manager.run(circuit1)
transpiled2 = pass_manager.run(circuit2)

sampler = Sampler(mode=backend)
# Default shots to use if not specified in run()
sampler.options.default_shots = 500
# Sample two circuits at 128 shots each.
sampler.run([transpiled1, transpiled2], shots=128)
<RuntimeJobV2('dab7ld3vpcac73ddek50', 'sampler')>

Casos especiais​

Shots​

O método SamplerV2.run aceita dois argumentos: uma lista de PUBs, cada um dos quais pode especificar um valor de shots específico do PUB, e um argumento de palavra-chave shots. Esses valores de shots fazem parte da interface de execução do Sampler e são independentes das opções do Sampler Runtime. Eles têm precedência sobre quaisquer valores especificados como opções para cumprir com a abstração do Sampler.

Porém, se shots não for especificado por nenhum PUB nem no argumento de palavra-chave run (ou se forem todos None), então o valor de shots das opções é usado, principalmente default_shots.

Em resumo, esta é a ordem de precedência para especificar shots no Sampler, para qualquer PUB particular:

  1. Se o PUB especificar shots, usar esse valor.

  2. Se o argumento de palavra-chave shots for especificado em run, usar esse valor.

  3. Se twirling estiver habilitado, então o produto de num_randomizations e shots_per_randomization, conforme especificado nas opções de twirling, é usado.

  4. Se sampler.options.default_shots for especificado, usar esse valor.

Portanto, se shots forem especificados em todos os lugares possíveis, o de maior precedência (shots especificados no PUB) é usado.

nota

Embora os shots especificados no PUB e em run tenham maior precedência, o job falha se twirling estiver habilitado e o produto de num_randomizations e shots_per_randomization for menor que o valor de shots. Nesse cenário, o SamplerV2 não consegue alocar os shots entre os num_randomizations especificados.

Exemplo:

from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit_ibm_runtime import SamplerV2 as Sampler
from qiskit.circuit.library import random_iqp
from qiskit.transpiler import generate_preset_pass_manager

service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

circuit1 = random_iqp(3)
circuit1.measure_all()
circuit2 = random_iqp(3)
circuit2.measure_all()

pass_manager = generate_preset_pass_manager(
    optimization_level=3, backend=backend
)

transpiled1 = pass_manager.run(circuit1)
transpiled2 = pass_manager.run(circuit2)

# Setting shots during primitive initialization
sampler = Sampler(mode=backend, options={"default_shots": 4096})

# Setting options after primitive initialization
# This uses auto-complete.
sampler.options.default_shots = 2000

# This does bulk update.  The value for default_shots is overridden
# if you specify shots with run() or in the PUB.
sampler.options.update(
    default_shots=1024, dynamical_decoupling={"sequence_type": "XpXm"}
)

# Sample two circuits at 128 shots each.
sampler.run([transpiled1, transpiled2], shots=128)
<RuntimeJobV2('dab7lf3vpcac73ddek8g', 'sampler')>

Opções disponíveis​

A tabela a seguir documenta as opções da versão mais recente do qiskit-ibm-runtime. Para ver versões anteriores das opções, visite a referência de API do qiskit-ibm-runtime e selecione uma versão anterior.

default_shots

O número total de shots a usar por circuito por configuração.

Opções: Inteiro >= 0

Padrão: None

Documentação de API de default_shots

dynamical_decoupling

Controla as configurações de mitigação de erros por desacoplamento dinâmico.

Documentação de API de dynamical_decoupling

dynamical_decoupling.enable

Opções: True, False

Padrão: False

dynamical_decoupling.extra_slack_distribution

Opções: middle, edges

Padrão: middle

dynamical_decoupling.scheduling_method

Opções: asap, alap Padrão: alap

dynamical_decoupling.sequence_type

Opções: XX, XpXm, XY4 Padrão: XX

dynamical_decoupling.skip_reset_qubits

Opções: True, False Padrão: False

environment

Documentação de API de environment

environment.job_tags

Lista de tags.

Opções: None

Padrão: None

environment.log_level

Opções: DEBUG, INFO, WARNING, ERROR, CRITICAL

Padrão: WARNING

environment.private

Opções: True, False

Padrão: False

execution

Documentação de API de execution

execution.init_qubits

Se os qubits devem ser redefinidos para o estado fundamental a cada shot.

Opções: True, False

Padrão: True

execution.rep_delay

O atraso entre uma medição e o circuito quântico subsequente.

Opções: Valor no intervalo fornecido por backend.rep_delay_range

Padrão: Fornecido por backend.default_rep_delay

execution.meas_type

Opções: classified, kerneled, avg_kerneled

Padrão: classified

max_execution_time

Limita por quanto tempo um job pode ser executado, em segundos. Consulte o guia de tempo máximo de execução para mais detalhes.

Opções: Número inteiro de segundos no intervalo [1, 10800]

Padrão: 10800 (3 horas)

Documentação de API de max_execution_time

simulator

Opções a passar ao simular um Backend

Documentação de API de simulator

simulator.basis_gates

Opções: Lista de nomes de gates base para desdobrar

Padrão: O conjunto de todos os gates base suportados pelo simulador Qiskit Aer

simulator.coupling_map

Opções: Lista de interações direcionadas entre dois qubits

Padrão: None, o que implica ausência de restrições de conectividade (conectividade total).

simulator.noise_model

Opções: Qiskit Aer NoiseModel, ou sua representação

Padrão: None

simulator.seed_simulator

Opções: Inteiro

Padrão: None

twirling

Opções de twirling

Documentação de API de twirling

twirling.enable_gates

Opções: True, False

Padrão: False

twirling.enable_measure

Opções: True, False

Padrão: False

twirling.num_randomizations

Opções: auto, Inteiro >= 1

Padrão: auto

twirling.shots_per_randomization

Opções: auto, Inteiro >= 1

Padrão: auto

twirling.strategy

Opções: active, active-circuit, active-accum, all

Padrão: active-accum

experimental

Opções experimentais, quando disponíveis.

Compatibilidade de recursos​

Certos recursos de runtime não podem ser usados juntos em um único job. Clique na aba apropriada para ver uma lista de recursos incompatíveis com o recurso selecionado:

Circuitos dinâmicos

Incompatível com:

  • Desacoplamento dinâmico

Outras observações:

  • O twirling de gates pode ser aplicado a circuitos dinâmicos, mas apenas a gates que não estejam dentro de blocos condicionais. O twirling de medição só pode ser aplicado a medições terminais.
  • Compatível com gates fracionários ao usar o qiskit-ibm-runtime v0.42.0 ou posterior.
Desacoplamento dinâmico

Incompatível com:

  • Circuitos dinâmicos
Gates fracionários

Incompatível com:

  • Twirling de gates

Compatível com circuitos dinâmicos ao usar o qiskit-ibm-runtime v0.42.0 ou posterior.

Twirling de gates

Incompatível com:

  • Gates fracionários
  • Stretches

Outras observações:

  • O twirling de gates pode ser aplicado a circuitos dinâmicos, mas apenas a gates que não estejam dentro de blocos condicionais.
  • O twirling de medição só pode ser aplicado a medições terminais.
  • O twirling de medição é incompatível com a instrução store.
  • Não funciona com entanglers não-Clifford.

Próximos passos​

Recomendações
Fonte: IBM Quantum docs — atualizado em 1 de set. de 2026
Versão em inglês no doQumentation — atualizada em 1 de set. de 2026
Problema com o site ou a tradução?Problema de conteúdo? Editar no IBM Quantum docs