PlanetMag

PlanetMag logo

Matlab software for evaluation of planetary magnetic field models and the oscillations applied to moons. The primary purposes of this software are to offer capabilities for:

Evaluation of planetary magnetic fields at arbitrary locations and times around the supported planets based on models described in peer-reviewed publications based on spacecraft data. The supported planets are Earth, Jupiter, Saturn, Uranus, and Neptune.
Determination of frequency spectra of magnetic oscillations in the frame of reference of satellites orbiting each supported planet, including recording complex amplitudes in each vector component in standard coordinate systems referenced to the J2000.0 epoch.
Statistical comparison of planetary field model results against spacecraft data, for validation purposes.

PlanetMag uses the SPICE toolkit and published magnetospheric models derived from spacecraft data. All timing and phases are referenced to the J2000 epoch, 2000-Jan-01 12:00:00 TDB, which is equivalent to 11:58:55.816 am UTC on the same date.

The main repository is mirrored at https://github.com/NASA-Planetary-Science/PlanetMag; any pull requests should be submitted to the primary repository at https://github.com/coreyjcochrane/PlanetMag. Read the software documentation at https://coreyjcochrane.github.io/PlanetMag.

This scientific software is the brain child of Corey J. Cochrane and Erik Sturm. The PlanetMag framework was developed by Corey J. Cochrane and Marshall J. Styczinski. The software is currently maintained by Marshall J. Styczinski.

Questions about PlanetMag? Please contact Corey J. Cochrane at corey.j.cochrane@jpl.nasa.gov. If you run into problems or need help with using the software, please contact maintainer Marshall J. Styczinski at itsmoosh@gmail.com.

Installation

PlanetMag requires Mice — the Matlab implementation of the SPICE toolkit, specific SPICE kernels, and Matlab version 2020b or later.

Mice functions must be located on the Matlab path.
The specific SPICE kernels used are all listed in functions/LoadSpice.m, and the expected path to find them is in the same file (./SPICE/ by default).
Smaller kernels are packaged with PlanetMag, but larger generic kernels must be downloaded from the generic kernels for satellites page of the NAIF website.
Earth data requires the latest Earth PCK file available at https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/earth_latest_high_prec.bpc.
PlanetMag relies on the pagemtimes function, which was introduced in Matlab version 2020b.

Some mission data (especially from ESA) uses Common Data Format (.cdf) files. Reading these files requires the CDF toolkit, available at https://spdf.gsfc.nasa.gov/pub/software/cdf/dist/latest/. Matlab ships with a version of the toolkit that works for most files, but can lock up reading large files (>15 MB). An example script for converting CDF files to ASCII tables is in ConvertSwarmCDF.m.

To fully install PlanetMag and access all features, complete the following. Note that although higher version numbers may exist of the .bsp files at the links below, these don’t necessarily cover the same bodies or eras as needed by PlanetMag. Use exactly the following .bsp file names.

Download or clone Matlab repo
Download Mice and place it in the right spot
Download the following SPICE kernels to the SPICE directory:
1. de430.bsp — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/
2. jup365.bsp — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/
3. sat441.bsp — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/
4. ura111.bsp — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/
5. nep097.bsp — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/
6. earth_latest_high_prec.bpc — from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/
7. For Galileo, all in the SPICE/Galileo directory and all from https://naif.jpl.nasa.gov/pub/naif/GLL/kernels/spk/:
  1. s980326a.bsp
  2. s000131a.bsp
  3. s030916a.bsp
8. For Cassini:
  1. All in the SPICE/Cassini directory, from https://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/extras/mk/, download all meta kernels listed in LoadSpice() (one for each year Cassini was operational at Saturn).
  2. Delete all files from each meta kernel except for the .bsp files with SCPSE in the name.
  3. All in the SPICE/Cassini/spk directory, from https://naif.jpl.nasa.gov/pub/naif/pds/data/co-s_j_e_v-spice-6-v1.0/cosp_1000/data/spk/, download all .bsp files listed in the meta kernels.
9. For Juno, all from https://naif.jpl.nasa.gov/pub/naif/JUNO/kernels/spk/:
  1. In the SPICE directory:
    1. jup380s.bsp
  2. In the SPICE/Juno directory:
    1. juno_rec_orbit.bsp
10. For Voyager 1, all in the SPICE/Voyager 1 directory and all from https://naif.jpl.nasa.gov/pub/naif/VOYAGER/kernels/spk/:
  1. vgr1_jup230.bsp
  2. vgr1_sat337.bsp
11. For Voyager 2, all in the SPICE/Voyager 2 directory and all from https://naif.jpl.nasa.gov/pub/naif/VOYAGER/kernels/spk/:
  1. vgr2_jup230.bsp
  2. vgr2_sat337.bsp
  3. vgr2.ura111.bsp
  4. vgr2_nep097.bsp
Download spacecraft magnetic data for comparison to the MAG/sc directory, where sc is the name of the spacecraft.

Running the software

Add the top-level PlanetMag directory and all subdirectories to the Matlab path and navigate to the top-level PlanetMag directory.
Run PlanetMag.m to test for full functionality and a demonstration of evaluation of excitation moments (amplitude and phase of oscillations) applied to Europa by Jupiter.
Comparison between magnetic models requires downloading spacecraft data from PDS into MAG/Mission, where “Mission” is the name of the spacecraft from which data will be compared. .tab files from PDS should keep the same filenames.
1. Compare field models evaluated with PlanetMag.m using the Comparison scripts in the comparison directory.
2. Swarm data is used for Earth field model validation. Data files are available at https://swarm-diss.eo.esa.int/#swarm/Level1b/Latest_baselines/MAGx_LR

Acknowledging PlanetMag

We appreciate your interest in PlanetMag! Please consider alerting us to your work (corey.j.cochrane@jpl.nasa.gov). Suggested acknowledgement in publications: “Data used in this work were generated using the open-source PlanetMag framework hosted on GitHub (https://github.com/coreyjcochrane/PlanetMag).”

Open-source license

PlanetMag is licensed under Apache-2.0.

Copyright notice

Copyright (c) 2024 California Institute of Technology (“Caltech”). U.S. Government sponsorship acknowledged. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Caltech nor its operating division, the Jet Propulsion Laboratory, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

Disclaimer

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.