{ "cells": [ { "cell_type": "markdown", "id": "title", "metadata": {}, "source": [ "---\n", "title: \"QRMI を使用して量子ワークロードを実行する\"\n", "description: \"Quantum Resource Management Interface を使用して、 IBM Quantum のワークロードを管理し、HPC環境から量子化学ワークフローを実行します。\"\n", "---\n", "\n", "{/* cspell:ignore QRMI SPANK GRES Slurm LUCJ CCSD pvdz hcore Pellegrini rustup cregs CUDA SBATCH dotenv */}\n", "\n", "\n", "\n", "# QRMI を使用して量子ワークロードを実行する\n", "\n", "*所要時間の目安： IBM Quantum® ハードウェア上でSQDセクションの実行にかかる時間は1分未満です。 この見積もりには、待ち時間や通常の処理時間は含まれていません。実行時間は状況によって異なる場合があります。*\n", "\n", "\n", "\n", "## 学習成果\n", "\n", "1. HPCスケジューラと IBM Quantum ハードウェアの間で、QRMIがミドルウェアとして果たす役割\n", "2. 実際の IBM® バックエンドに対して、QRMIの主要なライフサイクル（`acquire` → `task_start` → `task_status` → → `task_result` `release`）を活用する方法\n", "3. QRMI 上に構築された高レベルな Qiskit `SamplerV2` およびラッパー `QRMIService` の使用方法\n", "4. HPCスケジューラ（Slurm）が環境変数を介して量子リソースを割り当てる仕組みと、アプリケーションがそれらを利用する仕組み\n", "5. QRMIを通じて IBM ハードウェアを使用し、N $_2$ 上でSQD（サンプルベース量子対角化）の化学ワークフロー全体を実行する方法\n", "\n", "\n", "\n", "## 前提条件\n", "\n", "* [Qiskit primitives （サンプリングと推定）](/docs/guides/primitives)\n", "* [IBM Quantum セッション](/docs/guides/run-jobs-session)\n", "* [IBM Quantum トランスパイレーション](/docs/guides/transpile)\n", "* [サンプルベース量子対角化（SQD）](/docs/tutorials/sample-based-quantum-diagonalization)\n", "* Python の仮想環境および量子化学に関する基本的な知識\n", "\n" ] }, { "cell_type": "markdown", "id": "background", "metadata": {}, "source": [ "\n", "\n", "## 背景\n", "\n", "\n", "\n", "### 量子コンピューティングとHPCの統合における課題\n", "\n", "ハイパフォーマンス・コンピューティング（HPC）のワークフローでは、従来のコンピューティング・クラスターと量子処理ユニット（QPU）との間で、シームレスな連携が必要となる場合が多い。 量子ハードウェアのバックエンドやサービスによって、認証メカニズム、通信フォーマット、およびジョブライフサイクルAPIはそれぞれ異なります。 IBM Quantum システムをHPCワークロードマネージャー（Slurmなど）に統合するには、リソースの取得、ジョブの実行、およびセッション管理のための、明確で標準的なインターフェースが必要です。\n", "\n", "\n", "\n", "### QRMIとは\n", "\n", "**Quantum Resource Management Interface（QRMI）** は、Rustで記述されたミドルウェアライブラリであり、HPCスケジューラや古典的なアプリケーションから量子ハードウェアへのアクセスを標準化するものです。 単一の統合されたライフサイクルAPIを提供します：\n", "\n", "```\n", "┌─────────────────────────────────────────────────────────────────┐\n", "│ HPC Application Layer │\n", "│ (Slurm job script / Python workflow / CUDA-Q) │\n", "└───────────────────────────┬─────────────────────────────────────┘\n", " │ QRMI API\n", " │ acquire() / task_start() / task_result() / release()\n", "┌───────────────────────────▼─────────────────────────────────────┐\n", "│ QRMI Core (Rust) │\n", "│ Python bindings · C bindings · Lua bindings │\n", "└───────────────────────────┬─────────────────────────────────────┘\n", " │\n", " IBM Quantum Compute Service / IBM Quantum System\n", "```\n", "\n", "QRMIは、 [github.com/qiskit-community/qrmi](https://github.com/qiskit-community/qrmi) でオープンソースプロジェクトとして公開されており、概要論文 [arXiv:2506.10052](https://arxiv.org/abs/2506.10052) にその詳細が記載されています。\n", "\n", "\n", "\n", "### 主要な設計上の選択\n", "\n", "**回路のコンパイルではなく、リソースのライフサイクル。** QRMIは、取得・送信・ポーリング・解放というライフサイクルのみを処理し、それ以外の機能は一切持ちません。 回路のコンパイル、最適化、およびトランスパイルは、引き続きアプリケーション層（例えば、Qiskit）で行われます。 これにより、インターフェースはミニマルで、組み合わせやすいものになります。\n", "\n", "**ベンダーポータビリティモデル。** QRMIは、サポートされているハードウェアバックエンド間で共通のジョブ管理コール（`acquire`, `task_start`, `task_status`, `task_result`, `release`）を提供していますが、ベンダーを変更する際には、異なるコンパイルパス、ベンダー固有のペイロード構築、およびアプリケーション層での結果のデコードが必要となります。\n", "\n", "**IBM のネイティブペイロード形式。** IBM Quantum バックエンドの場合、QRMIは Qiskit Runtime スキーマに準拠した OpenQASM 3のJSONペイロード(`QiskitPrimitive`)を使用します。\n", "\n", "**環境変数による設定。** 認証情報とエンドポイントURLは、実行時に環境変数から読み込まれます。 HPCクラスタでは、ジョブがディスパッチされる際に、Slurm QRMI SPANKプラグインがこれらを自動的に設定します。 ノートブックや対話型セッションでは、ファイル `.env` からそれらを読み込みます。 アプリケーションコードには、ハードコードされた認証情報やエンドポイントURLは一切含まれません。\n", "\n", "**GRES による HPC スケジューラの統合。** SlurmジョブがQRMI SPANKプラグインインターフェース（`#SBATCH --gres=qpu:1` および `#SBATCH --qpu=ibm_kingston`）を使用してQuantumリソースを要求すると、プラグインは および `QRMI_JOB_QPU_RESOURCES` をジョブ環境 `QRMI_JOB_QPU_TYPES` に注入します。 アプリケーションは、どのリソースが割り当てられたかを確認 `get_job_qpu_resources_and_types()` するために呼び出しを行います。バックエンド名をハードコードする必要はありません。 `QRMIService` Qiskitユーザー向けに、このパターンをラップします。\n", "\n", "\n", "\n", "### 主要なAPI呼び出し\n", "\n", "| コール | 目的 |\n", "| -------------------------- | ----------------------------------------------------------- |\n", "| `qrmi.acquire()` | リソースへのアクセス権を取得します（たとえば、専用のセッションを開くなど）。ロックトークンを返します |\n", "| `qrmi.target()` | バックエンドの機能（量子ビット、ゲート、カップリングマップ）をJSON形式で取得する |\n", "| `qrmi.task_start(payload)` | 量子ジョブを送信します。ジョブIDを返します |\n", "| `qrmi.task_status(job_id)` | ジョブのステータスを照会する (`Queued`, `Running`, `Completed`, `Failed`) |\n", "| `qrmi.task_result(job_id)` | 完了したジョブの結果を生のJSON文字列として取得する |\n", "| `qrmi.task_stop(job_id)` | ジョブのキャンセルまたはクリーンアップ |\n", "| `qrmi.release(lock)` | リソースロックを解除する（たとえば、セッションを閉じるなど） |\n", "\n", "\n", "\n", "### このチュートリアルの内容\n", "\n", "このチュートリアルは、2つのパートで構成されています：\n", "\n", "\\*\\*手順 1～3（小規模な例）：\\*\\*IBM Quantum ハードウェア上で、単純なベル状態回路の実演を通じてQRMI APIを紹介します。ここでは、低レベルのプリミティブの直接的な使用方法に加え、高レベルな機能 `QRMIService` や `SamplerV2` 統合についても解説します。\n", "\n", "**大規模ハードウェアの例：** 結合距離 1.0 のN $_2$ 分子に対する完全なSQDワークフロー $\\AA$ ( cc-pVDZ 基底アクティブスペース、26個の空間軌道／52キュービット)を、QRMIを介して IBM Quantum ハードウェア上で実行した。 SQDは、を用いて構築されたLUCJアンザッツの量子サンプリングと `ffsim` 、を用いて行う自己一貫的な構成の復元を組み合わせたものである `qiskit-addon-sqd`。\n", "\n" ] }, { "cell_type": "markdown", "id": "requirements", "metadata": {}, "source": [ "\n", "\n", "## 要件\n", "\n", "このチュートリアルを始める前に、以下のものがインストールされていることを確認してください。\n", "\n", "\n", "\n", "### Python 環境設定\n", "\n", "PyPI, では、 Linux 用の事前ビルド済みバイナリホイールが提供されているため、 Linux ／HPC システムでは標準でそのまま動作 `pip install` します。\n", "\n", "```bash\n", "python3 -m venv ~/.venvs/qrmi-ibm\n", "source ~/.venvs/qrmi-ibm/bin/activate\n", "python -m pip install \"qrmi[ibm]\" python-dotenv pyscf ffsim qiskit-addon-sqd matplotlib ipykernel\n", "python -m ipykernel install --user --name qrmi-ibm --display-name \"QRMI IBM\"\n", "```\n", "\n", "\n", " ソースから QRMI を `pip` ビルドする場合は、最新の Rust ツールチェーン（Rust バージョン 1.91.1 以上）がインストールされていることを確認してください。インストールは、 [rustup.rs](https://rustup.rs) `rustup` から行ってください。\n", "\n", "\n", "**JupyterでQRMIの IBM** カーネルを選択し、再起動してから、ノートブックのセルを順番に実行してください。 保存されている出力結果は、投稿者によるハードウェア実行時のものです。インストールコマンドには、その実行で使用された正確なバージョンは明記されていません。\n", "\n", "\n", "\n", "### 資格情報は必須です\n", "\n", "* IBM Quantum ：IAM API キーおよびサービス CRN （ [IBM Quantum Platform]() より）\n", "\n", "スタンドアロンで実行する場合は、このノートブックの隣に、認証情報のプレースホルダーを置き換えて、以下の値を含めたファイル `.env` を作成してください。 このファイルは非公開にしてください。 別のバックエンドを選択する場合は、その名前と環境変数のプレフィックスの両方を更新してください。\n", "\n", "```dotenv\n", "ibm_kingston_QRMI_IBM_QCS_ENDPOINT=https://quantum.cloud.ibm.com/api/v1\n", "ibm_kingston_QRMI_IBM_QCS_IAM_ENDPOINT=https://iam.cloud.ibm.com\n", "ibm_kingston_QRMI_IBM_QCS_IAM_APIKEY=\n", "ibm_kingston_QRMI_IBM_QCS_SERVICE_CRN=\n", "ibm_kingston_QRMI_IBM_QCS_SESSION_MODE=dedicated\n", "ibm_kingston_QRMI_IBM_QCS_SESSION_MAX_TTL=28800\n", "QRMI_JOB_QPU_RESOURCES=ibm_kingston\n", "QRMI_JOB_QPU_TYPES=ibm-quantum-compute-service\n", "```\n", "\n", "Slurmによるリソース割り当てについては、クラスタから提供されたリソース設定および認証情報を使用してください。 このノートブックでは、既存の環境変数が保持されます。\n", "\n" ] }, { "cell_type": "markdown", "id": "setup-header", "metadata": {}, "source": [ "\n", "\n", "## セットアップ\n", "\n", "依存関係をインポートし、リソース設定を読み込みます。\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "setup-imports", "metadata": { "tags": [ "environment-ibm" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Backend: ibm_kingston\n", "Environment ready.\n" ] } ], "source": [ "import os\n", "import time\n", "import json\n", "import numpy as np\n", "from dotenv import load_dotenv\n", "\n", "from qrmi import (\n", " QuantumResource,\n", " ResourceType,\n", " Payload,\n", " TaskStatus,\n", " get_job_qpu_resources_and_types,\n", ")\n", "from qrmi.primitives import QRMIService\n", "from qrmi.primitives.ibm import SamplerV2, get_target\n", "\n", "from qiskit import QuantumCircuit, qasm3\n", "from qiskit.circuit.library import efficient_su2\n", "from qiskit.primitives.containers.sampler_pub import SamplerPub\n", "from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager\n", "\n", "# Load credentials from .env without overriding already-set scheduler environment variables\n", "load_dotenv(override=False)\n", "\n", "# Preserve resources if injected by Slurm SPANK plugin; fallback to default for interactive run\n", "BACKEND_NAME = os.environ.get(\"QRMI_JOB_QPU_RESOURCES\", \"ibm_kingston\")\n", "os.environ.setdefault(\"QRMI_JOB_QPU_RESOURCES\", BACKEND_NAME)\n", "os.environ.setdefault(\"QRMI_JOB_QPU_TYPES\", \"ibm-quantum-compute-service\")\n", "\n", "print(f\"Backend: {BACKEND_NAME}\")\n", "print(\"Environment ready.\")" ] }, { "cell_type": "markdown", "id": "small-scale-header", "metadata": {}, "source": [ "\n", "\n", "## 小規模な例\n", "\n", "手順 1～3 では、簡単な回路を用いて QRMI API について解説します。 各ステップは、 IBM Quantum ハードウェアにおけるQRMIライフサイクルの主要なフェーズに対応しています。\n", "\n", "これらの初期段階におけるペイロードは、実行が高速かつ低コストであるように選ばれた、小さなベル状態回路である。\n", "\n", "これらの例では、リモートでのリソース割り当てやジョブ管理を実演するため、ハードウェアが使用されています。 ローカル回路シミュレータでは、QRMIサービスとスケジューラの統合を検証することはできません。 このノートブックを実行すると、 IBM Quantum 件のジョブが送信され、設定済みのバックエンドへのアクセスが必要となります。\n", "\n" ] }, { "cell_type": "markdown", "id": "step1-header", "metadata": {}, "source": [ "\n", "\n", "### ステップ1：古典的な問題を量子リソースに写像する\n", "\n", "QRMIワークフローの最初のステップは、 `QuantumResource` オブジェクトを作成し、そのオブジェクトにアクセスできることを確認することです。\n", "\n", "`get_target()` バックエンドのハードウェア記述（量子ビット数、基底ゲート、結合マップ）を取得し、それをQiskit `Target` オブジェクトとしてパッケージ化します。このオブジェクトは、ステップ2でトランスパイラーによって使用されます。\n", "\n", "\n", "\n", "### ステップ 2：量子ハードウェアでの実行に向けて問題を最適化する\n", "\n", "提出する前に、ステップ1で取得したオブジェクト `Target` を使用して、Qiskitで回路をバックエンドの命令セットアーキテクチャ（ISA）にトランスパイルしてください。\n", "\n", "この例では、 OpenQASM の3つの回路文字列とジョブのメタデータを `Payload.QiskitPrimitive`、 IBM プリミティブスキーマにカプセル化したものが生成されます。\n", "\n", "\n", "\n", "### ステップ 3: QRMI プリミティブを使用して実行する\n", "\n", "ペイロードが構築されると、このサンプルはジョブを送信し、完了をポーリングします。 `task_start()` 即座にジョブIDを返します。ステータスが `Queued`/`Running` でなくなるまでポーリング `task_status()` されます。 結果は生のJSON文字列として取得され、解析されて測定サンプルが抽出されます。\n", "\n", "以下のセルでは、取得、実行、クリーンアップをまとめて処理しているため、取得後の処理でエラーが発生した場合でも、ノートブックが所有するセッションは解放されます。\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "step1-ibm", "metadata": { "tags": [ "environment-ibm" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Resource id: ibm_kingston\n", "Resource type: ResourceType.IBMQuantumComputeService\n", "Accessible: True\n", "Lock token: 2ff43011-aed1-4436-a4df-40f37ec588b7\n", "\n", "Backend: ibm_kingston\n", "Qubits: 156\n", "Gates: ['cz', 'id', 'rx', 'rz', 'rzz', 'sx', 'x', 'xslow']\n", " ┌───┐ ░ ┌─┐ \n", " q_0: ┤ H ├──■───░─┤M├───\n", " └───┘┌─┴─┐ ░ └╥┘┌─┐\n", " q_1: ─────┤ X ├─░──╫─┤M├\n", " └───┘ ░ ║ └╥┘\n", "meas: 2/══════════════╩══╩═\n", " 0 1 \n", "\n", "Transpiled gate counts: OrderedDict([('rz', 6), ('sx', 3), ('measure', 2), ('cz', 1), ('barrier', 1)])\n", "Payload ready\n", "Job submitted: dai43g8mhr3c73e7a7o0\n", " Status: TaskStatus.Queued\n", " Status: TaskStatus.Running\n", " Status: TaskStatus.Completed\n", "\n", "Final status: TaskStatus.Completed\n", "\n", "Measurement counts: {'11': 487, '00': 254, '01': 177, '10': 106}\n", "\n", "Session released.\n" ] } ], "source": [ "# ── IBM Quantum ───────────────────────────────────────────────────────\n", "qrmi = QuantumResource(BACKEND_NAME, ResourceType.IBMQuantumComputeService)\n", "# ResourceType.IBMQuantumSystem is the alternative for directly provisioned systems\n", "\n", "print(f\"Resource id: {qrmi.resource_id()}\")\n", "print(f\"Resource type: {qrmi.resource_type()}\")\n", "print(f\"Accessible: {qrmi.is_accessible()}\")\n", "\n", "# Acquire exclusive access — open try/finally immediately so every\n", "# subsequent failure (target retrieval, transpilation, submission) is covered.\n", "# Release is skipped when running under Slurm: the SPANK plugin owns the\n", "# session lifecycle and will release it when the job finishes.\n", "lock = qrmi.acquire()\n", "print(f\"Lock token: {lock}\")\n", "try:\n", " # Retrieve backend capabilities\n", " transpiler_target = get_target(\n", " qrmi\n", " ) # calls qrmi.target() and parses the JSON\n", " target_json = json.loads(qrmi.target().value)\n", " config = target_json.get(\"configuration\", {})\n", " print(f\"\\nBackend: {config.get('backend_name', 'unknown')}\")\n", " print(f\"Qubits: {config.get('n_qubits', 'unknown')}\")\n", " print(f\"Gates: {config.get('basis_gates', [])}\")\n", "\n", " # ── IBM Quantum ───────────────────────────────────────────────────\n", "\n", " # Build a Bell state circuit\n", " qc = QuantumCircuit(2)\n", " qc.h(0)\n", " qc.cx(0, 1)\n", " qc.measure_all()\n", " print(qc.draw(\"text\"))\n", "\n", " # Transpile to ISA using the target retrieved in Step 1\n", " pm = generate_preset_pass_manager(\n", " optimization_level=1, target=transpiler_target\n", " )\n", " isa_circuit = pm.run(qc)\n", " print(f\"\\nTranspiled gate counts: {isa_circuit.count_ops()}\")\n", "\n", " # Build the QRMI payload\n", " # Payload.QiskitPrimitive wraps the IBM SamplerV2 input schema:\n", " # pubs: list of [qasm3_string, parameter_values] (shots goes at top level)\n", " # program_id: \"sampler\" or \"estimator\"\n", " shots = 1024\n", " pub = SamplerPub.coerce((isa_circuit,), shots)\n", " qasm3_str = qasm3.dumps(\n", " pub.circuit,\n", " disable_constants=True,\n", " allow_aliasing=True,\n", " experimental=qasm3.ExperimentalFeatures.SWITCH_CASE_V1,\n", " )\n", " # Parameter values as a flat list (empty for non-parametric circuits)\n", " param_array = pub.parameter_values.as_array(\n", " pub.circuit.parameters\n", " ).tolist()\n", "\n", " input_json = {\n", " \"pubs\": [\n", " [qasm3_str, param_array]\n", " ], # list-of-lists; shots at top level\n", " \"version\": 2,\n", " \"support_qiskit\": False, # True returns binary-encoded Qiskit result\n", " \"shots\": shots,\n", " }\n", " payload = Payload.QiskitPrimitive(\n", " input=json.dumps(input_json), program_id=\"sampler\"\n", " )\n", " print(\"Payload ready\")\n", "\n", " # ── IBM Quantum ───────────────────────────────────────────────────\n", "\n", " # Submit the job\n", " job_id = qrmi.task_start(payload)\n", " print(f\"Job submitted: {job_id}\")\n", "\n", " # Poll until complete\n", " while True:\n", " status = qrmi.task_status(job_id)\n", " print(f\" Status: {status}\")\n", " if status not in [TaskStatus.Running, TaskStatus.Queued]:\n", " break\n", " time.sleep(5)\n", "\n", " print(f\"\\nFinal status: {status}\")\n", "\n", " # Retrieve results\n", " # support_qiskit=False → plain JSON; parse directly without ResultDecoder\n", " if status == TaskStatus.Completed:\n", " raw = qrmi.task_result(job_id).value\n", " result = json.loads(raw)\n", " # IBM QCS plain-JSON result shape: {\"results\": [{\"data\": {\"meas\": {\"samples\": [...]}}}]}\n", " # samples is a list of hex-encoded integers; decode to zero-padded bitstrings\n", " samples = result[\"results\"][0][\"data\"][\"meas\"][\"samples\"]\n", " num_bits = sum(reg.size for reg in isa_circuit.cregs)\n", " from collections import Counter\n", "\n", " counts = Counter(format(int(s, 16), f\"0{num_bits}b\") for s in samples)\n", " print(f\"\\nMeasurement counts: {dict(counts.most_common(8))}\")\n", " qrmi.task_stop(job_id)\n", " else:\n", " print(f\"Job did not complete. Logs:\\n{qrmi.task_logs(job_id)}\")\n", "\n", "finally:\n", " # Release only in interactive sessions; under Slurm the SPANK plugin\n", " # manages the session lifecycle and calling release() here would\n", " # prematurely close a session it does not own.\n", " if not os.environ.get(\"SLURM_JOB_ID\"):\n", " qrmi.release(lock)\n", " print(\"\\nSession released.\")" ] }, { "cell_type": "markdown", "id": "higher-level-header", "metadata": {}, "source": [ "\n", "\n", "### Qiskitの高レベルインターフェース：QRMIServiceおよび SamplerV2\n", "\n", "上記の生のライフサイクルでは、すべての呼び出しを明示的に制御できます。 標準的なQiskitワークフローにおいて、QRMIは…を実装するプリミティブ `SamplerV2` を提供します `BaseSamplerV2`。\n", "\n", "\n", " `SamplerV2` ペイロードのシリアライズ、送信（`task_start`）、ポーリング、および結果のデコードを処理します。 HPCのバッチ環境（例えばSlurmなど）では、リソースの割り当てと解放はスケジューラとSPANKプラグインによって管理されます。 低レベルのAPIオブジェクトを直接使用する対話型の Python セッションでは、 および `acquire()` を使用して、専用セッションを明示的に管理 `release()` することができます。\n", "\n", "\n" ] }, { "cell_type": "code", "execution_count": 4, "id": "higher-level-sampler", "metadata": { "tags": [ "environment-ibm" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Using: ibm_kingston (ResourceType.IBMQuantumComputeService)\n", "Job ID: dai43jj9k43c73afhrhg | Status: JobStatus.QUEUED\n", "Counts (first 5): {'00010': 66, '00100': 28, '11000': 71, '00110': 23, '10100': 14}\n" ] } ], "source": [ "# QRMIService reads QRMI_JOB_QPU_RESOURCES / QRMI_JOB_QPU_TYPES set in Setup or Slurm\n", "service = QRMIService()\n", "qrmi_svc = service.resources()[0]\n", "print(f\"Using: {qrmi_svc.resource_id()} ({qrmi_svc.resource_type()})\")\n", "\n", "# Build an EfficientSU2 circuit\n", "circuit = efficient_su2(5, entanglement=\"linear\")\n", "circuit.measure_all()\n", "param_values = np.random.rand(circuit.num_parameters)\n", "\n", "pm = generate_preset_pass_manager(\n", " optimization_level=1, target=get_target(qrmi_svc)\n", ")\n", "isa_circuit = pm.run(circuit)\n", "\n", "# SamplerV2 executes jobs against the QRMI resource and decodes results into primitive containers\n", "sampler = SamplerV2(qrmi_svc, options={\"default_shots\": 1024})\n", "job = sampler.run([(isa_circuit, param_values)])\n", "print(f\"Job ID: {job.job_id()} | Status: {job.status()}\")\n", "\n", "# Poll with retry — re-raise immediately on permanent failures;\n", "# only retry on transient network/timeout errors (connection resets, 503s).\n", "_TRANSIENT = (\n", " \"503\",\n", " \"Service Unavailable\",\n", " \"ConnectionError\",\n", " \"TimeoutError\",\n", " \"timed out\",\n", " \"Connection reset\",\n", ")\n", "result = None\n", "for attempt in range(60):\n", " try:\n", " result = job.result() # blocks until complete\n", " break\n", " except Exception as e:\n", " if not any(tok in str(e) for tok in _TRANSIENT):\n", " raise\n", " print(f\" Transient error on attempt {attempt + 1}: {e}\")\n", " time.sleep(10)\n", "\n", "if result is not None:\n", " counts = result[0].data.meas.get_counts()\n", " print(f\"Counts (first 5): {dict(list(counts.items())[:5])}\")\n", "else:\n", " print(\"Job did not complete after retries.\")\n", "\n", "if job.errored():\n", " print(f\"Logs:\\n{job.logs()}\")" ] }, { "cell_type": "markdown", "id": "hpc-header", "metadata": {}, "source": [ "\n", "\n", "### HPCの文脈：Slurmによるリソースの割り当て\n", "\n", "HPCクラスタでは、ユーザーはSlurm GRES構文とQRMI SPANKプラグインのオプションを組み合わせて、量子リソースをリクエストします。 このプラグインは、認証情報とリソースの注入を自動的に処理します：\n", "\n", "```bash\n", "#SBATCH --gres=qpu:1\n", "#SBATCH --qpu=ibm_kingston\n", "python my_workflow.py # QRMI_JOB_QPU_RESOURCES and QRMI_JOB_QPU_TYPES are already set\n", "```\n", "\n", "アプリケーションコードは、実行時に割り当てられたリソースを自動的に検出します。バックエンド名がハードコードされることはありません：\n", "\n" ] }, { "cell_type": "code", "execution_count": 5, "id": "hpc-discovery", "metadata": { "tags": [ "environment-ibm" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Resources allocated by scheduler:\n", " ibm_kingston (ibm-quantum-compute-service)\n", "\n", "QRMIService found: ibm_kingston accessible=True\n" ] } ], "source": [ "# get_job_qpu_resources_and_types() reads QRMI_JOB_QPU_RESOURCES / QRMI_JOB_QPU_TYPES\n", "# set by the Slurm SPANK plugin (or manually above in Setup)\n", "qpus, qpu_types = get_job_qpu_resources_and_types()\n", "print(\"Resources allocated by scheduler:\")\n", "for qpu, qpu_type in zip(qpus, qpu_types):\n", " print(f\" {qpu} ({qpu_type})\")\n", "\n", "# QRMIService wraps this into a list of ready QuantumResource objects\n", "for r in QRMIService().resources():\n", " print(\n", " f\"\\nQRMIService found: {r.resource_id()} accessible={r.is_accessible()}\"\n", " )" ] }, { "cell_type": "markdown", "id": "large-scale-header", "metadata": {}, "source": [ "\n", "\n", "## 大規模ハードウェアの例：N上のSQD $_2$\n", "\n", "ここでは、これらすべてのコンポーネントを統合し、より大規模な完全な量子化学ワークフローを構築し、QRMIを通じて実際の IBM Quantum ハードウェア上で実行します。\n", "\n", "**SQDには**以下の機能が組み込まれています：\n", "\n", "1. CCSD振幅を用いて構築され `ffsim` 、CCSD振幅から初期化された局所ユニタリークラスター・ジャストロウ（LUCJ）アンザッツの量子サンプリング\n", "2. ヘビーヘックス格子トポロジーに合致する、ハードウェアを意識したトランスパイレーション（以下を通じて） `generate_lucj_pass_manager`\n", "3. IBM Quantum ハードウェア上でのサンプリング実行（QRMIを通じて `QRMIService` 管理） `SamplerV2`\n", "4. 古典的な後処理：自己一貫性のある構成の復元および反復的な部分空間の対角化（以下を用いて） `qiskit-addon-sqd`\n", "\n", "SQDを、結合距離 1.0 のN $_2$ に適用する。 $\\AA$ ここで、活性空間は基底 `cc-pVDZ` セット（26個の空間軌道、52個のスピン軌道／量子ビットに相当）から導出される。\n", "\n", "**Nの参照エネルギー $_2$ /cc-pVDZ アクティブ空間（結合距離 1.0 $\\AA$ ）：**\n", "\n", "* 基準エネルギー（別途SCI計算）： **− 109.22802922 Ha**\n", "\n", "\n", " 以下のSQDの実行例は、 IBM Quantum ハードウェア上でのQRMIのエンドツーエンド実行が成功したことを示しています。 LUCJを1回繰り返し、10万回の計算を行った結果、算出値は基準エネルギーより約 23.7 kcal/mol高くなり、化学的精度（≤ 1 kcal/mol）を満たしていない。 ショット数やSQDの反復回数を変更 `n_reps`することで精度が向上する可能性がありますが、さらなる検証が必要です。\n", "\n", "\n", "保存された実行では、バックエンドがそれらに対応できなかったため `(20, 20)` 、パ `ffsim` スマネージャーが反対スピンの相互作用 `(24, 24)` と を除去しました。 報告された結果は、この調整済み回路を用いて得られたものである。\n", "\n" ] }, { "cell_type": "code", "execution_count": 7, "id": "large-scale-all", "metadata": { "tags": [ "environment-ibm" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "WARN: Unable to to identify input symmetry using original axes.\n", "Different symmetry axes will be used.\n", "\n", "converged SCF energy = -108.929838385609\n", "N₂/cc-pVDZ active space: 26 orbitals (52 qubits), (5, 5) electrons\n", "SCF energy: -108.92983839 Ha\n", "Reference energy: -109.22802922 Ha\n", "E(CCSD) = -109.2177884185545 E_corr = -0.2879500329450047\n", "CCSD energy: -109.21778842 Ha\n", "Using QRMI resource: ibm_kingston\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "LUCJ circuit: 52 qubits, depth 3\n", "Transpiled gate counts: OrderedDict([('sx', 7041), ('rz', 6969), ('cz', 1858), ('measure', 52), ('x', 47), ('barrier', 1)])\n", "Job submitted via QRMI: dai43o0mhr3c73e7a81g | Status: JobStatus.QUEUED\n", "Waiting for results from hardware...\n", "Total shots collected: 100000\n", "Fraction of valid configurations sampled: 0.00319\n", "Expected fraction from uniform random: 9.6079e-07\n", "\n", "Running SQD post-processing...\n", "Iteration 1\n", " Subsample 0: Energy = -109.09341960 Ha | Subspace dim = 208849\n", " Subsample 1: Energy = -109.11738590 Ha | Subspace dim = 204304\n", " Subsample 2: Energy = -109.09947704 Ha | Subspace dim = 212521\n", "Iteration 2\n", " Subsample 0: Energy = -109.16015998 Ha | Subspace dim = 332929\n", " Subsample 1: Energy = -109.16823702 Ha | Subspace dim = 319225\n", " Subsample 2: Energy = -109.16189785 Ha | Subspace dim = 336400\n", "Iteration 3\n", " Subsample 0: Energy = -109.17759299 Ha | Subspace dim = 471969\n", " Subsample 1: Energy = -109.17937442 Ha | Subspace dim = 512656\n", " Subsample 2: Energy = -109.17970409 Ha | Subspace dim = 504100\n", "Iteration 4\n", " Subsample 0: Energy = -109.18410905 Ha | Subspace dim = 608400\n", " Subsample 1: Energy = -109.18265405 Ha | Subspace dim = 636804\n", " Subsample 2: Energy = -109.18608430 Ha | Subspace dim = 657721\n", "Iteration 5\n", " Subsample 0: Energy = -109.18870837 Ha | Subspace dim = 846400\n", " Subsample 1: Energy = -109.18890818 Ha | Subspace dim = 848241\n", " Subsample 2: Energy = -109.19022232 Ha | Subspace dim = 804609\n", "\n", "=== Energy Summary (N₂/cc-pVDZ active space) ===\n", "SCF energy: -108.92983839 Ha\n", "Reference energy: -109.22802922 Ha\n", "Final SQD energy: -109.19022232 Ha\n", "Energy error: 0.03780690 Ha (23.7238 kcal/mol)\n" ] }, { "data": { "text/plain": [ "\"Output" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "from qrmi.primitives.ibm import get_backend\n", "import math\n", "import os\n", "import time\n", "from functools import partial\n", "from dotenv import load_dotenv\n", "import numpy as np\n", "import matplotlib.pyplot as plt\n", "\n", "import pyscf\n", "import pyscf.gto\n", "import pyscf.scf\n", "import pyscf.cc\n", "import pyscf.mcscf\n", "import pyscf.ao2mo\n", "\n", "import ffsim\n", "import ffsim.qiskit\n", "from qiskit import QuantumCircuit, QuantumRegister\n", "from qiskit_addon_sqd.fermion import (\n", " SCIResult,\n", " diagonalize_fermionic_hamiltonian,\n", " solve_sci_batch,\n", ")\n", "from qrmi.primitives import QRMIService\n", "from qrmi.primitives.ibm import SamplerV2, get_target\n", "\n", "load_dotenv(override=False)\n", "os.environ.setdefault(\"QRMI_JOB_QPU_RESOURCES\", \"ibm_kingston\")\n", "os.environ.setdefault(\"QRMI_JOB_QPU_TYPES\", \"ibm-quantum-compute-service\")\n", "\n", "# ── Step 1: Map classical inputs to a quantum problem ─────────────────\n", "\n", "# Build N2 molecule at 1.0 Å bond distance\n", "mol = pyscf.gto.Mole()\n", "mol.build(\n", " atom=[[\"N\", (0, 0, 0)], [\"N\", (1.0, 0, 0)]],\n", " basis=\"cc-pvdz\",\n", " symmetry=\"Dooh\",\n", ")\n", "\n", "# Define active space: freeze 2 core orbitals\n", "n_frozen = 2\n", "active_space = range(n_frozen, mol.nao_nr())\n", "\n", "# Get molecular integrals\n", "scf = pyscf.scf.RHF(mol).run()\n", "norb = len(active_space)\n", "n_electrons = int(sum(scf.mo_occ[active_space]))\n", "n_alpha = (n_electrons + mol.spin) // 2\n", "n_beta = (n_electrons - mol.spin) // 2\n", "nelec = (n_alpha, n_beta)\n", "\n", "cas = pyscf.mcscf.CASCI(scf, norb, nelec)\n", "mo = cas.sort_mo(active_space, base=0)\n", "hcore, nuclear_repulsion_energy = cas.get_h1cas(mo)\n", "eri = pyscf.ao2mo.restore(1, cas.get_h2cas(mo), norb)\n", "\n", "# Reference energy from external SCI calculation\n", "reference_energy = -109.22802921665716\n", "\n", "print(\n", " f\"N₂/cc-pVDZ active space: {norb} orbitals ({2 * norb} qubits), {nelec} electrons\"\n", ")\n", "print(f\"SCF energy: {scf.e_tot:.8f} Ha\")\n", "print(f\"Reference energy: {reference_energy:.8f} Ha\")\n", "\n", "# Get CCSD amplitudes for initializing the LUCJ ansatz\n", "ccsd = pyscf.cc.CCSD(\n", " scf, frozen=[i for i in range(mol.nao_nr()) if i not in active_space]\n", ").run()\n", "t1 = ccsd.t1\n", "t2 = ccsd.t2\n", "print(f\"CCSD energy: {ccsd.e_tot:.8f} Ha\")\n", "\n", "# Discover backend via QRMIService (QRMI_JOB_QPU_RESOURCES set in Setup)\n", "service = QRMIService()\n", "qrmi_sqd = service.resources()[0]\n", "print(f\"Using QRMI resource: {qrmi_sqd.resource_id()}\")\n", "\n", "# get_backend() wraps the QRMI resource as a Qiskit backend for layout synthesis\n", "\n", "backend = get_backend(qrmi_sqd)\n", "\n", "# Set ansatz properties\n", "n_reps = 1\n", "pairs_aa = [(p, p + 1) for p in range(norb - 1)]\n", "pairs_ab = None\n", "\n", "# Create pass manager adapted to hardware heavy-hex topology\n", "pass_manager, pairs_ab = ffsim.qiskit.generate_lucj_pass_manager(\n", " backend=backend,\n", " norb=norb,\n", " connectivity=\"heavy-hex\",\n", " interaction_pairs=(pairs_aa, pairs_ab),\n", " optimization_level=3,\n", ")\n", "\n", "# Create the compressed LUCJ ansatz operator\n", "ucj_op = ffsim.UCJOpSpinBalanced.from_t_amplitudes(\n", " t2=t2,\n", " t1=t1,\n", " n_reps=n_reps,\n", " interaction_pairs=(pairs_aa, pairs_ab),\n", " optimize=True,\n", " options=dict(maxiter=1000),\n", ")\n", "\n", "# Assemble the circuit\n", "qubits = QuantumRegister(2 * norb, name=\"q\")\n", "circuit = QuantumCircuit(qubits)\n", "circuit.append(ffsim.qiskit.PrepareHartreeFockJW(norb, nelec), qubits)\n", "circuit.append(ffsim.qiskit.UCJOpSpinBalancedJW(ucj_op), qubits)\n", "circuit.measure_all()\n", "print(f\"LUCJ circuit: {circuit.num_qubits} qubits, depth {circuit.depth()}\")\n", "\n", "# ── Step 2: Optimize for quantum hardware execution ───────────────────\n", "\n", "isa_circuit = pass_manager.run(circuit)\n", "print(f\"Transpiled gate counts: {isa_circuit.count_ops()}\")\n", "\n", "# ── Step 3: Execute using Qiskit primitives (QRMI SamplerV2) ─────────\n", "\n", "sampler = SamplerV2(qrmi_sqd, options={\"default_shots\": 100_000})\n", "# sampler.options.environment.job_tags = [\"TUT_SQD\"]\n", "job = sampler.run([(isa_circuit,)])\n", "print(f\"Job submitted via QRMI: {job.job_id()} | Status: {job.status()}\")\n", "print(\"Waiting for results from hardware...\")\n", "\n", "_TRANSIENT = (\n", " \"503\",\n", " \"Service Unavailable\",\n", " \"ConnectionError\",\n", " \"TimeoutError\",\n", " \"timed out\",\n", " \"Connection reset\",\n", ")\n", "primitive_result = None\n", "for attempt in range(120):\n", " try:\n", " primitive_result = job.result()\n", " break\n", " except Exception as e:\n", " if not any(tok in str(e) for tok in _TRANSIENT):\n", " raise\n", " print(f\" Transient error on attempt {attempt + 1}: {e}\")\n", " time.sleep(10)\n", "\n", "if primitive_result is None:\n", " raise RuntimeError(\"Job did not complete after retries\")\n", "\n", "pub_result = primitive_result[0]\n", "bit_array = pub_result.data.meas\n", "print(f\"Total shots collected: {bit_array.num_shots}\")\n", "\n", "# ── Step 4: Post-process and return result in classical format ────────\n", "\n", "\n", "def is_valid_bitstring(\n", " bitstring: str, norb: int, nelec: tuple[int, int]\n", ") -> bool:\n", " n_a, n_b = nelec\n", " return (\n", " len(bitstring) == 2 * norb\n", " and bitstring[norb:].count(\"1\") == n_a\n", " and bitstring[:norb].count(\"1\") == n_b\n", " )\n", "\n", "\n", "num_valid = sum(\n", " is_valid_bitstring(b, norb, nelec) for b in bit_array.get_bitstrings()\n", ")\n", "valid_fraction = num_valid / bit_array.num_shots\n", "expected_random = (\n", " math.comb(norb, n_alpha) * math.comb(norb, n_beta) / (2 ** (2 * norb))\n", ")\n", "print(f\"Fraction of valid configurations sampled: {valid_fraction:.5f}\")\n", "print(f\"Expected fraction from uniform random: {expected_random:.4e}\")\n", "\n", "# Configure SQD eigensolver\n", "energy_tol = 1e-3\n", "occupancies_tol = 1e-3\n", "max_iterations = 5\n", "num_batches = 3\n", "samples_per_batch = 300\n", "symmetrize_spin = True\n", "carryover_threshold = 1e-4\n", "max_cycle = 200\n", "\n", "# Hartree-Fock initial occupancy guess\n", "initial_occupancies = (\n", " np.array([1] * n_alpha + [0] * (norb - n_alpha)),\n", " np.array([1] * n_beta + [0] * (norb - n_beta)),\n", ")\n", "\n", "sci_solver = partial(solve_sci_batch, spin_sq=0.0, max_cycle=max_cycle)\n", "result_history = []\n", "\n", "\n", "def callback(results: list[SCIResult]):\n", " result_history.append(results)\n", " iteration = len(result_history)\n", " print(f\"Iteration {iteration}\")\n", " for i, res in enumerate(results):\n", " subspace_dim = np.prod(res.sci_state.amplitudes.shape)\n", " print(\n", " f\" Subsample {i}: Energy = {res.energy + nuclear_repulsion_energy:.8f} Ha | Subspace dim = {subspace_dim}\"\n", " )\n", "\n", "\n", "print(\"\\nRunning SQD post-processing...\")\n", "rng = np.random.default_rng(42)\n", "sqd_result = diagonalize_fermionic_hamiltonian(\n", " hcore,\n", " eri,\n", " bit_array,\n", " samples_per_batch=samples_per_batch,\n", " norb=norb,\n", " nelec=nelec,\n", " num_batches=num_batches,\n", " energy_tol=energy_tol,\n", " occupancies_tol=occupancies_tol,\n", " max_iterations=max_iterations,\n", " sci_solver=sci_solver,\n", " symmetrize_spin=symmetrize_spin,\n", " initial_occupancies=initial_occupancies,\n", " carryover_threshold=carryover_threshold,\n", " callback=callback,\n", " seed=rng,\n", ")\n", "\n", "final_energy = sqd_result.energy + nuclear_repulsion_energy\n", "energy_error = final_energy - reference_energy\n", "\n", "print(\"\\n=== Energy Summary (N₂/cc-pVDZ active space) ===\")\n", "print(f\"SCF energy: {scf.e_tot:.8f} Ha\")\n", "print(f\"Reference energy: {reference_energy:.8f} Ha\")\n", "print(f\"Final SQD energy: {final_energy:.8f} Ha\")\n", "print(\n", " f\"Energy error: {energy_error:.8f} Ha ({abs(energy_error) * 627.5:.4f} kcal/mol)\"\n", ")\n", "\n", "# ── Visualization ─────────────────────────────────────────────────────\n", "\n", "x1 = range(len(result_history))\n", "min_e = [\n", " min(res, key=lambda r: r.energy).energy + nuclear_repulsion_energy\n", " for res in result_history\n", "]\n", "e_diff = [abs(e - reference_energy) for e in min_e]\n", "chem_accuracy = 0.001 # ~1 mHa / ~0.6 kcal/mol\n", "\n", "y2 = np.sum(sqd_result.orbital_occupancies, axis=0)\n", "x2 = range(len(y2))\n", "\n", "fig, axs = plt.subplots(1, 2, figsize=(12, 5))\n", "\n", "# Energies convergence plot\n", "axs[0].plot(x1, e_diff, label=\"Energy error\", marker=\"o\")\n", "axs[0].set_xticks(list(x1))\n", "axs[0].set_xticklabels(list(x1))\n", "axs[0].set_yscale(\"log\")\n", "axs[0].axhline(\n", " y=chem_accuracy,\n", " color=\"#BF5700\",\n", " linestyle=\"--\",\n", " label=\"Chemical accuracy (1 mHa)\",\n", ")\n", "axs[0].set_title(\"SQD Energy Error vs Iteration\")\n", "axs[0].set_xlabel(\"Iteration\")\n", "axs[0].set_ylabel(\"Energy Error (Ha)\")\n", "axs[0].legend()\n", "\n", "# Spatial orbital occupancy plot\n", "axs[1].bar(x2, y2, width=0.8)\n", "axs[1].set_xticks(list(x2)[::2])\n", "axs[1].set_xticklabels(list(x2)[::2])\n", "axs[1].set_title(\"Avg Occupancy per Spatial Orbital\")\n", "axs[1].set_xlabel(\"Spatial Orbital Index\")\n", "axs[1].set_ylabel(\"Avg Occupancy\")\n", "\n", "plt.tight_layout()\n", "plt.show()" ] }, { "cell_type": "markdown", "id": "next-steps", "metadata": {}, "source": [ "\n", "\n", "## 次のステップ\n", "\n", "\n", " この作品に興味を持たれた方は、以下の資料もご覧になってみてはいかがでしょうか\n", "\n", " * [サンプルベース量子対角化チュートリアル](/docs/tutorials/sample-based-quantum-diagonalization) — IBM Quantum Platform における完全な SQD 化学ワークフロー（大規模な分子や基底関数セットを含む）\n", " * [サンプルベースのクリロフ量子対角化](/docs/tutorials/sample-based-krylov-quantum-diagonalization) — フェルミオン格子モデルにおける時間発展回路を用いた関連手法\n", " * [`qiskit-addon-sqd` ドキュメント](/docs/addons/qiskit-addon-sqd) — SQD後処理ライブラリの完全なAPIリファレンスおよび追加のチュートリアル\n", " * [QRMI GitHub リポジトリ](https://github.com/qiskit-community/qrmi) — ソースコード、追加のバックエンド例（CUDA-Q、C、Lua）\n", " * [QRMIの概要論文](https://arxiv.org/abs/2506.10052) — QRMIアーキテクチャおよびHPC統合に関する技術的解説\n", " * [IBM Quantum Compute サービスセッションガイド](/docs/guides/run-jobs-session) — セッションとQRMI `acquire`／ IBM`release` バックエンドのライフサイクルとの関係\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": 5 }