This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Sep 23 18:17:45 2025.

# Directory Listing of Routines

# projects/maven/maven_orbit_tplot

- HYBRID_ORBIT
  Plots the MAVEN orbit over a hybrid model of the Mars-solar wind interaction.
- MAG_MOLA_ORBIT
  Plots a set of [longitude,latitude] positions over a MAG-MOLA
- MAG_NPOLE_ORBIT
  Plots a set of [longitude,latitude] positions over a polar MAG map.
- MAVEN_ORBIT_BETA
  Calculates the MAVEN orbit beta angle, which is the angle between
- MAVEN_ORBIT_COMMON
  Common block definition for maven_orbit_tplot and associated routines.
- MAVEN_ORBIT_EPH
  Returns the MAVEN spacecraft ephemeris, consisting of the MSO and GEO state
- MAVEN_ORBIT_MAKEEPH
  Generates MAVEN spacecraft state vectors using the SPICE Icy toolkit.
- MAVEN_ORBIT_MOVIE
  3D visualization of MAVEN orbit using IDL 8 new graphics
- MAVEN_ORBIT_OPTIONS
  Stores a structure of MAVEN_ORBIT keyword options and provides
- MAVEN_ORBIT_PREDICT
  Specialized version of maven_orbit_tplot that makes predict ephemeris
- MAVEN_ORBIT_SNAP
  After running maven_orbit_tplot, this routine plots the orbit as viewed
- MAVEN_ORBIT_TPLOT
  Loads MAVEN ephemeris information, currently in the form of IDL save files produced
- MAVEN_ORBIT_UPDATE
  Updates the "current" spacecraft ephemeris using SPICE.
- MHD_ORBIT
  Plots
- MVN_EXO_BAR
  Creates a colored bar indicating when the spacecraft is below
- MVN_FLYZ_BAR
  Creates a bar indicating planned times of fly-plus-Z. Time ranges
- MVN_MARS_LOCALTIME
  Uses SPICE to determine the local solar time on Mars at a given longitude
- MVN_MARS_TERMINATOR
  Given a time, uses SPICE to determine the location of the
- MVN_SUN_BAR
  Creates a colored bar indicating sun/shadow. Assumes that
- PARABOLA_VERTEX
  Calculates the vertex of the parabola defined by three points.
- TIME_TO_PERIAPSIS
  Calculates the time needed for the spacecraft to go from periapsis

# Routine Descriptions

## HYBRID_ORBIT

[Next Routine] [List of Routines]

    PROCEDURE:   hybrid_orbit
    PURPOSE:
      Plots the MAVEN orbit over a hybrid model of the Mars-solar wind interaction.

    USAGE:
      hybrid_orbit, lon, lat

    INPUTS:
           lon:       East longitude (0 to 360 degrees).

           lat:       Latitude (-90 to 90 degrees).

                      Note: lon and lat must have the same number
                            of elements.

    KEYWORDS:
           PSYM:      Symbol type (same as for plot).

           LSTYLE:    Line style (same as for plot).

           COLOR:     Line/symbol color (same as for plot).

           RESET:     Read in the MAG-MOLA image and calculate the
                      plot size and position.

           MONITOR:   Place snapshot window in this monitor.  Only works if
                      monitor configuration is defined (see win.pro).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-27 11:42:58 -0700 (Wed, 27 Jul 2022) $
     $LastChangedRevision: 30964 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/hybrid_orbit.pro $

    CREATED BY:	David L. Mitchell  04-02-03

(See projects/maven/maven_orbit_tplot/hybrid_orbit.pro)

## MAG_MOLA_ORBIT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mag_mola_orbit
    PURPOSE:
      Plots a set of [longitude,latitude] positions over a MAG-MOLA
      map.

    USAGE:
      mag_mola_orbit, lon, lat

    INPUTS:
           lon:       East longitude (0 to 360 degrees).

           lat:       Latitude (-90 to 90 degrees).

                      Note: lon and lat must have the same number
                            of elements.

    KEYWORDS:
           PSYM:       Symbol type (same as for plot).

           NOSYM:      Do not plot symbol at s/c position.

           LSTYLE:     Line style (same as for plot).

           COLOR:      Line/symbol color (same as for plot).

           RESET:      Read in the MAG-MOLA or MAG-LANGLAIS image and
                       calculate the plot size and position.

           NOERASE:    Do not refresh the plot for each [lon, lat] point.

           BIG:        Use a 1000x500 MAG-MOLA image.

           DBR:        Use a 1000x500 dBr/dt image.
                       (Note: dBr/dt is approx. the same as dBr/dlat.)

           LANGLAIS:   Use a variable size map of the radial component of
                       the Langlais spherical harmonic expansion evaluated
                       at a constant altitude:
                           1 -> 160 km  (approx. electron footpoint altitude)
                           2 -> 250 km

           LLIM:       A structure of keywords for controlling the window
                       size and plotting options for the Langlais map.  This
                       allows you to zoom in on a region.  Any keywords accepted
                       by CONTOUR and SPECPLOT are allowed.  Only the X dimension
                       of the window (LLIM.XSIZE) is used.  The Y dimension is
                       calculated so that the pixels per degree is the same in
                       longitude and latitude.  Default contour levels (LLIM.LEVELS)
                       are [-70,-50,-30,-10,10,30,50,70].

                       You can also specify tagname WASH, which controls how many
                       color indices away from light gray to extend the red-to-blue
                       shading for the Langlais map.  Default = 50.  Smaller values
                       make the shading more washed out.  Set LLIM.WASH=0 to show
                       contour map without shading.

                       Use tagname COMPONENT to specify which component of the
                       magnetic field to plot: 'BR' (radial), 'BN' (north),
                       'BE' (east), 'BH' (horizontal), or 'B' (magnitude).
                       Default: LLIM.COMPONENT='BR'.

           BAZEL:      If set to a 3xN element array of the magnetic field in
                       the local azimuth-elevation frame, plot a magnetic field
                       azimuth whisker with the origin at the spacecraft location.
                       All whiskers are the same length, so they act as "compass
                       needles".

           CAZEL:      If set, the BAZEL whisker colors are set according to a
                       rainbow table, where blue = radial out, and red = radial in.
                       If not set, all the whiskers are same color as the symbols.
                       Default = 1.

           BSCALE:     Sets the scale of the BAZEL whiskers.  Default = 1.

           TERMINATOR: Overlay the terminator at the time specified by this
                       keyword.

           SHADOW:     If TERMINATOR is set, specifies which "terminator" to
                       plot.
                          0 : Optical shadow boundary at surface (default).
                          1 : Optical shadow at electron exobase (170 km).

           SITES:      A 2 x N array of surface locations to plot.

           SLAB:       Text labels for each of the sites.

           SCOL:       Color for each of the sites.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-22 12:45:24 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33647 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mag_mola_orbit.pro $

    CREATED BY:	David L. Mitchell  04-02-03

