プログラムでQamuyを使う¶

Qamuy Client SDKを使用することで、PythonプログラムからQamuyを利用することができます。以下のような用途で利用すると便利です。

入力データの多数のバリエーションを作成し、それらの計算をクラウド上で同時に実行する
計算で得られた結果データを、Pythonを用いて集計・解析する
Jupyter Notebookを用いて、対話的に計算・解析を行う

Qamuy Client SDK バージョン確認¶

qamuy.utilsパッケージ内のget_version()で、Qamuy Client SDKのバージョンが確認できます。

import qamuy.utils

qamuy.utils.get_version()

入力データの作成¶

Python SDKで入力データを作成する方法はいくつかあり、用途や好みに合わせて使い分けることが可能です。

入力データオブジェクトの各属性に値を代入していく¶

最初に「空」のオブジェクトを作成し、その属性に値を代入していくことで、逐次的に入力データを作成することができます。

import qamuy.chemistry as qy

input = qy.QamuyChemistryInput()
# 計算対象の分子を設定
molecule = input.target_molecule
molecule.geometry = qy.molecule_geometry(["H", "H"], [[0.0, 0.0, -0.35], [0.0, 0.0, 0.35]])
molecule.basis = "6-31g"
molecule.multiplicity = 1
molecule.num_excited_states = 1
molecule.cas = qy.cas(2, 2)
# 周期系を指定することもできます
ps = input.target_periodic_system
atoms = ["H", "H"]
coords = [
    [0.0, 0.0, 0.0],
    [1.42, 0.0, 0.0]
]
trans_vec = [[2.13, -1.23, 0.0], [2.13, 1.23, 0.0], [0.0, 0.0, 5.0]]
kpt_grid_shape = [2, 1, 1]
ps.geometry = qy.periodic_system_geometry(atoms, coords, trans_vec, kpt_grid_shape)
ps.basis = "sto3g"
ps.num_excited_states = 0
ps.cas = qy.cas_periodic_system(2, 2)
# アルゴリズムを設定
input.solver.type = "VQE"
# ...
# 計算する物理量を設定
properties = input.output_chemical_properties
properties.append(qy.output_chemical_property(target="dipole_moment", states=[0, 1]))
properties.append(
    qy.output_chemical_property(
        target="gradient", states=[0, 1], type="HAMILTONIAN_NUMERICAL", dx=0.1
    )
)

QamuyChemistryInputオブジェクトは、入力データ全体を表します。

多くの属性はPythonの単純な値を代入することで設定できますが、一部の属性の設定を簡単にするための関数が用意されています。

molecule_geometry()で分子構造の指定を作成することができます。
qamuy.chemistry.molecule_geometry(atoms, coordinates, geometry_format='CARTESIAN')¶
Create an object representing geometry of a molecule.
パラメータ:
atoms -- A list of nuclei that make up the molecule.

coordinates -- A list of coordinates of the nuclei specifying a molecular structure, or a list of such lists specifying multiple molecular structure.

geometry_format -- A notation in which the coordinates are described. Possible values are CARTESIAN (default) and Z_MATRIX.
戻り値:

A Molecule.Geometry object, which can be substituted in target_molecule.geometry attribute.
molecule_geometry_from_xyz()で「xyz 形式」（計算化学の分野でよく使われるフォーマット）の文字列から分子構造の指定を作成できます。

qamuy.chemistry.molecule_geometry_from_xyz(xyz)¶

Create an object representing geometry of a molecule from a string of xyz format. See https://en.wikipedia.org/wiki/XYZ_file_format

パラメータ:

xyz -- A string of xyz format.

戻り値:

A Molecule.Geometry object, which can be substituted in target_molecule.geometry attribute.
cas()でCAS (complete active space) の指定を作成することができます。
qamuy.chemistry.cas(active_ele=None, active_orb=None, cas_list=None)¶
Create an object representing a complete active space.
パラメータ:
active_ele (int) -- Number of electrons in the active space.

active_orb (int) -- Number of orbitals in the active space.

cas_list (list<int>) -- List of orbital indices in the active space.
戻り値:

A Cas object.

また周期系に対しては

periodic_system_geometry()で周期系の構造を指定することができます。
qamuy.chemistry.periodic_system_geometry(atoms, coordinates, trans_vector, kpt_grid_shape)¶
Create an object representing geometry of a periodic system.
パラメータ:
atoms -- A list of nuclei that make up a cell of a periodic system.

