{ "cells": [ { "cell_type": "markdown", "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", "metadata": {}, "source": [ "---\n", "title: \"Comece a usar o Qiskit Functions\"\n", "description: \"Como realizar tarefas comuns, desde a instalação e autenticação até a verificação do status das tarefas e a obtenção de mensagens de erro\"\n", "---\n", "\n", "{/* cspell:ignore Jarman, HIVQE, Cadavid, Chandarana, Leclerc, Sachdeva, HUBO, Filippov, Downfolding, Aharonov, Mundada, Yamauchi, supersymmetric, Paterakis, Gharibyan, Jaffali, Pellow */}\n", "\n" ] }, { "cell_type": "markdown", "id": "b7c85b80", "metadata": { "tags": [ "version-info" ] }, "source": [ "\n" ] }, { "cell_type": "markdown", "id": "04b0ccd6-e960-484b-8696-81b2d567cba2", "metadata": {}, "source": [ "\n", "\n", "# Comece a usar o Qiskit Functions\n", "\n", "Os usuários dos planos Premium, Flex e “ On-Prem ” (por meio da API IBM Quantum Platform ) podem começar a usar o “ IBM ” Qiskit Functions gratuitamente ou adquirir uma licença junto a um dos parceiros que contribuíram com uma função para o catálogo.\n", "\n", "\n", "\n", "## Solicite uma avaliação gratuita do software de gerenciamento de ativos de terceiros ( Qiskit Functions )\n", "\n", "Para solicitar uma avaliação gratuita, acesse o site [Qiskit Functions Catalog](/functions) e explore o painel de detalhes. Clique `Request a free trial` e preencha as informações solicitadas pelo parceiro da Functions, incluindo o IBM Cloud `AccessGroupId`:\n", "\n", "1. Acesse o [IBM Cloud IAM](http://cloud.ibm.com/iam/groups).\n", "2. Verifique se você se qualifica.\n", " * Na barra de menu do cabeçalho, alterne sua conta para uma com o seguinte formato: `XXXXXXX - [Organization Name]`\n", " * Verifique se a organização é a mesma associada à sua conta Premium.\n", " * Se você vir “Conta \\[de] \\[Seu Nome]”, significa que está usando sua conta *pessoal*, que não dá direito ao acesso premium.\n", "3. Descubra o ID do seu grupo de acesso.\n", " * Clique no nome de um grupo.\n", " * Clique **em “Detalhes** ”.\n", " * Copie o ID do grupo de acesso. Deve começar com `AccessGroup-`.\n", "\n", "\n", "\n", "\n", "\n", "## Instale o cliente do Qiskit Functions Catalog\n", "\n", "1. Para começar a usar o Qiskit Functions, instale o cliente IBM Qiskit Functions Catalog :\n", "\n", " ```\n", " pip install qiskit-ibm-catalog\n", " ```\n", "\n", "2. Recupere sua chave de API no [painel IBM Quantum Platform](/) e ative seu ambiente virtual Python. Consulte as [instruções de instalação](/docs/guides/install-qiskit#local) caso ainda não tenha um ambiente virtual configurado.\n", "\n", " **Se você estiver trabalhando em um ambiente confiável do Python (como em um laptop pessoal ou estação de trabalho),** use o `save_account()` método para salvar suas credenciais localmente. ( [Pule para a próxima etapa](#functions-untrusted) se você não estiver usando um ambiente confiável, como um computador compartilhado ou público, para se autenticar no site IBM Quantum Platform.)\n", "\n", " `save_account()`Para usar, execute `python` no seu shell e, em seguida, digite o seguinte:\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", " QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n", " ```\n", "\n", " Digite `exit()`. A partir de agora, sempre que precisar se autenticar no serviço, você poderá carregar suas credenciais da seguinte forma:\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", " catalog = QiskitFunctionsCatalog()\n", " ```\n", "\n", " Por exemplo:\n", "\n", " \n", "\n", "3. **Evite executar código em uma máquina não confiável ou em um ambiente externo de nuvem Python para minimizar os riscos de segurança.** Se 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 IBM Cloud](https://cloud.ibm.com/iam/apikeys) para reduzir o risco. Saiba mais no tópico “[Gerenciamento de chaves de API de usuários](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ”. Para inicializar o serviço nessa situação, use este código:\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", " # After using the following code, delete your API key on the\n", " # IBM Quantum Platform home dashboard\n", " catalog = QiskitFunctionsCatalog(token=\"\") # Use the 44-character\n", " # API_KEY you created and saved from the IBM Quantum Platform Home dashboard\n", " ```\n", "\n", " \n", " **Nunca inclua sua chave no código-fonte, em scripts do `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á-lo com segurança.\n", "\n", " Se você compartilhar sua chave acidentalmente com alguém ou a incluir em um sistema de controle de versão como Git, revogue-a imediatamente excluindo-a na página [de chaves da API IBM Cloud](https://cloud.ibm.com/iam/apikeys) para reduzir os riscos. Saiba mais no tópico “[Gerenciamento de chaves de API de usuários](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ”.\n", " \n", "\n", "\n", "\n", "## Liste as funções às quais você tem acesso\n", "\n", "Após se autenticar, você pode listar as funções do Qiskit Functions Catalog às quais tem acesso:\n", "\n", "\n", "\n", "\n", "\n", "## Verificar os back-ends disponíveis e a capacidade\n", "\n", "Antes de executar uma função, verifique quais back-ends sua instância consegue acessar e quanta capacidade de execução ainda resta. `run()` realiza as mesmas verificações antes de enviar um trabalho, para que você possa detectar antecipadamente problemas de capacidade e de back-end.\n", "\n", "Liste os back-ends aos quais sua instância tem acesso. Os resultados são armazenados em cache por catálogo. Passe o mouse `refresh_cache=True` para atualizá-los.\n", "\n", "\n", "\n", "`backends()` aceita os mesmos filtros que o do site Qiskit Runtime[`QiskitRuntimeService.backends()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#backends). Por exemplo, liste apenas os backends com pelo menos 127 qubits ou passe uma função `filters` para um controle mais preciso:\n", "\n", "\n", "\n", "Pesquise um único backend e confirme o acesso:\n", "\n", "\n", "\n", "Você também pode selecionar o backend com o menor número de tarefas pendentes. `least_busy()` usa os mesmos filtros que o `Qiskit Runtime` [`QiskitRuntimeService.least_busy()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#least_busy):\n", "\n", "\n", "\n", "Use `usage()` para verificar a capacidade restante de autonomia. Retorna `usage_remaining_seconds` e `usage_limit_reached` para a instância ativa.\n", "\n", "\n", "\n", "Por exemplo, verifique a capacidade restante antes de executar um longo lote de tarefas e interrompa o processo se não houver capacidade suficiente para concluí-lo:\n", "\n", "\n", "\n", "\n", "\n", "## Executar funções habilitadas\n", "\n", "`catalog.load(\"\")`Depois que um objeto de catálogo for instanciado, você poderá selecionar uma função usando:\n", "\n", "\n", "\n", "Cada função do Qiskit possui entradas, opções e saídas personalizadas. Consulte as páginas de documentação específicas da função que você deseja executar para obter mais informações. Por padrão, todos os usuários podem executar apenas uma tarefa de função por vez:\n", "\n", "\n", "\n", "\n", " `run()` verifica a capacidade restante e o acesso ao backend antes de enviar o trabalho. Se sua instância estiver sem capacidade ou se o backend que você indicou não estiver acessível, `run()` o sistema gera um erro imediatamente, em vez de deixar a tarefa falhar na fila. Quando a capacidade está baixa, `run()` emite um aviso. Toque `suppress_low_usage_warning=True` para desligar o som.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "## Verificar o status do trabalho\n", "\n", "`job_id`Com a função Qiskit, você pode verificar o status dos trabalhos em execução. Isso inclui os seguintes status:\n", "\n", "* **`QUEUED`**: O programa remoto está na fila de funções do Qiskit. A prioridade na fila depende do quanto você já utilizou o Qiskit Functions.\n", "* **`INITIALIZING`**: O programa remoto está sendo iniciado; isso inclui a configuração do ambiente remoto e a instalação das dependências.\n", "* **`RUNNING`**: O programa está em execução. Isso também inclui vários status mais detalhados, caso sejam suportados por funções específicas.\n", " * **`RUNNING: MAPPING`**: Atualmente, a função está mapeando suas entradas clássicas para entradas quânticas.\n", " * **`RUNNING: OPTIMIZING_FOR_HARDWARE`**: A função está sendo otimizada para a QPU selecionada. Isso poderia incluir a transpilagem de circuitos, a caracterização da QPU, a retropropagação de observáveis e assim por diante.\n", " * **`RUNNING: WAITING_FOR_QPU`**: A função enviou um trabalho para Qiskit Runtime e está aguardando na fila.\n", " * **`RUNNING: EXECUTING_QPU`**: A função possui uma tarefa ativa do Qiskit Runtime.\n", " * **`RUNNING: POST_PROCESSING`**: A função consiste no pós-processamento dos resultados, o que pode incluir a mitigação de erros, o mapeamento de resultados quânticos para o clássico e assim por diante.\n", "* **`DONE`**: O programa está concluído, e você pode recuperar os dados dos resultados com `job.result()`.\n", "* **`ERROR`**: O programa parou de funcionar devido a um problema. Use `job.result()` para obter a mensagem de erro.\n", "* **`CANCELED`**: O programa foi cancelado por um usuário, pelo serviço ou pelo servidor.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "## Exibir resultados\n", "\n", "Depois que um programa for executado `DONE`, você pode usar `job.result()` para obter o resultado. Esse formato de saída varia de acordo com cada função; portanto, certifique-se de seguir a documentação específica:\n", "\n", "\n", "\n", "Você também pode cancelar um trabalho a qualquer momento:\n", "\n", "\n", "\n", "\n", "\n", "## Acesse as vagas associadas no site Qiskit Runtime\n", "\n", "Uma função do Qiskit pode enviar um ou mais tarefas do tipo “ Qiskit Runtime ” para uma QPU enquanto está em execução. Para recuperar os IDs desses trabalhos em execução, use `job.runtime_jobs()`. Você pode usar esses IDs para recuperar os objetos de tarefa em execução de uma instância `QiskitRuntimeService` ou para localizar as cargas de trabalho no painel do IBM Quantum® Platform.\n", "\n", "\n", "\n", "Se uma função agrupar suas tarefas em tempo de execução em sessões ou lotes, use `job.runtime_sessions()` para listar os IDs das sessões. Passe um ID de sessão para `job.runtime_jobs()` a fim de retornar apenas os trabalhos em execução nessa sessão:\n", "\n", "\n", "\n", "\n", " A lista retornada pode estar vazia. Uma função reporta seus trabalhos em tempo de execução somente quando os envia por meio do serviço de tempo de execução que a função recebe durante a execução, e algumas funções não enviam trabalhos em tempo de execução diretamente.\n", "\n", "\n", "\n", "\n", "## Visualizar logs de tarefa\n", "\n", "Use `job.logs()` para recuperar a saída de log que uma função gera durante sua execução. Os registros são úteis para acompanhar o andamento e para depurar um trabalho que termine em um determinado estado `ERROR` .\n", "\n", "\n", "\n", "Para uma tarefa de longa duração que gera muitas linhas de log, use `job.filtered_logs()` para retornar apenas as linhas desejadas. Passe uma expressão regular para `include` para manter as linhas correspondentes ou para `exclude` para descartar as linhas correspondentes:\n", "\n", "\n", "\n", "\n", "\n", "## Listar tarefas do Qiskit Functions executadas anteriormente\n", "\n", "Você pode usar `jobs()` para listar todos os trabalhos enviados para Qiskit Functions :\n", "\n", "\n", "\n", "Para refinar os resultados, aplique filtros. Filtre por função com `function`, por status com `status`e por data de envio com `created_after`. Navegue pelos resultados usando `limit` e `offset`:\n", "\n", "\n", "\n", "Se você já tiver o ID de um determinado trabalho, poderá recuperá-lo com `catalog.job()`:\n", "\n", "\n", "\n", "\n", "\n", "## Buscar mensagens de erro\n", "\n", "Se o status de um programa for `ERROR`, use `job.error_message()` para obter a mensagem de erro da seguinte maneira:\n", "\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "6699700c-ae26-4c10-8d09-05ee77a1afb7", "metadata": { "tags": [ "id-load-credentials" ] }, "outputs": [], "source": [ "# Load saved credentials\n", "from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", "catalog = QiskitFunctionsCatalog(channel=\"ibm_quantum_platform\")" ] }, { "cell_type": "code", "execution_count": 2, "id": "275b4b94-7656-403e-8997-941c03c7ef55", "metadata": { "tags": [ "id-list-functions" ] }, "outputs": [ { "data": { "text/plain": [ "[QiskitFunction(qunova/hivqe-chemistry),\n", " QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),\n", " QiskitFunction(algorithmiq/tem),\n", " QiskitFunction(qedma/qesem),\n", " QiskitFunction(multiverse/singularity),\n", " QiskitFunction(ibm/circuit-function),\n", " QiskitFunction(q-ctrl/optimization-solver),\n", " QiskitFunction(colibritd/quick-pde),\n", " QiskitFunction(q-ctrl/performance-management),\n", " QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "catalog.list()" ] }, { "cell_type": "code", "execution_count": null, "id": "6f2167d5-2dbb-4b5a-8639-8d0712a943c6", "metadata": { "tags": [ "id-catalog" ] }, "outputs": [], "source": [ "catalog.backends()" ] }, { "cell_type": "code", "execution_count": null, "id": "f6252b70-c063-4f81-c273-6e5f8a02c145", "metadata": { "tags": [ "id-backends-filter" ] }, "outputs": [], "source": [ "catalog.backends(min_num_qubits=127)" ] }, { "cell_type": "code", "execution_count": null, "id": "fec85827-af64-40db-a4a8-1173d6378e52", "metadata": { "tags": [ "id-backend" ] }, "outputs": [], "source": [ "catalog.backend(\"ibm_fez\")" ] }, { "cell_type": "code", "execution_count": null, "id": "aca1a365-bddf-45b9-bd6d-bab893eac30b", "metadata": { "tags": [ "id-least-busy" ] }, "outputs": [], "source": [ "catalog.least_busy(min_num_qubits=127)" ] }, { "cell_type": "code", "execution_count": null, "id": "d77a9e2a-a581-43e4-ad49-e5e92bfaf914", "metadata": { "tags": [ "id-usage" ] }, "outputs": [], "source": [ "catalog.usage()" ] }, { "cell_type": "code", "execution_count": null, "id": "9446ba1c-9369-47e2-8274-6cf8166fd4b9", "metadata": { "tags": [ "id-usage-example" ] }, "outputs": [], "source": [ "usage = catalog.usage()\n", "if usage[\"usage_remaining_seconds\"] < 600:\n", " raise SystemExit(\"Not enough capacity remaining to start this batch.\")" ] }, { "cell_type": "code", "execution_count": null, "id": "7c570541-599a-48c6-b735-c378b3e2ba02", "metadata": { "tags": [ "id-low-capacity" ] }, "outputs": [], "source": [ "job = ibm_cf.run(\n", " pubs=[(circuit, observable)],\n", " instance=instance,\n", " backend_name=backend_name, # E.g. \"ibm_fez\"\n", " suppress_low_usage_warning=True,\n", ")" ] }, { "cell_type": "code", "execution_count": 3, "id": "65a26da5-f537-44ed-9cb4-b335518d009d", "metadata": { "tags": [ "id-run-functions" ] }, "outputs": [], "source": [ "ibm_cf = catalog.load(\"ibm/circuit-function\")" ] }, { "cell_type": "code", "execution_count": 5, "id": "9b9a7a3c-cc98-4c19-93cd-f59793515c70", "metadata": { "tags": [ "id-one-function" ] }, "outputs": [ { "data": { "text/plain": [ "'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job = ibm_cf.run(\n", " pubs=[(circuit, observable)],\n", " instance=instance,\n", " backend_name=backend_name, # E.g. \"ibm_fez\"\n", ")\n", "\n", "job.job_id" ] }, { "cell_type": "code", "execution_count": 6, "id": "d0574d73-0966-4426-b2f5-94df72a07caa", "metadata": { "tags": [ "id-status" ] }, "outputs": [ { "data": { "text/plain": [ "'QUEUED'" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.status()" ] }, { "cell_type": "code", "execution_count": 7, "id": "45e302d8-f3c2-4868-8b7c-6d451f6119a9", "metadata": { "tags": [ "id-retrieve" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(), stds=np.ndarray(), ensemble_standard_error=np.ndarray()), 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})\n" ] } ], "source": [ "result = job.result()\n", "print(result)" ] }, { "cell_type": "code", "execution_count": 8, "id": "0e55d4d6-4680-4671-907f-35aac16971ef", "metadata": { "tags": [ "id-cancel" ] }, "outputs": [ { "data": { "text/plain": [ "'Job has been stopped.'" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "job.cancel()" ] }, { "cell_type": "code", "execution_count": null, "id": "a1f0c2d4-7b1e-4a3c-9d2e-1f0a3b5c7d90", "metadata": { "tags": [ "id-runtime-jobs" ] }, "outputs": [], "source": [ "runtime_job_ids = job.runtime_jobs()\n", "runtime_job_ids" ] }, { "cell_type": "code", "execution_count": null, "id": "b2e1d3c5-8c2f-4b4d-8e3f-2a1b4c6d8e01", "metadata": { "tags": [ "id-runtime-sessions" ] }, "outputs": [], "source": [ "sessions = job.runtime_sessions()\n", "session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])\n", "session_runtime_jobs" ] }, { "cell_type": "code", "execution_count": null, "id": "c3f2e4d6-9d30-4c5e-9f40-3b2c5d7e9f12", "metadata": { "tags": [ "id-logs" ] }, "outputs": [], "source": [ "print(job.logs().splitlines())" ] }, { "cell_type": "code", "execution_count": null, "id": "d4030f5e-ae41-4d6f-a051-4c3d6e80af23", "metadata": { "tags": [ "id-filtered-logs" ] }, "outputs": [], "source": [ "print(job.filtered_logs(include=\"iteration\"))" ] }, { "cell_type": "code", "execution_count": 9, "id": "4becfe13-68dd-481d-bb43-fc502c254623", "metadata": { "tags": [ "id-all-jobs" ] }, "outputs": [ { "data": { "text/plain": [ "[,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ,\n", " ]" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "old_jobs = catalog.jobs()\n", "old_jobs" ] }, { "cell_type": "code", "execution_count": null, "id": "e5141a6f-bf52-4e70-b162-5d4e7f91b034", "metadata": { "tags": [ "id-filter-jobs" ] }, "outputs": [], "source": [ "recent_errors = catalog.jobs(\n", " function=ibm_cf,\n", " status=\"ERROR\",\n", " created_after=\"2024-01-01T00:00:00Z\",\n", " limit=5,\n", ")\n", "recent_errors" ] }, { "cell_type": "code", "execution_count": 18, "id": "18d87f07-8a8e-4b93-80d0-7c07e49272e2", "metadata": { "tags": [ "id-by-id" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "f6c29f49-4d5f-4fff-aca6-2e9a115b9763\n" ] } ], "source": [ "# First, get the most recent job that has been executed.\n", "latest_job = old_jobs[0]\n", "\n", "# We can also get that same job with `catalog.job`\n", "job_by_id = catalog.job(latest_job.job_id)\n", "\n", "# Verify that the job is the same using both retrieval methods.\n", "assert job_by_id.job_id == latest_job.job_id\n", "\n", "# Print the job_id for this job.\n", "print(job_by_id.job_id)" ] }, { "cell_type": "code", "execution_count": 1, "id": "68412b66-8022-4dd3-b140-ec33e119693b", "metadata": { "tags": [ "id-fetch-errors" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'\n" ] } ], "source": [ "job.error_message()" ] }, { "cell_type": "markdown", "id": "709b39ca-5dbd-42c0-830c-1248c2e5d63c", "metadata": {}, "source": [ "\n", "\n", "## Próximas etapas\n", "\n", "\n", " * [Explore as funções do circuito](/docs/guides/algorithmiq-tem) para criar novos algoritmos e aplicativos, sem precisar se preocupar com a transpilagem ou o tratamento de erros.\n", " * [Explore as funções da aplicação](/docs/guides/q-ctrl-optimization-solver) para resolver tarefas específicas do domínio, com entradas e saídas clássicas.\n", " * Consulte a [documentação de referência da API](/docs/api/functions/index) em Qiskit Functions.\n", " * Para ter uma experiência prática, experimente alguns [tutoriais](/docs/tutorials/index#leverage-qiskit-capabilities) que mostram o que é o “ Qiskit Functions ”.\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3" } }, "nbformat": 4, "nbformat_minor": 4 }