(See projects/maven/maven_orbit_tplot/mag_mola_orbit.pro)

## MAG_NPOLE_ORBIT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mag_npole_orbit
    PURPOSE:
      Plots a set of [longitude,latitude] positions over a polar MAG map.

    USAGE:
      mag_Npole_orbit, lon, lat

    INPUTS:
           lon:       East longitude (0 to 360 degrees).

           lat:       Latitude (-90 to 90 degrees).

                      Note: lon and lat must have the same number
                            of elements.

    KEYWORDS:
           PSYM:      Symbol type (same as for plot).

           LSTYLE:    Line style (same as for plot).

           COLOR:     Line/symbol color (same as for plot).

           RESET:     Read in the MAG-MOLA image and calculate the
                      plot size and position.

           NOERASE:   Do not refresh the plot for each [lon, lat] point.

           TERMINATOR: Overlay the terminator.

           SHADOW:     If TERMINATOR is set, specifies which "terminator" to
                       plot.
                          0 : Optical shadow boundary at surface.
                          1 : Optical shadow boundary at s/c altitude.
                          2 : EUV shadow boundary at s/c altitude.

           MONITOR:   Place snapshot window in this monitor.  Only works if
                      monitor configuration is defined (see win.pro).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-27 11:42:58 -0700 (Wed, 27 Jul 2022) $
     $LastChangedRevision: 30964 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mag_npole_orbit.pro $

    CREATED BY:	David L. Mitchell  04-02-03

(See projects/maven/maven_orbit_tplot/mag_npole_orbit.pro)

## MAVEN_ORBIT_BETA

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_beta
    PURPOSE:
      Calculates the MAVEN orbit beta angle, which is the angle between
      the Sun direction and the orbit plane [-90 to 90 degrees].  When beta
      is positive, the orbit normal (P x V, where P is position and V is
      velocity) points toward the Sun-facing hemisphere.

      This routine requires SPICE.

    USAGE:
      maven_orbit_beta

    INPUTS:
           time:      [Optional] One or more UTC times, in any format accepted by
                      time_double.  If not specified and MISSION is not set, then
                      try to get the periapsis times for all MAVEN orbits within
                      the tplot timespan (TRANGE_FULL).

    KEYWORDS:
           RESULT:    Structure containing UTC (x) and beta angle (y).  Works as a
                      tplot variable.

           MISSION:   Ignore the time input, and calculate beta at periapsis for
                      every orbit in the mission that has SPK coverage (including
                      up to several weeks into the future).

                      Warning: This will likely require SPICE to be reinitialized.

           TPLOT:     Store the tplot variable and set some tplot options.
                      Default = 1.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-09-15 11:55:02 -0700 (Wed, 15 Sep 2021) $
     $LastChangedRevision: 30296 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_beta.pro $

(See projects/maven/maven_orbit_tplot/maven_orbit_beta.pro)

## MAVEN_ORBIT_COMMON

[Previous Routine] [Next Routine] [List of Routines]

    COMMON BLOCK:   maven_orbit_common
    PURPOSE:
      Common block definition for maven_orbit_tplot and associated routines.

    USAGE:
      To be used inside routines that want access to the common block.  Put this
      line near the top:

        @maven_orbit_common

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-07-07 10:47:04 -0700 (Fri, 07 Jul 2023) $
     $LastChangedRevision: 31941 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_common.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/maven_orbit_tplot/maven_orbit_common.pro)

## MAVEN_ORBIT_EPH

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:   maven_orbit_eph
    PURPOSE:
      Returns the MAVEN spacecraft ephemeris, consisting of the MSO and GEO state
      vectors along with some derived quantities: altitude, GEO longitude, GEO
      latitude, and solar zenith angle.  The reference surface for calculating
      altitude ("datum") is specified.

      The coordinate frames are:

       GEO = body-fixed Mars geographic coordinates (non-inertial) = IAU_MARS

                  X ->  0 deg E longitude, 0 deg latitude
                  Y -> 90 deg E longitude, 0 deg latitude
                  Z -> 90 deg N latitude (= X x Y)
                  origin = center of Mars
                  units = kilometers

       MSO = Mars-Sun-Orbit coordinates (approx. inertial)

                  X -> from center of Mars to center of Sun
                  Y -> opposite to Mars' orbital angular velocity vector
                  Z = X x Y
                  origin = center of Mars
                  units = kilometers

      The returned structure contains the following tags:

           TIME            DOUBLE    unix time (essentially the same as UTC)
           MSO_X           FLOAT     position in the MSO frame (km)
           MSO_V           FLOAT     velocity in the MSO frame (km/s)
           GEO_X           FLOAT     position in the IAU_MARS frame (km)
           GEO_V           FLOAT     velocity in the IAU_MARS frame (km/s)
           R               FLOAT     radial distance from Mars' center (km)
           R_M             FLOAT     Mars volumetric mean radius (3389.50 km)
           VMAG_MSO        FLOAT     magnitude of MSO_V (km/s)
           VMAG_GEO        FLOAT     magnitude of GEO_V (km/s)
           ALT             DOUBLE    altitude relative to the DATUM (km)
           LON             DOUBLE    IAU_MARS longitude of spacecraft (deg)
           LAT             DOUBLE    IAU_MARS latitude of spacecraft (deg)
           DATUM           STRING    reference surface* for calculating altitude
           SZA             DOUBLE    solar zenith angle (deg)
           LST             DOUBLE    local solar time (0-24 Mars hours)
           SLON            DOUBLE    IAU_MARS longitude of sub-solar point (deg)
           SLAT            DOUBLE    IAU_MARS latitude of sub-solar point (deg)

        * The datum can be one of: 'sphere', 'ellipsoid', 'areoid', or 'surface'.
          See mvn_altitude.pro for details.  The default is 'ellipsoid'.

    USAGE:
      eph = maven_orbit_eph()

    INPUTS:
           none

    KEYWORDS:
           none

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-07-07 10:48:05 -0700 (Fri, 07 Jul 2023) $
     $LastChangedRevision: 31942 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_eph.pro $

