Pular para o conteúdo principal

Comece a usar as Qiskit Functions

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime
# 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
from qiskit_ibm_catalog import QiskitFunctionsCatalog

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name
catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")
qesem_function = catalog.load("qedma/qesem")
circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

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

Solicite um teste gratuito para Qiskit Functions de terceiros​

Para solicitar um teste 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.

    • Alterne sua conta no menu 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ê vir "[Your Name]'s Account", você está usando sua conta pessoal, que não é elegível para acesso premium.

  3. Encontre o ID do seu 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.

    If you are working in a trusted Python environment (such as on a personal laptop or workstation), use the save_account() method to save your credentials locally. (Skip to the next step if you are not using a trusted environment, such as a shared or public computer, to authenticate to IBM Quantum Platform.)

    A instância com a qual você se autentica precisa ter o acesso a Qiskit Functions habilitado. Para configurá-lo em uma instância existente, consulte Configurar acesso a Qiskit Functions em uma instância.

    Para usar save_account(), execute python no seu shell e digite 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 o seguinte:

    from qiskit_ibm_catalog import QiskitFunctionsCatalog
    catalog = QiskitFunctionsCatalog()

    Por exemplo:

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

Avoid executing code on an untrusted machine or an external cloud Python environment to minimize security risks. If you must use an untrusted environment (on, for example, a public computer), change your API key after each use by deleting it on the IBM Cloud API keys page to reduce risk. Learn more in the Managing user API keys topic. To initialize the service in this situation, use this code:

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
Proteja sua chave de API

Nunca inclua sua chave no código-fonte, em scripts Python ou em arquivos 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 de forma segura.

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

Listar as funções às quais você tem acesso​

Depois de se autenticar, você pode listar as funções do Qiskit Functions Catalog às quais você 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)]

Executar funções habilitadas​

Depois que um objeto de catálogo for instanciado, você pode selecionar uma função usando catalog.load("<provider/function-name>"):

qesem_function = catalog.load("qedma/qesem")

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

from qiskit.quantum_info import SparsePauliOp

avg_magnetization = SparsePauliOp.from_sparse_list(
    [("Z", [q], 1 / 5) for q in range(5)], num_qubits=5
)

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)
job.job_id
'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'
dica

run() verifica sua capacidade restante e o acesso ao backend antes de submeter o job. Se sua instância estiver sem capacidade, ou se o backend nomeado não estiver acessível, run() gera um erro imediatamente, em vez de deixar o job falhar na fila. Quando a capacidade está baixa, run() emite um aviso. Passe suppress_low_usage_warning=True para silenciá-lo.

job = qesem_function.run(
    pubs=[(circuit, [avg_magnetization, observable])],
    backend_name=backend_name,  # example: "ibm_fez"
    suppress_low_usage_warning=True,
    # options = {
    #     "estimate_time_only": "empirical",
    #     "default_precision": 0.2,  # Default precision is applied to all pubs that don't have a precision specified, see API reference for more details
    #     "max_execution_time": 3600,  # You can specify a maximum QPU time in seconds, see API reference for more details
    #     "transpilation_level": "standard",  # "minimal_with_layout_opt" for minimal transpilation, see API reference for more details
    #     "parallel_execution": True,  # True for parallel execution, see API reference for more details
    # },
)

Verificar o status do job​

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 da Qiskit Function. A prioridade na fila é baseada em quanto você já usou 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 compatível com funções específicas.

    • RUNNING: MAPPING: A função está atualmente mapeando suas entradas clássicas para entradas quânticas.

    • RUNNING: OPTIMIZING_FOR_HARDWARE: A função está otimizando para o QPU selecionado. Isso pode incluir a transpilação do circuito, a caracterização do QPU, a retropropagação de observáveis, entre outros.

    • RUNNING: WAITING_FOR_QPU: A função submeteu um job ao IBM Quantum Compute Service e está aguardando na fila.

    • RUNNING: EXECUTING_QPU: A função tem um job ativo do Quantum Compute.

    • RUNNING: POST_PROCESSING: A função está pós-processando os resultados, o que pode incluir mitigação de erros, mapeamento de resultados quânticos para clássicos, entre outros.

  • DONE: O programa está concluído, e você pode recuperar os dados do resultado com job.result().

  • ERROR: O programa parou de ser executado devido a um problema. Use job.result() para obter a mensagem de erro.

  • CANCELED: O programa foi cancelado por um usuário, pelo serviço ou pelo servidor.

job.status()
'QUEUED'

Recuperar resultados​

Depois que um programa está DONE, você pode usar job.result() para buscar o resultado. Esse formato de saída varia de acordo com cada função, 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.cancel()
'Job has been stopped.'

Acessar os jobs do Quantum Compute associados​

Uma Qiskit Function pode submeter um ou mais jobs do Quantum Compute a um QPU enquanto é executada. Para recuperar os IDs desses jobs de runtime, use job.runtime_jobs(). Você pode usar esses IDs para buscar os objetos de job de runtime de uma instância QiskitRuntimeService, ou para encontrar as workloads no painel do IBM Quantum® Platform.

runtime_job_ids = job.runtime_jobs()
runtime_job_ids

Se uma função agrupa seus jobs de runtime em sessões ou lotes, use job.runtime_sessions() para listar os IDs de sessão. Passe um ID de sessão para job.runtime_jobs() para retornar apenas os jobs de runtime dessa sessão:

sessions = job.runtime_sessions()
if sessions:
    session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])
    print(session_runtime_jobs)
else:
    print("No runtime sessions for this job.")
nota

A lista retornada pode estar vazia. Uma função relata seus jobs de runtime somente quando os envia através do serviço de runtime que a função recebe em tempo de execução, e algumas funções não enviam jobs de runtime diretamente.

Visualizar logs do job​

Use job.logs() para recuperar a saída de log que uma função produz durante a execução. Os logs são úteis para acompanhar o progresso e depurar um job que termina em um estado ERROR.

print(job.logs().splitlines())

Para um job de longa duração que produz muitas linhas de log, use job.filtered_logs() para retornar apenas as linhas que você deseja. Passe uma expressão regular para include para manter as linhas correspondentes, ou para exclude para descartar as linhas correspondentes:

print(job.filtered_logs(include="iteration"))

Listar jobs de Qiskit Functions executados anteriormente​

Você pode usar jobs() para listar todos os jobs submetidos às 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>]

Para restringir os resultados, passe filtros. Filtre por função com function, por status com status, e por data de submissão com created_after. Percorra os resultados com limit e offset:

recent_errors = catalog.jobs(
    function=qesem_function,
    status="ERROR",
    created_after="2024-01-01T00:00:00Z",
    limit=5,
)
recent_errors

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

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

# We can also get that same job with `catalog.job`
job_by_id = catalog.job(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

Buscar 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
Fonte: IBM Quantum docs — atualizado em 3 de set. de 2026
Versão em inglês no doQumentation — atualizada em 3 de set. de 2026
Problema com o site ou a tradução?Problema de conteúdo? Editar no IBM Quantum docs