planetMagFields 1.5.2

Description:

planetMagFields 1.5.2

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.