(See projects/maven/maven_orbit_tplot/maven_orbit_eph.pro)

## MAVEN_ORBIT_MAKEEPH

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_makeeph
    PURPOSE:
      Generates MAVEN spacecraft state vectors using the SPICE Icy toolkit.
      The result is returned in a structure with the following tags:

        T              Time (UTC): number of seconds since 1970-01-01
        X              X position coordinate (km)
        Y              Y position coordinate (km)
        Z              Z position coordinate (km)
        VX             X velocity component (km/s)
        VY             Y velocity component (km/s)
        VZ             Z velocity component (km/s)

    USAGE:
      maven_orbit_makeeph, frame=frame, origin=origin, eph=eph
    INPUTS:

    KEYWORDS:
           TSTEP:     Time step (seconds).  Default = 60.

           EPH:       Named variable to hold the ephemeris structure.

           FRAME:     Coordinate frame.  Type mvn_frame_name(/list) for a full list.

           ORIGIN:    Origin of coordinate frame.  Can be "Mars", "Phobos", or
                      "Deimos".  Default = "Mars".

           TSTART:    Start time for output save file ephemeris.

           TSTOP:     Stop time for output save file ephemeris.

           MVN_SPK:   Include the specified spacecraft kernel(s) in the loadlist.
                      Full path and filename is required.  Used for the long-range
                      predict kernels, such as the design reference mission (DRM).

           UNLOAD:    Unload all kernels (cspice_kclear) after completion.

           RESET:     Unload all kernels (cspice_kclear) and start fresh.

           STAT:      Return statistics of ephemeris coverage.  (Useful to determine
                      the boundary between reconstructions and predictions.)

           OBJECT:    By default, this routine uses the name 'MAVEN' (id = -202) for
                      the spacecraft, which is the definition used by NAIF.  It is
                      possible for an ephemeris to use a non-standard object name/id.
                      Use this keyword to override the default and specify the non-
                      standard name or id.  Example: OBJECT='-200000'.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-07-05 13:14:34 -0700 (Thu, 05 Jul 2018) $
     $LastChangedRevision: 25439 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_makeeph.pro $

    CREATED BY:	David L. Mitchell  2014-10-13

(See projects/maven/maven_orbit_tplot/maven_orbit_makeeph.pro)

## MAVEN_ORBIT_MOVIE

