planetMagFields

Software to easily access and analyze information about magnetic fields of planets in our solar system and visualize them in both 2D and 3D.

Prerequisites

Installation

Features and examples

Jupyter notebook

Documentation

Code contribution and reporting issues

Citing planetMagFields

Acknowledgements

Prerequisites

planetMagFields requires NumPy, Matplotlib and SciPy. Other than that, the following external libraries are used for a few different functions:

• 2D plotting for map projections other than Hammer : Cartopy library
• Potential extrapolation: SHTns library
• Writing vts files for 3D visualisation: PyEVTK library

Installation

planetMagFields can be installed in a few different ways:

Using pip

planetMagFields is available on PyPI and can be installed with

$ python3 -m pip install planetMagFields

Using setup.py

You can also use setup.py to install planetMagFields:

$ git clone https://github.com/AnkitBarik/planetMagFields
$ cd planetMagFields
$ pytho3 setup.py install --user

Or using pip:

$ git clone https://github.com/AnkitBarik/planetMagFields
$ cd planetMagFields
$ python3 -m pip install . --user

Using PYTHONPATH

Download the package from the GitHub repository and add it to PYTHONPATH:

$ git clone https://github.com/AnkitBarik/planetMagFields
$ export PYTHONPATH=$PYTHONPATH:/path/to/planetMagFields

Features and examples

The Planet class

This gives access to all the relevant properties of a planet and has methods to plot the field and write a vts file for 3D visualization. Usage:

from planetmagfields import Planet
p = Planet(name='earth',datDir='planetmagfields/data/')

This displays the some information about the planet

Planet: Earth
l_max = 13
Dipole tilt (degrees) = -9.410531

and gives access to variables associated with the planet such as:

• p.lmax : maximum spherical harmonic degree till which data is available
• p.glm, p.hlm: the Gauss coefficients
• p.Br : computed radial magnetic field at surface
• p.dipTheta : dipole tilt with respect to the rotation axis
• p.dipPhi : dipole longitude ( in case zero longitude is known, applicable to Earth )
• p.idx : indices to get values of Gauss coefficients
• p.model : the magnetic field model used. Available models can be obtained using the get_models function. Selects the latest available model when unspecified.

Example using IPython:

In [1]: from planetmagfields import Planet

In [2]: p = Planet(name='jupiter',model='jrm09')
Planet: Jupiter
Model: jrm09
l_max = 10
Dipole tilt (degrees) = 10.307870

In [3]: p.glm[p.idx[2,0]]      # g20
Out[3]: 11670.4

In [4]: p.hlm[p.idx[4,2]]      # h42
Out[4]: 27811.2

2D and 3D visualizations

planetMagFields can be used to produce both 2D and 3D visualizations of a planetary field. While doing so, it also provides the option of potential extrapolation using the SHTns library. Two examples are shown below: Earth's surface field and a 3D visualization of Jupiter's field using Paraview. This is done by writing a .vts file using the PyEVTK library.

Jupyter notebook

For quick and easy visualization we include a Jupyter notebook with a binder link (see badge at the top). This makes use of Jupyter widgets to provide dropdown lists of planets and available magnetic field models for each as well as a slider for radial level, as shown below

This plots the radial magnetic field at the chosen radial level and the corresponding magnetic field spectrum,

Documentation

Full list of features with examples as well as the magnetic field models used are described in detail in the documentation, available here: https://ankitbarik.github.io/planetMagFields/

Code contribution and reporting issues

planetMagFields is an open source project and anyone is welcome to contribute to it. If you wish to contribute to this project, please follow the guidelines below:

• Please make sure the tests pass before opening a pull request.
• Please follow Python PEP-8 guidelines when it comes to code style.
• If you wish to add new data file, please name it following the convention <planet>_<model>.dat, where planet and model denote the names of the planet and the magnetic field model being used. See the data directory for examples.
• If you implement a new feature or data source, please update the documentation accordingly.

Please report any bugs or other issues through GitHub Issues.

Citing planetMagFields

If you're using planetMagFields for your work, please cite the JOSS paper:

Barik et al., (2024). planetMagFields: A Python package for analyzing and plotting planetary magnetic field data. Journal of Open Source Software, 9(97), 6677, https://doi.org/10.21105/joss.06677

@article{Barik2024,
  doi = {10.21105/joss.06677},
  url = {https://doi.org/10.21105/joss.06677},
  year = {2024},
  publisher = {The Open Journal},
  volume = {9},
  number = {97},
  pages = {6677},
  author = {Barik, Ankit and Angappan, Regupathi},
  title = {planetMagFields: A Python package for analyzing and plotting planetary magnetic field data},
  journal = {Journal of Open Source Software}
}

Acknowledgements

I would like to thank Regupathi Angappan for motivating me to create this package, testing it and for writing the Jupyter notebook. I thank Jon Aurnou for testing it out and pointing out runtime errors. I would like to thank Thomas Gastine for comparing the plots with real data and pointing out a normalization error which has been fixed. Thanks a lot to Arthus for adding the setup.py.