coordinates -- A list of coordinates of the nuclei specifying a priodic system, or a list of such lists specifying multiple structures.

trans_vector -- Translation vectors that characterize a periodic boundary condition.

kpt_grid_shape -- The numbers of k points for each axis of the reciprocal space.
戻り値:

A PeriodicSystem.Geometry object, which can be substituted in target_periodic_system.geometry attribute.
分子系と同様にcas_periodic_system()でCAS(complete active space)を指定できます.
qamuy.chemistry.cas_periodic_system(active_ele=None, active_orb=None)¶
Create an object representing a complete active space.
パラメータ:
active_ele (int) -- Number of electrons in the active space for a cell.

active_orb (int) -- Number of orbitals in the active space for a k-point.
戻り値:

A Cas object.
output_chemical_property()で評価する物理量の指定を作成することができます。
qamuy.chemistry.output_chemical_property(target, **kwargs)¶
Create an object representing parameters of a chemical property to be calculated. See a description of each target property in the reference page of input data for detail.
パラメータ:
target (str) -- An identifier of the target property. (e.g. "energy", "dipole_moment", etc.)

kwargs -- Keyword arguments necessary for each target property.
戻り値:

A TargetChemicalProperty object, which can be put into output_chemical_properties attribute.
spin_state()で参照状態のスピン状態の指定を作成することができます。
qamuy.chemistry.spin_state(state, multiplicity, sz)¶
Create an object representing a spin state for a reference state.
パラメータ:
state (int) -- The index of a reference state.

multiplicity (int) -- The multiplicity of a reference state.

sz (float) -- The value of z component of the total spin of a reference state.
戻り値:

A SpinState object.

一部の属性はリスト型になっているため、要素を追加する際に対応するオブジェクトを作成する必要があります。

output_chemical_properties: qamuy.chemistry.output_chemical_property()でオブジェクトを作成します。

input.output_chemical_properties.append(
  qy.output_chemical_property(
      target="gradient", states=[0, 1], type="HAMILTONIAN_NUMERICAL", dx=0.1
  )
)

post_hf_methods: qamuy.chemistry.PostHFMethodでオブジェクトを作成します。

input.post_hf_methods.append(
  qy.PostHFMethod(type="CASCI", excited_state_type="STATE_SPECIFIC")
)

spin_state_list: qamuy.chemistry.spin_state()でオブジェクトを作成します。
```
input.ansatz.spin_state_list.append(
    qy.spin_state(0, 1, 0.0)
)
```

属性に対してPythonオブジェクトを代入する場合、代入されるオブジェクトはコピーされることに注意してください。代入後に、代入されたオブジェクトの内部を変更しても、代入先には反映されません。以下の例では、input.target_moleculeのgeometryは設定されません。

molecule = qy.Molecule()
input.target_molecule = molecule # ← この時点でmoleculeはコピーされる
molecule.geometry = qy.molecule_geometry(["H", "H"], [[0.0, 0.0, -0.35], [0.0, 0.0, 0.35]])
print(input.target_molecule) # => geometryは設定されていない

入力データ全体を一度に作成する¶

入力データの各部分に対して、対応するPythonクラスが提供されています。これらのクラスのコンストラクターを使用して、入力データ全体を一度に作成することができます。

import qamuy.chemistry as qy

input = qy.QamuyChemistryInput(
    # 計算対象の分子
    target_molecule=qy.Molecule(
        geometry=qy.molecule_geometry(
            ["H", "H"], [[0.0, 0.0, -0.35], [0.0, 0.0, 0.35]]
        ),
        basis="6-31g",
        multiplicity=1,
        num_excited_states=1,
        cas=qy.cas(2, 2)
    ),
    # アルゴリズム
    solver=qy.Solver(type="VQE"),
    # ...
    # 計算する物理量
    output_chemical_properties=[
        qy.output_chemical_property(target="dipole_moment", states=[0, 1]),
        qy.output_chemical_property(
            target="gradient", states=[0, 2], type="HAMILTONIAN_NUMERICAL", dx=0.1
        )
    ]
)

Molecule, Solverなどが、各設定項目に対応するクラスです。これらのコンストラクターでは、名前付き引数で各属性の値を指定できます。

クラスのコンストラクターにdictを指定することも可能です。