[Previous Routine] [Next Routine] [List of Routines]

     PROCEDURE:
           maven_orbit_movie
     PURPOSE:
           3D visualization of MAVEN orbit using IDL 8 new graphics
     CALLING SEQUENCE:
           timespan,'2015-01-01'
           maven_orbit_movie, dim=[640,480], rate=3600
     OPTIONAL KEYWORDS:
           TRANGE: time range (if not present then timerange() is called)
           DIMENSIONS: [width,height] (Def: half of the screen size)
           MOVIENAME: name of the output movie file (Def: 'maven_orbit.mp4')
           RATE: speed of the movie (Def: 4*3600 = 4 hr/sec)
           FPS: frames per sec of the movie (Def: 20)
           ZOOMSCALE: zoom in/out scale (Def: 1.5)
           FONT_SIZE: font size of the time stamp (Def: 24)
           BOXSIZE: minmax of the 3D box in km (Def: [-3.,3.]*R_M)
           BCMODEL: specifies crustal field model (Def: 'morschhauser')
           SNAP: if set, generate a snapshot instead of a movie
           TSNAP: time of the snapshot (Def: start time of timerange())
           FIGNAME: name of the snapshot file (Def: 'maven_orbit.png')
                    most file formats are acceptable
                    (http://www.exelisvis.com/docs/save_method.html)
           CLOSEWIN: close the graphic window when finished
     CREATED BY:
           Yuki Harada on 2015-11-04

     $LastChangedBy: haraday $
     $LastChangedDate: 2021-10-17 22:40:06 -0700 (Sun, 17 Oct 2021) $
     $LastChangedRevision: 30373 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_movie.pro $

(See projects/maven/maven_orbit_tplot/maven_orbit_movie.pro)

## MAVEN_ORBIT_OPTIONS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_options
    PURPOSE:
      Stores a structure of MAVEN_ORBIT keyword options and provides
      a mechanism for changing those options.  Keywords set by this
      routine are persistent defaults in the MAVEN_ORBIT routines.
      They can be overridden by explicitly setting keywords in those
      routines.

      Call this routine from your idl_startup.pro to customize default
      options for yourself.

    USAGE:
      maven_orbit_options, key

    INPUTS:
           key:           Structure containing keyword(s) for MAVEN_ORBIT_TPLOT
                          and MAVEN_ORBIT_SNAP.  Unrecognized keywords can be
                          added to the structure but will subsequently be ignored.

                          {KEYWORD: value, KEYWORD: value, ...}

    KEYWORDS:
           GET:           Set this to a named variable to return the current
                          default keyword structure (after changes, if any).

           REPLACE:       If this keyword is set, then the input structure
                          replaces any existing structure.  Otherwise, the
                          input structure is merged with any existing one.

           DELETE:        An array of tag names to delete from the default
                          keyword structure.

           RESET:         Reset the default structure to something universally
                          benign: {WSCALE: 1.}

           LIST:          List the current keyword default structure.  This is
                          the default when this routine is called without any
                          inputs or keywords.

           SILENT:        Suppresses output.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-03-22 19:18:19 -0700 (Mon, 22 Mar 2021) $
     $LastChangedRevision: 29805 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_options.pro $

(See projects/maven/maven_orbit_tplot/maven_orbit_options.pro)

## MAVEN_ORBIT_PREDICT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_predict
    PURPOSE:
      Specialized version of maven_orbit_tplot that makes predict ephemeris
      plots suitable for short- and long-term planning, including identification
      of Fly-Y/Z calibration opportunities, conjunction periods, and dust storm
      seasons.

      Warnings:

       (1) This routine will reset timespan to cover the specified extended
           ephemeris, overwriting any existing timespan.  This will affect any
           routines that use timespan for determining what data to process.

       (2) This routine can reset the SPICE loadlist.

       (3) The extended ephemerides span about a decade, with peak RAM consumption
           of ~6 GB.  Most modern computers have at least 16 GB of RAM, but this is
           something to be aware of.

      It's best to use this routine in its own IDL session.

    USAGE:
      maven_orbit_predict, extended=1, eph=eph

    INPUTS:

    KEYWORDS:
           EXTENDED: If set to a value from 1 to 8, loads one of eight long-term predict
                     ephemerides.  Most have a density scale factor (DSF) of 2.5, which
                     is a weighted average over several Mars years.  They differ in the
                     number and timing of apoapsis, periapsis, and inclination maneuvers
                     (arm, prm, inc) and total fuel usage (meters per second, or ms).
                     The date when the ephemeris was generated is given at the end of
                     the filename (YYMMDD).  More recent dates better reflect actual
                     past perfomance and current mission goals.  When in doubt, use the
                     most recent.

                       0 : use timerange() to load short-term predicts
                       1 : trj_orb_250407-350702_dsf2.0_prm_4.4ms_250402.bsp
                       2 : trj_orb_240821-331231_dsf2.0_prm_4.4ms_240820.bsp
                       3 : trj_orb_230322-320101_dsf2.5-arm-prm-inc-17.5ms_230320.bsp
                       4 : trj_orb_230322-320101_dsf1.5-prm-3.5ms_230320.bsp
                       5 : trj_orb_220810-320101_dsf2.5_arm_prm_19.2ms_220802.bsp
                       6 : trj_orb_220101-320101_dsf2.5_arms_18ms_210930.bsp
                       7 : trj_orb_220101-320101_dsf2.5_arm_prm_13.5ms_210908.bsp
                       8 : trj_orb_210326-301230_dsf2.5-otm0.4-arms-prm-13.9ms_210330.bsp

                     Default = 1 (most recent long-term predict).

                     You can set this keyword to zero, so that none of the extended predicts
                     is used.  In that case, the routine will attempt to load ephemeris data
                     based on the value of timerange().  This can be used to load the short-
                     term predict ephemeris, which provides a more accurate estimate of how
                     the orbit will evolve over the next 3-4 months.

           EPH:      Named variable to hold the MSO and GEO state vectors along with
                     some calculated values.

           LINE_COLORS: Line color scheme for altitude panel.  This can be an integer [0-10]
                     to select one of 11 pre-defined line color schemes.  It can also be array
                     of 24 (3x8) RGB values: [[R,G,B], [R,G,B], ...] that defines the first 7
                     colors (0-6) and the last (255).  For details, see line_colors.pro and
                     color_table_crib.pro.  Default = 5.

           COLORS:   An array with up to 3 elements to specify color indices for the
                     plasma regimes: [sheath, pileup, wake].  Defaults are:

                       regime       index       LINE_COLORS=5
                       -----------------------------------------
                       sheath         4         green
                       pileup         5         orange
                       wake           2         blue
                       -----------------------------------------

                     The colors you get depend on your line color scheme.  The solar wind
                     is always displayed in the foreground color (usually white or black).

                     Note: Setting LINE_COLORS and COLORS here is local to this routine and
                           affects only the altitude panel.

           PDS:      Plot vertical dashed lines separating the PDS release dates.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-25 09:53:09 -0700 (Sun, 25 May 2025) $
     $LastChangedRevision: 33337 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_predict.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/maven_orbit_tplot/maven_orbit_predict.pro)

