PlanetMag Matlab run scripts

PlanetMag()

PlanetMag(moonName, era, coordType, CALC_NEW, ALL_MODELS, DO_FFT, DO_MPAUSE, LIVE_PLOTS, nptsApprox, specificModel, specificMPmodel, outData, figDir, coeffPath, fPatternFT, fPatternTseries, figXtn, magPhase_deg)

Evaluates planetary magnetic field for a time series at the specified moon location and inverts for the complex amplitudes of oscillation in that moon’s frame.

This function is intended to be run as a script, so all parameters are optional.

Parameters:

  • moonName (char, 1xC, default='Europa') – Name of target moon for which to generate magnetic spectrum amplitudes.

  • era (char, 1xD, default='Galileo') –

    Time period over which measurements will be evaluated, corresponding to the prime mission lifetime. Options:

    • 'Swarm'

    • 'Galileo'

    • 'Cassini'

    • 'Juno'

    • 'Clipper'

    • 'Voyager'

  • coordType (char, 1xE, default='IAU') –

    Desired standard coordinates for magnetic spectrum inversion. Options:

    • 'IAU'

    • 'SPRH'

  • CALC_NEW (bool, default=1) – Whether to perform calculations or attempt to reload saved data for plotting purposes.

  • ALL_MODELS (bool, default=0) – Whether to run all implemented model options for the desired body.

  • DO_FFT (bool, default=0) – Whether to calculate and print an FFT from the time series after performing the inversion.

  • DO_MPAUSE (bool, default=0) – Whether to include a magnetopause screening current model.

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • nptsApprox (int, default=12*365.25*3*24) – Desired number of points to use in time series for inversion. A whole number of the period of interest (typically synodic period, as it is the strongest oscillation) will ultimately be selected, which is why this number is approximate.

  • specificModel (int, default=0) – Index number for the magnetospheric model to run. Options depend on the body, and setting to 0 selects the default model. See GetModelOpts() for a description of the options.

  • specificMPmodel (int, default=0) – Index number for the magnetopause model to run if DO_MPAUSE is true. 0 selects the default model See MpauseFld() for a description of the options.

  • outData (char, 1xF, default='out') – Directory to use for output of complex spectrum amplitudes.

  • figDir (char, 1xG, default='figures') – Directory to use for output figures.

  • coeffPath (char, 1xH, default='modelCoeffs') – Directory containing model coefficients files.

  • fPatternFT (char, 1xI, default='FTdata') – Pattern for file names of FFT spectrum data saved to disk.

  • fPatternTseries (char, 1xJ, default='TseriesData') – Pattern for file names of time series data saved to disk.

  • figXtn (char, 1xK, default='pdf') – Extension to use for figures, which determines the file type.

  • magPhase_deg (double, default=0) – Arbitrary offset in degrees by which to rotate the magnetospheric field evaluation.

Returns:

  • T_h (double, 1xP) – Oscillation periods of significant peaks in the excitation spectrum in hours.

  • B0vec (double, 1x3) – Time-independent background magnetic field vector from evaluated time series in nT in the selected coordinates.

  • B1vec1, B1vec2, B1vec3 (complex double, 1xP) – Degree-1 complex excitation moments inverted from the evaluated time series in nT at the body center. Components 1, 2, and 3 are aligned with, respectively, x, y, z or r, theta, phi depending on the selected coordinates.

  • outFname (char, 1xH) – Output file name to which the excitations moments were written.

  • header (char, 1xI) – Column header printed to output file, which contains information about what data were saved.

CompareEarModels()

comparison.CompareEarModels(LIVE_PLOTS, scName, xtn, SEQUENTIAL, coeffPath, figDir, figXtn)

Compare magnetic field measurements from spacecraft near Earth against each implemented magnetic field model.

Datasets:

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • scName (string, default="Swarm") – Spacecraft name for which magnetic field data will be compared against implemented models. A directory must exist with this name in the MAG directory within the top-level PlanetMag directory. This directory will be searched for data files with the xtn extension, and each of these files will be loaded.

  • xtn (char, 1xC, default='.tab') – File extension for data files found in fullfile('MAG', sc), beginning with '.'.

  • SEQUENTIAL (bool) – Whether to plot points by index or hours relative to a reference time.

  • coeffPath (char, 1xD, default='modelCoeffs') – Directory containing model coefficients files.

  • figDir (char, 1xE, default='figures') – Directory to use for output figures.

  • figXtn (char, 1xF, default='pdf') – Extension to use for figures, which determines the file type.