input = qy.QamuyChemistryInput({
    # 計算対象の分子
    "target_molecule": qy.Molecule({
        "geometry": qy.molecule_geometry(
            ["H", "H"], [[0.0, 0.0, -0.35], [0.0, 0.0, 0.35]]
        ),
        "basis": "6-31g",
        "multiplicity": 1,
        "cas": qy.cas(2, 2)
    })
})

既にある入力データをコピーして変更する¶

先に作成した入力データをコピーして、一部を変更して利用することができます。一部の条件だけを変更した複数の入力データを作成するのに便利です。

from copy import deepcopy

# Hardware efficient ansatzの入力データを作成
input1 = qy.QamuyChemistryInput()
input1.ansatz.type = "HARDWARE_EFFICIENT"
# 作成した入力データをコピー
input2 = deepcopy(input1)
# コピーした入力データをUCCD ansatzを使うよう変更
input2.ansatz.type = "UCCD"

既にある入力データファイルをロードして変更する¶

先に作成した入力データファイルを読み込み、一部を変更して利用することができます。一部の条件だけを変更した複数の入力データを作成するのに便利です。ファイル形式は JSON 及 YAML に対応しています。

from qamuy.utils.file_io import load_input

# 以前作成した入力データファイルの読み込み
input = load_input("input_H2_JW_VQE_HWE_BFGS.yaml")

# ロードした入力データをUCCD ansatzを使うよう変更
input.ansatz.type = "UCCD"

既にある出力データファイルをロードして計算結果を用いる¶

先に計算を実行した際に得た結果の一部をコピーして、入力値として利用することができます。ファイル形式は JSON 及 YAML に対応しています。

from qamuy.utils.file_io import load_output

# 以前計算を実行した際に得た出力データファイルの読み込み
output = load_output("output_H2_JW_VQE_HWE_BFGS.yaml")
result = output.molecule_result
# 最適パラメターをコピー
opt_params = result.quantum_device_result.vqe_log.opt_params

入力データの保存¶

作成した入力データをファイル形式で保存することができます。ファイル形式は JSON 及 YAML に対応しています。

from qamuy.utils.file_io import save

input = qy.QamuyChemistryInput()
...
# 作成した入力データをファイルに保存
save(input, filename="my_input_file.yaml")

計算ジョブの実行¶

クラウド上で計算ジョブを実行するには、qamuy.client.Clientクラスを使用します。以下のように、Clientクラスのコンストラクターでインスタンスを作成し、そのメソッドを使用して計算の実行・結果の取得を行います。

from qamuy.client import Client

client = Client(email_address="EMAIL_ADDRESS", password="PASSWORD")
job = client.submit(input)
results = client.wait_and_get_job_results([job])

Client() のemail_address、passwordの引数にメールアドレスとパスワードを設定することで、プログラムコード内でログインが可能となります。qamuyコマンドによって、すでにログインしている場合は引数なしのClient()でログインできます。
前節で作成した入力データ（input）を引数としてsubmit()メソッドを実行すると、クラウド上で計算が開始されます。計算ジョブを表すJobオブジェクトが返されます。この時点では、計算処理は完了していません。入力データに問題がある場合（必要なパラメーターが指定されていないなど）、この時点で例外が発生することがあります。
wait_and_get_job_results()メソッドで、計算ジョブの完了を待ち、結果を取得します。複数の計算ジョブをリストとして渡すことで、一度に結果を取得することが可能です。ジョブが1つだけの場合も、サンプルコードのようにリストに入れて呼び出します。それぞれの入力データに対応する結果のResultオブジェクトをリストとして返します。

class qamuy.client.Client¶: API client for Qamuy.

Client.submit(input)¶

Submit a calculation job with the input data passed as an argument. May raise an exception if validation of the input or an API request fails. This method does not wait for completion of the submitted job.

パラメータ:: input -- An input data for calculation.
戻り値:: A Job object containing information of the submitted job.

Client.wait_and_get_job_results(jobs, print_progress=True)¶

Given multiple jobs, wait for completion of jobs and get results of them.

パラメータ:

jobs -- An iterable of Job objects.
print_progress (bool) -- Print progress to stderr.

戻り値:

A list of Result objects containing status, output data and error of each job.

ジョブの結果を表すResultオブジェクトは、以下の属性を持ちます。

