ツールの機能リファレンス

ツールの機能リファレンス#

1. Experiment#

1.1. 過去の実験の読み込み#

Experimentクラスでは過去の実験ログを読み込んで、途中から実験を再開したり、他の人の実験を再現実行することができます。 実験を再現する方法については次の章で扱うため、ここでは過去の実験を読み込む方法について紹介します。

  • パターン1: 自分で行った実験を読み込む場合 自分のローカル環境やクラウド環境で行った実験については、以下のようにQXMTで生成されるログファイルであるexperiment.jsonを指定することで読み込むことができます。読み込んだ際にワーキングディレクトリ等のディレクトリ構成が読み込み元と異なる場合には自動的に現在の実行ディレクトリに更新されます。

読み込んだ後にrunメソッドで実験を再開すると連続した連番がrun_idとして付与され、一連の実験として管理することができます。

import qxmt

experiment_path = "/your_project/experiments/your_experiment/experiment.json"
experiment = qxmt.Experiment().load(experiment_path)

  • パターン2: 他の人が行った実験を読み込む場合 他の人が行った実験を読み込む場合、その環境が共有サーバや共有クラウド等アクセスできる状態にある場合にはパターン1と同様の方法で読み込むことができます。その際にconifgのパスを適切に設定すること、カスタムモジュールを利用している場合はPythonの実行パスを通す必要があることに注意が必要です。

もし、異なる環境で実験が行われており直接アクセスできない場合には対象の実験のexperiments/your_experimentフォルダ (QXMTによって自動生成・管理されるフォルダ)とカスタムモジュールを利用している場合には該当コードを自分の環境にコピーしてくる必要があります。その後は、これまでと同様の手順で読み込むことが可能です。

1.2. 実験の再現#

Experimentインスタンスで現在管理中の実験やloadメソッドで読み込んだ実験の特定のrun_idに対して実験の再現を行い、その成果物であるモデル等を取得する方法を紹介します。

特定のrun_idの実験を再現する場合には、runがすでに蓄積されているExperimentインスタンスに対して以下のようにreproduceメソッドを実行します。 すると、対象実験の再現実行が行われ最終的にモデルの精度がログに記載されている値と等しいかどうかで再現の成功有無を判定します。

他の人の実験を再現する場合など、ディレクトリ構成が異なる場合はconfigファイル内のカスタムモジュールのpathを再確認することとPythonの実行パスが通っていることを再度確認して下さい。

reproduced_artifact, reproduced_result = experiment.reproduce(run_id=1, check_commit_id=True)

設定できるパラメータとして以下の2つがあります。

  • run_id: 再現実行したい実験のrun_id

  • check_commit_id: 再現時にgitのcommit idレベルでチェックを行いたい時はTrueに設定

再現に成功すると、reproduced_artifactとreproduced_resultという二つの値が返されます。これらの値は、通常のrunメソッド実行時と同様にデータセットやモデルを格納したいインスタンスとなっており、必要に応じて取得や可視化を行うことができます。

2. Dataset#

2.1 OpenMLを用いたデータセットの読み込み#

QXMTではデータセットの準備を簡略化するためにOpenMLのAPIをconfigファイル経由で利用できるようになっています。ここでは、利用したいデータセットを検索しconfigに設定して利用するまでの流れを紹介します。

実験で「Fashion-MNIST」のデータセットを利用したいとします。その場合は、まずOpenMLのデータセット検索ページで利用し該当するデータセットを探し、詳細ページへ移動します。詳細ページに移動すると以下のようなデータセットの情報を確認することができます。この中の「ID」をconfigに記載します (今回の場合はID=”40996”)。

データセット詳細ページ

検索した情報を元にRunのconfigを以下のように設定します。(設定が必要な部分のみ抜粋)