CompareJupModels()

comparison.CompareJupModels(LIVE_PLOTS, scName, opts, MPopts, moonName, orbNum, moonProx_RP, PlanetMinDist_RP, PlanetMaxDist_RP, dataDir, figDir, figXtn, SEQUENTIAL, coeffPath, FULLORBITS, FLYBYS, JUNOTOO)

Compare magnetic field measurements from spacecraft near Jupiter against each implemented magnetic field model.

Datasets:

Note

This script requires having run PlanetMag.m for the Galileo era for all implemented planetary and magnetopause models using ALL_MODELS=1.

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • scName (string, default="Galileo") – Spacecraft name for which magnetic field data will be compared against implemented models. A directory must exist with this name in the MAG directory within the top-level PlanetMag directory. This directory will be searched for body-specific data files, and each of these files will be loaded.

  • opts (int, 1xnOpts, default=1:nOpts) – List of model option ID numbers to include in comparison, as defined in GetModelOpts().

  • MPopts (int, 1xnMPopts, default=1:nMPopts) – List of magnetopause model option ID numbers to include in comparison, as defined in GetModelOpts().

  • moonName (char, 1xC, default='Ganymede') – Name of moon for which scName has flyby data. Flyby data is not used if FULLORBITS is true, but a name must be passed for kernel loading.

  • orbNum (int, default=-1) –

    Orbit number to use for data comparison. Accepts the following special options:

    • -1: Use all orbits for which data is available.

    • -2: Use all orbits for which flyby data is available for moonName.

  • moonProx_RP (double, default=0.1) – Minimum distance to major moons of the system within which measurements will be ignored in model validation due to local perturbations, in units of the parent planet’s radius.

  • PlanetMinDist_RP (double, default=10) – Minimum distance to parent planet within which measurements will be ignored, in units of the parent planet’s radius.

  • PlanetMaxDist_RP (double, default=20) – Maximum distance away from parent planet beyond which measurements will be ignored, in units of the parent planet’s radius.

  • dataDir (char, 1xD, default='out') – Name of directory where excitation moments are printed to disk.

  • figDir (char, 1xE, default='figures') – Directory to use for output figures.

  • figXtn (char, 1xF, default='pdf') – Extension to use for figures, which determines the file type.

  • SEQUENTIAL (bool, default=1) – Whether to plot points by index or hours relative to a reference time (J2000).

  • coeffPath (char, 1xG, default='modelCoeffs') – Directory containing model coefficients files.

  • FULLORBITS (bool, default=1) – Whether to evaluate goodness of fit from full-orbit data in System III coordinates beyond some threshold distance rMinMoon_RP. Independent of FLYBYS.

  • FLYBYS (bool, default=0) – Whether to evaluate goodness of fit from flyby data in moon coordinates. Measurements are only used if they are beyond rMinMoon_RP away from the target moon. Independent of FULLORBITS.

  • JUNOTOO (bool, default=1) – Whether to include Juno flyby data if FLYBYS is also true. Currently, only Ganymede flyby data is implemented.

CompareSatModels()

comparison.CompareSatModels(LIVE_PLOTS, LOAD_PDS_ASCII, yearRange, RELATIVE_t, RELATIVE_r, scName, SEQUENTIAL, coeffPath, figDir, figXtn, magDataMat)

Compare magnetic field measurements from spacecraft near Saturn against each implemented magnetic field model.

