Commit 87c7c00a authored by Maximilian Schanner's avatar Maximilian Schanner
Browse files

Reworked the docs.

parent 5a4dd9ea
...@@ -4,18 +4,9 @@ ...@@ -4,18 +4,9 @@
[[_TOC_]] [[_TOC_]]
`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. `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.
By default, `pymagglobal` includes several models. Use
```console
$ pymagglobal --list-models
```
to get a list of these default models or go to [pymagglobal/dat](https://git.gfz-potsdam.de/sec23/korte/pymagglobal/-/tree/master/pymagglobal/dat) for further information. Using
```console
$ pymagglobal ... <path/to/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 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.
Once installed, `pymagglobal` can be imported and its routines used to access the models from inside your own python code. 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).
## License ## License
GNU General Public License, Version 3, 29 June 2007 GNU General Public License, Version 3, 29 June 2007
...@@ -54,62 +45,6 @@ $ pip3 install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J ...@@ -54,62 +45,6 @@ $ pip3 install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J
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. 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.
## Documentation
Check out the extended documention [here](https://sec23.git-pages.gfz-potsdam.de/korte/pymagglobal).
pymagglobal comes with a GUI, that can be started from the command line via
```console
$ pymagglobal-gui
```
You can also use pymagglobal directly from the command line, 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
```
We can first use `built_in_models`, to access a dictionary of available models:
```python
models = built_in_models()
```
pymagglobal provides a `Model` class. Built-in models can be accessed directly, custom models are set up with a name and a path:
```python
gufm1 = pymagglobal.Model('gufm1')
my_model = pymagglobal.Model('My model', '<path/to/my_model.dat>')
```
The model can be passed to 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)
```
Additionally, the object 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
```
## Testing ## Testing
To test your `pymagglobal` installation, run To test your `pymagglobal` installation, run
...@@ -123,6 +58,9 @@ $ pip install pymagglobal[tests] --extra-index-url https://public:5mz_iyigu-WE3H ...@@ -123,6 +58,9 @@ $ pip install pymagglobal[tests] --extra-index-url https://public:5mz_iyigu-WE3H
[FieldTools]: http://doi.org/10.5880/fidgeo.2019.033 [FieldTools]: http://doi.org/10.5880/fidgeo.2019.033
## Documentation
Extensive documentation is available [here]((https://sec23.git-pages.gfz-potsdam.de/korte/pymagglobal).
## Contact ## Contact
* [Maximilian Schanner](mailto:arthus@gfz-potsdam.de) * [Maximilian Schanner](mailto:arthus@gfz-potsdam.de)
Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ Helmholtz Centre Potsdam German Research Centre for Geoscienes GFZ
......
Command line interface Command line interface
====================== ======================
The python package `pymagglobal` also offers a utility command `pymagglobal` can be accessed directly via the command line. This is documented below.
.. argparse:: .. argparse::
:module: pymagglobal.__main__ :module: pymagglobal.__main__
......
...@@ -2,23 +2,17 @@ A python interface for global geomagnetic field models ...@@ -2,23 +2,17 @@ A python interface for global geomagnetic field models
====================================================== ======================================================
.. toctree:: .. toctree::
:hidden: :hidden:
overview
installation
package_documentation package_documentation
command_line_interface command_line_interface
examples examples
CHANGELOG CHANGELOG
:ref:`pymagglobal <Overview>` serves the purpose of replacing some Fortran scripts, which are used in the geomagnetism community to evaluate global field models.
:code:`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. 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.
:code:`pymagglobal` comes with a GUI, that can be started from the command line via
.. code-block:: bash
$ pymagglobal-gui
Installation Installation
------------ ------------
.. note: .. note:
...@@ -26,16 +20,13 @@ Installation ...@@ -26,16 +20,13 @@ Installation
This should also help if you receive :code:`ImportError: NumPy 1.10+ is required to install cartopy.` This should also help if you receive :code:`ImportError: NumPy 1.10+ is required to install cartopy.`
:code:`pymagglobal` is distributed via the PyPI registry of the corresponding repository. It can be installed using pymagglobal is distributed via the PyPI registry of the corresponding repository. It can be installed using
.. code-block:: bash .. code-block:: bash
$ pip3 install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@git.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple $ pip3 install pymagglobal --extra-index-url https://public:5mz_iyigu-WE3HySBH1J@git.gfz-potsdam.de/api/v4/projects/1055/packages/pypi/simple
See also `here <https://git.gfz-potsdam.de/sec23/korte/pymagglobal#installation>`_ and `here <https://git.gfz-potsdam.de/sec23/korte/pymagglobal#testing>`_. Additional information can be found in the :ref:`installation section <Installation>`.
.. include:: ../pymagglobal/dat/README.rst
License License
------- -------
...@@ -55,11 +46,3 @@ GNU General Public License for more details. ...@@ -55,11 +46,3 @@ GNU General Public License for more details.
You should have received a copy of the GNU General Public License You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>. along with this program. If not, see <https://www.gnu.org/licenses/>.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
* `Repository <https://git.gfz-potsdam.de/sec23/korte/pymagglobal/>`_
.. _Installation:
Installation
============
Nothing here yet.
This file complements pymagglobal.
It is licensed under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/)
.. _Overview:
Overview
========
:code:`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.
A detailed description of the file format, together with a list of the included models can be found below.
:code:`pymagglobal` comes with a GUI, that can be started from the command line via
.. code-block:: bash
$ pymagglobal-gui
You can also use pymagglobal directly from the command line, to get various results from the models. For example,
.. code-block:: bash
$ pymagglobal dipole gufm1
will give a plot of the dipole moment time series for the model gufm1. In general, pymagglobal is called as
.. code-block:: bash
$ pymagglobal command --options model
where `command` specifies the quantity you want to get from `pymagglobal` and `model` is the respective model. You can use
.. code-block:: bash
$ pymagglobal command --options <path/to/your_model>
to parse your own model, if it is in a format similar to gufm1. Use
.. code-block:: bash
$ pymagglobal --help
to get further information. Each command has its own help, so you may also use
.. code-block:: bash
$ 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:
.. code-block:: python
import pymagglobal
pymagglobal provides a `Model` class. Built-in models can be accessed directly, custom models are set up with a name and a path:
.. code-block:: python
gufm1 = pymagglobal.Model('gufm1')
my_model = pymagglobal.Model('My model', '<path/to/my_model.dat>')
The model can be passed to routines in pymagglobal. For example, to get the dipole series from above use
.. code-block:: python
import numpy as np
times = np.linspace(1590, 1990, 201)
gufm1_dipoles = pymagglobal.dipole_series(times, gufm1)
Additionally, the object contains several quantities of interest, for example the minimal and maximal time for which the model is valid
.. code-block:: python
>>> gufm1.t_min
1590.0
>>> gufm1.t_max
1990.0
By default, `pymagglobal` includes several models. A dictionary of the built in models is returned by `built_in_models`. The keys give a list of the model names, while the items point to the paths, where the models are stored. To access a dictionary of available models:
.. code-block:: python
models = built_in_models()
names = models.keys()
paths = models.items()
You can also use
.. code-block:: bash
$ pymagglobal --list-models
to get a list of these default models via the command line interface or check the table below.
.. code-block:: bash
$ pymagglobal ... <path/to/your_model>
you can use `pymagglobal` to evaluate your own models, if they come in a similar format. `<patodel>` specifies the path to your model and is given instead of the name of an included model.
.. include:: ../pymagglobal/dat/README.rst
This file complements pymagglobal.
It is licensed under CC0 1.0 (https://creativecommons.org/publicdomain/zero/1.0/)
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