status: ジョブのステータスを表します。qamuy.client.ResultStatus型（enum）を持ち、値はSUCCESSまたはFAILUREのいずれかです。
output: 計算の出力データのオブジェクトです。計算がエラー終了した場合、Noneになります。このオブジェクトから情報を取り出す方法については次節を参照ください。
error: 計算がエラー終了した場合のエラーの情報を含むdictです。計算が成功した場合、Noneになります。

result = results[0]
result.status # => <ResultStatus.SUCCESS: 0>
result.output # => {'input': { ... }, 'molecule_result': { ... }, ... }
result.error # => None

以下は、複数の入力データで同時に計算を実行して出力を取り出す例です。

# 複数の入力データを用意しておく
inputs = [input1, input2, ...]
# クライアントを作成
client = Client()
# 入力データから1つずつ計算を開始して、計算ジョブのリストにする
jobs = [client.submit(input) for input in inputs]
# 全ての計算ジョブが完了するのを待ち、結果を取得する
results = client.wait_and_get_job_results(jobs)
# エラー終了した計算があった場合、エラーを表示する
for i, result in enumerate(results):
    if result.status == qamuy.client.ResultStatus.FAILURE:
        print(f"Job {i} has failed: {result.error}")
# Resultデータから出力データを取り出す
outputs = [result.output for result in results]

計算ジョブ情報の保存¶

計算ジョブ開始時に得られるJobオブジェクトをファイルに保存することができます。プログラムを一度終了した後でも、ファイルから復元したJobオブジェクトを使って計算結果を取得できます。

ジョブの保存:

from qamuy.utils.file_io import save_job

job = client.submit(input)
# job.jsonファイルにJobオブジェクトを保存
save_job(job, filename="job.json")

ジョブの復元:

from qamuy.utils.file_io import load_job

# job.jsonファイルからJobオブジェクトを復元
job = load_job(filename="job.json")
# 復元したJobオブジェクトを使って計算結果を取得
results = client.wait_and_get_job_results([job])

計算ジョブの中止¶

Clientクラスのterminate_job()メソッドで、計算ジョブを中止することができます。

job = client.submit(input)
client.terminate_job(job)

Client.terminate_job(job)¶

Terminate a calculation job.

パラメータ:: job -- A job object to be terminated.
戻り値:: A job object for the specified job with its status updated.

出力データの保存¶

計算の出力データ（前節のResultクラスのoutput属性に入っている）をファイル形式で保存することができます。ファイル形式は JSON 及 YAML に対応しています。

from qamuy.utils.file_io import save

output = results[0].output
# 出力データをファイルに保存
save(output, filename="my_output_file.yaml")

以前に保存した出力データファイルを読み込む¶

先に計算を実行した際に得た結果を読み込み、結果の分析を行うことができます。ファイル形式は JSON 及 YAML に対応しています。

from qamuy.utils.file_io import load_output

# 以前計算を実行した際に得た出力データファイルの読み込み
output = load_output("output_H2_JW_VQE_HWE_BFGS.yaml")

出力データから情報を取り出す¶

計算の出力データには、出力データで記載しているのと同じ構造でデータが格納されており、普通のPythonクラスと同様に属性を使って情報を取り出すことができます。

output = result.output
# 1つ目の分子構造に対する結果を取り出す
m_result = output.molecule_result
# 量子計算の結果を取り出す
q_result = m_result.quantum_device_result
# VQEのログ情報を取り出す
vqe_log = q_result.vqe_log
# 最適化されたVQEのパラメーターを取り出す
list(vqe_log.opt_params) # => [0.0, ...]
# 量子計算の実行に必要な量子回路の情報を取り出す
vqe_log.quantum_resources.circuit # => {'num_qubit': 8, 'num_parameter': 32, 'num_gate': 39, 'num_1qubit_gate': 32, 'num_2qubit_gate': 7}
# 評価された物理量を格納しているオブジェクトを取り出す
evaluated_properties = q_result.evaluated_properties
# 構造最適化の結果を格納しているオブジェクトを取り出す
geo_result = output.geometry_optimization_result

多くの情報は単純に属性にアクセスすることで取得できますが、一部の情報を簡単に取り出すための関数が用意されています。

評価された物理量を取得する¶

get_evaluated_property()で、評価された物理量を取り出すことができます。複数のパラメーター（電子状態や状態ペアなど）について評価している場合、それらを全て含んだオブジェクトが返されます。

