README.md 3.6 KB
Newer Older
Michele Compostella's avatar
Michele Compostella committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# A software workflow for fingerprinting and visualizing defects in damaged crystal structures
---
#### Udo von Toussaint, F. J. Domı́nguez-Gutiérrez, Markus Rampp, Michele Compostella
###### Max-Planck-Institut für Plasmaphysik, Boltzmannstrasse 2, 85748 Garching, Germany
###### Max-Planck Computing and Data Facility, Giessenbachstrasse 2, 85748 Garching, Germany
---


## Introduction

This repository contains the recipe to create a Docker container where users can test the workflow for fingerprinting and visualizing defects in damaged crystal structures.

Together with the required software, data for the analysis of point defects in a bcc Fe sample are provided. This dataset was obtained by performing MD simulations to emulate neutron bombardment at a primary-knock on-atom of 10 keV.


## Requirements

In order to build the Docker image, the following software is required on the local machine:  

* tar
* curl
* wget
* git
Michele Compostella's avatar
Michele Compostella committed
24
* [docker](https://docs.docker.com/install/)
Michele Compostella's avatar
Michele Compostella committed
25
26
27
28
29
30
31

#### Important:
The workflow presented in this repository uses the GAP library for the software QUIP. When installing this software, you are accepting the [GAP license agreement](http://www.libatoms.org/gap/gap_download.html).


## Installation

Michele Compostella's avatar
Michele Compostella committed
32
33
34
35
36
Clone this repository to your local machine with
```shell
git clone https://gitlab.mpcdf.mpg.de/mcompo/favad.git
```

Michele Compostella's avatar
Michele Compostella committed
37
38
39
After cloning this repository, run the following command to create the Docker image  

```shell
Michele Compostella's avatar
Michele Compostella committed
40
cd favad
Michele Compostella's avatar
Michele Compostella committed
41
./build.sh
Michele Compostella's avatar
Michele Compostella committed
42
43
```

Michele Compostella's avatar
Michele Compostella committed
44
Note that building the Docker image requires root permission on the local machine.  
Michele Compostella's avatar
Michele Compostella committed
45
The build.sh script accepts additional optional parameters in order to automatically accept the [GAP license agreement](http://www.libatoms.org/gap/gap_download.html):
Michele Compostella's avatar
Michele Compostella committed
46
47

```shell
Michele Compostella's avatar
Michele Compostella committed
48
./build.sh "I accept" "FULL NAME" "EMAIL ADDRESS" "ORGANIZATION"
Michele Compostella's avatar
Michele Compostella committed
49
50
51
52
53
54
```
If these optional parameters are not specified, the build process will ask for them during runtime.


## How to run the Docker image

55
56
57
58
59
60
61
Once the Docker image has been created and the [Docker daemon is running](https://docs.docker.com/config/daemon/), you can create a local folder where the output files will be stored using, for example:

```shell
mkdir $HOME/favad_output/
```

Finally, shell into the Docker container mounting the created folder:
Michele Compostella's avatar
Michele Compostella committed
62

Michele Compostella's avatar
Michele Compostella committed
63
```shell
64
sudo docker run -t -i --volume $HOME/favad_output/:/home/favad/sample/output/ favad /bin/bash
Michele Compostella's avatar
Michele Compostella committed
65
```
Michele Compostella's avatar
Michele Compostella committed
66

67
Using the previous command, the ouput files generated inside the Docker container will be available in $HOME/faved_output/ of your local machine. Please note that the content of this folder will be overwritten, if the folder is not empty.
Michele Compostella's avatar
Michele Compostella committed
68
69
70

At this point you can run the workflow for fingerprinting and visualizing defects on the sample dataset inside the Docker container:
```shell
71
72
cd /home/favad/sample/
python3 FaVaD.py -p /home/favad/sample/parameters.txt
Michele Compostella's avatar
Michele Compostella committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
```

---

## Local Installation

In the 'assets' folder we provide a script for the installation of the entire software stack on a local machine (instead of inside a Docker container) running Ubuntu 18.04 LTS.  
In this case, you can run the installer using
```shell
./assets/installer.sh /local_installation_path/ "FULL NAME" "EMAIL ADDRESS" "ORGANIZATION"
```
By running the installer, you are accepting the [GAP license agreement](http://www.libatoms.org/gap/gap_download.html).


## How to run locally

If you installed the software stack locally, you can run the workflow for fingerprinting and visualizing defects on the sample dataset using
```shell
cd ./sample
Michele Compostella's avatar
Michele Compostella committed
92
python3 FaVaD.py -p ./parameters.txt
Michele Compostella's avatar
Michele Compostella committed
93
94
95
```
Note however that you are required to change the paths in the parameter.txt file to match the current location of the files and software executables.