README.md 4.93 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. 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. 
Maximilian Schanner's avatar
Maximilian Schanner committed
8

Maximilian Schanner's avatar
Maximilian Schanner committed
9
For extensive documentation, including a more detailed description of the standard file format, check out the [docs](https://sec23.git-pages.gfz-potsdam.de/korte/pymagglobal).
Maximilian Schanner's avatar
Maximilian Schanner committed
10

11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
## License
GNU General Public License, Version 3, 29 June 2007

Copyright (C) 2020 Helmholtz Centre Potsdam -  GFZ German Research Centre for Geosciences, Potsdam, Germany (https://www.gfz-potsdam.de)

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

Data files are licensed under [CC-BY 4.0](https://creativecommons.org/licenses/by/4.0/).

31
## Citation
32
33
> Schanner, M. A.; Mauerberger, S.; Korte, M. (2020)  
> pymagglobal - Python interface for global geomagnetic field models. V. 0.1.0.  
34
> GFZ Data Services. https://doi.org/10.5880/GFZ.2.3.2020.005  
35
[![DOI](https://img.shields.io/badge/DOI-10.5880%2FGFZ.2.3.2020.005-blue.svg)](http://doi.org/10.5880/GFZ.2.3.2020.005)
36

37
38
39
40
41
42
## 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
43
$ pip3 install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@git.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple
44
45
```

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

48
49
50
51
52
53
## Testing

To test your `pymagglobal` installation, run
```console
$ python tests/run_tests.py
```
54
55
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
56
$ pip install pymagglobal[tests] --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@git.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple
57
```
58

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

Maximilian Schanner's avatar
Maximilian Schanner committed
61
62
63
## Documentation
Extensive documentation is available [here]((https://sec23.git-pages.gfz-potsdam.de/korte/pymagglobal).

64
65
66
67
68
69
70
71
## 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
72
`pymagglobal` uses `numpy`, `scipy`, `matplotlib` and `cartopy`:
73
74
75
76
77
78
79
80
81
82
83

[\[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".  
84
85
Nature Methods, in press.  
https://doi.org/10.1038/s41592-019-0686-2
86
87
88

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

92
[\[cartopy\]](https://scitools.org.uk/cartopy) UK Met Office (2018)  
93
94
"Cartopy: a cartographic python library with a Matplotlib interface"

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

97
98
99
100
[\[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
101
102
[\[orthopoly\]](https://wordsworthgroup.github.io/orthopoly/index.html) Mark Baum (2020)  
 wordsworthgroup/orthopoly v0.7 (Version v0.7)  
103
Zenodo. http://doi.org/10.5281/zenodo.3779456