# 物理量の名前（出力データの説明ページ参照）を指定する
qy.get_evaluated_property(q_result, "energy")
# => {'values': [{'value': -1.1261231613839167, 'state': 0, 'sample_std': 0.0}, {'state': 1, 'value': -0.6254196782618017, 'sample_std': 0.0}], 'metadata': {'elapsed_time': 0.005356331821531057}}

qamuy.chemistry.get_evaluated_property(result, property_name)¶

Extract evaluated property values from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.

戻り値:

An object containing values for the specified property, typically contains a list of property values and metadata.

get_evaluated_properties()で、評価された物理量のリストを取り出すことができます。これは、gradient等の評価において、物理量を得るための手法を複数指定した場合に有用です。

# 物理量の名前（出力データの説明ページ参照）を指定する
qy.get_evaluated_properties(q_result, "gradient")
# => [{'values': [{'value': [0.0, 0.0, 0.036077760736360556, 0.0, 0.0, -0.03607776073639941], 'state': 0}, {'state': 1, 'value': [0.0, 0.0, 0.23747779376661535, 0.0, 0.0, -0.237477793766483]}], 'metadata': {'elapsed_time': 0.9695170419999997}, 'type': 'HAMILTONIAN_NUMERICAL'}, {'values': [{'value': [0.0, 0.0, 0.03607675773015902, 0.0, 0.0, -0.036076757730159156], 'state': 0}, {'state': 1, 'value': [0.0, 0.0, 0.23747658698911753, 0.0, 0.0, -0.23747658698911753]}], 'metadata': {'elapsed_time': 0.06478304199999929}, 'type': 'HAMILTONIAN_ANALYTICAL'}]

qamuy.chemistry.get_evaluated_properties(result, property_name)¶

Extract evaluated property values from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.

戻り値:

A list of objects containing values for the specified property, typically contains a list of property values and metadata.

電子状態を指定して評価される物理量（energy, dipole_momentなど）は、get_evaluated_property_for_state()で状態を指定して値を取得できます。電子状態ペアを指定して評価される物理量（trasition_dipole_momentなど）は、get_evaluated_property_for_state_pair()で状態ペアを指定して値を取得できます。

get_evaluated_properties()と同様に、物理量を複数の手法で評価した場合は、get_evaluated_properties_for_state()、またはget_evaluated_properties_for_state_pair()ですべての値を取得できます。

# 状態を指定して値を取得する
energy = qy.get_evaluated_property_for_state(q_result, "energy", state=1)
# => {'state': 1, 'value': -0.6254196782618017, 'sample_std': 0.0}
energy.value # => -0.6254196782618017
# 状態ペアを指定して値を取得する
tdm = qy.get_evaluated_property_for_state_pair(q_result, "transition_dipole_moment", state_pair=(0, 1))
# => {'state_pair': [0, 1], 'value': [{'real': 0.0, 'imag': 0.0}, {'real': 0.0, 'imag': 0.0}, {'real': -0.9847720194759502, 'imag': 0.0}]}
tdm.value[2] # => (-0.9847720194759502+0j)

qamuy.chemistry.get_evaluated_property_for_state(result, property_name, state=0)¶

Extract an evaluated property value for a state from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.
state (int) -- The index of a state for a property value to be extracted.

戻り値:

An object containing a value for the specified property for the specified state, typically contains the state index, the property value and its sample standard deviation.

qamuy.chemistry.get_evaluated_properties_for_state(result, property_name, state=0)¶

Extract evaluated property values for a state from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.
state (int) -- The index of a state for a property value to be extracted.

戻り値:

A list of objects containing a value for the specified property for the specified state, typically contains the state index, the property value and its sample standard deviation.

qamuy.chemistry.get_evaluated_property_for_state_pair(result, property_name, state_pair)¶

Extract an evaluated property value for a state pair from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.
state_pair (Iterable[int]) -- A pair of indices of the state pair for the property value to be extracted.

戻り値:

An object containing a value for the specified property for the specified state pair, typically contains the state pair, the property value and its sample standard deviation.

qamuy.chemistry.get_evaluated_properties_for_state_pair(result, property_name, state_pair)¶

Extract evaluated property values for a state pair from a quantum/post-HF result object.

パラメータ:

result -- A QuantumDeviceResult or PostHFResult object.
property_name (str) -- The name of a property to extract.
state_pair (Iterable[int]) -- A pair of indices of the state pair for the property value to be extracted.

