JupiterMag

Python wrapper for a collection of Jovian magnetic field models written in C++ (see libjupitermag).

This is part of a community code project :

Magnetospheres of the Outer Planets Group Community Code

Journal Paper DOI: https://doi.org/10.1007/s11214-023-00961-3 (PDF via DOI, or https://rdcu.be/c5I71, see Journal Publication.)

Authors

Matt James - University of Leicester
Gabby Provan - University of Leicester
Aneesah Kamran - University of Leicester
Rob Wilson - LASP
Marissa Vogt - Boston University
Marty Brennan - NASA JPL
Stan Cowley - University of Leicester

1 Requirements

For the Python code to run, the following Python packages would be required:

NumPy
Matplotlib
DateTimeTools
RecarrayTools
PyFileIO

all of which would be installed automatically if using pip.

During installation, the C++ library which this module uses will be compiled.

1.1 Linux

JupiterMag was built and tested primarily using Linux Mint 20.3 (based on Ubuntu 20.04/Debian). To rebuild the code, ensure that g++, make and ld are installed.

1.2 Windows

This has been tested on Windows 10 (64-bit), other versions may also work. Requires g++ and ld to work (these can be provided by TDM-GCC). This may or may not work with other compilers installed.

1.3 MacOS

This module has been tested on MacOS 11 Big Sur. It requires g++, make and libtool to recompile (provided by Xcode).

2 Installation

Install using pip3:

pip3 install JupiterMag --user

