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

Maximilian Schanner's avatar
Maximilian Schanner committed
3
4
### python interface for global geomagnetic field models

Maximilian Schanner's avatar
Maximilian Schanner committed
5
6
pymagglobal serves the purpose of replacing some Fortran scripts, which are used in the geomagnetism community to evaluate global field models.  
It works for files given in a format which was first used by the gufm model and than established in the community. By default, pymagglobal includes several models. Use
Maximilian Schanner's avatar
Maximilian Schanner committed
7
8
9
```console
$ pymagglobal --list-models
```
Maximilian Schanner's avatar
Maximilian Schanner committed
10
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. You can dowload additional models [here](TODO: PROVIDE MODELS VIA FTP). Using
Maximilian Schanner's avatar
Maximilian Schanner committed
11
12
13
14
15
```console
$ pymagglobal --input <path/to/your_model> ... your.model
```
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 file and `your.model` the name of your model.

Maximilian Schanner's avatar
typo    
Maximilian Schanner committed
16
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
17

Maximilian Schanner's avatar
Maximilian Schanner committed
18
19
20
# License
GNU General Public License, Version 3, 29 June 2007

21
Copyright (C) 2020 Helmholtz Centre Potsdam GFZ, German Research Centre for Geosciences, Potsdam, Germany
Maximilian Schanner's avatar
Maximilian Schanner committed
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

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

# Citation
TODO

# Documentation
Use
```console
$ pymagglobal --help
```
to get info on how to use pymagglobal. TODO: Expand this section

# Installation
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/`.  
   If you let conda modify your `bash.rc`, `<conda>/bin/conda` may be replaced by
   `conda`.  
Maximilian Schanner's avatar
Typo    
Maximilian Schanner committed
59
   You may want to create a fresh environment for pymagglobal. This is done using
Maximilian Schanner's avatar
Maximilian Schanner committed
60
61
62
63
64
65
66
67
68
69
70
71
72
73
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
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
   ```console
   $  <conda>/bin/conda create --name Your_Environment
   ```
   followed by
   ```console
   $  <conda>/bin/conda activate Your_Environment
   ```
   Careful: With tcshell, you have to use activate.csh.
   

2. Install `conda-build`
   ```console
   $ <conda>/bin/conda install conda-build
   ```
3. Build [FieldTools]  
   This step will make the pyfield library available via the local conda channel.

   Navigate to `<pymagglobal>` and build [FieldTools]
   ```console
   $ <conda>/bin/conda build FieldTools
   ```

4. Build pymagglobal  
   Navigate to `../<pymagglobal>` and build pymagglobal
   ```console
   $ <conda>/bin/conda build pymagglobal
   ```
5. Install pymagglobal  
   ```console
   $ <conda>/bin/conda install pymagglobal -c local
   ```
   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
   ```

With `conda-build` installed, you may also go to `<pymagglobal>` and run 
```console
$ bash install.sh
```
which will simply do steps 3-5 for you.

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

# 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
pymagglobal uses `numpy`, `scipy`, `matplotlib` and `cartopy`:

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