Docs update for ML models and scattering at surfaces

docs/Project.toml

@@ -3,15 +3,14 @@ ASEconvert = "3da9722f-58c2-4165-81be-b4d7253e8fd2"
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 AtomsIO = "1692102d-eeb4-4df9-807b-c9517f998d44"
 ComponentArrays = "b0b7db55-cfe3-40fc-9ded-d10e2dbeff66"
-CubeLDFAModel = "56146587-2a70-4d59-809c-88d5ba27a8d3"
 DiffEqBase = "2b5f629d-d688-5b77-993f-72d75c75574e"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-NNInterfaces = "07253886-9aba-4a5d-b3d5-29b8b100a664"
+FrictionProviders = "0e168e98-d76b-4d03-b07e-2b13986b2fd0"
 NQCBase = "78c76ebc-5665-4934-b512-82d81b5cbfb7"
 NQCDistributions = "657014a1-bd25-4aa2-92cb-cbcede0310ad"
 NQCDynamics = "36248dfb-79eb-4f4d-ab9c-e29ea5f33e14"

docs/make.jl

@@ -1,7 +1,7 @@
 using Documenter
 using DocumenterCitations
 using NQCBase, NQCModels, NQCDistributions, NQCDynamics
-using CubeLDFAModel, NNInterfaces
+using FrictionProviders
 
 bib = CitationBibliography(joinpath(@__DIR__, "references.bib"))
 
