Qiskit Functionsの概要

注意

• Qiskit Functionsは、IBM Quantum® Premium Plan、Flex Plan、およびOn-Prem（IBM Quantum Platform API経由）Planのユーザーのみが利用できる実験的な機能です。現在プレビューリリースの状態であり、変更される場合があります。

Package versions

このページのコードは、以下の要件を使用して開発されました。 これらのバージョン以上を使用することをお勧めします。

qiskit[all]~=1.4.1
qiskit-ibm-runtime~=0.37.0
qiskit-ibm-catalog~=0.4

Qiskit Functionsは、量子ソフトウェア開発ワークフローの一部を抽象化することで、ユーティリティスケールのアルゴリズム探索とアプリケーション開発を簡素化・加速します。これにより、Qiskit Functionsはコードの手書きや実験の微調整に通常費やされる時間を節約できます。

Functionには2つの形式があります：

タイプ	何をするか？	入出力の例	誰向けか？
Circuit function	Circuitを実行するための簡素化されたインターフェース。トランスパイル、エラー抑制、エラー軽減を抽象化します	入力: 抽象的なPUBオブジェクト 出力: 軽減された期待値	ハードウェアの最適化やエラー処理に集中することなく、新しいアルゴリズムやアプリケーションを発見するためにQiskitを使用する研究者向け。Circuit FunctionはカスタムApplication Functionの構築に使用できます。
Application function	アルゴリズムの探索やドメイン固有のユースケースなど、より高レベルのタスクを対象とします。古典的な入出力でタスクを解決するための量子ワークフローを抽象化します	入力: 分子、グラフ 出力: 基底状態・励起状態のエネルギー、コスト関数の最適値	古典的なデータを量子Circuitにマッピングすることなく、既存の大規模古典ワークフローに量子を統合する、非量子分野の研究者向け。

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime

FunctionはIBM®およびサードパーティパートナーによって提供されます。それぞれが特定のワークロード特性に対して高性能であり、独自のパフォーマンスチューニングオプションがあります。

利用可能なFunctionの概要

Circuit functions

名前	プロバイダー	推奨用途	独自のメリット
Tensor-Network Error Mitigation Guide API reference	Algorithmiq	低重みのオブザーバブルとループのないCircuitを持つワークロード。	測定オーバーヘッドと分散を削減し、関連するCircuitクラスに対してゼロノイズ外挿（ZNE）や確率的エラーキャンセレーション（PEC）などの標準的なエラー軽減ベースラインを上回ります。
QESEM: Error Suppression and Error Mitigation Guide API reference	Qedma	分数またはパラメータ化されたGateを持つCircuit、高重みのオブザーバブル、バイアスのない期待値と正確な実行時間の見積もりが必要なワークフローを含むワークロード。	低い分散とリソースオーバーヘッドでバイアスのない期待値を生成し、関連するCircuitクラスに対してZNEおよびPECを上回ります。
Performance Management Guide API reference	Q-CTRL	パラメトリックCircuit、深いCircuit、または多数のCircuit実行を必要とするワークロード。	量子アルゴリズムにAI駆動のエラー抑制を自動的に適用し、IBMデバイスのパフォーマンスを最大化して、ショット数、計算時間、コストを削減しながら正確な結果を提供します。 SamplerおよびEstimatorプリミティブの実行精度を改善するゼロオーバーヘッドの手法で、あらゆる重みのオブザーバブルと互換性があります。

Application functions

名前	プロバイダー	推奨用途	独自のメリット
QUICK-PDE Guide API reference	ColibriTD	マルチフィジックスPDEに量子計算を使用します。 量子および物理モデリングパラメータの完全な制御を維持しながら、量子ハードウェア向けのシミュレーションワークフローを準備します。	高度な解のエンコーディングとスペクトル法によって正確でスケーラブルなPDE解を提供する堅牢なハイブリッドVQAフレームワークを提供し、量子対応のシミュレーション能力を構築しようとするチームの理想的な出発点となります。
Quantum Portfolio Optimizer Guide API reference	Global Data Quantum	リスクを最小化しながらリターンを最大化する最適なポートフォリオ戦略を時間をかけて探索し、取引戦略のバックテストを可能にする金融最適化のワークロード。	この金融ユースケースに特化してVQE量子アルゴリズムを高度に適応させ、最適化された実行戦略とオプティマイザー、ポートフォリオ最適化に合わせたノイズ対応エラー軽減技術を使用して、組み合わせ最適化問題を解決します。
HI-VQE Chemistry Guide API reference	Qunova Computing	多体電子構造問題の解決を必要とする計算化学、分子シミュレーション、材料科学、またはあらゆるハミルトニアンシミュレーションのワークロード。	40〜60 qubitでモデル化された問題に対して化学的精度（1 kcal/mol、1.6 mHa）を達成する強化されたSQDを使用して分子電子構造を解決し、収束速度または精度においてスーパーコンピュータ上の一部の古典的解法または標準SQDを数桁上回ります。
Iskay Quantum Optimizer Guide API reference	Kipu Quantum	スケジューリング、物流、ルーティング、QUBO/HUBO問題などの最適化ワークロード。	量子最適化ルーチンのための調整可能な古典的前処理・後処理手法を統合しています。 選択されたHUBOベンチマークで古典的ソルバー（CPLEX、シミュレーテッドアニーリング、タブーサーチ）に対する実行時間優位性を提供します。 難しい課題であるMarket Split ms_5_100を数時間以内に解決します（このチュートリアルを参照）。
Singularity Machine Learning Guide API reference	Multiverse Computing	IBMハードウェアで実行される量子最適化を活用することで、精度や計算効率の向上が期待できる古典的な機械学習分類ワークフロー。	Random ForestやXGBoostなどの古典モデルと同等またはそれを超える精度を提供しながら、大幅に少ない学習器とよりコンパクトなアンサンブルで動作します。 量子最適化された投票によって駆動され、最も情報量の多い学習器を選択し、決定境界を精緻化することで、より高い効率性、モデルの複雑さの削減、より堅牢なパフォーマンスをもたらします。
Optimization Solver Guide API reference	Q-CTRL	バイナリ最適化問題または任意のバイナリコスト関数にマッピングできる組み合わせ問題。 任意の次数のコスト関数と最大デバイス規模までの問題サイズをサポートします。	ノイズ対応のエンドツーエンド量子最適化ソリューションで、高レベルの問題定義の入力を可能にし、ユーティリティスケールの量子ハードウェア上で古典的に困難な組み合わせ問題の正確な解を自動的に見つけます。 深い量子の専門知識なしに、エラー抑制、効率的なマッピング、ハイブリッド量子古典最適化を処理することで、フルデバイススケールでの最適化タスクの複雑さを抽象化します。

Qiskit Functionsを始める

Premium、Flex、およびOn-Prem（IBM Quantum Platform API経由）プランのユーザーは、IBM Qiskit Functionsを無料で使い始めることができます。また、カタログにFunctionを提供しているパートナーの1社からライセンスを取得することもできます。

サードパーティQiskit Functionsの無料トライアルをリクエストする

新しい無料トライアルをリクエストするには、Qiskit Functions Catalogに移動して詳細パネルを確認します。Request a free trialをクリックし、IBM Cloud AccessGroupIdを含む、Functionsパートナーが要求する情報を入力します：

1. IBM Cloud IAMに移動します。
2. 利用資格を確認します。
   • トップバーでアカウントをXXXXXXX - [Organization Name]という形式のアカウントに切り替えます。
   • 組織がPremiumアカウントに関連付けられているものと同じであることを確認します。
   • 「[あなたの名前]のアカウント」と表示される場合は、Premiumアクセスの対象外の_個人_アカウントを使用しています。
3. アクセスグループIDを確認します。
   • グループ名をクリックします。
   • 詳細をクリックします。
   • アクセスグループIDをコピーします。AccessGroup-で始まるはずです。

Qiskit Functions Catalogクライアントをインストールする

1. Qiskit Functionsの使用を開始するには、IBM Qiskit Functions Catalogクライアントをインストールします：

   pip install qiskit-ibm-catalog

