|
| 1 | +```@meta |
| 2 | +CurrentModule = ACEfriction.DataUtils |
| 3 | +``` |
| 4 | + |
| 5 | +The submodule `ACEfriction.DataUtils.jl` provides structures to internally store friction data in `ACEfriction.jl` and functions to import and export friction data from and to custom formatted hdf5 files. |
| 6 | + |
| 7 | + |
| 8 | +### [Friction Data representation](@id friction-data-representation) |
| 9 | + |
| 10 | +For pre-training storage and manipulation of friction data, |
| 11 | +`ACEfriction.jl` implements the structure `FrictionData` to represent a single observation $(R_i,\Gamma_i)$ of an atomic configuration $R_i$ and corresponding friction tensor $\Gamma_i$: |
| 12 | +```julia |
| 13 | +struct FrictionData |
| 14 | + atoms |
| 15 | + friction_tensor |
| 16 | + friction_indices |
| 17 | +end |
| 18 | +``` |
| 19 | +where |
| 20 | +- `atoms` -- stores data of the atomic configuration ans is assumed to be of type `JuLIP.Atoms`, |
| 21 | +- `friction_tensor` -- stores data on the friction tensor and is assumed to be of type`SparseMatrix{SMatrix{3, 3, T, 9}}`, where `T<:Float` and `Ti<:Int`. That is, the friction tensor is stored in the form of sparse matrices with $3 \times 3$-matrix valued block entries, |
| 22 | +- `friction_indices` -- is a one-dimensional integer array, which contains all atom indices for which the friction tensor is defined. |
| 23 | + |
| 24 | +### Importing & Exporting Friction Data |
| 25 | + |
| 26 | +`ACEfriction.DataUtils` implements the function [`save_h5fdata`](@ref) to save arrays of friction data to a [custom formatted](@ref costum-hdf5-format) `hdf5` file, as well as the function [`load_h5fdata`](@ref) to load friction data from such costum formatted `hdf5` files: |
| 27 | + |
| 28 | +```@docs |
| 29 | +save_h5fdata |
| 30 | +``` |
| 31 | + |
| 32 | +```@docs |
| 33 | +load_h5fdata |
| 34 | +``` |
| 35 | + |
| 36 | + |
| 37 | +### [Custom HDF5 File Format for Friction Data](@id costum-hdf5-format) |
| 38 | + |
| 39 | +The hierachical structure of such hdf5 files is as follows: |
| 40 | + |
| 41 | +Each observation $(R_i,\Gamma_i)$ is saved in a separate group in named by respective index $i$, i.e., we have the following groups on root level of the hdf5 file: |
| 42 | +``` |
| 43 | +├─ 📂 1 |
| 44 | +├─ 📂 2 |
| 45 | +├─ 📂 3 |
| 46 | +│ : |
| 47 | +├─ 📂 N_obs |
| 48 | +``` |
| 49 | +Within each of these groups, the data of the respective atomic configuration $R_i$ and friction tensor $\Gamma_i$ are saved in the subgroups `atoms` and `friction_tensor`, respectively: |
| 50 | +``` |
| 51 | +├─ 📂 i # Index of data point |
| 52 | + ├─ 📂 atoms # Atom configuration data |
| 53 | + │ ├─ 🔢 atypes |
| 54 | + │ ├─ 🔢 cell |
| 55 | + │ │ └─ 🏷️ column_major |
| 56 | + │ ├─ 🔢 pbc |
| 57 | + │ └─ 🔢 positions |
| 58 | + │ └─ 🏷️ column_major |
| 59 | + └─ 📂 friction_tensor # Friction tensor data |
| 60 | + ├─ 🔢 ft_I |
| 61 | + ├─ 🔢 ft_J |
| 62 | + ├─ 🔢 ft_mask |
| 63 | + └─ 🔢 ft_val, |
| 64 | + └─ 🏷️ column_major |
| 65 | +``` |
| 66 | + |
| 67 | +[Datasets](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html) in the group `atoms` store the equivalent information provided by the attributes `positions`, `numbers`, `cell`, and `pbc` of [atoms objects](https://wiki.fysik.dtu.dk/ase/ase/atoms.html), i.e., |
| 68 | +an atomic configuration of N atoms is described by the following datasets contained in the group `atoms`: |
| 69 | +- `atypes` -- A one-dimensional Integer dataset of length N. The ith entry corresponds to the atomic element number of the ith atom in the configuration. (Note: `types` corresponds to the atoms attribute `numbers` in the ase.) |
| 70 | +- `cell` -- A two-dimensional Float64 dataset of size 3 x 3. |
| 71 | +- `pbc` -- A one-dimensional Integer array of length 3 indicating the periodicity properties of the xyz dimension, e.g., `pbc = [1,0,0]` describes periodic boundary conditions in x dimension and non-periodic boundary conditions in the y and z dimensions. |
| 72 | +- `positions` -- A two-dimensional Float64 dataset of size n N x 3. The ith column corresponds to the position of the ith atom in the configuration |
| 73 | + |
| 74 | +[Datasets](https://support.hdfgroup.org/documentation/hdf5/latest/_h5_d__u_g.html) in the group `friction_tensor` store the friction tensor as a N x N sparse matrix with 3x3 valued block entries, i.e., a friction tensor with m non-zero 3x3 blocks is stored |
| 75 | +- `ft_I` -- A one-dimensional Integer dataset of length m specifying the column indices of non-zero block entries of the friction tensor. |
| 76 | +- `ft_J` -- A one-dimensional Integer dataset of length m specifying the row indices of non-zero block entries of the friction tensor. |
| 77 | +- `ft_val` -- A three-dimensional Float64 dataset of size m x 3 x 3 specifying the values of the non-zero 3 x 3 block entries of the friction tensor. For example, the 3 x 3 array `ft_val[k,:,:]` corresponds to the 3 x 3 block entry of the friction tensor with column index `ft_I[k]`, and row index `ft_J[k]`. |
| 78 | +- `ft_mask` -- A one-dimensional Integer dataset/list containg the indices of atoms for which friction information is provided. |
| 79 | + |
| 80 | + |
| 81 | +!!! warning |
| 82 | + All two or three-dimensional datasets in the groups `atoms` and `friction_tensor` have an additional attribute `column_major`. If the hdf5 file is created in a language that stores matrices in column-major form (e.g., julia), this attribute must be set to 1 (True). If the hdf5 file is created in a language that stores matrices in column-major form (e.g., python), this attribute must be set to 0 (False). |
| 83 | + |
| 84 | + |
| 85 | + |
0 commit comments