dataset:
  type: "openml"
  openml:
    name: "Fashion-MNIST"
    id: 40996
    return_format: "numpy"
    save_path: "data/openml/Fashion-MNIST/dataset.npz"

  • type: QXMTで利用するデータセットタイプを指定。OpenMLのデータセット利用する場合はopenmlと設定

  • openml.name: OpenML上でのデータセット名

  • openml.id: OpenML上でのデータセットのID

  • openml.return_format: データセットのフォーマットを指定。pandasまたはnumpy形式を指定可能

  • openml.save_path: ダウンロードしたデータセットを保存するパスを指定。nullの場合は保存しない

openml.nameとopenml.idは、どちらか一方のみでも利用可能です。openml.nameのみが設定された場合はAPIを使って内部で該当するデータセットが検索されます。openml.idは対象のデータセットを一意に特定することができるため、こちらの値を設定することを推奨しています。openml.nameとopenml.idの両方が設定された場合はopenml.idの値が優先されます。

2.2 TensorFlow Datasetsを用いたデータセットの読み込み#

QXMTではTensorFlow Datasetsのデータセットをconfigファイル経由で読み込み、QXMT内部で利用するnumpy配列の形式に変換できます。この機能を利用する場合は、optional dependencyとしてqxmt[tfds]をインストールしてください。

pip install "qxmt[tfds]"

configでは以下のように設定します。(設定が必要な部分のみ抜粋)

dataset:
  tfds:
    name: "mnist"
    split: ["train", "test"]
    return_format: "numpy"
    data_dir: "data/tfds_cache"
    save_path: "data/tfds/mnist/dataset.npz"
    download: true
    shuffle_files: false

  • tfds.name: TensorFlow Datasets上のデータセット名

  • tfds.split: 読み込むsplitを指定。"train"のような文字列、または["train", "test"]のようなリストを指定可能。複数指定した場合、QXMTでは読み込んだデータを結合してからdataset.splitの比率に従って再分割します

  • tfds.return_format: データセットの返却形式を指定。現在はnumpyまたはarrayをサポート

  • tfds.data_dir: TensorFlow Datasetsが元データをダウンロード・展開・キャッシュするディレクトリ。nullの場合はTensorFlow Datasetsのデフォルト設定を利用

  • tfds.save_path: QXMTが読み込み後のXとyをnumpy形式で保存するパス。.npzまたは.npyを指定可能。nullの場合は保存しない

  • tfds.download: データセットが未取得の場合にTensorFlow Datasetsによるダウンロードを許可するかどうか

  • tfds.shuffle_files: TensorFlow Datasets側でファイル単位のシャッフルを行うかどうか

tfds.data_dirとtfds.save_pathは用途が異なります。tfds.data_dirはTensorFlow Datasetsのキャッシュ場所であり、TFDS形式の元データを管理します。一方、tfds.save_pathはQXMTが読み込み後にnumpy配列として保存する出力先です。通常はtfds.data_dirのみで十分ですが、後からfile loaderで再利用したい場合や、QXMTで読み込んだnumpyデータを成果物として残したい場合はtfds.save_pathも指定します。

QXMTのDatasetBuilderは、読み込んだデータセットをdataset.splitのtrain_ratio、validation_ratio、test_ratioに従って分割します。そのため、TFDSのsplitに["train", "test"]を指定した場合でも、TFDS上のtrainとtestがそのままQXMTのtrain/testとして保持されるわけではありません。

2.3 Raw Processing LogicとTransform LogicのChain処理#

QXMTからデフォルトで提供されているLogicに限らず、ユーザが独自に定義したカスタムのRaw Processing LogicとTransform LogicについてもChain処理として、複数の処理を順に適用することが可能です。configでの定義方法は、各種ロジックをリスト形式で順に記載していきます。

以下の例では、データセットに対してnormalizationを行ったのち、dimension_reduction_by_pcaで次元圧縮を行う処理を定義しています。 yamlにおけるリストの表記方法はいくつかパターンがありますが、yamlで許可されている記法であれば問題ありません。

transform_logic:
- module_name: qxmt.datasets.transform.normalizer
  implement_name: normalization
  params: null
- module_name: qxmt.datasets.transform.reducer
  implement_name: dimension_reduction_by_pca
  params:
    n_components: 2

