|
1 | 1 | # [WIP] Atomistic Composable Workflows |
2 | 2 |
|
3 | | -The Center for the Exascale Simulation of Materials in Extreme Environments ([CESMIX](https://computing.mit.edu/cesmix/)) is a new MIT research effort to advance the state-of-the-art in predictive simulation. It seeks to connect quantum and molecular simulations of materials with state-of-the-art programming languages, compiler technologies, and software performance engineering tools, underpinned by rigorous approaches to statistical inference and uncertainty quantification. |
4 | | - |
5 | | -This repository 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. This is a work in progress and is not ready for production, however some of our examples can already be used. |
6 | | - |
7 | | -## Atomistic composable workflows |
8 | | - |
9 | | -A series of composable workflows is guiding our design and development. We analyzed three of the most representative workflows: classical MD, Ab initio MD, and classical MD with active learning. |
10 | | - |
11 | | -<img src="composable_workflows.png" alt="Composable workflows" width="75%" /> |
12 | | - |
13 | | -- CW1 describes the software components and relationships of a classical MD simulation. Essentially, at each time step, the force associated with each atom is calculated based on the interatomic potential, and then used to calculate each new atomic position. |
14 | | -The correct functioning of the calculators is analyzed and reported, via the curved arrow components to the dynamics model or control component. E.g. a UQ analysis is performed on the force and MD calculations so that the control module can take corrective action. |
15 | | -In addition, a composable design must guarantee the communication of all the processes, for this purpose "wrapper" components, represented by small circles in the figure, are included in the design. The wrappers are key in this design because they allow heterogeneous software to coexist in the same workflow. Each wrapper implements a set of interfaces associated with a particular component. |
16 | | -- CW2 depicts an Ab initio MD process. It is mostly analogous to the workflow described above, but in this case the force calculation is provided by a DFT simulation. |
17 | | -- CW3 presents a combination of the latter workflows. Here, potentials/forces are fitted with respect to the data generated by the DFT simulator. The fitting process is complex and therefore requires a dedicated software component, as well as analysis of its inputs in terms of error, sensitivity, etc. Furthermore, the dynamics model component, based on the analysis of the potential, forces and molecular dynamics, can re-fit these forces in a process called active learning. |
18 | | - |
19 | | -## Atomistic suite for CESMIX in Julia |
20 | | - |
21 | | -This composable approach allowed us to characterize each software component involved, which can be associated with one or more atomistic tools, as well as their interactions with other components. In particular, an increasing number of Julia packages dedicated to atomistic simulations are currently being developed. These packages combine the dynamic and interactive nature of Julia with its high-performance capabilities. |
22 | | - |
23 | | -<img src="workflow3.png" alt="Componsable workflow 3" width="75%"/> |
24 | | - |
25 | | - |
26 | | -- [AtomsBase.jl](https://github.com/JuliaMolSim/AtomsBase.jl) is a lightweight abstract interface for representation of atomic geometries. It helps in the operability of diverse atomistic tools. Furthermore, [AtomIO.jl](https://github.com/mfherbst/AtomIO.jl) is a standard IO package for atomic structures integrating with FileIO, AtomsBase, and others. |
27 | | -- [DFTK.jl](https://docs.dftk.org/stable/), the density-functional toolkit, is a library for playing with plane-wave density-functional theory (DFT) algorithms. In its basic formulation it solves periodic Kohn-Sham equations. |
28 | | -- [InteratomicPotentials.jl](https://github.com/cesmix-mit/InteratomicPotentials.jl) and [InteratomicBasisPotentials.jl](https://github.com/cesmix-mit/InteratomicBasisPotentials.jl) are responsible for providing the methods to calculate the energies, forces and virial tensors of the potentials that we use in CESMIX. |
29 | | -- [PotentialLearning.jl](https://github.com/cesmix-mit/PotentialLearning.jl) aims to facilitate the learning/fitting of interatomic potentials and forces, ensuring fast execution, leveraging state-of-the-art tools. The code of this tool will be refactored in the near future. |
30 | | -- [Atomistic.jl](https://github.com/cesmix-mit/Atomistic.jl) provides an integrated workflow for MD simulations. |
31 | | -- [LAMMPS.jl](https://github.com/cesmix-mit/LAMMPS.jl) provides the bindings to the LAMMPS API, allowing other modules to access interatomic potentials, such as SNAP. |
32 | | - |
33 | | - |
34 | | - |
35 | | -## Case studies |
36 | | - |
37 | | -Listed here is a subset of the case studies we are developing. We are gradually adding new cases as well as improving and increasing the complexity of the current ones. |
38 | | - |
39 | | -| CW | Type | DFT | UQ | Fitting/ Learning | Potential / Forces | Molecular Dynamics | Location | |
40 | | -|:--:|:-------------------------:|:----------------:|:--:|:-----------------:|:----------------------------------------------:|:-----------------------:|-------------------| |
41 | | -| 1 | Ar | | ✓ | ✓ | InteratomicPotentials.jl → Lennard Jones / ACE | LAMMPS.jl → LAMMPS | Current repo | |
42 | | -| 1 | Ar | | ✓ | ✓ | InteratomicPotentials.jl → LennardJones / ACE | Atomistic.jl → Molly.jl | Current repo | |
43 | | -| 1 | Ar | | | | InteratomicPotentials.jl → LennardJones | Atomistic.jl → Molly.jl | [Atomistic.jl repo](https://github.com/cesmix-mit/Atomistic.jl/blob/main/examples/argon/molly_lj_simulation.jl) | |
44 | | -| 1 | Na | | | | LAMMPS.jl → EAM | LAMMPS.jl → LAMMPS | Current repo | |
45 | | -| 3 | Na | DFTK.jl | ✓ | ✓ | InteratomicPotentials.jl → SNAP / ACE | LAMMPS.jl → LAMMPS | Current repo | |
46 | | -| 3 | HfO2 , a-HfO2, TiO2, etc. | Multiple sources | | ✓ | InteratomicPotentials.jl → ACE | Atomistic.jl → Molly.jl | Current repo | |
47 | | - |
48 | | -Atomistic.jl also provides abstractions for using NBodySimulator.jl, however we are currently focusing on Molly.jl, which provides more flexibility. |
49 | | - |
50 | | -Examples of use can be found on the websites or github repositories of each tool mentioned. |
51 | | - |
52 | | - |
53 | | -## Example: Fit different DFT datasets using ACE, run multiple serial/parallel fitting experiments, and run an MD simulation. |
54 | | - |
55 | | -In the folder `ACE`, you will find a basic integrated example that allows you to fit DFT datasets with ACE and run an MD simulation. |
56 | | - |
57 | | -### Chose a DFT dataset |
58 | | - |
59 | | -Choose a DFT dataset. Currently, this code accepts either two `xyz` files, one for training and one for testing, or a single `xyz` file, which is automatically split into training and testing. Example datasets can be downloaded from the following urls. |
60 | | - |
61 | | -- a-HfO2 dataset: "Machine-learned interatomic potentials by active learning: |
62 | | - amorphous and liquid hafnium dioxide". Ganesh Sivaraman, |
63 | | - Anand Narayanan Krishnamoorthy, Matthias Baur, Christian Holm, |
64 | | - Marius Stan, Gábor Csányi, Chris Benmore & Álvaro Vázquez-Mayagoitia. |
65 | | - DOI: 10.1038/s41524-020-00367-7. |
66 | | - [Dataset url](https://github.com/argonne-lcf/active-learning-md/tree/master/data) |
67 | | -- FitSNAP: A Python Package For Training SNAP Interatomic Potentials for use in the LAMMPS molecular dynamics package. [Datasets url](https://github.com/FitSNAP/FitSNAP/tree/master/examples) |
68 | | -- CESMIX training data repository. [Datasets url](https://github.com/cesmix-mit/TrainingData) |
69 | | - |
70 | | - |
71 | | -### Fit ACE |
72 | | - |
73 | | -The input parameters are listed below: |
74 | | - |
75 | | -| Input parameter | Description | E.g. | |
76 | | -|----------------------|-----------------------------------------------------------|---------------------| |
77 | | -| experiment_path | Experiment path | TiO2/ | |
78 | | -| dataset_path | Dataset path | data/ | |
79 | | -| trainingset_filename | Training datasets filename | TiO2trainingset.xyz | |
80 | | -| testset_filename | Test datasets filename | TiO2testset.xyz | |
81 | | -| n_train_sys | No. of atomic configurations in training dataset | 80 | |
82 | | -| n_test_sys | No. of atomic configurations in test dataset | 20 | |
83 | | -| n_body | Body order | 3 | |
84 | | -| max_deg | Maximum polynomial degree | 3 | |
85 | | -| r0 | An estimate on the nearest-neighbour distance for scaling | 1.0 | |
86 | | -| rcutoff | Outer cutoff radius | 5.0 | |
87 | | -| wL | See run-experiments.jl | 1.0 | |
88 | | -| csp | See run-experiments.jl | 1.0 | |
89 | | -| w_e | Energy weight | 1.0 | |
90 | | -| w_f | Force weight | 1.0 | |
91 | | - |
92 | | -Run fitting process |
93 | | - |
94 | | -``` |
95 | | -$ julia fit-ace.jl experiment_path TiO2/ \ |
96 | | - dataset_path data/ \ |
97 | | - trainingset_filename TiO2trainingset.xyz \ |
98 | | - testset_filename TiO2testset.xyz \ |
99 | | - n_train_sys 80 \ |
100 | | - n_test_sys 20 \ |
101 | | - n_body 3 \ |
102 | | - max_deg 3 \ |
103 | | - r0 1.0 \ |
104 | | - rcutoff 5.0 \ |
105 | | - wL 1.0 \ |
106 | | - csp 1.0 \ |
107 | | - w_e 1.0 \ |
108 | | - w_f 1.0 |
109 | | -``` |
110 | | - |
111 | | -In addition, you can run the experiments with the default parameters (the parameters shown above). |
112 | | - |
113 | | -```bash |
114 | | -$ julia fit-ace.jl |
115 | | -``` |
116 | | - |
117 | | - |
118 | | -### Run multiple fitting experiments in serial/parallel using the wrapper to ACE1.jl in InteratomicBasisPotentials.jl |
119 | | - |
120 | | -Modify the file `run-experiments.jl` to specify the parameter ranges needed to generate the experiments. E.g. |
121 | | -```julia |
122 | | -# Parallel execution. Warning: a high number of parallel experiments may degrade system performance. |
123 | | -parallel = true |
124 | | - |
125 | | -# n_body: body order. N: correlation order (N = n_body - 1) |
126 | | -n_body = 2:5 |
127 | | - |
128 | | -# max_deg: maximum polynomial degree |
129 | | -max_deg = 3:6 |
130 | | -``` |
131 | | - |
132 | | -Run the script: |
133 | | - |
134 | | -```bash |
135 | | -$ julia run-experiments.jl |
136 | | -``` |
137 | | - |
138 | | -Each experiment is run in a separate process (using `nohup` to facilitate its execution in a cluster). |
139 | | -The results are stored in the folder `experiments/`. |
140 | | -After all experiments have been completed, run the following script to gather the results into a single csv. |
141 | | - |
142 | | -```shell |
143 | | -$ ./gather-results.sh |
144 | | -``` |
145 | | - |
146 | | -### Run an MD simulation using the wrapper to Molly.jl or NBodySimulator.jl in Atomistic.jl |
147 | | - |
148 | | -```bash |
149 | | -$ run-md-ahfo2-ace-nbs.jl |
150 | | -``` |
151 | | -or |
152 | | -```bash |
153 | | -$ run-md-ahfo2-ace-molly.jl |
154 | | -``` |
155 | | -(Note: currently there is a bug in the second script) |
156 | | - |
157 | | - |
158 | | - |
159 | | -## Installation |
160 | | - |
161 | | -#### Install Julia on Ubuntu |
162 | | - |
163 | | -1. Open terminal and download Julia from https://julialang.org/downloads/ |
164 | | - ```bash |
165 | | - $ wget https://julialang-s3.julialang.org/bin/linux/x64/1.7/julia-1.7.3-linux-x86_64.tar.gz |
166 | | - ``` |
167 | | -2. Extract file |
168 | | - ```bash |
169 | | - $ tar xvzf julia-1.7.3-linux-x86_64.tar.gz |
170 | | - ``` |
171 | | -3. Copy to `/opt` and create link |
172 | | - ```bash |
173 | | - $ sudo mv ./julia-1.7.3 /opt/ |
174 | | - $ sudo ln -s /opt/julia-1.7.3/bin/julia /usr/local/bin/julia |
175 | | - ``` |
176 | | -4. Alternative: add line to `.bashrc` |
177 | | - ```bash |
178 | | - $ nano .bashrc |
179 | | - PATH=$PATH:/home/youruser/julia-1.7.3 /bin/ |
180 | | - ``` |
181 | | -5. Restart the terminal |
182 | | - |
183 | | -#### Add registries and install dependencies |
184 | | - |
185 | | -1. Open a Julia REPL |
186 | | - ```bash |
187 | | - $ julia |
188 | | - ``` |
189 | | -2. Add registries: General, CESMIX, and MolSim |
190 | | - ```bash |
191 | | - pkg> registry add https://github.com/JuliaRegistries/General |
192 | | - pkg> registry add https://github.com/cesmix-mit/CESMIX.git |
193 | | - pkg> registry add https://github.com/JuliaMolSim/MolSim.git |
194 | | - ``` |
195 | | -3. Install general packages your workflow is likely to require. E.g. |
196 | | - ```bash |
197 | | - pkg> add LinearAlgebra |
198 | | - pkg> add StaticArrays |
199 | | - pkg> add UnitfulAtomic |
200 | | - pkg> add Unitful |
201 | | - pkg> add Flux |
202 | | - pkg> add Optimization |
203 | | - pkg> add OptimizationOptimJL |
204 | | - pkg> add BenchmarkTools |
205 | | - pkg> add Plots |
206 | | - ``` |
207 | | -4. Install CESMIX packages |
208 | | - ```bash |
209 | | - pkg> add AtomsBase |
210 | | - pkg> add InteratomicPotentials |
211 | | - pkg> add InteratomicBasisPotentials |
212 | | - pkg> add https://github.com/cesmix-mit/PotentialLearning.jl |
213 | | - pkg> add Atomistic |
214 | | - ``` |
215 | | -5. Install other important dependencies |
216 | | - - MD simulators |
217 | | - ``` |
218 | | - pkg> add Molly |
219 | | - pkg> add NBodySimulator |
220 | | - ``` |
221 | | - - ACE (see: https://acesuit.github.io/ACE.jl/dev/gettingstarted/#Installation) |
222 | | - ```bash |
223 | | - pkg> add PyCall IJulia |
224 | | - pkg> add ACE |
225 | | - pkg> add JuLIP ASE ACEatoms |
226 | | - pkg> add IPFitting |
227 | | - ``` |
228 | | - |
| 3 | +This repository 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. This is a work in progress, but some of our examples can already be used. |
| 4 | + |
| 5 | + |
| 6 | +<!--<a href="https://cesmix-mit.github.io/AtomisticComposableWorkflows/stable"> |
| 7 | +<img alt="Stable documentation" src="https://img.shields.io/badge/documentation-stable%20release-blue?style=flat-square"> |
| 8 | +</a>--> |
| 9 | +<a href="https://cesmix-mit.github.io/AtomisticComposableWorkflows/dev"> |
| 10 | +<img alt="Development documentation" src="https://img.shields.io/badge/documentation-in%20development-orange?style=flat-square"> |
| 11 | +</a> |
| 12 | +<a href="https://mit-license.org"> |
| 13 | +<img alt="MIT license" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square"> |
| 14 | +</a> |
| 15 | +<a href="https://github.com/cesmix-mit/AtomisticComposableWorkflows/issues/new"> |
| 16 | +<img alt="Ask us anything" src="https://img.shields.io/badge/Ask%20us-anything-1abc9c.svg?style=flat-square"> |
| 17 | +</a> |
0 commit comments