Commit 289f1655 authored by Maximilian Schanner's avatar Maximilian Schanner
Browse files

sqa killed the readme [skip ci]

parent 4287ee4b
......@@ -23,6 +23,164 @@ you can use `pymagglobal` to evaluate your own models, if they come in a similar
Once installed, `pymagglobal` can be imported and its routines used to access the models from inside your own python code.
## Citation
TODO
## Documentation
Check out the extended documention [here](http://arthus.gitext-pages.gfz-potsdam.de/pymagglobal). From the command line, you can use `pymagglobal` to get various results from the models. For example,
```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
```
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
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
gufm1 = pymagglobal.Model('gufm1', pymagglobal.models['gufm1'])
```
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
```
## 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 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.
You may want to create a fresh environment for pymagglobal. This is done using
```console
$ conda create --name Your_Environment
```
followed by
```console
$ conda activate Your_Environment
```
Careful: With tcshell, you have to use activate.csh.
2. Install `conda-build`
```console
$ conda install conda-build
```
With `conda-build` installed, you may go to `<pymagglobal>` and run
```console
$ bash install.sh
```
which will do the next steps for you. If `install.sh` fails or you want to do the steps by hand:
3. Build [FieldTools]
This step will make the pyfield library available via the local conda channel.
Navigate to `<pymagglobal>` and build [FieldTools]
```console
$ conda build FieldTools
```
4. Build pymagglobal
Navigate to `<pymagglobal>` and build pymagglobal
```console
$ conda build ./
```
5. Install pymagglobal
```console
$ 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
```
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.
[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
`pymagglobal` uses `numpy`, `scipy`, `matplotlib`, `cartopy` and `pyfield`:
[\[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"
[\[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
## License
Copyright © 2020 Helmholtz Centre Potsdam - GFZ German Research Centre for Geosciences, Germany (https://www.gfz-potsdam.de/)
......@@ -35,4 +193,4 @@ This work is licensed under the following license(s):
Please see the individual files for more accurate information.
> **Hint:** We provided the copyright and license information in accordance to the [REUSE Specification 3.0](https://reuse.software/spec/).
\ No newline at end of file
> **Hint:** We provided the copyright and license information in accordance to the [REUSE Specification 3.0](https://reuse.software/spec/).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment