aenet_env package

VASP教師データの準備とænet学習処理を提供するパッケージ。

Submodules

aenet_env.aenet_backend module

ænet の学習入力自動生成と公式バイナリ実行。

ænet 2.x の generate.x / train.x の入力形式に従う。

aenet_env.aenet_backend.prepare_aenet_inputs(references, output, *, species, radial_cutoff, angular_cutoff, radial_order, angular_order, minimum_distance, hidden_nodes, iterations, test_percent)

XSF から ænet 2.x の generate.in / train.in / 各元素 .stp を作る。

既存の学習出力ファイル（*.nn、aenet.train、restart 等）は変更しない。 入力ファイルだけを書き換える。

引数:

references: 呼び出し元から指定するreferences。 output: 呼び出し元から指定するoutput。 species: 呼び出し元から指定するspecies。 radial_cutoff: 呼び出し元から指定するradial_cutoff。 angular_cutoff: 呼び出し元から指定するangular_cutoff。 radial_order: 呼び出し元から指定するradial_order。 angular_order: 呼び出し元から指定するangular_order。 minimum_distance: 呼び出し元から指定するminimum_distance。 hidden_nodes: 呼び出し元から指定するhidden_nodes。 iterations: 呼び出し元から指定するiterations。 test_percent: 呼び出し元から指定するtest_percent。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• references (Sequence[Path])

• output (Path)

• species (Tuple[str, ...])

• radial_cutoff (float)

• angular_cutoff (float)

• radial_order (int)

• angular_order (int)

• minimum_distance (float)

• hidden_nodes (int)

• iterations (int)

• test_percent (int)

Return type:

None

aenet_env.aenet_backend.train_aenet(output, *, generate_exe, train_exe)

ænet公式バイナリでgenerate.x→train.xを実行する。

引数:

output: 呼び出し元から指定するoutput。 generate_exe: 呼び出し元から指定するgenerate_exe。 train_exe: 呼び出し元から指定するtrain_exe。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

Parameters:

• output (Path)

• generate_exe (str)

• train_exe (str)

Return type:

None

aenet_env.install module

インストール済みの雛形をカレントディレクトリに配置する。

aenet_env.install.find_installed_scripts()

インストール先と配布記録を調べ、同名の雛形を一度だけ取得する。

Return type:

list[Path]

aenet_env.install.install_scripts(destination, *, force=False)

雛形を配置する。forceが真のときだけ既存ファイルを上書きする。

Parameters:

• destination (Path)

• force (bool)

Return type:

tuple[int, int]

aenet_env.install.main()

aenet_env install で雛形をカレントディレクトリに配置する。

Return type:

None

aenet_env.references module

VASP vasprun.xmlからænet用の周期XSF教師構造を生成する。

XSFはænet公式のCRYSTAL/PRIMVEC/PRIMCOORD仕様に従う。 未完了・未収束のVASP計算や欠落した力を教師データとして扱わない。

aenet_env.references.collect_reference_xsf(cases, references, *, filename='reference.xsf')

完了したVASP計算からXSFを生成・収集し、不完全な計算結果は除外する。

引数:

cases: 呼び出し元から指定するcases。 references: 呼び出し元から指定するreferences。 filename: 呼び出し元から指定するfilename。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileExistsError: 関数内の条件判定により送出する。 FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• cases (Sequence[Path])

• references (Path)

• filename (str)

Return type:

List[Path]

aenet_env.references.vasprun_to_xsf(source, destination)

周期構造のXSFを生成する。単位はÅ、eV、eV/Åとし、既存ファイルを上書きしない。

引数:

source: 呼び出し元から指定するsource。 destination: 呼び出し元から指定するdestination。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileExistsError: 関数内の条件判定により送出する。

Parameters:

• source (Path)

• destination (Path)

Return type:

None

aenet_env.structure_sampling module

aenet_env.structures module

構造群の探索・DFTケースの複製。

このモジュールは材料に依存せず、example/以下から呼び出す。

aenet_env.structures.discover_cases(structures)

既存構造群からPOSCARを再帰探索する。材料名・階層数は問わない。

引数:

structures: 呼び出し元から指定するstructures。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

structures (Path)

Return type:

List[Path]

aenet_env.structures.discover_flat_cases(material_dir)

材料ディレクトリ直下の番号付きPOSCARディレクトリを探索。

引数:

material_dir: 呼び出し元から指定するmaterial_dir。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

material_dir (Path)

Return type:

List[Path]

aenet_env.structures.load_or_discover_cases(material_dir)

番号付きPOSCARディレクトリを直接探索する。台帳は使用しない。

引数:

material_dir: 呼び出し元から指定するmaterial_dir。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

Parameters:

material_dir (Path)

Return type:

List[Path]

aenet_env.structures.stage_cases(structures, calculations)

元のサブディレクトリ階層を保持して計算用POSCARをコピーする。

既存POSCARと内容が異なる場合は上書きせず停止する。VASP結果を消さない。

引数:

structures: 呼び出し元から指定するstructures。 calculations: 呼び出し元から指定するcalculations。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileExistsError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• structures (Path)

• calculations (Path)

Return type:

List[Path]

aenet_env.training module

ænetの各学習実装を呼び出すための共通処理。

選択された学習方式の実行と入力データの検証を担当する。 学習方式と最適化手法の選択は呼び出し側が行い、このモジュールでは決定しない。 Fortran版の直接実行とaenet-pythonのANNPotentialは、いずれもFortran学習処理を利用する。 aenet-pythonのTorchANNPotentialは同パッケージ内の別実装である。 独立したaenet-PyTorchは外部プログラムとして扱い、Pythonモジュールとして読み込まない。

外部ライブラリのソースは変更しない。外部コマンドの実行は呼び出し側ではなく本モジュールで行う。

aenet_env.training.prepare_fortran_dataset(references, output, *, species, radial_cutoff, angular_cutoff, radial_order, angular_order, minimum_distance, hidden_nodes, iterations, test_percent, generate_exe='generate.x')

Fortran版と互換性のある記述子および学習データを生成する。

引数:

references: 呼び出し元から指定するreferences。 output: 呼び出し元から指定するoutput。 species: 呼び出し元から指定するspecies。 radial_cutoff: 呼び出し元から指定するradial_cutoff。 angular_cutoff: 呼び出し元から指定するangular_cutoff。 radial_order: 呼び出し元から指定するradial_order。 angular_order: 呼び出し元から指定するangular_order。 minimum_distance: 呼び出し元から指定するminimum_distance。 hidden_nodes: 呼び出し元から指定するhidden_nodes。 iterations: 呼び出し元から指定するiterations。 test_percent: 呼び出し元から指定するtest_percent。 generate_exe: 呼び出し元から指定するgenerate_exe。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。

Parameters:

• references (Sequence[Path])

• output (Path)

• species (tuple[str, ...])

• radial_cutoff (float)

• angular_cutoff (float)

• radial_order (int)

• angular_order (int)

• minimum_distance (float)

• hidden_nodes (int)

• iterations (int)

• test_percent (int)

• generate_exe (str)

Return type:

Path

aenet_env.training.train_aenet_python_torch(references, *, architecture, descriptor, config, model_path)

aenet-pythonのTorchANNPotentialを使い、XSFファイルから学習する。

公式の学習手順に従い、XSFファイル名をtrainへ直接渡す。 独自のStructure生成処理やXSFの再解析は行わない。 descriptorとconfigには、呼び出し側で作成したaenet-python固有の設定オブジェクトを渡す。

例外:

ValueError: 教師構造が指定されていない場合。 FileNotFoundError: 教師構造のファイルが存在しない場合。 ImportError: aenet-pythonのPyTorch関連機能を読み込めない場合。

引数:

references: 呼び出し元から指定するreferences。 architecture: 呼び出し元から指定するarchitecture。 descriptor: 呼び出し元から指定するdescriptor。 config: 呼び出し元から指定するconfig。 model_path: 呼び出し元から指定するmodel_path。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• references (Sequence[Path])

• architecture (Mapping[str, list[tuple[int, str]]])

• descriptor (Any)

• config (Any)

• model_path (Path)

Return type:

Any

aenet_env.training.train_fortran_api(training_set, *, architecture, config, workdir)

aenet-pythonのANNPotential APIを介して、Fortran版の学習処理を実行する。