戻り値:

A list of objects containing a value for the specified property for the specified state pair, typically contains the state pair, the property value and its sample standard deviation.

最適化の履歴を取得する¶

get_cost_history()で、VQEの最適化の過程におけるコスト関数の値の履歴を取得できます。VQDでは状態ごとに最適化履歴があるため、state引数で状態を指定して取得します。

# VQD以外の場合
qy.get_cost_history(vqe_log)
# => [-2.8676660336874353, -2.8730106287973363, -2.8774113831920385, -2.8776372678569313, -2.87766596449332, -2.877666000913216, -2.877666001029628]
# VQDの場合
qy.get_cost_history(vqe_log, state=0)
# => [-1.0905990711053306, -1.1224141482846215, -1.126120352809452, -1.126123161339495, -1.126123161383906]

qamuy.chemistry.get_cost_history(vqe_log, state=None)¶

Extract a history of the cost function in VQE as a list. For a non-VQD solver, state argument should not be passed since there is always only one cost history. For VQD, state argument should be passed to specify which cost history to extract.

パラメータ:

vqe_log -- A VQELog object.
state (Optional[int]) -- (Only for VQD) The state index for which a cost history is extracted.

戻り値:

A list containing a history of cost function value.

get_energy_history_for_state()で、VQEの最適化の過程におけるエネルギーの値の履歴を取得できます。エネルギーは状態ごとに計算されるため、state引数で状態を指定して取得します。

# state引数を指定しない場合、state=0の履歴を取得する
qy.get_energy_history_for_state(vqe_log)
# => [-1.0905990711053308, -1.122414148284593, -1.126120352859052, -1.1261231613400429, -1.1261231613839124]
# state引数を指定
qy.get_energy_history_for_state(vqe_log, state=1)
# => [-0.7980960020626229, -0.8373225307277186, -0.868697141428127, -0.877005924728595, -0.877050254353493, -0.8770502823998373, -0.8770502826217522]

qamuy.chemistry.get_energy_history_for_state(vqe_log, state=0)¶

Extract a history of energy of a state in VQE as a list.

パラメータ:

vqe_log -- A VQELog object.
state (int) -- The index of a state for which the energy history it extracted.

戻り値:

A list containing a history of energy value for the specified state.

構造最適化後の構造を取得する¶

get_optimized_geometry()で、構造最適化により得られた構造をMolecule.Geometryオブジェクト（molecule_geometry()で作成した分子構造と同様の形式）として取得する事ができます。

opt_geo = qy.get_optimized_geometry(geo_result)
print(opt_geo)
# => {'atoms': ['H', 'H'], 'coordinates': [[0.0, 0.0, 0.0], [0.0, 0.0, 0.7414]], 'geometry_format': 'CARTESIAN'}

qamuy.chemistry.get_optimized_geometry(geo_result)¶

Extract an object representing optimized geometry of molecule.

パラメータ:: geo_result -- A GeometryOptimizationResult object.
戻り値:: A Molecule.Geometry object.

更に、geometry_to_xyz()により、Molecule.Geometryオブジェクトで表された分子構造を、計算化学の分野でよく使われるフォーマットである「xyz形式」の文字列として出力できます。外部ライブラリを用いた分子構造の可視化などに便利です。

geo_xyz = qy.geometry_to_xyz(opt_geo)
print(geo_xyz)
# =>
# 2
#
# H           0.00000        0.00000        0.00000
# H           0.00000        0.00000        0.74140

qamuy.chemistry.geometry_to_xyz(geometry, vib_mode=None)¶

Convert molecular geometry to a string of xyz format.

パラメータ:

geometry -- A Molecule.Geometry object.
vib_mode (optional) -- A list of displacements of each nucleus specifying a vibration mode, whose length is 3 * n_atoms, e.g., [0., 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8] for water molecule

戻り値:

A string of xyz format.

出力データの情報を可視化する¶

計算の出力データに含まれる情報を、わかりやすく可視化することが可能です。以下の種類の可視化がサポートされています。

VQEの最適化過程におけるコスト関数・エネルギーの値の履歴プロット

なお、可視化にはMatplotlibを利用しており、各々の可視化関数はMatplotlibのFigure, Axesの組を返します。したがって、Matplotlibの機能を使ってプロットをカスタマイズしたり、ファイルに書き出したりすることが可能です。詳しくはMatplotlibのドキュメントをご参照ください。

VQE最適化のコスト・エネルギー履歴プロット¶

例: 1回の計算結果を使ってプロットする¶

Qamuyで行った計算の出力データをもとにコストまたはエネルギー履歴をプロットするには、以下のようにします。

import qamuy.plot

# 計算の実行・出力データの取り出し
results = client.wait_and_get_job_results([job])
output = results[0].output

# コスト関数履歴のプロット
fig, ax = qamuy.plot.plot_cost_history(output)
# Matplotlibの機能で画像ファイルに保存
fig.savefig("cost_history.png", bbox_inches="tight")

# エネルギー履歴のプロット
fig, ax = qamuy.plot.plot_energy_history(output, state_label_map={0: "S0", 1: "T1"})
# Matplotlibの機能で画像ファイルに保存
fig.savefig("energy_history.png", bbox_inches="tight")

例: 複数の計算結果をまとめてプロットする¶

複数の計算出力データをもとにコストまたはエネルギー履歴をプロットするには、以下のようにqamuy.plot.HistoryPlotOptionsオブジェクトのリストを作成する必要があります。

import qamuy.plot

# 計算の実行・出力データの取り出し
results = client.wait_and_get_job_results([job])
outputs = [result.output for result in results]

# プロットの入力データ定義
plot_options = [
  qamuy.plot.HistoryPlotOptions(output)
  for output in outputs
]

# コスト関数履歴のプロット
fig, ax = qamuy.plot.plot_cost_history(plot_options, history_label_template="$ansatz")
# Matplotlibの機能で画像ファイルに保存
fig.savefig("cost_history_multiple.png", bbox_inches="tight")

# エネルギー履歴のプロット
fig, ax = qamuy.plot.plot_energy_history(
  plot_options, state_label_map={0: "S0", 1: "T1"}, history_label_template="$ansatz $state"
)
# Matplotlibの機能で画像ファイルに保存
fig.savefig("energy_history_multiple.png", bbox_inches="tight")

コスト・エネルギー履歴プロットのオプション¶

1回の計算結果をプロットする場合は、その出力データをプロット関数に直接渡すことができます。複数の計算結果をまとめてプロットする場合は、HistoryPlotOptionsオブジェクトのリストを作成してプロット関数に渡す必要があります。

class qamuy.plot.HistoryPlotOptions¶

An object containing options for cost function/energy history plot.

パラメータ:

output (QamuyChemistryOutput) -- Output data of a calculation by Qamuy
states (List[int], optional) -- Specifies states to be included in the plot. All states are included if omitted.
history_label_template (str, optional) --
A string template used to format labels for history entries. You can specify the following variables using $ notation of Python template strings.
- $state: Label for the state
- $solver: Eigensolver
- $ansatz: Ansatz
- $depth: Depth of ansatz
- $optimizer: Optimizer
- $mapping: Fermion-qubit mapping
ref_label_template (str, optional) --
A string template used to format labels for a reference post-HF method. You can specify the following variables using $ notation of Python template strings.
- $state: Label for the state
- $method: Post-HF method

例¶

options = qamuy.plot.HistoryPlotOptions(
  output,
  states=[0, 1],
  history_label_template="$solver: $state",
  ref_label_template="$method: $state",
)

コスト関数履歴のプロット¶

コスト関数履歴はplot_cost_history関数でプロットできます。

qamuy.plot.plot_cost_history(plot_input, *, states=None, history_label_template=None, state_label_map=None, **fig_kwargs)¶

Plot histories of cost function values evaluated during an optimization process of VQE.

パラメータ:

plot_input (QamuyChemistryOutput, HistoryPlotOptions or List[HistoryPlotOptions]) -- Input data for the plot
states (List[int], optional) -- Specifies states to be included in the plot. All states are included if omitted.
history_label_template (str, optional) --
A string template used to format labels for history entries. You can specify the following variables using $ notation of Python template strings.
- $state: Label for the state
- $solver: Eigensolver
- $ansatz: Ansatz
- $depth: Depth of ansatz
- $optimizer: Optimizer
- $mapping: Fermion-qubit mapping
state_label_map (Dict[int, str], optional) -- A dict mapping each state index (int) to a label displayed in plot legend. Zero-based state index is used if omitted.

