はじめに

初めてPFP をお使いになる方はまずは以下のマニュアル、事例をお試しください。

Documents > Matlantis Guidebook
Documents > About PFP
Example launcher より
- Matlantis Examples> Basics > Welcome
- Matlantis Examples > Basics > How to use PFP

さらに、補足的な情報として、以下もご参照ください。

Documents > About DFT-D3
Documents > PFP API Client Reference
Matlantis Examples > Basic > About DFT-D3

Gaussian や VASP向けのinput作成は以下をご参照ください。

Matlantis Examples > Miscellaneous > DFT calculation : Gaussian 16 input file
Matlantis Examples > Miscellaneous > DFT calculation : VASP5 input

目次に戻る⏎

Documents へのアクセス方法：

ドキュメントへアクセスするには3つの方法があります。

Notebook 環境からアクセスする方法：

①Basic Launcher から
②Helpメニューから

Dashboard 画面からアクセスする方法：

③ Documents

目次に戻る⏎

Example launcher のサンプルファイルの開き方：

ここでは Welcome を開く方法を紹介します。

Example launcher を開きます。
Matlantis Examples > Basics > Welcome を探します。
ファイル名右にあるアイコンから適したものを選択して、自分のワークスペース上にコピーします。内容をプレビューすることもできます。
- ① 現在 File Browser にて開いている場所へコピーします。
- ② 指定したワークスペース上へコピーします。クリックすると任意のディレクトリが選択できます。
- ③ ファイルをプレビューします。

目次に戻る⏎

PFP について

Maltantis で提供する汎用ニューラルネットワーク PFP (Preferred Potential)を利用するためには、まず pfp-api-client という ASE を含む、PFP を利用するためのパッケージをインストールをします。

Matlantis Examples > Basics > Welcome より抜粋

目次に戻る⏎

パッケージのインストール方法

Package launcher からインストールする方法：

以下のパッケージはPckage launcher から次のようにインストールできます。

pfp-api-client
matlantis-features
matlantis-group-drive-client

Package launcher を開きます。
最新版の install ボタンをクリックします。
python のバージョンを選んでインストールします。

インストールが成功すると次のような表示になります。

※ pfcc-extras のインストール方法についてはこちらをご覧ください。

※ matlantis-lammps についてはこちらをご覧ください。

pip を用いた方法：

pip を用いてもインストールできます。Package laucher からインストールできないパッケージなどは pip をお使いください。（参考：よく使うPython パッケージ）

Notebook 上で pip を実行する場合：
先頭に「!」をつけてコマンドを実行してください。
```
!pip install -U pfp-api-client
```

ターミナルから pip を実行する場合：
Matlantis 環境でターミナルを開く場合、次のように File > New > Terminal からターミナルを開きます。ターミナルを開いたら、Python 環境をアクティベートすると pip が実行できます。（Python 環境のアクティベート方法はこちらをご覧ください）

目次に戻る⏎

パッケージの全体構成

pfp-api-client：
機械学習ポテンシャル PFP を用いたエネルギー・力を推論します
matlantis-features：
内部で PFPを利用してさまざまな物性値を計算する Features や PFP の呼び出しはせず、結果を分析するための post-calculation features のような関数などを含みます。
- DipoleFeatures
- ElasticTesorFeature
- VibrationFeature
- ForceConstantFeature
- ReactionStringFeature
- PostVibrationGasThermoFeature
- PostMDDiffusionFeature
- PostEMDViscosityFeature
- PostNEMDViscosityFeature
- PostPhononBandFeature
- PostPhononDOSFeature
- PostNEMDThermalConductivityFeature
- etc…

Matlantis Guidebook > はじめに > Matlantis パッケージの全体構成より抜粋

目次に戻る⏎

ASE との関係

Atomistic Simulation Environment （ASE）は分子シミュレーションにおいて広く使われている Python パッケージです。（参考：ASE の基本的な Modules）
ASE と pfp-api-client, matlantis-features を連携することで PFPを用いた構造最適化や分子動力学法（Molecular Dynamics, MD）を簡単に実行できます。
- 弊社が提供するExample は多くのものが ASE と連携させた事例です。
ASE では計算対象の系をAtoms クラスで定義し、任意の Calculator をセットすることで様々な手法を呼び出してエネルギーや力の計算が実行できます。
- pfp-api-client の Estimator クラスからインスタンスを作成して Calculator にセットすると簡単にPFP計算が可能です。Estimator の設定についてはこちらをご覧ください。
- atoms.calc に Calculator をセットして計算できるものの例：
  - ポテンシャルエネルギー　atoms.get_potential_energy()
  - 力　atoms.get_forces()
  - 電荷　atoms.get_charges()

目次に戻る⏎

計算モードとモデルバージョン

PFPには7つの計算モードがあります。

従来の（旧）計算モードの名称との対応は以下の通りです。

現在の名称	従来の名称	学習データの計算手法
PBE	CRYSTAL_U0	PBE/PAW only
PBE_PLUS_D3	CRYSTAL_U0_PLUS_D3	PBE/PAW + Grimme-D3※
PBE_U	CRYSTAL	PBE/PAW with Hubbard 補正
PBE_U_PLUS_D3	CRYSTAL_PLUS_D3	PBE/PAW with Hubbard 補正 + Grimme-D3※
WB97XD	MOLECULE	ωB97xd/6-31G(d)

※ D3補正は学習データの計算手法に適用されているわけではありません（推論値に加算される形で考慮されます）

デフォルトの計算モードや使用可能な計算モードはバージョンによって異なります（v3.0.0 までは PBE_U が、v4.0.0以降 PBE がデフォルトです）。計算モードとバージョンはどちらも指定して利用することを推奨します（計算モードとバージョンを同時に指定する方法はこちらをご覧ください）。

Matlantis Guidebook > PFP Versions > 計算モードと各PFPバージョンの対応状況 > 計算モードの一覧, 各PFPバージョンで利用可能な計算モードの一覧とデフォルト計算モードより抜粋

目次に戻る⏎

計算モードの指定

計算モード（calc_mode) は次のようにして指定します。

Matlantis Examples > Basics > How to use PFP より抜粋

目次に戻る⏎

モデルバージョンの指定

モデルバージョンは次のように指定します。

Matlantis Examples > Basics > How to use PFP より抜粋

目次に戻る⏎

計算モードとモデルバージョンを同時に指定（推奨）

モデルバージョンと計算モードは明示的に指定してのご利用を推奨します。

以下のように、モデルバージョンと計算モードをテキストでも指定できます。
例）

from pfp_api_client import Estimator, ASECalculator
model_version = "v5.0.0"
calc_mode = "CRYSTAL_U0_PLUS_D3"
estimator = Estimator(model_version=model_version, calc_mode=calc_mode)
calculator = ASECalculator(estimator)

Estimator の指定方法は pfp-api-client と matlantis-features で異なります。こちらもご覧ください

目次に戻る⏎

Hubbard 補正と D3 分散補正

Hubbard 補正

U-J 値については以下をご確認ください。

About PFP > 学習データセット > 計算条件 > 結晶系（Hubbard 補正あり）> GGA+U

目次に戻る⏎

DFT-D3 補正

D3補正は学習データの計算手法に適用されているわけではなく、推論値に加算する形で考慮されます。

オリジナルの DFT-D3 とのちがいとして、カットオフ距離を40 Bohr に変更しています。

torch-dftd の解説記事と実装についてもご参照ください。

About DFT-D3 > PFPにおけるD3補正より抜粋

目次に戻る⏎

単位と周期境界条件

About PFP > アーキテクチャ解説 > 単位系, 周期境界より抜粋

目次に戻る⏎

対応元素

周期表の色のついた元素（96元素）に対応しています。

