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

Last modified: Tue Nov 4 18:16:51 2025.

# Directory Listing of Routines

# projects/maven/general

- FILE_EXTRACT_TIME_FROM_NAME
- MVN_ALTITUDE
  Determines the altitude of MAVEN. Altitude is defined as the distance
- MVN_APPDIR
  Determines the direction of the APP I-axis in the spacecraft frame.
- MVN_EARTHDIR
  Determines the direction of Earth as viewed from Mars in any coordinate
- MVN_FILE_SOURCE( [DEFAULT_SOURCE] )
  Returns a structure that contains all the information (or options) needed to download and return MAVEN data file names.
- MVN_FRAME_NAME
  Expands a MAVEN frame name fragment to the full frame name
- MVN_GET_ALTITUDE
  Calculates the altitude of the MAVEN spacecraft above the Martian
- MVN_GET_SCPOT
  Given a time, returns the spacecraft potential. Only works after
- MVN_GETORB
  Wrapper for mvn_orbit_num that is quiet by default.
- MVN_LS
  Calculates the Mars season (solar longitude and Mars year).
- MVN_MARS_YEAR
  Calculates the Mars year
- MVN_NADIR
  Determines the direction of nadir at the position of the spacecraft in
- MVN_ORBIT_NUM
  Returns database structure that contains orbit information about each MAVEN orbit.
- MVN_PFP_FILE_NEXT_REVISION
- MVN_PFP_FILE_RETRIEVE
- MVN_PFP_SPD_DOWNLOAD
- MVN_RAMDIR
  Calculates the spacecraft orbital velocity relative to the body-fixed
- MVN_SCPOT
  Merges five separate methods for estimating the spacecraft potential.
- MVN_SCPOT_COM
  Stores the spacecraft potential information. Place this near the top
- MVN_SCPOT_COMP_DAILYSAVE
- MVN_SCPOT_DEFAULTS
  Sets defaults for mvn_scpot and related routines. These are stored
- MVN_SCPOT_RESTORE
  Reads in save files mvn_swe_l3_scpot_YYYYMMDD_v??_r??, create tplot
- MVN_SCPOT_SURVEY
  Makes a survey of the spacecraft potential at periapsis +/- 1 minute.
- MVN_SET_USERPASS,USERNAME,PASSWORD
  Sets the username and password for automatic file retrieval
- MVN_SPC_CLEAR_SPICE_KERNELS
  Clears spice kernels, and unsets the 'kernel verified' flag in the
- MVN_SPC_UNIXTIME_TO_MET
- MVN_SUNDIR
  Determines the direction of the Sun at the position of the spacecraft in
- MVN_TOPOGRAPHY
  Calculates topographic profiles along the orbit track based on laser
- MVN_USR_DIR
  returns a user directory that can be used to store user specific files. Use sparingly!

# Routine Descriptions

## FILE_EXTRACT_TIME_FROM_NAME

[Next Routine] [List of Routines]

     Function: file_extract_time_from_name
       Generic function that will extract the time from a file name that has YYYYMMDD_hhmmss as part of the name

(See projects/maven/general/file_extract_time_from_name.pro)

## MVN_ALTITUDE

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

    PROCEDURE:   mvn_altitude
    PURPOSE:
      Determines the altitude of MAVEN.  Altitude is defined as the distance
      from a point (e.g., MAVEN) to a reference surface along a line normal
      to the reference surface.  The reference surface is sometimes called the
      "datum".  This routine recognizes four definitions of altitude:

        areocentric:  The datum is a sphere with Mars' volumetric mean radius
                      of 3389.50 km.

        areodetic:    The datum is the IAU Mars ellipsoid:
                      R_equator = 3396.19 km ; R_pole = 3376.20 km

        areoid:       The datum is the Mars areoid, which is a gravitational
                      equipotential ("sea level").  This surface is irregular
                      but within ~2 km of the IAU Mars ellipsoid.

        topographic:  The datum is the solid surface, based on laser altimeter
                      data (MGS-MOLA).

      Areocentric and areodetic longitudes are identical, while the latitudes
      differ by less than 0.3 deg.  The altitudes can differ by more than 10 km,
      (about an atmospheric scale height), so this is the main reason for
      choosing the ellipsoid (or the areoid) for the region around periapsis.

      The areoid and solid surface are irregular, so areocentric longitude and
      latitude are used for those reference surfaces.  This is consistent with
      usage in the literature.

      The results are stored in TPLOT variables.

      You must have SPICE installed for this routine to work.

    USAGE:
      mvn_altitude, trange

    INPUTS:
           trange:   Optional.  Time range for calculating altitude.  If not
                     specified, then use the current range set by timespan.

    KEYWORDS:
           DT:       Time resolution (sec).  Default is to use the time resolution
                     of maven_orbit_tplot (usually 10 sec).

           CART:     A 3 x N array of cartesian coordinates in the IAU_MARS frame.
                     If specified, then trange and DT are ignored and the result
                     is returned via keyword RESULT.  If not specified, then try
                     to get this information from maven_orbit_tplot, and the result
                     is stored in tplot variables as well as in RESULT.

           DATUM:    String for specifying the datum.  Can be one of "sphere",
                     "ellipsoid", "areoid", or "surface".  Default = 'ellipsoid'.
                     Minimum matching is used for this keyword.

           LATLON:   Create tplot variables for latitude and longitude.  If
                     DATUM = 'ellipsoid', then you get areodetic latitude and
                     longitude.

           RESULT:   Returns a structure containing the altitude, latitude and
                     longitude.  If CART is set, then each of these will have N
                     values.  If CART is not set, then the structure will be
                     compatible with tplot (x = time, y = altitude).

           PANS:     Named variable to hold the tplot variables created.  Variable
                     names are in the form: mvn_<par>_<dat>, where <par> is the
                     parameter (alt, lon, lat) and <dat> is a three-letter code
                     for the datum (sph, ell, are, sur).

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-04-07 16:16:41 -0700 (Wed, 07 Apr 2021) $
     $LastChangedRevision: 29857 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_altitude.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_altitude.pro)