3. Device#

3.1 シミュレータの指定#

QXMTでは各プラットフォームから提供されているシミュレータをconfigから指定して利用することができます。 いくつかのチュートリアルでは、PennyLaneから提供されている最も基本的なシミュレータであるdefault.qubitを利用しています。 計算時間が実験のボトルネックとなっている場合には、C++ベースで実装されたlightning.qubitや高速なシミュレータの一つとして知られているqulacs.simulator等の利用を検討してみてください。

以下に、lightning.qubitを利用する場合のconfigの設定例を記載します。

device:
  platform: "pennylane"
  device_name: "lightning.qubit"
  n_qubits: 2
  shots: null
  device_options: null

これらの追加のシミュレータを利用する場合には、ご自身の環境にプラグインをインストールする必要がある場合もあります。 たとえば、lightning.qubitであればpip install pennylane-lightning等で追加を行えます。 その他、PennyLaneで利用可能なシミュレータは公式ドキュメントにまとめてあります。

※ QXMTでは利用頻度の高いdefault.qubit、lightning.qubit、qulacs.simulatorを対象に動作確認・テストを行っています。そのため、一部のシミュレータではQXMTの全ての機能が利用できない可能性があります。追加希望等がございましたら、QXMTのレポジトリ内からIssueを作成して提案していただけると助かります。

3.2 シミュレータの実行モードを指定#

シミュレーションの実行方法には、State Vector方式とSampling方式の2種類が存在します。 State Vector方式では、状態ベクトルに対してゲートを行列演算として適用していきます。演算の結果をそのまま利用するため結果が決定的となり再現性を担保しやすいため、動作確認に適しています。Sampling方式では演算の結果得られた確率振幅に従い、Samplingを行い最終的な測定値を求めます。そのため、ノイズ等は考慮されていませんが、実機に近い挙動でシミュレーションを実行することができます。

QXMTでは、deviceのconfigでshotsの値を設定するかどうかで、各種形式を指定することができます。 shotsは測定数を表し、数を増やすほどState Vector形式の値に収束していきます。

# State Vector形式
device:
  platform: "pennylane"
  device_name: "default.qubit"
  n_qubits: 2
  shots: null
  device_options: null

# Sampling形式
device:
  platform: "pennylane"
  device_name: "default.qubit"
  n_qubits: 2
  shots: 1024
  device_options:
    seed: *global_seed

3.3 量子コンピュータ実機の利用#

量子コンピュータの実機をAmazon BraketとIBM Quantum経由で利用することができます。実機およびリモートのシミュレータでは、利用量に応じて課金が必要となります。事前に各種プロバイダーの料金表を確認して下さい。

3.3.1 Amazon Braketの利用#

Amazon Braketでは、様々なプロバイダーから提供されている量子コンピュータの実機およびシミュレータが利用できます。どちらを利用する場合でも、configファイルの設定方法は共通となります。Amazon Braketを利用する際にはAWS経由でアクセスする必要があるためアカウント作成後、以下の3つの環境変数を事前に設定して下さい。

AWS_ACCESS_KEY_ID="xxx"
AWS_SECRET_ACCESS_KEY="xxx"
AWS_DEFAULT_REGION="xxx"

環境変数の設定が完了すると、configの設定のみでローカルのシミュレータで実行していた時と同様の手順で実行することが可能です。configには、device_nameを"braket.aws.qubit"に設定したのち、backend_nameに利用したいバックエンドを指定します。利用可能なバックエンドは、リージョンや時間帯によっても異なるためAmazon Braketの公式ドキュメントを参照して下さい。

device:
  platform: "pennylane"
  device_name: "braket.aws.qubit"
  backend_name: "iqm"
  n_qubits: 2
  shots: 1024

※ configの全体像はこちらのテンプレートを参照して下さい。

3.3.2 IBM Quantumの利用#