戻り値:

A tuple of Matplotlib's Figure and Axes.

例¶

fig, ax = qamuy.plot.plot_cost_history(
  output,
  states=[0, 1],
  history_label_template="$solver: $state",
  state_label_map={0: "S0", 1: "T1"}
)

エネルギー履歴のプロット¶

エネルギー履歴はplot_energy_history関数でプロットできます。

qamuy.plot.plot_energy_history(plot_input, *, states=None, reference_method='AUTO', history_label_template=None, ref_label_template=None, state_label_map=None, **fig_kwargs)¶

Plot histories of energy evaluated during an optimization process of VQE.

パラメータ:

plot_input (QamuyChemistryOutput, HistoryPlotOptions or List[HistoryPlotOptions]) -- Input data for the plot
states (List[int], optional) -- Specifies states to be included in the plot. All states are included if omitted.
reference_method (str or PostHFMethod.Type, optional) -- Specifies a post-HF method for which energy value is plotted as a reference value. AUTO is used if omitted, which uses the first available post-HF energy is used. Specify None to suppress plotting reference values.
history_label_template (str, optional) --
A string template used to format labels for history entries. You can specify the following variables using $ notation of Python template strings.
- $state: Label for the state
- $solver: Eigensolver
- $ansatz: Ansatz
- $depth: Depth of ansatz
- $optimizer: Optimizer
- $mapping: Fermion-qubit mapping
state_label_map (Dict[int, str], optional) -- A dict mapping each state index (int) to a label displayed in plot legend. Zero-based state index is used if omitted.

戻り値:

A tuple of Matplotlib's Figure and Axes.

例¶

fig, ax = qamuy.plot.plot_energy_history(
  output,
  states=[0, 1],
  reference_method="CASCI",
  history_label_template="$solver: $state",
  state_label_map={0: "S0", 1: "T1"}
)

履歴プロットの高度なカスタマイズ¶

最適化履歴プロットをさらにカスタマイズしたい場合、以下のクラスを拡張して使用することができます。

HistoryPlotterは、各種履歴プロットを行うための抽象基底クラスです。 HistoryPlotterを継承する具象クラスは、plot_dataメソッドを実装する必要があります。プロットを行うにはplotメソッドを使用します。

class qamuy.plot.HistoryPlotter¶

An abstract base class for history plot.

title¶

Plot title

Type:: str

x_label¶

Label of X axis

Type:: str

y_label¶

Label of Y axis

Type:: str

history_label_template¶

A string template used to format labels for history entries. You can specify the following variables using $ notation of Python template strings.

$state: Label for the state
$solver: Eigensolver
$ansatz: Ansatz
$depth: Depth of ansatz
$optimizer: Optimizer
$mapping: Fermion-qubit mapping

Type:: str

ref_label_template¶

A string template used to format labels for a reference post-HF method. You can specify the following variables using $ notation of Python template strings.

$state: Label for the state
$method: Post-HF method

Type:: str

state_label_map¶

A dict mapping each state index (int) to a label displayed in plot legend. Zero-based state index is used if omitted.

Type:: Dict[int, str]

legend_kwargs¶

Keyword arguments passed to Axes.legend method of Matplotlib.

Type:: dict

setup_caption_kwargs¶

Keyword arguments passed to Axes.text method of Matplotlib when drawing a caption describing the caluclation setup.

Type:: dict

abstract HistoryPlotter.plot_data(fig, ax, mol_result_and_states)¶: An abstract method to plot data. Subclasses should define this method.

HistoryPlotter.plot(plot_input, states=None, **fig_kwargs)¶

Plot a history plot with given input data.

パラメータ:

plot_input (QamuyChemistryOutput, HistoryPlotOptions or List[HistoryPlotOptions]) -- Input data for the plot
states (List[int], optional) -- Specifies states to be included in the plot. All states are included if omitted.
**fig_kwargs -- Keyword arguments passed to Matplotlib's pyplot.figure function when creating a Figure object.

CostHistoryPlotterおよびEnergyHistoryPlotterは、コストおよびエネルギー履歴をプロットするためのクラスで、HistoryPlotterを継承した具象クラスです。

class qamuy.plot.CostHistoryPlotter¶: A concrete class for cost history plot.

class qamuy.plot.EnergyHistoryPlotter(reference_method='AUTO')¶: A concrete class for energy history plot.