2. IBM Quantum PlatformダッシュボードからAPIキーを取得し、Python仮想環境を有効化します。仮想環境がまだ設定されていない場合は、インストール手順を参照してください。

   信頼できるPython環境（個人用ラップトップやワークステーションなど）で作業している場合は、save_account()メソッドを使用して認証情報をローカルに保存します。（信頼できない環境（共有または公共のコンピューターなど）を使用してIBM Quantum Platformに認証する場合は、次のステップにスキップしてください。）

   save_account()を使用するには、シェルでpythonを実行し、以下を入力します：

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   QiskitFunctionsCatalog.save_account(channel="ibm_quantum_platform", token="<your-token>", instance="<instance-crn>")

   exit()と入力します。これ以降、サービスへの認証が必要な場合は、以下のようにして認証情報を読み込むことができます：

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   catalog = QiskitFunctionsCatalog()

# Load saved credentials
from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

3. **セキュリティリスクを最小化するために、信頼できないマシンや外部クラウドのPython環境でのコード実行は避けてください。**信頼できない環境（例えば公共のコンピューター）を使用する必要がある場合は、IBM Cloud APIキーページで削除することで使用後にAPIキーを変更してリスクを軽減します。詳細については、ユーザーAPIキーの管理のトピックを参照してください。この状況でサービスを初期化するには、以下のセクションを展開して使用できるコードを確認してください：

   信頼できない環境でのサービスの初期化

   from qiskit_ibm_catalog import QiskitFunctionsCatalog
   
   # After using the following code, delete your API key on the IBM Quantum Platform home dashboard
   catalog = QiskitFunctionsCatalog(token="<YOUR_API_KEY>") # Use the 44-character API_KEY you created and saved from the IBM Quantum Platform Home dashboard

   注意

   APIキーを保護してください！ ソースコード、Pythonスクリプト、またはノートブックファイルにキーを含めないでください。他の人とコードを共有する際は、APIキーがPythonスクリプト内に直接埋め込まれていないことを確認してください。代わりに、キーなしでスクリプトを共有し、安全な設定方法の手順を提供してください。

   誤ってキーを誰かと共有したり、Gitなどのバージョン管理に含めてしまった場合は、IBM Cloud APIキーページで削除してすぐにキーを取り消し、リスクを軽減してください。詳細については、ユーザーAPIキーの管理のトピックを参照してください。

4. 認証が完了したら、アクセス可能なQiskit Functions Catalogのfunctionを一覧表示できます：

catalog.list()

[QiskitFunction(qunova/hivqe-chemistry),
 QiskitFunction(global-data-quantum/quantum-portfolio-optimizer),
 QiskitFunction(algorithmiq/tem),
 QiskitFunction(qedma/qesem),
 QiskitFunction(multiverse/singularity),
 QiskitFunction(ibm/circuit-function),
 QiskitFunction(q-ctrl/optimization-solver),
 QiskitFunction(colibritd/quick-pde),
 QiskitFunction(q-ctrl/performance-management),
 QiskitFunction(kipu-quantum/iskay-quantum-optimizer)]

有効なFunctionを実行する

カタログオブジェクトをインスタンス化したら、catalog.load(provider/function-name)を使用してFunctionを選択できます：

ibm_cf = catalog.load("ibm/circuit-function")

各Qiskit Functionにはカスタムの入力、オプション、出力があります。実行したいFunctionの詳細については、各Functionのドキュメントページを確認してください。デフォルトでは、すべてのユーザーは一度に1つのFunction jobのみ実行できます：

# This cell is hidden from users
# It gets these details programmatically so we can test this notebook
from qiskit_ibm_runtime import QiskitRuntimeService
from qiskit.circuit.random import random_circuit

service = QiskitRuntimeService()
instance = service.active_account()["instance"]
backend_name = service.least_busy().name

circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits

job = ibm_cf.run(
    pubs=[(circuit, observable)],
    instance=instance,
    backend_name=backend_name,  # E.g. "ibm_fez"
)

job.job_id

'7f08c9d5-471b-4da2-92e7-4f2cb94c23a8'

Jobのステータスを確認する

ヒント

現在、IBM QuantumワークロードテーブルはQiskit Runtimeワークロードのみを反映しています。Qiskit FunctionワークロードのステータスはQiskit Runtimeワークロードテーブルに表示されません。job.status()を使用して現在のステータスを確認してください。

Qiskit Functionのjob_idを使用して、実行中のJobのステータスを確認できます。以下のステータスがあります：

