{ "cells": [ { "cell_type": "markdown", "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", "metadata": {}, "source": [ "---\n", "title: \"Découvrez « Qiskit Functions »\"\n", "description: \"Comment effectuer les tâches courantes, de l'installation et de l'authentification à la vérification de l'état des tâches et à la consultation des messages d'erreur\"\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", "# Découvrez « Qiskit Functions »\n", "\n", "Les utilisateurs des formules Premium, Flex et « On-Prem » (via l'API IBM Quantum Platform ) peuvent commencer à utiliser gratuitement « IBM » ( Qiskit Functions ) ou se procurer une licence auprès de l'un des partenaires ayant contribué à l'enrichissement du catalogue.\n", "\n", "\n", "\n", "## Demandez un essai gratuit de l' Qiskit Functions tiers\n", "\n", "Pour demander un essai gratuit, rendez-vous sur la page « [Qiskit Functions Catalog](/functions) » et consultez l'onglet « Détails ». Cliquez `Request a free trial` ici et renseignez les informations demandées par le partenaire Functions, notamment l' IBM Cloud `AccessGroupId`:\n", "\n", "1. Accédez à [IBM Cloud IAM](http://cloud.ibm.com/iam/groups).\n", "2. Vérifier les conditions d'éligibilité.\n", " * Dans la barre de menu située en haut de la page, sélectionnez un compte au format suivant : `XXXXXXX - [Organization Name]`\n", " * Assurez-vous que l'organisation correspond bien à celle associée à votre compte Premium.\n", " * Si vous voyez « Compte \\[de \\[votre nom] ] », cela signifie que vous utilisez votre compte *personnel*, qui ne donne pas droit à l'accès premium.\n", "3. Recherchez l'identifiant de votre groupe d'accès.\n", " * Cliquez sur le nom d'un groupe.\n", " * Cliquez sur «\\*\\* Détails\\*\\* ».\n", " * Copiez l'identifiant du groupe d'accès. Ça devrait commencer par `AccessGroup-`.\n", "\n", "\n", "\n", "\n", "\n", "## Installez le client « Qiskit Functions Catalog »\n", "\n", "1. Pour commencer à utiliser Qiskit Functions, installez le client IBM Qiskit Functions Catalog :\n", "\n", " ```\n", " pip install qiskit-ibm-catalog\n", " ```\n", "\n", "2. Récupérez votre clé API depuis le [tableau de bord d' IBM Quantum Platform](/), puis activez votre environnement virtuel Python. Si vous n'avez pas encore configuré d'environnement virtuel, consultez les [instructions d'installation](/docs/guides/install-qiskit#local).\n", "\n", " **Si vous travaillez dans un environnement « Python » de confiance (par exemple sur un ordinateur portable personnel ou un poste de travail),** utilisez la `save_account()` méthode pour enregistrer vos identifiants localement. ( [Passez à l'étape suivante](#functions-untrusted) si vous n'utilisez pas un environnement sécurisé, tel qu'un ordinateur partagé ou public, pour vous authentifier sur IBM Quantum Platform.)\n", "\n", " `save_account()`Pour l'utiliser, lancez `python` dans votre terminal, puis saisissez ce qui suit :\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", " QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n", " ```\n", "\n", " Tapez `exit()`. Désormais, chaque fois que vous devrez vous authentifier auprès du service, vous pourrez charger vos identifiants en procédant comme suit :\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", " catalog = QiskitFunctionsCatalog()\n", " ```\n", "\n", " Par exemple :\n", "\n", " \n", "\n", "3. **Évitez d'exécuter du code sur une machine non fiable ou dans un environnement cloud externe de type « Python » afin de minimiser les risques de sécurité.** Si vous devez utiliser un environnement non sécurisé (par exemple, un ordinateur public), modifiez votre clé API après chaque utilisation en la supprimant sur la page [des clés API IBM Cloud](https://cloud.ibm.com/iam/apikeys) afin de réduire les risques. Pour en savoir plus, consultez la rubrique «[ Gestion des clés API des utilisateurs](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ». Pour initialiser le service dans ce cas, utilisez le code suivant :\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", " **N'incluez jamais votre clé dans le code source, les scripts `Python` ou les fichiers de notebook.** Lorsque vous partagez du code avec d'autres personnes, veillez à ce que votre clé API ne soit pas intégrée directement dans le script Python. Partagez plutôt le script sans la clé et fournissez des instructions pour le configurer en toute sécurité.\n", "\n", " Si vous partagez accidentellement votre clé avec quelqu'un ou si vous l'incluez dans un système de contrôle de version comme Git, révoquez-la immédiatement en la supprimant sur la page [des clés API IBM Cloud](https://cloud.ibm.com/iam/apikeys) afin de réduire les risques. Pour en savoir plus, consultez la rubrique «[ Gestion des clés API des utilisateurs](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui) ».\n", " \n", "\n", "\n", "\n", "## Énumérez les fonctions auxquelles vous avez accès\n", "\n", "Une fois connecté, vous pouvez afficher la liste des fonctions de l' Qiskit Functions Catalog auxquelles vous avez accès :\n", "\n", "\n", "\n", "\n", "\n", "## Exécuter les fonctions activées\n", "\n", "Une fois qu'un objet de catalogue a été instancié, vous pouvez sélectionner une fonction à l'aide de `catalog.load(\"\")`:\n", "\n", "\n", "\n", "Chaque fonction Qiskit dispose d'entrées, d'options et de sorties personnalisées. Pour plus d'informations, consultez les pages de documentation spécifiques à la fonction que vous souhaitez exécuter. Par défaut, tous les utilisateurs ne peuvent exécuter qu'une seule tâche de fonction à la fois :\n", "\n", "\n", "\n", "\n", " `run()` vérifie la capacité restante et l'accès au serveur avant d'envoyer la tâche. Si votre instance est saturée ou si le backend que vous avez spécifié n'est pas accessible, `run()` le système génère immédiatement une erreur au lieu de laisser la tâche échouer dans la file d'attente. Lorsque la capacité est faible, `run()` le système émet un avertissement. Appuyez sur `suppress_low_usage_warning=True` pour le mettre en sourdine.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "## Vérifier l'état d'avancement d'une mission\n", "\n", "`job_id`Grâce à votre fonction Qiskit, vous pouvez vérifier l'état des tâches en cours d'exécution. Cela comprend les statuts suivants :\n", "\n", "* **`QUEUED`**: Le programme distant se trouve dans la file d'attente des fonctions de Qiskit. La priorité dans la file d'attente dépend de votre niveau d'utilisation d' Qiskit Functions.\n", "* **`INITIALIZING`**: Le programme distant est en cours de lancement; cela comprend la configuration de l'environnement distant et l'installation des dépendances.\n", "* **`RUNNING`**: Le programme est en cours d'exécution. Cela inclut également plusieurs statuts plus détaillés, si ceux-ci sont pris en charge par des fonctions spécifiques.\n", " * **`RUNNING: MAPPING`**: La fonction effectue actuellement la conversion de vos entrées classiques en entrées quantiques.\n", " * **`RUNNING: OPTIMIZING_FOR_HARDWARE`**: La fonction est optimisée pour le QPU sélectionné. Cela pourrait inclure la transpilation de circuits, la caractérisation des QPU, la rétropropagation des observables, etc.\n", " * **`RUNNING: WAITING_FOR_QPU`**: La fonction a soumis une tâche au service de calcul d' IBM Quantum, et celle-ci est en attente dans la file d'attente.\n", " * **`RUNNING: EXECUTING_QPU`**: La fonction dispose d'une tâche de calcul quantique en cours d'exécution.\n", " * **`RUNNING: POST_PROCESSING`**: Cette fonction consiste à traiter les résultats a posteriori, ce qui peut inclure la correction des erreurs, la conversion des résultats quantiques en résultats classiques, etc.\n", "* **`DONE`**: Le programme est terminé, et vous pouvez récupérer les données de résultat à l'aide de `job.result()`.\n", "* **`ERROR`**: Le programme s'est arrêté en raison d'un problème. Utilisez `job.result()` pour afficher le message d'erreur.\n", "* **`CANCELED`**: Le programme a été annulé par un utilisateur, le service ou le serveur.\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "## Afficher les résultats\n", "\n", "Une fois qu'un programme est `DONE`, vous pouvez utiliser `job.result()` pour récupérer le résultat. Ce format de sortie varie selon les fonctions; veillez donc à suivre les instructions fournies dans la documentation correspondante :\n", "\n", "\n", "\n", "Vous pouvez également annuler une mission à tout moment :\n", "\n", "\n", "\n", "\n", "\n", "## Accéder aux tâches de calcul quantique associées\n", "\n", "Une fonction Qiskit peut soumettre un ou plusieurs tâches de calcul quantique à une QPU pendant son exécution. Pour récupérer les identifiants de ces tâches d'exécution, utilisez `job.runtime_jobs()`. Vous pouvez utiliser ces identifiants pour récupérer les objets de tâche en cours d'exécution à partir d'une instance `QiskitRuntimeService` , ou pour localiser les charges de travail sur le tableau de bord « IBM Quantum® Platform ».\n", "\n", "\n", "\n", "Si une fonction regroupe ses tâches d'exécution en sessions ou en lots, utilisez `job.runtime_sessions()` pour afficher la liste des identifiants de session. Transmettez un identifiant de session à `job.runtime_jobs()` pour n'afficher que les tâches en cours d'exécution dans cette session :\n", "\n", "\n", "\n", "\n", " La liste renvoyée peut être vide. Une fonction ne signale ses tâches d'exécution que lorsqu'elle les soumet via le service d'exécution dont elle dispose au moment de l'exécution; or, certaines fonctions ne soumettent pas directement leurs tâches d'exécution.\n", "\n", "\n", "\n", "\n", "## Affichage des journaux de travail\n", "\n", "Utilisez `job.logs()` pour récupérer les informations de journalisation générées par une fonction lors de son exécution. Les journaux sont utiles pour suivre la progression et pour déboguer une tâche qui se termine par un état `ERROR` .\n", "\n", "\n", "\n", "Pour une tâche qui s'exécute depuis longtemps et qui génère de nombreuses lignes de journal, utilisez `job.filtered_logs()` pour n'afficher que les lignes qui vous intéressent. Passez une expression régulière à `include` pour conserver les lignes correspondantes, ou à `exclude` pour les supprimer :\n", "\n", "\n", "\n", "\n", "\n", "## Afficher la liste des tâches « Qiskit Functions » déjà exécutées\n", "\n", "Vous pouvez utiliser `jobs()` pour afficher la liste de toutes les tâches soumises à Qiskit Functions :\n", "\n", "\n", "\n", "Pour affiner les résultats, appliquez des filtres. Filtrer par fonction à l'aide de `function`, par statut à l'aide de `status`, et par date de soumission à l'aide de `created_after`. Parcourez les résultats à l'aide des touches et `limit` `offset`:\n", "\n", "\n", "\n", "Si vous disposez déjà de l'identifiant d'un travail donné, vous pouvez récupérer ce travail à l'aide de la commande suivante `catalog.job()`:\n", "\n", "\n", "\n", "\n", "\n", "## Récupérer les messages d'erreur\n", "\n", "Si l'état d'un programme est `ERROR`, utilisez `job.error_message()` pour récupérer le message d'erreur comme suit :\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": "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", "if sessions:\n", " session_runtime_jobs = job.runtime_jobs(runtime_session=sessions[0])\n", " print(session_runtime_jobs)\n", "else:\n", " print(\"No runtime sessions for this job.\")" ] }, { "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", "## Etapes suivantes\n", "\n", "\n", " * [Découvrez les fonctions de circuit](/docs/guides/algorithmiq-tem) pour créer de nouveaux algorithmes et applications, sans avoir à vous soucier de la transcompilation ni de la gestion des erreurs.\n", " * [Découvrez les fonctionnalités de l'application](/docs/guides/q-ctrl-optimization-solver) permettant de résoudre des tâches spécifiques à un domaine, avec des entrées et des sorties classiques.\n", " * Consultez la [documentation de référence de l'API](/docs/api/functions/index) sur Qiskit Functions.\n", " * Pour acquérir une expérience pratique, essayez quelques [tutoriels](/docs/tutorials/index#leverage-qiskit-capabilities) qui présentent l' 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 }