@@ -15,7 +15,7 @@ end
 @time makedocs(;
     plugins=[bib],
     sitename="NQCDynamics.jl",
-    modules=[NQCDynamics, NQCDistributions, NQCModels, NQCBase, CubeLDFAModel],
+    modules=[NQCDynamics, NQCDistributions, NQCModels, NQCBase, FrictionProviders],
     doctest=false,
     format=Documenter.HTML(
         prettyurls=get(ENV, "CI", nothing) == "true",
@@ -33,7 +33,7 @@ end
             "NQCModels/overview.md"
             "NQCModels/analyticmodels.md"
             "NQCModels/ase.md"
-            "NQCModels/neuralnetworkmodels.md"
+            "NQCModels/machinelearningmodels.md"
             "NQCModels/frictionmodels.md"
         ]
         "NQCDistributions.jl" => Any[

docs/src/NQCModels/ase.md

@@ -56,7 +56,7 @@ derivative(model, rand(3, 2))
     the `get_potential_energy` and `get_forces` functions. For instance, you can use
     [SchNetPack (SPK)](https://github.com/atomistic-machine-learning/schnetpack) by
     passing their ASE calculator to the `AdiabaticASEModel`.
-    Take a look at [Neural network models](@ref) to learn more.
+    Take a look at [machine learning models](@ref ml-pes-models) to learn more.
 ```@setup logging
 runtime = round(time() - start_time; digits=2)
 @info "...done after $runtime s."

docs/src/NQCModels/frictionmodels.md

@@ -6,40 +6,32 @@ start_time = time()
 
 To perform [molecular dynamics with electronic friction (MDEF)](@ref mdef-dynamics)
 a specific type of model must be used
-that provides the friction tensor used to propagate the dynamics.
+that provides the friction tensor used to propagate the dynamics. For this we recommend using [FrictionProviders.jl](https://github.com/NQCD/FrictionProviders.jl), however, various analytic models can also be employed.
 
 As detailed in the [MDEF page](@ref mdef-dynamics), there are two ways to obtain friction
 values, either from the local density friction approximation (LDFA), or from time-dependent
-perturbation theory (TDPT).
+perturbation theory (TDPT), also known as orbital-dependent friction (ODF).
 The models on this page describe our existing implementations.
 
-## Analytic models
+## [FrictionProviders.jl](@id friction-providers)
 
-Since *ab initio* friction calculations are often expensive it is useful to
-have some models that we can use to test different friction methods.
-The [`DiabaticFrictionModel`](@ref NQCModels.DiabaticModels.DiabaticFrictionModel)
-is the abstract type that groups together the diabatic models for which electronic friction can be evaluated.
-These have many electronic states, modelling the electronic structure characteristic of a metal. 
-The friction is calculated for these models directly from the nonadiabatic couplings
-with the equation:
-```math
-γ = 2\pi\hbar \sum_j <1|dH|j><j|dH|1> \delta(\omega_j) / \omega_j
-```
-where the delta function is approximated by a normalised Gaussian function and the sum
-runs over the adiabatic states ([Box2021](@cite)).
-The matrix elements in this equation are the position derivatives of the diabatic hamiltonian
-converted to the adiabatic representation.
+Machine learning-based models, and cube-based calculators can called through [FrictionProviders.jl](https://github.com/NQCD/FrictionProviders.jl) connector package.
 
-!!! warning
+Currently, [FrictionProviders.jl](https://github.com/NQCD/FrictionProviders.jl) supports
+LDFA (density) models based on:
+- Cube electronic densities
+- (ACEpotentials.jl)[https://github.com/ACEsuit/ACEpotentials.jl]
+- (Scikit-learn)[https://github.com/scikit-learn/scikit-learn]
 
-    The analytic friction models and the equation above are experimental and subject to change.
+TDPT (ODF) friction models based on:
+- (ACEds.jl)[https://github.com/ACEsuit/ACEds.jl]
+
+The use of [FrictionProviders.jl](https://github.com/NQCD/FrictionProviders.jl) with LDFA (Cube calculator and ACE model), and TDPT (ACEds-based model) is explained on the [reactive scattering example](@ref example-h2scattering), to investigate the scattering of a diatomic molecule from a metal surface.
 
-## [CubeLDFAModel.jl](@id models-cubeldfa)
+### [Density models for LDFA](@id models-ldfa)
 
-Our LDFA implementation is given in
-[CubeLDFAModel.jl](https://github.com/NQCD/CubeLDFAModel.jl)
-which takes a `.cube` file containing the electron density and evaluates the friction based
-upon this local density.
+Our Cube-LDFA implementation takes a `.cube` file containing the electron density, whereas the ML-LDFA models predict the density directly.
+In both cases the obtained local density is then used to evaluate the friction.
 
 The model works by fitting the LDA data provided by [Gerrits2020](@cite) that provides
 the LDFA friction coefficient as a function of the Wigner-Seitz radius.
@@ -62,18 +54,25 @@ This graph shows how we interpolate the LDA data and evaluate the friction coeff
 as a function of the Wigner-Seitz radius.
 ![ldfa graph](../assets/figures/ldfa_graph.png)
 
-The [reactive scattering example](@ref example-h2scattering) uses this model to investigate
-the scattering of a diatomic molecule from a metal surface.
 
-## NNInterfaces.jl
-
-Another way to perform MDEF simulations is the use one of the models from
-[`NNInterfaces.jl`](https://github.com/NQCD/NNInterfaces.jl/) that uses a neural network
-to obtain the time-dependent perturbation theory friction from the atomic positions.
-As with LDFA, one of these models is used in the
-[reactive scattering example](@ref example-h2scattering).
+## Analytic models
 
-```@setup logging
-runtime = round(time() - start_time; digits=2)
-@info "...done after $runtime s."
+Since *ab initio* friction calculations are often expensive it is useful to
+have some models that we can use to test different friction methods.
+The [`DiabaticFrictionModel`](@ref NQCModels.DiabaticModels.DiabaticFrictionModel)
+is the abstract type that groups together the diabatic models for which electronic friction can be evaluated.
+These have many electronic states, modelling the electronic structure characteristic of a metal. 
+The friction is calculated for these models directly from the nonadiabatic couplings
+with the equation:
+```math
+γ = 2\pi\hbar \sum_j <1|dH|j><j|dH|1> \delta(\omega_j) / \omega_j
 ```
+where the delta function is approximated by a normalised Gaussian function and the sum
+runs over the adiabatic states ([Box2021](@cite)).
+The matrix elements in this equation are the position derivatives of the diabatic hamiltonian
+converted to the adiabatic representation.
+
+!!! warning
+
+    The analytic friction models and the equation above are experimental and subject to change.
+

docs/src/NQCModels/machinelearningmodels.md

@@ -0,0 +1,53 @@
+```@setup logging
+@info "Expanding src/NQCModels/machinelearningmodels.md..."
+start_time = time()
+```
+# [Machine learning interatomic potentials](@id ml-pes-models)
+
+Using the ASE interface within (NQCModels.jl)[https://github.com/NQCD/NQCModels.jl] we can directly use models trained e.g. using [MACE](https://github.com/ACEsuit/mace).
+
+To use a MACE model, please load any pre-trained model into a given path you can access.
+
+First we load the model into an `ase` calculator and attach it to our diatomic
+hydrogen molecule.
+```julia
+using PyCall
+
+ase = pyimport("ase")
+mace_calc = pyimport("mace.calculators")
+
+h2 = ase.Atoms("H2", [(0, 0, 0), (0, 0, 0.74)])
+
+calculator = mace_calc.MACECalculator(model_path="../assets/mace/h2cu.model", device="cpu", default_dtype="float32")
+h2.set_calculator(calculator)
+```
+
+We can obtain the energies and forces from `ase` directly in the usual way, converting
+them to atomic units using [UnitfulAtomic](https://github.com/sostock/UnitfulAtomic.jl).
+```julia-repl
+using Unitful, UnitfulAtomic;
+austrip(h2.get_total_energy() * u"eV")
+austrip.(h2.get_forces() .* u"eV/Å")
+```
+
+!!! warning
+
+    Note that this is an arbitrary model not trained on H2, hence the calculation of the
+    potential energy and forces most likely do not make sense.
+
+Then, we can convert the ASE output into the format used in NQCModels,
+which makes it possible to use the MACE model e.g. for molecular dynamics calculations
+within NQCDynamics.jl:
+```julia-repl
+using NQCModels;
+model = AdiabaticASEModel(h2);
+
+r = [0 0; 0 0; 0 ustrip(auconvert(0.74u"Å"))]
+
+potential(model, r)
+derivative(model, r)
+```
+```@setup logging
+runtime = round(time() - start_time; digits=2)
+@info "...done after $runtime s."
+```

docs/src/dynamicssimulations/dynamicsmethods/mdef.md

@@ -108,7 +108,7 @@ cubic Spline functions. The Wigner-Sietz radius is connected to the metal substr
 ```
 
 In this way, the electron density associated with the current substrate atom position is used to compute the respective friction coefficient through fitting function for each point of the trajectory.
-Visit the [CubeLDFAModel.jl](@ref models-cubeldfa) to learn more about how this is evaluated.
+Visit the [FrictionProviders.jl](@ref models-friction) to learn more about how this is evaluated.
 
 ## Time-dependent Perturbation theory (TDPT)