# aenet_env [![en](https://img.shields.io/badge/lang-en-red.svg)](https://ohara-lab-su.github.io/aenet_env/en/index.html) [![ja](https://img.shields.io/badge/lang-ja-yellow.svg)](https://ohara-lab-su.github.io/aenet_env/ja/index.html) [![GitHub](https://img.shields.io/badge/GitHub-ohara--lab--su%2Faenet_env-181717?logo=github)](https://github.com/ohara-lab-su/aenet_env/) [![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Documentation-222222?logo=githubpages&logoColor=white)](https://ohara-lab-su.github.io/aenet_env/ja/) [![Ohara Lab](https://img.shields.io/badge/Ohara%20Lab-Home-4B5563?logo=homeassistant&logoColor=white)](https://ohara-lab-su.github.io/index.html) ænetによるANN原子間ポテンシャルの学習・利用に必要なPythonモジュール群、 実行スクリプト、参照データ準備、外部ツール連携、 インストールおよび実行環境の構築を支援するライブラリ。 ## 設計上の位置付け 研究ワークフローの一例は **RMC → 小規模周期DFT候補 → VASP参照計算 → MLP学習 → RMC_POT** 。RMCが散乱データに基づく構造探索を担い、MLPはDFTに基づくエネルギー評価を担う。大きなRMCセルをそのままDFTで計算することは前提としない。一方、小規模周期セルへの変換は局所環境・組成・周期境界・配位の整合性を自動的に保証しない。候補構造の評価では、局所環境の再現性、周期境界の影響、DFT計算への適合性を確認する。 `src/aenet_env/` は学習・参照データ準備・構造処理・外部ツール呼び出し・環境構築を再利用するためのAPI群、`scripts/` は具体的なワークフローや実行設定の雛形を置く。利用者は目的に応じて必要なモジュール・段階だけを使用できる。スクリプトは先頭の定数を編集し、 `main()` から実行する。 ## 現行ディレクトリ構成（v0.0.3） ```text 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マニュアル](https://github.com/atomisticnet/aenet/blob/master/doc/aenet-doc.org)、[aenet-python](https://github.com/atomisticnet/aenet-python)、[独立ænet-PyTorch](https://github.com/atomisticnet/aenet-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ビルド例： ```bash 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` は既存ディレクトリを削除する**ため、作業データがないことを確認してから実行する。 ```bash 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本体のインストール **後**に、次を実行する。 ```bash aenet config --set-aenet-path /home/hpc/aenet ``` これは `aenet-python` 側でænet実行ファイルの配置先を設定するコマンド。指定したディレクトリにある実行ファイルを確認し、個別のパスを設定する。 **ænet本体のビルドやインストールを行うコマンドではない。** `aenet` コマンドを利用できるPython環境で実行する。 ### 4. aenet_env（Pythonツール）のインストール `aenet_env` のプロジェクトルートで実行する。 ```bash 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. 実行スクリプトの配置 計算を実施する作業ディレクトリで実行する。 ```bash aenet_env-install ``` `share/aenet_env/scripts/` に同梱された直下の `.py` / `.sh` をカレントディレクトリへコピーする。既存ファイルはスキップし、同名ファイルは一度だけ処理する。既存ファイルを上書きするときは以下を使用する。 ```bash 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連携用途についてのもので、ライブラリ全体の対象範囲を限定しない。