README.md 4.43 KB
Newer Older
Maximilian Schanner's avatar
Maximilian Schanner committed
1
2
3
# CORBASS

### CORrelation Based Archeomagnetic SnapShot model
4
5
6
# License
GNU General Public License, Version 3, 29 June 2007

Maximilian Schanner's avatar
Maximilian Schanner committed
7
Copyright (C) 2019 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

CORBASS is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

CORBASS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

# Citation
Maximilian Schanner's avatar
Maximilian Schanner committed
23
> Schanner, Maximilian Arthus and Mauerberger, Stefan (2019)  
24
25
26
27
28
> CORBASS: CORrelation Based Archeomagnetic SnapShot model. V. 1.0.  
> GFZ Data Services. http://doi.org/10.5880/GFZ.2.3.2019.008 

[![DOI](https://img.shields.io/badge/DOI-10.5880%2FGFZ.2.3.2019.008-blue.svg)](http://doi.org/10.5880/GFZ.2.3.2019.008)

Maximilian Schanner's avatar
Maximilian Schanner committed
29
# Documentation
Maximilian Schanner's avatar
Maximilian Schanner committed
30
The `CORBASS` model is described in TODO: #12. In  a way this
Maximilian Schanner's avatar
Maximilian Schanner committed
31
32
repository can be seen as supplementary material to this publication. Below this
section we give installation instructions.
Maximilian Schanner's avatar
Maximilian Schanner committed
33
34
35
36
37

From an algorithmic point of view, `CORBASS` can be simplified in the following
flowchart:
```mermaid
graph LR;
38
  ParameterFile-->Exploration-->Integration-->Evaluation;
Maximilian Schanner's avatar
Maximilian Schanner committed
39
40
```

Maximilian Schanner's avatar
Maximilian Schanner committed
41
`CORBASS` uses parameter files, which include among other things a link to 
Maximilian Schanner's avatar
Maximilian Schanner committed
42
datasets, in a format similar to the [GEOMAGIA](http://geomagia.gfz-potsdam.de/) 
Maximilian Schanner's avatar
Maximilian Schanner committed
43
output. Thus a first step is to create such a file for your data. You can find
Maximilian Schanner's avatar
Maximilian Schanner committed
44
45
an [example](Example_Parfile.py)
in the [*examples* section].
Maximilian Schanner's avatar
Maximilian Schanner committed
46

Maximilian Schanner's avatar
Maximilian Schanner committed
47
Once you have a parameter file, the recommended way to run `CORBASS` is to use
Maximilian Schanner's avatar
Maximilian Schanner committed
48

Maximilian Schanner's avatar
Maximilian Schanner committed
49
```console
Maximilian Schanner's avatar
typo    
Maximilian Schanner committed
50
(CORBASS)$ python run.py <path/to/parfile.py>  
Maximilian Schanner's avatar
Maximilian Schanner committed
51
```
Maximilian Schanner's avatar
Maximilian Schanner committed
52

Maximilian Schanner's avatar
Maximilian Schanner committed
53
This way the `CORBASS` posterior model coefficients, the NEZ- and DIF-field models
Maximilian Schanner's avatar
Maximilian Schanner committed
54
55
56
and down component and intensity at the CMB are calculated and provided as `.txt`
files. The output location is specified in the parameter file.

Maximilian Schanner's avatar
Maximilian Schanner committed
57
58
59
Under the hood, `CORBASS` first explores the model parameter space by using the
`exploration` module. This way the region of interest, i.e. where the 
probability mass is concentrated, is found and can be accessed by the
60
61
`integration` module. The output can then be used to calculate further results,
using the `evaluation` module.
Maximilian Schanner's avatar
Maximilian Schanner committed
62

Maximilian Schanner's avatar
typo    
Maximilian Schanner committed
63
If you want to use the individual modules, you can find Jupyter notebooks for
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
64
each module in the [*examples* section].
Maximilian Schanner's avatar
Maximilian Schanner committed
65

66
[*examples* section]: examples
Maximilian Schanner's avatar
Maximilian Schanner committed
67

Maximilian Schanner's avatar
Maximilian Schanner committed
68
# Installation
69
70
71
72
73
0. Clone the repository 
   ```console
    $ git clone https://gitext.gfz-potsdam.de/arthus/corbass.git
   ```
   In the following `<corbass>` refers to the path you cloned the `CORBASS` repository into.
Maximilian Schanner's avatar
Maximilian Schanner committed
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

1. Download and install [Miniconda](https://conda.io/miniconda.html) for Python 3.
   By default, the installation directory `<conda>` is `~/miniconda3/`.  
   If you let conda modify your `bash.rc`, `<conda>/bin/conda` may be replaced by
   `conda`.

2. Build and install [FieldTools]

   1. Install `conda-build` (to base)
   ```console
   $ <conda>/bin/conda install conda-build
   ```

   2. Navigate to `<corbass>` and build [FieldTools]
   ```console
   $ <conda>/bin/conda build FieldTools
   ```

3. Create the virtual environment `CORBASS`
   ```console
   $ <conda>/bin/conda env create -f corbass.yml
   ```

4. Activate the virtual environment
   ```console
   $ source <conda>/bin/activate CORBASS
   ```

Maximilian Schanner's avatar
Maximilian Schanner committed
102
103
   Careful with tcshell, you have to use activate.csh.  
   When you are done, deactivate the environment by
Maximilian Schanner's avatar
Maximilian Schanner committed
104
   ```console
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
105
   (CORBASS)$ conda deactivate
Maximilian Schanner's avatar
Maximilian Schanner committed
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

   ```

5. Install optional packages, for example
   ```console
   (CORBASS)$ conda install ipython jupyter notebook
   ```

6. If [corbass.yml](corbass.yml) changes, you are recommended to update your environment:
   ```console
   $ <conda>/bin/conda env update -f corbass.yml
   ```

[FieldTools]: https://gitup.uni-potsdam.de/matusche/fieldtools

Maximilian Schanner's avatar
Maximilian Schanner committed
121
# Contact
Maximilian Schanner's avatar
Maximilian Schanner committed
122
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)  
Maximilian Schanner's avatar
Maximilian Schanner committed
123
124
125
126
127
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ  
Section 2.3: Geomagnetism  
Telegrafenberg  
14473 Potsdam, Germany

Maximilian Schanner's avatar
Maximilian Schanner committed
128
* [Stefan Mauerberger](mailto:mauerber@uni-potsdam.de)  
Maximilian Schanner's avatar
Maximilian Schanner committed
129
Institut of mathematics  
Maximilian Schanner's avatar
Maximilian Schanner committed
130
University of Potsdam  
Maximilian Schanner's avatar
Maximilian Schanner committed
131
132
Campus Golm, Haus 9  
Karl-Liebknecht-Str. 24-25  
Maximilian Schanner's avatar
Maximilian Schanner committed
133
14476 Potsdam OT Golm, Germany