Skip to content
Snippets Groups Projects
Select Git revision
  • main default
  • v0.1.0
2 results

pymagglobal

  • Clone with SSH
  • Clone with HTTPS
  • user avatar
    Maximilian Schanner authored
    a379a609
    History

    pymagglobal

    python interface for global geomagnetic field models

    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.
    By default, pymagglobal includes several models. Use

    $ pymagglobal --list-models

    to get a list of these default models or go to pymagglobal/dat for further information. Using

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

    Citation

    TODO

    Documentation

    Check out the extended documention here. From the command line, you can use pymagglobal 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

    Using the function file2splines you can get a spline object, representing the model. For example, to get a spline object for gufm1, use

    gufm1_splines = pymagglobal.file2splines(pymagglobal.models['gufm1'])

    This object can be evaluated to get the coefficients for a specific epoch

    gufm1_1600 = gufm1_splines(1600)

    or passed to other 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_splines)

    Additionally, pymagglobal provides a Model class, which is set up with a path and a name:

    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

    >>> gufm1.t_min
    1590.0
    >>> gufm1.t_max
    1990.0

    Installation

    pymagglobal is built and installed using conda.

    1. Clone the repository

       $ git clone https://gitext.gfz-potsdam.de/arthus/pymagglobal.git

      In the following <pymagglobal> refers to the path you cloned the pymagglobal repository into.

    2. Download and install Miniconda 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

      $ conda create --name Your_Environment

      followed by

      $ conda activate Your_Environment

      Careful: With tcshell, you have to use activate.csh.

    3. Install conda-build

      $ conda install conda-build

    With conda-build installed, you may go to <pymagglobal> and run

    $ bash install.sh

    which will do the next steps for you. If install.sh fails or you want to do the steps by hand:

    1. Build FieldTools
      This step will make the pyfield library available via the local conda channel.

      Navigate to <pymagglobal> and build FieldTools

      $ conda build FieldTools
    2. Build pymagglobal
      Navigate to <pymagglobal> and build pymagglobal

      $ conda build ./
    3. Install pymagglobal

      $ conda install pymagglobal -c local

      This will make pymagglobal available as a python package, i.e. you can use

      import pymagglobal

      as well as register a shell command in your local environmet, so that you can run

      $ pymagglobal --help

    Another way to use pymagglobal is via nix-shell. With nix installed, simply run

    $ nix-shell

    from within the pymagglobal root directory.

    Contact

    • Maximilian Schanner
      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] 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] J. D. Hunter (2007)
    "Matplotlib: A 2D Graphics Environment",
    Computing in Science & Engineering, vol. 9, no. 3, pp. 90-95

    [cartopy] Met Office (2015)
    "Cartopy: a cartographic python library with a Matplotlib interface"

    [pyfield] 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/)

    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.