Merge pull request #67 from cesmix-mit/update-doc

Update to documentation.

docs/make.jl

@@ -12,21 +12,25 @@ DocMeta.setdocmeta!(
     recursive = true,
 )
 
+
 bib = CitationBibliography(joinpath(@__DIR__, "citation.bib"))
 
 # Generate examples
 
-#const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
-#const OUTPUT_DIR = joinpath(@__DIR__, "src/generated")
+const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
+const OUTPUT_DIR   = joinpath(@__DIR__, "src/generated")
+
+examples = [
+    "Subsampling, compute descriptors, and fit ACE" => "Na/fit-dpp-ace-na"
+]
 
-#examples = Pair{String,String}[]
+for (_, name) in examples
+    example_filepath = joinpath(EXAMPLES_DIR, string(name, ".jl"))
+    Literate.markdown(example_filepath, OUTPUT_DIR, documenter=true)
+end
 
-#for (_, name) in examples
-#    example_filepath = joinpath(EXAMPLES_DIR, string(name, ".jl"))
-#    Literate.markdown(example_filepath, OUTPUT_DIR, documenter = true)
-#end
+examples = [title=>joinpath("generated", string(name, ".md")) for (title, name) in examples]
 
-#examples = [title => joinpath("generated", string(name, ".md")) for (title, name) in examples]
 
 makedocs(
       root    =  joinpath(dirname(pathof(PotentialLearning)), "..", "docs"),
@@ -39,9 +43,10 @@ makedocs(
       highlightsig = true,
       sitename = "PotentialLearning.jl",
       expandfirst = [],
-      draft = false,
+      draft = false,    
       pages = ["Home" => "index.md",
                "How to run the examples" => "how-to-run-the-examples.md",
+               "Examples" => examples,
                "API" => "api.md"],
       format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",

docs/src/how-to-run-the-examples.md

@@ -1,7 +1,6 @@
 # How to run the examples
 
 ## Add registries
-
 Open a Julia REPL (`$ julia`), type `]` to enter the Pkg REPL, and add the following registries:
 ```julia
     pkg> registry add https://github.com/JuliaRegistries/General
@@ -10,32 +9,27 @@ Open a Julia REPL (`$ julia`), type `]` to enter the Pkg REPL, and add the follo
     pkg> registry add https://github.com/ACEsuit/ACEregistry
 ```
 
-## Install the dependencies of the `examples` folder project
-
+## Clone repository and access an example folder
 Clone `PotentialLearning.jl` repository in your working directory.
 ```shell
     $ git clone [email protected]:cesmix-mit/PotentialLearning.jl.git
 ```
-Open a Julia REPL activating the `examples`  folder project.
-```shell
-    $ julia --project=PotentialLearning.jl/examples
-```
- Type `]` to enter the Pkg REPL and instantiate.
-```julia
-    pkg> instantiate
-```
-
-## Run an example
-
 Access to any folder within `PotentialLearning.jl/examples`. E.g.
 ```shell
-    $ cd PotentialLearning.jl/examples/ACE
+    $ cd PotentialLearning.jl/examples/Na
 ```
+
+## Run example
 Open a Julia REPL, activate the `examples` folder project, and define the number of threads.
 ```julia
-    $ julia --project=../ --threads=4
+    $ julia --project=./ --threads=4
+```
+Type `]` to enter the Pkg REPL and instantiate.
+```julia
+    pkg> instantiate
 ```
 Finally, include the example file.
 ```julia
-    julia> include("fit-ace.jl")
+    julia> include("fit-dpp-ace-na.jl")
 ```
+

docs/src/index.md

@@ -1,28 +1,30 @@
 # [WIP] PotentialLearning.jl
 
-An open source Julia library for active learning of interatomic potentials in atomistic simulations of materials. It incorporates elements of bayesian inference, machine learning, differentiable programming,  software composability, and high-performance computing. This package is part of a software suite developed for the [CESMIX](https://computing.mit.edu/cesmix/) project.
+An open source Julia library to enhance active learning of interatomic potentials in atomistic simulations of materials. It incorporates elements of bayesian inference, machine learning, differentiable programming,  software composability, and high-performance computing. This package is part of a software suite developed for the [CESMIX](https://computing.mit.edu/cesmix/) project.
 
 ## Specific goals
-- Intelligent data subsampling: iteratively query a large pool of unlabeled data to extract a minimum number of training data that would lead to a supervised ML model with superior accuracy compared to a training model with educated handpicking.
-    - Via [DPP](), [clustering](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit).
-- Quantity of Interest based dimension reduction through the theory of Active Subspaces.
-- Inference of the optimal values and uncertainties of the model parameters, to propagate them through the atomistic simulation.
-    - Interatomic potential hyper-parameter optimization. E.g.  estimation of the optimum cutoff radius.
-    - Interatomic potential fitting. The potentials addressed in this package are defined in [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl) and [InteratomicBasisPotentials.jl](https://github.com/cesmix-mit/InteratomicBasisPotentials.jl). E.g. ACE, SNAP, Neural Network Potentials.
-- Measurement of QoI sensitivity to individual parameters. 
-- Input data management and post-processing.
+
+- **Intelligent subsampling** of atomistic configurations via [DPP](https://github.com/dahtah/Determinantal.jl) and [clustering](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit)-based algorithms.
+- **Optimization of interatomic potentials**
+    - Parallel optimization of hyperparameters and coefficients via [Hyperopt.jl](https://github.com/baggepinnen/Hyperopt.jl).
+    - Multi-objective optimization (Pareto fronts): force execution time vs fitting accuracy (e.g. MAE of energies and forces).
+- **Neuralization of linear interatomic potentials**
+    - Neural version of [Julia-ACE](https://github.com/ACEsuit/ACE1.jl) and [LAMMPS-POD](https://docs.lammps.org/pair_pod.html).
+    - Integration with [Flux](https://fluxml.ai/Flux.jl/stable/) ecosystem.
+- **Interatomic potential compression**
+    - Feature selection (e.g. [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl)) and dimensionality reduction (e.g [PCA](https://juliastats.org/MultivariateStats.jl/dev/pca/)) of atomistic descriptors.
+- **Interatomic potential fitting/training**
+    - Inference of parameter uncertainties in linear interatomic potentials.
+- **Quantity of Interest (QoI) sensitivity** analysis of interatomic potential parameters.
+- **Dimension reduction of QoI** through the theory of Active Subspaces.
+- **Atomistic configuration and DFT data management and post-processing**
   - Process input data so that it is ready for training. E.g. read XYZ file with atomic configurations, linearize energies and forces, split dataset into training and testing, normalize data, transfer data to GPU, define iterators, etc.
   - Post-processing: computation of different metrics (MAE, RSQ, COV, etc), saving results, and plotting.
 
-
 ## Leveraging Julia!
+
 - [Software composability](https://julialang.org/) through [multiple dispatch](https://www.youtube.com/watch?v=kc9HwsxE1OY). A series of [composable workflows](https://github.com/cesmix-mit/AtomisticComposableWorkflows) is guiding our design and development. We analyzed three of the most representative workflows: classical molecular dynamics (MD), Ab initio MD, and classical MD with active learning. In addition, it facilitates the training of new  potentials defined by the composition of neural networks with state-of-the-art interatomic potential descriptors.
 - [Differentiable programming](https://fluxml.ai/blog/2019/02/07/what-is-differentiable-programming.html). Powerful automatic differentiation tools, such as [Enzyme](https://enzyme.mit.edu/julia/) or [Zygote](https://fluxml.ai/Zygote.jl/latest/), help to accelerate the development of new interatomic potentials by automatically calculating loss function gradients and forces.
 - [SciML](https://sciml.ai/): Open Source Software for Scientific Machine Learning. It provides libraries, such as [Optimization.jl](https://github.com/SciML/Optimization.jl), that bring together several optimization packages into one unified Julia interface. 
 - Machine learning and HPC abstractions: [Flux.jl](https://fluxml.ai/Flux.jl/stable/) makes parallel learning simple using the NVIDIA GPU abstractions of [CUDA.jl](https://cuda.juliagpu.org/stable/). Mini-batch iterations on heterogeneous data, as required by a loss function based on energies and forces, can be handled by [DataLoader.jl](https://fluxml.ai/Flux.jl/v0.10/data/dataloader/).
 
-
-## Examples
-
-See [AtomisticComposableWorkflows](https://github.com/cesmix-mit/AtomisticComposableWorkflows) repository. It aims to gather easy-to-use CESMIX-aligned case studies, integrating the latest developments of the Julia atomistic ecosystem with state-of-the-art tools.
-