Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update to documentation. #67

Merged
merged 2 commits into from
Jun 5, 2024
Merged

Update to documentation. #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aae2e04
First update to documentation.
emmanuellujan Jun 5, 2024
505f4ae
Update of index.md in documentation.
emmanuellujan Jun 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 14 additions & 9 deletions docs/make.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand All @@ -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",
Expand Down
28 changes: 11 additions & 17 deletions docs/src/how-to-run-the-examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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")
```

32 changes: 17 additions & 15 deletions docs/src/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Loading