From 65e70e94158ae53d37a1b5549479f49e8d821461 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 13:16:26 -0400
Subject: [PATCH 1/7] Improvements in Readme.

---
 README.md | 43 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 38 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 89bcf14e..0cc60bf5 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
-## [WIP] PotentialLearning.jl
 
-Composable Optimization Workflows for Fast and Accurate Interatomic Potentials. This package is part of a software suite developed for the [CESMIX](https://computing.mit.edu/cesmix/) project.
+## PotentialLearning.jl 
+
+Optimize your atomistic data and interatomic potential models in your molecular dynamics workflows.
 
 <!--<a href="https://cesmix-mit.github.io/PotentialLearning.jl/stable">
 <img alt="Stable documentation" src="https://img.shields.io/badge/documentation-stable%20release-blue?style=flat-square">
@@ -14,7 +15,39 @@ Composable Optimization Workflows for Fast and Accurate Interatomic Potentials.
 <a href="https://github.com/cesmix-mit/PotentialLearning.jl/issues/new">
 <img alt="Ask us anything" src="https://img.shields.io/badge/Ask%20us-anything-1abc9c.svg?style=flat-square">
 </a>
-<a href="https://github.com/cesmix-mit/PotentialLearning.jl/releases">
-<img alt="GitHub tag (latest SemVer pre-release)" src="https://img.shields.io/github/v/tag/cesmix-mit/PotentialLearning.jl?include_prereleases&label=latest%20version&logo=github&sort=semver&style=flat-square">
-</a>
+</a> 
+<br />
+<br />
+
+**Reduce expensive Density Functional Theory (DFT) calculations** while maintaining training accuracy by intelligently reducing your atomistic dataset.
+
+```julia
+# Reduce your atomistic dataset by intellegently comparing energy descriptors.
+ds = DataSet(conf_train .+ e_descr)
+dataset_selector = kDPP(ds, GlobalMean(), DotProduct())
+inds = get_random_subset(dataset_selector)
+conf_train = @views conf_train[inds]
+```
+
+***Get fast and accurate interatomic potential models*** through multi-objective hyper-parameter optimization.
+
+```julia
+# Define the interatomic potential model and hyper-parameter value ranges.
+model = ACE
+pars = OrderedDict( :body_order        => [2, 3, 4],
+                    :polynomial_degree => [3, 4, 5], ...)
+
+# Define your custom loss function: fitting accuracy and force calculations.
+function custom_loss(metrics::OrderedDict)
+    ...
+    return w_e * e_mae + w_f * f_mae + w_t * time_us
+end
+
+# Optimize the hyper-parameters.
+iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
+```
+
+
+**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments [CESMIX](https://computing.mit.edu/cesmix/). Massachusetts Institute of Technology (MIT).
+
 

From ed080e2d0331006027e25f60f1950a951ece0632 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 15:21:53 -0400
Subject: [PATCH 2/7] Improvements in readme

---
 README.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 0cc60bf5..5406a82a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 
 ## PotentialLearning.jl 
 
-Optimize your atomistic data and interatomic potential models in your molecular dynamics workflows.
+Optimize your atomistic data and interatomic potential models in your molecular dynamic workflows.
 
 <!--<a href="https://cesmix-mit.github.io/PotentialLearning.jl/stable">
 <img alt="Stable documentation" src="https://img.shields.io/badge/documentation-stable%20release-blue?style=flat-square">
@@ -19,17 +19,20 @@ Optimize your atomistic data and interatomic potential models in your molecular
 <br />
 <br />
 
-**Reduce expensive Density Functional Theory (DFT) calculations** while maintaining training accuracy by intelligently reducing your atomistic dataset.
+***Reduce expensive Density functional theory calculations*** while maintaining training accuracy by intelligently subsampling your atomistic dataset. Example: 
 
+1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)). See complete example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
 ```julia
-# Reduce your atomistic dataset by intellegently comparing energy descriptors.
 ds = DataSet(conf_train .+ e_descr)
 dataset_selector = kDPP(ds, GlobalMean(), DotProduct())
 inds = get_random_subset(dataset_selector)
 conf_train = @views conf_train[inds]
 ```