## MVN_APPDIR

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

    PROCEDURE:   mvn_appdir
    PURPOSE:
      Determines the direction of the APP I-axis in the spacecraft frame.
      There are two gimbals: inner and outer.  The outer gimbal performs
      rotations about the APP J-axis (orthogonal to I).  The inner gimbal
      performs rotations about the spacecraft Y-axis.

      This vector can be rotated into any coordinate frame recognized by
      SPICE.  See mvn_frame_name for a list.  The default is MAVEN_SPACECRAFT.

      You must have SPICE installed for this routine to work.  This routine will
      check to make sure SPICE has been initialized and that the loaded kernels
      cover the specified time range.

    USAGE:
      mvn_appdir, time

    INPUTS:
           time:     If time has two elements, interpret it as a time range and
                     create an array of evenly spaced times with resolution DT.

                     If time has more than two elements, then the APP direction
                     is calculated for each time in the array.

                     Otherwise, attempt to get the time range from tplot and
                     create an array of evenly spaced times with resolution DT.

    KEYWORDS:
           DT:       Time resolution (sec).  Default = 10 sec.

           FRAME:    String or string array for specifying one or more frames
                     to transform the Sun direction into.  Any frame recognized
                     by SPICE is allowed.  The default is 'MAVEN_SPACECRAFT'.
                     Type 'mvn_frame_name(/list)' to see a full list of frames.
                     Minimum matching name fragments (e.g., 'sta', 'swe') are
                     allowed -- see mvn_frame_name for details.

           POLAR:    If set, convert the direction to polar coordinates and
                     store as additional tplot variables.
                        Phi = atan(y,x)*!radeg  ; [  0, 360]
                        The = asin(z)*!radeg    ; [-90, +90]

           PH_180:   If set, the range for Phi is -180 to +180 degrees.

           REVERSE:  Reverse the sense to be the -I direction.

           PANS:     Named variable to hold the tplot variables created.  For the
                     default frame, this would be 'APP_MAVEN_SPACECRAFT'.

           FORCE:    Ignore the SPICE check and forge ahead anyway.

           SUCCESS:  Returns 1 on normal completion, 0 otherwise.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-01-15 12:18:34 -0800 (Mon, 15 Jan 2024) $
     $LastChangedRevision: 32371 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_appdir.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_appdir.pro)

## MVN_EARTHDIR

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

    PROCEDURE:   mvn_earthdir
    PURPOSE:
      Determines the direction of Earth as viewed from Mars in any coordinate
      frame recognized by SPICE.  See mvn_frame_name for a list.  The default
      is MAVEN_SPACECRAFT.  If you sit on the spacecraft and look in this
      direction, you will see Earth.

      You must have SPICE installed for this routine to work.  This routine will
      check to make sure SPICE has been initialized and that the loaded kernels
      cover the specified time range.

    USAGE:
      mvn_earthdir, trange

    INPUTS:
           trange:   Time range for calculating the sub-Earth point.  If not
                     specified, this routine will attempt to get the time range
                     from tplot_com.

    KEYWORDS:
           DT:       Time resolution (sec).  Default = 1.

           FRAME:    String or string array for specifying one or more frames
                     to transform the Earth direction into.  Any frame recognized
                     by SPICE is allowed.  The default is 'MAVEN_SPACECRAFT'.
                     Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
                     Type 'mvn_frame_name(/list)' to see a full list of frames.
                     Minimum matching name fragments (e.g., 'sta', 'swe') are
                     allowed -- see mvn_frame_name for details.

           ABCORR:   Aberration correction.  Options are:

                         'NONE'  : No correction (default)

                       Receive (photons leave Mars at ET-LT and reach Earth at ET)
                         'LT'    : One-way light time
                         'LT+S'  : One-way light time + stellar aberration
                         'CN'    : Same as 'LT' but with better accuracy
                         'CN+S'  : Same as 'LT+S' but with better accuracy

                       Transmit (photons leave Earth at ET and reach Mars at ET+LT)
                         'XLT'   : One-way light time
                         'XLT+S' : One-way light time + stellar aberration
                         'XCN'   : Same as 'LT' but with better accuracy
                         'XCN+S' : Same as 'LT+S' but with better accuracy

                     The aberration correction is used for situations where photons
                     leave one object and arrive at the other object at a later time.
                     By far, the largest part of this correction is the rotation of
                     Mars (0.75 to 5.5 degrees).  The motions of Earth and Mars in
                     their orbits result in a correction smaller than 0.003 deg.

                     For MAVEN, the only time to use an aberration correction is for
                     radio occultations.  For all other purposes, use 'NONE'.

                     See documentation for CSPICE_SUBPNT for details:
                     https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/IDL/icy/cspice_subpnt.html

           POLAR:    If set, convert the direction to polar coordinates and store
                     as additional tplot variables.
                        Phi = atan(y,x)*!radeg  ; [  0, 360]
                        The = asin(z)*!radeg    ; [-90, +90]

           PH_180:   If set, the range for Phi is -180 to +180 degrees.

           REVERSE:  Reverse the sense to be the anti-Earth direction.  If you sit on
                     the spacecraft and look in this direction you will have turned
                     your back on Earth.  You're a Martian now.

           PANS:     Named variable to hold the tplot variables created.  For the
                     default frame, this would be 'Earth_MAVEN_SPACECRAFT'.

           FORCE:    Ignore the SPICE check and forge ahead anyway.

           SUCCESS:  Returns 1 on normal completion, 0 otherwise.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-04-11 20:59:57 -0700 (Tue, 11 Apr 2023) $
     $LastChangedRevision: 31732 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_earthdir.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_earthdir.pro)

## MVN_FILE_SOURCE( [DEFAULT_SOURCE] )

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

    NAME:
     mvn_file_source( [default_source] )
    PURPOSE:
     Returns a structure that contains all the information (or options) needed to download and return MAVEN data file names.
     The structure is stored in a common block variable and has persistance.
     This funtion is used primarily by the routine mvn_pfp_file_source().  However users might wish to change the default values.
     see "file_retrieve" for specific information on how to use the options in this structure.
    Typical Usage:
      source=mvn_file_source()   ; get the options
      printdat, source           ; display the options
    Examples:
     #1a:
      tempsource = mvn_file_source(verbose=4,local_data_dir='tempdir/')  ; temporarily change VERBOSE and LOCAL_DATA_DIR
      files = mvn_pfp_file_retrieve(source=tempsource)
    INPUT:
      default_source  (optional)  if this is a structure then it will be returned as the output
    KEYWORDS:
      SET = [0,1]  : If set, then new options (KEYWORDS or DEFAULT_SOURCE) are made to the common block variable are therefor persistant.
          DO NOT USE THIS KEYWORD INSIDE publically distributed code - IT WILL PRODUCE SIDE EFFECTS FOR OTHERS! !
      RESET = [0,1]  : If set then the default is restored.
          DO NOT USE THIS KEYWORD INSIDE publically distributed code - IT WILL PRODUCE SIDE EFFECTS FOR OTHERS! !
    EXAMPLE 1:
         printdat, mvn_file_source(/set,  USER_PASS='user:password')   ; Add the user and password to enable authentication on the remote server.
     #1b
      help,/structure, mvn_file_source(verbose=3,/set)    ; Permanentaly change the verbose level for all subsequent calls
      files = mvn_pfp_file_retrieve()
     #1c
      help,/structure, mvn_file_source(no_server=1,/set)  ; Permanently disable searching on the remote server
     #2
      help,/structure,   mvn_file_source(/reset)       ; reset structure to the default.
    OUTPUT:
     Structure:
      see "FILE_RETRIEVE" for a description of each structure element.

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2015-11-06 14:01:30 -0800 (Fri, 06 Nov 2015) $
     $LastChangedRevision: 19295 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_file_source.pro $

