aenet_env

ænetによるANN原子間ポテンシャルの学習・利用に必要なPythonモジュール群、 実行スクリプト、参照データ準備、外部ツール連携、 インストールおよび実行環境の構築を支援するライブラリ。

設計上の位置付け

研究ワークフローの一例は RMC → 小規模周期DFT候補 → VASP参照計算 → MLP学習 → RMC_POT 。RMCが散乱データに基づく構造探索を担い、MLPはDFTに基づくエネルギー評価を担う。大きなRMCセルをそのままDFTで計算することは前提としない。一方、小規模周期セルへの変換は局所環境・組成・周期境界・配位の整合性を自動的に保証しない。候補構造の評価では、局所環境の再現性、周期境界の影響、DFT計算への適合性を確認する。

src/aenet_env/ は学習・参照データ準備・構造処理・外部ツール呼び出し・環境構築を再利用するためのAPI群、scripts/ は具体的なワークフローや実行設定の雛形を置く。利用者は目的に応じて必要なモジュール・段階だけを使用できる。スクリプトは先頭の定数を編集し、 main() から実行する。

現行ディレクトリ構成（v0.0.3）

aenet_env/
├── pyproject.toml
├── README.md / README.ja.md
├── CHANGELOG.md / CHANGELOG.ja.md
├── src/aenet_env/
│   ├── aenet_backend.py        # ænet入力生成と公式実行ファイル
│   ├── training.py             # 4種類の学習呼び出し
│   ├── structure_sampling.py   # 周期構造の検査・共通サンプリング
│   ├── structures.py           # 構造・ケース探索
│   ├── xyz.py                  # XYZとPOSCAR
│   ├── vasp_inputs.py          # VASP入力準備
│   ├── references.py           # vasprun.xml → XSF
│   └── install_scripts.py      # 雛形インストーラー
├── scripts/
│   ├── a00_make_structures.py
│   ├── a01_make_structures.py
│   ├── a03_bin_geometric_sampling.py
│   ├── a03_lib_geometric_sampling.py
│   ├── b00_make_poscar.py
│   ├── b01_stage_structures.py
│   ├── b02_prepare_vasp.py
│   ├── b03_submit_vasp_jobs.py
│   ├── c00_collect_references.py
│   ├── c01_train_ann.py
│   ├── job_hpcs2024_node1.sh
│   └── job_hpcs2024_node2.sh
├── docs/
└── cal/SiO2/POSCAR

build/ と src/aenet_env.egg-info/ はビルド生成物であり、ライブラリのソースではない。scripts/axx/ の設計メモは現在の配布設定ではインストール対象外。

構造生成と参照データの準備

RMC由来の構造から、小規模周期セルとしてDFT計算可能な候補を作成する。候補生成では、対象局所環境、セル寸法、変異条件に応じて方式を選択する。周期境界、組成、原子間距離、配位状態を検査する必要があり、DFT参照データの採用に際しては、構造検査と第一原理計算の収束を確認する。

VASP参照データと学習の手順

段階	実行スクリプト	主な処理
候補	a00 / a01 / a03_bin	周期DFT候補を生成（方式は選択）
b00	b00_make_poscar.py	XYZから元素ごとにまとめたPOSCARを生成
b01	b01_stage_structures.py	構造ケースの配置・確認
b02	b02_prepare_vasp.py	INCAR、KPOINTS、POTCAR等の準備
b03	b03_submit_vasp_jobs.py	HPCでVASPジョブを投入
c00	c00_collect_references.py	VASP結果からエネルギー・力を含むXSF参照構造を収集
c01	c01_train_ann.py	ænetのANNポテンシャルを学習

VASP結果は vasprun.xml 等を原本とし、references/*.xsf を学習入力とする。単にXYZ候補を生成した段階ではエネルギー・力の教師ラベルはない。VASPの正常終了・収束と力の有無を確認してから参照データとして採用する。

学習方式と設定

c01_train_ann.py の main() で 次のうち1方式だけを有効化する。

1. fortran_legacy(refs)：generate.x と train.x を直接呼び出す。

2. fortran_normal(refs)：aenet-python の ANNPotential / TrainingConfig / BFGS APIを使用する。内部はFortran学習系。

3. aenet_python_torch(refs)：aenet-python の ChebyshevDescriptor と TorchTrainingConfig を使用するPyTorch学習。

4. separate_aenet_pytorch(refs)：別途導入する独立したænet-PyTorchを外部プログラムとして実行する。

提示された c01_train_ann.py では fortran_normal(refs) が有効。対象元素 ('Si', 'O')、動径/角度カットオフ 6.0 / 3.5 Å、次数 10 / 3、最小距離 0.5 Å、隠れ層は30ノード×2層、反復1000回、テスト比率10%、デバイス cpu、力の重み 0.0 。出力は SiO2/ann。FORCE_WEIGHT=0.0 はPyTorch経路の設定であり、すべての学習経路に共通する設定ではない。これらの値はv0.0.3のSiO₂計算例の設定である。

training.py はFortran互換データセットを準備し、既存 aenet.train があれば再生成を回避する。aenet-python の外部APIへは必要に応じて Path を文字列に変換する。独立ænet-PyTorchは別途実行ファイル・学習入力・変換器を要する。学習結果の .nnやPyTorchモデルの存在だけで精度は判断できない。独立したDFT検証集合でエネルギー・力・局所環境依存性を評価する。

ANN学習パラメータの物理的意味と変更方法

設定場所と呼び出し関係

通常は scripts/c01_train_ann.py の冒頭の定数を編集する。 実際の学習処理は src/aenet_env/training.py の関数 が担当し、Fortran形式の入力ファイル生成は src/aenet_env/aenet_backend.py が担当する。c01 は学習方式・パラメータを選択する呼び出し側であり、ニューラルネットワークの学習アルゴリズム自体を実装しているわけではない。

main() で fortran_legacy(refs)、fortran_normal(refs)、aenet_python_torch(refs)、separate_aenet_pytorch(refs) の 一つだけを有効にする。現在の例は fortran_normal(refs) であり、aenet-python の ANNPotential.train() を介してFortran学習を行う。方式を切り替えると利用可能な設定・出力形式・学習する物理量が異なるため、設定値を同一視しない。

原子エネルギーモデルと局所記述子

ænetは各原子の局所環境を並進・回転・同種原子の置換に不変な記述子へ変換し、元素ごとのANNで原子エネルギーを予測する。構造全体のエネルギーは原子エネルギーの和 E = Σ_i E_i として表される。これは 有限カットオフ内の局所環境から全エネルギーを近似する仮定 であり、長距離静電相互作用が自動的に厳密に扱われることを意味しない。力を学習・評価する場合はエネルギーの原子座標微分 F_i = −∂E/∂R_i を用いる。局所記述子とANNの意味についてはænet公式マニュアルおよびArtrith–Urban–Ceder (2017) を参照。

c01 の設定	現行例	意味・変更時の注意
ROOT	SiO2	相対パスの基点。実行時のカレントディレクトリから解釈される。
REFERENCES	SiO2/references	DFTラベル付きXSFの入力。*.xsf を列挙する。構造・エネルギー・力の整合性を事前確認する。
OUTPUT	SiO2/ann	生成した学習入力、データセット、学習結果の格納先。実験条件を変える際は別ディレクトリを推奨。
SPECIES	('Si', 'O')	元素別ネットワークと局所環境の化学種。参照構造の元素集合と一致させる。順序も再現性のため固定する。
RADIAL_CUTOFF	6.0 Å	中心原子から近傍原子までの動径記述子の有効範囲。大きいほど遠方の配位殻を取り込むが計算量と必要な学習データが増える。
ANGULAR_CUTOFF	3.5 Å	近傍原子間の方向・角度情報を表す角度記述子の範囲。短すぎるとSi–O–Si等のネットワーク幾何を十分区別できない可能性がある。
RADIAL_ORDER	10	Chebyshev動径展開の次数。距離分布の表現解像度を左右する。高次化は細かな構造を区別できる一方、過学習・計算負荷に注意。
ANGULAR_ORDER	3	Chebyshev角度展開の次数。局所結合角の区別能力に関係する。カットオフと組み合わせて検証する。
MINIMUM_DISTANCE	0.5 Å	記述子設定の下限距離 RMIN / min_cutoff。構造生成時の原子衝突判定閾値とは別物。極端に短いDFT構造を正当化しない。
HIDDEN_NODES	30	元素別ANNの各隠れ層のノード数。現行 architecture() は 30:tanh ×2層。容量を増やすと表現力と過学習リスクが増す。
ITERATIONS	1000	学習反復の上限設定。学習法によって1反復の意味が異なるため、異方式間の同じ数値は同じ学習量を意味しない。
TEST_PERCENT	10%	学習用データから取り分けるテスト比率。別途確保する完全独立の検証集合の代用にはならない。
DEVICE	cpu	aenet_python_torch() のPyTorch計算先。現在有効なFortran API経路には適用されない。
FORCE_WEIGHT	0.0	aenet_python_torch() のエネルギー・力損失の相対重み。0では力を直接学習しない。現在のFortran API経路にも適用されない。
GENERATE_EXE / TRAIN_EXE	generate.x / train.x	Fortran実行ファイル名またはパス。generate.x は記述子生成、train.x は直接実行経路での学習。

カットオフは記述子が参照する局所環境の空間範囲を定める。 たとえばSi–O最近接距離だけで RADIAL_CUTOFF を決めず、Si–SiやO–Oを含む第二配位殻、ネットワークの構造多様性、セル寸法を考慮する。周期セルが小さい場合はカットオフとセルの関係、周期像の取り扱いを検証する。 6.0/3.5 Å、10/3、30×2 は現行スクリプトの v0.0.3の設定例である。

方式別の設定が反映される場所

学習経路	記述子・ネットワーク	最適化・学習設定	力の教師データ
fortran_legacy	aenet_backend.py が .stp、generate.in、train.in を作成。隠れ層2層 tanh 固定	生成 train.in の METHOD bfgs、ITERATIONS、TESTPERCENT。train.x を実行	現行入力生成では力の損失重みを設定していない
fortran_normal（現行）	同じ .stp / aenet.train を準備し、architecture() を ANNPotential に渡す	TrainingConfig(iterations=..., testpercent=..., method=BFGS())	FORCE_WEIGHT は使わない
aenet_python_torch	ChebyshevDescriptor と architecture()	TorchTrainingConfig、Adam(mu=0.001, batchsize=16)	force_weight を指定できる。力を学習するにはラベルと実装対応を確認する
separate_aenet_pytorch	generate.x でデータ生成後、専用形式へ変換	独立実装の train.in と trainer_script に依存	独立実装の設定を別途確認する。c01 の FORCE_WEIGHT は直接渡されない

Fortran入力の固定設定

aenet_backend.py は train.in に MAXENERGY 10000 と METHOD bfgs を書き、NETWORKS を隠れ層2層の tanh として出力する。MAXENERGY は学習対象エネルギーの採否に関わる入力キーワードであり、 10000 を汎用的な適正値と見なさない。これらを変更したい場合、c01 の定数だけでは変更できず、 現在のモジュールAPIには対応する引数がない。独自に生成された train.in を手動変更しても、次の prepare_aenet_inputs() 呼び出しで再生成・上書きされる。

学習データセットの更新

training.prepare_fortran_dataset() は aenet.train が存在すると generate.x を実行しない。一方、.stp と generate.in は毎回書き換える。したがって RADIAL_CUTOFF、ANGULAR_CUTOFF、 RADIAL_ORDER、ANGULAR_ORDER、SPECIES、参照XSFを変更しても、 古い特徴量を含む aenet.train がそのまま使われる可能性がある。条件を変えた学習は新しい OUTPUT を使うか、既存データセットの再生成を明示的に管理する。再生成時に旧学習成果を誤消去しないよう、バックアップする。 train.restart / train.rngstate などが残るとFortranの再開学習になる場合もある。

教師データと評価上の注意

• DFTの整合性：VASPの汎関数、PAWデータセット、ENCUT、k点、スピン状態、収束条件、エネルギー基準を揃える。異なる計算条件を無批判に混合しない。XSFの全エネルギーと力の単位・符号・原子順序を確認する。

• 原子エネルギー基準：現行 generate.in の TYPES は各元素に 0.0 を設定し、PyTorch経路の atomic_energies もゼロ。これは元素ごとの基準エネルギーを物理的に求めたことを意味しない。組成が変動する場合は特に基準の一貫性を検証する。

• 分割方法：同一RMC由来のほぼ重複した構造を学習・テストへ無作為に分散すると、見かけの誤差が過小になる。元構造や生成条件単位で分離した外部検証集合を用意する。

• 評価指標：エネルギーは全エネルギーだけでなく原子あたりの誤差、相対エネルギー差、組成別・局所環境別誤差を確認する。RMCの原子移動に使うなら、移動前後の ΔE の再現性を優先的に検証する。力を使うなら成分別MAE/RMSEを評価する。

• 外挿：学習データにない短距離衝突、過小配位、過大配位、歪んだ結合角に対してANNが正しい反発やエネルギーを返す保証はない。RMCの試行移動がこれらを頻繁に生成する場合、検証と追加教師データが必要。

• 損失の解釈：FORCE_WEIGHT を正にしても、エネルギー[eV]と力[eV/Å]の誤差の規格化・サンプリング数・実装上の損失定義を確認せず、数値だけでバランスを判断しない。

• 再現性：学習・テスト分割、乱数シード、データセットのハッシュ、ænet/aenet-pythonの版、生成した .stp / train.in / generate.in、学習ログを保存する。ITERATIONS だけで収束を判定しない。

公式資料： ænetマニュアル、aenet-python、独立ænet-PyTorch 。記述子の原論文：N. Artrith, A. Urban, G. Ceder, Phys. Rev. B 96, 014112 (2017), DOI:10.1103/PhysRevB.96.014112。

インストール

1. ænet（Fortran版）のビルド

ænet本体は aenet_env とは別にインストールする。一般的なCMakeビルド例：

git clone https://github.com/atomisticnet/aenet.git
cd aenet
cmake -S . -B build -DBUILD_AENET=ON
cmake --build build --target build_all

上記はビルドまでの手順であり、インストール先を指定して配置するには cmake --install を別途実行する。

2. HPC（zaiene-hpcs2024）のIntel oneAPI / MKL構成例

ソースの作業用ディレクトリを ~/aenet/build_aenet、インストール先を /home/hpc/aenet とする例。 rm -rf build_aenet は既存ディレクトリを削除するため、作業データがないことを確認してから実行する。

cd ~/aenet
rm -rf build_aenet
git clone https://github.com/atomisticnet/aenet.git build_aenet
cd build_aenet
cmake -S . -B build \
  -DCMAKE_Fortran_COMPILER=/opt/intel/oneapi/compiler/2023.2.1/linux/bin/ifx \
  -DUSE_MKL=ON \
  -DBUILD_AENET=ON
cmake --build build --target build_all -j 8
cmake --install build --prefix /home/hpc/aenet

-S . はソースディレクトリ、-B build はビルドディレクトリ、-DCMAKE_Fortran_COMPILER=... はFortranコンパイラの指定、 -DUSE_MKL=ON はMKL利用、-DBUILD_AENET=ON はænet本体のビルド有効化、-j 8 は並列ビルド数8、--prefix はインストール先の指定である。コンパイラのパスは上記HPC固有の設定であり、他の環境では変更する。

cmake --install build のみでは、ビルド時に設定されたデフォルトのprefixへインストールされる。実際に提示されたログでは /home/hpc/aenet/build_aenet/bin/ 以下へ配置された。 /home/hpc/aenet/bin/ に配置するには --prefix /home/hpc/aenet を指定する。

提示されたインストールログでは、次のファイルが配置された。

• bin/generate.x、bin/train.x、bin/predict.x

• lib/libaenet.a、lib/libaenet.so*、include/aenet.h

• tools/fingerprint.x、tools/neighbors.x、tools/trnset_info.x、tools/trnset2ASCII.x

3. aenet-pythonの実行ファイルパス設定

ænet本体のインストール 後に、次を実行する。

aenet config --set-aenet-path /home/hpc/aenet

これは aenet-python 側でænet実行ファイルの配置先を設定するコマンド。指定したディレクトリにある実行ファイルを確認し、個別のパスを設定する。 ænet本体のビルドやインストールを行うコマンドではない。 aenet コマンドを利用できるPython環境で実行する。

4. aenet_env（Pythonツール）のインストール

aenet_env のプロジェクトルートで実行する。

pip install .

pyproject.toml の [project].dependencies に vasp-util、rmc-util、xlogger-py、numpy、GitHub版 aenet-python（配布名 aenet）、torch を指定している。pip install . はこれらのPython依存パッケージを導入するが、 ænet Fortran実行ファイル、VASP、独立版ænet-PyTorchは導入しない。[project.optional-dependencies] は使用しない。

5. 実行スクリプトの配置

計算を実施する作業ディレクトリで実行する。

aenet_env-install

share/aenet_env/scripts/ に同梱された直下の .py / .sh をカレントディレクトリへコピーする。既存ファイルはスキップし、同名ファイルは一度だけ処理する。既存ファイルを上書きするときは以下を使用する。

aenet_env-install --force

--force は既存ファイルを上書きするオプションであり、 スクリプト内のローカル設定値も失われる。必要なら事前にバックアップする。コマンド名は aenet_env-install であり、aenet_env-install.py ではない。scripts/axx/ はコピー対象外。

Python実行スクリプトの先頭行は #!/usr/bin/env python とし、実行権限を付ける。シバンがないと ./c01_train_ann.py がシェルで解釈されて失敗する。 提示された install_scripts.py 自体はコピー時のシバン・実行権限補正を保証しない ため、配布元のスクリプトを確認する。

更新・運用上の注意

update_zaiene2024.sh における chmod: *.py: No such file or directory は、該当実行位置に *.py が存在しないことを示す。シェルスクリプト本文を確認できていないため修正位置は断定しない。提供ログではrsyncによる同期とHPC上での pip install . が成功している。SSHの耐量子鍵交換警告はインストール成否とは別の問題。

同じ版番号で繰り返しwheelを作成したログがあるため、更新内容は版番号だけでなく実際にインストールされたファイルでも確認する。 build/ や .egg-info/ の転送は必要性を見直す。 v0.0.3は文書・配布・学習経路の整備段階であり、RMC_POT連携の完成版ではない。 この未実装事項はRMC連携用途についてのもので、ライブラリ全体の対象範囲を限定しない。