+2) Use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on the subsampled dataset.
 
-***Get fast and accurate interatomic potential models*** through multi-objective hyper-parameter optimization.
+We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and distributed parallelism; and optimal subsampler selection.
+
+***Get fast and accurate interatomic potential models*** through multi-objective hyper-parameter optimization. 
 
 ```julia
 # Define the interatomic potential model and hyper-parameter value ranges.
@@ -47,7 +50,4 @@ end
 iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
 ```
 
-
-**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments [CESMIX](https://computing.mit.edu/cesmix/). Massachusetts Institute of Technology (MIT).
-
-
+**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology (MIT).

From aecd3c34c9c105fb8ed3fa01fac003945ac2ec64 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 15:55:35 -0400
Subject: [PATCH 3/7] Improvements in readme

---
 README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 5406a82a..27fc0738 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,3 @@
-
 ## PotentialLearning.jl 
 
 Optimize your atomistic data and interatomic potential models in your molecular dynamic workflows.
@@ -19,35 +18,36 @@ Optimize your atomistic data and interatomic potential models in your molecular
 <br />
 <br />
 
-***Reduce expensive Density functional theory calculations*** while maintaining training accuracy by intelligently subsampling your atomistic dataset. Example: 
+**Reduce expensive ***Density functional theory*** calculations** while maintaining training accuracy by intelligently subsampling your atomistic dataset. 
 
-1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)). See complete example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
+1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
 ```julia
 ds = DataSet(conf_train .+ e_descr)
 dataset_selector = kDPP(ds, GlobalMean(), DotProduct())
 inds = get_random_subset(dataset_selector)
 conf_train = @views conf_train[inds]
 ```
-2) Use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on the subsampled dataset.
+2) Export the reduced dataset, use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on it, and fit your model.
+
+See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
 
 We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and distributed parallelism; and optimal subsampler selection.
 
-***Get fast and accurate interatomic potential models*** through multi-objective hyper-parameter optimization. 
+**Get fast and accurate interatomic potential models** through parallel multi-objective hyper-parameter optimization. 
 
+1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss functions. Then, optimize your model.
 ```julia
-# Define the interatomic potential model and hyper-parameter value ranges.
 model = ACE
 pars = OrderedDict( :body_order        => [2, 3, 4],
                     :polynomial_degree => [3, 4, 5], ...)
-
-# Define your custom loss function: fitting accuracy and force calculations.
 function custom_loss(metrics::OrderedDict)
     ...
     return w_e * e_mae + w_f * f_mae + w_t * time_us
 end
-
-# Optimize the hyper-parameters.
 iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
 ```
+2) Export optimal hyper-parameter values to your molecular dynamic workflow.
+
+See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
 
 **Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology (MIT).

From 28af525afb4a16591c7bab614fa6cab04924a7d2 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 16:43:53 -0400
Subject: [PATCH 4/7] Improvements in readme

---
 README.md | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 27fc0738..d29bfcbb 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Optimize your atomistic data and interatomic potential models in your molecular
 <br />
 <br />
 
-**Reduce expensive ***Density functional theory*** calculations** while maintaining training accuracy by intelligently subsampling your atomistic dataset. 
+**Reduce expensive ***Density functional theory*** calculations** while maintaining training accuracy by intelligently subsampling your atomistic dataset:
 
 1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
 ```julia
@@ -33,7 +33,7 @@ See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generat
 
 We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and distributed parallelism; and optimal subsampler selection.
 
-**Get fast and accurate interatomic potential models** through parallel multi-objective hyper-parameter optimization. 
+**Get fast and accurate interatomic potential models** through parallel multi-objective hyper-parameter optimization:
 
 1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss functions. Then, optimize your model.
 ```julia