(See projects/maven/general/mvn_file_source.pro)

## MVN_FRAME_NAME

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

    FUNCTION:   mvn_frame_name
    PURPOSE:
      Expands a MAVEN frame name fragment to the full frame name
      recognized by SPICE.  You can omit the leading 'MAVEN_' or
      'IAU_' from the fragment.  Case folded minimum matching is
      performed.  For example, all of the following are expanded
      to 'MAVEN_STATIC': 'maVEn_st', 'sta', 'St'.  The fragment
      can appear anywhere in the full name.  For example, 'LiMb'
      is expanded to 'MAVEN_IUVS_LIMB'.

      'GEO' is accepted as a synonym for 'MARS'.

      Simply returns the input if the fragment is not recognized
      or ambiguous.

    USAGE:
      spice_frame = mvn_frame_name(frame)

    INPUTS:
           frame:    String scalar or array of MAVEN frame name fragments.
                     If no frame is provided, keyword LIST is set.

    KEYWORDS:
         SUCCESS:    An array of integers with the same number of elements
                     as frame:
                         0 = match not found or ambiguous
                         1 = unique match found

         RESET:      Refresh the list of frame names.

         LIST:       Print a list of frame names and exit.  Returns the
                     null string.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-10 13:21:57 -0700 (Wed, 10 Sep 2025) $
     $LastChangedRevision: 33615 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_frame_name.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_frame_name.pro)

## MVN_GETORB

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

    FUNCTION:   mvn_getorb
    PURPOSE:
      Wrapper for mvn_orbit_num that is quiet by default.

    Typical CALLING SEQUENCE:
      orbdata = mvn_getorb()

    KEYWORDS:
      VERBOSE:        If set, then use default verbosity for mvn_orbit_num.
                      This typically shows dozens of file download messages
                      followed by a "floating illegal operand" error.

                      If not set, then suppress all of the above.

      REFRESH:        Refresh the orbit number database.

    Author: David Mitchell  - October, 2025
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-10-21 10:34:58 -0700 (Tue, 21 Oct 2025) $
     $LastChangedRevision: 33781 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_getorb.pro $

(See projects/maven/general/mvn_getorb.pro)

## MVN_GET_ALTITUDE

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

    FUNCTION: mvn_get_altitude
    PURPOSE:
      Calculates the altitude of the MAVEN spacecraft above the Martian
      surface (either the solid planet or the constant-pressure surface
      known as the 'areoid').  This routine is called by the more general
      mvn_altitude, which has other possible definitions for altitude.

    USAGE:
      mav_get_altitude, elon_sc, lat_sc,r_sc, alt_sc

    INPUTS:
           xpc: a 1-dimensional array of values of the east longitude
                    of the spacecraft. UNITS: km

           ypc:  a 1-dimensional array of values of the latitude
                    of the spacecraft. UNITS: km

           zpc:    a 1-dimensional array of values of the radial
                    distance of the spacecraft from the planet's center
                    of mass. UNITS: kilometers
    OUTPUT:
           The output array of spacecraft altitudes.
                    UNITS: kilometers

    KEYWORDS:
           TOPOGRAPHIC: Set this keyword to anything nonzero if the spacecraft
                        altitude above the planet's topography is
                        desired.  If this keyword is not specified, the
                        altitude will be above the constant-pressure
                        surface known as the areoid (the equivalent of
                        sea level) and the relevant altitude for most
                        MAVEN studies.

           MOLA_STRUC:  Depreciated.  Structure now stored in a common block.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-05-29 15:49:17 -0700 (Mon, 29 May 2017) $
     $LastChangedRevision: 23361 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_get_altitude.pro $

    CREATED BY:	Robert J. Lillis 2013-01-22

(See projects/maven/general/mvn_get_altitude.pro)

## MVN_GET_SCPOT

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

    FUNCTION:
    	mvn_get_scpot

    PURPOSE:
    	Given a time, returns the spacecraft potential.  Only works after
       the potentials have been restored/calculated by mvn_scpot.

    AUTHOR:
    	David L. Mitchell

    CALLING SEQUENCE:
    	pot = mvn_get_scpot(time)

    INPUTS:
       time:      Time or array of times for getting the potential, in
                  any format accepted by time_double().

    KEYWORDS:

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-09-12 14:13:48 -0700 (Wed, 12 Sep 2018) $
     $LastChangedRevision: 25778 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_get_scpot.pro $

(See projects/maven/general/mvn_get_scpot.pro)

## MVN_LS

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

    FUNCTION: mvn_ls
    PURPOSE:
      Calculates the Mars season (solar longitude and Mars year).

        Ls =   0  --> Northern spring equinox  (beginning of Mars year)
        Ls =  90  --> Northern summer solstice
        Ls = 180  --> Northern fall equinox
        Ls = 270  --> Northern winter solstice

        Ls =  71  --> Aphelion
        Ls = 251  --> Perihelion

        Ls = 180-320  --> Dust storm season

      Ls (pronounced "L sub S") is the angular position of Mars in its orbit about the
      Sun, starting at the northern spring equinox and ranging from 0 to 360 degrees.
      This is different from longitude in the rotating IAU_SUN frame, which is used to
      specify the positions of features (flares, sunspots) on the Sun as well as the
      face of the Sun seen by an observer.

      For the definition of Mars year, see Piqueux et al., Icarus 251 (2015) 332–338.

        Mars year  0 began 1953-05-24/11:54:39
        Mars year 34 began 2017-05-05/11:28:03

    USAGE:
      result = mvn_ls(time)

    INPUTS:
           time:      An array of times in any format accepted by time_double.  If no
                      time is provided, then all values in the common block are returned.
                      If keyword DT is set, then the minimum and maximum values of time
                      are used to create an array of evenly spaced values sampled every
                      DT seconds.

    OUTPUT:
                      By default, returns an array of Ls (L_sub_s) values with the same
                      number of elements as time.  If keyword ALL is set, then returns a
                      structure with three tags:

                        time      : the times at which the Mars season is calculated
                        Ls        : the longitude of Mars in its orbit about the Sun,
                                    with Ls=0 at Mars' northern spring equinox
                        Mars_year : the Mars year (Ls = 0 to 360) -- Mars year 0 began
                                    at 1953-05-24/11:54:39.  Year 1 was chosen to
                                    correspond to a global dust storm in 1956.

    KEYWORDS:
           DT :       Optional.  Time resolution in seconds for calculating the result.
                      If set, then the minimum and maximum values of time are used to
                      create an array of values sampled every DT seconds.  Linear
                      interpolation between calculated values spaced by 1 day provides
                      an accuracy of ~0.0001 deg, so there's typically no need for DT
                      to be any smaller.  If not set, then the result is calculated for
                      all values in the time array.

           ALL:       By default, this function returns an array of Ls (L_sub_s) values
                      with the same number of elements as time.  Set this keyword to
                      instead get a structure with three tags: time, Ls, and Mars_year.

           TPLOT:     Make a tplot variable.

           BAR:       If TPLOT is set, then setting this keyword creates a detached horizontal
                      time axis with labels for Mars year and Ls.  This axis can be placed
                      below any panel or at the top.  Only seems to work for Mars years 24-36
                      (1998-2023).

           CALC:      Instead of interpolating on an array of pre-calculated values, use
                      spice to calculate values based on time and DT.  This mode always
                      returns a structure of arrays, as if ALL were set.  Use this if you
                      need a precision better than ~0.0001 deg.

           SILENT:    Suppress diagnostic output (mostly from spice).

           RESET:     Re-calculate mars_season and refresh the common block.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-07-11 17:52:59 -0700 (Fri, 11 Jul 2025) $
     $LastChangedRevision: 33456 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_ls.pro $

    CREATED BY:	Robert J. Lillis 2017-10-09
    FILE:  mvn_ls
    VERSION:  1.0