Download the latest release (on the right -> if you're viewing this on GitHub), then from within the directory where it was saved:

pip3 install JupiterMag-1.2.0.tar.gz --user

Or using this repo (replace "1.2.0" with the current version number):

#pull this repo
git clone https://github.com/mattkjames7/JupiterMag.git
cd JupiterMag

#update the submodule
git submodule update --init --recursive

#build the source distribution file
python3 setup.py sdist
#the output of the previous command should give some indication of 
#the current version number. If it's not obvious then do
# $ls dist/ to see what the latest version is
pip3 install dist/JupiterMag-1.2.0.tar.gz --user

I recommend installing gcc >= 9.3 (that's what this is tested with, earlier versions may not support the required features of C++).

This module should now work with both Windows and MacOS

2.1 Update an Existing Installation

To update an existing installation:

pip3 install JupiterMag --upgrade --user

Alternatively, uninstall then reinstall, e.g.:

pip3 uninstall JupiterMag
pip3 install JupiterMag --user

3 Usage

3.1 Internal Field

A number of internal field models are included (see here for more information) and can be accessed via the JupiterMag.Internal submodule, e.g.:

import JupiterMag as jm

#configure model to use VIP4 in polar coords (r,t,p)
jm.Internal.Config(Model="vip4",CartesianIn=False,CartesianOut=False)
Br,Bt,Bp = jm.Internal.Field(r,t,p)

#or use jrm33 in cartesian coordinates (x,y,z)
jm.Internal.Config(Model="jrm33",CartesianIn=True,CartesianOut=True)
Bx,By,Bz = jm.Internal.Field(x,y,z)

All coordinates are either in planetary radii (x,y,z,r) or radians (t,p). All Jovian models here use R_j=71,492 km.

NOTE: figure 1 of the paper, which presents the radial components of the JRM33 model using degrees of 13 and 18 is corrupted, here is a clean version created using this code:

3.2 External Field

Currently the only external field source included is the Con2020 field (see here for the standalone Python code and here for more information on the C++ code used here as part of libjupitermag), other models could be added in future.

This works in a similar way to the internal field, e.g.:

#configure model
jm.Con2020.Config(equation_type='analytic')
Bx,By,Bz = jm.Con2020.Field(x,y,z)

3.3 Tracing

Field line tracing can be done using the TraceField object, e.g.

import JupiterMag as jm

#configure external field model prior to tracing
#in this case using the analytic Con2020 model for speed
jm.Con2020.Config(equation_type='analytic')

#trace the field in both directions from a starting position
T = jm.TraceField(5.0,0.0,0.0,IntModel='jrm09',ExtModel='Con2020')

The above example will trace the field line from the Cartesian SIII position (5.0,0.0,0.0) (R_j) in both directions until it reaches the planet using the JRM09 internal field model with the Con2020 external field model. The exact point at which the trace stops is either the surface of the planet or the radius L-MIC ionosphere, whichever has the shortest radial distance to the centre of Jupiter (see 3.3.2). The object returned, T, is an instance of the TraceField class which contains the positions and magnetic field vectors at each step along the trace, along with some footprint coordinates and member functions which can be used for plotting.

3.3.1 Plotting

The TraceField class has a few methods which will create some simple plots of the traced field lines:

PlotXZ() - plot the field traces in the X-Z plane (SIII)
PlotXY() - plot the traces projected in the X-Y plane (SIII)
PlotRhoZ() - plot the field traces in ρ-Z plane, where ρ² = x² + y²

The example below can be used to compare field traces using just an internal field model (JRM33) with both internal and external field models (JRM33 + Con2020):

import JupiterMag as jm
import numpy as np

#be sure to configure external field model prior to tracing
jm.Con2020.Config(equation_type='analytic')
#this may also become necessary with internal models in future, e.g.
#setting the model degree

#create some starting positions
n = 8
theta = (180.0 - np.linspace(22.5,35,n))*np.pi/180.0
r = np.ones(n)
x0 = r*np.sin(theta)
y0 = np.zeros(n)
z0 = r*np.cos(theta)

#create trace objects, pass starting position(s) x0,y0,z0
T0 = jm.TraceField(x0,y0,z0,Verbose=True,IntModel='jrm33',ExtModel='none')
T1 = jm.TraceField(x0,y0,z0,Verbose=True,IntModel='jrm33',ExtModel='Con2020')

#plot a trace
ax = T0.PlotRhoZ(label='JRM33',color='black')
ax = T1.PlotRhoZ(fig=ax,label='JRM33 + Con2020',color='red')

ax.set_xlim(-2.0,15.0)
ax.set_ylim(-6.0,6.0)

The resulting objects T0 and T1 store arrays of trace positions and magnetic field vectors along with a bunch of footprints.The above code produces a plot like this:

3.3.2 Trace Footprints

The field traces each have an associated set of "footprints" which are stored within the TraceField instance as a set of three numpy.recarrays called:

TraceField.surface - locations where the field line intersects the "surface" of Jupiter (oblate spheroid, equatorial radius = 71,492 km and polar radius = 66,854 km).
TraceField.ionosphere - where the field lines map to the ionosphere as used by th L-MIC model (sphere of radius 67,354 km, 500 km above polar radius).
TraceField.equator - location of the farthest point of the field trace from the planet (unless the field line is open).

Every trace has an element of each of the above footprint arrays, but if the field is open, then some of the elements will be filled with NAN, indicating the absence of a footprint.

The surface and ionosphere arrays have the following fields:

xn3, yn3, zn3 - north footprint, SIII coords (R_j)
xs3, ys3, zs3 - south footprint, SIII coords (R_j)
xnm, ynm, znm - north footprint, dipole coords (R_j)
xsm, ysm, zsm - south footprint, dipole coords (R_j)
latn, lonn - latitude and longitude, north footprint, SIII coords (°)
lats, lons - latitude and longitude, south footprint, SIII coords (°)
mlatn, mlonn - latitude and longitude, north footprint, dipole coords (°)
mlats, mlons - latitude and longitude, south footprint, dipole coords (°)

The equator array has these fields:

x3, y3, z3 - SIII coords (R_j)
xm, ym, zm - dipole coords (R_j)
mlone - longitude in dipole coords (°)
fllen - length of the field line (R_j)
mshell - distance from the centre of the planet to the farthest point along the field trace (R_j)