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
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# License
GNU General Public License, Version 3, 29 June 2007

Copyright (C) 2019  Maximilian Schanner, GFZ Potsdam  
Copyright (C) 2019  Stefan Mauerberger, University of Potsdam

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
> Schanner, M. and Mauerberger, S.  (2019)  
> 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
30
# Documentation
Maximilian Schanner's avatar
Maximilian Schanner committed
31
The `CORBASS` model is described in TODO: #12. In  a way this
Maximilian Schanner's avatar
Maximilian Schanner committed
32
33
repository can be seen as supplementary material to this publication. Below this
section we give installation instructions.
Maximilian Schanner's avatar
Maximilian Schanner committed
34
35
36
37
38

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

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

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

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

Maximilian Schanner's avatar
Maximilian Schanner committed
54
This way the `CORBASS` posterior model coefficients, the NEZ- and DIF-field models
Maximilian Schanner's avatar
Maximilian Schanner committed
55
56
57
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
58
59
60
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
61
62
`integration` module. The output can then be used to calculate further results,
using the `evaluation` module.
Maximilian Schanner's avatar
Maximilian Schanner committed
63

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

[*examples* section]: (examples)
Maximilian Schanner's avatar
Maximilian Schanner committed
68

Maximilian Schanner's avatar
Maximilian Schanner committed
69
# Installation
70
71
72
73
74
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
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
102

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

   ```

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

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