IBMQについても、アカウント作成後に発行したキーを環境変数"IBMQ_API_KEY"に設定することで同様に実行可能です。 configには、device_nameを"qiskit.remote"に設定したのち、backend_nameに利用したいバックエンドを指定します。backend_nameをnullに設定した場合には、待機しているジョブ数をもとに最も待ち時間が短いバックエンドが選択されます。

device:
  platform: "pennylane"
  device_name: "qiskit.remote"
  backend_name: null
  n_qubits: 2
  shots: 128

※ configの全体像はこちらのテンプレートを参照して下さい。

4. Feature Map#

4.1 Feature Mapの可視化#

作成した特徴マップの量子回路を可視化する方法を紹介します。 まず、可視化したい特徴マップのインスタンスにアクセスします。インスタンスへは大きく二つの方法でアクセスする方法があります。

一つ目の方法は、runの実行結果として返ってくるArtifact経由で特徴マップのインスタンスを取得する方法です。

artifact, result = experiment.run(config_source=adhoc_config)
feature_map = artifact.model.kernel.feature_map

もう一つの方法は、対象の特徴マップのインスタンスを直接作成する方法です。この方法では、カスタムの特徴マップを作る場合に回路図を見ながら試行錯誤したいという場合に便利です。

from qxmt.feature_maps.pennylane.rotation import RotationFeatureMap
feature_map = RotationFeatureMap(2, 2, ["X", "Y"])

特徴マップのインスタンスが取得できるとdrawメソッドでその量子回路を可視化できます。 現在PennyLaneで作成した量子回路の可視化フォーマットとして、defaultとmplの2種類が用意されています。 同一回路における、それぞれの可視化結果をここでは紹介します。

feature_map.draw(x_dim=2, format="default")

0: ─╭AngleEmbedding(M0)─╭AngleEmbedding(M0)─╭AngleEmbedding(M0)─╭AngleEmbedding(M0)─┤
1: ─╰AngleEmbedding(M0)─╰AngleEmbedding(M0)─╰AngleEmbedding(M0)─╰AngleEmbedding(M0)─┤
M0 =
[0.41553733 0.03790852]

feature_map.draw(x_dim=2, format="mpl")
特徴マップの可視化例

特徴マップの可視化時には、入力データのサンプル情報を伝える必要があるため引数xまたはx_dimのどちらかを設定する必要があります。

  • xは入力データの1つのサンプル値を設定します (例：x_train[0]など)

  • x_dimを利用する場合には、入力データの次元数を設定します。すると、次元数に応じたランダムなデータが生成され、その値を元に量子回路の可視化が行われます。

これらの値は、量子回路可視化時にサンプルデータとして用いられるだけで、モデル構築等の実験の結果には影響しません。

4.2 NPQCの利用#

ここでは、参考文献[1]で提案されたNPQCを利用する場合のconifg設定方法を紹介します。

NPQCは以下の量子回路で定義され、入力データをqubitに対して繰り返しエンコーディングしていくため、利用するqubit数以上の入力次元数を持つデータを扱うことができます。

NPQCの回路図

特徴マップの関する設定は、config内のfeature_mapという項目で一括管理されています。こちらで利用する特徴マップの種類やパラメータを指定することができます。NPQCFeatureMapを利用したい場合は以下のようにconfigを設定します。以下のconifgではデバイスの設定項目を省略していますが、NPQCでは量子回路のqubit数を偶数にする必要がある点に注意して下さい。

feature_map:
  module_name: "qxmt.feature_maps.pennylane"
  implement_name: "NPQCFeatureMap"
  params:
    c: 1.0
    reps: 2

  • module_name: 特徴マップが実装されているモジュール名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • implement_name: 特徴マップを実装したクラス名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • params.c: 特徴マップで利用されるスケールパラメータ

  • params.reps: 特徴マップの繰り返し数

4.3 YZCXの利用#

ここでは、参考文献[1]で提案されたYZCXを利用する場合のconifg設定方法を紹介します。

YZCXは以下の量子回路で定義され、NPQCと同様に利用するqubit数以上の入力次元数を持つデータを扱うことができます。

YZCXの回路図

