update to documentation

docs/make.jl

@@ -29,8 +29,17 @@ makedocs(;
                 "Fitting an Electronic Friction Tensor" => "fitting-eft.md",
                 "Fitting a Dissipative Particle Dynamics Friction Model" => "fitting-mbdpd.md"
             ],
-        "Function Manual" => Any[
-            "function-manual.md",
+        # "Importing & Exporting Friction Data" => Any[
+        #         "data-import-export.md",
+        #     ],
+        # "Function Manual" => Any[
+        #     "function-manual.md"
+        # ]
+                "Function Manual" => Any[
+            "ACEfriction.FrictionModels" => "./function-manual/ACEfriction.FrictionModels.md",
+            "ACEfriction.MatrixModels" => "./function-manual/ACEfriction.MatrixModels.md",
+            "ACEfriction.FrictionFit" => "./function-manual/ACEfriction.FrictionFit.md",
+            "ACEfriction.DataUtils" => "./function-manual/ACEfriction.DataUtils.md"
         ]
     ]
     )

docs/src/data-import-export.md

@@ -0,0 +1,71 @@
+# Friction Data 
+
+To train a friction tensor model in ACEfriciton.jl, friction data 
+$D = (R_i,\Gamma_i)_{i=1}^{N_{\rm obs}}$ comprised of atomic configurations, $R_i$, and a friction tensors, $\Gamma_i$ is required. 
+
+`ACEfriction.jl` implements the structure `FrictionData` to store and manipulate single observations $(R_i,\Gamma_i)$ in the pre-training phase: 
+```julia
+struct FrictionData
+    atoms
+    friction_tensor
+    friction_indices
+end
+```
+where
+- `atoms` -- stores data of the atomic configuration ans is assumed to be of type `JuLIP.Atoms`,
+- `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,
+-`friction_indices` --  is a one-dimensional integer array, which contains all atom indices for which the friction tensor is defined.
+
+# Importing & Exporting Friction Data
+
+`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.
+
+
+# Custom HDF5 File Format for Friction Data
+
+The hierachical structure of such hdf5 files is as follows:
+
+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:
+```
+├─ 📂 1   
+├─ 📂 2  
+├─ 📂 3   
+│  :   
+├─ 📂 N_obs   
+```
+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: 
+```
+├─ 📂 i                        # Index of data point 
+   ├─ 📂 atoms                 # Atom configuration data
+   │  ├─ 🔢 atypes
+   │  ├─ 🔢 cell 
+   │  │  └─ 🏷️ column_major 
+   │  ├─ 🔢 pbc
+   │  └─ 🔢 positions
+   │     └─ 🏷️ column_major
+   └─ 📂 friction_tensor       # Friction tensor data
+      ├─ 🔢 ft_I               
+      ├─ 🔢 ft_J
+      ├─ 🔢 ft_mask
+      └─ 🔢 ft_val, 
+         └─ 🏷️ column_major
+```
+
+[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., 
+an atomic configuration of N atoms is described by the following datasets contained in the group `atoms`:
+- `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.)
+- `cell` -- A two-dimensional Float64 dataset of size 3 x 3. 
+- `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. 
+- `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 
+
+[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
+- `ft_I` -- A one-dimensional Integer dataset of length m specifying the column indices of non-zero block entries of the friction tensor.
+- `ft_J` -- A one-dimensional Integer dataset of length m specifying the row indices of non-zero block entries of the friction tensor.
+- `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]`. 
+- `ft_mask` -- A one-dimensional Integer dataset/list containg the indices of atoms for which friction information is provided. 
+
+
+!!! note
+    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).
+
+

docs/src/fitting-eft.md

@@ -3,7 +3,7 @@
 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. 
 
 ## Load Electronic Friction Tensor Data
-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].
+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).
 ```julia
 using ACEfriction
 # Load data 
@@ -12,8 +12,8 @@ rdata = ACEfriction.DataUtils.load_h5fdata( "./test/test-data-100.h5");
 n_train = Int(ceil(.8 * length(rdata)))
 n_test = length(rdata) - n_train
 # Partition data into train and test set and convert the data 
-fdata = Dict("train" => FrictionData.(rdata[1:n_train]), 
-            "test"=> FrictionData.(rdata[n_train+1:end]));
+fdata = Dict("train" => rdata[1:n_train], 
+            "test"=> rdata[n_train+1:end]);
 ```
 
 ## Specify the Friction Model
@@ -46,7 +46,7 @@ To train our model we first extract the parameters from the friction model, whic
 c=params(fm)                                
 ffm = FluxFrictionModel(c)
 ```
-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.
+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.
 ```julia
 flux_data = Dict( "train"=> flux_assemble(fdata["train"], fm, ffm; ),
                   "test"=> flux_assemble(fdata["test"], fm, ffm));

docs/src/fitting-mbdpd.md

@@ -34,8 +34,8 @@ The following code loads training and test data comprised of particle configurat
 rdata_train = ACEfriction.DataUtils.load_h5fdata("./examples/data/dpd-train-x.h5"); 
 rdata_test = ACEfriction.DataUtils.load_h5fdata("./examples/data/dpd-train-x.h5"); 
 
-fdata = Dict("train" => FrictionData.(rdata_train), 
-            "test"=> FrictionData.(rdata_test));
+fdata = Dict("train" => rdata_train, 
+            "test"=> rdata_test);
 (n_train, n_test) = length(fdata["train"]), length(fdata["test"])
 ```
 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: 

docs/src/function-manual/ACEfriction.DataUtils.md