(See projects/maven/general/mvn_ls.pro)

## MVN_MARS_YEAR

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

    PROCEDURE: mvn_mars_year
    PURPOSE:
      Calculates the Mars year

    USAGE:
      mvn_year, time

    INPUTS:
           time: time in string ('YYYY-MM-DD', 'YYYY-MM-DD/hh:mm:ss' etc) or double format.
    OUTPUT:
           Mars year (decimal)

    KEYWORDS:
           TPLOT: makes a tplot variable of Ls

    CREATED BY:	Robert J. Lillis 2017-10-09
    FILE:  mvn_mars_year
    VERSION:  1.0

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2023-04-15 16:43:52 -0700 (Sat, 15 Apr 2023) $
     $LastChangedRevision: 31753 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_mars_year.pro $

(See projects/maven/general/mvn_mars_year.pro)

## MVN_NADIR

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

    PROCEDURE:   mvn_nadir
    PURPOSE:
      Determines the direction of nadir at the position of the spacecraft in
      one or more coordinate frames.  The results are stored in TPLOT variables.
      If you sit on the spacecraft and look in this direction, you will see the
      ground.

      For this routine, nadir is defined to be the direction to the center of
      Mars (i.e., the origins of the MSO, MSE, and IAU_MARS frames).

      This vector can be rotated into any coordinate frame recognized by
      SPICE.  See mvn_frame_name for a list.  The default is MAVEN_SPACECRAFT.

      You must have SPICE installed for this routine to work.  This routine will
      check to make sure SPICE has been initialized and that the loaded kernels
      cover the specified time range.

    USAGE:
      mvn_nadir, time

    INPUTS:
           time:     If time has two elements, interpret it as a time range and
                     create an array of evenly spaced times with resolution DT.

                     If time has more than two elements, then the ram direction
                     is calculated for each time in the array.

                     Otherwise, attempt to get the time range from tplot and
                     create an array of evenly spaced times with resolution DT.

    KEYWORDS:
           DT:       Time resolution (sec).  Default is 10 sec.

           FRAME:    String or string array for specifying one or more frames
                     to transform the nadir direction into.  Any frame recognized
                     by SPICE is allowed.  The default is 'MAVEN_SPACECRAFT'.
                     Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
                     Type 'mvn_frame_name(/list)' to see a full list of frames.
                     Minimum matching name fragments (e.g., 'sta', 'swe') are
                     allowed -- see mvn_frame_name for details.

           POLAR:    If set, convert the direction to polar coordinates and
                     store as additional tplot variables.
                        Phi = atan(y,x)*!radeg  ; units deg [  0, 360]
                        The = asin(z)*!radeg    ; units deg [-90, +90]

           PH_180:   If set, the range for Phi is -180 to +180 degrees.

           REVERSE:  Reverse the sense of nadir to be zenith.  If you sit on the
                     spacecraft and look in this direction you will see the stars
                     above.

           PANS:     Named variable to hold the tplot variables created.  For the
                     default frame, this would be 'Nadir_MAVEN_SPACECRAFT'.

           FORCE:    Ignore the SPICE check and forge ahead anyway.

           SUCCESS:  Returns 1 on normal completion, 0 otherwise

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-02-16 14:42:30 -0800 (Sun, 16 Feb 2025) $
     $LastChangedRevision: 33129 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_nadir.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_nadir.pro)

