Pular para o conteúdo principal

Introdução às Qiskit Functions

Notas
  • As Qiskit Functions são um recurso experimental disponível apenas para usuários dos planos IBM Quantum® Premium, Flex e On-Prem (via IBM Quantum Platform API). Estão em status de versão prévia e sujeitas a alterações.
Versões dos pacotes

O código nesta página foi desenvolvido usando os seguintes requisitos. Recomendamos o uso dessas versões ou mais recentes.

qiskit[all]~=1.4.1
qiskit-ibm-runtime~=0.37.0
qiskit-ibm-catalog~=0.4

As Qiskit Functions simplificam e aceleram a descoberta de algoritmos em escala utilitária e o desenvolvimento de aplicações, abstraindo partes do fluxo de trabalho de desenvolvimento de software quântico. Dessa forma, as Qiskit Functions liberam o tempo normalmente gasto escrevendo código manualmente e ajustando experimentos.

Visão geral das Qiskit Functions As Functions vêm em duas formas:

TipoO que faz?Exemplos de entradas e saídasPara quem é?
Circuit functionInterface simplificada para execução de circuits. Abstrai transpilação, supressão de erros e mitigação de errosEntrada: Objetos PUB abstratos
Saída: Valores esperados mitigados		Pesquisadores que usam o Qiskit para descobrir novos algoritmos e aplicações, sem precisar se concentrar na otimização para hardware ou no tratamento de erros. Circuit functions podem ser usadas para construir application functions personalizadas.
Application functionAbrange tarefas de nível mais alto, como exploração de algoritmos e casos de uso específicos de domínio. Abstrai o fluxo de trabalho quântico para resolver tarefas, com entradas e saídas clássicasEntrada: Moléculas, grafos
Saída: Energia do estado fundamental e excitado, valores ótimos para a função de custo		Pesquisadores em domínios não quânticos, integrando o quantum em fluxos de trabalho clássicos de grande escala já existentes, sem precisar mapear dados clássicos para quantum circuits.
# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime

As Functions são fornecidas pela IBM® e por parceiros terceiros. Cada uma tem bom desempenho para características específicas de carga de trabalho e possui opções exclusivas de ajuste de desempenho.

Visão geral das functions disponíveis​

Circuit functions​

NomeFornecedorUso recomendadoBenefícios exclusivos
Tensor-Network Error MitigationAlgorithmiqCargas de trabalho com observáveis de baixo peso e circuits sem loops.Reduz o overhead de medição e a variância, superando as linhas de base padrão de mitigação de erros, como Zero Noise Extrapolation (ZNE) e Probabilistic Error Cancellation (PEC) para classes de circuits relevantes.
QESEM: Error Suppression and Error MitigationQedmaCargas de trabalho que incluem circuits com gates fracionários ou parametrizados, observáveis de alto peso, e fluxos de trabalho que exigem valores esperados imparciais e estimativas precisas de tempo de execução.Produz valores esperados imparciais com menor variância e overhead de recursos, superando ZNE e PEC para classes de circuits relevantes.
Performance ManagementQ-CTRLCargas de trabalho que contêm circuits paramétricos, circuits profundos ou que requerem muitas execuções de circuits.Aplica automaticamente supressão de erros baseada em IA a algoritmos quânticos, maximizando o desempenho dos dispositivos IBM para entregar resultados precisos enquanto reduz o número de shots, o tempo de computação e o custo necessários.

Método sem overhead que melhora a precisão de execução para as primitivas Sampler e Estimator, compatível com qualquer peso de observáveis.

Application functions​

NomeFornecedorUso recomendadoBenefícios exclusivos
QUICK-PDEColibriTDUse computação quântica para PDEs de múltipla física.

Prepare fluxos de trabalho de simulação para hardware quântico, mantendo controle total sobre os parâmetros de modelagem quântica e física.		Oferece um framework híbrido VQA robusto que entrega soluções de PDE precisas e escaláveis por meio de codificação de soluções avançada e métodos espectrais, tornando-o um ponto de entrada ideal para equipes que buscam construir capacidades de simulação prontas para o quantum.
Quantum Portfolio OptimizerGlobal Data QuantumCargas de trabalho para otimização financeira, buscando estratégias ótimas de portfólio ao longo do tempo enquanto minimizam o risco e maximizam os retornos, permitindo backtesting de estratégias de negociação.Resolve problemas de otimização combinatória por meio de uma adaptação altamente especializada do algoritmo quântico VQE para esse caso de uso financeiro, usando estratégias de execução e otimizadores otimizados, junto com técnicas de mitigação de erros conscientes do ruído adaptadas à otimização de portfólios.
HI-VQE ChemistryQunova ComputingCargas de trabalho em química computacional, simulação molecular, ciência de materiais ou qualquer simulação de Hamiltoniano que exija a resolução de problemas de estrutura eletrônica de muitos corpos.Resolve estruturas eletrônicas moleculares usando SQD aprimorado com precisão química (1 kcal/mol, 1,6 mHa) para problemas modelados com 40 a 60 qubits, superando algumas soluções clássicas em supercomputadores ou SQD padrão em velocidade de convergência ou precisão, respectivamente, por ordens de magnitude.
Iskay Quantum OptimizerKipu QuantumCargas de trabalho de otimização como agendamento, logística, roteamento e problemas QUBO/HUBO.

Métodos integrados e ajustáveis de pré e pós-processamento clássico para a rotina de otimização quântica.

Entrega vantagem de tempo de execução sobre solvers clássicos (CPLEX, simulated annealing e busca tabu) em benchmarks HUBO selecionados.

Market Split ms_5_100, um desafio difícil, resolvido em horas (veja este tutorial).
Singularity Machine LearningMultiverse ComputingFluxos de trabalho de classificação de machine learning clássico que poderiam se beneficiar de maior precisão ou eficiência computacional ao aproveitar a otimização quântica executada em hardware IBM.Entrega precisão comparável ou superior a modelos clássicos como Random Forest ou XGBoost, operando com significativamente menos learners e um ensemble mais compacto.

Impulsionado por votação otimizada quanticamente, seleciona os learners mais informativos e refina os limites de decisão, resultando em maior eficiência, menor complexidade do modelo e desempenho mais robusto.
Optimization SolverQ-CTRLProblemas de otimização binária ou qualquer problema combinatório que possa ser mapeado para uma função de custo binária.

Funções de custo de qualquer ordem e tamanhos de problema até a escala máxima do dispositivo são suportados.		Solução de otimização quântica end-to-end, consciente do ruído, que permite entradas de definições de problemas de alto nível e encontra automaticamente soluções precisas para problemas combinatórios classicamente desafiadores em hardware quântico de escala utilitária.

Abstrai a complexidade ao lidar com supressão de erros, mapeamento eficiente e otimização híbrida quantum-clássica para resolver tarefas de otimização na escala completa do dispositivo sem necessidade de profundo conhecimento em quantum.

Comece a usar as Qiskit Functions​

Usuários dos planos Premium, Flex e On-Prem (por meio da IBM Quantum Platform API) podem começar a usar as IBM Qiskit Functions gratuitamente ou adquirir uma licença de um dos parceiros que contribuíram com uma function para o catálogo.

Solicite um período de avaliação gratuito para Qiskit Functions de terceiros​

Para solicitar um novo período de avaliação gratuito, navegue até o Qiskit Functions Catalog e explore o painel de detalhes. Clique em Request a free trial e preencha as informações exigidas pelo parceiro da Functions, incluindo o AccessGroupId do IBM Cloud:

  1. Navegue até o IBM Cloud IAM.
  2. Verifique a elegibilidade.
    • Mude sua conta na barra superior para uma com o seguinte formato: XXXXXXX - [Organization Name]
    • Certifique-se de que a organização é a mesma associada à sua conta Premium.
    • Se você ver "[Your Name]'s Account", está usando sua conta pessoal, que não é elegível para acesso premium.
  3. Encontre seu ID de grupo de acesso.
    • Clique no nome de um grupo.
    • Clique em Details.
    • Copie o ID do grupo de acesso. Ele deve começar com AccessGroup-.

Instale o cliente do Qiskit Functions Catalog​

  1. Para começar a usar as Qiskit Functions, instale o cliente do IBM Qiskit Functions Catalog:

    pip install qiskit-ibm-catalog

  2. Recupere sua chave de API no painel do IBM Quantum Platform e ative seu ambiente virtual Python. Consulte as instruções de instalação caso ainda não tenha um ambiente virtual configurado.

    Se você está trabalhando em um ambiente Python confiável (como em um laptop ou estação de trabalho pessoal), use o método save_account() para salvar suas credenciais localmente. (Pule para o próximo passo se não estiver usando um ambiente confiável, como um computador compartilhado ou público, para se autenticar no IBM Quantum Platform.)

    Para usar save_account(), execute python no seu terminal e insira o seguinte:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog

    QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

    Digite exit(). A partir de agora, sempre que precisar se autenticar no serviço, você pode carregar suas credenciais com

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()
# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

  1. Evite executar código em uma máquina não confiável ou em um ambiente Python de nuvem externo para minimizar riscos de segurança. Se você precisar usar um ambiente não confiável (por exemplo, em um computador público), altere sua chave de API após cada uso excluindo-a na página de chaves de API do IBM Cloud para reduzir o risco. Saiba mais no tópico Managing user API keys. Para inicializar o serviço nessa situação, expanda a seção a seguir para ver o código que você pode usar:

    Inicialize o serviço em um ambiente não confiável
    from qiskit_ibm_catalog import QiskitFunctionsCatalog

    # After using the following code, delete your API key on the IBM Quantum Platform home dashboard
    catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard
    cuidado

    Proteja sua chave de API! Nunca inclua sua chave no código-fonte, script Python ou arquivo de notebook. Ao compartilhar código com outras pessoas, certifique-se de que sua chave de API não esteja incorporada diretamente no script Python. Em vez disso, compartilhe o script sem a chave e forneça instruções para configurá-la com segurança.

    Se você acidentalmente compartilhar sua chave com alguém ou incluí-la em controle de versão como o Git, revogue imediatamente sua chave excluindo-a na página de chaves de API do IBM Cloud para reduzir o risco. Saiba mais no tópico Managing user API keys.

  2. Após a autenticação, você pode listar as functions do Qiskit Functions Catalog às quais tem acesso:

catalog.list()
[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

Execute as functions habilitadas​

Após instanciar um objeto de catálogo, você pode selecionar uma function usando catalog.load(provider/function-name):

ibm_cf = catalog.load("ibm/circuit-function")

Cada Qiskit Function possui entradas, opções e saídas personalizadas. Consulte as páginas de documentação específicas da function que você deseja executar para obter mais informações. Por padrão, todos os usuários podem executar apenas um job de function por vez:

# This cell is hidden from users
# It gets these details programmatically so we can test this notebook
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.circuit.random import random_circuit

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name

circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits
job = ibm_cf.run(
    pubs=[(circuit, observable)],
    instance=instance,
    backend_name=backend_name,  # E.g. "ibm_fez"
)

job.job_id
'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'

Verifique o status do job​

dica

Atualmente, a tabela de cargas de trabalho do IBM Quantum reflete apenas cargas de trabalho do Qiskit Runtime. Use job.status() para ver o status atual da sua carga de trabalho do Qiskit Function.

Com o job_id da sua Qiskit Function, você pode verificar o status dos jobs em execução. Isso inclui os seguintes status:

  • QUEUED: O programa remoto está na fila do Qiskit Function. A prioridade na fila é baseada no quanto você utilizou as Qiskit Functions.
  • INITIALIZING: O programa remoto está iniciando; isso inclui a configuração do ambiente remoto e a instalação de dependências.
  • RUNNING: O programa está em execução. Isso também inclui vários status mais detalhados, se suportados por functions específicas
    • RUNNING: MAPPING": A function está atualmente mapeando suas entradas clássicas para entradas quânticas
    • RUNNING: OPTIMIZING_FOR_HARDWARE": A function está otimizando para o QPU selecionado. Isso pode incluir transpilação de Circuit, caracterização do QPU, backpropagation de observáveis, entre outros
    • RUNNING: WAITING_FOR_QPU: A function enviou um job ao Qiskit Runtime e está aguardando na fila
    • RUNNING: EXECUTING_QPU: A function tem um job ativo no Qiskit Runtime
    • RUNNING: POST_PROCESSING: A function está fazendo pós-processamento dos resultados. Isso pode incluir mitigação de erros, mapeamento de resultados quânticos para clássicos, entre outros
  • DONE: O programa foi concluído e você pode recuperar os dados do resultado com job.results().
  • ERROR: O programa parou de executar por causa de um problema. Use job.result() para obter a mensagem de erro.
  • CANCELED: O programa foi cancelado; seja por um usuário, pelo serviço ou pelo servidor.
job.status()
'QUEUED'

Recupere os resultados​

Após um programa estar DONE, você pode usar job.results() para buscar o resultado. O formato de saída varia com cada function, então certifique-se de seguir a documentação específica:

result = job.result()
print(result)
PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), metadata={'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32})], metadata={'dynamical_decoupling': {'enable': True, 'sequence_type': 'XX', 'extra_slack_distribution': 'middle', 'scheduling_method': 'alap'}, 'twirling': {'enable_gates': False, 'enable_measure': True, 'num_randomizations': 'auto', 'shots_per_randomization': 'auto', 'interleave_randomizations': True, 'strategy': 'active-accum'}, 'resilience': {'measure_mitigation': True, 'zne_mitigation': False, 'pec_mitigation': False}, 'version': 2})

Você também pode cancelar um job a qualquer momento:

job.stop()
'Job has been stopped.'

Liste os jobs executados anteriormente com as Qiskit Functions​

Você pode usar jobs() para listar todos os jobs enviados para as Qiskit Functions:

old_jobs = catalog.jobs()
old_jobs
[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

Se você já tem o ID de job para um determinado job, pode recuperá-lo com catalog.get_job_by_id():

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with get_job_by_id
job_by_id = catalog.get_job_by_id(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)
f6c29f49-4d5f-4fff-aca6-2e9a115b9763

Busque mensagens de erro​

Se o status de um programa for ERROR, use job.error_message() para buscar a mensagem de erro da seguinte forma:

job.error_message()
qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

Próximos passos​

Recomendações