README.md 8.04 KB
Newer Older
1
2
3
4
5
6
<!--
SPDX-FileCopyrightText: 2020 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)

SPDX-License-Identifier: CC0-1.0
-->

Maximilian Schanner's avatar
Maximilian Schanner committed
7
# pymagglobal
Maximilian Schanner's avatar
Maximilian Schanner committed
8

9
10
11
**python interface for global geomagnetic field models**

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

13
14
`pymagglobal` serves the purpose of replacing some Fortran scripts, which are used in the geomagnetism community to evaluate global field models. 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
15
16
17
```console
$ pymagglobal --list-models
```
18
to get a list of these default models or go to [pymagglobal/dat](https://gitext.gfz-potsdam.de/sec23/korte/pymagglobal/-/tree/master/pymagglobal/dat) for further information. Using
Maximilian Schanner's avatar
Maximilian Schanner committed
19
```console
20
$ pymagglobal ... <path/to/your_model>
Maximilian Schanner's avatar
Maximilian Schanner committed
21
```
22
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 of an included model. You can download additional models [here](ftp://ftp.gfz-potsdam.de/home/mag/arthus/pymagglobal_models/) and use them as above.
Maximilian Schanner's avatar
Maximilian Schanner committed
23

24
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
25

26
27
28
## Citation
TODO

29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
## Installation
> **Note:** pymagglobal depends on [cartopy](https://scitools.org.uk/cartopy). You have to install it, before running the install command.  
> This should also help if you receive `ImportError: NumPy 1.10+ is required to install cartopy.`

`pymagglobal` is distributed via the PyPI registry of this repository. It can be installed using
```console
$ pip install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@gitext.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple
```

Since [conda](https://docs.conda.io/) version 4.6, conda and pip get along well. So you can also run `pip install ...` from inside your conda environment.

Another way to use `pymagglobal` is via nix-shell. With [nix](https://nixos.org/download.html) installed, simply run
```console
$ nix-shell
```
from within the `pymagglobal` root directory. You may also use the nix-expression [pymagglobal.nix] to include `pymagglobal` in your own environments.

46
## Documentation
47
Check out the extended documention [here](https://sec23.gitext-pages.gfz-potsdam.de/korte/pymagglobal). From the command line, you can use `pymagglobal` to get various results from the models. For example,
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
```console
$ pymagglobal dipole gufm1
```
will give a plot of the dipole moment time series for the model gufm1. In general, pymagglobal is called as
```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
$ pymagglobal command --options <path/to/your_model>
```
to parse your own model, if it is in a format similar to gufm1. Use
```console
$ pymagglobal --help
```
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
```
73
74
75
76
We can first use `built_in_models`, to access a dictionary of available models:
```python
models = built_in_models()
```
77
78
Using the function `file2splines` you can get a spline object, representing the model. For example, to get a spline object for gufm1, use
```python
79
gufm1_splines = pymagglobal.file2splines(models['gufm1'])
80
81
82
83
84
85
86
87
88
89
90
91
92
93
```
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

times = np.linspace(1590, 1990, 201)
gufm1_dipoles = pymagglobal.dipole_series(times, gufm1_splines)
```
Additionally, pymagglobal provides a `Model` class, which is set up with a path and a name:
```python
94
gufm1 = pymagglobal.Model('gufm1', models['gufm1'])
95
96
97
98
99
100
101
102
103
```
The object now contains several quantities of interest, for example the minimal and maximal time for which the model is valid
```python
>>> gufm1.t_min
1590.0
>>> gufm1.t_max
1990.0
```

104
105
106
107
108
109
## Testing

To test your `pymagglobal` installation, run
```console
$ python tests/run_tests.py
```
110
111
112
113
from `<pymagglobal>`. Some tests require `FieldTools`, `packaging` and `orthopoly` and will be skipped, if the respective pacakges are not available. You can install `orthopoly` and `packaging` together with `pymagglobal`, by running
```console
$ pip install pymagglobal[tests] --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@gitext.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple
```
114
115
116
117
118

We also provide the expression for a nix-shell with all dependencies installed. This will however not test your local installation, but your local repository. To perform the tests, run
```console
$ nix-shell .tests-shell.nix --run "python tests/run_tests.py"
```
119
120
121
122
123
124
125
126
127
128
129

[FieldTools]: http://doi.org/10.5880/fidgeo.2019.033

## Contact
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)  
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ  
Section 2.3: Geomagnetism  
Telegrafenberg  
14473 Potsdam, Germany

## References
130
`pymagglobal` uses `numpy`, `scipy`, `matplotlib` and `cartopy`:
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150

[\[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)  
"Cartopy: a cartographic python library with a Matplotlib interface"

151
For testing `pymagglobal`, we use `pyfield`, `orthopoly` and [`packaging`](https://packaging.pypa.io/):
152

153
154
155
156
[\[pyfield\]](http://doi.org/10.5880/fidgeo.2019.033) Matuschek, H. and Mauerberger, S. (2019)  
FieldTools - A toolbox for manipulating vector fields on the sphere  
GFZ Data Services. 10.5880/fidgeo.2019.033

Maximilian Schanner's avatar
Maximilian Schanner committed
157
158
[\[orthopoly\]](https://wordsworthgroup.github.io/orthopoly/index.html) Mark Baum (2020)  
 wordsworthgroup/orthopoly v0.7 (Version v0.7)  
159
160
Zenodo. http://doi.org/10.5281/zenodo.3779456

161
## License
Maximilian Schanner's avatar
Maximilian Schanner committed
162

163
Copyright © 2020 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)
Maximilian Schanner's avatar
Maximilian Schanner committed
164

165
166
167
168
169
This work is licensed under the following license(s):
* Insignificant files are licensed under [CC0-1.0](LICENSES/CC0-1.0.txt)
* Software files are licensed under [GPL-3.0-or-later](LICENSES/GPL-3.0-or-later.txt)
* Data files are licensed under [GPL-3.0-or-later](LICENSES/GPL-3.0-or-later.txt)
* Everything else is licensed under [GPL-3.0-or-later](LICENSES/GPL-3.0-or-later.txt)
Maximilian Schanner's avatar
Maximilian Schanner committed
170

171
Please see the individual files for more accurate information.
Maximilian Schanner's avatar
Maximilian Schanner committed
172

173
> **Hint:** We provided the copyright and license information in accordance to the [REUSE Specification 3.0](https://reuse.software/spec/).