{ "cells": [ { "cell_type": "markdown", "id": "2ee21f3f-2a40-486f-9721-d8a358a87aa1", "metadata": {}, "source": [ "---\n", "title: \"Qiskit Functions を始めよう\"\n", "description: \"インストールや認証から、ジョブのステータス確認やエラーメッセージの取得に至るまで、一般的な操作の手順\"\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", "# Qiskit Functions を始めよう\n", "\n", "Premium、Flex、および On-Prem （ IBM Quantum Platform API経由）プランをご利用のお客様は、 IBM （ Qiskit Functions ）を無料でご利用開始できるほか、カタログに機能を提供しているパートナーのいずれかからライセンスを購入することも可能です。\n", "\n", "\n", "\n", "## サードパーティ製 Qiskit Functions の無料トライアルをお申し込みください\n", "\n", "無料トライアルをお申し込みになるには、 [Qiskit Functions Catalog](/functions) にアクセスし、詳細パネルをご覧ください。 `AccessGroupId`をクリック `Request a free trial` し、Functionsパートナーが求める情報（ IBM Cloud を含む）を入力してください：\n", "\n", "1. [IBM Cloud](http://cloud.ibm.com/iam/groups) のIAMに移動します。\n", "2. 資格要件を確認してください。\n", " * ヘッダーのメニューバーで、アカウントを以下の形式のものに切り替えてください： `XXXXXXX - [Organization Name]`\n", " * その組織が、ご自身のプレミアムアカウントに登録されている組織と同じであることを確認してください。\n", " * 「 \\[あなたの]アカウント」と表示されている場合は、 *個人*アカウントを利用していることになります。このアカウントではプレミアムアクセスをご利用いただけません。\n", "3. アクセスグループIDを確認してください。\n", " * グループ名をクリックしてください。\n", " * **「詳細」** をクリックしてください。\n", " * アクセスグループIDをコピーしてください。 `AccessGroup-`まずは. から始めるべきです。\n", "\n", "\n", "\n", "\n", "\n", "## Qiskit Functions Catalog クライアントをインストールする\n", "\n", "1. Qiskit Functions を使い始めるには、 IBM Qiskit Functions Catalog クライアントをインストールしてください：\n", "\n", " ```\n", " pip install qiskit-ibm-catalog\n", " ```\n", "\n", "2. [IBM Quantum Platform](/) のダッシュボードからAPIキーを取得し、 Python の仮想環境を有効にしてください。まだ仮想環境を設定していない場合は、 [インストール手順](/docs/guides/install-qiskit#local)を参照してください。\n", "\n", " **信頼された Python 環境（個人のノートPCやワークステーションなど）で作業している場合は、** この `save_account()` 方法を使用して認証情報をローカルに保存してください。（共有パソコンや公共のパソコンなど、信頼できない環境で IBM Quantum Platform への認証を行う場合は、 [次の手順に進んでください](#functions-untrusted)。）\n", "\n", " `save_account()`これを使用するには、シェルでを実行し `python` 、次に以下を入力してください：\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", "\n", " QiskitFunctionsCatalog.save_account(channel=\"ibm_quantum_platform\", token=\"\", instance=\"\")\n", " ```\n", "\n", " `exit()`「.」と入力してください。今後、このサービスへの認証が必要になる際は、以下の方法で認証情報を読み込むことができます：\n", "\n", " ```python\n", " from qiskit_ibm_catalog import QiskitFunctionsCatalog\n", " catalog = QiskitFunctionsCatalog()\n", " ```\n", "\n", " 例:\n", "\n", " \n", "\n", "3. **セキュリティリスクを最小限に抑えるため、信頼できないマシンや外部のクラウド Python 環境でのコード実行は避けてください。** 信頼できない環境（例えば、公共のコンピュータなど）を使用せざるを得ない場合は、リスクを軽減するために、使用のたびに [IBM Cloud](https://cloud.ibm.com/iam/apikeys) のAPIキーページでAPIキーを削除し、新しいキーに変更してください。詳細については、「 [ユーザー API キーの管理](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui)」のトピックをご覧ください。この状況でサービスを初期化するには、次のコードを使用してください：\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", " **ソースコード、 Python スクリプト、またはノートブックファイルに、決して鍵を含めないでください。** 他の人とコードを共有する際は、 Python スクリプト内にAPIキーが直接埋め込まれていないことを確認してください。その代わりに、キーを含まないスクリプトを共有し、安全に設定するための手順を説明してください。\n", "\n", " うっかりキーを他人に共有してしまったり、 Git などのバージョン管理システムにキーが含まれてしまった場合は、リスクを軽減するため、直ちに [IBM Cloud のAPIキー](https://cloud.ibm.com/iam/apikeys) ページでキーを削除して無効化してください。詳細については、「 [ユーザー API キーの管理](https://cloud.ibm.com/docs/account?topic=account-userapikey\\&interface=ui)」のトピックをご覧ください。\n", " \n", "\n", "\n", "\n", "## アクセス可能な関数を列挙してください\n", "\n", "認証が完了すると、 Qiskit Functions Catalog 内の、自分がアクセス権を持つ関数のリストを表示できます：\n", "\n", "\n", "\n", "\n", "\n", "## 利用可能なバックエンドと容量を確認する\n", "\n", "関数を実行する前に、インスタンスがどのバックエンドにアクセスできるか、および残りの実行容量がどれくらいあるかを確認してください。 `run()` ジョブを送信する前に同様のチェックを行うため、キャパシティやバックエンドの問題を早期に発見することができます。\n", "\n", "インスタンスからアクセス可能なバックエンドを一覧表示してください。結果はカタログごとにキャッシュされます。「Pass `refresh_cache=True` 」をクリックして更新してください。\n", "\n", "\n", "\n", "`backends()` . と同じフィルターを受け入れます [`QiskitRuntimeService.backends()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#backends)。たとえば、127キュービット以上のバックエンドのみを一覧表示したり、より詳細な制御を行うための関 `filters` 数を渡したりすることができます：\n", "\n", "\n", "\n", "1つのバックエンドを検索し、アクセスできることを確認します：\n", "\n", "\n", "\n", "また、保留中のジョブが最も少ないバックエンドを取得することもできます。 `least_busy()` 以下のものと同じフィルターを使用します [`QiskitRuntimeService.least_busy()`](/docs/api/qiskit-ibm-runtime/qiskit-runtime-service#least_busy)：\n", "\n", "\n", "\n", "\\[ ] を使用して `usage()` 、残りの稼働時間を確認してください。アクティブなインスタンスに対して、および `usage_limit_reached` を返します `usage_remaining_seconds` 。\n", "\n", "\n", "\n", "たとえば、大量のジョブをバッチ処理する前に残りの容量を確認し、処理を完了するのに十分な容量が残っていない場合は停止してください：\n", "\n", "\n", "\n", "\n", "\n", "## 有効な関数を実行する\n", "\n", "`catalog.load(\"\")`カタログオブジェクトがインスタンス化された後、次のようにして関数を選択できます：\n", "\n", "\n", "\n", "各Qiskit関数には、独自の入力、オプション、および出力があります。詳細については、実行したい関数に関する具体的なドキュメントページをご確認ください。デフォルトでは、すべてのユーザーは一度に1つの関数ジョブしか実行できません：\n", "\n", "\n", "\n", "\n", " `run()` ジョブを送信する前に、残りの容量とバックエンドへのアクセス状況を確認します。インスタンスの容量が不足している場合、または指定したバックエンドにアクセスできない場合は、 `run()` ジョブをキュー内で失敗させるのではなく、直ちにエラーを発生させます。容量が低い場合、 `run()` 警告を発します。「Pass `suppress_low_usage_warning=True` 」を押して音を消してください。\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "\n", "## ジョブのステータスの確認\n", "\n", "`job_id`Qiskit Function を使用すると、実行中のジョブのステータスを確認できます。これには、以下のステータスが含まれます：\n", "\n", "* **`QUEUED`**: リモートプログラムは、Qiskitの関数キューに入っています。キューの優先順位は、 Qiskit Functions の利用量に基づいて決定されます。\n", "* **`INITIALIZING`**: リモートプログラムが起動しています。これには、リモート環境のセットアップや依存関係のインストールが含まれます。\n", "* **`RUNNING`**: プログラムが実行中です。また、特定の機能でサポートされている場合は、さらに詳細なステータスもいくつか含まれます。\n", " * **`RUNNING: MAPPING`**: この関数は現在、古典的な入力を量子入力に変換しています。\n", " * **`RUNNING: OPTIMIZING_FOR_HARDWARE`**: この関数は、選択されたQPUに対して最適化されています。これには、回路のトランスパイレーション、QPUの特性評価、観測可能なバックプロパゲーションなどが含まれる可能性がある。\n", " * **`RUNNING: WAITING_FOR_QPU`**: この関数は、 IBM Quantum Compute Service にジョブを送信し、現在キューで待機中です。\n", " * **`RUNNING: EXECUTING_QPU`**: この関数には、実行中のQuantum Computeジョブがあります。\n", " * **`RUNNING: POST_PROCESSING`**: この関数は結果の後処理を行うもので、エラーの軽減や、量子計算の結果を古典的な結果に変換することなどが含まれます。\n", "* **`DONE`**: プログラムは完了しました。結果データは `job.result()`. を使って取得できます。\n", "* **`ERROR`**: 問題が発生したため、プログラムの実行が停止しました。エラーメッセージを表示するには、\\[ ] を使用 `job.result()` してください。\n", "* **`CANCELED`**: プログラムは、ユーザー、サービス、またはサーバーによってキャンセルされました。\n", "\n", " \n", "\n", "\n", "\n", "\n", "\n", "## 検索結果\n", "\n", "プログラムの実行が完了したら `DONE`、を使用して `job.result()` 結果を取得できます。この出力形式は関数ごとに異なるため、必ず各関数のドキュメントに従ってください：\n", "\n", "\n", "\n", "また、ジョブはいつでもキャンセルできます：\n", "\n", "\n", "\n", "\n", "\n", "## 関連するQuantum Computeジョブにアクセスする\n", "\n", "Qiskit関数は、実行中に1つ以上の量子コンピューティングジョブをQPUに送信することができます。これらのランタイムジョブのIDを取得するには、. を使用します `job.runtime_jobs()`。これらのIDを使用すると、インスタンス `QiskitRuntimeService` からランタイムジョブオブジェクトを取得したり、 IBM Quantum® Platform ダッシュボード上でワークロードを検索したりすることができます。\n", "\n", "\n", "\n", "関数が実行時のジョブをセッションまたはバッチにグループ化している場合は、を使用してセッションIDを一覧表示 `job.runtime_sessions()` します。 1つのセッションIDをに渡すと `job.runtime_jobs()` 、そのセッション内の実行中のジョブのみが返されます：\n", "\n", "\n", "\n", "\n", " 返されるリストは空の場合もあります。関数は、実行時に受け取ったランタイムサービスを通じてランタイムジョブを送信した場合にのみ、そのジョブを報告します。また、一部の関数はランタイムジョブを直接送信しません。\n", "\n", "\n", "\n", "\n", "## ジョブ・ログの表示\n", "\n", "を使用して、関数の実行中に生成されるログ出力を取得 `job.logs()` します。ログは、進捗状況を追跡したり、特定の `ERROR` 状態で終了したジョブのデバッグを行ったりするのに役立ちます。\n", "\n", "\n", "\n", "多くのログ行を生成する長時間実行されるジョブの場合、\\`\\` を使用して、必要な行のみを取得 `job.filtered_logs()` してください。正規表現をに渡して一致する行を保持 `include` するか、に渡して一致する行を削除 `exclude` します：\n", "\n", "\n", "\n", "\n", "\n", "## 以前に実行された Qiskit Functions ジョブの一覧を表示する\n", "\n", "Qiskit Functions に送信されたすべてのジョブを一覧表示するには、以下を使用 `jobs()` できます：\n", "\n", "\n", "\n", "検索結果を絞り込むには、フィルタを設定してください。で機能別に `function`、でステータス別に `status`、で提出日別に絞り込みます `created_after`。と `limit` : を使って検索結果をページごとに閲覧できます `offset`：\n", "\n", "\n", "\n", "特定のジョブのジョブIDがすでにわかっている場合は、次のコマンドでそのジョブを取得できます `catalog.job()`：\n", "\n", "\n", "\n", "\n", "\n", "## エラーメッセージを取得する\n", "\n", "`ERROR`プログラムのステータスがの場合、次のようにを使用して `job.error_message()` エラーメッセージを取得します\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", "## 次のステップ\n", "\n", "\n", " * トランスパイルやエラー処理を気にすることなく、 [回路の機能を駆使して](/docs/guides/algorithmiq-tem)新しいアルゴリズムやアプリケーションを構築できます。\n", " * 従来の入力と出力を用いて、ドメイン固有の課題を解決[するためのアプリケーション機能を探索します](/docs/guides/q-ctrl-optimization-solver)。\n", " * Qiskit Functions の [API リファレンス](/docs/api/functions/index)を参照してください。\n", " * 実際に体験してみたい方は、 Qiskit Functions の使い方を解説した[チュートリアル](/docs/tutorials/index#leverage-qiskit-capabilities)を試してみてください。\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 }