You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
To train a friction tensor model in ACEfriciton.jl, friction data
4
+
$D = (R_i,\Gamma_i)_{i=1}^{N_{\rm obs}}$ comprised of atomic configurations, $R_i$, and a friction tensors, $\Gamma_i$ is required.
5
+
6
+
`ACEfriction.jl` implements the structure `FrictionData` to store and manipulate single observations $(R_i,\Gamma_i)$ in the pre-training phase:
7
+
```julia
8
+
struct FrictionData
9
+
atoms
10
+
friction_tensor
11
+
friction_indices
12
+
end
13
+
```
14
+
where
15
+
-`atoms` -- stores data of the atomic configuration ans is assumed to be of type `JuLIP.Atoms`,
16
+
-`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,
17
+
-`friction_indices` -- is a one-dimensional integer array, which contains all atom indices for which the friction tensor is defined.
18
+
19
+
# Importing & Exporting Friction Data
20
+
21
+
`ACEfriction.DataUtils` implements the function [`save_h5fdata(rdata::Vector{FrictionData}, filename::String)`](@ref) to save arrays of friction data to a custom costum formatted `hdf5` file, as well as the function [`load_h5fdata(filename::String)`](@ref) to load friction data from such costum formatted `hdf5` files.
22
+
23
+
24
+
# Custom HDF5 File Format for Friction Data
25
+
26
+
The hierachical structure of such hdf5 files is as follows:
27
+
28
+
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:
29
+
```
30
+
├─ 📂 1
31
+
├─ 📂 2
32
+
├─ 📂 3
33
+
│ :
34
+
├─ 📂 N_obs
35
+
```
36
+
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:
37
+
```
38
+
├─ 📂 i # Index of data point
39
+
├─ 📂 atoms # Atom configuration data
40
+
│ ├─ 🔢 atypes
41
+
│ ├─ 🔢 cell
42
+
│ │ └─ 🏷️ column_major
43
+
│ ├─ 🔢 pbc
44
+
│ └─ 🔢 positions
45
+
│ └─ 🏷️ column_major
46
+
└─ 📂 friction_tensor # Friction tensor data
47
+
├─ 🔢 ft_I
48
+
├─ 🔢 ft_J
49
+
├─ 🔢 ft_mask
50
+
└─ 🔢 ft_val,
51
+
└─ 🏷️ column_major
52
+
```
53
+
54
+
[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.,
55
+
an atomic configuration of N atoms is described by the following datasets contained in the group `atoms`:
56
+
-`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.)
57
+
-`cell` -- A two-dimensional Float64 dataset of size 3 x 3.
58
+
-`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.
59
+
-`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
60
+
61
+
[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
62
+
-`ft_I` -- A one-dimensional Integer dataset of length m specifying the column indices of non-zero block entries of the friction tensor.
63
+
-`ft_J` -- A one-dimensional Integer dataset of length m specifying the row indices of non-zero block entries of the friction tensor.
64
+
-`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]`.
65
+
-`ft_mask` -- A one-dimensional Integer dataset/list containg the indices of atoms for which friction information is provided.
66
+
67
+
68
+
!!! note
69
+
All two or three-dimensional datasets in the groups `atoms` 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).
Copy file name to clipboardExpand all lines: docs/src/fitting-eft.md
+34-6Lines changed: 34 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
In this workflow example we demonstrate how `ACEfriction.jl` can be used to fit a simple 6 x 6 Electronic friction tensor modeling the non-adiabitic interactions of a hydrogen-atom on a copper surface.
4
4
5
5
## Load Electronic Friction Tensor Data
6
-
We first use the function [load_h5fdata]() to load the data of friction tensors from a [custom-formated]() hdf5 file and convert the data to the internal data format [FrictionData].
6
+
We first use the function [load_h5fdata](@ref) to load the data of friction tensors from a [custom-formated](@ref costum-hdf5-format) hdf5 file and convert the data to the internal data format [FrictionData](@ref friction-data-representation).
Next, we specify the matrix models that will make up our friction model. In this case we only specify the single matrix model `m_equ`, which being of the type `RWCMatrixModel` is based on a row-wise coupling.
20
+
Next, we specify the matrix models that will make up our friction model. In this case we only specify the single matrix model `m_equ`, which being of the type [RWCMatrixModel](@ref) is based on a row-wise coupling. Alternative code for building a friction model with a pairwise coupling [PWCMatrixModel](@ref) is provided in [the last of section of this working example](@ref fitting-pairwise-coupling).
The first argument, `property`, of the constructor, `RWCMatrixModel`, specifies the equivariance symmetry of blocks. Here, `property` is of type `EuclideanMatrix` specifying each block to transform like an Euclidean Matrix. In this modeling application, only hydrogen atoms feel friction, which we specify by setting the second argument `species_friction` to `[:H]`. Yet, the friction felt by an hydrogen atom is affected by the presence of both hydrogen atoms and copper atoms in its vicinty, which we specify by setting `species_env` to `[:H, :Cu]`. Furthermore, the physics is such that hydrogen models only feel friction if they are in contact with the metal surface. We specify this by setting `species_substrat = [:Cu]`. For further details and information on the remaining optional arguments see the docomentation of the constructor of [RWCMatrixModel]().
32
+
The first argument, `property`, of the constructor, `RWCMatrixModel`, specifies the equivariance symmetry of blocks. Here, `property` is of type `EuclideanMatrix` specifying each block to transform like an Euclidean Matrix. In this modeling application, only hydrogen atoms feel friction, which we specify by setting the second argument `species_friction` to `[:H]`. Yet, the friction felt by an hydrogen atom is affected by the presence of both hydrogen atoms and copper atoms in its vicinty, which we specify by setting `species_env` to `[:H, :Cu]`. Furthermore, the physics is such that hydrogen models only feel friction if they are in contact with the metal surface. We specify this by setting `species_substrat = [:Cu]`. For further details and information on the remaining optional arguments see the docomentation of the constructor of [RWCMatrixModel](@ref).
33
33
34
34
Next we build a friction model from the matrix model(s),
35
35
```julia
@@ -46,7 +46,7 @@ To train our model we first extract the parameters from the friction model, whic
46
46
c=params(fm)
47
47
ffm =FluxFrictionModel(c)
48
48
```
49
-
Next, the function `flux_assemble` is used to prepare data for training. This includes evaluating the ACE-basis functions of the matrix models in `fm` on all configurations in the data set. Since the loss function of our model is quartic polynomial in the parameters, we don't need to reevaluate the ACE-basis functions at later stages of the training process.
49
+
Next, the function [`flux_assemble`]() is used to prepare data for training. This includes evaluating the ACE-basis functions of the matrix models in `fm` on all configurations in the data set. Since the loss function of our model is quartic polynomial in the parameters, we don't need to reevaluate the ACE-basis functions at later stages of the training process.
@@ -119,4 +119,32 @@ The diffusion coefficient matrix $\Sigma$ can also be used to efficiently genera
119
119
R =randf(fm,Σ)
120
120
```
121
121
122
+
## [Friction Model with a Pairwise Coupling](@id fitting-pairwise-coupling)
123
+
Instead of using a row-wise coupling, we can also use a pair-wise coupling to construct a friction model. The following code produces a friction model with a pair-wise coupling:
Here the training data is contains friction tensors of 50 configurations each comprised of 64 particles, and the test data contains friction tensors of 10 configurations each comprised of 216 particles. The underlying friction tensors were synthetically generated using the following simple friction model, which is a smooth version of the standard heuristic DPD friction models commonly used in simulations:
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).
0 commit comments