# 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/en/) [![Ohara Lab](https://img.shields.io/badge/Ohara%20Lab-Home-4B5563?logo=homeassistant&logoColor=white)](https://ohara-lab-su.github.io/index.en.html) Python modules, executable templates, reference-data preparation, external-tool integration, and installation/environment setup utilities for training and using ænet ANN interatomic potentials. A representative research workflow is **RMC → small periodic DFT candidates → VASP reference data → MLP training → RMC_POT**. ## Layout and responsibilities (v0.0.3) Reusable APIs for training, reference-data preparation, structure handling, tool integration, and environment setup are provided under `src/aenet_env/`. The scripts are configurable workflow examples; users may invoke only the modules and stages they need. Modules under `src/aenet_env/` are `structure_sampling.py` (periodic checks and sampling helpers), `structures.py` (case discovery), `xyz.py` (XYZ/POSCAR), `vasp_inputs.py` (VASP setup), `references.py` (vasprun.xml to XSF), `aenet_backend.py` (ænet input generation and binaries), `training.py` (four training interfaces), and `install_scripts.py` (template installer). The project-root `scripts/` contains `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`, and HPC job templates `job_hpcs2024_node1.sh` / `job_hpcs2024_node2.sh`. `build/` and `.egg-info/` are generated build artifacts. Candidate-generation methods are selected according to the local environments and sampling conditions under study. Generated periodic cells require independent checks of composition, periodic geometry, coordination, and DFT feasibility before use as reference structures. ## Processing stages | Stage | Script | Responsibility | |----------------------|-----------------------------|---------------------------------------------------------| | Candidate generation | `a00` / `a01` / `a03_bin` | Choose a periodic DFT candidate-generation method | | b00 | `b00_make_poscar.py` | Write species-grouped POSCARs from XYZ | | b01 | `b01_stage_structures.py` | Discover and stage cases | | b02 | `b02_prepare_vasp.py` | Prepare VASP input files | | b03 | `b03_submit_vasp_jobs.py` | Submit VASP jobs on the HPC system | | c00 | `c00_collect_references.py` | Collect energy/force-labeled XSF files from VASP output | | c01 | `c01_train_ann.py` | Train an ænet potential | Candidate XYZ files are **not** DFT-labeled training data. VASP completion, convergence, and force availability must be checked before using `references/*.xsf`. ## Four training interfaces Enable exactly one function in `c01_train_ann.py` `main()`: `fortran_legacy(refs)` (direct `generate.x` / `train.x`), `fortran_normal(refs)` (`aenet-python` Fortran-backed `ANNPotential` API), `aenet_python_torch(refs)` (`aenet-python` PyTorch training with Chebyshev descriptors), or `separate_aenet_pytorch(refs)` (separate ænet-PyTorch external program). **The supplied script enables `fortran_normal(refs)`.** Its SiO₂ example uses cutoffs 6.0/3.5 Å, descriptor orders 10/3, minimum distance 0.5 Å, two hidden layers of 30 nodes, 1000 iterations, and a 10% test split. `FORCE_WEIGHT=0.0` belongs to the PyTorch configuration; it is not a universal setting for all four methods. Outputs are under `SiO2/ann`. The Fortran dataset preparation reuses an existing `aenet.train`; compatibility with external `aenet-python` APIs requires care with `Path` versus `str`. Model artifacts do not establish accuracy without independent DFT validation. ## ANN training parameters: physical meaning and configuration ### Where parameters are set Edit the constants at the beginning of `scripts/c01_train_ann.py`. This script **selects the training route and constructs its configuration**; the actual operations are implemented in `src/aenet_env/training.py`. The Fortran input generator is `src/aenet_env/aenet_backend.py`. Enable exactly one call in `main()`. The current example enables `fortran_normal(refs)`, using `aenet.mlip.ANNPotential` and `TrainingConfig(BFGS())`. ænet approximates the total energy as a sum of element-specific atomic neural-network contributions, `E = Σ_i E_i`, evaluated from local descriptors invariant to translation, rotation and permutation of identical atoms. Forces are energy derivatives, `F_i = −∂E/∂R_i`. The finite descriptor cutoff is a modeling assumption; it does not automatically provide exact long-range electrostatics. | Setting in `c01` | Current value | Physical/operational meaning | |----------------------------------|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | `ROOT` / `REFERENCES` / `OUTPUT` | `SiO2` / `SiO2/references` / `SiO2/ann` | Paths relative to the process working directory. References are DFT-labeled XSF files; keep separate output directories for different experiments. | | `SPECIES` | `('Si', 'O')` | Species for element-specific networks and local environments; must match the reference set. | | `RADIAL_CUTOFF` | `6.0 Å` | Range of radial neighbor-environment information; increasing it adds coordination shells and cost. | | `ANGULAR_CUTOFF` | `3.5 Å` | Range of angular environment information; test its ability to distinguish network bond angles. | | `RADIAL_ORDER` | `10` | Chebyshev radial expansion order, controlling radial descriptor resolution. | | `ANGULAR_ORDER` | `3` | Chebyshev angular expansion order, controlling angular descriptor resolution. | | `MINIMUM_DISTANCE` | `0.5 Å` | Descriptor `RMIN` / `min_cutoff`, **not** a structural collision-rejection threshold. | | `HIDDEN_NODES` | `30` | Nodes per hidden layer; `architecture()` specifies two `tanh` layers. More capacity increases overfitting risk. | | `ITERATIONS` | `1000` | Training iteration limit; iterations are not directly comparable between optimizers. | | `TEST_PERCENT` | `10` | Holdout fraction within the supplied training set; not a substitute for an independent validation set. | | `DEVICE` | `cpu` | PyTorch-only compute device, not used by the currently selected Fortran API route. | | `FORCE_WEIGHT` | `0.0` | PyTorch-only relative force-loss weight; zero means forces are **not directly fitted**. Not used by the Fortran API route. | | `GENERATE_EXE` / `TRAIN_EXE` | `generate.x` / `train.x` | Fortran executables; ensure they can be found through `PATH` or supply paths. | Cutoffs are **not chemical bond lengths**. Select them considering relevant Si–O, Si–Si, O–O shells, bond-angle distributions, the periodic cell and computational cost. The example values are **not validated optimum hyperparameters**. ### Route-specific behavior - `fortran_legacy`: `prepare_fortran_dataset()` generates `.stp`, `generate.in`, `train.in`, and `aenet.train`; `train_fortran_legacy()` calls `train.x`. The generated input uses `METHOD bfgs`, two `tanh` hidden layers, `ITERATIONS`, and `TESTPERCENT`. - `fortran_normal` (**currently selected**): uses the same generated training set, passes `architecture()` and `TrainingConfig(iterations=..., testpercent=..., method=BFGS())` to `ANNPotential.train()`. `FORCE_WEIGHT` does not apply. - `aenet_python_torch`: constructs `ChebyshevDescriptor` and `TorchTrainingConfig` with `Adam(mu=0.001, batchsize=16)`; only this route currently passes `force_weight`. Check the availability and consistency of reference forces before enabling force training. - `separate_aenet_pytorch`: uses the separate project's `train.in`, training script and conversion tools. Its parameters are **not** controlled by `c01`'s `FORCE_WEIGHT`. **Hard-coded settings:** `aenet_backend.py` writes `MAXENERGY 10000`, `METHOD bfgs`, and two `tanh` hidden layers. There are currently no corresponding arguments in the module API; changing only a `c01` constant cannot alter these. Manually editing generated `train.in` is not persistent because input generation overwrites it. **Stale dataset hazard:** `training.prepare_fortran_dataset()` skips `generate.x` when `OUTPUT/aenet.train` already exists, even though it rewrites `.stp` and `generate.in`. Changes to cutoff, expansion order, species or reference structures may therefore be **silently ignored in the featurized training set**. Use a fresh `OUTPUT` directory per descriptor/reference-set revision or explicitly manage regeneration and backups. Existing `train.restart` and `train.rngstate` may trigger a Fortran restart rather than a new fit. ### Validation and scientific cautions Use consistent VASP settings (functional, PAW potentials, cutoff, k-points, convergence and spin). Verify XSF energies, force units/signs, species and atom order. Both the generated Fortran `TYPES` and PyTorch `atomic_energies` currently use zero atomic reference energies; this does not imply physically calibrated isolated-atom energies. Prevent leakage by keeping closely related RMC-derived structures in the same split, and reserve an external test set. Assess per-atom energy MAE/RMSE, relative energies, force-component errors when applicable, and **energy differences across RMC trial moves**. Validate short-range repulsion and under-/over-coordinated environments: ANN extrapolation is not guaranteed to be physical. Interpret force weights only after checking loss normalization. Record random seeds, splits, reference-set provenance, software versions and generated input files. References: [ænet manual](https://github.com/atomisticnet/aenet/blob/master/doc/aenet-doc.org), [aenet-python](https://github.com/atomisticnet/aenet-python), [separate ænet-PyTorch](https://github.com/atomisticnet/aenet-PyTorch). Chebyshev descriptor: N. Artrith, A. Urban and G. Ceder, *Phys. Rev. B* **96**, 014112 (2017), DOI: 10.1103/PhysRevB.96.014112. ## Installation ### 1. Build the ænet Fortran executables ænet Fortran is installed separately from the Python package: ```bash git clone https://github.com/atomisticnet/aenet.git cd aenet cmake -S . -B build -DBUILD_AENET=ON cmake --build build --target build_all ``` This builds the software; installation is a separate step. ### 2. HPC example: Intel oneAPI and MKL The following example uses `/home/hpc/aenet` as the installation prefix. **`rm -rf build_aenet` deletes that directory; verify its contents first.** ```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` selects the source tree, `-B` the build directory, `CMAKE_Fortran_COMPILER` the Fortran compiler, `USE_MKL` the MKL backend, `BUILD_AENET` the ænet build, `-j 8` eight parallel jobs, and `--prefix` the installation destination. The compiler path is HPC-specific. Without `--prefix`, `cmake --install build` uses the configured default prefix; the supplied log installed into `/home/hpc/aenet/build_aenet/`. With `--prefix /home/hpc/aenet`, the supplied log confirms installation of `bin/generate.x`, `bin/train.x`, `bin/predict.x`, `lib/libaenet.a`, `lib/libaenet.so*`, `include/aenet.h`, and tools `fingerprint.x`, `neighbors.x`, `trnset_info.x`, and `trnset2ASCII.x`. ### 3. Configure aenet-python after installing ænet ```bash aenet config --set-aenet-path /home/hpc/aenet ``` Run this **after** installing the Fortran executables. The `aenet-python` command checks the executables and sets their individual paths; it does not compile or install ænet itself. ### 4. Install the aenet_env Python package From the `aenet_env` project root: ```bash pip install . ``` `[project].dependencies` installs `vasp-util`, `rmc-util`, `xlogger-py`, `numpy`, GitHub-hosted `aenet-python` (distribution name `aenet`), and `torch`. This does **not** install VASP, the ænet Fortran binaries, or standalone ænet-PyTorch. No optional dependency group is used. ### 5. Copy executable templates Run in the target working directory: ```bash aenet_env-install ``` This copies packaged `.py` and `.sh` templates without overwriting existing files and processes each filename once. To overwrite local copies: ```bash aenet_env-install --force ``` `--force` replaces local files **including their configuration values**. Back up modified templates first. The command is `aenet_env-install`, not `aenet_env-install.py`. The `scripts/axx/` directory is not copied. Executable Python templates must start with `#!/usr/bin/env python` and have executable permissions. Missing shebangs caused the shell to interpret `./c01_train_ann.py` as a shell script. **The supplied `install_scripts.py` does not guarantee shebang or permission repairs at copy time.** The `update_zaiene2024.sh` `chmod: *.py: No such file or directory` warning is separate; the shell script has not been inspected. The supplied HPC logs confirm successful wheel installation, not successful ANN training. ## Validation boundary Check periodic boundary geometry, composition, local coordination and connectivity, DFT convergence, held-out energies and forces, and applicability to the target configuration space before using an ANN energy in simulation or as an RMC_POT constraint. The current release does not claim an implemented RMC_POT adapter or validated ANN accuracy.