YZCXFeatureMapを利用したい場合は以下のようにconfigを設定します。

feature_map:
  module_name: "qxmt.feature_maps.pennylane"
  implement_name: "YZCXFeatureMap"
  params:
    c: 1.0
    reps: 2
    seed: 42

  • module_name: 特徴マップが実装されているモジュール名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • implement_name: 特徴マップを実装したクラス名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • params.c: 特徴マップで利用されるスケールパラメータ

  • params.reps: 特徴マップの繰り返し数

  • params.seed: 回転角に適用する乱数のシード

5. Kernel#

5.1 Projected Kernelの利用#

QSVCに代表されるカーネル機械学習モデルでは、カーネルの計算アルゴリズムとして様々なものが存在します。ここでは参考文献[2]で提案されたProjected Kernelを利用する場合のconfigの設定方法を紹介します。

シンプルなProjected Kernelは以下の式で表され、スケールパラメータγと距離を計算するにあたり量子状態を古典状態に投影する方法を指定することができます。

Projected Kernelの定義式

引用元: “Power of data in quantum machine learning”[2]の式 (9)

カーネルの関する設定は、config内のkernelという項目で一括管理されています。こちらで利用するカーネルの種類やパラメータを指定することができます。Projected Kernelを利用したい場合は以下のようにconfigを設定します。

kernel:
  module_name: "qxmt.kernels.pennylane"
  implement_name: "ProjectedKernel"
  params:
    gamma: 1.0
    projection: "z"

  • module_name: カーネルメソッドが実装されているモジュール名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • implement_name: カーネルメソッドを実装したクラス名（今回はQXMTが提供しているものを利用するため上記のように記載）

  • params.gamma: カーネル計算時のスケールパラメータ

  • params.projection: 量子状態を古典状態へ投影する方法 (“x”, “y”, “z”が利用可能)

6. Model#

6.1 Cross Validationによるモデルの評価#

実装した量子機械学習モデルのパフォーマンスをCross Validationで評価したい場合には、次のように設定・実行を行います。 Cross Validationを実施するにあたりconfigファイルの追加設定は必要ありません。実行結果は、各分割の評価結果を格納したリストで返されます。

# experiment.runの結果として得られるartifactから、モデルとデータセットのインスタンスを取得
model = artifact.model
dataset = artifact.dataset

# 以下の例では元のDatasetでTrainとして用意されていたものを5分割して評価を実施
model.cross_val_score(X=dataset.X_train, y=dataset.y_train, cv=5)

>> [0.444643  0.535290 0.423356 0.551298 0.673212]

  • X: 分割元となるデータセットの説明変数

  • y: 分割元となるデータセットの目的変数

  • cv: データセットの分割数

QXMTのCross Validationでは、内部的にsckit-learnのcross_val_scoreを実行しています。そのため、sckit-learnのドキュメントに記載のその他のパラメータについても設定することが可能です。よく使うものとして評価指標はscoringパラメータで設定することができます。デフォルトでは、scikit-learnで定義されたモデルごとのデフォルト指標が利用されます (SVCの場合はaccuracy)。任意の指標を利用したい場合は、「String name scorers」を参照してください。

6.2 機械学習モデルのハイパーパラメータ探索#

機械学習のモデルのハイパーパラメータを探索する方法について紹介します。こちらもconfigの追加設定は必要ありません。実行結果は、探索の結果得られたパラーメータの値をdict形式で得ることができます。また、探索時にrefitパラメータをTrueに設定することで探索結果のパラメータでモデルを学習した結果を得ることもできます。

from sklearn.metrics import accuracy_score

# experiment.runの結果として得られるartifactから、モデルとデータセットのインスタンスを取得
model = artifact.model
dataset = artifact.dataset

# 探索範囲や条件の設定
search_space = {
    'C': [0.1, 1.0],
    'gamma': [0.01, 0.1]
}
search_args = {
    'cv': 5,
    "direction": "maximize",
    'n_jobs': -1,
    'verbose': 2,
    "n_trials": 5,
}