## MAVEN_ORBIT_SNAP

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_snap
    PURPOSE:
      After running maven_orbit_tplot, this routine plots the orbit as viewed
      along each of the MSO axes.  Optionally, the orbit can be superimposed on
      models of the solar wind interaction with Mars.  Also optionally, the
      position of the spacecraft can be plotted (in GEO coordinates) on a map
      of Mars' topography and magnetic field based on MGS MOLA and MAG data.

      All plots are generated at times selected with the cursor on the TPLOT
      window.  Hold down the left mouse button and drag for a movie effect.

    USAGE:
      maven_orbit_snap
    INPUTS:

    KEYWORDS:
           PREC:     Plot the position of the spacecraft at the selected time,
                     superimposed on the orbit.  Otherwise, the periapsis
                     location for each orbit is plotted.  For time ranges less
                     than seven days, the default is PREC = 1.  Otherwise the
                     default is 0.

           MHD:      Plot the orbit superimposed on an image of an MHD simulation
                     of the solar wind interaction with Mars (from Ma).
                       1 : Plot the XY projection
                       2 : Plot the XZ projection

           HYBRID:   Plot the orbit superimposed on an image of a hybrid simulation
                     of the solar wind interaction with Mars (from Brecht).
                       1 : Plot the XZ projection
                       2 : Invert Z in the model, then plot the XZ projection

           LATLON:   Plot MSO longitudes and latitudes of periapsis (PREC=0) or
                     the spacecraft (PREC=1) in a separate window.

           CYL:      Plot MSO cylindrical projection (x vs. sqrt(y^2 + z^2)).

           XZ:       Plot only the XZ projection (view from side).

           XY:       Plot only the XY projection (view from ecliptic north).

           YZ:       Plot only the YZ projection (view from Sun)

           MARS:     Plot the position of the spacecraft (PREC=1) or periapsis
                     (PREC=0) on an image of Mars topography (colors from MOLA)
                     and radial magnetic field (contours from Connerney et al.
                     2001).  Alternatively, use an image of dBr/dt that better
                     filters out solar wind influences (Connerney et al. 2004),
                     on top of a greyscale topo map with elevation contours.
                       1 : Use a small MAG-MOLA image
                       2 : Use a large MAG-MOLA image
                       3 : Use a large dBr-topology image
                       4 : Use a Langlais Br at 160 km image (electron footpoint)
                       5 : Use a Langlais Br at 250 km image (less detail)

           LLIM:     Limits structure for the Langlais image.  Use this to set
                     the window size (xsize), xrange, yrange, xticks, yticks, etc.
                     Any keywords accepted by CONTOUR and SPECPLOT are allowed.
                     The image is generated dynamically, so you can zoom into a
                     particular region.  When specifying window size, only the
                     horizontal dimension (xsize) is used.  The vertical dimension
                     (ysize) is calculated so that the pixels/degree is the same
                     in both X and Y.

                     The Langlais map is shown as a shaded contour plot.  Default
                     contour levels (LLIM.LEVELS) are [10,30,50,70] nT.  Positive
                     contours (+LLIM.LEVELS) are blue, and negative contours
                     (-LLIM.LEVELS) are red.  Shading is a washed-out red-to-blue
                     color scale to allow overlays.  You can control this by setting
                     the tag WASH in the LLIM structure:

                       LLIM.WASH > 50  (more color)
                       LLIM.WASH = 50  (default)
                       LLIM.WASH < 50  (less color)
                       LLIM.WASH =  0  (no color, contours only)

                     You can choose the magnetic field vector component to plot:

                       LLIM.COMPONENT = 'BR'  ; radial component (default)
                       LLIM.COMPONENT = 'BT'  ; north component
                       LLIM.COMPONENT = 'BP'  ; east component
                       LLIM.COMPONENT = 'BH'  ; horizontal component
                       LLIM.COMPONENT = 'B'   ; magnitude

           NPOLE:    Plot the position of the spacecraft (PREC=1) or periapsis
                     (PREC=0) on a north polar projection (lat > 55 deg).  The
                     background image is the north polar magnetic anomalies observed
                     at 180-km altitude by MGS (from Acuna).

           ALT:      If set and keywords MARS and/or NPOLE are set, then indicate the
                     spacecraft altitude next its symbol.

           TERMINATOR: Overplot the terminator and sub-solar point onto the Mars
                       topography plots (see MARS and NPOLE above).  SPICE must be
                       installed and initialized (e.g., mvn_swe_spice_init) before
                       using this keyword.  The following values are recognized:
                          0 : Do not plot any shadow boundary.  (default)
                          1 : Plot optical shadow boundary at surface.
                          2 : Plot optical shadow at electron exobase (170 km).

           NOERASE:  Don't erase previously plotted positions.  Can be used to build
                     up complex plots.

           NODOT:    Do not plot a filled circle at periapsis or spacecraft location.

           NOORB:    Do not plot the orbit.

           SCSYM:    Symbol for the spacecraft.  Default = 1 (plus symbol).  Filled
                     circles are obtained with SCSYM = 8.

           RESET:    Initialize all plots.

           COLOR:    Symbol color index.

           SSIZE:    Symbol size.

           KEEP:     Do not kill the plot windows on exit.

           TIMES:    An array of times for snapshots.  Snapshots are overlain onto
                     a single version of the plot.  For evenly spaced times, this
                     produces a "spirograph" effect.  This overrides the interactive
                     entry of times with the cursor.  Sets KEEP and NOERASE.  Also
                     sets RESET if necessary.

           TCOLORS:  Color index for every element of TIMES.

           BDIR:     Set keyword to show magnetic field direction in three planes,
                     In each plane, the same two components of B in MSO coordinates
                     are shown, i.e. in XY plane, plotting Bx-By. The color shows
                     if the third component (would be Bz in XY plane) is positive
                     (red) or negative (blue).

           BCLIP:    Maximum amplitude for plotting B whisker.

           MSCALE:   To change the scale/length of magnetic field whiskers, the default
                     value is set to 0.05

           VDIR:     Set keyword to a tplot variable containing MSO vectors for a whisker
                     plot (like BDIR).

           VCLIP:    Maximum amplitude for plotting V whisker.

           VRANGE:   Time range for plotting vectors.

           VSCALE:   To change the scale/length of vector lines, the default value is
                     set to 0.05.

           BAZEL:    Show the azimuth of the magnetic field vector at the spacecraft
                     location on the Mars topography-crustal magnetic field plot.
                     Whiskers are a fixed length and do not scale with the field
                     amplitude or projection.  The value of this keyword is used to
                     scale the whisker lengths.

           CAZEL:    If set, the BAZEL whisker colors are set according to the current
                     color table.  For table 1074 (reverse): blue = radial out, and
                     red = radial in.  If not set, all the whiskers are the same color
                     as the spacecraft symbol (see keyword COLOR).  Default = 0.

           THICK:    Line thickness.

           WSCALE:   Scale factor for sizing plot windows.  Default = 1.
                     Has no effect when plotting orbit projections over images, which
                     have fixed sizes.

           MAGNIFY:  Synonym for WSCALE.  (WSCALE takes precedence.)

           NOLABEL:  Omit text labels showing altitude and solar zenith angle.

           PSNAME:   Name of a postscript plot.  Works only for orbit plots.

           LANDERS:  Plot the locations of landers.  Can also be an array of surface
                     locations [lon1, lat1, lon2, lat2, ...] in the IAU_Mars frame.
                     (east longitude, units = deg).  Longitude range can be [-180, 180]
                     or [0, 360].  Default is all existing landing sites, from
                     Viking 1 to present.

           SLAB:     Text labels for each of the landers.  If LANDERS is a scalar,
                     then this provides a 1- or 2-character label for each lander.
                     If LANDERS is an 2N array, SLAB should be an N-element string
                     array.  Set SLAB to zero to disable text labels and just plot
                     symbols instead.  Text labels are centered in longitude with
                     the baseline at latitude.

           SCOL:     Color(s) for the lander labels or symbols.  If there are more
                     landers than colors, then additional landers are all given the
                     last color.  Default is 6 (red) for all.

           IONO:     Plot a dashed circle at this altitude.

           ARANGE:   Altitude range (km) for plotting orbit segments.  Both inbound
                     and outbound segments are plotted.

           BLACK:    Force a black background for the orbit projection plots so it's
                     easier to see the colors.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-22 12:44:04 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33646 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_snap.pro $

    CREATED BY:	David L. Mitchell  10-28-11