About PFP > 学習データセット> 計算条件 > 元素の対応状況および擬ポテンシャルより抜粋

目次に戻る⏎

Experimental / Unexperimental な元素

現在は Unexperimental な元素はありません（PFP v7 以降）

About PFP > 学習データセット> 計算条件 > 元素の対応状況(2024.09) より抜粋

目次に戻る⏎

サポートされている計算対象

About PFP > 学習データセット> 計算モードより抜粋

目次に戻る⏎

Notebook でできること

JupyterLab の一般的な操作方法については、こちらをご確認ください。

よく使うショートカットはこちらにまとめました。

カーネルの切り替え

カーネルの Python は次のようにノートブックの右上「Python 3.x」の表示をクリックすると切り替えられます。
ターミナルでは次のように use_venv コマンドを使って切り替えます。

Matlantis Guidebook > Notebook でできること > カーネルの Python を切り替えるより抜粋

目次に戻る⏎

Background Job

Background Job 機能を使うことで現在の notebookファイル（*.ipynb）のコピーが作成され、
コピーされたノートブックがバックグラウンドジョブで実行されます。
最大並列実行可能数（デフォルト3）を超えるとジョブはキューに追加されます
バックグラウンドで実行した計算が終了するとメールで通知を受け取ることができます（通知先のメールアドレスはMatlantis Setting から設定できます）。
新しいジョブを実行できない、実行履歴にアクセスできない、などバックグラウンドジョブの不具合が起きた場合、バックグラウンドジョブの状態リセットをお試しいただくと解決できる場合があります。この操作は、バックグラウンドジョブの実行履歴や計算途中の一時ファイルを削除します（計算済みのデータは削除されません）。バックグラウンドジョブの状態リセットの方法は Dashboard - Advanced をご覧ください。問題が解決しない場合は弊社までお問い合わせください。

Matlantis Guidebook > Notebook でできること > Background Job の使い方より抜粋

目次に戻る⏎

優先度機能

Token Availability が100を下回るとき、どの計算を優先するかを設定できます。

優先度 100 のとき：Token Availability と関係なく計算を試みます（最優先）
優先度 25 のとき： Token Availability が 75% 以上になるまで計算は保留されます
※ なにも設定しない場合、デフォルト値 100となります。
※ Token Availability については PFP Load Status をご確認ください。

設定方法：

Estimator クラスのコストラクタでの設定
Config.priority という変数を用いた設定
PFP_DEFAULT_PRIORITY という環境変数の設定
Backgroud job 実行時に設定

Matlantis Guidebook > pfp-api-client とは > トークン制および優先度機能について > 優先度機能より抜粋

目次に戻る⏎

pfp-api-client のロギングについて

計算に用いた PFP の計算モードやバージョンの記録にご利用いただけます。

Matlantis Guidebook > pfp-api-client とは > pfp-api-client のロギングについてより抜粋

目次に戻る⏎

参考情報

Estimator の設定方法

ASE の Estimator の設定方法は pfp-api-client と matlantis-features で異なります。

pfp-api-client の場合

from pfp_api_client.pfp.calculators.ase_calculator import ASECalculator
from pfp_api_client.pfp.estimator import Estimator

estimator = Estimator(model_version=”v5.0.0”, calc_mode=EstimatorCalcMode.CRYSTAL_U0)
calculator = ASECalculator(estimator)
atoms.calc = calculator

matlantis-featuresの場合
環境変数を用いる方法と estimator_fn を用いる方法があります。両方指定した場合は estimator_fn の設定が優先されます。

環境変数を用いた方法：

from ase.build import molecule
import os
from pfp_api_client.pfp.estimator import Estimator
from pfp_api_client.utils.messages import MessageEnum
from matlantis_features.features.common.opt import FireASEOptFeature

os.environ["MATLANTIS_PFP_MODEL_VERSION"] = "v4.0.0"
os.environ["MATLANTIS_PFP_CALC_MODE"] = "crystal_plus_d3"

