Files

Overview¶

There are two mandatory input files required for all RuNNer calculations:

1. input.nn: Contains all configuration settings and keywords.
2. input.data: Contains the dataset (atomic positions, lattice vectors, energies, forces, etc.).

Philosophy?¶

Here has to come something about the philosophy of the file system (dump files etc.)

Mode Precompute¶

The Precompute mode takes input.nn and input.data as input. It generates files required that can potentially speed up subsequent training runs, but is in general not needed.

Typical Output Files:

• Descriptor values: function.data and function.data.info(binary) or function.data.ascii.

• Descriptor derivatives: function_derivative.data and function_derivative.data.info(binary).

• Scaling factors: scaling.data.

• Coulomb matrices (if enabled): coulomb_matrix.data.

Mode Train¶

Input:

• input.nn & input.data.

• (Optional) Precomputed files from Precompute mode (function.data, function.data.info, function.data.ascii, function_derivative.data, function_derivative.data.info, scaling.data, coulomb_matrix.data).

• (Optional) weights.data for starting from old weights.

• (Optional) train_split.data and test_split.data to start from old splits.

Output:

• Weights: weights.out (periodic snapshots) and opt.weights.out (best epoch).

• Split info: train_split.data and test_split.data.

• Scaling factors: scaling.data.

• Prediction files (Optional): Prediction files for the training trajectory (atoms.out, charge.out, energy.out, forces.out, structure.out).

Mode Predict¶

Input:

• input.nn & input.data.

• scaling.data (Essential for correct feature scaling).

• weights.data (The trained model parameters).

Output:

• Prediction files: atoms.out, charge.out, energy.out, forces.out, and structure.out.

Input and Output Files¶

Prefixes and Suffixes¶

Prefixes and suffixes are used for some files to specify which feature maps information is stored in them. The exact format for including them is specified in the description of each file. Suffixes are used to specify feature maps containing local information, while prefixes are used for feature maps containing global information. The local suffixes are:

• short: used for short-range energy features

• charge: used for local charge features

• hirshv: used for features describing the Hirshfeld volume of an atom

• hardness: used for features describing the local hardness of an atom

• chi: used for features describing local atomic electronegativities

The global prefixes are:

• qeq: for global charges from charge equilibration, that are also used as features

• ee4g: for global charges used as feature in an ee4g.

atoms.out¶

Mode precompute: : Not Used

Mode train: : Possible Output

Mode predict: : Mandatory Output

This output file contains the atom_id and all predicted atomic properties, e.g., energies, charges, Hirshfeld volumes, hardness values, electronegativities, for each atom in the dataset. It is written during mode predict and during mode train if write_atoms_out is used. Reference values are not written into this file. For committees the file is written into the committees folder.

charges.data¶

Mode precompute: :  Possible Output 

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed global feature values of the dataset in binary form. The file can be written between the long- and the short-range fit in a 4G in mode precompute by using format_binary. In mode train and predict the file can be read in by using read_global_features_q or read_global_features_ee, for 4Gs and ee4Gs.

charges.data.ascii¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed global feature values of the dataset in human readable form. The file can be written between the long- and the short-range fit in a 4G in mode precompute by using format_ascii. This file can not read in later by RuNNer. If you want to write a file that can be read in by RuNNer, use format_binary to write the charges.data file.

charges.data.info¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the metainformation needed to read charges.data. It is always written and read in together with charges.data.

charge.out¶

Mode precompute: : Not Used 

Mode train: : Possible Output

Mode predict: : Possible Output

This output file contains the atom_id, the predicted atomic charges, and the reference atomic charges for each atom in the dataset. If atomic charges are predicted, the file is always written in mode predict. In mode train it can be written for the optimal epoch, based on the criteria of write_charge_out, by using optimal_epoch_property. The file can also be written periodically every few epochs when additionally using write_frequency. The file is splitted in mode train into a training set file and a test set file. For committees the file is written into the committees folder.

coulomb_matrix.data¶