(See projects/maven/maven_orbit_tplot/maven_orbit_snap.pro)

## MAVEN_ORBIT_TPLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_tplot
    PURPOSE:
      Loads MAVEN ephemeris information, currently in the form of IDL save files produced
      with maven_spice_eph.pro, and plots the spacecraft trajectory as a function of time
      (using tplot).  The plots are color-coded according to the nominal plasma regime,
      based on conic fits to the bow shock and MPB from Trotignon et al. (PSS 54, 357-369,
      2006).  The wake region is either the EUV or optical shadow in MSO coordinates:
      (sqrt(y*y + z*z) < Rm ; x < 0), where Rm is the Mars radius appropriate for optical
      or EUV wavelengths.

      The available coordinate frames are:

       GEO = body-fixed Mars geographic coordinates (non-inertial) = IAU_MARS

                  X ->  0 deg E longitude, 0 deg latitude
                  Y -> 90 deg E longitude, 0 deg latitude
                  Z -> 90 deg N latitude (= X x Y)
                  origin = center of Mars
                  units = kilometers
                  full rotation once per Mars day

       MSO = Mars-Sun-Orbit coordinates (approx. inertial)

                  X -> from center of Mars to center of Sun
                  Y -> opposite to Mars' orbital angular velocity vector
                  Z = X x Y
                  origin = center of Mars
                  units = kilometers
                  full rotation once per Mars year

    USAGE:
      maven_orbit_tplot
    INPUTS:

    KEYWORDS:
           TRANGE: A date or date range in any format accepted by time_double.
                   Only the date is used (hh:mm:ss is ignored).  If not specified,
                   then try to get the time range from tplot_com (TRANGE_FULL).
                   If that fails, then prompt the user for the time range.

                   Ephemeris data are loaded from one day before to one day after
                   TRANGE.  This ensures that interpolation is well defined even at
                   the edges of your date range.

           RESET_TRANGE: OBSOLETE.  This keyword has no effect.  Timespan is reset
                     only when EXTENDED is set (see below).

           TIMECROP: OBSOLETE.  This keyword has no effect.

           NOCROP:   OBSOLETE.  This keyword has no effect.

           STAT:     Named variable to hold the plasma regime statistics.

           SWIA:     Calculate viewing geometry for SWIA, based on nominal s/c
                     pointing.

           DATUM:    String for specifying the datum, or reference surface, for
                     calculating altitude.  Can be one of "sphere", "ellipsoid",
                     "areoid", or "surface".  Default = 'ellipsoid'.
                     Minimum matching is used for this keyword.
                     See mvn_altitude.pro for more information.

           IALT:     Ionopause altitude.  Highly variable, but nominally ~400 km.
                     For display only - not included in statistics.  Default is NaN.

           SHADOW:   The shadow region is defined by the cylinder in the MSO frame
                     where X < 0 and sqrt(Y^2 + Z^2) < R_shadow.

                     Use this keyword to choose the Rsh:
                        0 : optical shadow (R_shadow = Mars radius)
                        1 : EUV shadow (R_shadow = Mars radius + 150 km)  <- default

           SEGMENTS: Plot nominal altitudes for orbit segment boundaries as dotted
                     horizontal lines.  Closely spaced lines are transitions, during
                     which time the spacecraft is reorienting.  The actual segment
                     boundaries vary with orbit period.

           RESULT:   Named variable to hold the MSO ephemeris with some calculated
                     quantities.  OBSOLETE.  Still works, but use keyword EPH instead.

           EPH:      Named variable to hold the MSO and GEO state vectors along with
                     some calculated values.

           CURRENT:  Load the ephemeris from MOI to the current date + 2 weeks.  This
                     uses reconstructed SPK kernels, as available, then predicts.
                     This is the default.  OBSOLETE.

           SPK:      String array with an even number of elements >= 2 containing the
                     names of the MSO and GEO save/restore ephemerides to use instead
                     of the standard set.  Multiple MSO and GEO files can be specified,
                     but each MSO file must have a corresponding GEO file.  (These are
                     made in pairs - see maven_orbit_makeeph).

                     Used for long range predict and special events kernels.  Replaces
                     keywords EXTENDED and HIRES.

           EXTENDED: If set to a value from 1 to 8, loads one of eight long-term predict
                     ephemerides.  Most have a density scale factor (DSF) of 2.5, which
                     is a weighted average over several Mars years.  They differ in the
                     number and timing of apoapsis, periapsis, and inclination maneuvers
                     (arm, prm, inc) and total fuel usage (meters per second, or ms).
                     The date when the ephemeris was generated is given at the end of
                     the filename (YYMMDD).  More recent dates better reflect actual
                     past perfomance and current mission goals.  When in doubt, use the
                     most recent.

                       0 : use timerange() to load short-term predicts
                       1 : trj_orb_250407-350702_dsf2.0_prm_4.4ms_250402.bsp
                       2 : trj_orb_240821-331231_dsf2.0_prm_4.4ms_240820.bsp
                       3 : trj_orb_230322-320101_dsf2.5-arm-prm-inc-17.5ms_230320.bsp
                       4 : trj_orb_230322-320101_dsf1.5-prm-3.5ms_230320.bsp
                       5 : trj_orb_220810-320101_dsf2.5_arm_prm_19.2ms_220802.bsp
                       6 : trj_orb_220101-320101_dsf2.5_arms_18ms_210930.bsp
                       7 : trj_orb_220101-320101_dsf2.5_arm_prm_13.5ms_210908.bsp
                       8 : trj_orb_210326-301230_dsf2.5-otm0.4-arms-prm-13.9ms_210330.bsp

                     Default = 0.

                     For short-term predictions (< 3-4 months in the future) it's better to
                     set the desired timespan and run this routine without setting EXTENDED.
                     That will load the short-term predict spk kernels, which are more
                     accurate than any of the above long-term predicts.

           HIRES:    OBSOLETE.  This keyword has no effect.

           LOADONLY: Create the TPLOT variables, but do not plot.

           NOLOAD:   Don't load or refresh the ephemeris information.  Just fill in any
                     keywords and exit.

           LINE_COLORS: Line color scheme for altitude panel.  This can be an integer [0-10]
                     to select one of 11 pre-defined line color schemes.  It can also be array
                     of 24 (3x8) RGB values: [[R,G,B], [R,G,B], ...] that defines the first 7
                     colors (0-6) and the last (255).  For details, see line_colors.pro and
                     color_table_crib.pro.  Default = 5.

           COLORS:   An array with up to 3 elements to specify color indices for the
                     plasma regimes: [sheath, pileup, wake].  Passed to maven_orbit_tplot.
                     Defaults are:

                       regime       index       LINE_COLORS=5
                       -----------------------------------------
                       sheath         4         green
                       pileup         5         orange
                       wake           2         blue
                       -----------------------------------------

                     The colors you get depend on your line color scheme.  The solar wind
                     is always displayed in the foreground color (usually white or black).

                     Note: Setting LINE_COLORS and COLORS here is local to this routine and
                           affects only the altitude panel.

           VARS:     Array of TPLOT variables created.

           NOW:      Plot a vertical dotted line at the current time.

           PDS:      Plot vertical dashed lines separating the PDS release dates.

           VERBOSE:  Verbosity level passed to mvn_pfp_file_retrieve.  Default = 0
                     (suppress most messages).  Try a value > 2 to see more
                     messages; > 4 for lots of messages.

                     Also used to control the verbosity of spd_download_plus by
                     temporarily setting the debug level for dprint to VERBOSE.

           CLEAR:    Clear the common block and exit.

           SAVE:     Make a save file for all tplot variables and the common block.

           RESTORE:  Restore tplot variables and the common block from a save file.

           MISSION:  Restore save files that span from Mars orbit insertion to the
                     present.  These files are refreshed periodically.  Together,
                     the save files are 17 GB in size (as of December 2024), so this
                     keyword is only useful for computers with sufficient memory.

                       Latest refresh: 2024-12-16
                       Range 1: 2014-09-21 to 2025-01-18
                                -- gap --
                       Range 2: 2025-02-01 to 2025-04-05

                     The first range is derived from reconstructed spk kernels plus
                     short-term predict kernels.  The second range is derived from
                     medium-term predict kernels.

                     Using the where command, you can identify times that meet an
                     arbitrary set of ephemeris conditions.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-22 12:33:28 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33644 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_tplot.pro $

    CREATED BY:	David L. Mitchell  10-28-11