@@ -46,8 +46,12 @@ function custom_loss(metrics::OrderedDict)
 end
 iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
 ```
-2) Export optimal hyper-parameter values to your molecular dynamic workflow.
+2) Export optimal values to your molecular dynamic workflow.
 
 See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
 
+The interatomic potential models are compatible with the flexible interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). 
+In particular, we are interested in maintaining compatibility with the ACE model of [ACESuit](https://github.com/ACEsuit) as well as integrating potentials based on [LAMMPS](https://www.lammps.org/) such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package).
+
+
 **Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology (MIT).

From 507cce3e43f3e9f648302aea748a017dc7121b1d Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 18:04:55 -0400
Subject: [PATCH 5/7] Improvements in readme and index

---
 README.md         | 28 ++++++++++++++-------
 docs/src/index.md | 62 ++++++++++++++++++++++++++++++++---------------
 2 files changed, 62 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index d29bfcbb..d39dbbb8 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@ Optimize your atomistic data and interatomic potential models in your molecular
 <br />
 <br />
 
-**Reduce expensive ***Density functional theory*** calculations** while maintaining training accuracy by intelligently subsampling your atomistic dataset:
+<ins>**Reduce expensive ***Density functional theory*** calculations**</ins>  while maintaining training accuracy by intelligently subsampling your atomistic dataset:
 
 1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
 ```julia
