aenet_env

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, aenet-python, separate ænet-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:

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.

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

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:

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:

aenet_env-install

This copies packaged .py and .sh templates without overwriting existing files and processes each filename once. To overwrite local copies:

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.