## MVN_ORBIT_NUM

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

    NAME: MVN_ORBIT_NUM
     function: mvn_orbit_num()
    PURPOSE:
     Returns database structure that contains orbit information about each MAVEN orbit.
     Alternatively - Returns the time if given the orbit number or returns the orbit number if given the time.

     This routine uses the NAIF convention, where the orbit number increments at periapsis.  Two other
     conventions are in use for MAVEN: (1) orbit number increments at the inbound periapsis segment
     boundary (LM and IUVS), and (2) orbit number increments at apoapsis (NGIMS).  All three conventions
     agree at periapsis.

    Typical CALLING SEQUENCE:
      orbdata = mvn_orbit_num()
      store_data,'orbnum',orbdata.peri_time,orbdata.num,dlimit={ytitle:'Orbit'}
      tplot,var_label='orbnum'

    KEYWORDS:
      VERBOSE:        Message level for dprint.

      RELOAD_TIME:    Interval at which to sync local files with remote server.  Default = 3600 sec.

      REFRESH:        Ignore RELOAD_TIME and check the remote server anyway.

    TYPICAL USAGE:
      print, mvn_orbit_num(time=systime(1) )          ;  prints current MAVEN orbit number
      print ,  time_string( mvn_orbit_num(orbnum = 6.0)  ; prints the time of periapsis of orbit number 6
      timebar, mvn_orbit_num( orbnum = indgen(300) )   ; plots a vertical line at periapsis for the first 300 orbits
    Author: Davin Larson  - October, 2014
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2021-09-20 09:12:57 -0700 (Mon, 20 Sep 2021) $
     $LastChangedRevision: 30304 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_orbit_num.pro $

(See projects/maven/general/mvn_orbit_num.pro)

## MVN_PFP_FILE_NEXT_REVISION

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

    FUNCTION mvn_pfp_file_next_revision(filename,ndigits, [extension=extension])
    Returns the filename with the next revision number
    Warning: unpredictable results at rollover.

(See projects/maven/general/mvn_pfp_file_next_revision.pro)

## MVN_PFP_FILE_RETRIEVE

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

     Function:  files = mvn_pfp_file_retrieve(PATHNAME)
     Purpose:  Retrieve or Download MAVEN data files (i.e. L0 files)  (Can be used to generate filenames too)
     INPUT:
     PATHNAME:  string specifying relative path to files.         Default might change-  Currently:  'maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat'
             PATHNAME must be relative to the LOCAL_DATA_DIR and REMOTE_DATA_DIR fields of the source keyword.
             "globbed" filenames (*,?) are accepted.
     typical usage:
       files = mvn_pfp_file_retrieve('maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat',/daily_names)   ; get L0 files for user defined time span
       files = mvn_pfp_file_retrieve(pathname,/daily_names,trange=trange)  ; set time range
    Keywords:  (All are optional - none are recommended)
     L0:   set to 1 to return PFP L0 files
     DAILY_NAMES : resolution (in days) for generating file names.
             YYYY, yy, MM, DD,  hh,  mm, ss, .f, DOY, DOW, TDIFF are special characters that will be substituted with the appropriate date/time field
             Be especially careful of extensions that begin with '.f' since these will be translated into a fractional second.
             See "time_string"  TFORMAT keyword for more info.
     TRANGE : two element vector containing start and end times (UNIX_TIME or UT string).  if not present then timerange() is called to obtain the limits.
     SOURCE:  alternate file source.   Default is whatever is return by the function:  mvn_file_source()    (see "mvn_file_source" for more info)
     FILES:  if provided these will be passed through as output.
     VALID_ONLY:  Set to 1 to prevent non existent files from being returned.
     CREATE_DIR:  Generates a filename and creates the directories needed to create the file without errors.  Will not check for file on remote server.

     KEYWORDS Passed on to "FILE_RETRIEVE":
     LAST_VERSION : [0,1]  if set then only the last matching file is returned.  (Default is defined by source)
     VALID_ONLY:  [0,1]   If set then only existing files are returned.  (Default is defined by source keyword)
     VERBOSE:  set verbosity level (2 is typical)
     USER_PASS:  user:password combination for the remote server
     LIMITATIONS:
       Beware of file pathnames that include the character sequences:  YY,  MM, DD, hh, mm, ss, .f  since these can be retranslated to the time

(See projects/maven/general/mvn_pfp_file_retrieve.pro)

## MVN_PFP_SPD_DOWNLOAD

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

     Function:  files = mvn_pfp_spd_download(PATHNAME)
     Purpose: Retrieve or Download MAVEN data files. (Can
              be used to generate filenames too). Note that this is a
              Hacked version of mvn_pfp_file_retrieve, to use for SPICE
              kernels which are no longer able to be accessed via
              file_retrieve, jmm, 2017-01-30
     INPUT:
     PATHNAME:  string specifying relative path to files. Default might change-  Currently:  'maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat'
             PATHNAME must be relative to the LOCAL_DATA_DIR and REMOTE_DATA_DIR fields of the source keyword.
             "globbed" filenames (*,?) are accepted.
     typical usage:
       files = mvn_pfp_spd_download('maven/pfp/l0/YYYY/MM/mvn_pfp_all_l0_YYYYMMDD_v???.dat',/daily_names)   ; get L0 files for user defined time span
       files = mvn_pfp_spd_download(pathname,/daily_names,trange=trange)  ; set time range
    Keywords:  (All are optional - none are recommended)
     L0:   set to 1 to return PFP L0 files
     DAILY_NAMES : resolution (in days) for generating file names.
             YYYY, yy, MM, DD,  hh,  mm, ss, .f, DOY, DOW, TDIFF are special characters that will be substituted with the appropriate date/time field
             Be especially careful of extensions that begin with '.f' since these will be translated into a fractional second.
             See "time_string"  TFORMAT keyword for more info.
     TRANGE : two element vector containing start and end times (UNIX_TIME or UT string).  if not present then timerange() is called to obtain the limits.
     SOURCE:  alternate file source.   Default is whatever is return by the function:  mvn_file_source()    (see "mvn_file_source" for more info)
     FILES:  if provided these will be passed through as output.
     VALID_ONLY:  Set to 1 to prevent non existent files from being returned.
     CREATE_DIR:  Generates a filename and creates the directories needed to create the file without errors.  Will not check for file on remote server.

     KEYWORDS Passed on to "SPD_DOWNLOAD":
     LAST_VERSION : [0,1]  if set then only the last matching file is returned.  (Default is defined by source)
     VALID_ONLY:  [0,1]   If set then only existing files are returned.  (Default is defined by source keyword)
     VERBOSE:  set verbosity level (2 is typical)
     LIMITATIONS:
       Beware of file pathnames that include the character sequences:
       YY,  MM, DD, hh, mm, ss, .f  since these can be retranslated to
       the time
     $LastChangedBy: jimm $
     $LastChangedDate: 2021-03-17 12:57:32 -0700 (Wed, 17 Mar 2021) $
     $LastChangedRevision: 29766 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_pfp_spd_download.pro $

(See projects/maven/general/mvn_pfp_spd_download.pro)

## MVN_RAMDIR

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

    PROCEDURE:   mvn_ramdir
    PURPOSE:
      Calculates the spacecraft orbital velocity relative to the body-fixed
      rotating Mars frame (IAU_MARS).  If you sit on the spacecraft and look
      in this direction, the flow will be in your face.  The default is to
      calculate this direction in the MAVEN_SPACECRAFT frame.

      Careful!  Some people consider the opposite of the spacecraft velocity
      to be the RAM direction.  Watch for sign errors.

      This vector can be rotated into the APP frame or any of the instrument
      frames.  See mvn_frame_name for a list.  This is a pure rotation, so
      don't try to rotate into the MSO frame, since the result would still be
      in a frame that rotates with the planet.  Instead, use the MSO keyword.

      The co-rotation velocity in the IAU_MARS frame as a function of altitude
      (h) and latitude (lat) is:

          V_corot = (240 m/s)*[1 + h/3390]*cos(lat)

      Models (LMD and MTGCM) predict that peak horizontal winds are 190-315 m/s
      near the exobase and 155-165 m/s near the homopause.  These are comparable
      to the co-rotation velocity.  The spacecraft velocity is ~4200 m/s in this
      altitude range, so winds could result in up to a ~4-deg angular offset of
      the actual flow from the nominal ram direction.

      You must have SPICE installed for this routine to work.  This routine will
      check to make sure SPICE has been initialized and that the loaded kernels
      cover the specified time range.  With reconstructed kernels, this routine
      has an accuracy of ~0.1 deg.

    USAGE:
      mvn_ramdir, time

    INPUTS:
           time:     If time has two elements, interpret it as a time range and
                     create an array of evenly spaced times with resolution DT.

                     If time has more than two elements, then the ram direction
                     is calculated for each time in the array.

                     Otherwise, attempt to get the time range from tplot and
                     create an array of evenly spaced times with resolution DT.

    KEYWORDS:
           DT:       Time resolution (sec).  Default is 10 sec.

           FRAME:    String or string array for specifying one or more frames
                     to rotate the ram direction into.  Any frame recognized
                     by SPICE is allowed.  The default is 'MAVEN_SPACECRAFT'.
                     Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
                     Type 'mvn_frame_name(/list)' to see a full list of frames.
                     Minimum matching name fragments (e.g., 'sta', 'swe') are
                     allowed -- see mvn_frame_name for details.  This is a pure
                     rotation!

           POLAR:    If set, convert the direction to polar coordinates and
                     store as additional tplot variables.
                        Mag = sqrt(x*x + y*y + z*z) ; units km/s
                        Phi = atan(y,x)*!radeg      ; units deg [  0, 360]
                        The = asin(z/Mag)*!radeg    ; units deg [-90, +90]

           PH_180:   If set, the range for Phi is -180 to +180 degrees.

           REVERSE:  Reverse the sense of RAM to be the velocity of the incoming
                     ions with respect to the spacecraft.  If you sit on the
                     spacecraft and look in this direction the flow will be into
                     the back of your head.

           MSO:      Calculate ram vector in the MSO frame instead of the
                     rotating IAU_MARS frame.  May be useful at high altitudes.

           ERROR:    Calculate the magnitude of the RAM pointing error (deg) in
                     one of the APP frames and store as a separate tplot variable.
                     This only works for the APP, NGIMS and STATIC frames, as well
                     as the reverse of those frames.  Note that the NGIMS frame is
                     slightly shifted relative to the APP frame, so the calculated
                     error is slightly different.  If ERROR is set but no APP frame
                     is specified in FRAME, then MAVEN_APP is appended to the FRAME
                     list.

                     Using ephemeris predicts refreshed on a regular basis, the
                     spacecraft can usually point the APP into the RAM direction
                     with an accuracy of ~0.5 deg.  Occasionally, the error can
                     be up to ~2 deg.  The reconstructed RAM direction has an
                     accuracy of ~0.1 deg.

           PANS:     Named variable to hold the tplot variables created.  For the
                     default frame, this would be 'V_sc_MAVEN_SPACECRAFT'.

           RESULT:   Named variable to hold the result structure.

           FORCE:    Ignore the SPICE check and forge ahead anyway.

           SUCCESS:  Returns 1 on normal operation, 0 otherwise.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-09-08 12:49:13 -0700 (Mon, 08 Sep 2025) $
     $LastChangedRevision: 33605 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_ramdir.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_ramdir.pro)