(See projects/maven/maven_orbit_tplot/maven_orbit_tplot.pro)

## MAVEN_ORBIT_UPDATE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   maven_orbit_update
    PURPOSE:
      Updates the "current" spacecraft ephemeris using SPICE.

    USAGE:
      maven_orbit_update

    INPUTS:

    KEYWORDS:
           TSTEP:    Ephemeris time step (sec).  Default = 60 sec.

           REBUILD:  Normally, months containing only reconstructed kernels are not
                     updated.  Set this keyword to rebuild the entire database.

           TSTART:   Rebuild all files that contain data after this date.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-10-21 15:38:28 -0700 (Wed, 21 Oct 2020) $
     $LastChangedRevision: 29269 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/maven_orbit_update.pro $

    CREATED BY:	David L. Mitchell  2014-10-13

(See projects/maven/maven_orbit_tplot/maven_orbit_update.pro)

## MHD_ORBIT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mhd_orbit
    PURPOSE:
      Plots

    USAGE:
      mhd_orbit, lon, lat

    INPUTS:
           lon:       East longitude (0 to 360 degrees).

           lat:       Latitude (-90 to 90 degrees).

                      Note: lon and lat must have the same number
                            of elements.

    KEYWORDS:
           PSYM:      Symbol type (same as for plot).

           LSTYLE:    Line style (same as for plot).

           COLOR:     Line/symbol color (same as for plot).

           RESET:     Read in the MAG-MOLA image and calculate the
                      plot size and position.

           MONITOR:   Place snapshot window in this monitor.  Only works if
                      monitor configuration is defined (see win.pro).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-27 11:42:58 -0700 (Wed, 27 Jul 2022) $
     $LastChangedRevision: 30964 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mhd_orbit.pro $

    CREATED BY:	David L. Mitchell  04-02-03

(See projects/maven/maven_orbit_tplot/mhd_orbit.pro)

## MVN_EXO_BAR

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_exo_bar
    PURPOSE:
      Creates a colored bar indicating when the spacecraft is below
      the exobase.  Assumes that you have run maven_orbit_tplot first.

    USAGE:
      mvn_sun_bar

    INPUTS:

    KEYWORDS:
            ALT : Altitude of the exobase.  Default = 180 km.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-11-13 11:12:51 -0800 (Wed, 13 Nov 2024) $
     $LastChangedRevision: 32951 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mvn_exo_bar.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/maven_orbit_tplot/mvn_exo_bar.pro)

## MVN_FLYZ_BAR

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_flyz_bar
    PURPOSE:
      Creates a bar indicating planned times of fly-plus-Z.  Time ranges
      are drawn from the Science Constraints spreadsheet, which is
      produced by Lockheed Martin once a year in mid-summer.  You can
      find the latest spreadsheet (sci_constraints_YYYY.xlsx) here:

        https://lasp.colorado.edu/galaxy/display/MAVEN/Science+Operations+Spreadsheets

      You need to have a MAVEN account on Galaxy to access this file.

      This routine is accurate up through 2025.  After that, I have used
      the predict ephemeris to estimate when fly-plus-Z periods will occur.
      These estimates will be adjusted as new information becomes available.

    USAGE:
      mvn_flyz_bar

    INPUTS:
           none

    KEYWORDS:
           COLOR:    Bar color index.  Default is the current foreground color.
                     This can be changed later using options.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-07-07 10:42:02 -0700 (Fri, 07 Jul 2023) $
     $LastChangedRevision: 31940 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mvn_flyz_bar.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/maven_orbit_tplot/mvn_flyz_bar.pro)