# パラメータ探索の実施
best_params = model.hyperparameter_search(
    X=dataset.X_train,
    y=dataset.y_train,
    sampler_type="tpe",
    search_space=search_space,
    search_args=search_args,
    objective=None,
    refit=True
    )

# 探索結果の評価
pred = model.predict(dataset.X_test)
answer = dataset.y_test
score = accuracy_score(pred, answer)
print(f"Best Prameter: {best_params}")
print(f"Accuracy: {score}")

  • X: データセットの説明変数

  • y: データセットの目的変数

  • sampler_type: 探索に利用するアルゴリズム

    • grid: Grid Sampler

    • random: Random Sampler

    • tpe: TPE Sampler by Optuna

  • search_space: パラメータとその探索範囲

  • search_args: 探索時の設定

  • objective: 探索時に利用する目的関数 (Noneの場合は、モデルに定義されているデフォルト指標を利用。詳細：String name scorers)

  • refit: 探索後、結果のパラメータでモデルの学習を行うかどうか (True/False)

6.3 Optimizerの設定#

VQEを利用する場合には最適化計算で利用するOptimizerをconfig経由で指定することができます。現在は、PennyLaneとSciPyから提供されているOptimizerをサポートしています。Optimizerの設定は、configのoptimizer_settings.nameにて指定することができます。nameの値がscipy.で始まる場合に、SciPyのOptimizerが利用され、それ以外の場合はPennyLaneのものが利用されます。

SciPyで利用可能なOptimizerはこちらのページを参考にしてください。リンク先のページでmethod=で指定されている名前の先頭にscipy.を加えて、以下のようにconfigのoptimizer_settings.nameに指定することで利用可能です。

model:
  name: "basic"
  diff_method: "adjoint"
  optimizer_settings:
    name: "scipy.BFGS"
    params: null
  params:
    max_steps: 500
    tol: 1e-6
    verbose: true

PennyLaneのOptimizerを利用する場合は、以下の表を参考に該当するものを探してください。

Optimizer

config設定名

AdagradOptimizer

AdagradOptimizer or Adagrad

AdamOptimizer

AdamOptimizer or Adam

AdaptiveOptimizer

AdaptiveOptimizer or Adaptive

GradientDescentOptimizer

GradientDescentOptimizer or GradientDescent

MomentumOptimizer

MomentumOptimizer or Momentum

MomentumQNGOptimizer

MomentumQNGOptimizer or MomentumQNG

NesterovMomentumOptimizer

NesterovMomentumOptimizer or NesterovMomentum

QNGOptimizer

QNGOptimizer or QNG

QNSPSAOptimizer

QNSPSAOptimizer or QNSPSA

RMSPropOptimizer

RMSPropOptimizer or RMSProp

RiemannianGradientOptimizer

RiemannianGradientOptimizer or RiemannianGradient

RotoselectOptimizer

RotoselectOptimizer or Rotoselect

RotosolveOptimizer

RotosolveOptimizer or Rotosolve

SPSAOptimizer

SPSAOptimizer or SPSA

ShotAdaptiveOptimizer

ShotAdaptiveOptimizer or ShotAdaptive

configファイルでは以下のように設定します。

model:
  name: "basic"
  diff_method: "adjoint"
  optimizer_settings:
    name: "Adam"
    params:
      stepsize: 0.01
      beta1: 0.9
      beta2: 0.999
  params:
    max_steps: 500
    tol: 1e-6
    verbose: true

Reference#

[1] Tobias Haug, Chris N. Self, M. S. Kim, “Quantum machine learning of large datasets using randomized measurements”, Arxiv (2021)

[2] Hsin-Yuan Huang, Michael Broughton, Masoud Mohseni, Ryan Babbush, Sergio Boixo, Hartmut Neven, and Jarrod R McClean, “Power of data in quantum machine learning”, Nature Communications 12, 1–9 (2021).

バージョン情報

環境

バージョン

ドキュメント

2026/06/12

QXMT

v0.7.0