## MVN_SCPOT

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

    PROCEDURE:
    	mvn_scpot

    PURPOSE:
    	Merges five separate methods for estimating the spacecraft potential.
       In cases where more than one method yields a potential, this routine
       sets a hierarchy for which method takes precedence.  The hierarchy
       depends on location (altitude, shadow).  The five methods are:

           SWE+    : Estimate positive potentials by looking for a sharp
                     break in the electron energy spectrum.  Mainly for
                     the solar wind and sheath.
                     (Author: D. Mitchell)

           SWE-    : Estimate negative potentials by measuring shifts in
                     position of the He-II photoelectron peak.  Mainly
                     for the ionosphere.*
                     (Author: S. Xu)

           SWE/LPW : Use LPW I-V curves, empirically calibrated by the
                     SWE+ and SWE- methods.  Works almost everywhere,
                     except in the EUV shadow or when the spacecraft
                     charges to large negative potentials.
                     (Author: Y. Harada)

           STA-    : Estimate negative potentials by the low energy
                     cutoff of the H+ distribution (away from periapsis),
                     or energy shifts, relative to the ram energy, of O+
                     and O2+ (near periapsis).**
                     (Author: J. McFadden)

           SWEPAD  : Use pitch angle resolved photoelectron spectra to
                     estimate negative potentials in the wake.  Combined
                     with the STA- method, may be used to distinguish
                     spacecraft and Mars potentials.  Only works with
                     burst data.*
                     (Author: S. Xu)

      * Warning: The SWE- and SWEPAD methods provide the sum of the spacecraft
                 and Mars potentials.  Ionospheric photoelectrons are always subject
                 to the ambipolar potential (~1 V) that forms at the electron exobase
                 to maintain charge neutrality with the gravitationally bound ions.
                 There are other Mars potentials that can sometimes play a role.
                 Comparison with the STA method is necessary to separate the spacecraft
                 and Mars potentials.  Thus, the LPW, SWE+, and STA methods must take
                 precedence.

     ** Warning: O2+ dominates at periapsis.  Using shifts in the O2+ energy alone
                 assumes that thermospheric winds are negligible.

       The general order of precedence is: SWE/LPW, SWE+, STA-, SWE-, and
       SWEPAD (when activated by keyword).

    AUTHOR:
    	David L. Mitchell

    CALLING SEQUENCE:
    	mvn_scpot

    INPUTS:
       none - energy spectra are obtained from SWEA common block.

    KEYWORDS:
    	POTENTIAL: Returns a time-ordered array of structures:

                    {time            : 0D       , $
                     potential       : 0.       , $
                     method          : -1          }

                  The methods are: -1 (invalid), 0 (manually set),
                  1 (SWE/LPW), 2 (SWE+), 3 (SWE-), 4 (STA-), 5 (SWEPAD),
                  6 (interpolated).

                  The optimal value depends on the plasma environment.

       SETVAL:    Make no attempt to estimate the potential, just set it to
                  this value.  Units = volts.  No default.

       COMPOSITE: The composite potential (SWE/LPW, SWE+, SWE-, STA-) has
                  been pre-calculated with this routine and stored in save
                  files.  Set this keyword to simply restore this file and
                  save lots of time.  (Works for multiple days and can span
                  UT day boundaries.)  This is the default.  Set this keyword
                  to zero to force a recalculation.

       NOCALC:    Do not perform a recalculation.  Use the composite potential
                  or nothing.

       LPWPOT:    Use pre-calculated LPW/SWE derived potentials.  There is
                  a ~2-week delay in the production of this dataset.  You can
                  set this keyword to the full path and filename of a tplot
                  save/restore file, if one exists.  Otherwise, this routine
                  will determine the potential from SWEA and STATIC.
                  Default = 1 (yes).

       POSPOT:    Calculate positive potentials with mvn_swe_sc_pot (SWE+).
                  Default = 1 (yes).

       NEGPOT:    Calculate negative potentials with mvn_swe_sc_negpot.
                  Default = 1 (yes).

       STAPOT:    Use STATIC-derived potentials to fill in gaps.  This is
                  especially useful in the high-altitude shadow region.
                  Assumes that you have calculated STATIC potentials.
                  (See mvn_sta_scpot_load.pro)
                  Default = 1 (yes).

       SHAPOT:    Calculate negative potentials with 'mvn_swe_sc_negpot_
                  twodir_burst'.  Two estimates are obtained, one each for
                  the parallel and anti-parallel electron populations.  If
                  both directions yield a potential, then the one closer to
                  zero is chosen for merging with other methods.
                  Requires keyword NEGPOT to be set.
                  Default = 1 (yes).

       PANS:      Named varible to hold the tplot panels created.

       LOADONLY:  Load the potential but do not refresh the tplot window.

       QLEVEL:    Minimum quality level for SWEA data.  Filters out the vast
                  majority of spectra affected by the sporadic low energy
                  anomaly below 28 eV.  The validity levels are:

                    0B = Data are affected by the low-energy anomaly.  There
                         are significant systematic errors below 28 eV.
                    1B = Unknown because: (1) the variability is too large to
                         confidently identify anomalous spectra, as in the
                         sheath, or (2) secondary electrons mask the anomaly,
                         as in the sheath just downstream of the bow shock.
                    2B = Data are not affected by the low-energy anomaly.
                         Caveat: There is increased noise around 23 eV, even
                         for "good" spectra.

                    Default = 1.

       QINTERP:   Interpolate the potential for small gaps caused by the
                  sporadic low-energy anomaly.  Set this keyword to the largest
                  gap (in seconds) to interpolate across.

       SUCCESS:   Returns exit status.

    OUTPUTS:
       None - Result is stored in common blocks, returned via the POTENTIAL
              keyword, and stored as TPLOT variables.  Two TPLOT variables
              are created: one with a single merged potential and one showing
              the five unmerged methods in one panel.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-06-23 10:37:26 -0700 (Mon, 23 Jun 2025) $
     $LastChangedRevision: 33410 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot.pro $