Mode precompute: : Possible Output 

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed Coulomb matrices of all structures in the dataset. The file can be written during mode precompute by using write_coulomb_matrix. It can be read in during mode trainand predict by using read_coulomb_matrix.

coulomb_matrix.data.info¶

Mode precompute: : Possible Output 

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the metainformation needed to read Coulomb matrices of all structures in the dataset. The file can be written during mode precompute by using write_coulomb_matrix. It is always written and read in together with coulomb_matrix.data.

energy.out¶

Mode precompute: : Not Used 

Mode train: : Possible Output

Mode predict: : Mandatory Output

This output file contains for all structures in the dataset the structure_id, the number of atoms in the structure, all energy contributions (e.g. short-range, electrostatic, vdW), the predicted total energy of each structure, the reference energy, and the predictions error per atom. The file is always written in mode predict. In mode trainit can be written for the optimal epoch, based on the criteria of write_energy_out, by using optimal_epoch_property. The file can also be written periodically every few epochs when additionally using write_frequency. The file is splitted in mode train into a training set file and a test set file.

For committees the file is written into the committees folder.

feature_derivative.data¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed global feature derivative values of the dataset in binary form. The file can be written between the long- and the short-range fit in a 4G in mode precompute by using format_binary in combination with calculate_forces. In mode train and predict the file can be read in by using read_global_feature_derivatives_q or read_global_feature_derivatives_ee, for 4Gs and ee4Gs.

feature_derivative.data.info¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the metainformation needed to read feature_derivative.data. It is always written and read in together with feature_derivative.data.

forces.out¶

Mode precompute: : Not Used 

Mode train: : Possible Output

Mode predict: : Possible Output

This file contains for each atom in the dataset its atom_id, the structure_id of the corresponding structure, and prediction and reference for all 3 force components of the atom. The predicted forces are already summed up over all energy contributions. The file is written in mode predict if calculate_forces is used. In mode train it can also be written by using calculate_forces in combination with write_forces_out.

function.data¶

Mode precompute: :  Possible Output 

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed feature values of the dataset in binary form. The file can be written in mode precomputeby using format_binary. In mode train and predictthe file can be read in by using read_features.

function.data.ascii¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed feature values of the dataset in human readable form. The file can be written in mode precompute by using format_ascii This file can not read in later by RuNNer. If you want to write a file that can be read in by RuNNer, use format_binary to write the function.data file.

function.data.info¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the metainformation needed to read function.data. It is always written and read in together with function.data.

function_derivative.data¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the precomputed feature derivative values of the dataset in binary form. The file can be written in mode precompute by using format_binary in combination with calculate_forces. In mode train and predictthe file can be read in by using read_feature_derivatives.

function_derivative.data.info¶

Mode precompute: : Possible Output

Mode train: : Possible Input

Mode predict: : Possible Input

This file contains the metainformation needed to read function_derivative.data. It is always written and read in together with function_derivative.data.

input.data¶

Mode precompute: : Mandatory Input

Mode train: : Mandatory Input

Mode predict: : Mandatory Input

One of the main input files of RuNNer. This file contains all information about the dataset, the elements, atom positions, lattice vectors, and all reference values for all properties. The information stated in each line is signaled by a keyword at the beginning of the lines.

Possible keywords are:

• begin: Signals the start of a new structure. This line is also used to define the atomic properties and the order they are written in the atom line. For properties with more than one entry per atom, the length has to be given in parentheses behind the name of the property. If no properties names are given at all, the following default is used:

  begin position(3) element charge energy forces(3)

  The number and order of properties can differ between the structures of a dataset. This makes it very convenient to combine structures from different calculations, e.g., if you have not for every atom reference charges!

• lattice: This line contains one of the three lattice vector of a periodic structure. The keyword is followed by the three vector components. Periodic structures need exactly three lattice vectors! To define a non-periodic structure simply do not use this line.

• comment: You can write everything you want into this line! Useful are e.g. comments about refeence methods etc.

• atom: This line contains all information about one atom of the structure, e.g. position, element, force components, charges..., in the order specified in the begin line.

