planetMagFields: A Python package for analyzing and plotting planetary magnetic field data

Long term observations and space missions have generated a wealth of data on the magnetic fields of the Earth and other solar system planets. planetMagfields is a Python package designed to have all the planetary magnetic field data currently available in one place and to provide an easy interface to access the data. planetMagfields focuses on planetary bodies that generate their own magnetic field, namely Mercury, Earth, Jupiter, Saturn, Uranus, Neptune and Ganymede. planetMagfields provides functions to compute as well as plot the magnetic field on the planetary surface or at a distance above or under the surface. It also provides functions to filter out the field to large or small scales as well as to produce .vts files to visualize the field in 3D using Paraview, VisIt or similar rendering software. Lastly, the planetMagfields repository also provides a Jupyter notebook for easy interactive visualizations.


Statement of need
Planetary scientists studying the magnetic field of planets need to constantly access, visualize, analyze and extrapolate magnetic field data.In addition, with technological advancements in space exploration and planetary missions, we are constantly getting new data for planetary magnetic fields and hence, better field models.Though reviews of these field models are often written (Schubert & Soderlund, 2011;Stanley, 2014), there is very little software available that provides easy access to these models with a high level language and a way to easily visualize and analyze them.To the knowledge of the authors, there are a few publicly available repositories that are capable of providing access to planetary magnetic field data and tools to analyze them such as JupiterMag (James et al., 2024;Wilson et al., 2023), KMAG (Khurana, 2020), ChaosMagPy (Kloss, 2024), SHTools (Wieczorek & Meschede, 2018), PlanetMag (Styczinski & Cochrane, 2024) and libinteralfield (https://github.com/mattkjames7/libinternalfield).Out of these, only libinteralfield provides data and software to analyze and access magnetic fields of all planets.However, it is a C++ library which needs to be interfaced with something at a higher level to enable fast analyses and visualization.Thus, a software package that has different magnetic field models for all different planets of the solar system in one place, as well as provides a high level API to access, analyze and visualize them is not available.planetMagfields is intended not only to currently fill this gap, but also to provide a central repository, to be constantly updated, as more magnetic field models become available.
In addition to the research aspect of our software, the interactive Jupyter notebook serves as a valuable educational resource, fostering a deeper appreciation for the complexities of planetary magnetic environments.

Mathematics
Magnetic fields in planets are generated by electric currents in a fluid region inside them through a process called dynamo action (Jones, 2011;Schubert & Soderlund, 2011;Stanley, 2014).Outside this region, in the absence of current sources, the magnetic field ⃗ B can be written as the gradient of a scalar potential, ⃗ B = −∇V .The potential V is usually written as an expansion in orthogonal functions in spherical coordinates (r, θ, ϕ), where, g m l and h m l are called the Gauss coefficients.R p represents the radius of the planet and P m l are associated Legendre functions of order l and degree m, where l and m are integers.The above equation can be recast in terms of spherical harmonics, which is what the code uses.
The raw data obtained from satellites or space missions are usually inverted to obtain these Gauss coefficients which are the key to describing the surface magnetic field of a planet as well as how that field looks at a certain altitude from the surface.The magnetic energy content on the surface in a certain degree l is given by the Lowes spectrum: l plays the role of a wavenumber.Low degrees represent large spatial features in the field while high degrees represent small scale features.The maximum available degree l max of data for a particular planet depends on the quality of observations.

Benchmarking
We benchmarked our software against two publicly available repositories : JupiterMag (James et al., 2024;Wilson et al., 2023) for Jupiter and the CHAOS-7 (Finlay et al., 2020;Kloss, 2024) for Earth.For Jupiter, we compare the field at a depth of 85% of planetary radius, thus testing our extrapolation capability while for Earth, we compare the field on the surface in 2016, testing our implementation of taking into account changes in the Earth's field in a linear fashion (as is done for the IGRF model, Alken et al., 2021) The comparison for Jupiter is shown in Figure 1.We also use these cases in our unit testing.

Description of the software
The software package planetMagfields has data files containing Gauss coefficients from various inversion studies of planetary magnetic models for different planets.These coefficients are then used to obtain the magnetic field on a grid of latitude and longitude using equation ( 1).The main way of accessing the data is through the Planet class.An example is provided below using IPython (Pérez & Granger, 2007),  The last plot statement produces Figure 2 which is the radial magnetic field at 85% of the planetary radius.This can be compared against Figure 1h of Moore et al. (2018).planetMagfields primarily uses NumPy (Harris et al., 2020), Matplotlib (Hunter, 2007) and SciPy (Virtanen et al., 2020) for most of its analyses.Further support for various map projections is added through Cartopy (Met Office, 2010-2015).planetMagfields also provides functions to extrapolate and obtain all components of the magnetic field at a certain depth or height through spherical harmonic transforms using the SHTns library (Schaeffer, 2013).Finally, this extrapolation also allows one to visualize the field in 3D.To enable that, planetMagfields uses the PyEVTK library (https://github.com/paulo-herrera/PyEVTK) to write .vtsfiles which can be visualized using software like Paraview or VisIt.An example for Jupiter is provided below in Figure 3.A full list of available features is provided in the documentation.

Figure 1 :
Figure 1: Benchmarking the code against publicly available repositories.

Figure 2 :
Figure 2: Plotting example of Jupiter's radial magnetic field at a depth of 85% of the planetary radius.

Figure 3 :
Figure 3: 3D rendering of Jupiter's magnetic field using Paraview, using a vts file produced by planetMagfields.