@@ -0,0 +1,85 @@
+```@meta
+CurrentModule = ACEfriction.DataUtils
+```
+
+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.
+
+
+### [Friction Data representation](@id friction-data-representation)
+
+For pre-training storage and manipulation of friction data,
+`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$: 
+```julia
+struct FrictionData
+    atoms
+    friction_tensor
+    friction_indices
+end
+```
+where
+- `atoms` -- stores data of the atomic configuration ans is assumed to be of type `JuLIP.Atoms`,
+- `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,
+- `friction_indices` --  is a one-dimensional integer array, which contains all atom indices for which the friction tensor is defined.
+
+### Importing & Exporting Friction Data
+
+`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:
+
+```@docs
+save_h5fdata
+```
+
+```@docs
+load_h5fdata
+```
+
+
+### [Custom HDF5 File Format for Friction Data](@id costum-hdf5-format)
+
+The hierachical structure of such hdf5 files is as follows:
+
+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:
+```
+├─ 📂 1   
+├─ 📂 2  
+├─ 📂 3   
+│  :   
+├─ 📂 N_obs   
+```
+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: 
+```
+├─ 📂 i                        # Index of data point 
+   ├─ 📂 atoms                 # Atom configuration data
+   │  ├─ 🔢 atypes
+   │  ├─ 🔢 cell 
+   │  │  └─ 🏷️ column_major 
+   │  ├─ 🔢 pbc
+   │  └─ 🔢 positions
+   │     └─ 🏷️ column_major
+   └─ 📂 friction_tensor       # Friction tensor data
+      ├─ 🔢 ft_I               
+      ├─ 🔢 ft_J
+      ├─ 🔢 ft_mask
+      └─ 🔢 ft_val, 
+         └─ 🏷️ column_major
+```
+
+[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., 
+an atomic configuration of N atoms is described by the following datasets contained in the group `atoms`:
+- `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.)
+- `cell` -- A two-dimensional Float64 dataset of size 3 x 3. 
+- `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. 
+- `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 
+
+[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
+- `ft_I` -- A one-dimensional Integer dataset of length m specifying the column indices of non-zero block entries of the friction tensor.
+- `ft_J` -- A one-dimensional Integer dataset of length m specifying the row indices of non-zero block entries of the friction tensor.
+- `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]`. 
+- `ft_mask` -- A one-dimensional Integer dataset/list containg the indices of atoms for which friction information is provided. 
+
+
+!!! warning
+    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).
+
+
+

docs/src/function-manual/ACEfriction.FrictionFit.md

@@ -0,0 +1,23 @@
+```@meta
+CurrentModule = ACEfriction.FrictionFit
+```
+
+```@docs
+flux_assemble
+```
+```@docs    
+FluxFrictionModel
+```
+
+```@docs
+get_ids
+```
+```@docs
+l2_loss
+```
+```@docs
+weighted_l2_loss
+```
+```@docs
+weighted_l1_loss
+```

docs/src/function-manual.md → docs/src/function-manual/ACEfriction.FrictionModels.md

@@ -1,7 +1,3 @@
-# Function Manual (@id Function-Manual)
-
-## ACEfriction.FrictionModels.jl
-
 ```@meta
 CurrentModule = ACEfriction.FrictionModels
 ```
@@ -47,8 +43,3 @@ set_params!
 ```@docs
 set_zero!
 ```
-
-## ACEfriction.MatrixModels.jl
-
-
-## ACEfriction.FrictionFit.jl

docs/src/function-manual/ACEfriction.MatrixModels.md

@@ -0,0 +1,16 @@
+```@meta
+CurrentModule = ACEfriction.MatrixModels
+```
+
+```@docs
+RWCMatrixModel
+```
+```@docs
+PWCMatrixModel
+```
+```@docs
+OnsiteOnlyMatrixModel
+```
+```@docs
+mbdpd_matrixmodel
+```

docs/src/index.md

@@ -2,7 +2,7 @@
 
 The julia package `ACEfriction.jl` facilitates simulation and machine learning of configuration-dependent friction tensor models from data. The models are based on an equivariant Atomic Cluster Expansion (ACE) and, as such, are computationally highly efficient and size transferable. The underlying framework of model construction is described in detail in [Sachs et al., (2024)](@ref ACEfriction-paper).  
 
-For a quick start, we recommend reading the [Installation Instructions](installation.md) and the [Overview](overview.md) section, followed by the [Workflow Examples](fitting-eft.md). Detailed documentation of front-end-facing functions can be found in the [Function Manual](function-manual.md).  
+For a quick start, we recommend reading the [Installation Instructions](installation.md) and the [Overview](overview.md) section, followed by the [Workflow Examples](fitting-eft.md). Detailed documentation of front-end-facing functions can be found in the Function Manual.  
 
 
 ### [References](@id ACEfriction-paper)

examples/fit-ACEFrictionModel-new-ac.jl

@@ -93,6 +93,7 @@ set_params!(fm, params(ffm))
 
 at = fdata["test"][1].atoms
 @time Gamma(fm, at)
+G = Gamma(fm, at)
 @time Σ = Sigma(fm, at)
 @time Gamma(fm, Σ)
 @time randf(fm, Σ)

src/ACEfriction.jl

@@ -9,7 +9,6 @@ include("./atomcutoffs.jl")
 include("./matrixmodels/matrixmodels.jl")
 include("./frictionmodels.jl")
 include("./frictionfit/frictionfit.jl")
-
 include("./matrixmodelsutils.jl")
 
 import ACEfriction.FrictionModels: FrictionModel, Gamma, Sigma