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.
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
pagemtimesfunction, 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
SPICEdirectory:de430.bsp--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/jup365.bsp--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/sat441.bsp--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/ura111.bsp--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/nep097.bsp--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/earth_latest_high_prec.bpc--- from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/- For Galileo, all in the
SPICE/Galileodirectory and all from https://naif.jpl.nasa.gov/pub/naif/GLL/kernels/spk/:s980326a.bsps000131a.bsps030916a.bsp
- For Cassini:
- All in the
SPICE/Cassinidirectory, 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). - Delete all files from each meta kernel except for the .bsp files with SCPSE in the name.
- All in the
SPICE/Cassini/spkdirectory, 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.
- All in the
- For Juno, all from https://naif.jpl.nasa.gov/pub/naif/JUNO/kernels/spk/:
- In the
SPICEdirectory:jup380s.bsp
- In the
SPICE/Junodirectory:juno_rec_orbit.bsp
- In the
- For Voyager 1, all in the
SPICE/Voyager 1directory and all from https://naif.jpl.nasa.gov/pub/naif/VOYAGER/kernels/spk/:vgr1_jup230.bspvgr1_sat337.bsp
- For Voyager 2, all in the
SPICE/Voyager 2directory and all from https://naif.jpl.nasa.gov/pub/naif/VOYAGER/kernels/spk/:vgr2_jup230.bspvgr2_sat337.bspvgr2.ura111.bspvgr2_nep097.bsp
- Download spacecraft magnetic data for comparison to the
MAG/scdirectory, wherescis the name of the spacecraft.
- Add the top-level
PlanetMagdirectory and all subdirectories to the Matlab path and navigate to the top-levelPlanetMagdirectory. - Run
PlanetMag.mto 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.
- Compare field models evaluated with
PlanetMag.musing theComparisonscripts in thecomparisondirectory. - 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
- Compare field models evaluated with
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)."
PlanetMag is licensed under Apache-2.0.
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.
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.