Datasets:

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • LOAD_PDS_ASCII (bool, default=0) – Whether to load in .TAB files downloaded from PDS (true) or use pre-converted and compressed .mat summary of just the important bits (false).

  • yearRange (int, 1xG, default=4:17) – Years over which to compare Cassini data. Default includes all measurements.

  • scName (string, 1xS, default=["Cassini"]) – Spacecraft name for which magnetic field data will be compared against implemented models. A directory must exist with each name in the MAG directory within the top-level PlanetMag directory. These directories will be searched for data files with the .tab extension, and each of these files will be loaded.

  • SEQUENTIAL (bool, default=0) – Whether to plot points by index or hours relative to a reference time (typically closest approach).

  • coeffPath (char, 1xC, default='modelCoeffs') – Directory containing model coefficients files.

  • figDir (char, 1xD, default='figures') – Directory to use for output figures.

  • figXtn (char, 1xE, default='pdf') – Extension to use for figures, which determines the file type.

  • magDataMat (char, 1xF, default='MAG/scName/ALL_FGM_KRTP_1M') – File path to use for save/reload of PDS data in .mat file.

  • RELATIVE_t (bool, default=0) – Whether to plot points relative to the start of the input time series. Only has an effect when SEQUENTIAL = 0.

  • RELATIVE_r (bool, default=0) – Whether to plot points relative to distance from the parent planet. Overrides SEQUENTIAL and RELATIVE_t.

CompareUraModels()

comparison.CompareUraModels(LIVE_PLOTS, scName, SEQUENTIAL, coeffPath, figDir, figXtn)

Compare magnetic field measurements from spacecraft near Uranus against each implemented magnetic field model.

Datasets:

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • scName (string, default="Voyager 2") – Spacecraft name for which magnetic field data will be compared against implemented models. A directory must exist with this name in the MAG directory within the top-level PlanetMag directory. This directory will be searched for body-specific data files, and each of these files will be loaded.

  • SEQUENTIAL (bool, default=0) – Whether to plot points by index or hours relative to a reference time (typically closest approach).

  • coeffPath (char, 1xC, default='modelCoeffs') – Directory containing model coefficients files.

  • figDir (char, 1xD, default='figures') – Directory to use for output figures.

  • figXtn (char, 1xE, default='pdf') – Extension to use for figures, which determines the file type.

CompareNepModels()

comparison.CompareNepModels(LIVE_PLOTS, scName, SEQUENTIAL, coeffPath, figDir, figXtn)

Compare magnetic field measurements from spacecraft near Neptune against each implemented magnetic field model.

Datasets:

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • scName (string, default="Voyager 2") – Spacecraft name for which magnetic field data will be compared against implemented models. A directory must exist with this name in the MAG directory within the top-level PlanetMag directory. This directory will be searched for body-specific data files, and each of these files will be loaded.

  • SEQUENTIAL (bool, default=0) – Whether to plot points by index or hours relative to a reference time (typically closest approach).

  • coeffPath (char, 1xC, default='modelCoeffs') – Directory containing model coefficients files.

  • figDir (char, 1xD, default='figures') – Directory to use for output figures.

  • figXtn (char, 1xE, default='pdf') – Extension to use for figures, which determines the file type.

Spherical harmonics validation

comparison.OutputHEALpixTo_n10(hpDir, hpFname, outDir, outFbase)

Evaluates intermediate functions for each n,m on a HEALpix map and prints to disk.

Prints an evaluation of Legendre polynomials and their derivatives on a HEALpix map, for validation purposes. The HEALpix map must be supplied in a text file at the specified location. All harmonics are mapped, from n=1 to n=10.

Parameters:

  • hpDir (char, 1xC, default=fullfile('~', 'MoonMag', 'outData')) – Directory containing a file with pixel locations on a HEALpix grid where function outputs are to be compared.

  • hpFname (char, 1xD, default='healpix_locs.txt') – File name where HEALpix locations are stored.

  • outDir (char, 1xE, default='out') – Directory where a file with function outputs will be written.

  • outFbase (char, 1xF, default='pureHarmMap_') – File name pattern for function outputs.

  • ghVal (double, default=1.0) – Common value for g and h in gauss used in MoonMag and PlanetMag intermediate function evaluation.

Basic testing

test.PMtest(LIVE_PLOTS, nptsApprox)

Test script to run each focus feature of PlanetMag to check for errors.

Parameters:

  • LIVE_PLOTS (bool, default=0) – Whether to load interactive figure windows for plots (true) or print them to disk (false).

  • nptsApprox (int, default=30000) – Default number of points to use in PlanetMag(). This default is much less than that in PlanetMag() because this function is primarily intended only for smoke testing.

Note

Setting LIVE_PLOTS to true will use a lot of system memory, causing a freeze if insufficient memory is available.