## MVN_MARS_LOCALTIME

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_mars_localtime
    PURPOSE:
      Uses SPICE to determine the local solar time on Mars at a given longitude
      and UTC.  The result is stored as tplot variables and optionally returned
      via keyword.  You can specify arrays of times and longitudes as inputs, or
      this information can be obtained from the maven_orbit_tplot common block.

      It is assumed that you have already initialized SPICE.  (See
      mvn_swe_spice_init for an example.)

    USAGE:
      mvn_mars_localtime, time, lon, result=dat  ; user provides time and lon

      mvn_mars_localtime, result=dat             ; time & lon from common block

    INPUTS:
           time:      An array of times, in any format accepted by time_double.
                      Optional.  Required if lon is specified.

           lon:       An array of IAU_MARS east longitudes (units = degrees).
                      Optional.  Required if time is specified.

                      Both time and lon must have the same number of elements.
                      If only one is specified or they don't have the same
                      number of elements, an error is generated, and the
                      routine will exit without doing anything.

                      If both are unspecified (zero elements), then this
                      routine will attempt to get time and lon from the
                      maven_orbit_tplot common block.

    KEYWORDS:
           RESULT:    Structure containing the result:

                        time  : unix time (seconds since 1970)
                        lon   : east longitude at time (deg)
                        lst   : local solar time (Mars hours, 0 = midnight)
                        slon  : sub-solar point east longitude (deg)
                        slat  : sub-solar point latitude (deg)
                        frame : reference frame for longitudes and latitudes

           PANS:      Returns the names of any tplot variables created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-02-20 11:27:29 -0800 (Tue, 20 Feb 2024) $
     $LastChangedRevision: 32448 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mvn_mars_localtime.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/maven_orbit_tplot/mvn_mars_localtime.pro)

## MVN_MARS_TERMINATOR

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_mars_terminator
    PURPOSE:
      Given a time, uses SPICE to determine the location of the
      terminator and the subsolar point in IAU_MARS coordinates.
      The terminator is calculated with 1-deg resolution (360 points).
      The result is returned via keyword.

      It is assumed that you have already initialized SPICE.  (See
      mvn_swe_spice_init for an example.)

    USAGE:
      mvn_mars_terminator, time, result=dat

    INPUTS:
           time:      Time for calculating the terminator

    KEYWORDS:
           RESULT:    Structure containing the result:

                        time  : unix time for used for calculation
                        t_lon : terminator longitude (deg)
                        t_lat : terminator latitude (deg)
                        s_lon : sub-solar point longitude (deg)
                        s_lat : sub-solar point latitude (deg)
                        frame : coordinate frame ("IAU_MARS")

           SHADOW:    Choose which "shadow" to calculate:
                         0 : optical shadow at surface (default)
                         1 : optical shadow at electron exobase (170 km)

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-22 12:41:13 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33645 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mvn_mars_terminator.pro $

    CREATED BY:	David L. Mitchell

(See projects/maven/maven_orbit_tplot/mvn_mars_terminator.pro)

## MVN_SUN_BAR

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   mvn_sun_bar
    PURPOSE:
      Creates a colored bar indicating sun/shadow.  Assumes that
      you have run maven_orbit_tplot first.

    USAGE:
      mvn_sun_bar

    INPUTS:

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-02-27 07:04:31 -0800 (Mon, 27 Feb 2023) $
     $LastChangedRevision: 31540 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/mvn_sun_bar.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/maven_orbit_tplot/mvn_sun_bar.pro)

## PARABOLA_VERTEX

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   parabola_vertex
    PURPOSE:
      Calculates the vertex of the parabola defined by three points.
      The parabola is assumed to be of the form:

        y = A*(x - xv)^2. + yv

      where A is a constant and [xv, yv] are the coordinates of the
      vertex.  Works best when the input x values surround the vertex,
      but works in other cases as well.

      Uses the second-order Lagrange interpolation formula.  This is
      not a fit -- it is an exact algebraic calculation.

    USAGE:
      parabola_vertex, xi, yi, xv, yv

    INPUTS:
         xi : independent variable (at least 3 values)
         yi : dependent variable (at least 3 values)

         If xi and yi contain more than 3 values, then the routine
         uses the three points surrounding the extremum in yi.  The
         points do not have to be evenly spaced.

         The xi must be different.

    OUTPUTS:
         xv : location of the parabola vertex in x
         yv : value of the dependent variable at the vertex

    KEYWORDS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-02-27 07:04:12 -0800 (Mon, 27 Feb 2023) $
     $LastChangedRevision: 31539 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/parabola_vertex.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/maven_orbit_tplot/parabola_vertex.pro)

## TIME_TO_PERIAPSIS

[Previous Routine] [List of Routines]

    PROCEDURE:   time_to_periapsis
    PURPOSE:
      Calculates the time needed for the spacecraft to go from periapsis
      to some higher altitude(s).  NAIF conventions are used:

        Periapsis is defined as the minimum distance in the orbit to the
        center of Mars (a.k.a. "geometric periapsis").

        Altitude is calculated with respect to the IAU 2000 Mars ellipsoid
        (R_equator = 3396.19 km, R_pole = 3376.20 km).  This is known as
        "areodetic altitude".

      The spacecraft ephemeris is calculated using maven_orbit_tplot, which
      in turn uses SPICE.  The ephemeris is refreshed daily at 3:30 am (Pacific)
      using the latest available kernels from NAIF.  The ephemeris coverage
      extends from Mars orbit insertion to about eight weeks into the future.

    USAGE:
      time_to_periapsis, h

    INPUTS:
           h:             An array of altitudes (units = km).

    KEYWORDS:
           TIME:          Reference time for selecting the nearest orbit.
                          Can be in any format accepted by time_double.
                          If you supply an array of times, only the first
                          element is used.  If not specified, the current
                          UTC is used.

           RESULT:        Named variable to hold the result structure.

           VERBOSE:       Verbosity level.  See dprint.pro.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-10-26 15:28:30 -0700 (Mon, 26 Oct 2020) $
     $LastChangedRevision: 29295 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/maven_orbit_tplot/time_to_periapsis.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/maven_orbit_tplot/time_to_periapsis.pro)