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