引数:

training_set: 呼び出し元から指定するtraining_set。 architecture: 呼び出し元から指定するarchitecture。 config: 呼び出し元から指定するconfig。 workdir: 呼び出し元から指定するworkdir。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。

Parameters:

• training_set (Path)

• architecture (Mapping[str, list[tuple[int, str]]])

• config (Any)

• workdir (Path)

Return type:

Any

aenet_env.training.train_fortran_legacy(workdir, *, train_exe='train.x')

従来のtrain.xを直接実行する。別のポテンシャルモデルを導入するものではない。

引数:

workdir: 呼び出し元から指定するworkdir。 train_exe: 呼び出し元から指定するtrain_exe。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。

Parameters:

• workdir (Path)

• train_exe (str)

Return type:

None

aenet_env.training.train_separate_aenet_pytorch(training_set, *, converter_exe, python_exe, trainer_script, train_input, output, nn_converter_exe=None, ascii_models=None)

2023年公開の独立したaenet-PyTorchを、その専用train.in形式で実行する。

引数:

training_set: 呼び出し元から指定するtraining_set。 converter_exe: 呼び出し元から指定するconverter_exe。 python_exe: 呼び出し元から指定するpython_exe。 trainer_script: 呼び出し元から指定するtrainer_script。 train_input: 呼び出し元から指定するtrain_input。 output: 呼び出し元から指定するoutput。 nn_converter_exe: 呼び出し元から指定するnn_converter_exe。 ascii_models: 呼び出し元から指定するascii_models。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• training_set (Path)

• converter_exe (str)

• python_exe (str)

• trainer_script (Path)

• train_input (Path)

• output (Path)

• nn_converter_exe (str | None)

• ascii_models (Mapping[str, str] | None)

Return type:

None

aenet_env.vasp_inputs module

aenet_env.xyz module

XYZの解析、周期セル検査、元素ブロック順のPOSCAR生成。

このモジュールは材料に依存せず、example/以下から呼び出す。

aenet_env.xyz.convert_xyz_tree(xyz_root, structures, *, elements, cell=None)

指定ディレクトリ直下のXYZを、それぞれの名前に対応するVASP計算用ディレクトリへ変換する。

対象はxyz_root直下のXYZファイルに限る。既存のPOSCARは保持し、 内容が一致しない場合は上書きせず例外を送出する。

引数:

xyz_root: 呼び出し元から指定するxyz_root。 structures: 呼び出し元から指定するstructures。 elements: 呼び出し元から指定するelements。 cell: 呼び出し元から指定するcell。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileNotFoundError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• xyz_root (Path)

• structures (Path)

• elements (Sequence[str])

• cell (Sequence[Sequence[float]] | None)

Return type:

List[Path]

aenet_env.xyz.parse_xyz(path, cell=None)

単一フレームのXYZを読み、元素・直交座標・周期セルを返す。

extended XYZのLattice属性、または明示したcellが必須。 周期セルが無い場合や原子数が不整合の場合はValueErrorを送出する。

引数:

path: 呼び出し元から指定するpath。 cell: 呼び出し元から指定するcell。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

ValueError: 関数内の条件判定により送出する。

Parameters:

• path (Path)

• cell (Sequence[Sequence[float]] | None)

Return type:

Tuple[List[str], List[Tuple[float, float, float]], List[List[float]]]

aenet_env.xyz.write_poscar(source, destination, *, elements, cell=None)

XYZの原子を元素別にまとめ、VASP5形式のPOSCARを保存する。

elementsの並びがPOSCARの元素ブロック順になる。 既存POSCARと内容が異なる場合は上書きせず停止する。

引数:

source: 呼び出し元から指定するsource。 destination: 呼び出し元から指定するdestination。 elements: 呼び出し元から指定するelements。 cell: 呼び出し元から指定するcell。

戻り値:

関数の戻り値型に従う。戻り値がない場合はNone。

例外:

FileExistsError: 関数内の条件判定により送出する。 ValueError: 関数内の条件判定により送出する。

Parameters:

• source (Path)

• destination (Path)

• elements (Sequence[str])

• cell (Sequence[Sequence[float]] | None)

Return type:

None