README.md 5.11 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
8
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
9
10
11
```console
$ pymagglobal --list-models
```
Maximilian Schanner's avatar
Maximilian Schanner committed
12
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
13
14
15
16
17
```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
18
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
19

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

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

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

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

41
## Documentation
Maximilian Schanner's avatar
Maximilian Schanner committed
42
43
44
45
46
47
Use
```console
$ pymagglobal --help
```
to get info on how to use pymagglobal. TODO: Expand this section

48
## Installation
Maximilian Schanner's avatar
Maximilian Schanner committed
49
50
51
52
53
54
55
56
57
58
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/`.  
59
   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
60
   You may want to create a fresh environment for pymagglobal. This is done using
Maximilian Schanner's avatar
Maximilian Schanner committed
61
   ```console
62
   $ conda create --name Your_Environment
Maximilian Schanner's avatar
Maximilian Schanner committed
63
64
65
   ```
   followed by
   ```console
66
   $ conda activate Your_Environment
Maximilian Schanner's avatar
Maximilian Schanner committed
67
68
69
70
71
72
   ```
   Careful: With tcshell, you have to use activate.csh.
   

2. Install `conda-build`
   ```console
73
   $ conda install conda-build
Maximilian Schanner's avatar
Maximilian Schanner committed
74
   ```
75
76
77
78
79

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

Maximilian Schanner's avatar
Maximilian Schanner committed
82
83
84
85
86
3. Build [FieldTools]  
   This step will make the pyfield library available via the local conda channel.

   Navigate to `<pymagglobal>` and build [FieldTools]
   ```console
87
   $ conda build FieldTools
Maximilian Schanner's avatar
Maximilian Schanner committed
88
89
90
   ```

4. Build pymagglobal  
91
   Navigate to `<pymagglobal>` and build pymagglobal
Maximilian Schanner's avatar
Maximilian Schanner committed
92
   ```console
93
   $ conda build ./
Maximilian Schanner's avatar
Maximilian Schanner committed
94
95
96
   ```
5. Install pymagglobal  
   ```console
97
   $ conda install pymagglobal -c local
Maximilian Schanner's avatar
Maximilian Schanner committed
98
99
100
101
102
103
104
105
106
107
108
109
   ```
   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

110
## Contact
Maximilian Schanner's avatar
Maximilian Schanner committed
111
112
113
114
115
116
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)  
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ  
Section 2.3: Geomagnetism  
Telegrafenberg  
14473 Potsdam, Germany

117
## References
Maximilian Schanner's avatar
Maximilian Schanner committed
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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)  
137
"Cartopy: a cartographic python library with a Matplotlib interface"