{ "cells": [ { "cell_type": "markdown", "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", "metadata": {}, "source": [ "---\n", "title: \"Empieza a utilizar « Qiskit Functions »\"\n", "description: \"Cómo realizar tareas habituales, desde la instalación y la autenticación hasta la comprobación del estado de los trabajos y la consulta de mensajes de error\"\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", "# Empieza a utilizar « Qiskit Functions »\n", "\n", "Los usuarios de los planes Premium, Flex y « On-Prem » (a través de la API de IBM Quantum Platform ) pueden empezar a utilizar « IBM » Qiskit Functions de forma gratuita, o bien adquirir una licencia a través de uno de los socios que han aportado una función al catálogo.\n", "\n", "\n", "\n", "## Solicita una prueba gratuita de la aplicación de terceros « Qiskit Functions »\n", "\n", "Para solicitar una prueba gratuita, entra en [Qiskit Functions Catalog](/functions) y consulta el panel de detalles. `AccessGroupId`Haz clic `Request a free trial` y rellena los datos que solicita el socio de Functions, incluyendo el « IBM Cloud »:\n", "\n", "1. Accede a [« IBM Cloud » IAM](http://cloud.ibm.com/iam/groups).\n", "2. Comprueba si cumples los requisitos.\n", " * Cambia tu cuenta en la barra de menú de la cabecera por una que tenga el siguiente formato: `XXXXXXX - [Organization Name]`\n", " * Asegúrate de que la organización sea la misma que la asociada a tu cuenta Premium.\n", " * Si ves «Cuenta \\[de] \\[tu nombre]», significa que estás utilizando tu cuenta *personal*, que no da derecho al acceso premium.\n", "3. Busca tu ID de grupo de acceso.\n", " * Haz clic en el nombre de un grupo.\n", " * Haz clic en «**Detalles** ».\n", " * Copia el ID del grupo de acceso. Debería empezar por `AccessGroup-`.\n", "\n", "\n", "\n", "\n", "\n", "## Instala el cliente de Qiskit Functions Catalog\n", "\n", "1. Para empezar a utilizar Qiskit Functions, instala el cliente IBM Qiskit Functions Catalog :\n", "\n", " ```\n", " pip install qiskit-ibm-catalog\n", " ```\n", "\n", "2. Obtenga su clave API desde el [panel de control IBM Quantum Platform](/) y active su entorno virtual Python. Consulta las [instrucciones de instalación](/docs/guides/install-qiskit#local) si aún no tienes configurado un entorno virtual.\n", "\n", " **Si trabajas en un entorno de confianza de Python (como un ordenador portátil personal o una estación de trabajo),** utiliza el `save_account()` método para guardar tus credenciales localmente. ( [Pasa al siguiente paso](#functions-untrusted) si no estás utilizando un entorno de confianza, como un ordenador compartido o público, para autenticarte en IBM Quantum Platform.)\n", "\n", " `save_account()`Para utilizarlo, ejecuta `python` en tu terminal y, a continuación, escribe lo siguiente:\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", " QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n", " ```\n", "\n", " Escribe `exit()`. A partir de ahora, cada vez que necesites autenticarte en el servicio, podrás introducir tus credenciales de la siguiente manera:\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", " catalog = QiskitFunctionsCatalog()\n", " ```\n", "\n", " Por ejemplo:\n", "\n", " \n", "\n", "3. **Evita ejecutar código en un equipo no fiable o en un entorno externo de la nube Python para minimizar los riesgos de seguridad.** Si necesita utilizar un entorno no seguro (por ejemplo, en un ordenador público), cambie su clave API después de cada uso eliminándola en la página [de claves API IBM Cloud](https://cloud.ibm.com/iam/apikeys) para reducir el riesgo. Para obtener más información, consulta el tema «[Gestión de claves API de usuario](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ». Para inicializar el servicio en esta situación, utiliza 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 incluyas tu clave en el código fuente, en scripts de « Python » ni en archivos de cuaderno.** Cuando compartas código con otras personas, asegúrate de que tu clave API no esté incrustada directamente en el script Python. En su lugar, comparte el script sin la clave y proporciona instrucciones para configurarlo de forma segura.\n", "\n", " Si compartes tu clave accidentalmente con alguien o la incluyes en un sistema de control de versiones como Git, revoca inmediatamente tu clave eliminándola en la página [de claves de la API IBM Cloud](https://cloud.ibm.com/iam/apikeys) para reducir el riesgo. Para obtener más información, consulta el tema «[Gestión de claves API de usuario](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ».\n", " \n", "\n", "\n", "\n", "## Enumera las funciones a las que puedes acceder\n", "\n", "Una vez que te hayas autenticado, podrás ver la lista de funciones de Qiskit Functions Catalog a las que tienes acceso:\n", "\n", "\n", "\n", "\n", "\n", "## Comprobar los backends disponibles y su capacidad\n", "\n", "Antes de ejecutar una función, comprueba a qué backends puede acceder tu instancia y cuánta capacidad de ejecución te queda. `run()` realiza las mismas comprobaciones antes de enviar un trabajo, lo que te permite detectar a tiempo problemas de capacidad y del backend.\n", "\n", "Enumera los backends a los que puede acceder tu instancia. Los resultados se almacenan en caché por catálogo. Pulsa `refresh_cache=True` para actualizarlas.\n", "\n", "\n", "\n", "Busca un único backend y comprueba el acceso:\n", "\n", "\n", "\n", "También puedes obtener el backend con el menor número de trabajos pendientes:\n", "\n", "\n", "\n", "Utiliza `usage()` para ver la autonomía restante. Devuelve `usage_remaining_seconds` y `usage_limit_reached` para la instancia activa.\n", "\n", "\n", "\n", "Por ejemplo, comprueba la capacidad restante antes de ejecutar una serie larga de trabajos y detén el proceso si no queda suficiente para terminarla:\n", "\n", "\n", "\n", "\n", "\n", "## Ejecutar funciones habilitadas\n", "\n", "`catalog.load(\"\")`Una vez que se ha instanciado un objeto de catálogo, puedes seleccionar una función utilizando:\n", "\n", "\n", "\n", "Cada función de Qiskit tiene entradas, opciones y salidas personalizadas. Consulta las páginas de documentación específicas de la función que deseas ejecutar para obtener más información. Por defecto, todos los usuarios solo pueden ejecutar una tarea de función a la vez:\n", "\n", "\n", "\n", "\n", " `run()` comprueba la capacidad restante y el acceso al servidor antes de enviar el trabajo. Si tu instancia ha agotado su capacidad o no se puede acceder al backend que has especificado, `run()` se genera un error de inmediato, en lugar de dejar que la tarea falle en la cola. Cuando el nivel de capacidad es bajo, `run()` emite una advertencia. Pulsa `suppress_low_usage_warning=True` para silenciarlo.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "## Comprobar estado de trabajo\n", "\n", "`job_id`Con tu función de Qiskit, puedes comprobar el estado de los trabajos en ejecución. Esto incluye los siguientes estados:\n", "\n", "* **`QUEUED`**: El programa remoto se encuentra en la cola de funciones de Qiskit. La prioridad en la cola depende del uso que hayas hecho de Qiskit Functions.\n", "* **`INITIALIZING`**: Se está iniciando el programa remoto; esto incluye la configuración del entorno remoto y la instalación de las dependencias.\n", "* **`RUNNING`**: El programa se está ejecutando. Esto también incluye varios estados más detallados, siempre que las funciones específicas lo permitan.\n", " * **`RUNNING: MAPPING`**: Actualmente, la función está asignando tus entradas clásicas a entradas cuánticas.\n", " * **`RUNNING: OPTIMIZING_FOR_HARDWARE`**: La función se está optimizando para la QPU seleccionada. Esto podría incluir la transpilación de circuitos, la caracterización de la QPU, la retropropagación de observables, etc.\n", " * **`RUNNING: WAITING_FOR_QPU`**: La función ha enviado un trabajo a Qiskit Runtime y está a la espera en la cola.\n", " * **`RUNNING: EXECUTING_QPU`**: La función tiene una tarea de « Qiskit Runtime » activa.\n", " * **`RUNNING: POST_PROCESSING`**: La función consiste en el posprocesamiento de los resultados, lo que puede incluir la corrección de errores, la conversión de resultados cuánticos a clásicos, etc.\n", "* **`DONE`**: El programa ya está listo y puedes recuperar los datos de los resultados con `job.results()`.\n", "* **`ERROR`**: El programa ha dejado de funcionar debido a un problema. Utiliza `job.result()` para ver el mensaje de error.\n", "* **`CANCELED`**: El programa ha sido cancelado por un usuario, por el servicio o por el servidor.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "## Obtener resultados\n", "\n", "`DONE`Una vez que se haya ejecutado un programa, puedes utilizar `job.results()` para obtener el resultado. Este formato de salida varía según cada función, así que asegúrate de seguir la documentación específica:\n", "\n", "\n", "\n", "También puedes cancelar un trabajo en cualquier momento:\n", "\n", "\n", "\n", "\n", "\n", "## Mostrar los trabajos de « Qiskit Functions » ejecutados anteriormente\n", "\n", "Puedes utilizar `jobs()` para ver una lista de todos los trabajos enviados a Qiskit Functions :\n", "\n", "\n", "\n", "`catalog.get_job_by_id()`Si ya dispones del ID de un trabajo concreto, puedes recuperarlo con:\n", "\n", "\n", "\n", "\n", "\n", "## Recuperar mensajes de error\n", "\n", "Si el estado de un programa es `ERROR`, utiliza `job.error_message()` para obtener el mensaje de error de la siguiente manera:\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": "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()" ] }, { "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.stop()" ] }, { "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": 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 get_job_by_id\n", "job_by_id = catalog.get_job_by_id(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óximos pasos\n", "\n", "\n", " * [Explora las funciones de los circuitos](/docs/guides/algorithmiq-tem) para crear nuevos algoritmos y aplicaciones, sin necesidad de ocuparte de la transpilación ni de la gestión de errores.\n", " * [Explora las funciones de la aplicación](/docs/guides/q-ctrl-optimization-solver) para resolver tareas específicas del ámbito, con entradas y salidas clásicas.\n", " * Consulta la [documentación de referencia de la API](/docs/api/functions/index) en Qiskit Functions.\n", " * Para adquirir experiencia práctica, prueba algunos [tutoriales](/docs/tutorials/index#leverage-qiskit-capabilities) que muestran cómo funciona « 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 }