@@ -29,13 +29,13 @@ conf_train = @views conf_train[inds]
 ```
 2) Export the reduced dataset, use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on it, and fit your model.
 
-See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
 
-We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and distributed parallelism; and optimal subsampler selection.
+We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and [distributed parallelism](https://github.com/JuliaParallel/Dagger.jl); and optimal subsampler selection.
 
-**Get fast and accurate interatomic potential models** through parallel multi-objective hyper-parameter optimization:
+<ins>**Get fast and accurate interatomic potential models**</ins>  through parallel multi-objective hyper-parameter optimization:
 
-1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss functions. Then, optimize your model.
+1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss function. Then, [optimize](https://github.com/baggepinnen/Hyperopt.jl) your model.
 ```julia
 model = ACE
 pars = OrderedDict( :body_order        => [2, 3, 4],
@@ -48,10 +48,20 @@ iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
 ```
 2) Export optimal values to your molecular dynamic workflow.
 
-See example [here](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
 
-The interatomic potential models are compatible with the flexible interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). 
-In particular, we are interested in maintaining compatibility with the ACE model of [ACESuit](https://github.com/ACEsuit) as well as integrating potentials based on [LAMMPS](https://www.lammps.org/) such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package).
+The models are compatible with the interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). In particular, we are interested in maintaining compatibility with [ACESuit](https://github.com/ACEsuit), as well as integrating [LAMMPS](https://www.lammps.org/) based potentials such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package). We are also working to provide neural network potential architecture optimization.
 
+<ins>**Compress your interatomic potential data and model**</ins> using dimensionality reduction of energy and force descriptors:
+```julia
+pca = PCAState(tol = n_desc)
+fit!(ds_train, pca)
+transform!(ds_train, pca)
+```
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/PCA-ACE-aHfO2/fit-pca-ace-ahfo2/).
+
+We are working to provide feature selection of energy and force descriptors based on [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl).
+
+Additionally, this package includes utilities for loading input data (such as XYZ files), computing various metrics (including MAE, MSE, RSQ, and COV), exporting results, and generating plots.
 
-**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology (MIT).
+**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology ([MIT](https://www.mit.edu/)).
diff --git a/docs/src/index.md b/docs/src/index.md
index 2ba8b739..701170cc 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,28 +1,52 @@
-# [WIP] PotentialLearning.jl
+## PotentialLearning.jl 
 
-**Composable optimization workflows for fast and accurate interatomic potentials**. This package is part of a software suite developed for the [CESMIX](https://computing.mit.edu/cesmix/) project.
+Optimize your atomistic data and interatomic potential models in your molecular dynamic workflows.
 
 
-## Goals
+<ins>**Reduce expensive ***Density functional theory*** calculations**</ins>  while maintaining training accuracy by intelligently subsampling your atomistic dataset:
 
-**Optimize your atomistic data:** intelligent subsampling of large datasets to reduce DFT computations
-- Intelligent subsampling of atomistic configurations using algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl), etc.
-- Highly scalable parallel subsampling via hierarchical subsampling and distributed parallelism ([Dagger.jl](https://github.com/JuliaParallel/Dagger.jl)).
-- Optimal subsampler choosing via [Hyperopt.jl](https://github.com/baggepinnen/Hyperopt.jl).
+1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
+```julia
+ds = DataSet(conf_train .+ e_descr)
+dataset_selector = kDPP(ds, GlobalMean(), DotProduct())
+inds = get_random_subset(dataset_selector)
+conf_train = @views conf_train[inds]
+```
+2) Export the reduced dataset, use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on it, and fit your model.
 
-**Optimize your interatomic potential model:** hyperparameters, coefficients, model compression, and model selection.
-- Parallel optimization of hyperparameters, coefficients, and model selection 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).
-- Model compression via feature selection (e.g. [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl)) and dimensionality reduction (e.g [PCA](https://juliastats.org/MultivariateStats.jl/dev/pca/), Active Subspaces) of atomistic descriptors.
-- Fitting of linear potentials and inference of parameter uncertainties. Training of neural versions of [Julia-ACE](https://github.com/ACEsuit/ACE1.jl) and [LAMMPS-POD](https://docs.lammps.org/pair_pod.html).
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
 
-Additionally, this package provides utilities for 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.
+We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and [distributed parallelism](https://github.com/JuliaParallel/Dagger.jl); and optimal subsampler selection.
 
-## Leveraging Julia!
+<ins>**Get fast and accurate interatomic potential models**</ins>  through parallel multi-objective hyper-parameter optimization:
 
-- [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/).
+1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss function. Then, [optimize](https://github.com/baggepinnen/Hyperopt.jl) your model.
+```julia
+model = ACE
+pars = OrderedDict( :body_order        => [2, 3, 4],
+                    :polynomial_degree => [3, 4, 5], ...)
+function custom_loss(metrics::OrderedDict)
+    ...
+    return w_e * e_mae + w_f * f_mae + w_t * time_us
+end
+iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
+```
+2) Export optimal values to your molecular dynamic workflow.
 
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
+
+The models are compatible with the interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). In particular, we are interested in maintaining compatibility with [ACESuit](https://github.com/ACEsuit), as well as integrating [LAMMPS](https://www.lammps.org/) based potentials such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package). We are also working to provide neural network potential architecture optimization.
+
+<ins>**Compress your interatomic potential data and model**</ins> using dimensionality reduction of energy and force descriptors:
+```julia
+pca = PCAState(tol = n_desc)
+fit!(ds_train, pca)
+transform!(ds_train, pca)
+```
+See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/PCA-ACE-aHfO2/fit-pca-ace-ahfo2/).
+
+We are working to provide feature selection of energy and force descriptors based on [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl).
+
+Additionally, this package includes utilities for loading input data (such as XYZ files), computing various metrics (including MAE, MSE, RSQ, and COV), exporting results, and generating plots.
+
+**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology ([MIT](https://www.mit.edu/)).
\ No newline at end of file

From 1d8bf755f65d7beeb2fb8244df195723fde10473 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 18:14:53 -0400
Subject: [PATCH 6/7] Small improvements in make.jl and Na example.

---
 docs/make.jl                          | 26 ++++++++++++++++----------
 examples/DPP-ACE-Na/fit-dpp-ace-na.jl |  4 ++--
 2 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/docs/make.jl b/docs/make.jl
index 3c29f630..2814cfd6 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -35,31 +35,36 @@ end
 
 # Basic examples
 examples = [
-    "1 - Fit a-HfO2 dataset with ACE" => "ACE-aHfO2/fit-ace-ahfo2.jl",
-    "2 - Load Ar+Lennard-Jones dataset and postprocess" => "LJ-Ar/lennard-jones-ar.jl"
+    "Example 1 - Fit a-HfO2 dataset with ACE" => "ACE-aHfO2/fit-ace-ahfo2.jl",
 ]
 basic_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Subsampling examples
 examples = [
-    "1 - Subsample a-HfO2 dataset with DPP and fit with ACE" => "DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2.jl",
-    "2 - Subsample Na dataset with DPP and fit with ACE" => "DPP-ACE-Na/fit-dpp-ace-na.jl",
-    "3 - Subsample Si dataset with DPP, fit with ACE, and cross validate" => "DPP-ACE-Si/fit-dpp-ace-si.jl",
+    "Example 1 - Subsample a-HfO2 dataset with DPP and fit with ACE" => "DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2.jl",
+    "Example 2 - Subsample Na dataset with DPP and fit with ACE" => "DPP-ACE-Na/fit-dpp-ace-na.jl",
+    "Example 3 - Subsample Si dataset with DPP, fit with ACE, and cross validate" => "DPP-ACE-Si/fit-dpp-ace-si.jl",
 ]
 ss_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Optimization examples
 examples = [
-    "1 - Optimize ACE hyper-parameters: minimize force time and fitting error" => "Opt-ACE-aHfO2/fit-opt-ace-ahfo2.jl",
+    "Example 1 - Optimize ACE hyper-parameters: minimize force time and fitting error" => "Opt-ACE-aHfO2/fit-opt-ace-ahfo2.jl",
 ]
 opt_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Dimension reduction examples
 examples = [
-    "1 - Reduce ACE descriptors with PCA and fit a-HfO2 dataset" => "PCA-ACE-aHfO2/fit-pca-ace-ahfo2.jl",
+    "Example 1 - Reduce ACE descriptors with PCA and fit a-HfO2 dataset" => "PCA-ACE-aHfO2/fit-pca-ace-ahfo2.jl",
 ]
 dr_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
+examples = [
+    "Example 1 - Load Ar+Lennard-Jones dataset and postprocess" => "LJ-Ar/lennard-jones-ar.jl"
+]
+misc_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
+
+
 # Make and deploy docs #########################################################
 
 makedocs(
@@ -77,9 +82,10 @@ makedocs(
       pages = ["Home" => "index.md",
                "How to run the examples" => "how-to-run-the-examples.md",
                "Basic examples" => basic_examples,
-               "Optimize atomistic data via intelligent subsampling" => ss_examples,
-               "Optimize interatomic potential models via hyper-paramter optimization" => opt_examples,
-               "Optimize interatomic potential models via dimension reduction" => dr_examples,
+               "Intelligent subsampling" => ss_examples,
+               "Hyper-paramter optimization" => opt_examples,
+               "Dimension reduction" => dr_examples,
+               "Misc" => misc_examples,
                "API" => "api.md"],
       format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
diff --git a/examples/DPP-ACE-Na/fit-dpp-ace-na.jl b/examples/DPP-ACE-Na/fit-dpp-ace-na.jl
index db7b70b6..fa7918a8 100644
--- a/examples/DPP-ACE-Na/fit-dpp-ace-na.jl
+++ b/examples/DPP-ACE-Na/fit-dpp-ace-na.jl
@@ -46,12 +46,12 @@ dpp = kDPP(ds_train, GlobalMean(), DotProduct(); batch_size = 200)
 # Subsample trainig dataset.
 dpp_inds = get_random_subset(dpp)
 
-# ## Learn ACE coefficients based on ACE descriptors and DFT data.
+# ## e. Learn ACE coefficients based on ACE descriptors and DFT data.
 lb = LBasisPotential(ace)
 α = 1e-8
 Σ = learn!(lb, ds_train[dpp_inds], α)
 
-# ## e. Post-process output: calculate metrics, create plots, and save results.
+# ## f. Post-process output: calculate metrics, create plots, and save results.
 
 # Update test dataset by adding energy descriptors.
 println("Computing local descriptors of test dataset")

From ee70d68265945c2325a2903fc21c35368705c488 Mon Sep 17 00:00:00 2001
From: Emmanuel Lujan <lujan.emmanuel@gmail.com>
Date: Fri, 5 Jul 2024 18:55:35 -0400
Subject: [PATCH 7/7] Some documentation fixes and improvements.

---
 README.md         |  3 +++
 docs/make.jl      | 14 +++++++-------
 docs/src/index.md | 27 +++++++++++++++++++--------
 3 files changed, 29 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index d39dbbb8..d61f7b54 100644
--- a/README.md
+++ b/README.md
@@ -53,11 +53,14 @@ See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Op
 The models are compatible with the interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). In particular, we are interested in maintaining compatibility with [ACESuit](https://github.com/ACEsuit), as well as integrating [LAMMPS](https://www.lammps.org/) based potentials such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package). We are also working to provide neural network potential architecture optimization.
 
 <ins>**Compress your interatomic potential data and model**</ins> using dimensionality reduction of energy and force descriptors:
+1) Define a PCA state, fit PCA with your the energy and force descriptors of your dataset, and transform all dataset descriptors.
 ```julia
 pca = PCAState(tol = n_desc)
 fit!(ds_train, pca)
 transform!(ds_train, pca)
 ```
+2) Export PCA fitted data to be used in your workflow.
+
 See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/PCA-ACE-aHfO2/fit-pca-ace-ahfo2/).
 
 We are working to provide feature selection of energy and force descriptors based on [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl).
diff --git a/docs/make.jl b/docs/make.jl
index 2814cfd6..f508f6e5 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -35,32 +35,32 @@ end
 
 # Basic examples
 examples = [
-    "Example 1 - Fit a-HfO2 dataset with ACE" => "ACE-aHfO2/fit-ace-ahfo2.jl",
+    "Fit a-HfO2 dataset with ACE" => "ACE-aHfO2/fit-ace-ahfo2.jl",
 ]
 basic_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Subsampling examples
 examples = [
-    "Example 1 - Subsample a-HfO2 dataset with DPP and fit with ACE" => "DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2.jl",
-    "Example 2 - Subsample Na dataset with DPP and fit with ACE" => "DPP-ACE-Na/fit-dpp-ace-na.jl",
-    "Example 3 - Subsample Si dataset with DPP, fit with ACE, and cross validate" => "DPP-ACE-Si/fit-dpp-ace-si.jl",
+    "Subsample a-HfO2 dataset with DPP and fit with ACE" => "DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2.jl",
+    "Subsample Na dataset with DPP and fit with ACE" => "DPP-ACE-Na/fit-dpp-ace-na.jl",
+    "Subsample Si dataset with DPP, fit with ACE, and cross validate" => "DPP-ACE-Si/fit-dpp-ace-si.jl",
 ]
 ss_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Optimization examples
 examples = [
-    "Example 1 - Optimize ACE hyper-parameters: minimize force time and fitting error" => "Opt-ACE-aHfO2/fit-opt-ace-ahfo2.jl",
+    "Optimize ACE hyper-parameters: minimize force time and fitting error" => "Opt-ACE-aHfO2/fit-opt-ace-ahfo2.jl",
 ]
 opt_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 # Dimension reduction examples
 examples = [
-    "Example 1 - Reduce ACE descriptors with PCA and fit a-HfO2 dataset" => "PCA-ACE-aHfO2/fit-pca-ace-ahfo2.jl",
+    "Reduce ACE descriptors with PCA and fit a-HfO2 dataset" => "PCA-ACE-aHfO2/fit-pca-ace-ahfo2.jl",
 ]
 dr_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
 examples = [
-    "Example 1 - Load Ar+Lennard-Jones dataset and postprocess" => "LJ-Ar/lennard-jones-ar.jl"
+    "Load Ar+Lennard-Jones dataset and postprocess" => "LJ-Ar/lennard-jones-ar.jl"
 ]
 misc_examples = create_examples(examples, EXAMPLES_DIR, OUTPUT_DIR)
 
diff --git a/docs/src/index.md b/docs/src/index.md
index 701170cc..75390989 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -3,24 +3,29 @@
 Optimize your atomistic data and interatomic potential models in your molecular dynamic workflows.
 
 
-<ins>**Reduce expensive ***Density functional theory*** calculations**</ins>  while maintaining training accuracy by intelligently subsampling your atomistic dataset:
+### Reduce expensive Density functional theory calculations
 
-1) Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
+Reduce expensive Density functional theory calculations while maintaining training accuracy by intelligently subsampling your atomistic dataset:
+
+1 - Subsample your [atomistic configurations](https://github.com/JuliaMolSim/AtomsBase.jl) using a Determinantal Point Process ([DPP](https://github.com/dahtah/Determinantal.jl)) based algorithm that compares energy descriptors computed with the Atomic Cluster Expansion ([ACE](https://github.com/ACEsuit)).
 ```julia
 ds = DataSet(conf_train .+ e_descr)
 dataset_selector = kDPP(ds, GlobalMean(), DotProduct())
 inds = get_random_subset(dataset_selector)
 conf_train = @views conf_train[inds]
 ```
-2) Export the reduced dataset, use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on it, and fit your model.
+2 - Export the reduced dataset, use Density functional theory ([DFT](https://docs.dftk.org/stable/)) on it, and fit your model.
 
 See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/DPP-ACE-aHfO2-1/fit-dpp-ace-ahfo2/).
 
 We are working to provide different intelligent subsampling algorithms based on [DPP](https://github.com/dahtah/Determinantal.jl), [DBSCAN](https://docs.google.com/document/d/1SWAanEWQkpsbr2lqetMO3uvdX_QK-Z7dwrgPaM1Dl0o/edit), and [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl); highly scalable parallel subsampling via hierarchical subsampling and [distributed parallelism](https://github.com/JuliaParallel/Dagger.jl); and optimal subsampler selection.
 
-<ins>**Get fast and accurate interatomic potential models**</ins>  through parallel multi-objective hyper-parameter optimization:
 
-1) Define the interatomic potential model, hyper-parameter value ranges, and custom loss function. Then, [optimize](https://github.com/baggepinnen/Hyperopt.jl) your model.
+### Get fast and accurate interatomic potential models
+
+Get fast and accurate interatomic potential models through parallel multi-objective hyper-parameter optimization:
+
+1 - Define the interatomic potential model, hyper-parameter value ranges, and custom loss function. Then, [optimize](https://github.com/baggepinnen/Hyperopt.jl) your model.
 ```julia
 model = ACE
 pars = OrderedDict( :body_order        => [2, 3, 4],
@@ -31,22 +36,28 @@ function custom_loss(metrics::OrderedDict)
 end
 iap, res = hyperlearn!(model, pars, conf_train; loss = custom_loss);
 ```
-2) Export optimal values to your molecular dynamic workflow.
+2 - Export optimal values to your molecular dynamic workflow.
 
 See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/Opt-ACE-aHfO2/fit-opt-ace-ahfo2/).
 
 The models are compatible with the interfaces of our sister package [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl). In particular, we are interested in maintaining compatibility with [ACESuit](https://github.com/ACEsuit), as well as integrating [LAMMPS](https://www.lammps.org/) based potentials such as [ML-POD](https://docs.lammps.org/Packages_details.html#pkg-ml-pod) and [ML-PACE](https://docs.lammps.org/Packages_details.html#ml-pace-package). We are also working to provide neural network potential architecture optimization.
 
-<ins>**Compress your interatomic potential data and model**</ins> using dimensionality reduction of energy and force descriptors:
+### Compress your interatomic potential data and model
+
+Compress your interatomic potential data and model using dimensionality reduction of energy and force descriptors:
+
+1 - Define a PCA state, fit PCA with your the energy and force descriptors of your dataset, and transform all dataset descriptors.
 ```julia
 pca = PCAState(tol = n_desc)
 fit!(ds_train, pca)
 transform!(ds_train, pca)
 ```
+2 - Export PCA fitted data to be used in your workflow.
+
 See [example](https://cesmix-mit.github.io/PotentialLearning.jl/dev/generated/PCA-ACE-aHfO2/fit-pca-ace-ahfo2/).
 
 We are working to provide feature selection of energy and force descriptors based on [CUR](https://github.com/JuliaLinearAlgebra/LowRankApprox.jl).
 
 Additionally, this package includes utilities for loading input data (such as XYZ files), computing various metrics (including MAE, MSE, RSQ, and COV), exporting results, and generating plots.
 
-**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology ([MIT](https://www.mit.edu/)).
\ No newline at end of file
+**Acknowledgment:** Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)). Massachusetts Institute of Technology ([MIT](https://www.mit.edu/)).