• QUEUED: リモートプログラムがQiskit Functionのキューに入っています。キューの優先度はQiskit Functionsの使用量に基づきます。
• INITIALIZING: リモートプログラムが起動中です。リモート環境のセットアップと依存関係のインストールが含まれます。
• RUNNING: プログラムが実行中です。特定のFunctionでサポートされている場合、いくつかのより詳細なステータスも含まれます：
  • RUNNING: MAPPING: Functionが現在、古典的な入力を量子入力にマッピングしています。
  • RUNNING: OPTIMIZING_FOR_HARDWARE: Functionが選択されたQPU向けに最適化しています。これにはCircuitのトランスパイル、QPUの特性評価、オブザーバブルのバックプロパゲーションなどが含まれる場合があります。
  • RUNNING: WAITING_FOR_QPU: FunctionがQiskit RuntimeにJobを送信し、キューで待機しています。
  • RUNNING: EXECUTING_QPU: FunctionがアクティブなQiskit RuntimeのJobを持っています。
  • RUNNING: POST_PROCESSING: Functionが結果を後処理しています。エラー軽減、量子結果の古典的なマッピングなどが含まれる場合があります。
• DONE: プログラムが完了し、job.results()で結果データを取得できます。
• ERROR: 問題が発生してプログラムの実行が停止しました。job.result()でエラーメッセージを取得してください。
• CANCELED: プログラムがキャンセルされました。ユーザー、サービス、またはサーバーによってキャンセルされた場合があります。

job.status()

'QUEUED'

結果を取得する

プログラムがDONEになったら、job.results()を使用して結果を取得できます。出力形式はFunctionによって異なりますので、各Functionのドキュメントに従ってください：

result = job.result()
print(result)

PrimitiveResult([PubResult(data=DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>)), 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})

Jobはいつでもキャンセルできます：

job.stop()

'Job has been stopped.'

Qiskit Functionsで実行した過去のJobを一覧表示する

jobs()を使用して、Qiskit Functionsに送信されたすべてのJobを一覧表示できます：

old_jobs = catalog.jobs()
old_jobs

[<Job | f6c29f49-4d5f-4fff-aca6-2e9a115b9763>,
 <Job | 7f08c9d5-471b-4da2-92e7-4f2cb94c23a8>,
 <Job | 62fe9176-d1e5-467e-b2bd-7a3f3c7be4e5>,
 <Job | af525b2e-16b1-45a1-80bb-dbd94ce30258>,
 <Job | b95a7a57-c1ad-4958-b7ac-953e4e1ee824>,
 <Job | 7bfa33da-0f17-4e67-84b6-f556f7eeb436>,
 <Job | ca46c191-9eb9-4de6-bfa7-b60d7eb29b5e>,
 <Job | 6ac0ba93-3831-43fb-9fb9-760da2225e06>,
 <Job | f0e38071-060d-47e8-988d-9cc1f69358e3>,
 <Job | 629cf110-e490-4675-8a07-f6d298d166b0>]

特定のJobのJob IDがすでにわかっている場合は、catalog.get_job_by_id()でJobを取得できます：

# First, get the most recent job that has been executed.
latest_job = old_jobs[0]

# We can also get that same job with get_job_by_id
job_by_id = catalog.get_job_by_id(latest_job.job_id)

# Verify that the job is the same using both retrieval methods.
assert job_by_id.job_id == latest_job.job_id

# Print the job_id for this job.
print(job_by_id.job_id)

f6c29f49-4d5f-4fff-aca6-2e9a115b9763

エラーメッセージを取得する

プログラムのステータスがERRORの場合、job.error_message()を使用して以下のようにエラーメッセージを取得します：

job.error_message()

qiskit.exceptions.QiskitError: 'Workflow execution failed -- https://docs.quantum.ibm.com/errors#9999'

次のステップ

おすすめ

• Circuit functionsを探索することで、トランスパイルやエラー処理を管理することなく、新しいアルゴリズムやアプリケーションを構築できます。
• Application functionsを探索することで、古典的な入出力を使用してドメイン固有のタスクを解決できます。
• Qiskit FunctionsのAPIリファレンスドキュメントを参照してください。
• 実践的な経験を積むには、Qiskit Functionsを実演するチュートリアルをお試しください。