• charge: Contains the total charge of a structure. This is relevant if predicted charges are constrained to yield the total charge.

• energy: Contains the structures energy.

• end: Signals the end of a structure. The number of begin and end statements in the file have to be the same.

You can leave out lines or properties that are not used in your calculations.

input.nn¶

Mode precompute: : Mandatory Input

Mode train: : Mandatory Input

Mode predict: : Mandatory Input

One of the main input files of RuNNer. It contains all the settings and keywords to set up a calculation. Keywords can be given in arbitrary order. Blank lines and permitted. Comments can be written with #. If keywords are not specified, reasonable defaults are assumed where possible and written to the output for information. If an essential keyword is missing, RuNNer will stop with an error message and ask the user to specify the keyword. The specifics of each keyword are described in the keyword section.

opt.weights.out¶

Mode precompute: : Not Used 

Mode train: : Mandatory Output

Mode predict: : No Used

This output file contains the weights of one neural network of one element for the currently best training epoch based on the criteria stated with optimal_epoch_property. Files of this type are written for all trained neural networks and all elements during mode train and constantly updated during the training process. For committees the file is written into the committees folder.

optimizer_restart_x_y.data¶

Mode precompute: : Not Used 

Mode train: : Mandatory Output

Mode predict: : No Used

This output file contains the arrays for saving the state of the optimizer in the last epoch of the training. Files of this type are written for all (Kalman-) optimizers during mode train and constantly updated after each epoch.

optimizer_restart_x_y.data.info¶

Mode precompute: : Not Used 

Mode train: : Mandatory Output

Mode predict: : No Used

This output file contains the metadata for optimizer_restart_x_y.data.

scaling.data¶

Mode precompute: : Possible Output

Mode train: : Possible In-/Output

Mode predict: : Mandatory Input

This file contains information about the scaling and centering of the features and is specific to a set of structures and descriptors. It can be written in mode precompute by using use_old_scaling. In mode train it can be either read in using use_old_scaling, or otherwise is written if center_feature_maps or scale_feature_maps is used.

The file is organized in five columns which give the element_index (integers starting from 1 for each element in the order in which they are listed in elements), the feature_map_index like it is given in the RuNNer output, then the minimum, maximum and average value of this feature map.

stress.out¶

Mode precompute: : Not Used 

Mode train: : Not Used

Mode predict: : Possible Output

This file contains for each structure in the dataset the structure_id of the corresponding structure, and prediction for all 9 stress components of the cell. The predicted stresses are already summed up over all energy contributions. The file is written in mode predict if calculate_stress is used.

structure.out¶

Mode precompute: : Not Used

Mode train: : Possible Output

Mode predict: : Mandatory Output

This output file contains for each structure of the dataset the structure_id, the number of atoms, and the predicted structural properties, e.g., short-range energies, electrosttaic energies, vdW energies, etc. It is written during mode predict and during mode train if write_structure_out is used. Reference values are not written into this file. For committees the file is written into the committees folder.

test_split.data¶

Mode precompute: : Not Used

Mode train: : Possible Input / Mandatory Output

Mode predict: : Not Used

This file contains the structure_ids of all structures in the test set. It can be read in using use_old_split to manually change the train/test split or replicate the split of another fit.

train_split.data¶

Mode precompute: : Not Used

Mode train: : Possible Input / Mandatory Output

Mode predict: : Not Used

This file contains the structure_ids of all structures in the train set. It can be read in using use_old_split to manually change the train/test split or replicate the split of another fit.

weights.data¶

Mode precompute: : Not Used

Mode train: : Possible Input

Mode predict: : Mandatory Input

This file contains the weights of one neural network of one element. The file has the same format as the opt.weights.out and weights.out files. It is read in to initialize the weights in mode predict and can be used with initialization_method read to initialize the weights in mode train. For committees the file is written into the committees folder.

weights.out¶

Mode precompute: : Not Used

Mode train: : Mandatory Output

Mode predict: : Not Used

This file contains the weights of one neural network of one element. The file has the same format as the opt.weights.out and weights.data files. It is written during mode train periodically depending on write_frequency.