atoms = molecule("CH3OH")
opt = FireASEOptFeature()
result = opt(atoms)

estimator_fn を用いる方法（1）

from ase.build import molecule
from pfp_api_client.pfp.estimator import EstimatorCalcMode
from matlantis_features.features.common.opt import FireASEOptFeature
from matlantis_features.utils.calculators import pfp_estimator_fn


atoms = molecule("CH3OH")

opt = FireASEOptFeature(
estimator_fn=pfp_estimator_fn(
model_version="v2.0.0",
calc_mode=EstimatorCalcMode.CRYSTAL_PLUS_D3,
),
)
result = opt(atoms)

独自にestimator_fn を定義する方法：

from ase.build import molecule
from pfp_api_client.pfp.estimator import Estimator, EstimatorCalcMode
from pfp_api_client.utils.messages import MessageEnum

from matlantis_features.features.common.opt import FireASEOptFeature


def estimator_fn() -> Estimator:
# change the model version.
estimator = Estimator(
model_version="v2.0.0",
calc_mode=EstimatorCalcMode.CRYSTAL_PLUS_D3,
)

# disable the specific type of warning.
estimator.set_message_status(
message=MessageEnum.ExperimentalElementWarning,
message_enable=False,
)

return estimator

atoms = molecule("CH3OH")
opt = FireASEOptFeature(estimator_fn=estimator_fn)
result = opt(atoms)

Matlantis Guidebook > matlantis-features とは > matlantis-features で使われるestimator の設定方法より抜粋

目次に戻る⏎

ASE の基本的な Modules

File input and output
https://wiki.fysik.dtu.dk/ase/ase/io/io.html#module-ase.io
Atoms object
https://wiki.fysik.dtu.dk/ase/ase/atoms.html#the-atoms-object
Building things
https://wiki.fysik.dtu.dk/ase/ase/build/build.html#building-things
molecule, bulk, surface
- stack
- translate, rotate
- add_adsorbate
Constraints
https://wiki.fysik.dtu.dk/ase/ase/constraints.html#constraints
- FixAtoms
- ExpCellFilter, UnitCellFilter, StrainFilter

ASEについてはこちら

目次に戻る⏎

よく使うPython パッケージ

Matlantis 提供（Package launcher）
- pfp-api-client
- matlantis-features
- pfcc-extras
- matlantis-group-drive-client
計算化学関連
- ase
- pymatgen
- Sella
- plumed
データ解析・数値計算・統計処理
- pandas
- numpy
- scipy
グラフ化
- matplotlib
- plotly
- kaleido
- seaborn
機械学習
- scikit-learn
- torch
並列処理
- joblib
パラメタ最適化
- optuna

インストール方法はこちら

目次に戻る⏎

PFVM について

PFVM は Preferred Networks が開発した高性能・マルチプラットフォーム対応の深層アクセラレータライブラリです。
- この技術により計算可能原子が増加しました。（計算可能原子数はこちらでご確認ください）

Matlantis Guidebook > PFVM についてより抜粋

目次に戻る⏎

目次

はじめに

Documents へのアクセス方法：

Example launcher のサンプルファイル の開き方：

PFP について

パッケージのインストール方法

Package launcher からインストールする方法：

pip を用いた方法：

パッケージの全体構成

ASE との関係

計算モードとモデルバージョン

計算モードの指定

モデルバージョンの指定

計算モードとモデルバージョンを同時に指定（推奨）

Hubbard 補正と D3 分散補正

Hubbard 補正

DFT-D3 補正

単位と周期境界条件

対応元素

Experimental / Unexperimental な元素

サポートされている計算対象

Notebook でできること

カーネルの切り替え

Background Job

優先度機能

pfp-api-client のロギングについて

参考情報

Estimator の設定方法

ASE の 基本的な Modules

よく使うPython パッケージ

PFVM について

関連記事

Example launcher のサンプルファイルの開き方：

ASE の基本的な Modules