README.md 7.26 KB
Newer Older
Maximilian Schanner's avatar
Maximilian Schanner committed
1
# pymagglobal
Maximilian Schanner's avatar
Maximilian Schanner committed
2

3
4
5
**python interface for global geomagnetic field models**

[[_TOC_]]
Maximilian Schanner's avatar
Maximilian Schanner committed
6

Maximilian Schanner's avatar
Maximilian Schanner committed
7
pymagglobal serves the purpose of replacing some Fortran scripts, which are used in the geomagnetism community to evaluate global field models.  
Maximilian Schanner's avatar
Maximilian Schanner committed
8
9
It can be applied to all cubic-spline based geomagnetic field models stored in the same file format as gufm1 or the CALSxk model series. However, care has to be taken that two header lines of the model files are formatted correctly and the list of spline knot point epochs starts only in line 3. The first header line has to contain start and end epoch of the model as the first two numbers, any further information in that line is ignored. The second header line has to start with three integers, which are the maximum spherical harmonic degree, a dummy that actually is not used, and the number of splines.  
By default, pymagglobal includes several models. Use
Maximilian Schanner's avatar
Maximilian Schanner committed
10
11
12
```console
$ pymagglobal --list-models
```
13
to get a list of these default models or go to [pymagglobal/dat](https://gitext.gfz-potsdam.de/arthus/pymagglobal/-/tree/master/pymagglobal/dat) for further information. Using
Maximilian Schanner's avatar
Maximilian Schanner committed
14
```console
15
$ pymagglobal ... <path/to/your_model>
Maximilian Schanner's avatar
Maximilian Schanner committed
16
```
17
you can use pymagglobal to evaluate your own models, if they come in a similar format. `<path/to/your_model>` specifies the path to your model and is given instead of the name an included model. You can download additional models [here](TODO: PROVIDE MODELS VIA FTP) and use them as above.
Maximilian Schanner's avatar
Maximilian Schanner committed
18

Maximilian Schanner's avatar
typo    
Maximilian Schanner committed
19
Once installed, pymagglobal can be imported and its routines used to access the models from inside your own python code.
Maximilian Schanner's avatar
Maximilian Schanner committed
20

21
## License
Maximilian Schanner's avatar
Maximilian Schanner committed
22
23
GNU General Public License, Version 3, 29 June 2007

24
Copyright (C) 2020 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany
Maximilian Schanner's avatar
Maximilian Schanner committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38

pymagglobal 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.

pymagglobal 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/>.

39
## Citation
Maximilian Schanner's avatar
Maximilian Schanner committed
40
41
TODO

42
## Documentation
Maximilian Schanner's avatar
Maximilian Schanner committed
43
Check out the extended documention [here](http://arthus.gitext.gfz-potsdam.de/pymagglobal). From the command line, you can use pymagglobal to get various results from the models. For example,
44
```console
Maximilian Schanner's avatar
Maximilian Schanner committed
45
$ pymagglobal dipole gufm1
46
```
Maximilian Schanner's avatar
Maximilian Schanner committed
47
will give a plot of the dipole moment time series for the model gufm1. In general, pymagglobal is called as
48
49
50
51
52
```console
$  pymagglobal command --options model
```
where `command` specifies the quantity you want to get from pymagglobal and `model` is the respective model. You can use 
```console
53
$ pymagglobal command --options <path/to/your_model>
54
55
```
to parse your own model, if it is in a format similar to gufm1. Use
Maximilian Schanner's avatar
Maximilian Schanner committed
56
57
58
```console
$ pymagglobal --help
```
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
to get further information. Each command has its own help, so you may also use
```console
$ pymagglobal dipole --help
```
to get information on the options for the dipole time series.

When using `python` you can import the pymagglobal package and access the models directly:
```python
import pymagglobal
```
Using the function `file2splines` you can get a spline object, representing the model. For example, to get a spline object for gufm1, use
```python
gufm1_splines = pymagglobal.file2splines(pymagglobal.models['gufm1'])
```
This object can be evaluated to get the coefficients for a specific epoch
```python
gufm1_1600 = gufm1_splines(1600)
```
or passed to other routines in pymagglobal. For example, to get the dipole series from above use
```python
import numpy as np
Maximilian Schanner's avatar
Maximilian Schanner committed
80

81
82
83
times = np.linspace(1590, 1990, 201)
gufm1_dipoles = pymagglobal.dipole_series(times, gufm1_splines)
```
84
## Installation
Maximilian Schanner's avatar
Maximilian Schanner committed
85
86
87
88
89
90
91
92
93
94
pymagglobal is built and installed using [conda](https://www.anaconda.com/).

0. Clone the repository 
   ```console
    $ git clone https://gitext.gfz-potsdam.de/arthus/pymagglobal.git
   ```
   In the following `<pymagglobal>` refers to the path you cloned the `pymagglobal` repository into.

1. Download and install [Miniconda](https://conda.io/miniconda.html) for Python 3 
   By default, the installation directory `<conda>` is `~/miniconda3/`.  
95
   If you do not allow conda to modify your `bash.rc`, `conda` has to be replaced by `<conda>/bin/conda`. This may cause `install.sh` to fail.  
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
96
   You may want to create a fresh environment for pymagglobal. This is done using
Maximilian Schanner's avatar
Maximilian Schanner committed
97
   ```console
98
   $ conda create --name Your_Environment
Maximilian Schanner's avatar
Maximilian Schanner committed
99
100
101
   ```
   followed by
   ```console
102
   $ conda activate Your_Environment
Maximilian Schanner's avatar
Maximilian Schanner committed
103
104
105
106
107
108
   ```
   Careful: With tcshell, you have to use activate.csh.
   

2. Install `conda-build`
   ```console
109
   $ conda install conda-build
Maximilian Schanner's avatar
Maximilian Schanner committed
110
   ```
111
112
113
114
115

With `conda-build` installed, you may go to `<pymagglobal>` and run 
```console
$ bash install.sh
```
Maximilian Schanner's avatar
Maximilian Schanner committed
116
which will do the next steps for you. If `install.sh` fails or you want to do the steps by hand:
117

Maximilian Schanner's avatar
Maximilian Schanner committed
118
119
120
121
122
3. Build [FieldTools]  
   This step will make the pyfield library available via the local conda channel.

   Navigate to `<pymagglobal>` and build [FieldTools]
   ```console
123
   $ conda build FieldTools
Maximilian Schanner's avatar
Maximilian Schanner committed
124
125
126
   ```

4. Build pymagglobal  
127
   Navigate to `<pymagglobal>` and build pymagglobal
Maximilian Schanner's avatar
Maximilian Schanner committed
128
   ```console
129
   $ conda build ./
Maximilian Schanner's avatar
Maximilian Schanner committed
130
131
132
   ```
5. Install pymagglobal  
   ```console
133
   $ conda install pymagglobal -c local
Maximilian Schanner's avatar
Maximilian Schanner committed
134
135
136
137
138
139
140
141
142
143
144
145
   ```
   This will make `pymagglobal` available as a python package, i.e. you can use
   ```python
   import pymagglobal
   ```
   as well as register a shell command in your local environmet, so that you can run
   ```console
   $ pymagglobal --help
   ```

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

146
## Contact
Maximilian Schanner's avatar
Maximilian Schanner committed
147
148
149
150
151
152
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)  
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ  
Section 2.3: Geomagnetism  
Telegrafenberg  
14473 Potsdam, Germany

153
## References
Maximilian Schanner's avatar
Maximilian Schanner committed
154
pymagglobal uses `numpy`, `scipy`, `matplotlib`, `cartopy` and `pyfield`:
Maximilian Schanner's avatar
Maximilian Schanner committed
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

[\[scipy\]](https://www.scipy.org/) Pauli Virtanen, Ralf Gommers, Travis E. Oliphant, Matt Haberland,  
Tyler Reddy, David Cournapeau, Evgeni Burovski, Pearu Peterson,   
Warren Weckesser, Jonathan Bright, Stéfan J. van der Walt, Matthew Brett,  
Joshua Wilson, K. Jarrod Millman, Nikolay Mayorov, Andrew R. J. Nelson,   
Eric Jones, Robert Kern, Eric Larson, CJ Carey, İlhan Polat, Yu Feng,  
Eric W. Moore, Jake VanderPlas, Denis Laxalde, Josef Perktold, Robert Cimrman,  
Ian Henriksen, E.A. Quintero, Charles R Harris, Anne M. Archibald,  
Antônio H. Ribeiro, Fabian Pedregosa, Paul van Mulbregt,  
and SciPy 1.0 Contributors (2020)  
"SciPy 1.0: Fundamental Algorithms for Scientific Computing in Python".  
Nature Methods, in press.

[\[matplotlib\]](https://matplotlib.org/)  J. D. Hunter (2007)  
"Matplotlib: A 2D Graphics Environment",  
Computing in Science & Engineering, vol. 9, no. 3, pp. 90-95

[\[cartopy\]](https://scitools.org.uk/cartopy) Met Office (2015)  
173
"Cartopy: a cartographic python library with a Matplotlib interface"
Maximilian Schanner's avatar
Maximilian Schanner committed
174

175
176
[\[pyfield\]](https://gitup.uni-potsdam.de/matusche/fieldtools) Matuschek, H. and Mauerberger, S. (2019)  
FieldTools - A toolbox for manipulating vector fields on the sphere  
Maximilian Schanner's avatar
Maximilian Schanner committed
177
178
GFZ Data Services. 10.5880/fidgeo.2019.033