(See projects/maven/general/mvn_scpot.pro)

## MVN_SCPOT_COM

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

    COMMON BLOCK:   mvn_scpot_com
    PURPOSE:
      Stores the spacecraft potential information.  Place this near the top
      of any routine that needs access to the common block.

         mvn_sc_pot      : spacecraft potential structure
         mvn_pot_struct  : potential structure template

         Espan           : energy search range for swe+ method
         thresh          : minimum value of d(logF)/d(logE) for swe+ method
         dEmax           : maximum width of d(logF)/d(logE) for swe+ method
                           (Since dE/E is a constant, this is measured in units
                            of dE.)
         bias            : potential bias for swe+ method
         minflux         : minimum 40-eV energy flux for swe+ method
         badval          : fill value for potential when no method works
         ee              : 4x oversampled energy array
         dfs             : 4x oversampled d(logF)/d(logE)
         d2fs            : 4x oversampled d2(logF)/d(logE)2
         min_lpw_pot     : minimum valid LPW potential
         maxdt           : maximum time gap to interpolate over
         min_sta_pot     : minimum valid STA potential for altitudes below sta_peri_alt
         max_sta_alt     : maximum altitude for limiting range of STA potentials
         min_swe_alt     : minimum altitude for limiting range of SWE+ potentials

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-25 14:47:01 -0700 (Thu, 25 Jul 2024) $
     $LastChangedRevision: 32760 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot_com.pro $

    CREATED BY:	David L. Mitchell
    FILE:  mvn_scpot_com.pro

(See projects/maven/general/mvn_scpot_com.pro)

## MVN_SCPOT_COMP_DAILYSAVE

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

    PROCEDURE:   mvn_scpot_comp_dailysave
    PURPOSE:

    USAGE:
      mvn_scpot_comp_dailysave,start_day=start_day,end_day=end_day,ndays=ndays

    INPUTS:
           None

    KEYWORDS:
           start_day:     Save data over this time range.  If not
                          specified, then timerange() will be called

           end_day:       The end day of intented time range

           ndays:         Number of dates to process. Will be overwritten
                          if start_day & end_day are given. If both
                          end_day and ndays are not specified, ndays=7

     $LastChangedBy: jwl $
     $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
     $LastChangedRevision: 33563 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot_comp_dailysave.pro $

    CREATED BY:    Shaosui Xu, 08/01/2017
    FILE: mvn_scpot_comp_dailysave.pro

(See projects/maven/general/mvn_scpot_comp_dailysave.pro)

## MVN_SCPOT_DEFAULTS

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

    PROCEDURE:
    	mvn_scpot_defaults

    PURPOSE:
    	Sets defaults for mvn_scpot and related routines.  These are stored
       in a common block (mvn_scpot_com).

    AUTHOR:
    	David L. Mitchell

    CALLING SEQUENCE:
    	mvn_scpot_defaults

    INPUTS:
       none - simply sets defaults for the common block.

    KEYWORDS:
       ERANGE:    Energy range over which to search for the potential in
                  the SWE+ method.  Default = [3.,30.]

       THRESH:    Threshold for the minimum slope, d(logF)/d(logE), for
                  the SWE+ method  Default = 0.05

                  A smaller value includes more data and extends the range
                  over which you can estimate the potential, but at the
                  expense of making more errors.

       MINFLUX:   Minimum peak energy flux for the SWE+ method.
                  Default = 1e6

       DEMAX:     The largest allowable energy width of the spacecraft
                  potential feature for the SWE+ method.  This excludes
                  features not related to the spacecraft potential at
                  higher energies (often observed downstream of the shock).
                  Default = 6 eV

       BIAS:      Voltage bias applied to the energy of the maximum slope in
                  the SWE+ method.  This corrects for the common situation
                  in which the maximum slope that is used to locate the
                  photoelectron line does not quite match the optimal value
                  of the potential.  Default = +0.5 energy bins.

       ABINS:     When using 3D spectra, specify which anode bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,16)

       DBINS:     When using 3D spectra, specify which deflection bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = replicate(1,6)

       OBINS:     When using 3D spectra, specify which solid angle bins to
                  include in the analysis: 0 = no, 1 = yes.
                  Default = reform(ABINS#DBINS,96).  Takes precedence over
                  ABINS and OBINS.

       MASK_SC:   Mask the spacecraft blockage.  This is in addition to any
                  masking specified by the above three keywords.
                  Default = 1 (yes).

       BADVAL:    If the algorithm cannot estimate the potential, then set it
                  to this value.  Units = volts.  Default = NaN.

       MIN_LPW_POT : Minumum valid LPW potential.

       MIN_STA_POT : Minumum valid STA potential.

       MAX_STA_ALT : Maximum altitude for limiting range of STA potentials.

       MIN_SWE_ALT : Minimum altitude for limiting range of SWE+ potentials.

       MAXDT:     Maximum time gap to interpolate across.  Default = 64 sec.

       LIST:      Take no action.  Just list the defaults.

    OUTPUTS:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-07-25 14:47:01 -0700 (Thu, 25 Jul 2024) $
     $LastChangedRevision: 32760 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot_defaults.pro $

(See projects/maven/general/mvn_scpot_defaults.pro)

## MVN_SCPOT_RESTORE

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

    PROCEDURE:   mvn_scpot_restore
    PURPOSE:
      Reads in save files mvn_swe_l3_scpot_YYYYMMDD_v??_r??, create tplot
      varibles for s/c pot, store potential structures in results and/or full

    USAGE:
      mvn_scpot_restore, trange

    INPUTS:
           trange:        Restore data over this time range.  If not specified, then
                          uses the current tplot range or timerange() will be called

    KEYWORDS:
           ORBIT:         Restore mvn_swe_l3_scpot data by orbit number.

           RESULTS:       Hold the structure of composited potentials

           TPLOT:         Create tplot varibles for the composited s/c
                          potentials as well as for all the available s/c pots

           FULL:          Hold the structure of composited potentials and
                          all other potential structures

           SUCCESS:       Set to 1 if valid potentials are found.

     $LastChangedBy: hara $
     $LastChangedDate: 2024-02-23 14:47:10 -0800 (Fri, 23 Feb 2024) $
     $LastChangedRevision: 32458 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot_restore.pro $

    CREATED BY:    Shaosui Xu  06-23-17
    FILE: mvn_scpot_restore

(See projects/maven/general/mvn_scpot_restore.pro)

## MVN_SCPOT_SURVEY

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

    PROCEDURE:   mvn_scpot_survey
    PURPOSE:
      Makes a survey of the spacecraft potential at periapsis +/- 1 minute.

    USAGE:
      mvn_scpot_survey, result=result

    INPUTS:
          None.

    KEYWORDS:
          DOPLOT:         Create tplot variables.

          APOAPSIS:       Create a database for apoapsis instead.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-03-17 11:18:56 -0700 (Tue, 17 Mar 2020) $
     $LastChangedRevision: 28419 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_scpot_survey.pro $

    CREATED BY:    David L. Mitchell  2017-04-02
    FILE: mvn_scpot_survey

(See projects/maven/general/mvn_scpot_survey.pro)

## MVN_SET_USERPASS,USERNAME,PASSWORD

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

    NAME:
     mvn_set_userpass,username,password
    PURPOSE:
     Sets the username and password for automatic file retrieval
    Typical Usage:
      mvn_set_userpass,'joe@gmail.com','passwd!'[,/TEMPORARY]   ; This line is typically put in your IDL_STARTUP routine.
    Keywords:
      TEMPORARY:   Set this keyword to prevent the username and password from being stored in an environment variable
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See projects/maven/general/mvn_set_userpass.pro)

