Overview

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.

pymagglobal comes with a GUI, that can be started from the command line via

$ pymagglobal-gui

You can also use pymagglobal directly from the command line, to get various results from the models. For example,

$ pymagglobal dipole gufm1

will give a plot of the dipole moment time series for the model gufm1. In general, pymagglobal is called as

$  pymagglobal command --options model

where command specifies the quantity you want to get from pymagglobal and model is the respective model. You can use

$ pymagglobal command --options <path/to/your_model>

to parse your own model, if it is in a format similar to gufm1. Use

$ pymagglobal --help

to get further information. Each command has its own help, so you may also use

$ 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:

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:

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

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

>>> 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:

models = built_in_models()
names = models.keys()
paths = models.items()

You can also use

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

File format description

The format that is used by pymagglobal is the same as the gufm1 model and the CALSxk models. 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 model files are structured as follows:

  • The first line has to provide two numeric values: Start and end of the epoch for which the model is valid. Any trailing text is ignored.

  • The second line contains three integers: The maximal spherical harmonic degree, an unused number and the number of splines.

  • Then follows a block of years, specifying the knots for the cubic B-splines and a block of coefficients, containing first all coefficients for the first knot, then all for the second etc.

11590 1990 Trailing text is ignored
214  0  163
3  1582.5000000000    1585.0000000000    1587.5000000000 ...

The code is somewhat flexible with line breaks. Only the line break after the first line is really necessary. If you have trouble parsing your own files, feel free to contact one of the authors.

Included models

pymagglobal comes with several models pre-included. You can download additional models here. Below is a description of the included models.

Model

Interval

Reference

Short description

gufm1

1590 – 1990 CE

[Jack00]

Based on historical and modern data

arhimag1k

1000 – 2000 CE

[Senf20]

Combining archeomagnetic, volcanic and historical data

pfm9k.1a

7000 BCE – 1900 CE

[Nils14]

Based on archeomagnetic, volcanic and sediment data; Sediment timescales adjusted to best fit

HFM.OL1.A1

8000 BCE – 1990 CE

[Pano15]

Based on archeomagnetic, volcanic and sediment data; Data outlier treatment and strength of temporal and spatial regularization somewhat different from the CALSxk models

CALS10k.2

8000 BCE – 1990 CE

[Cons16]

Based on archeomagnetic, volcanic and sediment data; Recent centuries constrained to agree in general with gufm1

ARCH10k.1

8000 BCE – 1990 CE

[Cons16]

Based only on archeomagnetic and volcanic data; Sparse data coverage for early millennia; Recent centuries constrained to agree in general with gufm1

LSMOD.2

49.5 – 29.5 ka

[Kort19]

Based on sediment and volcanic data; Closely adjacent sediment records stacked for regional consistency; Small correction to a sediment record location compared to LSMOD.1; use the --longterm flag, to pass dates as ka BP

GGF100k

100 – 0 ka

[Pano18]

Based on sediment, volcanic and archeomagnetic data; Temporally stronger smoothed (by temporal regularization) compared to the dedicated Laschamp excursion models; use the --longterm flag, to pass dates as ka BP

GGFSS70

70 – 15 ka

[Pano21]

Based on nine selected high-quality sediment records; dedicated to cover three geomagnetic excursions: Norwegian-Greenland Sea (65 ka), Laschamps (41 ka), and Mono Lake/Auckland (34 ka); exhibits a better temporal resolution than the GGF100k model; use the --longterm flag, to pass dates as ka BP

References

Jack00

Jackson, A., A. R. T. Jonkers and M. R. Walker (2000): Four centuries of geomagnetic secular variation from historical records. Phil. Trans. R. Soc. Lond. A 358, 957–990

Senf20

Senftleben, R. (2020): Earth’s magnetic field over the last 1000 years. PhD thesis, University of Potsdam

Nils14

Nilsson, A., R. Holme, M. Korte, N. Suttie and M. Hill (2014): Reconstructing Holocene geomagnetic field variation: new methods, models and implications. Geophys. J. Int., 198, 229-248

Pano15

Panovska, S., M. Korte, C. Finlay and C. Constable (2015): Limitations in paleomagnetic data and modelling techniques and their impact on Holocene geomagnetic field models. Geophys. J. Int., 202, 402-418.

Cons16(1,2)

Constable, C., M. Korte and S. Panovska (2016): Persistent high paleosecular variation activity in Southern hemisphere for at least 10 000 years. Earth Planet. Sci. Lett.,453,78-86.

Kort19

Korte, M., M. C. Brown, S. Panovska and I. Wardinski (2019): Robust characteristics of the Laschamp and Mono Lake geomagnetic excursions: results from global field models. Frontiers in Earth Sciences, 7:86, doi:10.3389/feart.2019.00086

Pano18

Panovska, S., C. G. Constable and M. Korte (2018): Extending global continuous geomagnetic field reconstructions on timescales beyond human civilization. Geochem. Geophys. Geosys., 19, 4757-4772. doi:10.1029/2018GC007966

Pano21

Panovska, S., M. Korte, J. Liu and N. Nowacyk (2021): Global Evolution and Dynamics of the Geomagnetic Field in the 15–70 kyr Period Based on Selected Paleomagnetic Sediment Records. JGR: Solid Earth, 126, e2021JB022681. doi.org/10.1029/2021JB022681