## MVN_SPC_CLEAR_SPICE_KERNELS

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

    NAME:
     mvn_spc_clear_spice_kernels
    PURPOSE:
     Clears spice kernels, and unsets the 'kernel verified' flag in the
     mvn_spc_met_to_unixtime so that mvn_spc_met_to_unixtime doesn't crash
    CALLING SEQUENCE:
     mvn_spc_clear_spice_kernels
     $LastChangedBy: jimm $
     $LastChangedDate: 2015-03-16 11:57:01 -0700 (Mon, 16 Mar 2015) $
     $LastChangedRevision: 17140 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_spc_clear_spice_kernels.pro $

(See projects/maven/general/mvn_spc_clear_spice_kernels.pro)

## MVN_SPC_UNIXTIME_TO_MET

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

    Function:  mvn_spc_unixtime_to_met
    Purpose:  Convert unixtime to MET (mission Elapsed Time)
     Note: This routine MUST remain reasonably efficient since it could potentially be called from within an inner FOR loop.
     Author: Davin Larson
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2014-01-21 17:00:30 -0800 (Tue, 21 Jan 2014) $
     $LastChangedRevision: 13959 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu:36867/repos/idl_socware/trunk/projects/maven/mvn_spc_met_to_unixtime.pro $

(See projects/maven/general/mvn_spc_unixtime_to_met.pro)

## MVN_SUNDIR

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

    PROCEDURE:   mvn_sundir
    PURPOSE:
      Determines the direction of the Sun at the position of the spacecraft in
      one or more coordinate frames.  The results are stored in TPLOT variables.
      If you sit on the spacecraft and look in this direction, you will see the
      Sun.  Be sure to use eye protection.

      This vector can be rotated into any coordinate frame recognized by
      SPICE.  See mvn_frame_name for a list.  The default is MAVEN_SPACECRAFT.

      You must have SPICE installed for this routine to work.  This routine will
      check to make sure SPICE has been initialized and that the loaded kernels
      cover the specified time range.

    USAGE:
      mvn_sundir, time

    INPUTS:
           time:     If time has two elements, interpret it as a time range and
                     create an array of evenly spaced times with resolution DT.

                     If time has more than two elements, then the ram direction
                     is calculated for each time in the array.

                     Otherwise, attempt to get the time range from tplot and
                     create an array of evenly spaced times with resolution DT.

    KEYWORDS:
           DT:       Time resolution (sec).  Default = 10 sec.

           FRAME:    String or string array for specifying one or more frames
                     to transform the Sun direction into.  Any frame recognized
                     by SPICE is allowed.  The default is 'MAVEN_SPACECRAFT'.
                     Other possibilities are: 'MAVEN_APP', 'MAVEN_STATIC', etc.
                     Type 'mvn_frame_name(/list)' to see a full list of frames.
                     Minimum matching name fragments (e.g., 'sta', 'swe') are
                     allowed -- see mvn_frame_name for details.

           POLAR:    If set, convert the direction to polar coordinates and
                     store as additional tplot variables.
                        Phi = atan(y,x)*!radeg  ; [  0, 360]
                        The = asin(z)*!radeg    ; [-90, +90]

           PH_180:   If set, the range for Phi is -180 to +180 degrees.

           REVERSE:  Reverse the sense to be the anti-Sun direction.  If you sit
                     on the spacecraft and look in this direction, sunlight will
                     hit the back of your head.  Be sure to use skin protection.

           PANS:     Named variable to hold the tplot variables created.  For the
                     default frame, this would be 'Sun_MAVEN_SPACECRAFT'.

           FORCE:    Ignore the SPICE check and forge ahead anyway.

           SUCCESS:  Returns 1 on normal completion, 0 otherwise.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-04-11 20:26:40 -0700 (Tue, 11 Apr 2023) $
     $LastChangedRevision: 31731 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_sundir.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_sundir.pro)

## MVN_TOPOGRAPHY

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

    PROCEDURE:   mvn_topography
    PURPOSE:
      Calculates topographic profiles along the orbit track based on laser
      altimeter measurements by MGS-MOLA.  Topography is relative to the
      areoid (same as published maps).

      The result is stored in a TPLOT variable.

    USAGE:
      mvn_topography

    INPUTS:
           None:     Gets all necessary inputs from tplot.

    KEYWORDS:
           PANS:     Named variable to hold the tplot variable created.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2017-05-31 11:09:39 -0700 (Wed, 31 May 2017) $
     $LastChangedRevision: 23376 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/maven/general/mvn_topography.pro $

    CREATED BY:    David L. Mitchell

(See projects/maven/general/mvn_topography.pro)

## MVN_USR_DIR

[Previous Routine] [List of Routines]

     FUNCTION mvn_usr_dir()
    NAME:
     mvn_usr_dir
    PURPOSE:
     returns a user directory that can be used to store user specific files. Use sparingly!
    Typical Usage:
      file = mvn_usr_dir() + '/mvn_user_pass.sav'
    Keywords:
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See projects/maven/general/mvn_usr_dir.pro)